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, so a slow hook cannot stall a session - with one carve-out that is not steer's to set:

flowchart TD
    subgraph SessionStart
      inject[inject-standards.sh × N parts<br/>injects rules/*.md, each part under the 10k-char cap]
      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]
      cd[check-comment-density.sh<br/>comment-density notice]
    end
    subgraph Stop
      reconcile[reconcile-issue-first.sh]
    end
    subgraph Lifecycle
      cwd[CwdChanged<br/>check-worktree-trust.sh]
      send[SessionEnd<br/>on-session-end.sh]
      wtr[WorktreeRemove<br/>on-worktree-remove.sh]
    end

SessionStart¶

Since the session-checks consolidation, hooks.json registers three SessionStart scripts: the rule injection (one command per part), 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.

SubagentStart¶

PreToolUse¶

PostToolUse¶

Stop¶

Lifecycle events¶

Three registrations that are not gates and not context injection: they run because the harness has told steer that something in the session's environment changed. None of the three carries decision control, so none of them can block what it observes - a session ending, a worktree being removed, a directory change. SessionEnd and WorktreeRemove discard their JSON output fields; CwdChanged does not - it discards only continue.

What they can report differs:

The two teardown modes are the same distinction rules 45-delivery § Parallel worktrees and 50-done § End-of-session checklist draw, now attempted automatically rather than requested: stop what is running when a session ends, remove the data only when the thing that owned it is being deleted. Both share hooks/lib/worktree-lifecycle.sh. Only the WorktreeRemove half is dependable; the SessionEnd half is opportunistic, so the rules still ask the agent to stop what it started.

A worktree deleted by another tool - Orca, Conductor, git worktree remove - never raises WorktreeRemove. /steer:setup worktrees installs that tool's own teardown hook and sweeps the stacks it already orphaned.

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, check-comment-density);
• 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:setup 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 six words. Four describe a native spec/ spine:

Two further states cover an OpenSpec repo, and they are tested first, before the spec/ ladder above - such a repo may have no spec/ directory at all, which the ladder would read as unmanaged and answer with the greenfield bootstrap card, pushing an init that would lay a competing spec/features/** spine beside openspec/:

The OpenSpec test is openspec/project.md, openspec/specs/ or openspec/changes/ - a bare openspec/ directory is not enough, mirroring this helper's refusal to read a bare spec/ as a spine. Making these states rather than a bypass in front of one caller is what keeps /steer:setup doctor, /steer:setup sync and /steer:audit answering the same question the same way.

Where the three steer artifacts live¶

OpenSpec models none of an ADR log, a tracker declaration or an app guide, so steer keeps all three - on an OpenSpec repo, under openspec/steer/:

The steer/ segment is deliberate: openspec/ is written by a third-party CLI (openspec update regenerates openspec/AGENTS.md wholesale; archive relocates whole change directories), so a flat openspec/decisions/ would be one upstream release away from a collision. Both paths resolve through steer_tracker_file / steer_decisions_dir / steer_app_docs_dir in hooks/lib/scope.sh - the single definition every hook and script reads, so nothing can disagree about which file declares the tracker. steer_tracker_rel gives the repo-relative form the nudges name in their user-facing text, so a message never points at a path the repo does not have. Repos on the pre-fold shape are carried across by the MIGRATIONS.md ledger entry that /steer:setup sync applies.

The app guide matters here for a reason that is not cosmetic: scan-capabilities.sh reports app-knowledge-docs from that path and /steer:setup sync repairs an absent capability by creating the file - left pointing at spec/app/, sync would recreate a stray spec/ on the repo that just moved out of it.

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:setup 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:setup 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 AND, which binds loosest, so every arm must hold - 12-stack-infra's has-iac&org-e22 is the org pack's IaC stack, delivered only to an IaC repo that follows the pack. | for OR is also supported (the rule injects when any listed predicate holds) but no shipped rule uses it since the 6.6 rule diet folded the deployment rule, which carried has-iac|has-apps, into the code-project rule 45-delivery. The predicates are tracker-github, has-infra, has-iac, has-apps, has-compose, has-openspec, code-project, org-e22, automation-optin, 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. automation-optin is the single deliberate exception - it fails closed, because rule 53-autonomous-loops governs machinery a repo only has once it declares policy/automation.yml with loops: true, so injecting it by default would charge every consumer for a feature almost none of them run.

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.

Hook enforcement is guaranteed on Claude Code only. The GitHub Copilot CLI has its own hook harness and the plugin used to ship a parallel hooks/copilot-hooks.json for it; that variant retired, so the CLI runs no steer hooks and takes the standards from the committed .github/copilot-instructions.md. Copilot Chat in VS Code runs this hooks.json directly, as a Claude-format plugin, and so picks the hooks up incidentally - with no parity promise - see Copilot support.