feat(hooks): pre_tool_use veto — block tool calls from a hook

[emal-avala]

Summary

Promotes pre_tool_use from a notify-only signal to a gate. When a hook exits non-zero, the tool call is vetoed — the tool does not execute and the model receives a synthetic error ToolResult carrying the hook's stderr (or stdout, or a generic message) as the reason.

Problem

The pre_tool_use event fired, but its return value was ignored. Operators who wanted a policy guard (content scanning, destructive-command blocks, compliance checks) had to stretch the permission rule grammar to match arbitrary predicates — or wait for one. A hook that can both inspect the tool input and veto the call closes that gap cleanly.

Example

[[hooks]]
event     = "pre_tool_use"
tool_name = "Bash"
action    = { type = "shell", command = '''
  if echo "$TOOL_INPUT" | grep -q 'rm -rf /'; then
    echo "refusing destructive root delete" >&2
    exit 1
  fi
''' }

When this fires and exits 1, the Bash call is blocked and the model sees:

Blocked by pre-tool-use hook: refusing destructive root delete

Implementation

• HookResult gains a stderr field (default empty). Shell hooks populate it from subprocess stderr; HTTP hooks leave it empty. Existing call sites continue to work — the struct is Default + Clone and no external crate constructs HookResult directly.
• Veto wiring in query::run_turn_with_sink: per-call hook results are collected into a vetoed_ids set. Vetoed calls skip execute_tool_calls and produce a synthetic ToolResult::error.
• Denial surface integration: vetoed calls record on the existing DenialTracker, so the permission_denied hook, /permissions UI, and denial reports see the block uniformly with rule-based and user denials.
• Reason priority: stderr (trimmed) > stdout (trimmed) > generic "blocked by pre-tool-use hook". First line only so audit records stay scannable.

Backwards compatibility

• Hooks that exit 0 are unchanged — they fire, log whatever, and the tool proceeds.
• A hook that writes to stderr but exits 0 is NOT a veto — success is tied to exit status only. Lots of hooks log progress on stderr as a matter of style; they must not accidentally block.
• pre_tool_use was documented as "can block/modify" in the schema rustdoc — this PR makes the "can block" half real; the "modify" half is not claimed here.

Tests (3 new)

• Hook exiting non-zero sets success=false
• Stderr and stdout are captured into distinct fields with no cross-mix
• Exit-zero hook with stderr output still counts as success (not a veto)

All 13 hooks:: dispatcher tests pass. Clippy clean under -D warnings.

Test plan

• cargo test -p agent-code-lib --lib hooks::
• cargo clippy --workspace --tests --no-deps -- -D warnings
• cargo fmt --all --check

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.