@descent-vtt/spec-harness 0.19.0 → 0.20.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "spec-harness",
       "source": "./",
       "description": "Rounds of agent work under a brief.",
-      "version": "0.19.0"
+      "version": "0.20.0"
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-harness",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Rounds of agent work under a brief: context, a guard on every write, escalations a person signs, an audit at the end. Needs Claude Code 2.1.139 or later, and @descent-vtt/spec-harness and @descent-vtt/spec-brief 0.2.0 or later installed in the project.",
   "author": {
     "name": "DescentVTT",

package/CHANGELOG.md

@@ -9,6 +9,218 @@ only fixes, reports less or documents, so `^0.7.0` takes only releases that
 cannot turn a run red. The family's policy is
 [spec-core's ADR-0009](https://github.com/DescentVTT/spec-core/blob/main/docs/adr/0009-versions-before-1-0.md).
 
+## 0.20.0
+
+The hook decides each path by the work tree that holds it, a third
+worktree's and the MCP server's included, and finds siblings in the main
+checkout's install wherever a work tree has none; every process it starts
+has a time limit, and it reads only a file where a file is expected, so a
+named pipe no longer holds it without end; it says a guard that is off with
+exit 0, and `init --block-on-failure` asks Claude Code to hold a write when
+the hook cannot start. It gives a session spec-brief's answer again where
+nothing that answer was read from has changed, and it can report, at the end
+of a turn and where the configuration asks for it, what the work tree holds
+that the brief protects or that is outside its scope
+([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md),
+[ADR-0002](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0002-siblings-through-their-command-lines.md)).
+
+A configuration that does not load lets a write to itself through, so
+that a session can mend it; a write outside every work tree of the
+repository is held by no brief and no configuration; and `doctor` fails
+where the branch names a brief no round can work under
+([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md),
+[ADR-0004](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0004-the-active-brief-is-named-not-guessed.md)).
+
+`doctor` says a line of Claude Code's hook that asks for the help or the
+version as a guard that is off, fails `--strict` where git cannot say
+where it runs its hooks, and notes in a linked worktree the release the
+hook's line runs; a `.spec-harness.json` that cannot be read is said as
+that; and on Windows a drive letter is one in either case
+([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md)).
+
+### Added
+
+- **A report at the end of a turn, where `.spec-harness.json` asks for
+  one.** With `"turnReport": true`, `hook claude` answers Claude Code's
+  `Stop`: with one `git status`, every path the work tree holds changed
+  that the brief protects or that is outside its scope, a shell's writes
+  among them, in the words a write of it is given, as one `systemMessage`,
+  exit 0, and never a field that has Claude go on. `init` writes the entry,
+  in the background, where the key is on, and Claude reads the report as the
+  next turn begins; the plugin carries none, and with it on `init` says
+  what to add
+  ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md),
+  [ADR-0012](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0012-one-way-into-claude-code.md)).
+  Upgrading: off by default, so nothing changes until the key is turned on
+  and `spec-harness init --write` run again. A `Stop` entry aimed at the
+  hook exited 1, `the hook input names no event or tool`, and now exits 0;
+  a configuration's unknown key is refused with `turnReport` among the keys
+  it names.
+- **`init --block-on-failure` writes `"onFailure": "block"` on its hook
+  entries before and after a write and as a session starts**, and on those
+  an earlier run wrote, so that Claude Code 2.1.295 or later holds a write
+  where the hook cannot start, as in a worktree with no install, or runs
+  past its timeout. It is written only
+  where asked for, and the plugin does not carry it: no page says what an
+  older release does with the key. `doctor` advises it in a note, failing
+  nothing, for a line that guards without it where the Claude Code on
+  `PATH` reads the field
+  ([ADR-0012](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0012-one-way-into-claude-code.md)).
+  The entry at the end of a turn is left without it: it runs in the
+  background, where the hooks reference gives the field no effect.
+- **`doctor`, run in a linked worktree, notes the release the hook's line
+  runs.** The line names its script under `${CLAUDE_PROJECT_DIR}`, which
+  in a worktree session of the desktop app is the main checkout. Where the
+  main checkout's install of spec-harness and the worktree's are not one
+  release, a note names both; it fails nothing.
+
+### Changed
+
+- **The hook gives a session spec-brief's list of the briefs again, where
+  nothing it was read from has changed.** On a brief's branch the hook
+  started spec-brief before every write, most of what a write waited for on
+  Windows. Where spec-brief's `list --format json` names everything its
+  answer was read from, its `inputs`, the hook keeps the answer for the
+  session under the git common directory, in `spec-harness/answers/`, and
+  gives it again to the session's later runs while every file, directory
+  and index on the list reads as listed, with no process started; anything
+  else starts spec-brief as before. No answer changes
+  ([ADR-0002](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0002-siblings-through-their-command-lines.md),
+  [ADR-0003](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0003-state-outside-the-work-tree.md)).
+  Upgrading: nothing to change. A spec-brief whose `list` names no
+  `inputs`, 0.9.0 and every release before it, is started before every
+  write as it was.
+- **A process the harness asks a question of is stopped after 20 seconds,
+  and the hook holds the write there.** git had no limit and spec-brief
+  ten minutes, where Claude Code cancels the hook at the 60 seconds its
+  entry gives it, and before a write lets the write go ahead: a named pipe
+  at `.spec-brief.json` or `.git/config` kept the hook, `doctor` and
+  every command from coming back. git's reads and spec-brief's list are
+  now stopped at 20 seconds and said, `spec-brief did not answer within
+  20 seconds, and was stopped`; before a write that is `cannot check this
+  write: ...`, exit 2, which holds it. A round's work, a diff, a probe's
+  worktree, a sibling's check, keeps ten minutes
+  ([ADR-0002](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0002-siblings-through-their-command-lines.md)).
+  Upgrading: where git or spec-brief takes longer than 20 seconds to
+  answer, which none measured does, writes are held and commands exit 2
+  with the line: find what it waits on.
+- **A path is decided by the work tree that holds it.** A path in a work
+  tree of the repository that was neither the one the project names nor
+  the one the question's `cwd` is in was read from the project's top, as a
+  file of `.claude/worktrees/<name>/` under the project's branch or as one
+  outside the project, and a write its own brief protects passed with no
+  word. That work tree now decides it, by its branch, briefs and
+  configuration; a nested repository's file is decided as before
+  ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md)).
+  Upgrading: a session that writes into another worktree has the write
+  refused where that worktree's brief protects it.
+- **Every command finds the siblings in the main work tree's install** where
+  a linked worktree has none, as git's hook and `doctor` did: `guard`,
+  `context`, `audit`, `probe` and the rest exited 2, `spec-brief is not
+  installed here`.
+  Upgrading: in such a worktree these commands run, and `guard` and
+  `audit` can exit 1 where they exited 2.
+- **The server reads the work tree a path is in, and the round in the one
+  its client names.** `check_path` read every path as the project's, and
+  every tool the project's branch, so a worktree's file read as
+  `.claude/worktrees/<name>/...` and its brief went unnamed. `check_path`
+  decides an absolute path by the work tree of the repository that holds
+  it, and `start_round`, `check_path`, `request_escalation` and
+  `audit_round` read the round in the work tree a new `directory`
+  argument names, else the one the client's roots name where they name
+  exactly one of the repository's, else the project's, and say which as
+  `workTree`
+  ([ADR-0008](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0008-one-server-for-rounds.md)).
+  Upgrading: a client that declares roots naming a worktree has its calls
+  answered for that worktree; a script reading the tools' structured
+  answers finds `workTree`.
+- **The hook says the guard is off with exit 0, where it exited 1.** A
+  question it cannot read and a line of its own that turns the guard off
+  (one it cannot read, a `--root` that is no directory) were one line on
+  stderr and exit 1, which Claude Code counts as a hook that failed: under
+  `"onFailure": "block"` that held every write of the session, the one
+  that mends the line among them. Each is now the same line to the person,
+  as `systemMessage`, and exit 0, and the write goes on as it did, so
+  `onFailure` holds only a hook that did not run
+  ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md)).
+  Upgrading: a script that read the hook's exit 1 or its stderr reads the
+  line as `systemMessage` on stdout, with exit 0.
+- **A write to `.spec-harness.json` itself goes on while it does not
+  load.** Every write was held, exit 2, the one that mends the file among
+  them, so a session could not mend a typo in it. Before a write to that
+  file and to nothing else, the hook now decides nothing, exit 0, so the
+  person's own permission prompt stands, and says why every other write is
+  held, to the person and to Claude. A file of that name elsewhere, a link
+  to it, a second name of it and the configuration of another work tree
+  are held as before, and so is a configuration that is a directory, a
+  named pipe, or a link to a file of the repository. As a session starts
+  the hook says the same.
+  Upgrading: a brief that protects `.spec-harness.json` does not hold that
+  write while the file does not load, since none of it is read; the audit
+  and spec-brief's archive still measure the change.
+- **`doctor` exits 1 where the branch names a brief spec-brief does not
+  know, or has archived.** The hook holds every write on such a branch,
+  and `doctor` said so on its `brief` line and exited 0. One the flag or
+  `SPEC_BRIEF` names still fails nothing.
+  Upgrading: a branch whose name only reads as a brief's, as
+  `fix/brief-list-order` names `list` under the default `branches`, fails
+  `doctor` as it holds every write: rename the branch, or set `branches` in
+  `.spec-harness.json`.
+- **A write outside every work tree of the repository is not held by what
+  holds the writes inside.** A brief that is archived, or that spec-brief
+  does not list, whichever names it, and a configuration that does not
+  load held every write, a file outside the repository among them, and
+  `guard` refused such a path, exit 2. Such a write passes as one outside
+  the repository does, with no word, and spec-brief is not asked about it;
+  one inside any work tree of the repository, a linked worktree's among
+  them, is decided as before, by the work tree that holds it, and a path
+  with a `..` in it is held as before.
+  Upgrading: `guard` of a path outside the repository exits 0 under such
+  a brief, where it exited 2.
+- **A hook line that asks for the help or the version is a guard that is
+  off.** `hook claude --help`, `--version`, `-h` and `-v` print the help
+  or the version, exit 0, and check no write, which Claude Code takes for a
+  hook that succeeded; `doctor` said such a line guards, and said a
+  `--brief 404` beside it held every write. It says the line as one under
+  which no write is checked, whatever else is on it, and exits 1.
+  Upgrading: take the option off the hook's line; `doctor` exits 1 until
+  it is.
+- **`--help` or `--version` beside a `--root` that is not a directory is
+  a line the hook cannot read.** `hook claude --help --root nowhere`
+  printed the help, exit 0, where without `--help` the hook says the
+  root. It says `the hook's line cannot be read (--help is given beside a
+  fault, --root is "nowhere", which is not a directory, ...)` as it says
+  every line it cannot read, to the person with exit 0, before a write and
+  after one, and holds no write; as a session starts it says the same.
+  `doctor` says the line in the same words.
+  Upgrading: mend the line; no line a release wrote carries either.
+- **`doctor --strict` fails where git cannot say where it runs its
+  hooks.** Under a `core.hooksPath` that names a file, `where git runs its
+  hooks cannot be told` failed nothing, under `--strict` or not, where a
+  release, a hook's line, a plugin or a hook file that cannot be told
+  fails `--strict`.
+  Upgrading: point `core.hooksPath` at a directory, or leave it unset.
+
+### Fixed
+
+- **A named pipe where the harness reads a file** no longer keeps a
+  command from coming back: a document a brief cites, a sibling's
+  `package.json`, what the run before a write kept, git's configuration
+  and a worktree's `commondir` as the hook reads them, a request waiting
+  for a ruling, a probe's report. Only a regular file is read, and what
+  else stands there is read as a file that is not there
+  ([ADR-0002](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0002-siblings-through-their-command-lines.md)).
+- **A `.spec-harness.json` that cannot be read is said as that.** One the
+  account may not read, or one another process holds open on Windows, was
+  `.spec-harness.json is not valid JSON: EACCES: ...`. It is
+  `.spec-harness.json cannot be read: EACCES: ...`, exit 2 as before, and
+  a write to the file itself goes on, as to one that does not load.
+- **On Windows `--root C:\work` beside `--root c:\work` is one root.**
+  Every command refused the two as two directories, exit 2, and the hook
+  read such a line as one it cannot read, under which it checked no write;
+  Windows names a volume by its letter in either case. The hook now guards
+  under that root, and the rest of the path is compared as before.
+
 ## 0.19.0
 
 An option that takes one value is given one, and a line that is wrong is

package/README.md

@@ -91,8 +91,11 @@ An app that makes a branch for a session puts a name of its own before the brief
 - A branch that names an id spec-brief does not list, as `claude/brief-999-x`, is not passed over for the next: every write of the session is held until the brief or the branch is mended. Where Claude Code starts the hook as a session starts, the entry `init` and the plugin write under `SessionStart`, the session is told so before its first write.
 - A tag of the same name as the branch does not hide it: the branch is read as HEAD names it.
 - In a worktree session started from the desktop app, and after Claude enters a worktree mid-session, Claude Code starts the hook with `${CLAUDE_PROJECT_DIR}` at the main checkout and hands it the worktree as the question's `cwd` (the worktrees page, *What worktrees share with the main checkout*; [the hooks reference](https://code.claude.com/docs/en/hooks), *Reference scripts by path*). The worktree's branch names the brief, and a worktree with no install of its own is checked with the project's: an Edit of a file brief 042 protects, in a worktree on `claude/brief-042-x` of a main checkout on `main`, is refused.
-- git's pre-commit hook in such a worktree runs the main work tree's install where the worktree has none, and refuses the same file at the commit. A hook an earlier release wrote reads the worktree's own install alone: take it away and run `init --git-hook --write`.
-- Where `${CLAUDE_PROJECT_DIR}` is the worktree itself, the project root a session started in, the hook's script is looked for in the worktree's own `node_modules`. A worktree is a fresh checkout (the worktrees page, *Set up the worktree environment*), and where it has no install, node cannot find the script and exits 1: Claude Code reads that as a hook's non-blocking error, and the write goes ahead (the hooks reference, *Exit code output*). Install in the worktree before such a session writes. From Claude Code 2.1.295, `"onFailure": "block"` on the hook's entry holds the write instead; neither `init` nor the plugin writes it ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md)).
+- A path is decided by the work tree that holds it, where that is a work tree of the same repository, whichever `cwd` is in: an Edit of a file brief 042 protects, in a worktree on `claude/brief-042-x`, is refused from a session at the main checkout and from one in another worktree, inside the project or beside it. A path in no work tree of the repository is decided as before ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md)).
+- A nested repository, a submodule or a clone inside the tree, is another repository, and a path in it is decided as before, by the work tree of the project's repository that holds it, under the path it has there. What that lets through: a file the nested repository's own brief protects is outside the project's scope, warned of after the write and not refused, and one the project's brief does not reach passes with no word. That repository is guarded by its own hook, in its own sessions.
+- Where `${CLAUDE_PROJECT_DIR}` points in a session started with `claude --worktree` is on no page of Claude Code's: the hooks reference has it the project root where the session started, the worktrees page has the flag start Claude in the worktree, and a worktree a fresh checkout to install dependencies into, and says where it points only for a session started from the desktop app. Where it is the worktree, the next point holds.
+- git's pre-commit hook in such a worktree runs the main work tree's install where the worktree has none, and refuses the same file at the commit. So does every other command, `guard`, `context`, `audit`, `probe` and the rest, where each said that spec-brief is not installed here. A hook an earlier release wrote reads the worktree's own install alone: take it away and run `init --git-hook --write`.
+- Where `${CLAUDE_PROJECT_DIR}` is the worktree itself, the project root a session started in, the hook's script is looked for in the worktree's own `node_modules`. A worktree is a fresh checkout (the worktrees page, *Set up the worktree environment*), and where it has no install, node cannot find the script and exits 1: Claude Code reads that as a hook's non-blocking error, and the write goes ahead (the hooks reference, *Exit code output*). Install in the worktree before such a session writes. From Claude Code 2.1.295, `"onFailure": "block"` on the hook's entry holds the write instead: `init --block-on-failure` writes it on init's PreToolUse, PostToolUse and SessionStart entries, and the plugin does not carry it ([ADR-0012](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0012-one-way-into-claude-code.md)).
 
 ### Sessions that write through a shell, with no rulings
 
@@ -103,6 +106,7 @@ Claude Code starts the guard for `Edit`, `Write`, `MultiEdit` and `NotebookEdit`
 | The guard, before an Edit | an Edit of `src/db/schema.ts`: refused, with the next step | an Edit of `notes.md` under `outOfScope: "warn"`; every shell command |
 | The guard, after an Edit | an Edit of `notes.md`: a warning to Claude | every shell command |
 | The hook as a session starts | a configuration that does not load, an id spec-brief does not list, spec-brief missing or too old where a brief is named: one line, to the person and to Claude | everything: it holds nothing, and the event cannot block |
+| The report at the end of a turn, `"turnReport": true` | every path the work tree holds changed, a shell's writes among them: `src/db/schema.ts` reported as protected and `notes.md` as outside the scope, to Claude as the next turn begins | a change made and undone, or committed, within the turn; an ignored file; a turn an interrupt or an API error ends; and it refuses nothing, the write having happened |
 | git's pre-commit hook, `init --git-hook` | every staged path, a shell's writes among them: `src/db/schema.ts` refused; `notes.md` warned of under `warn`, refused under `ask` and `deny` | `git commit --no-verify`, which skips the hook ([githooks](https://git-scm.com/docs/githooks), *pre-commit*) |
 | `spec-harness audit` | the round's commits from the base: `src/db/schema.ts` changed, an error, and `notes.md`, a warning; exit 1 | what the brief, as it stands at the end, allows |
 | `spec-brief archive --strict --base <branch>` | the same, both errors: the brief is not archived | the same |
@@ -110,11 +114,11 @@ Claude Code starts the guard for `Edit`, `Write`, `MultiEdit` and `NotebookEdit`
 What every layer lets through:
 
 - **An edit of the brief.** Its file is always writable, and the audit and the archive read the brief as it stands at the end: a round that adds `notes.md` to `affectedFiles` and takes `src/db/schema.ts` out of `protectedFiles` is archived with `--strict`. The change is in the brief's diff, for the person who approved it to read.
-- **A shell's write**, until the commit.
+- **A shell's write**, until the commit; with `turnReport` on, it is reported at the end of the turn, and not refused.
 - **`git commit --no-verify`**, until the audit.
 - **A Claude Code mod** that handles `tool.check` can approve a call a `PreToolUse` hook blocked, unless the hook is in managed settings ([Claude Code's permissions page](https://code.claude.com/docs/en/permissions), *Precedence among rules, hooks, and mods*).
 
-Two more layers were weighed and not built. A `PostToolUse` hook for the shell tools: every shell command would pay for it, it is easy to get around, and the audit stays the gate ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md), amended 2026-09-30). And `"protected": "ask"`: a protected file passes the guard only by a ruling whose commit a person signed, which the audit and the archive check again ([ADR-0006](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0006-a-ruling-is-a-signed-commit.md)), and an approval given in the session is kept nowhere they read.
+Two more layers were weighed and not built. A `PostToolUse` hook for the shell tools: every shell command would pay for it, it is easy to get around, and the audit stays the gate; the report at the end of a turn is paid once a turn, in the background, and reads the work tree rather than a command ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md), amended 2026-09-30). And `"protected": "ask"`: a protected file passes the guard only by a ruling whose commit a person signed, which the audit and the archive check again ([ADR-0006](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0006-a-ruling-is-a-signed-commit.md)), and an approval given in the session is kept nowhere they read.
 
 ## Commands
 
@@ -171,13 +175,18 @@ May the round write this?
 Paths are compared as the filesystem spells them, links resolved and case corrected, so `SRC/db/schema.ts` does not walk past a protection on `src/db/schema.ts` on Windows.
 
 - `spec-harness hook claude` answers Claude Code's PreToolUse and PostToolUse hooks: a refusal before the write, with the reason and the next step; a warning after a write outside the scope. It never answers `allow`, which would skip the person's own permission prompt. When it cannot answer - the configuration does not load, the briefs cannot be read, the harness meets an error it did not expect - it exits 2, and before a write Claude Code then holds the write.
+- While `.spec-harness.json` does not load, a write to that file itself is let through, so that a session can mend it: no decision, so the person's own permission prompt stands, and the line that says why every other write is held, to the person as `systemMessage` and to Claude as `additionalContext`, as `.spec-harness.json: unknown key "outofscope"; ..., so every other write is held until it loads; this write, to /work/app/.spec-harness.json itself, is not checked`. The write is to the file and nothing else as the hook reads a path and as the disk does: a file that stands under that name alone, not a link to one and with no second name, named by every path of the call. A file of the same name elsewhere, a link to it, and the configuration of another work tree than the one that does not load are held as every other write is. After the write the hook loads the file again, and says, exit 2, where it still does not load. While it does not load nothing of it is read, so a brief that protects the file, or an `outOfScope` it sets, does not hold this write; the audit and spec-brief's archive still measure the round's change to it ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md)).
+- A write outside every work tree of the repository is decided as one outside the repository is, whatever holds the writes inside: a brief that is archived, or that spec-brief does not list, whichever names it, and a configuration that does not load. It passes with no word, before the write and after it, and spec-brief is not asked about it; `guard` says it is outside the repository. The work trees are the main one and every linked worktree, as the files git keeps under its common directory name them, and a file of a linked worktree is decided as any other inside, by the worktree that holds it. Where they cannot all be named, a git directory kept apart, an entry git keeps that cannot be read, or a `core.worktree` where the configuration does not load, the write is held as before, and so is a path with a `..` in it, which the hook reads before its links where Linux and macOS write it after ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md)).
 - In a worktree, a write is decided by the worktree's brief. Claude Code names the project a session started in, and hands the hook the directory Claude works in as the question's `cwd`: in a worktree session started from the desktop app, and after Claude enters a worktree, the first is the main checkout and the second the worktree. Where `cwd` is in another work tree of the same repository, that work tree's branch names the brief, its briefs and configuration are read, and its siblings are looked for in its own `node_modules` and then the project's, so a worktree with no install is checked with the project's. A path it does not hold, and every path where `cwd` is in another repository or in none, is decided by the project as before ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md)).
 - After a write the hook answers from what it decided before it, for the same call: the run before keeps the warnings it would give under the git common directory, in `spec-harness/calls/`, named by the question's `session_id` and `tool_use_id`, and the run after takes them away and answers with no process started. A refused call keeps nothing, nor one that writes `.spec-harness.json`, spec-brief's configuration, the brief or a file beside it, which are decided again after the write; what no run after a write reads is removed after a day. Under `outOfScope: "ask"` or `"deny"` no write is warned of, and the run after one says nothing with no process started ([ADR-0002](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0002-siblings-through-their-command-lines.md)).
+- On a brief's branch the hook asks spec-brief for the briefs, which on Windows is most of what a write waits on. Within a session it keeps spec-brief's answer, where spec-brief's `list` names every input it was read from (`inputs`), under the git common directory in `spec-harness/answers/`, by the work tree, the session, spec-brief's script and version, the command line, and the variables git and Node read; and it gives the answer again while each file on the list has the digest listed, or is still not there, each directory holds the files listed, or is still not there where it was listed as not there, and the git index and ignore files read as listed, with no process started. Anything else starts spec-brief as before: an input that is missing, unreadable or reads otherwise, `keep` not `true`, an answer with no `inputs`, a command `tools` names, and, where the list names what git read, `GIT_DIR`, `GIT_WORK_TREE`, `GIT_INDEX_FILE` or `GIT_COMMON_DIR` set. What is kept is removed after a day; every other command starts spec-brief every time ([ADR-0002](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0002-siblings-through-their-command-lines.md)).
 - As a session starts, resumes, is cleared, compacted or forked, `hook claude` answers Claude Code's SessionStart with what would hold every write of the session, in one line, to the person as `systemMessage` and to Claude as `additionalContext`: a configuration that does not load, a brief the line, `SPEC_BRIEF` or the branch names that spec-brief does not list, spec-brief missing or too old where a brief is named, and what is wrong with the hook's own line. Nothing is said where all is well, and it exits 0 whatever it finds: the event cannot block, and the session's start is not to be stopped by it ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md)).
+- With `"turnReport": true` in `.spec-harness.json`, `hook claude` answers Claude Code's `Stop`, which it runs as its main agent finishes a turn: with one `git --no-optional-locks status`, every path the work tree holds changed, a shell's writes among them, that the brief protects or that is outside its scope under the `outOfScope` in force, in the words a write of each is given, twenty by name and how many more, as one `systemMessage`; or nothing. It exits 0 and never has Claude go on. `init` writes the entry with `"async": true`, so the turn waits on none of it and Claude Code hands the report to Claude as the next turn begins; without `async` the person sees it as the turn ends, Claude does not, and the end of the turn waits for it. No ruling is read: a protected file a signed ruling allows is reported, and the audit reads the ruling. The plugin brings no such entry; with it on, `init` says the entry to add ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md), [ADR-0012](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0012-one-way-into-claude-code.md)).
+- A process the hook asks a question of, git or spec-brief's list of the briefs, is stopped after 20 seconds: Claude Code cancels the hook at the 60 seconds `init` and the plugin give its entry, and before a write lets the write go ahead. At the limit the hook says `cannot check this write: spec-brief did not answer within 20 seconds, and was stopped` and exits 2, which holds the write. Every command gives a question the same time, and a round's work, a diff, a probe's worktree, a sibling's check, ten minutes ([ADR-0002](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0002-siblings-through-their-command-lines.md)).
 - `spec-harness hook git` is a pre-commit hook for any agent or none. `init --git-hook` writes it; in a hook of your own it is the line `node node_modules/@descent-vtt/spec-harness/bin/spec-harness.js hook git`.
 - `hook claude` passes over whatever else is on its line that it does not read, as every release has, where every other command [refuses it](#an-input-that-names-nothing): its line is in settings a later release cannot rewrite, and exit 2 from it holds every write.
-- A `--root` on the hook's line that is a file, or is not there, is a guard that was set up and is off: `hook claude` says so on stderr and exits 1, which Claude Code shows as a hook error while the write goes on. It refuses nothing for it. No release wrote a `--root` there; without one the hook reads the project Claude Code names, then the session's directory, and outside a git work tree it has nothing to guard and says nothing.
-- A line the hook cannot read - an option no command has, an option left without its value, a `--format` or an `--at` that is none, two values for an option that takes one, `--help` beside `--version` - is said the same way: one line on stderr, exit 1, and no write held for it. Exit 2 from `hook claude` is for a write it could not check, never for what is wrong with its own line. `hook git` stops the commit on such a line, exit 2, where a person reads why.
+- A `--root` on the hook's line that is a file, or is not there, is a guard that was set up and is off: `hook claude` says so in one line to the person, as `systemMessage`, and exits 0, and the write goes on. It refuses nothing for it. No release wrote a `--root` there; without one the hook reads the project Claude Code names, then the session's directory, and outside a git work tree it has nothing to guard and says nothing.
+- A line the hook cannot read - an option no command has, an option left without its value, a `--format` or an `--at` that is none, two values for an option that takes one, `--help` beside `--version` - is said the same way: one line to the person, exit 0, and no write held for it. So is a question the hook cannot read, one that is not JSON or names no event. Exit 2 from `hook claude` is for a write it could not check, never for what is wrong with its own line; and no answer of the hook's is exit 1, which Claude Code counts as a hook that failed, so that `"onFailure": "block"` holds a write only for a hook that did not run ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md)). `hook git` stops the commit on such a line, exit 2, where a person reads why.
 
 A guard is a guardrail - an agent that writes through a shell passes it - so the audit and spec-brief's archive are the gates ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md)).
 
@@ -367,6 +376,8 @@ Run it in CI: exit 1 when a premise is stale, exit 2 when spec-guard is not ther
 
 `start_round`, `check_path`, `request_escalation`, `audit_round` and `list_rounds` over MCP on stdio, with the four workflow prompts. Both protocol eras are served. The architecture rules themselves stay with spec-guard's server.
 
+- The server is started for the project Claude Code names. `check_path` decides an absolute path by the work tree of the same repository that holds it, as the hook decides a write, and `start_round`, `check_path`, `request_escalation` and `audit_round` read the round, its branch and its brief, in one work tree: the one a `directory` argument names; else the one the client's roots name, where they name exactly one work tree of the repository, asked with `roots/list` where the client declared roots; else the project's. Each says which as `workTree`, and in its text where it is not the project's ([ADR-0008](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0008-one-server-for-rounds.md)).
+
 A tool answers an argument it cannot use with a tool error that names the argument, and writes nothing: one it does not take, one of the wrong type, and one that is given and [names nothing](#an-input-that-names-nothing), such as an empty `brief`.
 
 ### `init`
@@ -385,6 +396,7 @@ Configures the family to agree. It prints the plan, merges into files that exist
   - when it cannot tell, it says so and writes none: set `"base"` yourself.
 - **Claude Code**: the guard hooks in `.claude/settings.json` and the MCP server in `.mcp.json`, each run with `node` from the project's `node_modules`. The `npx` entries 0.1 wrote are replaced.
   - Beside the hook's entries under `PreToolUse` and `PostToolUse`, one under `SessionStart`, with no matcher: every way a session starts. In a file whose two an earlier release wrote, `init --write` adds it by itself; beside a line of the hook a person wrote or changed it adds none.
+  - With `--block-on-failure`, each of its entries before and after a write and as a session starts carries `"onFailure": "block"`, and so do those an earlier run wrote (`update`); the entry at the end of a turn, which runs in the background, is left without it, since the hooks reference gives the field no effect on a `Stop` hook or on one in the background. Claude Code 2.1.295 or later then holds a write where the hook cannot start, as where the project's install is not there, or runs past its timeout, where without the field it lets the write go ahead with a notice. Claude Code's documentation does not say what a release before 2.1.295 does with a key it does not know, and the file is read by every clone's Claude Code, so the field is written only where asked for: ask for it where every Claude Code that reads the file is 2.1.295 or later. The plugin's hooks do not carry it, and a line a person wrote is theirs to give it ([ADR-0012](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0012-one-way-into-claude-code.md)).
   - These are the ones the [Claude Code plugin](#as-a-claude-code-plugin) brings, so while that plugin is on - `"spec-harness@<marketplace>": true` under `enabledPlugins` in your user, project or local Claude Code settings - `init` writes neither and says why (`skip`).
   - To have its entries instead, which every clone reads, turn the Claude Code plugin off for the project, `claude plugin disable spec-harness@spec-tools --scope local`, and run `init` again.
   - It removes nothing: where the Claude Code plugin is on and a file already holds its entry, it says so (`advise`) and leaves the file alone. So where the hook stands in a settings file of your own, which `init` does not write.
@@ -415,7 +427,7 @@ The first thing to run when a hook refuses something unexpectedly. It reports:
   - In a linked worktree with no install of its own, the siblings are the main work tree's, as git's hook runs them there, and each such row says whose install it is: `(0.8.0, the install of /work/app: this work tree has none of its own)`. `--format json` has it as `elsewhere`, `null` for a sibling of the work tree's own.
 - **The repository**: its root, the branch, and the brief the flag, `SPEC_BRIEF` or the branch names.
   - A brief no round can work under is said on that line, with why: `brief   none: the flag names brief 999, and spec-brief knows no such brief`. So is one spec-brief has archived, an empty `--brief`, and a spec-brief that could not list the briefs. The guard holds every write while it stands, which is often why `doctor` is being run.
-  - It fails nothing, as a base that names no commit fails nothing: `doctor` exits as it would have. `--format json` has the id as `brief` and the reason as `briefProblem`, `null` where there is none.
+  - Where the branch names it, a brief spec-brief does not know or has archived, the hook holds every write on that branch, and `doctor` exits 1, as for a hook's line that holds every write: `brief   none: the branch names brief 999, and spec-brief knows no such brief`. One the flag or `SPEC_BRIEF` names fails nothing: the flag is the question `doctor` was asked, and the variable `doctor` reads is its own, which need not be the one Claude Code's hook is started with. Nor does a spec-brief that could not list the briefs, which is a sibling's row to judge. A base that names no commit fails nothing either. `--format json` has the id as `brief` and the reason as `briefProblem`, `null` where there is none ([ADR-0004](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0004-the-active-brief-is-named-not-guessed.md)).
 - **What a signed ruling needs to count**:
   - the base, and whether `--base`, `.spec-harness.json` or the remote named it;
   - whether the allowed-signers file is on that base;
@@ -426,11 +438,13 @@ The first thing to run when a hook refuses something unexpectedly. It reports:
   - A line OpenSSH refuses is named as no signer, with why. Its quotes are read as OpenSSH reads them: in the principals, the first double quote, wherever it opens, is taken out with the next, which ends the field; an option's value is always in double quotes, `\"` a quote inside it. And its options are OpenSSH's: `cert-authority`, `namespaces`, `valid-after` and `valid-before`, separated by commas.
 - **How Claude Code runs the guard**: the Claude Code plugin, with the settings file that turns it on; `init`'s hooks and server; both, which guards every write twice and exits 1, with how to keep one; or neither.
   - Where a settings file guards writes and none starts the hook as a session starts, a note says so and how to add it, `spec-harness init --write`, and fails nothing. `--format json` has `claudeCode.sessionStart`.
+  - Run in a linked worktree where something wires the guard, a note says which release of spec-harness the hook's line runs, where the main checkout's install and this work tree's are not one: the line names its script under `${CLAUDE_PROJECT_DIR}`, which is this work tree in a session started in it, and the main checkout in a worktree session of the desktop app, where by [Claude Code's worktrees page](https://code.claude.com/docs/en/worktrees) Claude Code reads the hooks from the main checkout's root and points the placeholder at it. Either decides a write by the work tree that holds it, from 0.19.0 on, so the note says which release answers, and fails nothing.
   - `"disableAllHooks": true` in a settings file switches the guard off: by [Claude Code's settings reference](https://code.claude.com/docs/en/settings-reference) it turns off the hooks of the user's, the project's and the local settings and of plugins. `doctor` reads the key from the three files as Claude Code merges them, the last that sets it deciding, names the file that holds it, and exits 1 where there are guard hooks for it to switch off. Where nothing is wired it is a note. Hooks of managed settings, and of a plugin managed settings force on, keep running; `doctor` reads no managed settings and no `--settings`.
   - A hook in Claude Code's settings is the guard by its command, `spec-harness` or its script, and the words `hook claude`, whatever else is on its line. `doctor` reads the line as the hook reads it, through the same code, with the project in place of `${CLAUDE_PROJECT_DIR}`, and says what the hook does with it.
   - Only an entry Claude Code runs as a command is a line of the hook, `"type": "command"`. An entry of another handler type (`http`, `mcp_tool`, `prompt`, `agent`) runs no command, whatever it holds, and is not reported. One with no `type`, or with a word the hooks reference does not list, is *cannot tell*, never fine: the reference requires the field and says nothing of an entry without it; `--strict` fails it.
   - A line that holds more than `init` writes, such as `--root ${CLAUDE_PROJECT_DIR}` or `--brief 012`, is said as it is and fails nothing: `"hook claude --root ${CLAUDE_PROJECT_DIR}" in .claude/settings.json is more than init writes, and guards: the hook reads the line, and its root, /work/app, is a directory`.
   - A line the hook cannot read, and a `--root` that is a file or is not there, are a guard that is off. Each is said in the words the hook itself says before a write, and exits 1.
+  - A line that asks for the help or the version, with `--help`, `--version`, `-h` or `-v`, is a guard that is off as well. The hook prints the help or the version, exit 0, in place of reading its question, and [Claude Code's hooks reference](https://code.claude.com/docs/en/hooks) has what a hook that exits 0 prints go to the debug log: no write is checked, and nothing says so. `doctor` says it and exits 1, whatever else is on the line: `"hook claude --help" in .claude/settings.json: the line asks for the help, which the hook prints, exit 0, in place of checking the write, so the guard is off and no write is checked`. Beside a `--root` that is a file or is not there, it is a line the hook cannot read, which the hook says before a write as it says the root without either.
   - A `--root` that is a directory outside any git work tree is a guard that is off as well, and the one fault the hook says nothing of: it reads a session outside a work tree there, checks no write, and exits 0. `doctor` asks git about the root as the hook does, says so, and exits 1: `"hook claude --root /elsewhere" in .claude/settings.json: --root is "/elsewhere", a directory outside any git work tree, which the hook reads as a session outside one, exit 0 and no word, so the guard is off and no write is checked`.
   - A `--root` in another git work tree than the project's is read by where that work tree is. The hook opens the work tree its root is in and decides by that work tree's briefs, and a file outside it is none of its repository's, which the hook passes with no word. So where that work tree does not hold the project - another repository beside it, or one inside it: a repository of its own, a submodule, a linked worktree - no write to a file of the project is checked. The guard is off, and `doctor` exits 1: `"hook claude --root ../other" in .claude/settings.json: --root is "../other", a directory in /work/other, the work tree of another repository, which does not hold this project: the hook checks a write to a file of that work tree, by its briefs, and passes any other with no word, exit 0, so the guard is off and no write to a file of this project is checked`. Where the work tree holds the project, as a repository the project is nested in does, or the main work tree around a linked one, a write here is checked, by that work tree's briefs and its branch and under the path the file has there: `doctor` says whose briefs they are and fails nothing. A work tree of the project's own repository, linked or main, is named `another work tree of this repository`, and is read by the same rule: a linked worktree beside the project holds none of its files.
   - A line that names a brief which is not one, as `--brief 404` does where spec-brief knows no brief 404 or has archived it, holds every write: the hook exits 2 before each until the line is mended. `doctor` asks spec-brief about the name as the hook does, in the work tree the line's root is in, says it in the words the hook holds the write with, and exits 1: `"hook claude --brief 404" in .claude/settings.json: the flag names brief 404, and spec-brief knows no such brief, so the hook holds every write until the line is mended: name a brief spec-brief lists, or take --brief off the line`.
@@ -443,7 +457,7 @@ The first thing to run when a hook refuses something unexpectedly. It reports:
     - A matcher of names with a hyphen in one, `Edit|Write|my-tool`, is read as the Claude Code on `PATH` reads it too. By [Claude Code's changelog](https://code.claude.com/docs/en/changelog), 2.1.195, such a matcher matched as a substring before that release and exactly from it on; the changelog does not say how the rest of it was read, the names it lists exactly, the matcher as a pattern, under which `Edit` is in `NotebookEdit` too, or its whole text, which is in no tool's name. So under 2.1.139 to 2.1.194, and where the release cannot be told, which writes the line is started for is *cannot tell* wherever those readings differ, never fine; `--strict` fails it: `(under PreToolUse it has the matcher "Edit|Write|my-tool", which Claude Code 2.1.194 may read otherwise: before 2.1.195 a matcher with a hyphenated name in it matched as a substring, and Claude Code's changelog does not say how the rest of it was read; from 2.1.195 on it is Edit and Write)`. A matcher whose readings all come to no tool that writes, `Bash|my-tool`, is no guard under any release, and nothing is said of the release.
     - A matcher that is an array, `["Edit", "Write"]`, is by the same page an entry Claude Code lists as an invalid setting, and no hook under it is started. Where one stands under `PreToolUse` or `PermissionRequest`, in an entry of the hook's or of any other program's, Claude Code loads none of that settings file's other hooks either. `doctor` says so of every line of the hook the file holds, and a line that stood to be started for a write is a guard that is off, exit 1: `"hook claude" in .claude/settings.json: .claude/settings.json has an array for a matcher under PreToolUse, ["Bash"], which Claude Code lists as an invalid setting, and beside one under PreToolUse or PermissionRequest it loads none of the file's other hooks, so the guard is off and no write is checked`. The hooks of another settings file are read as that file has them. Where such an array stands in the project's `.claude/settings.json`, the file `init` writes its hooks into, `doctor`'s advice is the array's first, since `init` writes no hook there while it stands, and then `init --write`. `--format json` has the array as `claudeCode.unloaded`, `null` where there is none.
   - A line with no `args` is one Claude Code hands to a shell. Where it holds a quote, a variable or anything else a shell rewrites after its command, what the hook is handed is *cannot tell*, never fine; `--strict` fails it. Written with `args`, each word reaches the hook as it stands, and `doctor` reads it.
-  - `"onFailure": "block"` on the hook's entry is said in a note. Claude Code 2.1.295 or later then holds a write when the hook fails, where without the field the write goes ahead: by the hook's exit 1 for a question it cannot read, by a hook that does not start, or by one that runs past its timeout. With a line that turns the guard off, that is every write, the one that mends the line among them.
+  - `"onFailure": "block"` on the hook's entry is said in a note. Claude Code 2.1.295 or later then holds a write when the hook fails, where without the field the write goes ahead: by a hook that does not start, or by one that runs past its timeout. The hook says each of its own answers with exit 0 or 2, a line that turns the guard off among them, so the field holds no write for those. Where the Claude Code on `PATH` is 2.1.295 or later and a line that guards sets no `onFailure`, a note advises it, with `init --write --block-on-failure` for `init`'s own entries, and fails nothing: every Claude Code that reads the file has to be one that reads the field.
   - `--format json` has each line under `claudeCode.lines`: its `file`, `events`, the `line` as written, its `state` (`guards`, `off`, `held`, `unstarted` or `unknown`), `onFailure`, the writing tools Claude Code waits on it `before` a write by and starts it `after` one by, of `Edit`, `Write` and `NotebookEdit` (`null` where that cannot be told), and what is said of it as `detail`, `cover` and `note`, `null` where there is nothing to say. Beside the lines, `claudeCode.presence` is whether the plugin is on this machine, `null` where no plugin is on and otherwise its `state` (`present`, `absent` or `unknown`) with the reason as `detail`; `claudeCode.hooksOff` is the settings file whose `disableAllHooks` is `true`, or `null`; and `claudeCode.notes` holds what is said of the two.
   - The plugin's own hooks are not read: they are a release's files, and every release wrote `hook claude` and no more on the line, under the matcher `init` writes. What is read is whether the plugin that settings turn on is on this machine, by [Claude Code's plugin loading reference](https://code.claude.com/docs/en/plugins/loading), from the directories Claude Code keeps plugins in: `plugins` in its configuration directory, or what `CLAUDE_CODE_PLUGIN_CACHE_DIR` names, and each directory `CLAUDE_CODE_PLUGIN_SEED_DIR` names.
     - *On the machine*: a version of it is in a cache, `cache/<marketplace>/spec-harness/<version>/`, which no `.orphaned_at` marks as left behind. Nothing more is said.
@@ -458,8 +472,8 @@ The first thing to run when a hook refuses something unexpectedly. It reports:
   - A hook that runs it through `npx` is one that runs it. A note names the line that runs it with `node`: `npx` starts npm to start node on every commit, and under npm 12 prints two `npm notice run` lines each time. A note, never a failure; `--format json` has it as `gitHook.note`.
   - What stands at the hook's path and is no file is no hook, and git takes it for one all the same. A directory there, which a repository whose `core.hooksPath` is in its work tree can hold, is one git tries to run where it may execute it, which on Windows is always: it cannot, and stops every commit, with `cannot spawn` on Windows and `cannot exec` elsewhere. `doctor` says the path, what it is and what git does with it, and exits 1, since nothing is checked there and nothing is committed: `.git/hooks/pre-commit is a directory, not a hook, and git stops every commit at it`. Where git may not execute it, it skips it as it skips a hook that is not executable: that is said, and fails nothing. `--format json` has the two as the `gitHook.state` `stops` and `ignored`. Only a file is read, so `doctor` and `init` come back from a named pipe there as well.
   - A hook file the account may not read is said with what git does with it, where `doctor` and `init` ended on a stack. Where git may not execute it either, it skips it with a hint and commits: said, and nothing fails. Where it may, git runs it, and a script the shell cannot read stops every commit, where a program runs unread: whether it runs spec-harness is *cannot tell*, never fine; `--strict` fails it. `--format json` has the `gitHook.state` `unreadable`.
-  - A `core.hooksPath` that names a file is one git names no hook under: it says `Invalid path ...: Not a directory`, and commits with no hook. `doctor` says that where git runs its hooks cannot be told, in git's own words, where it gave the reason it has for a git older than 2.31.
-- **What stands where a file is read.** A settings file, `.mcp.json` or a record of Claude Code's plugins that is neither a file nor a directory, such as a named pipe, is read as one that cannot be read as JSON, as a directory is: a pipe nothing writes to was read without end, and neither `doctor` nor `init` came back. `.spec-harness.json` that is neither stops every command, the hook among them, with `.spec-harness.json is neither a file nor a directory, not a configuration file`, exit 2, as one that is a directory does.
+  - A `core.hooksPath` that names a file is one git names no hook under: it says `Invalid path ...: Not a directory`, and commits with no hook. `doctor` says that where git runs its hooks cannot be told, in git's own words, where it gave the reason it has for a git older than 2.31. That is *cannot tell*, never fine; `--strict` fails it, where it failed nothing.
+- **What stands where a file is read.** A settings file, `.mcp.json` or a record of Claude Code's plugins that is neither a file nor a directory, such as a named pipe, is read as one that cannot be read as JSON, as a directory is: a pipe nothing writes to was read without end, and neither `doctor` nor `init` came back. `.spec-harness.json` that is neither stops every command, the hook among them, with `.spec-harness.json is neither a file nor a directory, not a configuration file`, exit 2, as one that is a directory does. One that cannot be read, which the account may not read or another process holds open on Windows, is said as that, with the reason: `.spec-harness.json cannot be read: EACCES: permission denied, open ...`, exit 2, where it was said to be JSON that is not valid. Every other file the harness reads is read only where it is a file, and what else stands there as a file that is not there: a document a brief cites, a sibling's `package.json`, what the run before a write kept, git's configuration and a worktree's `commondir` as the hook reads them, a request waiting for a ruling, and a probe's report, said as `neither a file nor a directory`.
 
 ### An input that names nothing
 
@@ -475,7 +489,7 @@ An option, an argument or a value that is given and names nothing is refused: ex
   | `premises` | `--brief`, `--root`, `--format`, `--strict` |
   | `escalate` | `--brief`, `--root`, `--format`, `--path`, `--reason`, `--option`, `--recommend`, `--list`, `--show` |
   | `rule` | `--root`, `--format`, `--allow`, `--deny`, `--note` |
-  | `init` | `--root`, `--format`, `--write`, `--git-hook` |
+  | `init` | `--root`, `--format`, `--write`, `--git-hook`, `--block-on-failure` |
   | `hook` | `--brief`, `--base`, `--root` |
   | `mcp` | `--root` |
 
@@ -485,19 +499,19 @@ An option, an argument or a value that is given and names nothing is refused: ex
 - **An argument a command does not take.** `context`, `rulings`, `audit` and `probe` take one brief's id at most, `rule` one escalation's id, `guard` its paths and `hook` the word `claude` or `git`; `escalate`, `premises`, `init`, `mcp` and `doctor` take none. `init mydir` set up the directory it stood in; `init --root mydir` sets up another.
 - **A value that names nothing.** An option that takes a value refuses one that is empty or only space, by the option's name: `--brief is "", which names no brief`. So does an argument, as in `guard ""`. No option gives an empty value a meaning: leave the option out for what the command does without it.
 - **A `--root` that is no directory**, a file or a path that is not there: `--root is "nowhere", which is not a directory`.
-- **An option that takes one value, given two.** `doctor --root nowhere --root .` ran in `.`, and `--brief 404 --brief 001` was brief 001: the parser kept the last, and the earlier went unread with no word. It is `--root is given twice, as "nowhere" and as ".", and one of the two would go unread; give it one`. Two values are compared as the option reads them, so the same thing given twice is the option once: `--root .` beside `--root ./`, a directory however it is spelt from where the command is started, and `--brief 12` beside `--brief 012`, a brief by its id as spec-brief's names are matched. A base, a format, an id and text are compared as written. `--path` and `--option` are lists, and each use adds to the list.
+- **An option that takes one value, given two.** `doctor --root nowhere --root .` ran in `.`, and `--brief 404 --brief 001` was brief 001: the parser kept the last, and the earlier went unread with no word. It is `--root is given twice, as "nowhere" and as ".", and one of the two would go unread; give it one`. Two values are compared as the option reads them, so the same thing given twice is the option once: `--root .` beside `--root ./`, a directory however it is spelt from where the command is started, a drive letter on Windows in either case (`--root C:\work` beside `--root c:\work`, which [spec-core's ADR-0005](https://github.com/DescentVTT/spec-core/blob/main/docs/adr/0005-the-family-contract.md) has every tool read as one: Windows names a volume by its letter in either case), and `--brief 12` beside `--brief 012`, a brief by its id as spec-brief's names are matched. A base, a format, an id and text are compared as written. `--path` and `--option` are lists, and each use adds to the list.
 - **A `.spec-harness.json` that is a directory** does not load, and is said so in a line, as one that is not JSON is.
 
 A line that is wrong is refused with `--help` or `--version` on it, each of the above and a command that is none, as an option no command has always was: `doctor --help --root a --root b` printed the help, exit 0. `--help` beside `--version` asks for two answers, of which one would go unread, and is refused: `--help is given beside --version, and one of the two answers would go unread; give one of them`. On a line that is right, either answers, a command that needs more than the line gives it among them, as `guard --help` does. Three things are read another way, each for its reason:
 
 - **`hook claude` reads its line as every release has.** The line is in `.claude/settings.json` and in the Claude Code plugin of every release since 0.1.0, which a later release cannot rewrite, and exit 2 from it holds every write of a session, the one that would mend the line among them. So what it does not read is passed over as before, an empty `--brief` with the rest. The releases have handed the harness five command lines, `hook claude`, `hook git`, `mcp`, and `mcp --root` with the project or with `.`, and each is read as the release that wrote it read it ([ADR-0012](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0012-one-way-into-claude-code.md)).
 
-  Two things on its line are said, and still refuse nothing. Each is one line on stderr and exit 1, said where there is a write the line leaves unchecked. Claude Code does not block a tool call on exit 1: it goes on with the write and shows the line as a hook error in the transcript. No release wrote more than `hook claude` on the hook's line, so either is a line a person changed.
+  Two things on its line are said, and still refuse nothing. Each is one line to the person, as `systemMessage`, and exit 0, said where there is a write the line leaves unchecked: Claude Code goes on with the write. It was exit 1, which Claude Code counts as a hook that failed, and under `"onFailure": "block"` that held every write of the session. No release wrote more than `hook claude` on the hook's line, so either is a line a person changed.
 
   - **A `--root` that is a file, or is not there.** It read as a session outside a git work tree, exit 0 and no word, and the guard was off. It is `--root is "nowhere", which is not a directory, so the guard is off and this write is not checked`, with what to do. An empty `--root` is the directory the hook was started in, and guards there, as before.
-  - **A line the parser cannot read**: an option no command has, as in `hook claude --nope`; an option left without its value, as `--root $DIR` is in a shell where the variable is not set; a `--format` or an `--at` that is none; two values for an option that takes one, whichever option it is, as in `hook claude --brief 001 --brief 404`, with `--help` beside them or not; `--help` beside `--version`. Each was exit 2, as it is from every other command, and Claude Code blocks the tool call on a PreToolUse hook's exit 2: every write of the session waited on a line only a write can mend. It is `the hook's line cannot be read (Option '--root <value>' argument missing), so the guard is off and this write is not checked`, with what to do. The parser's own words stand between the brackets, on one line.
+  - **A line the parser cannot read**: an option no command has, as in `hook claude --nope`; an option left without its value, as `--root $DIR` is in a shell where the variable is not set; a `--format` or an `--at` that is none; two values for an option that takes one, whichever option it is, as in `hook claude --brief 001 --brief 404`, with `--help` beside them or not; `--help` beside `--version`; and `--help` or `--version` beside a `--root` that is a file or is not there, which the hook said only as it ran, and printed the help over, exit 0. Each was exit 2, as it is from every other command, and Claude Code blocks the tool call on a PreToolUse hook's exit 2: every write of the session waited on a line only a write can mend. It is `the hook's line cannot be read (Option '--root <value>' argument missing), so the guard is off and this write is not checked`, with what to do. The parser's own words stand between the brackets, on one line.
 
-  Exit 2 from `hook claude` is kept for a write it could not check: a configuration that does not load, briefs that cannot be read, a brief that is named and is not one, an error nothing expected. `hook git` is not read this way. It stops one commit, exit 2, on a line a person reads, who can then mend the hook. Nor is a line that does not say `hook claude`, such as `hook` alone: the harness cannot tell whose it is. A hook entry that sets `"onFailure": "block"`, which Claude Code 2.1.295 and later read, has Claude Code hold the action when the hook fails, and exit 1 is a failure to it; neither `init` nor the plugin writes that field. [`doctor`](#doctor) says each of these of a line it finds in Claude Code's settings, before any write meets it.
+  Exit 2 from `hook claude` is kept for a write it could not check: a configuration that does not load, briefs that cannot be read, a brief that is named and is not one, an error nothing expected. `hook git` is not read this way. It stops one commit, exit 2, on a line a person reads, who can then mend the hook. Nor is a line that does not say `hook claude`, such as `hook` alone: the harness cannot tell whose it is. A hook entry that sets `"onFailure": "block"`, which Claude Code 2.1.295 and later read, has Claude Code hold the action when the hook fails: when it cannot start, runs past its timeout, or exits with a code other than 0 and 2, which no answer of the hook's is. `init --block-on-failure` writes the field; the plugin does not. [`doctor`](#doctor) says each of these of a line it finds in Claude Code's settings, before any write meets it.
 - **`doctor` says an empty `--brief` or `--base` in its report**, as it says a brief spec-brief does not know: a diagnosis is what a person runs when something is wrong, and it reports what is wrong with what it was given.
 - **`SPEC_BRIEF` set and empty is as unset**, since what sets it sets it whether or not there is a round ([Which brief](#which-brief)).
 
@@ -571,6 +585,7 @@ A person who runs the tools by hand runs `npx --no-install @descent-vtt/spec-har
 | `assertions.premises` | `The Defect, Measured`, `Premises`, `Preconditions` | Sections whose assertions state what was true before the round. |
 | `probes.runs`, `probes.timeout` | `2`, `600` | Runs per probe, and seconds per run. |
 | `tools` | found in `node_modules` | A sibling's command by name: `{ "spec-brief": ["node", "path/to/spec-brief.js"] }`. |
+| `turnReport` | `false` | `true`: as each of Claude Code's turns ends, the hook reports every changed path the brief protects or that is outside its scope, to Claude as the next turn begins ([`guard` and the hooks](#guard-path-and-the-hooks)). `init` writes the entry that runs it where it is on. |
 
 **Exit codes:**
 

package/dist/briefs.d.ts

@@ -19,6 +19,51 @@ export declare class SiblingOutputError extends Error {
 }
 /** Reads the document `spec-brief list --format json` prints. */
 export declare function parseBriefList(document: unknown): BriefRow[];
+/**
+ * A file a `list` answer was read from, by the SHA-256 of its bytes in hex;
+ * or `null` where spec-brief looked for it and found none, which is then to
+ * be found none again.
+ */
+export interface InputFile {
+    readonly path: string;
+    readonly sha256: string | null;
+}
+/**
+ * A directory whose files a `list` answer was read from, by their names:
+ * entries that are files, as spec-brief lists them; or `null` where
+ * spec-brief looked for the directory and found none, which is then to be
+ * found none again.
+ */
+export interface InputDirectory {
+    readonly path: string;
+    readonly entries: readonly string[] | null;
+}
+/**
+ * Everything a `list` answer was read from, as spec-brief lists it: its
+ * version, the files and directories it read, and what git read for it, the
+ * index and the ignore files, or `null` where it asked git nothing. A path
+ * is relative to the work tree and POSIX, or absolute where git names a
+ * file outside it (spec-core ADR-0005, amended 2026-10-19).
+ */
+export interface BriefInputs {
+    readonly tool: string;
+    readonly files: readonly InputFile[];
+    readonly directories: readonly InputDirectory[];
+    readonly git: {
+        readonly index: string | null;
+        readonly ignores: readonly InputFile[];
+    } | null;
+}
+/**
+ * What a `list` document says its answer was read from, where it may be
+ * given again; `null` where it lists nothing, where `keep` is anything but
+ * `true`, where it names nothing, and where anything on it is in a form not
+ * read here. Each is a doubt, and a doubt starts spec-brief as before
+ * (ADR-0002). The rows are `parseBriefList`'s to read, whatever this
+ * answers: a list this cannot read keeps an answer from being given again,
+ * and changes nothing of it.
+ */
+export declare function inputsOf(document: unknown): BriefInputs | null;
 /**
  * How the active brief was named, for messages. An argument is the id a
  * command takes after its name, or a tool call's `brief`: said to be the

package/dist/briefs.js

@@ -83,6 +83,79 @@ export function parseBriefList(document) {
         };
     });
 }
+const DIGEST = /^[0-9a-f]{64}$/;
+function inputPath(value) {
+    return typeof value === 'string' && value !== '';
+}
+function digestOf(value) {
+    return value === null || (typeof value === 'string' && DIGEST.test(value)) ? value : undefined;
+}
+function inputFiles(value) {
+    if (!Array.isArray(value))
+        return null;
+    const files = [];
+    for (const item of value) {
+        if (!isObject(item) || !inputPath(item['path']))
+            return null;
+        const sha256 = digestOf(item['sha256']);
+        if (sha256 === undefined)
+            return null;
+        files.push({ path: item['path'], sha256 });
+    }
+    return files;
+}
+function inputDirectories(value) {
+    if (!Array.isArray(value))
+        return null;
+    const directories = [];
+    for (const item of value) {
+        if (!isObject(item) || !inputPath(item['path']))
+            return null;
+        const entries = item['entries'];
+        // A name listed twice is a list that is not of one directory's files.
+        if (entries !== null && (!Array.isArray(entries) || !entries.every((entry) => typeof entry === 'string') || new Set(entries).size !== entries.length))
+            return null;
+        directories.push({ path: item['path'], entries });
+    }
+    return directories;
+}
+/**
+ * What a `list` document says its answer was read from, where it may be
+ * given again; `null` where it lists nothing, where `keep` is anything but
+ * `true`, where it names nothing, and where anything on it is in a form not
+ * read here. Each is a doubt, and a doubt starts spec-brief as before
+ * (ADR-0002). The rows are `parseBriefList`'s to read, whatever this
+ * answers: a list this cannot read keeps an answer from being given again,
+ * and changes nothing of it.
+ */
+export function inputsOf(document) {
+    if (!isObject(document))
+        return null;
+    const inputs = document['inputs'];
+    if (!isObject(inputs) || inputs['keep'] !== true || typeof inputs['tool'] !== 'string')
+        return null;
+    const files = inputFiles(inputs['files']);
+    const directories = inputDirectories(inputs['directories']);
+    const git = inputs['git'];
+    let asked;
+    if (git === null) {
+        asked = null;
+    }
+    else {
+        if (!isObject(git))
+            return null;
+        const index = digestOf(git['index']);
+        const ignores = inputFiles(git['ignores']);
+        if (index === undefined || ignores === null)
+            return null;
+        asked = { index, ignores };
+    }
+    // A list that names nothing is an answer that cannot be told from one that
+    // was read from nowhere.
+    if (files === null || directories === null || files.length + directories.length === 0)
+        return null;
+    return { tool: inputs['tool'], files, directories, git: asked };
+}
 /**
  * The brief a round is working on: named by an argument, by a flag, by
  * `SPEC_BRIEF`, or by the branch - never guessed from which brief happens to