---
name: od-hooks
description: Hooks/harness incidents — hook timeout, context spam, polling anti-patterns, a factory run stuck, hanging turn, crash mid-run, MCP/subagent resume. Triggers on hook, harness, timeout, workflow stuck, advisor. Invoke BEFORE changing harness supervision or adding daemons.
---

# Hooks / harness — incident playbook

audience: AI coding agents first. BLUF: reproduce hook/harness failure in isolation → fix fail-closed → NEVER restore v1 daemon/auto-relaunch.

## Covers

**Absorbs:** `hook-timeout`, `context-spam`, `polling-anti-pattern`, `tool-reliability-fatigue` (harness-reliability subset — ids C033, C034, C035, C050, C080, C122, C125, C182, C192 per taxonomy `_meta`).

**Keywords:** hook, harness, timeout, factory, workflow, stuck, hanging turn, context spam, polling, advisor, mcp, subagent, resume, crashed mid-run.

**Registry coverage:** 24 of 217 (2026-08-08). Recurring: hook floods context; polling where notify exists; coordinator restart masquerading as resume.

## Doctrine

Reproduce hook/harness failure in isolation. Fix fail-closed. NEVER restore v1 daemon/auto-relaunch behavior.

## First steps — canonical spec FIRST

1. **Factory phase/retry/gate/permission edit:** `python3 -m pytest modules/harness/factory/tests/ -q` MUST stay green. NEVER weaken a gate to make a run pass. Mandatory per repo `AGENTS.md`.
2. **Isolate hook:** run failing hook script directly with same stdin/env the PreToolUse/PostToolUse path uses. Hook must fail-closed on bad input, not hang.
3. **Classify failure:** hook timeout vs harness scheduler vs journal corruption vs UI polling. Different owners — do not conflate.
4. **Factory run stuck:** it blocks in the foreground by design. Read its phase from `/factory` or `factory watch`; a run waiting on a human is in `factory decisions`. There is NO resume — `factory stop <adw_id>` then relaunch. NEVER add a watchdog/reconcile/daemon to "fix" a crash.
5. **Context spam:** measure hook output bytes; route heavy output through `ft` filter or quietcontext MCP — hook must not dump raw build logs into context.
6. **Polling anti-pattern:** if event source exists (SSE, journal tail, notify), replace poll loop. UI staleness ≠ authority to add more polling.
7. **Repro artifact:** minimal command sequence + observed hang/timeout before code change.

## Never-touch — applies here

From `modules/workstation/claude/incidents/never-touch.md`:

- NEVER bypass admission queue or prevent-band gates.
- NEVER write in shared main checkout.
- NEVER restore v1-style harness daemon, automatic coordinator relaunch, or reconcile timers.

## Placement map — read these paths

`modules/workstation/claude/incidents/placement-map.md`:

- `~/.claude` — hooks (`hooks/`), harness `bin/`, skills.
- `~/.local/state/overdeck` — harness journals, `items.jsonl`, run state.
- Deploy clone — collector incident brief assets; harness bundle resolution: `modules/harness/CLAUDE.md`.

## Resolve — exact CLI (never guess syntax)

```
od-incidents list [--type hooks-harness] [--state S]
od-incidents show <id>
od-incidents search <query>
od-incidents resolve <id> --artifact <ref> [--summary <line>]
```

`resolve` REFUSES without `--artifact` (exit 2). Artifact = isolated hook repro test passing, or harness checkpoint resume test, or fix sha on origin/main.