feat: daemon-native hook bus — uniform tool/turn/lifecycle hooks for every backend

[saucam]

What

pi's extension hooks (tool_call block/mutate, lifecycle) are the best idea in the pi harness — and they only work for pi sessions, because they run inside the pi process. This PR adds codeoid's own hook layer at the daemon, dispatched on the provider-neutral events Session already sees, so one config-declared rule set applies uniformly whether a session runs on claude, pi, gemini, or openai.

Rules like "block writes to .env", "rewrite dangerous Bash before the approval prompt", "redact secrets from recorded output", "git-checkpoint per turn", "audit to a webhook" — written once, applied to every backend.

Full docs: docs/hooks.md.

Design

• HookBus (src/daemon/hooks/bus.ts) — built once at daemon startup (like ProviderRegistry / CompressionRegistry), threaded to every session via SessionCreateOptions. Sessions without matching hooks pay zero latency (hasHooks gate on every hot path).
• v1 hook kinds — command (shell via /bin/sh -c, event JSON on stdin, mirrors Claude Code's hook contract: exit 2 or {"decision":"block"} blocks; stdout JSON can mutate) and webhook (POST, same outcome shape). Deliberately no in-process JS plugin loader — much bigger security surface, left to a future kind.
• Events → Session seams (all existing seams, no new event plumbing):
  • tool_call — inside #makeCanUseToolFn, before the approval gate. A hook block is a policy deny: never prompts, never burns the autonomous budget, wins even for auto-approved safe tools. Mutations feed the same updatedInput path the approval sanitizer uses, and the displayed tool message is updated so the user approves what will actually run.
  • tool_result — patches the recorded output (canonical history → what a switched-to backend sees, scrollback, transcript). The native backend already consumed the original inside its own loop; docs state this honestly (redaction use case).
  • before_turn — contributes a systemPromptAppend, composed after the stable base so the cached prompt prefix is untouched when no hook fires.
  • after_turn, session_start/session_end/provider_switched/rotated — observe-only, fire-and-forget.
• Security — hook commands run in the daemon's trust context, so they get the hardened subprocess env from fix: allowlist the pi subprocess environment (GHSA-38vh parity) #135 (buildSubprocessEnv, shared basics only; CODEOID_*/ZEROID_*/TELEGRAM_* never leak; CODEOID_AGENT_ENV_ALLOW escape hatch applies). Payload on stdin, never env. Output capped at 1 MiB. Infra failures fail open (a crashed hook script can't brick every session); blocking is always an explicit hook decision.
• Config — hooks.entries[] with event, tool-name matcher regex (validated at load — a typo fails loudly), type, command/url, per-hook timeout. CODEOID_HOOKS_ENABLED=false kill switch.
• Wire-neutral — no protocol changes; blocks/mutations surface as standard info messages (hook.blocked / hook.updated_input metadata), so no client work is required. A read-only hooks.config snapshot verb (parallel to claude.config) is noted as a possible follow-up.
• Extracted #resolveToolCallMessage so the hook-block path and the manual deny path share one finalizer and can't drift.

Tests

• hook-bus.test.ts — command kind (block via JSON + via exit 2, mutation chaining, short-circuit, fail-open on crash/garbled JSON/timeout, matcher gating, invalid-matcher skip, env hardening with a root-key-shaped secret, stdin payload), webhook kind (block/mutate/non-2xx/unreachable via local Bun.serve), createHookBus gating.
• session-hooks.test.ts — end-to-end over MockSessionProvider: block before the approval gate with budget untouched, block wins on safe tools, mutation reaches the provider, before_turn append in TurnOpts, tool_result redaction in the completed message, lifecycle observe hooks, and a no-bus control asserting unchanged behavior.
• config.test.ts — schema defaults, entry parsing, kill switch, rejection of malformed entries (missing command/url, bad regex, unknown event, out-of-range timeout).

bun run test (1219 pass), typecheck, lint all green.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 99.56427% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 82.03%. Comparing base (8cf7388) to head (f249147).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/daemon/hooks/bus.ts	99.23%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #137      +/-   ##
==========================================
+ Coverage   81.57%   82.03%   +0.45%     
==========================================
  Files          95       97       +2     
  Lines       16406    16834     +428     
==========================================
+ Hits        13384    13810     +426     
- Misses       3022     3024       +2     

Flag	Coverage Δ
daemon	82.03% <99.56%> (+0.45%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/config.ts	91.48% <100.00%> (+0.77%)	⬆️
src/daemon/hooks/types.ts	100.00% <100.00%> (ø)
src/daemon/session-manager.ts	65.51% <100.00%> (+0.12%)	⬆️
src/daemon/session.ts	95.44% <100.00%> (+0.27%)	⬆️
src/daemon/hooks/bus.ts	99.23% <99.23%> (ø)

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[saucam]

/gemini-review

[github-actions]

🤖 Gemini code review

This PR introduces a uniform, daemon-native hook bus that enables config-declared hooks (shell commands and webhooks) to run across all backend providers. It features a hardened subprocess environment to prevent credential leakage and supports blocking and input mutation prior to the user approval gate. The implementation is robust, but there are potential improvements regarding cross-platform support and memory safety under massive webhook payloads.

Findings: 🔴 0 · 🟠 0 · 🟡 1 · 🟢 1

---

_{Tokens spent · ⬆️ Input: 25,197 · ⬇️ Output: 577 · Σ Total: 32,450
Total may be higher due to thinking token counts.}