Hooks
Tool event handlers that fire on SessionStart, PreToolUse, and Stop, loading message contexts enforcing git isolation and plan discipline.
Hooks fire on tool events and load message contexts that the
assistant treats as additional system prompts. Wiring lives in
the Claude Code settings.json hook block, the Codex hooks.json hook file,
and the Qwen Code settings.json hooks map.
| Event | Timeout | Purpose |
|---|---|---|
| SessionStart | 30 seconds | Read memory, check plan state, report readiness |
| PreCompact | 30 seconds | Verify state externalized before compaction |
| PostCompact | 30 seconds | Restore working state after compaction |
| Stop | 60 seconds | Session-end externalization |
| PreToolUse (Bash) | 10 seconds | Bash validation — git artifact isolation |
| PreToolUse (Write/Edit/NotebookEdit/apply_patch) | 10 seconds | Plan-reference isolation, frontmatter checks |
Dispatcher
Installed hook entries invoke the dispatcher by absolute script path. The
settings templates carry the ${HARNESS_ROOT} token —
python "${HARNESS_ROOT}/apothem/hooks/dispatch.py" <event> [<message-name>]
— which the installer renders to the harness root's real path at install
time (Claude Code and Qwen Code materialize the dispatcher under
<harness-root>/apothem/hooks/; Codex under <harness-root>/hooks/). The
dispatcher is a standalone stdlib script: it bootstraps its own sys.path,
so no importable apothem package is needed on the host. From a source
checkout, the module form python -m apothem.hooks.dispatch <event> (with
PYTHONPATH=src) runs the same code for development. The dispatcher loads
hooks/lib/resolve_root.py for ecosystem-root resolution and delegates to
hooks/emit_hook_context.py and hooks/session_start_bootstrap.py.
Message contexts
Per-event Markdown contexts live under src/apothem/hooks/messages/:
postcompact.md,precompact.md,stop.mdpretooluse-bash.md,pretooluse-write.md,pretooluse-edit.md,pretooluse-notebookedit.md
Each context file is loaded by the dispatcher when its event fires and its context argument is registered in the settings file.
Generated Hook Message Inventory
| Name | Description | Source |
|---|---|---|
postcompact | Post-compaction Blind Bootstrap (CM-24 §6.2). Restore working state from durable files; conversation context is now compressed. | src/apothem/hooks/messages/postcompact.md |
posttooluse-proactive-compaction | Proactive-compaction tracker for PostToolUse tool calls. | src/apothem/hooks/messages/posttooluse-proactive-compaction.md |
precompact | Pre-compaction protocol (CM-24 §2.3). Externalize all in-conversation state BEFORE the harness compresses context. | src/apothem/hooks/messages/precompact.md |
pretooluse-askuserquestion-recommended | Call-time (Recommended)-marker guard for AskUserQuestion tool calls. | src/apothem/hooks/messages/pretooluse-askuserquestion-recommended.md |
pretooluse-bash-plan-guard | Plans-Discipline write guard for Bash tool calls (companion to pretooluse-write-plan-guard.md). | src/apothem/hooks/messages/pretooluse-bash-plan-guard.md |
pretooluse-bash | CM-7 git-artifact isolation + M12 numeric-prefix discipline + M15 human-only authorship. | src/apothem/hooks/messages/pretooluse-bash.md |
pretooluse-conformity | > Advisory: this hook reports; it does not block. Mechanical enforcement runs in CI. | src/apothem/hooks/messages/pretooluse-conformity.md |
pretooluse-dependency-guard | Dependency-manifest supply-chain guard (advisory). | src/apothem/hooks/messages/pretooluse-dependency-guard.md |
pretooluse-edit-header-guard | SPDX-header inject guard for Edit tool calls. | src/apothem/hooks/messages/pretooluse-edit-header-guard.md |
pretooluse-edit | Codebase isolation (Edit scope). | src/apothem/hooks/messages/pretooluse-edit.md |
pretooluse-eval-guard | Dynamic-eval / unsafe-deserialization guard — advisory prompt-injection defense. | src/apothem/hooks/messages/pretooluse-eval-guard.md |
pretooluse-notebookedit | Codebase isolation (notebook scope). | src/apothem/hooks/messages/pretooluse-notebookedit.md |
pretooluse-write-header-guard | SPDX-header inject guard for Write tool calls. | src/apothem/hooks/messages/pretooluse-write-header-guard.md |
pretooluse-write-plan-guard | Plans-Discipline write guard for Write / Edit / NotebookEdit tool calls. | src/apothem/hooks/messages/pretooluse-write-plan-guard.md |
pretooluse-write | Codebase isolation + frontmatter compliance. | src/apothem/hooks/messages/pretooluse-write.md |
sessionstart | Session-start conformity posture. | src/apothem/hooks/messages/sessionstart.md |
stop | Session-end protocol (CM-14 + CM-24 §2.5 + CM-26 + CM-22 §2/§4). | src/apothem/hooks/messages/stop.md |