Module hook_runtime 

Hook runtime — spool hook <subcommand> entry points.

Why hooks?

spool is normally invoked via MCP tools, which require the user to explicitly call them. Hooks let the AI client (Claude Code first, later Codex/Cursor) trigger spool automatically at well-defined lifecycle events: session start, user prompt, post-tool-use, stop, pre-compact. This is what turns spool from a “passive MCP server” into a “proactive memory runtime”.

Hook contract

Every hook MUST:

1. Be silent on failure (D7). Any error short-circuits to run_silent which logs the error to stderr and exits with status 0. We never propagate errors back to Claude Code because a flaky hook must not block the user’s prompt.
2. Return in <500ms p95. Network calls are forbidden inside a hook body; only local file I/O and ledger reads are allowed.
3. Be idempotent. A hook may be invoked twice for the same event (e.g. Claude Code retries on transient errors). Writes must tolerate repeats.
4. Stay independent. Hooks talk to disk; they never assume any other spool process is running.

Module layout

• session_start — emit wakeup packet to stdout (R2 core delivery)
• user_prompt — detect cwd/task switch, optional lightweight recall
• post_tool_use — append a signal envelope to the distill queue
• stop — placeholder until R3 transcript heuristics
• pre_compact — placeholder until R3 self-tag preservation

Each submodule exposes a single run(args) -> anyhow::Result<()> function that the CLI dispatches to via run_silent.

Modules

post_tool_use

spool hook post-tool-use — append a signal envelope to the distill queue.

pre_compact

spool hook pre-compact — persist self-tagged memories before context compaction so they survive the window trim.

session_start

spool hook session-start — emit a wakeup packet at session start.

stop

spool hook stop — drain pending signals + scan transcript for self-tags and incidents + persist via the shared distill pipeline, then attempt silent knowledge distillation.

user_prompt

spool hook user-prompt — invoked when the user submits a prompt.

Functions

project_runtime_dir

Resolve the per-cwd .spool/ directory used to buffer hook signals (distill queue, last-prompt timestamp, …).

run_silent

Execute a hook body and swallow any error so Claude Code never sees a non-zero exit (D7).

trellis_present

Detect a sibling Trellis installation by probing for <cwd>/.trellis/.developer (Trellis’ identity marker).