Hook pipeline (Track G — 27 lifecycle events)

v0.7.0 ships a programmable extension surface that fires on every substrate lifecycle point. Hooks return one of Allow, Modify(delta), Deny{reason, code}, or AskUser{prompt, options, default}. Default off — a v0.7.0 install with no hooks.toml behaves identically to v0.6.4 at the lifecycle layer.

• Code paths: src/hooks/mod.rs, src/hooks/chain.rs, src/hooks/config.rs, src/hooks/decision.rs, src/hooks/events.rs, src/hooks/executor.rs, src/hooks/recall.rs, src/hooks/timeouts.rs, pre-store hook subtree under src/hooks/pre_store/, post-reflect hook subtree under src/hooks/post_reflect/.
• Helper binary: tools/auto-link-detector/ is the R3 reference pre_link hook (~775 LoC).
• Capability registry entry: CapabilityHooks in src/config.rs:944.
• Config file: ~/.config/ai-memory/hooks.toml — hot-reloadable via SIGHUP (src/hooks/config.rs:424).

Configuration

[[hook]]
event = "post_store"
command = "/usr/local/bin/auto-link-detector"
priority = 100
timeout_ms = 5000
mode = "daemon"          # daemon | exec (optional; default per event class)
enabled = true
namespace = "team/*"     # glob match (today: non-empty string accepted)
fail_mode = "open"       # open (default) | closed

Fields (src/hooks/config.rs:174-190):

• event — one of the 27 events below.
• command — absolute path to the helper binary.
• priority — higher fires first; first Deny short-circuits the chain.
• timeout_ms — wall-clock budget per call; capped at MAX_TIMEOUT_MS = 30_000 (src/hooks/config.rs:138). Exceeded → executor returns Timeout; chain converts per fail_mode.
• mode — daemon (long-lived subprocess, stdin JSON-RPC) or exec (one-shot fork+exec). Optional in TOML; missing values resolve via default_mode_for_event (src/hooks/config.rs:157) — daemon for hot-path events (post_recall, post_search, pre_recall_expand), exec otherwise.
• enabled — soft-disable without removing the row.
• namespace — glob pattern; chain is filtered before invocation. Validation is shape-only today (validate_hook at src/hooks/config.rs:297); the runtime matcher is a substrate-side prefix check.
• fail_mode — open (default; executor errors → chain logs warning, treats hook as Allow) or closed (executor errors → chain Deny and short-circuit). Use closed only for compliance-critical hooks (PII redaction, regulated-tenant access control) where silent fail-open is worse than a hard refusal. Defined at src/hooks/config.rs:111-122.

27-event matrix

The 20 baseline events:

The 5 grand-slam additions:

The 2 v0.8.0 Pillar-1 additions:

The discriminator strings (snake_case of the variant names via #[serde(rename_all = "snake_case")]) and the HookEvent enum live at src/hooks/events.rs:91; the canonical wire shapes for every event’s payload (MemoryDelta, RecallQuery, SearchResult, ReflectDelta, CompactionDelta, …) start right after the enum (≈src/hooks/events.rs:235) and span the rest of the module.

Decision-class semantics

Every hook returns a HookDecision (src/hooks/decision.rs:87):

• Allow — chain proceeds to the next hook (or to the substrate if this was the last one).
• Modify(delta) — chain proceeds, but the in-flight payload is rewritten using the hook’s delta. Only legal on pre_* events whose payload type implements the modify protocol (e.g. pre_store carries MemoryDelta, pre_link carries LinkDelta).
• Deny{reason, code} — chain short-circuits; the substrate refuses the operation and surfaces code (an i32 status-style code, serde-defaulted when the hook omits it) to the caller along with the reason string.
• AskUser{prompt, options, default} — chain pauses pending an operator decision. Today the only consumer is the K10 SSE approval loop (docs/k10-sse-approvals.md). The default is applied if the K10 sweeper expires the row before an operator answers.

is_pre_event (src/hooks/decision.rs:344) is the canonical predicate for “may this event return Modify” — the chain runner rejects Modify decisions on post_* events.

Per-class deadline budgets

The chain runner reads event_class(event) (src/hooks/timeouts.rs:137) at fire entry and computes a wall-clock ceiling on the entire chain. Per-hook budgets are derived by per_hook_budget_ms (src/hooks/timeouts.rs:264) and shrink monotonically as earlier hooks consume time:

The HotPath ceiling is the v0.6.3 recall p95 budget — a hook that can’t return a decision in 50ms cannot be wired on the read path without blowing SLO. The class deadline is the whole-chain ceiling; individual hook timeout_ms values may be smaller. A hook’s effective per-call budget is min(timeout_ms, remaining_chain_ms).

When per_hook_budget_ms returns None, the chain has already exhausted its class deadline before this hook even fired. The runner increments the process-wide timeout_violations_total counter (src/hooks/timeouts.rs:306-313) and handles the missed hook per its fail_mode (open → treated as Allow; closed → chain Deny). The doctor surface reads this counter for the “did we trip a budget since boot” panel.

Hot-path constraint

post_recall and post_search default to mode = "daemon" (src/hooks/config.rs:157). The v0.6.3 recall p95 budget is 50 ms; the daemon subprocess keeps the hook chain off the synchronous fork/exec path. mode = "exec" is permitted for these events but requires the explicit setting — the default is intentionally biased toward latency-preserving behavior.

pre_recall_expand defaults to daemon for the same reason but is classed as HotPath rather than Read (50 ms whole-chain ceiling vs 2 s), so a misconfigured exec-mode expansion hook still cannot park the recall path for a full second.

Hot-reload (SIGHUP)

spawn_reload_task (src/hooks/config.rs:424) listens for SIGHUP on Linux/macOS and atomically swaps the chain’s config snapshot (a shared Arc<HookConfigSnapshot>, i.e. RwLock<Vec<HookConfig>>). Read-side dispatch resolves the snapshot once per fire, so a reload mid-fire never tears: any in-flight chain finishes against the old config; new chains see the new config. On non-Unix targets the function is a no-op (src/hooks/config.rs:473).

Race window discussion. Between the operator’s kill -HUP <pid> and the chain snapshot swap there is a sub-millisecond window where a new chain fire may have already loaded the pre-swap snapshot. This is intentional — the alternative (locking writers out of the chain during reload) would convert hot-reload into a brief outage on a busy daemon. The operator-visible consequence: a single in-flight chain may run against the pre-reload config even after SIGHUP is delivered. Verification of the swap is via the tracing::info! emitted by the reload task (“hooks: reloaded config on SIGHUP”) — if the operator wants strict observability they grep for the line before treating the reload as effective.

On parse failure (TOML error, validation error, missing file) the reload task logs an error and keeps the previous config (src/hooks/config.rs:456). The daemon never reloads to an empty config because of operator typo — silent hook removal would be a security regression.

Security hardening

• Stderr redaction — the executor unconditionally scrubs the captured stderr tail through a keyword/shape-based pass (redact_stderr_tail, src/hooks/executor.rs:303) before forwarding to the daemon log — conservative, favouring over-redaction over leaking. Pinned by tests/g3_hooks_stderr_drain.rs.
• Timeout enforcement — hooks past their timeout_ms surface ExecutorError::Timeout; the child process is reaped via tokio’s kill_on_drop(true) (hard kill — no graceful-shutdown window). Pinned by tests/hooks_timeout_budget.rs.
• Substrate authority — hook decisions are advisory unless the substrate explicitly elevates them (e.g., the 7th-form storage::insert pre-write hook gates on the rule corpus, not on arbitrary user hooks). User-supplied hooks cannot bypass governance.

Tests

Pinned by tests/hooks_executor_test.rs, tests/hooks_hot_reload.rs, tests/hooks_pre_recall.rs, tests/hooks_timeout_budget.rs, tests/g3_hooks_stderr_drain.rs, tests/g11_auto_link_detector.rs.

Operator workflow

1. Author the helper binary. Use the auto-link-detector as the reference (tools/auto-link-detector/src/main.rs). Speak JSON-RPC over stdin/stdout for mode = "daemon"; one-shot exec for mode = "exec".
2. Drop the binary on PATH and chmod +x.
3. Edit ~/.config/ai-memory/hooks.toml with the row schema above.
4. Reload with kill -HUP $(pgrep -f 'ai-memory mcp') or restart the daemon. The reload task logs hooks: reloaded config on SIGHUP on success.
5. Verify the reload landed via the hooks: reloaded config on SIGHUP log line (it carries the loaded hook count). The capabilities hooks block (memory_capabilities over MCP, e.g. printf '<JSON-RPC tools/call>' | ai-memory mcp --profile full) reports hook_events_count (27) and registered_count — it does not enumerate per-event hook rows.

Tuning guidance

Recommended priority bands:

• priority = 1000+ — security / compliance hooks. Run first so they can Deny before a Modify hook rewrites the payload past their checks.
• priority = 100-999 — semantic-extraction hooks (auto-tagging, auto-link, embeddings). Run after compliance, before observability.
• priority = 1-99 — observability / metrics hooks. Run last; they see the final payload that the substrate is about to commit.

Recommended timeout_ms per event class:

For deployment sizes:

• Small (1-5 agents) — single daemon-mode auto-link-detector hook is plenty. Default fail_mode = "open" keeps the substrate resilient to hook bugs.
• Medium (10-50 agents) — multiple hooks per event acceptable; watch timeout_violations_total weekly. If non-zero, either tighten individual timeout_ms or move long-running work to a post-write queue.
• Large (100+ agents, regulated tenant) — compliance hooks at fail_mode = "closed" so a buggy hook produces a hard refusal rather than silent fail-open. Pair with an on-call alert on timeout_violations_total delta > 0.

Troubleshooting

Operator runbook (3am procedures)

A hook is denying every write — substrate appears stuck.

1. Set RUST_LOG=ai_memory::hooks=debug (pkill -USR2 ai-memory if you have the dynamic-log signal wired; otherwise restart).
2. Inspect the refused callers’ error responses — a hook Deny short-circuits the chain and surfaces {reason, code} directly to the caller (ChainResult::Deny); fail-mode conversions additionally log hooks: chain hook errored; fail_mode=closed, denying lines naming the hook command and event.
3. To unblock: edit ~/.config/ai-memory/hooks.toml, set enabled = false on the offending row, kill -HUP. Confirm via the hooks: reloaded config on SIGHUP log line.
4. RCA after the bleeding stops — replay the captured payload against the helper binary on the command line (daemon-mode helpers speak framed JSON-RPC on stdin/stdout, so a single-request replay is a printf | helper one-liner).

Reload appears to have hung.

SIGHUP reload is async and idempotent. If you don’t see the hooks: reloaded config on SIGHUP log line within ~1s, the most likely cause is a TOML parse error — look for the warning line. Re-issue kill -HUP after fixing the file. If the daemon process itself is unresponsive, fall through to standard restart procedure (scripts/dogfood-rebuild.sh documents the live-binary swap dance).

Hot-path latency regressed; suspect a hook.

1. Review ~/.config/ai-memory/hooks.toml (and the loaded-count on the last hooks: reloaded config on SIGHUP line) — confirm which events have hooks attached.
2. Temporarily disable hot-path hooks (enabled = false on post_recall / post_search / pre_recall_expand rows), SIGHUP.
3. Re-measure recall p95. If recovered, the hook was the cause.
4. Look at per-hook ExecutorMetrics for the trip — usually the helper binary blocked on an upstream (Ollama, network). Move the work async or relax the SLO.

Migration

A v0.6.4 → v0.7.0 install with no hooks.toml is a no-op at the lifecycle layer (an empty chain returns Allow without spawning anything). To opt in, follow the operator workflow above. To verify hooks are NOT firing on a write path, set RUST_LOG=ai_memory::hooks=debug and confirm the absence of per-hook chain log lines on writes.

See also: docs/MIGRATION_v0.7.md §”Hook pipeline (opt-in)”, the canonical inventory in docs/internal/v070-feature-inventory.md §”Feature: Hook pipeline (Track G, 25 events)”, the SSE approval pipeline that consumes AskUser decisions at docs/k10-sse-approvals.md, the transcript-store hook reference at docs/sidechain-transcripts.md, the K8 quotas substrate that gates write events after hook decisions at docs/k8-quotas.md, the federation hardening that applies the same hook chain to inbound peer writes at docs/federation.md, and the signed-events chain that records every governance-gated write at docs/signed-events-v4.md.