@descent-vtt/spec-harness 0.20.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';
@@ -417,6 +417,12 @@ 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,
@@ -502,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
@@ -513,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
@@ -580,6 +606,24 @@ function describeOnFailure(where, blocks) {
         return null;
     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
@@ -741,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, onFailureHere = false) {
+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);
@@ -765,14 +815,14 @@ 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 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));
@@ -788,6 +838,22 @@ 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 after every write it is started for