Hooks¶
Hooks fire on tool events and load message contexts that the
assistant treats as additional system prompts. Wiring lives in
settings.json (Windows / PowerShell host) and settings-unix.json
(POSIX / bash host).
| Event | Timeout | Purpose |
|---|---|---|
| SessionStart | 30s | Read memory, check plan state, report readiness |
| PreCompact | 30s | Verify state externalized before compaction |
| PostCompact | 30s | Restore working state after compaction |
| Stop | 60s | Session-end externalization |
| PreToolUse (Bash) | 10s | Bash validation — git artifact isolation |
| PreToolUse (Write/Edit/NotebookEdit) | 10s | Plan-reference isolation, frontmatter checks |
Dispatcher¶
The dispatcher entry points are:
src/apothem/hooks/lib/bootstrap.sh(POSIX / bash)src/apothem/hooks/lib/bootstrap.ps1(Windows / PowerShell)
Both stubs source src/apothem/hooks/lib/find-python.{sh,ps1}, locate a real
CPython 3.10+ interpreter, and exec src/apothem/hooks/dispatch.py
--event-name <event> [--context-file <path>]. The dispatcher
imports src/apothem/hooks/lib/resolve_root.py for ecosystem-root resolution
and delegates to src/apothem/hooks/emit_hook_context.py and
src/apothem/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-file argument is registered in the settings
file.
Paired-template review cadence¶
settings.json and settings-unix.json form an OS-paired template.
Every key in either file is either identical (cross-OS-portable) or
intentional drift (host-shell families).