docs(tool-gate): document the onToolCall gate + classifier, add example#383
Merged
Conversation
…example Third split of #96 (follow-up to #379). The onToolCall gate shipped in #377 and the classifyBashCommand classifier in #379; this documents both and adds a runnable example. - docs/tool-configuration.md: a "Per-call gating with onToolCall" section (where it sits, ToolCallContext/ToolCallDecision, deny returns an error ToolResult not a throw, agent overrides orchestrator default, orthogonal to onApproval, gated/gateAction/gateReason on the trace with gateReason redacted, not a security boundary) plus a shell risk classifier subsection. - examples/patterns/risk-gated-bash.ts: a security-audit agent that classifies each bash command and routes safe/review/high to allow/human-approval/deny. - AGENTS.md: cross-links in the tool-layer notes + /classifiers in the exports map. Closes #380
JackChen-me
force-pushed
the
feat/onToolCall-docs
branch
from
July 16, 2026 08:42
bd46149 to
9905eed
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Implements #380 (the third split of #96). Documents the per-call
onToolCallgate (shipped in #377) and the
classifyBashCommandclassifier (#379), and addsa runnable example.
What
docs/tool-configuration.mdgains a "Per-call gating withonToolCall"section: where the gate sits (after schema validation, before execute, one
layer below the name-based grant), the
ToolCallContext/ToolCallDecisionshapes, that
denyreturns a structured errorToolResultrather thanthrowing, agent-overrides-orchestrator precedence, that it is orthogonal to the
task-level
onApproval, thegated/gateAction/gateReasontrace fields(with
gateReasonredacted), and that it is not a security boundary. A "Shellrisk classifier" subsection documents
classifyBashCommand.examples/patterns/risk-gated-bash.ts: a security-audit agent grantedbashwhose
onToolCallgate classifies each command and routes safe to allow,review to human approval, high to deny.
AGENTS.md: cross-links from the tool-layer notes and the/classifierssubpath in the exports map.
Scope
Docs and example only. No code or behavior change.
Validation
npm run lintis green; the example typechecks against the/classifierssubpath and the doc's example link resolves.
Closes #380