[Docs] Clarify toolCallResult.exit_status semantics

[shivang-sec]

Page

docs/spec/instrument/hooks.md

What is wrong or missing

The exit_status field in steps/toolCallResult can be misread as the underlying process exit code, particularly when normalizing tool results from hosts such as OpenCode.

In ACS v0.1.0, exit_status is a four-value classification: success, failure, timeout, or blocked. It is not intended to represent a numeric process exit code. A tool that does not expose a numeric exit code can still populate the field based on whether the operation succeeded or failed.

The hooks documentation should explicitly state that exit_status is a classification rather than a process exit code, and provide normalization examples from OpenCode showing how host-specific result shapes map to the ACS classification. Where available, a numeric process exit code can remain additional detail in outputs.

Current Priority Scope

Feeds the AGT interoperability benchmark

[rocklambros]

Resolved on the substance, and the schema backs your reading.

exit_status stays required. tool-call-result.json has required: ["tool", "exit_status", "outputs"] and defines exit_status as {"type": "string", "enum": ["success", "failure", "timeout", "blocked"]}. It is a four-value classification and not a numeric process exit code, exactly as you describe.

The name is what misled readers, and more than one has hit it. That makes this a documentation fix rather than a schema change, which is where you already filed it, so no retitle is needed.

Remaining work as described in the issue: state in docs/spec/instrument/hooks.md that exit_status is a classification rather than a process exit code, and add the normalization examples showing how a host-specific result shape maps onto the four values. A numeric exit code stays available as additional detail in outputs.

One thing to keep separate. Discussion #128 argues that the four values describe the call and not its effect, so a side-effecting tool whose response is lost reports timeout and a retry looks identical to a first attempt. That is a different question about whether the vocabulary is sufficient, and it should not hold up the clarification here.