@descent-vtt/spec-harness 0.19.0 → 0.21.0

package/dist/configure.js

@@ -9,7 +9,7 @@
  */
 import { isAbsolute, join } from 'node:path';
 import { runInNewContext } from 'node:vm';
-import { CALLABLE_TOOLS } from './hooks.js';
+import { CALLABLE_TOOLS, HOOK_BUDGET_MS } from './hooks.js';
 import { literal } from './literal.js';
 import { namedTree } from './usage.js';
 import { parseGlobList } from './vendor/spec-core/pattern/index.js';
@@ -58,12 +58,28 @@ const GUARDED_EVENTS = [BEFORE, AFTER];
  * left out, it is every way a session starts.
  */
 const AT_START = 'SessionStart';
+/**
+ * The event Claude Code runs as its main agent finishes a turn, under which
+ * the hook reports what the work tree holds where `turnReport` is on
+ * (ADR-0005). Its entry has no matcher: the event takes none.
+ */
+const AT_TURN_END = 'Stop';
 const GUARD_ARGS = Object.freeze([`${PROJECT_DIR}/${BIN}`, 'hook', 'claude']);
 /**
  * The guard as a Claude Code hook: exec form, `args` given, so the project's
  * path is one argument whatever it holds, and no shell is involved.
  */
 export const GUARD_HOOK = Object.freeze({ type: 'command', command: 'node', args: GUARD_ARGS, timeout: 60 });
+/**
+ * The hook's entry at the end of a turn: the guard's line, run in the
+ * background. Claude Code waits on no part of it, so the turn ends as it
+ * would, and it hands the hook's `systemMessage` to Claude as the next
+ * turn begins, where from an entry it waits on it shows the person the
+ * message instead (the hooks reference,
+ * https://code.claude.com/docs/en/hooks, *Run hooks in the background* and
+ * *JSON output*, read 2026-10-19).
+ */
+export const TURN_HOOK = Object.freeze({ ...GUARD_HOOK, async: true });
 // bare-name: what 0.1 installed, an npx command found from wherever the
 // session stood. Read here so that init replaces it, and never run.
 const LEGACY_HOOK = 'npx --no-install spec-harness hook claude';
@@ -331,6 +347,34 @@ export function withSessionStart(settings, isHook) {
     const listed = hooks[AT_START];
     return { ...settings, hooks: { ...hooks, [AT_START]: [...(Array.isArray(listed) ? listed : []), { hooks: [{ ...GUARD_HOOK, args: [...GUARD_ARGS] }] }] } };
 }
+/** The events init writes its own line under. */
+const INIT_EVENTS = [BEFORE, AFTER, AT_START];
+/**
+ * Settings with `onFailure: "block"` on each of init's own entries, under
+ * the three events it writes them under, or `null` where each has it
+ * already: `init --block-on-failure`. Claude Code's hooks reference
+ * (https://code.claude.com/docs/en/hooks, Block the action when a hook
+ * fails, read 2026-10-19) has the field read by Claude Code 2.1.295 and
+ * later, and a failure under it, a hook that cannot start or that reaches
+ * its timeout among them, do what exit 2 does on its event: before a write,
+ * hold it. What a release before 2.1.295 does with the key is on no page, so
+ * init writes it only where it is asked to (ADR-0012). An entry a person
+ * wrote is theirs, and is left as it is.
+ */
+export function withOnFailure(settings) {
+    const hooks = isObject(settings['hooks']) ? settings['hooks'] : {};
+    const unblocked = (hook) => isGuard(hook) && hook['onFailure'] !== 'block';
+    const next = { ...hooks };
+    let changed = false;
+    for (const event of INIT_EVENTS) {
+        const groups = hooks[event];
+        if (!Array.isArray(groups) || !groups.some((group) => hooksOf(group).some(unblocked)))
+            continue;
+        next[event] = groups.map((group) => (hooksOf(group).some(unblocked) ? { ...group, hooks: hooksOf(group).map((hook) => (unblocked(hook) ? { ...hook, onFailure: 'block' } : hook)) } : group));
+        changed = true;
+    }
+    return changed ? { ...settings, hooks: next } : null;
+}
 /**
  * Whether settings have Claude Code start the hook as a session starts: an
  * entry under `SessionStart` whose line is init's, or one `isHook` knows
@@ -343,6 +387,25 @@ export function startsSessions(settings, isHook) {
         return false;
     return groups.some((group) => hooksOf(group).some((hook) => isObject(hook) && (isGuard(hook) || knownAs(hook, isHook))));
 }
+/**
+ * Settings with init's entry under `Stop` added, or `null` where a line
+ * of the hook stands there already, init's or one `isHook` knows, which
+ * would report the turn twice (ADR-0012).
+ */
+export function withTurnReport(settings, isHook) {
+    if (reportsTurns(settings, isHook))
+        return null;
+    const hooks = isObject(settings['hooks']) ? settings['hooks'] : {};
+    const listed = hooks[AT_TURN_END];
+    return { ...settings, hooks: { ...hooks, [AT_TURN_END]: [...(Array.isArray(listed) ? listed : []), { hooks: [{ ...TURN_HOOK, args: [...GUARD_ARGS] }] }] } };
+}
+/** Whether settings have Claude Code start the hook as a turn ends: an entry under `Stop` whose line is init's, or one `isHook` knows as the hook's. */
+export function reportsTurns(settings, isHook) {
+    const groups = field(field(settings, 'hooks'), AT_TURN_END);
+    if (!Array.isArray(groups))
+        return false;
+    return groups.some((group) => hooksOf(group).some((hook) => isObject(hook) && (isGuard(hook) || knownAs(hook, isHook))));
+}
 /** Whether `isHook` knows an entry's line as the hook's. */
 function knownAs(hook, isHook) {
     const written = writtenHook(hook);
@@ -354,6 +417,30 @@ function knownAs(hook, isHook) {
  * which it holds, and not as the session starts.
  */
 export const NO_SESSION_START = 'note: no settings file has Claude Code start the hook as a session starts, so a configuration that does not load, or a brief named that spec-brief does not list, is said only at the first write, which it holds: spec-harness init --write adds the entry beside the two it wrote';
+/**
+ * What doctor notes where `turnReport` is on and no settings file has Claude
+ * Code start the hook as a turn ends: the report the configuration asks for
+ * is made at no turn's end. The plugin brings no entry for it (ADR-0012).
+ */
+export const NO_TURN_END = `note: "turnReport" is on, and no settings file has Claude Code start the hook as a turn ends, so no turn's end is reported: spec-harness init --write adds the entry beside init's, and says where it goes where the plugin brings the guard hooks`;
+/**
+ * What doctor notes, run in a linked worktree, of the spec-harness the
+ * hook's line runs: the one installed where `${CLAUDE_PROJECT_DIR}` points,
+ * which is this work tree in a session started in it, and the main
+ * checkout in a worktree session of the desktop app's, where Claude Code
+ * reads the hooks from the main checkout's root and points the placeholder
+ * at it (its worktrees page, What worktrees share with the main checkout,
+ * read 2026-10-19). Said where the two are not one release, `null` for
+ * none, and `null` where they are. A note: from 0.19.0 on either decides a
+ * write by the work tree that holds it, so it says which release answers,
+ * not where a write is decided.
+ */
+export function describeInstalls(main, there, here) {
+    if (there === here)
+        return null;
+    const release = (version) => (version === null ? 'none' : version);
+    return `note: this is a linked worktree of ${main}, and the hook's line runs the spec-harness installed where \${CLAUDE_PROJECT_DIR} points: this work tree's, ${release(here)}, in a session started here, and ${main}'s, ${release(there)}, in one started there, as a worktree session of the desktop app is`;
+}
 /** The server's entry, reading the project at `projectDir`: {@link PROJECT_DIR} for the plugin, {@link PROJECT_DIR_OR_HERE} for a project. */
 export function mcpServer(projectDir) {
     return { command: 'node', args: [`${projectDir}/${BIN}`, 'mcp', '--root', projectDir] };
@@ -421,7 +508,7 @@ function writtenHook(hook) {
         return null;
     const words = line.slice(at + 1);
     const untyped = type === 'command' ? null : type === undefined ? 'no "type"' : `the "type" ${JSON.stringify(type)}`;
-    return { words, shell: shell && words.some((word) => SHELL_READS.test(word)), blocks: hook['onFailure'] === 'block', untyped };
+    return { words, shell: shell && words.some((word) => SHELL_READS.test(word)), blocks: hook['onFailure'] === 'block', untyped, launcher: { word: line[at], shell } };
 }
 /**
  * Every line in Claude Code's settings that runs the harness, under the two
@@ -432,17 +519,37 @@ function writtenHook(hook) {
  */
 export function writtenHooks(settings) {
     const found = [];
-    for (const { event, words, shell, blocks, untyped } of harnessEntries(settings)) {
-        const same = found.find((other) => sameLine(other, { words, shell, blocks, untyped }));
+    for (const { event, words, shell, blocks, untyped, launcher } of harnessEntries(settings)) {
+        const same = found.find((other) => sameLine(other, { words, shell, blocks, untyped, launcher }));
         if (same === undefined)
-            found.push({ events: [event], words, shell, blocks, untyped });
+            found.push({ events: [event], words, shell, blocks, untyped, launcher });
         else if (!same.events.includes(event))
             same.events.push(event);
     }
     return found;
 }
 function sameLine(one, other) {
-    return one.shell === other.shell && one.blocks === other.blocks && one.untyped === other.untyped && sameStrings(one.words, other.words);
+    // `shell` is not compared: it follows from whether a shell reads the
+    // launcher and from the words after it, which are.
+    return (one.blocks === other.blocks &&
+        one.untyped === other.untyped &&
+        one.launcher.word === other.launcher.word &&
+        one.launcher.shell === other.launcher.shell &&
+        sameStrings(one.words, other.words));
+}
+/**
+ * What is said of the script a line runs where it is in none of the places
+ * it can name, `null` where it is in one, and `null` where that cannot be
+ * told here: a relative path, which is read from wherever the session
+ * stands as the hook starts, a name a program finds by itself (npx's
+ * package, a command on `PATH`), and a word a shell reads before it runs
+ * anything.
+ */
+function absentScript(launcher, places) {
+    const paths = [...new Set(places.projects.map((project) => launcher.word.split(PROJECT_DIR).join(project)))];
+    if (paths.some((path) => (launcher.shell && SHELL_READS.test(path)) || !isAbsolute(path) || places.isFile(path)))
+        return null;
+    return paths.length === 1 ? `the script it runs, ${paths[0]}, is not there` : `the script it runs is in neither place \${CLAUDE_PROJECT_DIR} can name, ${paths.join(' or ')}`;
 }
 /**
  * The writing tools whose call an entry is handed and waited on for, or
@@ -477,17 +584,58 @@ export function isStarted(tools) {
 }
 /**
  * The release of Claude Code that reads `onFailure` on a hook's entry, by its
- * hooks reference (https://code.claude.com/docs/en/hooks, read 2026-10-12).
+ * hooks reference (https://code.claude.com/docs/en/hooks, Command hook
+ * fields, read 2026-10-19) and its changelog, which adds the field under it.
+ */
+export const ON_FAILURE_SINCE = '2.1.295';
+/** Whether the Claude Code doctor asked its release reads `onFailure`: one that was told, at {@link ON_FAILURE_SINCE} or later. */
+export function readsOnFailure(release) {
+    // A release that was told is one whose version was read as one, and the
+    // constant is a version, so both parse.
+    return release !== null && release.state !== 'unknown' && meets(parseVersion(release.version), parseVersion(ON_FAILURE_SINCE));
+}
+/**
+ * What `onFailure: "block"` changes for a line, named by `where` it stands,
+ * or `null` where the entry does not set it. The hook fails for none of its
+ * own answers, a line of its own that turns the guard off among them, which
+ * it says with exit 0 (ADR-0005): what the field holds is a hook that does
+ * not run.
  */
-const ON_FAILURE_SINCE = '2.1.295';
-/** What `onFailure: "block"` changes for a line, named by `where` it stands, or `null` where the entry does not set it. */
-function describeOnFailure(where, blocks, off) {
+function describeOnFailure(where, blocks) {
     if (!blocks)
         return null;
-    const holds = `${where} sets onFailure to "block", so Claude Code ${ON_FAILURE_SINCE} or later holds a write when the hook fails`;
-    if (off)
-        return `${holds}, which with this line is every write, the one that mends the line among them: mend it by hand`;
-    return `${holds}, where it lets the write go ahead without it: by its exit 1 for a question it cannot read, by not starting, or by running past its timeout`;
+    return `${where} sets onFailure to "block", so Claude Code ${ON_FAILURE_SINCE} or later holds a write when the hook fails, where it lets the write go ahead without it: by not starting, as where the script on its line is not there, or by running past its timeout`;
+}
+/**
+ * What is said of a line whose entries give the hook less time than a run
+ * of it is given ({@link HOOK_BUDGET_MS}), or `null`. Claude Code's hooks
+ * reference (Timeouts, read 2026-10-24) has a command hook cancelled at its
+ * entry's `timeout`, and a PreToolUse hook it cancels blocks no tool call:
+ * a run that needs its budget, which holds the write at the end of it, is
+ * cut short there, and the write goes ahead. A note, which fails nothing:
+ * the timeout is the person's. One that is no number is not read.
+ */
+function describeTimeout(where, entries) {
+    const short = entries.flatMap((entry) => {
+        const seconds = entry.hook['timeout'];
+        return typeof seconds === 'number' && seconds * 1000 < HOOK_BUDGET_MS ? [`${seconds} seconds under ${entry.event}`] : [];
+    });
+    if (short.length === 0)
+        return null;
+    return `${where} gives the hook ${named(short)}, less than the ${HOOK_BUDGET_MS / 1000} a run of it is given, so Claude Code cancels a run that takes longer before it answers, and a write it would have held goes ahead: give the entry 60, as init writes it, or no timeout`;
+}
+/**
+ * What is said of a line that guards and whose entries set no `onFailure`,
+ * where the Claude Code here reads the field: a hook that cannot start lets
+ * the write go ahead, and the field would hold it. Advice, which fails
+ * nothing: the file is read by every clone's Claude Code, and what a release
+ * before {@link ON_FAILURE_SINCE} does with the key is on no page. `own` is
+ * whether the entries are init's, in the file init writes, which
+ * `init --block-on-failure` gives the field.
+ */
+function adviseOnFailure(where, own) {
+    const how = own ? 'spec-harness init --write --block-on-failure writes it on these entries' : 'it is written on each of its entries';
+    return `${where} sets no onFailure, so Claude Code lets a write go ahead where the hook cannot start, as where the script on its line is not there, or runs past its timeout: where every Claude Code that reads the file is ${ON_FAILURE_SINCE} or later, as the one here is, "onFailure": "block" holds the write instead, and ${how}`;
 }
 /** Names as a sentence lists them: one, two with "and", more with commas before it. Never asked of none. */
 function named(names) {
@@ -637,8 +785,14 @@ export function handedLines(sources, project) {
  * `PermissionRequest` has none of its hooks loaded ({@link arrayMatcher}):
  * each line of the hook there is started for no write, and one that stood
  * to be started for a write is a guard that is off.
+ *
+ * `scripts` is where a caller that says whether the script a line runs is
+ * there looks for it; with none it is not asked. A line whose script is
+ * not there is a hook Claude Code cannot start, which it lets each write
+ * go ahead without, or holds every write for where the entry sets
+ * `onFailure` to `"block"` and the release here reads it.
  */
-export function reportHooks(sources, project, read, pattern = patternReader(), matching = TODAY) {
+export function reportHooks(sources, project, read, pattern = patternReader(), matching = TODAY, onFailureHere = false, scripts = null) {
     const reading = { pattern, matching };
     return sources.flatMap(({ file, settings }) => {
         const entries = harnessEntries(settings);
@@ -661,15 +815,18 @@ export function reportHooks(sources, project, read, pattern = patternReader(), m
                 // someone meant a matcher, is a guard set up that checks nothing;
                 // one that stood to be started for none leaves no write unchecked
                 // that it was ever asked about.
-                const unloaded = { file, events: hook.events, line: hook.words, onFailure: hook.blocks ? 'block' : null, before: [], after: [], cover: null, note: null };
+                const unloaded = { file, events: hook.events, line: hook.words, onFailure: hook.blocks ? 'block' : null, before: [], after: [], cover: null, note: null, timeout: null };
                 const said = `${where}: ${describeArrayMatcher(file, array)}`;
                 if (isStarted(before) || isStarted(after) || mine.some((entry) => Array.isArray(entry.matcher))) {
                     return [{ ...unloaded, state: 'off', detail: `${said}, so the guard is off and no write is checked; ${ONE_STRING}` }];
                 }
                 return [{ ...unloaded, state: 'unstarted', detail: `${said}: the line is not started, and stood to be started for no write as it is, so no guard is switched off` }];
             }
-            const written = { file, events: hook.events, line: hook.words, onFailure: hook.blocks ? 'block' : null, before, after, cover: describeCover(where, before, after, mine, reading) };
-            const note = describeOnFailure(where, hook.blocks, false);
+            const written = { file, events: hook.events, line: hook.words, onFailure: hook.blocks ? 'block' : null, before, after, cover: describeCover(where, before, after, mine, reading), timeout: describeTimeout(where, mine) };
+            const note = describeOnFailure(where, hook.blocks);
+            // Where the release here reads the field, a line that guards without it is advised it.
+            const own = file === PROJECT_SETTINGS && mine.every((entry) => isGuard(entry.hook));
+            const guards = (detail) => ({ ...written, state: 'guards', detail, note: note ?? (onFailureHere ? adviseOnFailure(where, own) : null) });
             if (hook.untyped !== null) {
                 const detail = `${where} stands on an entry with ${hook.untyped}, where Claude Code's hooks reference has "type": "command" on an entry it runs as a command, so whether Claude Code runs it cannot be told here: give the entry "type": "command"`;
                 return [{ ...written, state: 'unknown', detail, note }];
@@ -681,17 +838,30 @@ export function reportHooks(sources, project, read, pattern = patternReader(), m
             // What the hook would do with a line it is never asked on before a write is not what guards.
             const unstarted = { ...written, state: 'unstarted', detail: null, note };
             const waited = before === null || before.length > 0;
+            // Whatever the hook would do with the words, it never reads them where
+            // its script is not there. By the hooks reference
+            // (https://code.claude.com/docs/en/hooks, Block the action when a hook
+            // fails, read 2026-10-24) a command hook that cannot start, as where
+            // its script does not exist, has failed, and the action goes ahead
+            // unless the entry sets onFailure to "block", which holds it.
+            const absent = scripts === null ? null : absentScript(hook.launcher, scripts);
+            if (absent !== null) {
+                if (!waited && !isStarted(after))
+                    return [unstarted];
+                const mend = 'install spec-harness in the project, npm install --save-dev @descent-vtt/spec-harness, or name its script where it is';
+                if (hook.blocks && onFailureHere && waited) {
+                    return [{ ...written, state: 'held', detail: `${where}: ${absent}, so the hook cannot start, and Claude Code holds every write it is started for before, since the entry sets onFailure to "block"; ${mend}`, note }];
+                }
+                return [{ ...written, state: 'off', detail: `${where}: ${absent}, so the hook cannot start, the guard is off and Claude Code lets each write it is started for go ahead without it; ${mend}`, note }];
+            }
             if (handed.state === 'off') {
                 const detail = `${where}: ${handed.fault.wrong}, so the guard is off and ${handed.unchecked ?? 'no write is checked'}; ${handed.fault.mend}`;
-                // A fault the hook says, it says with exit 1 after every write it is
-                // started for as well, so it is said wherever the line stands.
-                if (handed.silent !== true)
-                    return [{ ...written, state: 'off', detail, note: describeOnFailure(where, hook.blocks, true) }];
-                // A root outside any work tree, or in one that does not hold the
-                // project, of which the hook says nothing: no run of it fails
-                // there, so onFailure holds no write for it, and where the line is
-                // waited on before no write there is none it leaves unchecked.
-                return [waited ? { ...written, state: 'off', detail, note } : unstarted];
+                // A fault the hook says, it says after every write it is started for
+                // as well, so it is said wherever the line stands. A root outside
+                // any work tree, or in one that does not hold the project, it says
+                // nothing of, and where the line is waited on before no write there
+                // is none it leaves unchecked.
+                return [handed.silent !== true || waited ? { ...written, state: 'off', detail, note } : unstarted];
             }
             if (!waited)
                 return [unstarted];
@@ -703,11 +873,11 @@ export function reportHooks(sources, project, read, pattern = patternReader(), m
                 return [{ ...written, state: 'unknown', detail: null, note }];
             // What a release wrote: its hook, and nothing after it.
             if (sameStrings(hook.words, ['hook', 'claude']))
-                return [{ ...written, state: 'guards', detail: null, note }];
+                return [guards(null)];
             const root = handed.root === undefined ? '' : `, and its root, ${handed.root}, is a directory`;
             // Whose briefs a write is checked by, where they are not the project's own.
             const holder = handed.holder === undefined ? '' : ` in ${namedTree(handed.holder)}, which holds this project: the hook checks a write here by that work tree's briefs and its branch, as a file under ${handed.holder.path}/ there`;
-            return [{ ...written, state: 'guards', detail: `${where} is more than init writes, and guards: the hook reads the line${root}${holder}`, note }];
+            return [guards(`${where} is more than init writes, and guards: the hook reads the line${root}${holder}`)];
         });
     });
 }
@@ -936,7 +1106,11 @@ export function wiringState(wiring) {
  * checks no write.
  */
 export function guardSwitchedOff(wiring) {
-    return wiring.hooksOff !== null && (wiring.hooks.length > 0 || (wiring.plugin !== null && absence(wiring) === null));
+    return wiring.hooksOff !== null && guardWired(wiring);
+}
+/** Whether something brings the guard hooks: a settings file that holds them, or a plugin settings turn on that may be on this machine. */
+export function guardWired(wiring) {
+    return wiring.hooks.length > 0 || (wiring.plugin !== null && absence(wiring) === null);
 }
 /**
  * What doctor and init say of `disableAllHooks` in `file`. `guarded` is