| Phase | 6 — Extensibility |
| Status | Not started |
| Depends on | 04 |
| Size | M |
| Drop-in critical | ★ (hook config schema + dispatch) |
Port codex-hooks: the lifecycle-hook engine that runs user/plugin commands at
defined agent events, with matchers, outcomes, and state persistence.
reference-codex/codex-rs/hooks/src/(event types, matchers, handlers, state).reference-codex/codex-rs/config/src/hook_config.rs(HookEventsToml,MatcherGroup,HooksFile).
- The 10 event types:
PreToolUse,PermissionRequest,PostToolUse,PreCompact,PostCompact,SessionStart,UserPromptSubmit,SubagentStart,SubagentStop,Stop. - Config schema (TOML
[hooks]/hooks.jsonfrom plugins): per-event arrays of{command, args, env, matcher{toolName, source, …}}; env interpolation ($tool.name, etc.). - Dispatch: evaluate matchers, run hook commands (subprocess) with the right
environment/payload, collect outcomes, merge outcomes (e.g. suppress/modify),
persist hook state hashes (
state.hooks.<event>.<hook_id>). - Sourcing from config + plugins (spec 22), with
external-agent-migrationcompatibility for imported hook configs.
- Hook config parsing (TOML + plugin JSON) matches Codex (golden).
- For a scripted session, the same hooks fire in the same order with the same payload/env as Codex (differential), and outcomes merge identically.
- Hook state persistence keys/values match.
- Matcher semantics and outcome-merge precedence are subtle; mirror exactly.
- Subprocess env/payload contract must match (hooks are user-authored against it).
- The events themselves are emitted by core (specs 27–30); this owns the engine.