# src/hooks KNOWLEDGE BASE
## OVERVIEW
Hook runtime executes user-configured shell commands at tool, assistant, and reasoning lifecycle phases. Owns bounded shell execution, JSON payloads, provider context injection, lifecycle records, diagnostics, and TUI activity bridge.
## WHERE TO LOOK
| Module boundary | `mod.rs` | Re-exports `HookRuntime`, `HookOutcome`, `HookAction`, `HookPhase`, records. |
| Execution | `runtime.rs` | Phase dispatch, command spawn, bounded pipes, timeout/cancel, failure policy application, context injection parsing. |
| Payload | `payload.rs` | JSON envelope (`magi-code.tool_hook` schema v1), affected paths, env refs, redaction modes, payload-ref overflow. |
| Records | `records.rs` | Lifecycle/context-injection records, diagnostics, outcomes/actions, phase/category/status enums. |
| Activity | `activity.rs` | TUI activity event emission for hook start/success/failure. |
| Tests | `tests.rs` | Phase dispatch, failure policies, context injection, payload redaction, affected paths, timeout. |
## CONVENTIONS
- Four phases: `before_tool`, `after_tool`, `after_assistant`, `after_reasoning`.
- Tool filters (`include_tools`/`exclude_tools`) apply only to before/after tool phases.
- Post-target phases (`is_after_event()`) report `target_ran=true` in diagnostics.
- Context injection runs on after phases only.
- Hook stdout context schema: `{"context_items":[{"role":"user","content":"..."}]}`.
- Context injection accepts only `user` role and byte-caps parsed content.
- Failure policies: `ignore`, `warn`, `block`, `fail`.
- `block` is before-tool only and prevents tool execution.
- Post-phase hooks cannot use `block`.
- Hook commands use `shell::runtime` preflight and bounded pipe readers, same safety path as bash tool.
- Hook cwd is canonicalized before execution.
- Path policies inherit from `ToolSettings`; per-tool absolute-path flags drive affected-path resolution.
- Payload modes: `full` complete request/result JSON; `redacted` masks credential keys and summarizes sensitive keys.
- Payload stdin cap is 1 MiB.
- Over-cap payload spills to payload-ref file under session dir, mode 0600, canonical containment checked.
- Payload ref omitted when spilled form still exceeds limits.
- `HookPayloadArtifacts::Drop` cleans payload-ref files.
- Payload cleanup warnings surface as diagnostics.
- Affected paths resolve cwd-relative or absolute based on tool path policy.
- Affected paths max: 16 paths, 1024 chars each.
- Write affected paths reject symlinks.
- Lifecycle records carry phase, tool name, status, policy, category, elapsed_ms, redacted message.
- Lifecycle records persist to session JSONL.
- Context injection records carry status, item_count, byte_count, max_bytes, injection_id.
- All diagnostics and records pass through `redact_sensitive_text`.
- Activity events emit only when `show_in_tui` setting is enabled.
- Cancellation checked before each hook and during command execution loop.
## ANTI-PATTERNS
- Do not bypass `preflight_bash_cwd_scope` for hook commands.
- Do not inject raw hook stdout into provider context without JSON parsing and role validation.
- Do not allow `block` failure policy on post-phase hooks.
- Do not skip payload redaction in `redacted` mode.
- Do not write payload-ref files outside canonical session root.
- Do not ignore `AgentCancellation` during hook command execution.
- Do not exceed stdin cap; spill to ref or omit.
- Do not leak credential-like keys, command text, or tool output in diagnostics or records.