Hooks reference¶

steer's hooks are POSIX-sh scripts under plugins/steer/hooks/, wired in hooks.json. They inject the always-on rules and gate risky actions. All hook commands are invoked with an explicit sh prefix, so the executable bit is irrelevant (marketplace install does not chmod). No jq dependency. Every hook declares an explicit timeout in hooks.json (10s for the rule injection, orientation, and PreToolUse hooks; 30s for the consolidated session checks, the PostToolUse formatter, and the Stop reconcile) so a slow hook can never stall a session.

flowchart TD
    subgraph SessionStart
      inject[inject-standards.sh<br/>injects rules/*.md]
      checks[session-checks.sh<br/>orchestrates the six session checks]
      orient[orient-session.sh]
      checks --> drift[check-template-drift.sh]
      checks --> oq[check-open-questions.sh]
      checks --> unmanaged[check-unmanaged-repo.sh]
      checks --> faults[surface-faults.sh]
      checks --> grad[check-graduation.sh]
      checks --> wt[check-worktree-trust.sh]
    end
    subgraph PreToolUse
      pins[check-version-pins.sh]
      wn[check-write-nudges.sh<br/>spec/scaffold + issue-first]
      ba[check-bash-actions.sh<br/>trunk-push gate + issue-create guard]
    end
    subgraph PostToolUse
      fmt[format-on-write.sh<br/>format the just-written file]
    end
    subgraph Stop
      reconcile[reconcile-issue-first.sh]
    end

SessionStart¶

Since the session-checks consolidation, hooks.json carries three SessionStart registrations: the rule injection, one session-checks.sh orchestrator, and the orientation hook. The session checks are no longer registered individually — session-checks.sh runs them in the order below, failure-isolated (a crashing check never blocks the rest) and always exiting 0; each check keeps its own contract (read the payload from stdin, print a notice or nothing) and stays individually testable.

PreToolUse¶

PostToolUse¶

Stop¶

Shared input extraction (lib/json.sh)¶

The PreToolUse/Stop hooks read their JSON payload from stdin through one shared helper, hooks/lib/json.sh — deterministic, dependency-free, and with no jq requirement (it uses jq only as a fast path when present, and falls back to a narrow POSIX grep/sed extractor otherwise). The two paths agree on the same contract:

• A field resolves to tool_input.<name> in preference to a top-level .<name>, so a same-named field elsewhere in the payload cannot be mistaken for the tool's real argument (e.g. the file_path a Write is about).
• Within that scope the first match wins, so a repeated key buried in a later content value cannot shadow the real field, and escaped quotes/backslashes in values are tolerated.

This is best-effort extraction for the exact PreToolUse shapes — not a general JSON parser — and every consuming hook is fail-open, so an unparseable payload degrades to a missed nudge, never a wrongful block.

Which repo a hook is judging (lib/repo-root.sh)¶

Hooks receive the session cwd, but the thing being acted on is not always in the same repository. When a git repo is nested inside another work tree — a vendored or gitignored clone, a tools/ checkout, a polyrepo member cloned inside its workspace — an upward .git walk from cwd stops at the outer repo while the tool writes to, or pushes from, the inner one. Every marker read off that root (delivery mode, profile, graduation signals, tracker) then describes the wrong repository.

steer_action_root <cwd> [action_path] resolves from the acted-on path instead, falling back to cwd's root when there is none:

• editor writes pass tool_input.file_path / .notebook_path (check-write-nudges, check-version-pins, format-on-write);
• the trunk-push gate passes the -C <dir> target of the git command (steer_git_c_target, used by check-bash-actions).

A path that does not exist yet resolves via its nearest existing ancestor, so a Write creating a new file — or a new directory — is attributed to the repo that will contain it. No path, an unresolvable path, or a path outside any work tree all fall back to cwd, leaving the single-repo case (the overwhelmingly common one) exactly as it was.

There is no equivalent handling for cd <dir> && git push: only -C states its target in the command line. That case still resolves from cwd.

steer_primary_worktree <root> answers a different question: which checkout a relative marker path should be resolved against. A linked worktree (.claude/worktrees/<name>) is a different work-tree root than the checkout the marker was written in, so a relative path resolved against it silently points somewhere else. It returns <root> unchanged for a primary checkout and the primary's root for a linked worktree, reading the gitdir: pointer out of the worktree's .git file rather than shelling out to git (this file is sourced on the PreToolUse hot path). Anything it cannot read with certainty — an unparseable .git, a relative gitdir:, a --separate-git-dir layout — returns <root> unchanged. Two consumers: steer_workspace_root (below) anchors relative marker paths with it, and check-worktree-trust.sh uses it as the linked-worktree detector — a returned root that differs from the session's root is the signal that this checkout is a linked worktree.

Is this repo spine-managed, and is the spine intact (lib/spine.sh)¶

Three hooks need to know whether the repo in front of them has a steer-managed /spec spine before they say anything: check-unmanaged-repo.sh (the bootstrap nudge), orient-session.sh (the SessionStart orientation line) and check-write-nudges.sh. They all get the answer from one helper, hooks/lib/spine.sh — also sourced by the bundled scripts/scan-spine-state.sh and scripts/workspace-snapshot.sh, which is how the skills that need the state (/steer:setup, /steer:sync, /steer:next, …) reach it: a skill dot-sourcing this file directly cannot pre-approve the call, and check_skill_helper_sourcing now fails the build on it. Its only dependency is lib/repo-root.sh, so it stays usable on the hook hot path.

steer_spine_state <repo_root> prints exactly one of four words:

Two things about that classification are load-bearing:

• spec/.version, not spec/, is the ownership marker. A bare spec/ directory proves nothing — an empty folder, or a foreign OpenAPI spec/, would otherwise silence the bootstrap nudges in a repo that was never bootstrapped.
• A polyrepo member's spine is partial by design. Product-level artifacts live once in the workspace repo, so a member (detected by spec/PRODUCT.md) is checked against STEER_SPINE_REQUIRED_MEMBER — just the pointer — instead of the full STEER_SPINE_REQUIRED. Without that split every member would report damaged and /steer:sync would "repair" it by reinstalling the very product-level files the topology exists to de-duplicate, recreating the split-brain spine.

The action history is deliberately absent from STEER_SPINE_REQUIRED. It is a directory (spec/history/) whose legacy single-file shape is still valid, so it needs an either-or presence test rather than a file-existence check: a repo that predates that migration is structurally fine, just older, and reporting damaged would fire the repair nudge on every such repo. A migrated repo has both — the directory plus the frozen archive — which also passes. The migration itself is carried by the MIGRATIONS.md ledger, not by the spine check.

Version drift — a spine older or newer than the installed plugin — is intentionally not decided here. /steer:sync and /steer:next own that semver comparison; this helper answers only the structural question so the always-on hooks stay fast and dependency-free.

Which rules apply, and to which repo (lib/scope.sh)¶

Every scope decision a hook makes — which always-on rules to inject, whether the issue-first nudges apply, which repo a tracker write belongs to — comes from hooks/lib/scope.sh. It is sourced by every SessionStart and PreToolUse hook, so it stays POSIX sh with no jq and no network.

steer_inject_when_ok <token> <root> is the entry point for rule scoping: a rule whose first line is <!-- steer:inject-when=<token> --> is injected only when the predicate holds. Tokens compose with | for OR — the rule injects when any listed predicate holds (the one shipped composite is 52-deployment's has-iac|has-apps). The predicates are tracker-github, has-infra, has-iac, has-apps, has-compose, code-project, polyrepo, has-workspace-manifest and has-product-pointer. An unknown token fails open (injects), so a typo'd marker can never silently drop a rule from the always-on context.

Four helpers resolve polyrepo topology:

• steer_polyrepo_role <root> — prints workspace when spec/workspace.yml is present, member when spec/PRODUCT.md is, and nothing in a single repo.
• steer_workspace_path <root> — prints the optional relative path to a local workspace checkout, read from spec/PRODUCT.md's workspace.path. It is scoped to the workspace: block, so an unrelated path: elsewhere in the pointer is never mistaken for it, and an unresolved [...] placeholder counts as absent. This is the raw reader; callers wanting a usable checkout use the next one.
• steer_workspace_root <root> — the local workspace checkout a member can actually read the spine from, or non-zero meaning "use the GitHub gateway". It adds the two tests the raw path lacks, both of which were silent failures: a relative path is anchored on steer_primary_worktree (so it survives a linked worktree), and spec/workspace.yml must be present at the resolved path — a directory that merely exists is not a workspace. Without the second test the path: .. the member template recommends resolved, inside a worktree, to a real but empty .claude/worktrees directory, which satisfied an existence check and made every product-level spec read as absent.
• steer_tracker_repo <root> — the tracker's declared repository: value. In a member this is deliberately never that member's own repo, which is why closing refs across repos need the cross-repo form.

A fifth helper, steer_tracker_is_github, is the behaviourally largest — it decides whether the issue-first rules and nudges apply. In a member there is no local spec/tracker.md, so it resolves the workspace's through steer_workspace_root — and when no local checkout is declared it fails open to inject. That fail-open is what turns issue-first on in a polyrepo member (rule 36-issue-first, plus check-write-nudges.sh, check-bash-actions.sh and reconcile-issue-first.sh): the alternative, treating an unreachable tracker as "no tracker", silently disabled the tracker discipline in exactly the repos where all the code lives.

steer_work_mode <root> separates a code project from a knowledge-work folder; in knowledge mode inject-standards.sh skips every conditional rule and keeps only the unmarked always-on core.

Surfaces without hooks¶

Claude Code (CLI, IDE extensions, Desktop Code tab) and Cowork run hooks; the Desktop Chat tab and claude.ai web chat do not. On those chat-only surfaces, load the rules manually with /steer:standards. See Installation and Known limitations.

GitHub Copilot CLI has its own hook harness; the plugin ships a parallel hooks/copilot-hooks.json for it — see Copilot support.