feat(hooks): permission_denied event — fires per blocked tool call

[emal-avala]

Summary

Adds HookEvent::PermissionDenied, a lifecycle event that fires for each tool call blocked either by a configured permission rule or by the interactive user prompt. Closes a visible compliance gap: until now the DenialTracker recorded denials silently and audit pipelines had to grep session JSON.

Context per fire

{
  "session_id":    "…",
  "turn":          3,
  "tool":          "Bash",
  "tool_use_id":   "call_abc",
  "reason":        "Denied by rule for Bash",
  "input_summary": "rm -rf /",
  "timestamp":     "2026-04-23T23:45:01Z"
}

Firing semantics

• Batched once per turn, right after Stop, so hooks see the full post-turn state.
• One event per new denial — hooks can filter on tool for per-tool policies (block-dangerous-bash-to-pager, etc.). Aggregation is left to downstream log processing.
• tool_name hook scoping works: [[hooks]] event = "permission_denied" tool_name = "Bash" only fires on Bash denials. The dispatcher receives the tool name per call.
• Eviction-aware: the existing 100-record DenialTracker ring buffer can evict old records; the engine's high-water mark tracks total() (which never decrements), so batch size stays correct even when records_since clamps to the retained tail.

Example hook

[[hooks]]
event  = "permission_denied"
action = { type = "http", url = "https://audit.example.com/ingest", method = "POST" }

[[hooks]]
event     = "permission_denied"
tool_name = "Bash"
action    = { type = "shell", command = "./on-bash-denial.sh" }

Implementation

• DenialTracker::records_since(total_before) — pure snapshot of new records. Four unit tests covering: zero-case, eviction clamping, index-vs-queue-length semantics, empty-case safety.
• QueryEngine.last_seen_denial_total high-water mark (never regresses through eviction).
• QueryEngine::fire_permission_denied_hooks() helper; one call site at end-of-turn.
• Schema: new variant + serde roundtrip test.
• Dispatcher: registered hook fires (protects against cross-fire regressions).
• CLI: format_hook_event, parse_hook_event, and HOOK_EVENT_CATALOG all teach the new name. Invariant tests (hook_event_catalog_has_unique_names, parse_hook_event_covers_every_variant_in_catalog) still pass.

Tests

• 4 new DenialTracker::records_since unit tests
• 1 new schema serde roundtrip
• 1 new dispatcher fire test
• Existing CLI catalog invariants continue to pass

Full permissions + hooks + schema suites pass. Clippy clean under -D warnings.

Test plan

• cargo test -p agent-code-lib --lib permissions::tracking
• cargo test -p agent-code-lib --lib hooks::
• cargo test -p agent-code-lib --lib hook_event_serde
• cargo test -p agent-code --bin agent hook_event_catalog
• 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.