# Hook runtime guide
## Scope
Runs configured lifecycle hooks and separates provider context from local diagnostics.
## Where to look
| Runtime facade | `mod.rs` |
| Execution, policy, cancellation, injection | `runtime.rs` |
| Payloads, affected paths, stdout parsing | `payload.rs` |
| Phases and durable record shapes | `records.rs` |
| Optional activity bridge | `activity.rs` |
| Safety and phase coverage | `tests.rs` |
## Local rules
- Phases are `before_tool`, `after_tool`, `after_assistant`, and `after_reasoning`. Tool filtering is for tool phases; context injection is for after phases.
- Failure policies distinguish ignore, warn, block, and fail. Block applies only before a tool; preserve `target_ran` when reporting post-target failures.
- Parse injected stdout as `context_items` containing user-role content. Reject other roles and enforce byte limits; never inject arbitrary stdout.
- Execute through tool cwd preflight and shared platform-shell spawning, with bounded pipes and cleanup in the hook runtime.
- Keep payload-ref files under the canonical session root with protected permissions; oversized payloads may be omitted rather than escaping the limits.
- Affected paths have separate count/length limits and tool path checks. Preserve write-symlink rejection.
- Lifecycle/context-injection records are redacted before persistence. Optional activity and hook diagnostics are not provider conversation items.