Missing Hook Capabilities — Agent Stack Gaps

Beyond the 13 missing events, the agent stack lacks several hook capabilities that Claude Code supports.

1. Handler Types (core support implemented; platform executors pending)

Claude Code supports 5 hook handler types. hooks-adapter core now models and dispatches all 5 handler types. command remains the legacy default when type is omitted.

Implemented

**hooks-adapter/core:**

• src/normalizer/runner.ts — Dispatches by handler type and preserves command fail-open/fail-closed semantics
• src/types/plan.ts — HandlerRef is a backward-compatible typed union; omitted type behaves as command
• src/handlers/http.ts — HTTP POST handler with allowed-env header interpolation, URL validation, timeout, and JSON result parsing
• src/handlers/mcp-tool.ts — MCP tool handler through an injected executor seam
• src/handlers/prompt.ts — Prompt handler through an injected, timeout/depth-bounded executor seam
• src/handlers/agent.ts — Agent handler through an injected, timeout/depth/max-turn bounded executor seam

Remaining integration work

**agent-platform:**

• src/harness/adapters/adapterBridge.ts already forwards opaque hook config to adapters. Live mcp_tool, prompt, and agent execution still needs platform wiring that supplies hooks-adapter executor seams from the unified tool registry/model/agent invocation surfaces.

2. Decision Types (3 missing)

Changes needed

**hooks-adapter/core:**

• src/types/result.ts — defer, block, retry are in the decision union
• src/merge-engine/merge.ts and src/sdk-interface/parser.ts — Handle precedence and validation for the decision types

**hooks-adapter/adapter-claude:**

• src/renderer.ts — Renders block as PreToolUse deny; defer and unsupported retry omit native decisions explicitly

**agent-platform:**

• src/harness/internal/createRun/orchestration/effects.ts — Handles hook decision metadata for block/retry/session abort
• src/governance/ — Existing permission events audit hook block/retry bridge decisions

3. Matcher Patterns (regex, negation, OR missing)

Changes needed

**hooks-adapter/core:**

• src/normalizer/plan-resolver.ts — Extend evaluateWhen() with regex, OR, negation
• src/types/plan.ts — Add if field to HookPlanEntry

4. Async Execution (fully missing)

Changes needed

**hooks-adapter/core:**

• src/normalizer/runner.ts — Add async spawn mode (don't await)
• src/normalizer/runner.ts — Add rewake: monitor exit code, inject stderr as system reminder
• New: src/state/hook-execution-tracker.ts — Track once per session

**agent-platform:**

• Background hook results need to feed back into orchestration context

5. Environment Variables (2 missing)

Changes needed

**hooks-adapter/core:**

• src/propagation/materialize.ts — Add missing env vars to injection
• New: env file mechanism for SessionStart/Setup/CwdChanged/FileChanged hooks

**agent-platform:**

• Propagate CLAUDE_EFFORT from session options

6. Hook Output Processing (partial)

Changes needed

**hooks-adapter/core:**

• src/types/result.ts — Continue to keep supported output fields as typed top-level fields
• src/sdk-interface/parser.ts and src/merge-engine/merge.ts — Normalize updatedInput to canonical toolMutation

**agent-platform:**

• src/harness/internal/createRun/orchestration/ — Handles hook metadata continueSession:false as session abort
• src/session/ — No new API required for current Claude sessionTitle; it is emitted through SessionStart hook-specific output
• src/harness/ — updatedInput remains canonicalized to toolMutation; live tool input mutation requires a provable pending tool invocation boundary

**agent-runtime:**

• src/daemon/ — Dynamic file watcher registration for watchPaths remains deferred until watcher handles support safe runtime registration

7. Hook Configuration (partial)

Changes needed

**hooks-adapter/core:**

• src/config.ts — Add disableAllHooks support
• src/normalizer/runner.ts — Per-hook timeout, shell selection
• New HTTP handler: header interpolation with allowedEnvVars