hookshot
Hookshot
From docs to enforcement hooks. Reads what you've documented. Generates the hooks that make agents read it.
Philosophy: Hookshot warns by default, blocks only for a gate the repo opted into. It never amends files, never lints-and-fixes. Every hook it generates emits guidance and exits 0; the one exception is the delivery gate, which a repo can flip from shadow (log only) to enforce (refuse the stop) after reading its own shadow log.
Modes
Hookshot is composable — invoke with one or more flags. Default mode (no flags) runs the doc-coverage generator.
| Flag | What it adds |
|---|---|
| (no flag) | Doc coverage — PreToolUse Edit/Write hook that nudges agents to read the relevant docs/ section before editing a covered file. (Default behavior, documented below.) |
--drift-warn |
Skill drift warning — PreToolUse Edit/Write hook that warns when an agent edits a file inside .claude/skills/<name>/ for a skill that's tracked in skills-lock.json. Edits should go upstream. |
--md-lint |
Markdown lint — PostToolUse Edit/Write hook that runs npx markdownlint-cli2 on any changed *.md file and surfaces warnings. Never auto-fixes. |
--preflight |
Session preflight — SessionStart hook (startup, resume, clear, compact) that tells the agent its session id, to run preflight for a task, and where to record its outcome-contract pointer. Ships scripts/preflight.py. |
--gate |
Delivery gate — Stop hook that diffs what exists against the session's outcome contract. Shadow mode logs would-be refusals; enforce mode refuses the stop. Ships scripts/gate.py, references/contract-format.md, references/shadow-log.md. |
Flags compose: /hookshot --drift-warn --md-lint installs both new hooks alongside the default doc-coverage hook. --preflight --gate are the only modes that ship scripts of their own and the only ones that install into Codex as well as Claude Code. Re-running hookshot merges with existing hooks idempotently.