all-hands-cli 0.1.0

package/docs/harness/cli/trace-command.md

@@ -0,0 +1,122 @@
+---
+description: "Observability system with dual-storage trace events (SQLite + JSONL), structured logging across all harness subsystems (hooks, commands, TUI, agents), and CLI querying with filtering, stats aggregation, and real-time tailing."
+---
+
+## Intent
+
+When multiple agents run concurrently across tmux windows, debugging failures requires structured observability. The trace system captures events from every harness subsystem -- hooks, CLI commands, TUI actions, agent spawning -- and stores them in both a queryable SQLite database and a greppable JSONL file. The dual-storage design reflects the two access patterns: SQL for filtered queries and aggregation, JSONL for `grep`/`tail -f` workflows.
+
+## Event Model
+
+Every trace event carries agent context derived from environment variables (AGENT_ID, AGENT_TYPE, PROMPT_NUMBER, SPEC_NAME, BRANCH), enabling filtering by which agent produced the event. The `viaDaemon` flag distinguishes events from the CLI daemon vs direct tsx execution.
+
+### Event Types
+
+```mermaid
+graph LR
+    subgraph Session
+        ss[session.start]
+        se[session.end]
+    end
+
+    subgraph Tools
+        tp[tool.pre]
+        tpost[tool.post]
+        tf[tool.failure]
+        td[tool.denied]
+        be[bash.error]
+    end
+
+    subgraph Hooks
+        hs[hook.start]
+        hok[hook.success]
+        he[hook.error]
+    end
+
+    subgraph Commands
+        cs[command.start]
+        cok[command.success]
+        ce[command.error]
+    end
+
+    subgraph TUI
+        ta[tui.action]
+        tl[tui.lifecycle]
+        te[tui.error]
+    end
+
+    subgraph Agents
+        as2[agent.spawn]
+        ast[agent.stop]
+        ac[agent.compact]
+    end
+
+    subgraph Prompts
+        ps[prompt.submit]
+    end
+
+    subgraph Harness
+        herr[harness.error]
+    end
+```
+
+Error events are explicitly enumerated for fast filtering: `tool.failure`, `tool.denied`, `bash.error`, `hook.error`, `harness.error`, `tui.error`, `command.error`.
+
+## Storage Architecture
+
+[ref:.allhands/harness/src/lib/trace-store.ts:logEvent:36af65f] writes to both backends on every event:
+
+- **SQLite** (`.allhands/harness/.cache/trace/trace.db`): Indexed columns for agent_id, agent_type, event_type, tool_name, timestamp, is_error. Enables efficient filtered queries.
+- **JSONL** (`.allhands/harness/.cache/trace/trace.jsonl`): Append-only file, one JSON object per line. Enables `grep`, `jq`, and file-watching workflows.
+
+Both writes use silent failure -- trace errors never break the operation being traced.
+
+## Payload Sanitization
+
+To prevent log bloat from large tool inputs/outputs, payloads are trimmed before storage:
+
+| Control | Default | Env Override |
+|---------|---------|--------------|
+| Max string length | 200 chars | `TRACE_MAX_STRING_LENGTH` |
+| Max nesting depth | 3 levels | `TRACE_MAX_DEPTH` |
+| Max array items | 5 | `TRACE_MAX_ARRAY_ITEMS` |
+| Max object keys | 8 | `TRACE_MAX_OBJECT_KEYS` |
+
+[ref:.allhands/harness/src/lib/trace-store.ts:sanitizePayload:36af65f] applies [ref:.allhands/harness/src/lib/trace-store.ts:trimStrings:36af65f] and [ref:.allhands/harness/src/lib/trace-store.ts:truncateStructure:36af65f] to enforce these limits with cycle detection via WeakSet.
+
+## Structured Logging Helpers
+
+The trace store provides typed logging functions that construct appropriate event payloads:
+
+| Function | Event Type | Use Case |
+|----------|-----------|----------|
+| [ref:.allhands/harness/src/lib/trace-store.ts:logHarnessError:36af65f] | `harness.error` | Internal harness failures |
+| [ref:.allhands/harness/src/lib/trace-store.ts:logHookStart:36af65f] | `hook.start` | Hook execution begins |
+| [ref:.allhands/harness/src/lib/trace-store.ts:logHookSuccess:36af65f] | `hook.success` | Hook completes |
+| [ref:.allhands/harness/src/lib/trace-store.ts:logCommandStart:36af65f] | `command.start` | CLI command begins |
+| [ref:.allhands/harness/src/lib/trace-store.ts:logCommandSuccess:36af65f] | `command.success` | CLI command completes |
+| [ref:.allhands/harness/src/lib/trace-store.ts:logCommandError:36af65f] | `command.error` | CLI command fails |
+| [ref:.allhands/harness/src/lib/trace-store.ts:logTuiError:36af65f] | `tui.error` | TUI runtime error |
+| [ref:.allhands/harness/src/lib/trace-store.ts:logTuiAction:36af65f] | `tui.action` | User action in TUI |
+
+## Query Interface
+
+[ref:.allhands/harness/src/lib/trace-store.ts:queryEvents:36af65f] builds parameterized SQL queries from filter options:
+
+- `agentId`, `agentType` -- Filter by agent identity
+- `eventType` -- Single event type filter
+- `toolName` -- Filter by tool
+- `since` -- Time filter supporting relative strings (`1h`, `30m`, `2d`) and ISO timestamps
+- `errorsOnly` -- Boolean flag that filters on `is_error = 1`
+- `limit`/`offset` -- Pagination (default limit: 100)
+
+[ref:.allhands/harness/src/lib/trace-store.ts:getStats:36af65f] provides aggregate statistics with breakdowns by event type, agent type, and tool name, all supporting the `since` time filter.
+
+## CLI Commands
+
+[ref:.allhands/harness/src/commands/trace.ts:register:089fb26] exposes four subcommands:
+
+- **`ah trace list`** -- Query events with full filter support. Human-readable output highlights errors in red, shows truncated payloads for tool events, and displays prompt text for `prompt.submit` events.
+- **`ah trace errors`** -- Shortcut for `list --errors`. Prominently displays error messages, command summaries, hook names, and truncated stack traces.
+- **`ah trace stats`** -- Aggregate statistics with breakdowns. Useful for understanding activity patterns and error rates across agents.
+- **`ah trace tail`** -- Real-time event watching via filesystem change detection on the JSONL file. Supports `--agent` and `--type` filters. Uses `fs.watch` with position tracking to read only new lines.

package/docs/harness/cli-daemon.md

@@ -0,0 +1,92 @@
+---
+description: "Unix socket daemon that eliminates ~400ms Node.js startup overhead per hook invocation by running hooks in-process, using stdout interception and process.exit() catching to maintain hook compatibility."
+---
+
+# CLI Daemon
+
+The CLI daemon solves a performance problem: every hook invocation spawns a new Node.js process, paying ~400ms of startup overhead. When the TUI is running dozens of hooks per minute across multiple agents, this adds up. The daemon pre-loads all hook handlers into a long-running process and serves them over a Unix socket.
+
+## The Problem
+
+```
+Without daemon:
+  Agent tool call -> Claude Code hook -> spawn node -> parse CLI -> import modules -> run hook -> exit
+  ~400ms per invocation
+
+With daemon:
+  Agent tool call -> Claude Code hook -> connect socket -> send JSON -> receive result
+  ~5ms per invocation
+```
+
+## Architecture
+
+```mermaid
+flowchart LR
+    subgraph TUI Process
+        D[CLIDaemon] --> S[Unix Socket Server]
+        S --> H[Handler Registry]
+        H --> C[context hooks]
+        H --> V[validation hooks]
+        H --> O[observability hooks]
+        H --> E[enforcement hooks]
+    end
+
+    subgraph Agent Hook
+        CLI[ah hooks ...] --> |connect| S
+        S --> |JSON response| CLI
+    end
+```
+
+[ref:.allhands/harness/src/lib/cli-daemon.ts:CLIDaemon:e269aee] manages the server lifecycle. It listens on a Unix socket at `.allhands/harness/.cache/cli-daemon.sock` (resolved by [ref:.allhands/harness/src/lib/cli-daemon.ts:getSocketPath:e269aee]).
+
+## Handler Registration
+
+[ref:.allhands/harness/src/lib/cli-daemon.ts:registerHandler:e269aee] adds hook handlers to a global registry keyed by `"category.name"` (e.g., `"context.tldr-inject"`, `"validation.schema-check"`). Hook modules register via [ref:.allhands/harness/src/hooks/shared.ts:registerCategoryForDaemon:ca0caaf], which takes the same `HookCategory` definition used for CLI registration and adapts it for daemon mode.
+
+This dual-registration design means hook authors define their hooks once. The same handler function works whether invoked via the CLI (Commander subcommand) or the daemon (socket message).
+
+## I/O Interception
+
+The core challenge: existing hooks call `process.exit()` and write to `process.stdout`. In a daemon, these would kill the server or corrupt the socket stream.
+
+[ref:.allhands/harness/src/lib/cli-daemon.ts:runWithInterceptedIO:e269aee] solves this by:
+
+1. **Replacing `process.exit()`** with a throw of [ref:.allhands/harness/src/lib/cli-daemon.ts:ExitSignal:e269aee] -- a custom error class that the runner catches. The hook thinks it exited; the daemon stays alive.
+2. **Replacing `process.stdout.write()`** with a buffer capture. Hook output is collected into a string instead of going to the terminal.
+3. **Setting `AH_VIA_DAEMON=1`** in the environment so hooks can detect daemon mode for trace logging.
+4. **Restoring all originals** in a `finally` block, ensuring the daemon's I/O is never permanently corrupted even if a hook throws.
+
+## Command Protocol
+
+Communication uses newline-delimited JSON over the Unix socket:
+
+| Command | Fields | Response |
+|---------|--------|----------|
+| `hook` | `category`, `name`, `input` (HookInput) | `{success, output}` or `{success, output, fallback: true}` |
+| `ping` | -- | `{success, pong: true, handlers: N}` |
+| `list` | -- | `{success, handlers: ["ctx.tldr-inject", ...]}` |
+| `shutdown` | -- | `{success, shutting_down: true}` |
+
+[ref:.allhands/harness/src/lib/cli-daemon.ts:processCommand:e269aee] dispatches commands. For `hook` commands, it looks up the handler, runs it with intercepted I/O, and returns the captured output. If the handler is not registered, it returns `fallback: true` -- signaling the caller to fall back to CLI execution.
+
+[ref:.allhands/harness/src/lib/cli-daemon.ts:createConnectionHandler:e269aee] handles socket connections with buffered reads, splitting on newlines to support multiple commands per connection.
+
+## Stale Socket Handling
+
+On startup, `CLIDaemon.start()` checks if the socket file already exists. If another daemon is actively listening (verified by attempting a connection), it skips starting. If the socket is stale (left behind by a crashed process), it unlinks the file and starts fresh.
+
+On stop, the server closes and the socket file is cleaned up.
+
+## TLDR Daemon (Companion)
+
+The CLI daemon coexists with the TLDR daemon -- a separate process that handles code analysis. Key TLDR lifecycle functions:
+
+- [ref:.allhands/harness/src/lib/tldr.ts:isTldrInstalled:702ae0d] -- Checks if the `tldr` binary is available
+- [ref:.allhands/harness/src/lib/tldr.ts:isTldrDaemonRunning:702ae0d] -- Checks the TLDR socket (separate from CLI daemon socket)
+- [ref:.allhands/harness/src/lib/tldr.ts:ensureTldrDaemon:702ae0d] -- Starts the TLDR daemon if not running
+- [ref:.allhands/harness/src/lib/tldr.ts:hasSemanticIndex:702ae0d] / [ref:.allhands/harness/src/lib/tldr.ts:buildSemanticIndex:702ae0d] -- Manages the semantic search index
+- [ref:.allhands/harness/src/lib/tldr.ts:warmCallGraph:702ae0d] -- Pre-builds the call graph cache for impact analysis
+
+The TLDR daemon communicates via its own Unix socket, queried synchronously by [ref:.allhands/harness/src/lib/tldr.ts:queryDaemonSync:702ae0d] or asynchronously by [ref:.allhands/harness/src/lib/tldr.ts:queryDaemon:702ae0d]. When the daemon is unavailable, functions like [ref:.allhands/harness/src/lib/tldr.ts:searchDaemon:702ae0d] fall back to [ref:.allhands/harness/src/lib/tldr.ts:ripgrepFallback:702ae0d].
+
+The TUI starts both daemons at initialization and stops them on teardown.

package/docs/harness/event-loop.md

@@ -0,0 +1,184 @@
+---
+description: "Background polling daemon that monitors git branches, dispatches prompt execution, spawns hypothesis planner with exponential backoff, tracks agent windows, detects PR review feedback, and coordinates parallel agent spawning with cooldown guards."
+---
+
+# Event Loop
+
+The event loop is a non-blocking polling daemon that bridges external state (git, tmux, GitHub) with the TUI's reactive model. It runs on a configurable tick interval and fires callbacks when state changes, enabling the TUI to stay current without blocking user interaction.
+
+## Tick Architecture
+
+Each tick runs four independent checks in parallel, followed by a sequential prompt loop check:
+
+```mermaid
+graph TD
+    T[tick] --> P[checkPRReviewFeedback]
+    T --> G[checkGitBranch]
+    T --> A[checkAgentWindows]
+    T --> F[checkPromptFiles]
+    P & G & A & F --> L[checkPromptLoop]
+```
+
+[ref:.allhands/harness/src/lib/event-loop.ts:EventLoop:940f18a] stores all state in an [ref:.allhands/harness/src/lib/event-loop.ts:EventLoopState:940f18a] object that tracks the current branch, spec, PR URL, active agents, executor prompts, tick count, and hypothesis planner backoff counters (`emergentSpawnCount`, `emergentLastPromptCount`).
+
+## Check: PR Review Feedback
+
+[ref:.allhands/harness/src/lib/pr-review.ts:checkPRReviewStatus:ca5f05b] polls GitHub for PR review comments. The event loop only runs this check every N ticks (configured via `settings.prReview.checkFrequency`, default 3) since reviews take minutes to complete.
+
+The detection pipeline:
+1. [ref:.allhands/harness/src/lib/pr-review.ts:parsePRUrl:ca5f05b] validates the PR URL format
+2. Reads `lastReviewRunTime` from `status.yaml` to filter old comments
+3. Checks for comments matching the configured `reviewDetectionString` (default: "greptile")
+4. [ref:.allhands/harness/src/lib/pr-review.ts:hasNewReview:ca5f05b] compares previous and current `PRReviewState` to detect new reviews
+5. On detection, fires `onPRReviewFeedback` callback and updates `status.yaml`
+
+[ref:.allhands/harness/src/lib/pr-review.ts:triggerPRReview:ca5f05b] posts a comment (default: "@greptile") to trigger a new review cycle.
+
+## Check: Git Branch
+
+The event loop treats the git branch as the primary context key. On each tick, it reads the current branch and compares it to stored state. When a branch change is detected:
+
+1. Updates `currentBranch`, `planningKey` (sanitized branch name for `.planning/` lookup)
+2. Resolves the new spec via `getSpecForBranch()`
+3. Fires `onBranchChange` callback so the TUI reloads prompts and planning artifacts
+
+This implements the **branch-keyed model**: no separate "active spec" tracking is needed because the branch determines the spec.
+
+## Check: Agent Windows
+
+Monitors tmux windows to track which agents are alive. Only considers windows that appear in the spawned agent registry (preventing pickup of unrelated tmux windows).
+
+When agents disappear:
+- Their MCP daemons are cleaned up via `shutdownDaemon()`
+- They are unregistered from the spawn registry
+- Active executor prompt numbers are reconciled (executor/emergent windows encode prompt numbers in their names, e.g., `executor-03`)
+- The spawn cooldown timestamp is cleared when an executor or emergent window disappears, allowing new spawns immediately
+
+The reconciliation step also runs proactively: if `activeExecutorPrompts` contains numbers with no matching running window, those entries are pruned. This handles edge cases where an agent dies before the next `checkAgentWindows` tick.
+
+## Check: Prompt Files
+
+[ref:.allhands/harness/src/lib/prompts.ts:loadAllPrompts:89011a7] reads all prompt files from the current planning directory. The event loop computes a hash-based snapshot of prompt filenames, statuses, and numbers. When the hash changes, it fires `onPromptsChange` with the full prompt list and a `PromptSnapshot` containing counts by status.
+
+When new pending prompts are detected (snapshot pending count increases), the hypothesis planner backoff resets to zero -- external prompt creation signals productive work.
+
+This makes the harness the coordinator: it detects when agents create, modify, or complete prompts without those agents needing to know about the TUI.
+
+## Prompt Execution Loop
+
+The prompt loop is the sequential check that runs after all parallel checks complete, implemented in [ref:.allhands/harness/src/lib/event-loop.ts:EventLoop:940f18a]. It implements a unified decision path:
+
+```mermaid
+stateDiagram-v2
+    [*] --> CheckEnabled: loopEnabled?
+    CheckEnabled --> Paused: No
+    CheckEnabled --> CheckEmergent: Yes
+    CheckEmergent --> Blocked: emergent planner running
+    CheckEmergent --> CheckCapacity: no emergent
+    CheckCapacity --> AtMax: executors >= maxParallel
+    CheckCapacity --> CheckCooldown: has capacity
+    CheckCooldown --> Cooling: spawned < cooldown ago
+    CheckCooldown --> PickPrompt: cooldown clear
+    PickPrompt --> SpawnExecutor: pending prompt found
+    PickPrompt --> CheckBackoff: no pending + no in_progress
+    CheckBackoff --> BackoffWait: within backoff window
+    CheckBackoff --> SpawnHypothesisPlanner: backoff clear
+    PickPrompt --> Wait: no pending + in_progress exist
+```
+
+1. **Loop enabled + pending prompts** -- Pick next eligible prompt, spawn executor
+2. **Loop enabled + no pending + no in_progress** -- Spawn hypothesis planner (with backoff)
+3. **Loop enabled + no pending + in_progress exist** -- Wait for running executors
+4. **Loop disabled** -- Nothing happens
+
+### Parallel Execution Rules
+
+1. **One agent per tick** -- Only one agent spawns per event loop cycle, preventing thundering herds
+2. **Hypothesis planner singleton** -- At most one emergent planner runs at a time; the planner spawns only when all prompts are done (none pending, none in_progress)
+3. **Parallel executors** -- When parallel mode is enabled, up to `settings.spawn.maxParallelPrompts` (default 3) executors can run simultaneously
+4. **10-second base cooldown** -- [ref:.allhands/harness/src/lib/event-loop.ts:SPAWN_COOLDOWN_MS:940f18a] prevents race conditions where tmux hasn't registered the new window yet
+5. **Prompt exclusion** -- `activeExecutorPrompts` tracks which prompts have running agents, preventing duplicate assignment
+
+Two toggles control execution: **Loop** (O) enables/disables the entire prompt loop, **Parallel** (P) toggles multi-executor mode.
+
+### Prompt Selection
+
+[ref:.allhands/harness/src/lib/prompts.ts:pickNextPrompt:89011a7] selects the next prompt to execute:
+- Filters to `pending` status only
+- Checks dependency satisfaction via [ref:.allhands/harness/src/lib/prompts.ts:dependenciesSatisfied:89011a7] -- all dependency prompt numbers must be `done`
+- Excludes prompts already being worked on (`excludePrompts` parameter)
+- Returns the lowest-numbered eligible prompt (FIFO ordering)
+
+[ref:.allhands/harness/src/lib/prompts.ts:markPromptInProgress:89011a7] atomically updates the prompt's frontmatter status to `in_progress` using file locking via [ref:.allhands/harness/src/lib/prompts.ts:withFileLock:89011a7].
+
+## Hypothesis Planner Backoff
+
+When no pending or in-progress prompts remain, the event loop spawns a hypothesis planner to generate new work. To avoid wasteful respawning when the planner fails to produce prompts, exponential backoff is applied.
+
+### Tracking Productivity
+
+[ref:.allhands/harness/src/lib/event-loop.ts:EventLoopState:940f18a] tracks two fields:
+
+| Field | Purpose |
+|-------|---------|
+| `emergentSpawnCount` | Consecutive unproductive spawns (planner ran but did not create new prompts) |
+| `emergentLastPromptCount` | Total prompt count at time of last planner spawn -- compared against current count to detect new prompt creation |
+
+After each spawn, if `currentPromptCount <= emergentLastPromptCount`, the spawn was unproductive and `emergentSpawnCount` increments. If the planner produced new prompts, the count resets to zero.
+
+### Backoff Formula
+
+```
+cooldown = SPAWN_COOLDOWN_MS * 2^min(emergentSpawnCount, 4)
+```
+
+| Unproductive Spawns | Cooldown |
+|---------------------|----------|
+| 0 | 10s |
+| 1 | 20s |
+| 2 | 40s |
+| 3 | 80s |
+| 4+ | 160s (cap) |
+
+The base cooldown is [ref:.allhands/harness/src/lib/event-loop.ts:SPAWN_COOLDOWN_MS:940f18a] (10 seconds). The exponent caps at 4, giving a maximum wait of 160 seconds.
+
+### Backoff Resets
+
+The backoff counter resets to zero when:
+- **Loop toggle** -- `setLoopEnabled()` resets `emergentSpawnCount` on any toggle
+- **New pending prompt detection** -- `checkPromptFiles()` resets when `snapshot.pending > previousSnapshot.pending`
+
+Backoff status is traced via the `onLoopStatus` callback, logging messages like `Emergent planner backoff: waiting 40s (2 unproductive spawns)`.
+
+## Event Loop Callbacks
+
+[ref:.allhands/harness/src/lib/event-loop.ts:EventLoopCallbacks:940f18a] defines the callback interface:
+
+| Callback | Trigger |
+|----------|---------|
+| `onPRReviewFeedback` | New PR review detected |
+| `onBranchChange` | Git branch changed |
+| `onAgentsChange` | Agent windows appeared or disappeared |
+| `onSpawnExecutor` | Pending prompt picked for execution |
+| `onSpawnEmergentPlanning` | Hypothesis planner spawn triggered (no arguments -- planner uses profile defaults) |
+| `onLoopStatus` | Status messages for activity log |
+| `onPromptsChange` | Prompt files created, modified, or completed |
+
+## Configuration
+
+All timing and behavior is configurable via `.allhands/settings.json`:
+
+| Setting | Path | Default | Purpose |
+|---------|------|---------|---------|
+| Tick interval | `eventLoop.tickIntervalMs` | 5000 | Milliseconds between ticks |
+| PR check frequency | `prReview.checkFrequency` | 3 | Check PR every N ticks |
+| Review detection | `prReview.reviewDetectionString` | "greptile" | Comment substring to detect |
+| Rerun comment | `prReview.rerunComment` | "@greptile" | Comment to post for rerun |
+| Max parallel | `spawn.maxParallelPrompts` | 3 | Max concurrent executors |
+
+## Lifecycle
+
+- **Start**: `start()` begins the interval timer and runs an initial tick
+- **Stop**: `stop()` clears the interval
+- **Force tick**: `forceTick()` triggers an immediate tick, used when enabling parallel mode to spawn without waiting
+- **Branch sync**: `setBranchContext()` manually overrides branch state after TUI-initiated changes, preventing the event loop from re-detecting the change and overwriting TUI state

package/docs/harness/hooks/README.md

@@ -0,0 +1,15 @@
+---
+description: "Index of harness hook documentation covering context injection, validation enforcement, and lifecycle/observability hooks."
+---
+
+# Hooks
+
+Hooks intercept tool calls (PreToolUse, PostToolUse) and session events (Stop, Compact, SessionStart) to inject context, enforce rules, and observe agent behavior.
+
+## Hook Categories
+
+| Category | Doc |
+|---|---|
+| Context injection (tldr, edit, search routing, transcript safeguard) | `docs/harness/hooks/context-hooks.md` |
+| Validation (diagnostics, schema, formatting) | `docs/harness/hooks/validation-hooks.md` |
+| Lifecycle, observability, enforcement, notifications | `docs/harness/hooks/lifecycle-and-observability-hooks.md` |

package/docs/harness/hooks/context-hooks.md

@@ -0,0 +1,96 @@
+---
+description: "Pre/post tool hooks that inject TLDR-powered code analysis context, route searches through AST-grep and semantic layers, enforce token-efficient file reads, and provide impact analysis for refactoring operations."
+---
+
+# Context Hooks
+
+Context hooks intercept tool invocations to inject code intelligence before, during, and after agent tool use. They bridge the TLDR analysis daemon with the agent's tool pipeline, ensuring agents receive structured code understanding without consuming raw file tokens.
+
+All hooks gracefully degrade when TLDR is not installed -- they fall back to allowing the tool unmodified.
+
+## Intent-Driven Context Injection
+
+The primary entry point [ref:.allhands/harness/src/hooks/context.ts:detectIntent:f5da0a1] classifies agent prompts into analysis intents that determine which TLDR layers to query:
+
+| Intent | Trigger Patterns | TLDR Layers |
+|--------|-----------------|-------------|
+| `debug` | "debug", "investigate", "trace", "why does" | Call Graph + CFG |
+| `dataflow` | "where does", "come from", "data flow" | DFG |
+| `slice` | "what affects", "depends on", "impact of" | PDG/slice |
+| `structure` | "show structure", "list functions" | AST only |
+| `arch` | "plan", "design", "refactor", "architecture" | Architecture layers |
+| `default` | Everything else | Call Graph |
+
+[ref:.allhands/harness/src/hooks/context.ts:extractReferences:f5da0a1] supplements intent detection by pulling function/symbol references from backtick-quoted identifiers and function-call syntax in prompts.
+
+## Hook Inventory
+
+### PreToolUse Hooks
+
+**tldr-inject** -- [ref:.allhands/harness/src/hooks/context.ts:tldrContextInject:f5da0a1]
+Intercepts Task tool invocations. Routes to the appropriate TLDR daemon endpoint (context, CFG, DFG, arch) based on detected intent. Injects the analysis result as additional context so the agent sees code structure alongside its task.
+
+**edit-inject** -- [ref:.allhands/harness/src/hooks/context.ts:editContextInject:f5da0a1]
+Intercepts Edit tool invocations. Before an edit executes, fetches the file's code structure via TLDR extract, providing the agent with function signatures, class definitions, and import maps for the target file.
+
+**arch-inject** -- [ref:.allhands/harness/src/hooks/context.ts:archContextInject:f5da0a1]
+Intercepts architecture-related tool calls. Queries [ref:.allhands/harness/src/lib/tldr.ts:archDaemon:702ae0d] to inject architectural layer information (module boundaries, dependency direction, layer violations) into the agent's context.
+
+**signature-helper** -- [ref:.allhands/harness/src/hooks/context.ts:signatureHelper:f5da0a1]
+Intercepts code editing operations. Extracts function calls from the code being edited via [ref:.allhands/harness/src/hooks/context.ts:extractFunctionCalls:f5da0a1], then searches for their signatures using [ref:.allhands/harness/src/hooks/context.ts:getSearchPattern:f5da0a1]. Prevents agents from guessing function signatures by providing the actual definitions.
+
+**import-validator** -- [ref:.allhands/harness/src/hooks/context.ts:importValidator:f5da0a1]
+Validates import statements in edited files. Cross-references imports against the TLDR daemon's knowledge of the project's module graph, catching broken imports before they reach runtime.
+
+**read-enforcer** -- [ref:.allhands/harness/src/hooks/context.ts:tldrReadEnforcer:f5da0a1]
+Intercepts Read tool calls for large code files. Instead of allowing the agent to consume an entire file's tokens, returns a TLDR-generated summary (imports, classes, functions with signatures and line numbers) and denies the raw read. Bypasses for: files under 100 lines, explicit offset/limit parameters, non-code files, and recent search context indicating a specific location.
+
+**search-router** -- [ref:.allhands/harness/src/hooks/context.ts:smartSearchRouter:f5da0a1]
+Intercepts Grep tool calls and routes them through a three-tier search strategy:
+1. AST-grep for structural code patterns (function defs, class declarations)
+2. TLDR semantic search for natural language / conceptual queries
+3. Literal ripgrep fallback if both fail
+
+Uses [ref:.allhands/harness/src/hooks/context.ts:classifySearchPattern:f5da0a1] to determine query type and [ref:.allhands/harness/src/hooks/context.ts:suggestLayers:f5da0a1] to select the optimal search layer. Saves search context via [ref:.allhands/harness/src/hooks/shared.ts:saveSearchContext:ca0caaf] for downstream hooks (read-enforcer uses this to allow targeted reads after a search).
+
+### PostToolUse Hooks
+
+**post-edit-diagnostics** -- [ref:.allhands/harness/src/hooks/context.ts:postEditDiagnostics:f5da0a1]
+Runs after Edit tool completes. Queries [ref:.allhands/harness/src/lib/tldr.ts:diagnosticsDaemon:702ae0d] against the edited file, surfacing type errors and lint issues immediately so agents can self-correct without a separate diagnostic step.
+
+**edit-notify** -- [ref:.allhands/harness/src/hooks/context.ts:editNotify:f5da0a1]
+Async notification after file edits. Calls [ref:.allhands/harness/src/lib/tldr.ts:notifyFileChanged:702ae0d] to update the TLDR daemon's dirty file tracking, keeping the analysis cache consistent with the current working tree.
+
+### UserPromptSubmit Hooks
+
+**impact-refactor** -- [ref:.allhands/harness/src/hooks/context.ts:impactRefactor:f5da0a1]
+Triggers when a user prompt mentions refactoring keywords (refactor, rename, move, delete, extract, inline). Extracts function names via [ref:.allhands/harness/src/hooks/context.ts:extractImpactFunctionNames:f5da0a1], queries [ref:.allhands/harness/src/lib/tldr.ts:impactDaemon:702ae0d] for the reverse call graph, and injects a caller listing so agents understand the blast radius before modifying code.
+
+**transcript-safeguard** -- [ref:.allhands/harness/src/hooks/context.ts:transcriptSafeguardPre:f5da0a1]
+PreToolUse guard on TaskOutput. Blocks all TaskOutput calls unconditionally -- background tasks broadcast a completion notification with their result when they finish, making TaskOutput redundant. Blocking prevents dumping massive raw transcripts into agent context.
+
+## Search Context Pipeline
+
+```mermaid
+sequenceDiagram
+    participant Agent
+    participant SearchRouter
+    participant ReadEnforcer
+    participant Cache
+
+    Agent->>SearchRouter: Grep(pattern="handleAction")
+    SearchRouter->>SearchRouter: classifySearchPattern() -> structural/function
+    SearchRouter->>Cache: saveSearchContext({target, layers})
+    SearchRouter-->>Agent: AST-grep results with file:line
+
+    Agent->>ReadEnforcer: Read(file_path, no offset)
+    ReadEnforcer->>Cache: loadSearchContext()
+    ReadEnforcer->>ReadEnforcer: Has definitionLocation? Allow full read
+    ReadEnforcer-->>Agent: Full file content (search-targeted)
+```
+
+The search context cache connects the search-router and read-enforcer hooks. When a search finds a specific definition location, the subsequent read is allowed in full rather than being replaced with a summary. This prevents the frustrating pattern of search finding a result but the read being blocked.
+
+## Graceful Degradation
+
+Every hook in this module checks [ref:.allhands/harness/src/lib/tldr.ts:isTldrInstalled:702ae0d] and [ref:.allhands/harness/src/lib/tldr.ts:isTldrDaemonRunning:702ae0d] before attempting analysis. If TLDR is unavailable, hooks call [ref:.allhands/harness/src/hooks/shared.ts:allowTool:ca0caaf] and exit silently. This means the harness functions without TLDR -- agents just lose the enriched context layer.

package/docs/harness/hooks/lifecycle-and-observability-hooks.md

@@ -0,0 +1,135 @@
+---
+description: "Agent lifecycle management (stop, compact, session start), observability tracing across all hook events, enforcement rules for tool access, notification delivery, hook discovery/registration, and shared utilities underpinning the hook system."
+---
+
+# Lifecycle, Observability, and Infrastructure Hooks
+
+This document covers the hooks that manage agent lifecycles, record observability data, enforce access policies, handle notifications, and provide the shared infrastructure that all hooks depend on.
+
+## Agent Lifecycle
+
+### Stop Handler
+
+[ref:.allhands/harness/src/hooks/lifecycle.ts:handleAgentStop:166f290] runs when an agent signals completion. It:
+1. Checks if the agent's tmux window exists via the tmux library
+2. Sends a notification that the agent has stopped
+3. Retrieves the prompt associated with the agent via [ref:.allhands/harness/src/lib/prompts.ts:getPromptByNumber:89011a7]
+4. Kills the tmux window to free resources
+
+The stop handler uses [ref:.allhands/harness/src/hooks/shared.ts:outputStopHook:ca0caaf] with `decision: 'approve'` to confirm the agent should terminate.
+
+### Compaction Handler
+
+[ref:.allhands/harness/src/hooks/lifecycle.ts:handleAgentCompact:166f290] intercepts the PreCompact event -- triggered when an agent's context window fills up. Instead of losing context, it:
+1. Delegates to [ref:.allhands/harness/src/lib/compaction.ts:runCompaction:031e2fc] which analyzes the conversation state
+2. The compaction system uses an oracle to analyze what the agent accomplished and recommend next actions
+3. Generates a progress update via [ref:.allhands/harness/src/lib/compaction.ts:formatProgressUpdate:031e2fc]
+4. Appends the progress to the prompt file via [ref:.allhands/harness/src/lib/prompts.ts:appendToProgressSection:89011a7]
+5. Executes the recommendation (commit, continue, or stop) via [ref:.allhands/harness/src/lib/compaction.ts:executeRecommendation:031e2fc]
+6. Outputs a system message via [ref:.allhands/harness/src/hooks/shared.ts:outputPreCompact:ca0caaf] that survives the compaction
+
+The compaction pipeline captures git diff state through [ref:.allhands/harness/src/lib/compaction.ts:getGitDiffSummary:031e2fc] and [ref:.allhands/harness/src/lib/compaction.ts:getGitDiffFull:031e2fc] to give the oracle full visibility into what changed.
+
+### Session Start
+
+[ref:.allhands/harness/src/hooks/session.ts:tldrWarm:98e8198] runs on SessionStart. It warms the TLDR daemon cache by calling [ref:.allhands/harness/src/lib/tldr.ts:warmIndex:702ae0d]. The hook is entirely non-blocking -- if TLDR is not installed or the daemon is already running, it exits silently. Errors are swallowed to never block session initialization.
+
+## Observability
+
+[ref:.allhands/harness/src/hooks/observability.ts::239a80d] provides structured logging across every hook event type. Each handler logs to the trace store via [ref:.allhands/harness/src/lib/trace-store.ts:logEvent:36af65f].
+
+### Event Coverage
+
+| Event | Handler | What Gets Logged |
+|-------|---------|-----------------|
+| SessionStart | [ref:.allhands/harness/src/hooks/observability.ts:handleSessionStart:239a80d] | Session ID, timestamp |
+| PromptSubmit | [ref:.allhands/harness/src/hooks/observability.ts:handlePromptSubmit:239a80d] | Prompt content summary |
+| PreToolUse | [ref:.allhands/harness/src/hooks/observability.ts:handleToolPre:239a80d] | Tool name, input summary |
+| PostToolUse | [ref:.allhands/harness/src/hooks/observability.ts:handleToolPost:239a80d] | Tool result, error detection |
+| ToolFailure | [ref:.allhands/harness/src/hooks/observability.ts:handleToolFailure:239a80d] | Error details, stderr |
+| ToolDenied | [ref:.allhands/harness/src/hooks/observability.ts:handleToolDenied:239a80d] | Denial reason |
+| TaskSpawn | [ref:.allhands/harness/src/hooks/observability.ts:handleTaskSpawn:239a80d] | Sub-agent metadata |
+| AgentStop | [ref:.allhands/harness/src/hooks/observability.ts:handleAgentStop:239a80d] | Completion status |
+| AgentCompact | [ref:.allhands/harness/src/hooks/observability.ts:handleAgentCompact:239a80d] | Compaction trigger reason |
+
+[ref:.allhands/harness/src/hooks/observability.ts:shouldLogTool:239a80d] filters noise by skipping high-frequency, low-value tool calls. [ref:.allhands/harness/src/hooks/observability.ts:summarizeBashCommand:239a80d] truncates long shell commands to keep log entries readable. [ref:.allhands/harness/src/hooks/observability.ts:isBashError:239a80d] parses Bash tool results to detect non-zero exit codes and stderr output.
+
+[ref:.allhands/harness/src/hooks/observability.ts:handleToolPreWithTaskRouting:239a80d] extends the base PreToolUse handler with task-aware routing logic, tracking sub-agent spawns alongside regular tool usage.
+
+## Enforcement Rules
+
+[ref:.allhands/harness/src/hooks/enforcement.ts::e905788] contains PreToolUse hooks that enforce access policies:
+
+- [ref:.allhands/harness/src/hooks/enforcement.ts:enforceGitHubUrl:e905788] -- Intercepts WebFetch/WebSearch for GitHub URLs and redirects agents to use `gh` CLI instead, which has authenticated access and richer output
+- [ref:.allhands/harness/src/hooks/enforcement.ts:enforceResearchFetch:e905788] -- Controls web fetch operations during research phases, ensuring agents use approved research channels
+- [ref:.allhands/harness/src/hooks/enforcement.ts:enforceResearchSearch:e905788] -- Controls web search operations, applying similar research-phase policies
+
+Enforcement hooks use [ref:.allhands/harness/src/hooks/shared.ts:denyTool:ca0caaf] with specific guidance messages, redirecting agents to better alternatives rather than simply blocking.
+
+## Notifications
+
+[ref:.allhands/harness/src/hooks/notification.ts:handleStopNotification:5b5578d] and [ref:.allhands/harness/src/hooks/notification.ts:handleCompactNotification:5b5578d] send system notifications when agents stop or compact. They use [ref:.allhands/harness/src/lib/notification.ts:sendGateNotification:8f14a76] to deliver alerts, keeping operators informed of agent lifecycle events without requiring TUI visibility.
+
+## Transcript Parsing
+
+[ref:.allhands/harness/src/hooks/transcript-parser.ts:parseTranscript:338596c] is a utility that processes Claude Code JSONL transcript files into structured summaries (`TranscriptSummary`). It streams the file line-by-line via readline for memory efficiency.
+
+[ref:.allhands/harness/src/hooks/transcript-parser.ts:summarizeToolInput:338596c] condenses verbose tool inputs into one-line summaries. [ref:.allhands/harness/src/hooks/transcript-parser.ts:buildCompactionMessage:338596c] transforms a parsed transcript summary into a system message suitable for compaction injection.
+
+## Hook Registration Infrastructure
+
+### Auto-Discovery
+
+[ref:.allhands/harness/src/hooks/index.ts:discoverAndRegisterHooks:8fe9903] scans the hooks directory at runtime, dynamically importing every `.ts` file (except `index.ts`, `shared.ts`, and `transcript-parser.ts`). Each module must export a `register(parent: Command)` function that attaches its subcommands to the CLI.
+
+This pattern means adding a new hook category requires only creating the file -- no manual registration.
+
+### Category-Based Registration
+
+[ref:.allhands/harness/src/hooks/shared.ts:registerCategory:ca0caaf] provides declarative hook registration. A `HookCategory` object describes all hooks in a category with their names, event types, matchers, and handler functions. The function generates Commander subcommands for CLI execution.
+
+[ref:.allhands/harness/src/hooks/shared.ts:registerCategoryForDaemon:ca0caaf] does the same registration but targets the CLI daemon's in-process handler registry instead of Commander, enabling the same hook definitions to work in both CLI and daemon modes.
+
+### Shared I/O Protocol
+
+All hooks communicate through a JSON stdin/stdout protocol defined in [ref:.allhands/harness/src/hooks/shared.ts::ca0caaf]:
+
+```mermaid
+stateDiagram-v2
+    [*] --> ReadInput: stdin JSON
+    ReadInput --> ProcessHook: HookInput parsed
+    ProcessHook --> AllowTool: No action needed
+    ProcessHook --> DenyTool: Block with reason
+    ProcessHook --> InjectContext: Add context
+    ProcessHook --> OutputContext: Post-tool info
+    ProcessHook --> BlockTool: Post-tool block
+    ProcessHook --> OutputStopHook: Lifecycle decision
+    ProcessHook --> OutputPreCompact: Compaction message
+    AllowTool --> [*]: exit(0), no output
+    DenyTool --> [*]: JSON + exit(0)
+    InjectContext --> [*]: JSON + exit(0)
+    OutputContext --> [*]: JSON + exit(0)
+    BlockTool --> [*]: JSON + exit(0)
+    OutputStopHook --> [*]: JSON + exit(0)
+    OutputPreCompact --> [*]: JSON + exit(0)
+```
+
+Key I/O functions:
+- [ref:.allhands/harness/src/hooks/shared.ts:readHookInput:ca0caaf] -- Reads and parses stdin JSON, normalizing `tool_response` to `tool_result`
+- [ref:.allhands/harness/src/hooks/shared.ts:allowTool:ca0caaf] -- Silent exit (no output = allow)
+- [ref:.allhands/harness/src/hooks/shared.ts:denyTool:ca0caaf] -- Outputs deny decision with reason
+- [ref:.allhands/harness/src/hooks/shared.ts:blockTool:ca0caaf] -- Outputs block decision with message
+- [ref:.allhands/harness/src/hooks/shared.ts:injectContext:ca0caaf] -- Modifies tool input to add context
+- [ref:.allhands/harness/src/hooks/shared.ts:preToolContext:ca0caaf] -- Adds pre-tool context
+- [ref:.allhands/harness/src/hooks/shared.ts:outputContext:ca0caaf] -- Adds post-tool context
+- [ref:.allhands/harness/src/hooks/shared.ts:outputStopHook:ca0caaf] -- Approve or block agent stop
+- [ref:.allhands/harness/src/hooks/shared.ts:outputPreCompact:ca0caaf] -- Inject compaction system message
+
+### Utility Functions
+
+- [ref:.allhands/harness/src/hooks/shared.ts:getProjectDir:ca0caaf] -- Resolves the project root directory
+- [ref:.allhands/harness/src/hooks/shared.ts:loadProjectSettings:ca0caaf] -- Reads `.allhands/settings.json` for project-level configuration
+- [ref:.allhands/harness/src/hooks/shared.ts:getBaseBranch:ca0caaf] -- Determines the base branch for git operations
+- [ref:.allhands/harness/src/hooks/shared.ts:detectLanguage:ca0caaf] -- Infers programming language from file extension, glob pattern, or type hints
+- [ref:.allhands/harness/src/hooks/shared.ts:getCacheDir:ca0caaf] / [ref:.allhands/harness/src/hooks/shared.ts:getCacheSubdir:ca0caaf] -- Manage per-project cache directories
+- [ref:.allhands/harness/src/hooks/shared.ts:saveSearchContext:ca0caaf] / [ref:.allhands/harness/src/hooks/shared.ts:loadSearchContext:ca0caaf] -- Persist search state between hooks within a session