[aaronormerod]

What changed

Match the toolCallRequest payload summary in hooks.md to tool-call-request.json.

Which issue does this implement

Closes #197

Base branch

• integration, because this touches docs/spec/

Type of change

• Documentation

Specification changes

• I opened a Discussion before this PR
• Schema changes validate against the JSON Schema spec
• I described the impact on downstream implementers below

No schema change, text only. The schema is unchanged.

Breaking for implementers? No.

I tested this

• I synced my branch with the base branch before opening this
• uv run pytest -v passes on my machine
• uv run mkdocs build --strict passes on my machine

Checklist

• Commits are signed off with git commit -s (required by the DCO)
• Prose follows STYLE.md
• No secrets, tokens, or internal URLs in the diff

Security

• This change has no security impact

[github-actions]

This pull request's description says it closes #197, which is on the project roadmap. When it merges, GitHub closes that issue and the roadmap counts it as delivered. Please confirm the change delivers the whole issue before merging.

[Lrd0036]

Checked against tool-call-request.json: the summary now matches the schema field for field and covers everything #197 lists, so closing it here is right.

Optional & non-blocking: Provenance required on every argument under ACS-Provenance, so "optional Provenance (required under ACS-Provenance)" would be a bit more precise. It's fine to leave it for a later pass.

The toolCallResult summary a few lines down has the same problem (execution_id isn't in the schema; the field is request_id_ref). I'll file that separately.

@bar-capsule FYI since this is under docs/spec/: it only brings the summary in line with the existing schema and changes no normative behavior. Merging.

Thanks @aaronormerod!

[rocklambros]

@aaronormerod, GitHub wouldn't let me assign you issue #196, issue #197, or issue #74, and I think that's because you haven't commented on them yet. Can you leave a comment on each one saying you're on it? Then I can assign you.

[rocklambros]

Aaron, the new sentence matches tool-call-request.json field for field. tool.name is required with version and provider optional, arguments is a map of {value, provenance} objects, and capability, operation, raw_command, and intent (description, goal) sit at the top level. That is every item issue #197 lists, so Closes #197 is right.

The merged tree on top of integration d9e3d5d is clean. Pytest 922 passed and 1 skipped, mkdocs build --strict ok, and the agt suite ran 1287 tests with 0 failures on Bun 1.3.11 and 1.3.14, the same counts as integration alone. The old tool (id, capability) wording appears nowhere else under docs/ or specification/.

Lance's note on Provenance can wait. The base schema marks it optional, and the strict tool-call-request.acs-provenance.json variant is where it becomes required, so "optional Provenance" is right for this summary.

Approving. Merge waits on the assignment step from my comment above: once you comment on issue #197, I can assign it to you and merge.

[drk-ram]

Reviewed at head f033a6365fc9d4d7272a73b0a645fec0774386a8. Approving. This is a one-line change in docs/spec/instrument/hooks.md and it is correct.

Before: tool (id, capability), arguments (each value carrying optional Provenance), agent reasoning.

After: tool (name required; version, provider), arguments (a map of objects, each with a required value and optional Provenance), and optionally capability, operation, raw_command, and intent (description, goal).

I compared the new sentence field by field with specification/v0.1.0/hooks/tool-call-request.json at this head:

• required is ["tool", "arguments"], and tool.required is ["name"]. The sentence matches both.
• tool.version and tool.provider exist, and tool.id does not. The old text named a field the schema never had.
• arguments is additionalProperties: { type: object, required: ["value"], properties: { value, provenance } }. "A map of objects with a required value and optional Provenance" is accurate, and the old text implied bare values.
• operation, capability, raw_command and intent are all optional top-level properties, and intent carries description and goal. The new text names every one.
• "Agent reasoning" has no counterpart in this payload schema. The closest field is the optional intent, which the new text now covers.

Using "optional Provenance" on each argument is also right. The base schema leaves it optional, and tool-call-request.acs-provenance.json makes it required under provenance_producer: deterministic. The sentence's pointer to the Provenance section is still the right place to say that.

No schema change, no normative change, nothing for implementers to do. I also searched docs/ for the old "(id, capability)" phrasing and found no other stale copy of it. A merge simulation against #271 (92c3128105e3) shows no conflicts.

Non-blocking, for a follow-up: the neighbouring summary for toolCallResult has drifted the same way. It reads "execution_id (correlated to the request), outputs, exit status, duration", but hooks/tool-call-result.json has no execution_id. Its properties are tool (required), operation, request_id_ref, exit_status (required), outputs (required) and duration_ms. The agentResponse summary ("agent reasoning") is fine, because that schema does define reasoning. Since a summary drifted without anything catching it, a guard in the style of tests/test_acs_examples.py from #271 that compares each hook's prose payload list with its schema would be worth having.