v0.7.0 — base operator-control hooks + kind=hook installer support
Three new hook customizations for long-running Claude Code sessions, lifted from the cwc-long-running-agents pattern. First real consumer of kind: hook in the toolkit's manifest schema; this release lands first-class hook-kind installer support including .claude/settings.json idempotent deep-merge.
| Hook | Event | What it does |
|---|---|---|
kill-switch |
PreToolUse | touch .harness/STOP → halts the next tool call (exit 2 + halt-message stderr); rm to resume. |
steer |
PreToolUse | Write .harness/STEER.md with a mid-run redirect → next tool call sees the contents in agent context; file renamed to STEER.consumed-<iso-ts>.md for audit trail. |
commit-on-stop |
Stop | If working tree is dirty at turn-end, creates auto-save/<iso-ts> branch and commits the work there. Returns HEAD to original branch with clean tree. Never modifies current branch; never pushes. |
Paired with agentic-harness v2.2.0, which adds optional sections to /work and /release phase specs documenting how to dispatch the three hooks. The harness works standalone without the toolkit — graceful-skip when toolkit is absent.
Highlights
- Three hook customizations at
hooks/{kill-switch,steer,commit-on-stop}/, each withhook.md+ bash/pwsh scripts + bash/pwsh settings fragments. Claude-Code-only for v0.7.0; manual equivalents for Antigravity + Gemini CLI documented in the how-to. - First-class
kind: hookinstaller dispatch acrossinstall.sh+install.ps1: per-host paths to.claude/hooks/<name>.{sh,ps1}(chmod +x on POSIX) + idempotent deep-merge ofsettings-fragment-{bash,pwsh}.jsoninto.claude/settings.json. New--hook/-Hookflag. Newscripts/merge-settings-fragment.pyhelper. - ADR 0003 — base operator-control hooks — captures Context (3 forces + 7 open questions), Decision (7 locked design calls: per-repo file location, STEER audit-trail rename, safety-branch not current-branch, Stop-event-only for v0.7.0, alphabetical-install-order hook ordering, claude-code-only scope, Python helper for settings merge), Consequences (5+/6−/5 load-bearing assumptions w/ re-audit triggers).
- How to use the base hooks — practical recipe with three worked scenarios (halt runaway loop, mid-run redirect, crash recovery), hook-ordering invariant, file conventions, cleanup patterns, manual equivalents for other hosts, troubleshooting.
- MANAGED_PARENTS extended with
.claude/hooksfor true-sync--updateorphan cleanup..claude/settings.jsonis NOT wiped — it's user-state-merged; the toolkit re-merges its fragments idempotently each install run.
Locked invariants (load-bearing; documented for re-audit)
- kill-switch fires before steer in PreToolUse. Alphabetical install order enforces this:
commit-on-stop<kill-switch<steer; within PreToolUse (only kill-switch + steer share it), kill-switch is the first entry. A halt always takes precedence over a redirect. - Per-repo file location.
.harness/STOP,.harness/STEER.md, andauto-save/<ts>all scope to the project root. Device-scope is deferred to a futuredev-machine-setupplan. - commit-on-stop never modifies the current branch. All saves go to a fresh
auto-save/<ts>branch; HEAD returns to the original branch with a clean working tree.
Scope adjustment from plan
commit-on-stop ships Stop event only for v0.7.0. The N-consecutive-errors trigger (PostToolUse with state-tracking + COMMIT_ON_STOP_ERROR_THRESHOLD env var) is deferred to a follow-up plan — Stop covers the load-bearing case; the N-errors variant requires hook-side state machinery that's significantly more complex.
Future consumers
These three hooks are the load-bearing primitives for several future roadmap items:
- Design skill (#6) — per-step execution loop benefits from all three (halt + redirect + crash recovery).
- Quality-gates bundle (#10) — packages kill-switch + steer + commit-on-stop alongside the evaluator (#3) and evidence-tracker (#9).
- Long-running custom skills — any skill that runs for >5 minutes wants the operator-precision layer.
See CHANGELOG.md for the full v0.7.0 entry.