Follow-up to #96. The per-call onToolCall gate landed in #377. This tracks the third split described in #96: documentation and a runnable example.

Scope

• Document the onToolCall gate: where it sits (after schema validation, before execute, one layer below the name-based allow/deny/preset), the ToolCallContext and ToolCallDecision shapes, that deny returns a structured error ToolResult rather than throwing, and that it is orthogonal to the task-level onApproval.
• Document the observability surface: gated / gateAction / gateReason on the tool_call trace event, and that gateReason is redacted like other sensitive text.
• Add a runnable example under examples/ showing the motivating use case end to end: gating bash per call and routing ambiguous commands through a human-in-the-loop approval before allow or deny.
• Likely home: docs/tool-configuration.md, cross-linked from the tool layer notes in AGENTS.md.

Reference

The motivating integration is temodar-agent, which hand-rolled this by wrapping every tool's execute. See #96 for the full background.