Skip to content

v0.7.0 — base operator-control hooks + kind=hook installer support

Choose a tag to compare

@alexherrero alexherrero released this 14 May 13:52
· 536 commits to main since this release

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 with hook.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: hook installer dispatch across install.sh + install.ps1: per-host paths to .claude/hooks/<name>.{sh,ps1} (chmod +x on POSIX) + idempotent deep-merge of settings-fragment-{bash,pwsh}.json into .claude/settings.json. New --hook / -Hook flag. New scripts/merge-settings-fragment.py helper.
  • 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/hooks for true-sync --update orphan cleanup. .claude/settings.json is 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, and auto-save/<ts> all scope to the project root. Device-scope is deferred to a future dev-machine-setup plan.
  • 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.