@descent-vtt/spec-harness 0.16.0 → 0.18.0

package/dist/configure.js

@@ -7,12 +7,13 @@
  * Each merge keeps what a person wrote and returns `null` when there is
  * nothing to add.
  */
-import { isAbsolute } from 'node:path';
+import { isAbsolute, join } from 'node:path';
 import { runInNewContext } from 'node:vm';
-import { WRITING_TOOLS } from './hooks.js';
+import { CALLABLE_TOOLS } from './hooks.js';
 import { literal } from './literal.js';
+import { namedTree } from './usage.js';
 import { parseGlobList } from './vendor/spec-core/pattern/index.js';
-import { CLAUDE_CODE_MINIMUM } from './versions.js';
+import { CLAUDE_CODE_MINIMUM, meets, parseVersion } from './versions.js';
 function isObject(value) {
     return typeof value === 'object' && value !== null;
 }
@@ -37,6 +38,14 @@ export const PROJECT_DIR = '${CLAUDE_PROJECT_DIR}';
  * default; `.` is right, since a project's server starts in the project.
  */
 export const PROJECT_DIR_OR_HERE = '${CLAUDE_PROJECT_DIR:-.}';
+/**
+ * The matcher every release wrote: each name the hook reads a file from
+ * (hooks.ts). `MultiEdit` is one no supported Claude Code has a tool for,
+ * and Claude Code compares a listed name with a tool's exactly, so it starts
+ * the hook for nothing there. It stays, since the hook is asked about a name
+ * only under a matcher that lets the name through, and it reads this one for
+ * whatever still sends it.
+ */
 const HOOK_MATCHER = 'Edit|Write|MultiEdit|NotebookEdit';
 /** The event Claude Code runs before a tool call, the only one of the two where a hook can refuse the call. */
 const BEFORE = 'PreToolUse';
@@ -70,26 +79,80 @@ function upgraded(group) {
     return { ...group, hooks: hooks.map((hook) => (isLegacyGuard(hook) ? { ...hook, command: 'node', args: [...GUARD_ARGS] } : hook)) };
 }
 /**
- * The tools, of those that write a file, that a group's matcher has Claude
- * Code start the group's hooks for, by its hooks reference
+ * The tools, of those that write a file and a supported Claude Code can call
+ * (hooks.ts), that a group's matcher has Claude Code start the group's hooks
+ * for, by its hooks reference
  * (https://code.claude.com/docs/en/hooks, Matcher patterns, read
  * 2026-10-12): left out, empty or `*`, every tool; made of letters, digits,
  * `_`, `-`, spaces, `,` and `|` alone, the tools it names, one between each
  * `|` or `,`; with any other character in it, a JavaScript regular
  * expression that may match anywhere in a tool's name. `null` where the
- * reference does not say, or it cannot be told: a matcher that is not text,
- * is no pattern, or is a pattern whose reading runs out its budget.
+ * reference does not say, or it cannot be told: a matcher that is neither
+ * text nor an array, is no pattern, or is a pattern whose reading runs out
+ * its budget.
+ *
+ * Two things its page on debugging a configuration adds
+ * (https://code.claude.com/docs/en/debug-your-config, Check hooks and Check
+ * common causes, read 2026-10-14). A matcher that is an array is an entry
+ * Claude Code lists as an invalid setting, among the reasons a hook is not
+ * loaded and never fires: no tool. And a comma separates names only from
+ * {@link COMMA_SINCE} on, so a matcher that lists names with one is read as
+ * `commas` has the Claude Code here read it.
  */
-function matchedTools(matcher) {
+function matchedTools(matcher, pattern, commas) {
     if (matcher === undefined || matcher === '' || matcher === '*')
-        return WRITING_TOOLS;
+        return CALLABLE_TOOLS;
+    if (Array.isArray(matcher))
+        return [];
     if (typeof matcher !== 'string')
         return null;
-    if (/^[A-Za-z0-9_\- ,|]*$/.test(matcher)) {
-        const names = matcher.split(/[|,]/).map((name) => name.trim());
-        return WRITING_TOOLS.filter((tool) => names.includes(tool));
-    }
-    return patternTools(matcher);
+    if (!NAMES.test(matcher))
+        return pattern(matcher);
+    const comma = commas.as === 'separator' ? null : commaReading(matcher, pattern);
+    if (comma === null)
+        return listedTools(matcher);
+    if (commas.as === 'pattern')
+        return comma.earlier;
+    // Which of the two readings holds cannot be told, and where both are no
+    // tool that writes it need not be.
+    return comma.earlier !== null && comma.listed.length === 0 ? comma.listed : null;
+}
+/** A matcher that is a name, or names between `|` and `,`: what the reference compares with a tool's name exactly. */
+const NAMES = /^[A-Za-z0-9_\- ,|]*$/;
+/** The writing tools a matcher of names lists, one between each `|` or `,`. */
+function listedTools(matcher) {
+    const names = matcher.split(/[|,]/).map((name) => name.trim());
+    return CALLABLE_TOOLS.filter((tool) => names.includes(tool));
+}
+/**
+ * The release of Claude Code from which a comma in a matcher separates
+ * names as a `|` does. Its page on debugging a configuration (Check hooks,
+ * read 2026-10-14) has a comma before it fall through to the reading of a
+ * pattern, under which the matcher never matched, and its changelog has the
+ * fix under this release: hooks with comma-separated matchers no longer
+ * silently never firing.
+ */
+export const COMMA_SINCE = '2.1.191';
+/** The reading every release from {@link COMMA_SINCE} on has, and what a caller that asks no release is given. */
+const SEPARATOR = { as: 'separator' };
+/**
+ * How the Claude Code doctor asked its release reads a comma. A release that
+ * was not asked, or could not be told, leaves the reading untold: asked or
+ * not, nothing says which it is.
+ */
+export function commasUnder(release) {
+    if (release === null || release.state === 'unknown')
+        return { as: 'untold' };
+    // A release that was told is one whose version was read as one, and the
+    // constant is a version, so both parse.
+    return meets(parseVersion(release.version), parseVersion(COMMA_SINCE)) ? SEPARATOR : { as: 'pattern', release: release.version };
+}
+/** The two readings of a matcher of names that holds a comma, or `null` for any other matcher, which every release reads one way. */
+function commaReading(matcher, pattern) {
+    if (typeof matcher !== 'string' || !NAMES.test(matcher) || !matcher.includes(','))
+        return null;
+    const read = pattern(matcher);
+    return { listed: listedTools(matcher), earlier: read !== null && read.length === 0 ? read : null };
 }
 /**
  * How long the reading of one pattern may take, in milliseconds of the
@@ -104,7 +167,7 @@ const PATTERN_BUDGET = 100;
  * is no pattern, or its reading runs out its budget.
  *
  * The pattern is a line of a settings file, which arrives with a clone, and
- * one can be written that a test of four short names never finishes:
+ * one can be written that a test of a few short names never finishes:
  * `^((((([A-Za-z]*)*)*)*)*)*$X` ran for more than ten seconds. Tested as
  * written, one such entry and neither doctor nor init would come back, with
  * no word. So it is made and tested in a context of its own, whose run
@@ -115,13 +178,39 @@ const PATTERN_BUDGET = 100;
  */
 function patternTools(source) {
     try {
-        const matched = runInNewContext('tools.filter((tool) => new RegExp(source).test(tool))', { tools: WRITING_TOOLS, source }, { timeout: PATTERN_BUDGET });
+        const matched = runInNewContext('tools.filter((tool) => new RegExp(source).test(tool))', { tools: CALLABLE_TOOLS, source }, { timeout: PATTERN_BUDGET });
         return matched;
     }
     catch {
         return null;
     }
 }
+/**
+ * A reader for one run: a pattern is read the first time it is asked of,
+ * and answered from that reading after.
+ *
+ * A reading that runs out its budget costs the whole of it, a settings file
+ * can hold one matcher over any number of entries, and init asks of an
+ * entry twice, for what doctor says of the file and for what to write into
+ * it. Fifty entries under one such pattern were fifty readings, five and a
+ * half seconds, and fifty-one for init; they are one. Nothing is spared a
+ * file that holds a pattern of its own for each entry.
+ *
+ * Made where a run begins and handed down, never kept by this module: a
+ * reading is of the clock, so one kept past its run would answer for a
+ * machine that is busy no longer.
+ */
+export function patternReader(read = patternTools) {
+    const known = new Map();
+    return (source) => {
+        const before = known.get(source);
+        if (before !== undefined)
+            return before;
+        const tools = read(source);
+        known.set(source, tools);
+        return tools;
+    };
+}
 /** Whether Claude Code runs a hook's entry in the background, where it waits on no answer of it. */
 function inBackground(hook) {
     return hook['async'] === true || hook['asyncRewake'] === true;
@@ -134,12 +223,12 @@ function inBackground(hook) {
  * entry started only for the calls its rule matches, in the syntax of a
  * permission rule, which is not read here.
  */
-function answered(event, matcher, hook) {
+function answered(event, matcher, hook, pattern, commas) {
     if (event === BEFORE && inBackground(hook))
         return [];
     if (hook['if'] !== undefined)
         return null;
-    return matchedTools(matcher);
+    return matchedTools(matcher, pattern, commas);
 }
 /**
  * `.claude/settings.json`, or the plugin's hooks, with the guard hooks merged
@@ -153,10 +242,17 @@ function answered(event, matcher, hook) {
  * init rewrites none but the one 0.1 wrote. Without `isHook`, only init's
  * own line is known: the default's `false` and an `undefined` read the same
  * in `some`, so that mutant is equivalent.
+ *
+ * `pattern` reads a matcher that is a pattern: the run's own reader, where
+ * the run has read the file's matchers already ({@link patternReader}).
+ * `commas` is how the Claude Code here reads a comma in a matcher of names,
+ * where the run asked its release ({@link commasUnder}): a line that
+ * release starts for no write is no guard, and init's own is written beside
+ * it.
  */
-export function mergeClaudeSettings(current, isHook = () => false) {
+export function mergeClaudeSettings(current, isHook = () => false, pattern = patternReader(), commas = SEPARATOR) {
     const hooks = isObject(current['hooks']) ? current['hooks'] : {};
-    const theirs = harnessEntries(current).some((entry) => !isGuard(entry.hook) && !isLegacyGuard(entry.hook) && isHook(entry.words) && isStarted(toolsOf(entry)));
+    const theirs = harnessEntries(current).some((entry) => !isGuard(entry.hook) && !isLegacyGuard(entry.hook) && isHook(entry.words) && isStarted(toolsOf(entry, pattern, commas)));
     if (theirs)
         return null;
     let changed = false;
@@ -166,7 +262,7 @@ export function mergeClaudeSettings(current, isHook = () => false) {
         const before = Array.isArray(listed) ? listed : [];
         const groups = before.map(upgraded);
         const replaced = groups.some((group, index) => group !== before[index]);
-        const present = harnessEntries({ hooks: { [event]: groups } }).some((entry) => isGuard(entry.hook) && isStarted(toolsOf(entry)));
+        const present = harnessEntries({ hooks: { [event]: groups } }).some((entry) => isGuard(entry.hook) && isStarted(toolsOf(entry, pattern, commas)));
         if (!present)
             groups.push({ matcher: HOOK_MATCHER, hooks: [{ ...GUARD_HOOK, args: [...GUARD_ARGS] }] });
         if (replaced || !present) {
@@ -207,9 +303,24 @@ function isLauncher(word) {
 }
 /** Anything in a word that a shell reads before the program is handed it: a quote, a variable, an operator, a pattern. */
 const SHELL_READS = /[^A-Za-z0-9_./:=@%+,-]/;
+/**
+ * The handler types that are no command, by Claude Code's hooks reference
+ * (https://code.claude.com/docs/en/hooks, Hook handler fields, read
+ * 2026-10-12): an entry of one sends a request, calls a tool of an MCP
+ * server, or asks a model or an agent. It runs no command, the harness's or
+ * any other, whatever else the entry holds.
+ */
+const OTHER_HANDLERS = ['http', 'mcp_tool', 'prompt', 'agent'];
+/**
+ * The line of an entry that runs the harness, or `null` for one that does
+ * not. Only an entry Claude Code runs as a command is one: the reference
+ * has `type` as a field every entry must have, with `"command"` for a
+ * command and four other words, and says nothing of an entry with none or
+ * with another word, which is kept, and said as one that cannot be told.
+ */
 function writtenHook(hook) {
-    const { command, args } = hook;
-    if (typeof command !== 'string')
+    const { command, args, type } = hook;
+    if (typeof command !== 'string' || OTHER_HANDLERS.includes(type))
         return null;
     let line;
     // Without arguments the line is a shell's, which splits it at its spaces:
@@ -227,7 +338,8 @@ function writtenHook(hook) {
     if (at === -1)
         return null;
     const words = line.slice(at + 1);
-    return { words, shell: shell && words.some((word) => SHELL_READS.test(word)), blocks: hook['onFailure'] === 'block' };
+    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 };
 }
 /**
  * Every line in Claude Code's settings that runs the harness, under the two
@@ -238,25 +350,25 @@ function writtenHook(hook) {
  */
 export function writtenHooks(settings) {
     const found = [];
-    for (const { event, words, shell, blocks } of harnessEntries(settings)) {
-        const same = found.find((other) => sameLine(other, { words, shell, blocks }));
+    for (const { event, words, shell, blocks, untyped } of harnessEntries(settings)) {
+        const same = found.find((other) => sameLine(other, { words, shell, blocks, untyped }));
         if (same === undefined)
-            found.push({ events: [event], words, shell, blocks });
+            found.push({ events: [event], words, shell, blocks, untyped });
         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 && sameStrings(one.words, other.words);
+    return one.shell === other.shell && one.blocks === other.blocks && one.untyped === other.untyped && sameStrings(one.words, other.words);
 }
 /**
  * The writing tools whose call an entry is handed and waited on for, or
  * `null` where that cannot be told. Read where it is asked for and no
  * sooner: a matcher that is a pattern can cost its whole budget.
  */
-function toolsOf(entry) {
-    return answered(entry.event, entry.matcher, entry.hook);
+function toolsOf(entry, pattern, commas) {
+    return answered(entry.event, entry.matcher, entry.hook, pattern, commas);
 }
 /** Every entry that runs the harness under the two events the guard answers, in the order the settings hold them. */
 function harnessEntries(settings) {
@@ -301,18 +413,39 @@ function named(names) {
     return names.length === 1 ? last : `${names.slice(0, -1).join(', ')} and ${last}`;
 }
 /** The writing tools a line's entries under `event` are waited on for between them, or `null` where an entry that cannot be told might add one. */
-function toolsUnder(event, entries) {
-    const read = entries.filter((entry) => entry.event === event).map(toolsOf);
-    const sure = WRITING_TOOLS.filter((tool) => read.some((tools) => tools !== null && tools.includes(tool)));
-    return sure.length < WRITING_TOOLS.length && read.some((tools) => tools === null) ? null : sure;
+function toolsUnder(event, entries, reading) {
+    const read = entries.filter((entry) => entry.event === event).map((entry) => toolsOf(entry, reading.pattern, reading.commas));
+    const sure = CALLABLE_TOOLS.filter((tool) => read.some((tools) => tools !== null && tools.includes(tool)));
+    return sure.length < CALLABLE_TOOLS.length && read.some((tools) => tools === null) ? null : sure;
+}
+/**
+ * What is said after a matcher that Claude Code does not read as its text
+ * suggests: an array, which it loads no hook under, and names with a comma
+ * where the release here reads the comma another way than the newest does,
+ * or cannot be told. Nothing for any other matcher, and nothing for a comma
+ * where both readings come to no tool that writes.
+ */
+function saidOfMatcher(matcher, { pattern, commas }) {
+    if (Array.isArray(matcher))
+        return ', an array, which Claude Code lists as an invalid setting and loads no hook under';
+    if (commas.as === 'separator')
+        return '';
+    const comma = commaReading(matcher, pattern);
+    if (comma === null || (comma.earlier !== null && comma.listed.length === 0))
+        return '';
+    const listed = comma.listed.length === 0 ? 'no tool that writes' : named(comma.listed);
+    const earlier = comma.earlier === null ? 'a pattern whose matches its documentation does not give' : 'a pattern that matches no tool';
+    if (commas.as === 'untold')
+        return `, which is ${listed} from Claude Code ${COMMA_SINCE} on, where a comma separates names, and ${earlier} before it: the release here cannot be told`;
+    return `, which Claude Code ${commas.release} reads as ${earlier}: a comma separates names from ${COMMA_SINCE} on, where the matcher is ${listed}`;
 }
 /** What a line's entries under `event` hold that decides when Claude Code starts them, as written. */
-function entriesUnder(event, entries) {
+function entriesUnder(event, entries, reading) {
     const under = entries.filter((entry) => entry.event === event);
     if (under.length === 0)
         return `it stands under no ${event}`;
     const said = under.map(({ matcher, hook }) => {
-        const pattern = matcher === undefined ? 'no matcher' : `the matcher ${JSON.stringify(matcher)}`;
+        const pattern = matcher === undefined ? 'no matcher' : `the matcher ${JSON.stringify(matcher)}${saidOfMatcher(matcher, reading)}`;
         const background = inBackground(hook) ? ' in the background' : '';
         const rule = hook['if'] === undefined ? '' : ` with "if" ${JSON.stringify(hook['if'])}`;
         return `${pattern}${background}${rule}`;
@@ -323,25 +456,62 @@ function entriesUnder(event, entries) {
  * What is said of the writes Claude Code starts a line for, by the event and
  * the matcher of each entry that holds it; `null` where it is waited on
  * before every tool that writes and started after each, as init writes it.
+ * A tool is one a supported Claude Code can call: `MultiEdit`, which the
+ * hook still reads a path from, is named as unchecked for no line, since no
+ * such Claude Code has it to call (hooks.ts).
  */
-function describeCover(where, before, after, entries) {
+function describeCover(where, before, after, entries, reading) {
     const parts = [];
-    const left = (tools) => WRITING_TOOLS.filter((tool) => !tools.includes(tool));
+    const left = (tools) => CALLABLE_TOOLS.filter((tool) => !tools.includes(tool));
     if (before === null)
-        parts.push(`which writes Claude Code waits on it before cannot be told here (${entriesUnder(BEFORE, entries)})`);
+        parts.push(`which writes Claude Code waits on it before cannot be told here (${entriesUnder(BEFORE, entries, reading)})`);
     else if (before.length === 0)
-        parts.push(`Claude Code waits on it before no write, so it is not the guard and refuses none (${entriesUnder(BEFORE, entries)})`);
+        parts.push(`Claude Code waits on it before no write, so it is not the guard and refuses none (${entriesUnder(BEFORE, entries, reading)})`);
     else if (left(before).length > 0) {
-        parts.push(`Claude Code waits on it before a write by ${named(before)}, and before none by ${named(left(before))}, which goes unchecked (${entriesUnder(BEFORE, entries)})`);
+        parts.push(`Claude Code waits on it before a write by ${named(before)}, and before none by ${named(left(before))}, which goes unchecked (${entriesUnder(BEFORE, entries, reading)})`);
     }
     if (after === null)
-        parts.push(`which writes it is started after cannot be told here (${entriesUnder(AFTER, entries)})`);
+        parts.push(`which writes it is started after cannot be told here (${entriesUnder(AFTER, entries, reading)})`);
     else if (after.length === 0)
-        parts.push(`it is started after no write, so it warns of none (${entriesUnder(AFTER, entries)})`);
+        parts.push(`it is started after no write, so it warns of none (${entriesUnder(AFTER, entries, reading)})`);
     else if (left(after).length > 0)
-        parts.push(`it is started after a write by ${named(after)} alone (${entriesUnder(AFTER, entries)})`);
+        parts.push(`it is started after a write by ${named(after)} alone (${entriesUnder(AFTER, entries, reading)})`);
     return parts.length === 0 ? null : `${where}: ${parts.join('; ')}`;
 }
+/** The events under which an array for a matcher keeps Claude Code from loading the rest of a file's hooks. */
+const UNLOADING = [BEFORE, 'PermissionRequest'];
+/**
+ * The first array that stands for a matcher under `PreToolUse` or
+ * `PermissionRequest` in a settings file, or `null`.
+ *
+ * Claude Code's page on debugging a configuration
+ * (https://code.claude.com/docs/en/debug-your-config, Check hooks, read
+ * 2026-10-14) has a matcher that is an array, where it must be one string,
+ * as an entry Claude Code lists as an invalid setting, at the start of an
+ * interactive session and in `claude doctor`; and where the array is under
+ * one of these two events, none of that file's other hooks load either. It
+ * names no release. So a file that holds one runs no hook at all, whoever
+ * wrote the entry and whatever it runs: the array's own is not loaded, and
+ * neither is any other.
+ */
+export function arrayMatcher(settings) {
+    const hooks = field(settings, 'hooks');
+    for (const event of UNLOADING) {
+        const groups = field(hooks, event);
+        if (!Array.isArray(groups))
+            continue;
+        const group = groups.find((candidate) => Array.isArray(field(candidate, 'matcher')));
+        if (group !== undefined)
+            return { event, matcher: JSON.stringify(field(group, 'matcher')) };
+    }
+    return null;
+}
+/** What is said of a settings file that an array for a matcher keeps Claude Code from loading the hooks of. */
+export function describeArrayMatcher(file, { event, matcher }) {
+    return `${file} has an array for a matcher under ${event}, ${matcher}, which Claude Code lists as an invalid setting, and beside one under PreToolUse or PermissionRequest it loads none of the file's other hooks`;
+}
+/** How a matcher that is an array is mended. */
+export const ONE_STRING = 'write the matcher as one string, its names between "|"';
 /** The words Claude Code hands the hook for a line: what follows the harness's command, each `${CLAUDE_PROJECT_DIR}` filled with `project`. */
 function handedWords(words, project) {
     return words.map((word) => word.split(PROJECT_DIR).join(project));
@@ -360,14 +530,29 @@ export function handedLines(sources, project) {
  * A line that guards and holds no more than a release wrote is reported
  * with nothing to say, as it always was. One with more on it is said as it
  * is, and fails nothing. One the hook cannot read, or whose root is no
- * directory, is a guard that is off, and one that names a brief which is not
+ * directory, or is in no work tree that holds the project, is a guard that
+ * is off, and one that names a brief which is not
  * one holds every write: each a problem, and doctor exits 1 for it. A line
  * Claude Code waits on before no write is not the guard, whatever the hook
  * would do with it.
+ *
+ * `pattern` reads a matcher that is a pattern, once for every entry under
+ * it in every file: the run's own reader, where something else in the run
+ * reads the same files ({@link patternReader}). `commas` is how the Claude
+ * Code here reads a comma in a matcher of names, where its release was
+ * asked ({@link commasUnder}); a caller that asks none reads a comma as
+ * every release from {@link COMMA_SINCE} on does.
+ *
+ * A file that holds an array for a matcher under `PreToolUse` or
+ * `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.
  */
-export function reportHooks(sources, project, read) {
+export function reportHooks(sources, project, read, pattern = patternReader(), commas = SEPARATOR) {
+    const reading = { pattern, commas };
     return sources.flatMap(({ file, settings }) => {
         const entries = harnessEntries(settings);
+        const array = arrayMatcher(settings);
         return writtenHooks(settings).flatMap((hook) => {
             const handed = read(handedWords(hook.words, project));
             if (handed === null)
@@ -377,21 +562,49 @@ export function reportHooks(sources, project, read) {
             // A line that is not under both events is under one.
             const where = `"${hook.words.map((word) => (word === '' ? "''" : word)).join(' ')}" in ${file}${both ? '' : ` (under ${hook.events[0]} alone)`}`;
             const mine = entries.filter((entry) => sameLine(entry, hook));
-            const before = toolsUnder(BEFORE, mine);
-            const after = toolsUnder(AFTER, mine);
-            const written = { file, events: hook.events, line: hook.words, onFailure: hook.blocks ? 'block' : null, before, after, cover: describeCover(where, before, after, mine) };
+            const before = toolsUnder(BEFORE, mine, reading);
+            const after = toolsUnder(AFTER, mine, reading);
+            if (array !== null) {
+                // Nothing of the file is loaded, whatever the line holds and
+                // whatever the hook would do with it. A line that stood to be
+                // started for a write, or stands under an array itself, where
+                // 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 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);
+            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 }];
+            }
             if (hook.shell) {
                 const detail = `${where} is a shell's to read before the hook is handed it, so what the hook does with it cannot be told here: written with "args", each word reaches the hook as it stands`;
-                return [{ ...written, state: 'unknown', detail, note: describeOnFailure(where, hook.blocks, false) }];
+                return [{ ...written, state: 'unknown', detail, note }];
             }
+            // 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;
             if (handed.state === 'off') {
-                const detail = `${where}: ${handed.fault.wrong}, so the guard is off and no write is checked; ${handed.fault.mend}`;
-                return [{ ...written, state: 'off', detail, note: describeOnFailure(where, hook.blocks, true) }];
+                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];
             }
-            const note = describeOnFailure(where, hook.blocks, false);
-            // What the hook would do with a line it is never asked on before a write is not what guards.
-            if (before !== null && before.length === 0)
-                return [{ ...written, state: 'unstarted', detail: null, note }];
+            if (!waited)
+                return [unstarted];
             if (handed.state === 'held') {
                 const detail = `${where}: ${handed.wrong}, so the hook holds every write until the line is mended: name a brief spec-brief lists, or take --brief off the line`;
                 return [{ ...written, state: 'held', detail, note }];
@@ -402,7 +615,9 @@ export function reportHooks(sources, project, read) {
             if (sameStrings(hook.words, ['hook', 'claude']))
                 return [{ ...written, state: 'guards', detail: null, note }];
             const root = handed.root === undefined ? '' : `, and its root, ${handed.root}, is a directory`;
-            return [{ ...written, state: 'guards', detail: `${where} is more than init writes, and guards: the hook reads the line${root}`, note }];
+            // 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 }];
         });
     });
 }
@@ -434,6 +649,119 @@ export function enabledPlugin(sources) {
     }
     return [...decided.values()].find((entry) => entry !== null) ?? null;
 }
+/**
+ * The settings file whose `disableAllHooks` turns Claude Code's hooks off,
+ * or `null` where none does.
+ *
+ * By its settings reference
+ * (https://code.claude.com/docs/en/settings-reference, disableAllHooks, read
+ * 2026-10-12) the key is a Boolean any settings file may hold, and `true`
+ * turns hooks off. Set outside managed settings, it turns off the hooks of
+ * the user's, the project's and the local settings and of plugins, and the
+ * hooks of managed settings, of the Agent SDK and of a plugin that managed
+ * settings force on keep running. By its hooks reference (Disable or remove
+ * hooks) the value that counts is the one left after settings precedence:
+ * of the files given, lowest precedence first, the last that sets a Boolean
+ * decides. A value that is no Boolean is passed over, as the key left out.
+ */
+export function hooksDisabled(sources) {
+    let file = null;
+    for (const source of sources) {
+        const value = field(source.settings, 'disableAllHooks');
+        if (typeof value === 'boolean')
+            file = value ? source.file : null;
+    }
+    return file;
+}
+/** The project's settings file for Claude Code, as it is named among the sources. */
+export const PROJECT_SETTINGS = '.claude/settings.json';
+/** Where Claude Code records the marketplaces it has fetched, in a directory it keeps plugins in. */
+export const MARKETPLACE_REGISTRY = 'known_marketplaces.json';
+/** Where it records the marketplaces hosted on claude.ai, in a shape its reference does not give. */
+export const HOSTED_REGISTRY = 'known_marketplaces_claudeai.json';
+/**
+ * The origins in a plugin's id that are no marketplace, by Claude Code's
+ * plugin loading reference (https://code.claude.com/docs/en/plugins/loading,
+ * Find where a plugin came from, read 2026-10-12): a plugin started from a
+ * directory or an archive, one saved under a skills directory, and one
+ * synced from a claude.ai account. None has a marketplace, and the first
+ * and the last no record on disk that the reference describes.
+ */
+const OTHER_ORIGINS = ['inline', 'skills-dir', 'synced'];
+/** A name a directory can be looked up by: no separator, and no way out of the directory it is looked up in. */
+const DIRECTORY_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/**
+ * The marketplace a plugin's id names, where it names one whose directory
+ * can be looked up: `null` for an origin that is no marketplace, and for
+ * text that names no directory.
+ */
+export function pluginMarketplace(id) {
+    const origin = id.slice(id.indexOf('@') + 1);
+    return OTHER_ORIGINS.includes(origin) || !DIRECTORY_NAME.test(origin) ? null : origin;
+}
+function turnsOn(settings, id) {
+    const plugins = field(settings, 'enabledPlugins');
+    return isObject(plugins) && plugins[id] === true;
+}
+function holds(record, name) {
+    return isObject(record) && Object.hasOwn(record, name);
+}
+/**
+ * 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, read 2026-10-12), from
+ * the settings files and from what the directories it keeps plugins in
+ * hold: its plugins root, and each seed directory.
+ *
+ * `present`: a version of it is in a cache, where the reference has one
+ * directory for each installed version of a marketplace plugin (Find
+ * plugins on disk).
+ *
+ * `absent` is said only where the reference leaves the plugin no way to
+ * load (Enabled in project settings but not installed): its only `true` is
+ * in the project's `.claude/settings.json`, for which Claude Code fetches
+ * no plugin a machine lacks, and neither of the page's two exceptions is
+ * met, a marketplace that lists it by a relative path, since no marketplace
+ * of that name is recorded as fetched or declared in settings, and a seed
+ * directory that holds it.
+ *
+ * Everything else is `unknown`: an origin that is no marketplace, a record
+ * that is not there or cannot be read, a marketplace that is there or is
+ * declared, whose own list is not read here, and a `true` in a settings
+ * file of the person's own, for which Claude Code fetches.
+ */
+export function pluginPresence(plugin, sources, roots) {
+    const untold = (detail) => ({ state: 'unknown', detail });
+    const marketplace = pluginMarketplace(plugin.id);
+    if (marketplace === null)
+        return untold(`${plugin.id} names no marketplace whose plugins are kept in a cache: a plugin from --plugin-dir, a skills directory or a claude.ai account comes another way`);
+    if (roots.length === 0)
+        return untold('where Claude Code keeps its plugins is not known here: none of CLAUDE_CODE_PLUGIN_CACHE_DIR, CLAUDE_CONFIG_DIR and a home directory is set');
+    if (roots.some((root) => root.cached))
+        return { state: 'present', detail: null };
+    const unread = roots.find((root) => !isObject(root.registry));
+    if (unread !== undefined) {
+        const wrong = unread.registry === null ? 'is not there' : 'cannot be read as JSON';
+        return untold(`${join(unread.directory, MARKETPLACE_REGISTRY)}, where Claude Code records the marketplaces it has fetched, ${wrong}`);
+    }
+    const fetched = roots.find((root) => holds(root.registry, marketplace));
+    if (fetched !== undefined) {
+        return untold(`its marketplace, ${marketplace}, is on this machine (${join(fetched.directory, MARKETPLACE_REGISTRY)}) and no version of the plugin is in the cache: Claude Code loads a plugin that its marketplace lists by a relative path from the marketplace itself, and the marketplace's list is not read here`);
+    }
+    const declaring = sources.find(({ settings }) => holds(field(settings, 'extraKnownMarketplaces'), marketplace));
+    if (declaring !== undefined)
+        return untold(`${declaring.file} declares its marketplace, ${marketplace}, under extraKnownMarketplaces, which Claude Code fetches after a session has started: nothing of it is on this machine now`);
+    const hosted = roots.find((root) => root.hosted);
+    if (hosted !== undefined)
+        return untold(`${join(hosted.directory, HOSTED_REGISTRY)} records the marketplaces hosted on claude.ai, in a shape Claude Code's reference does not give, so whether ${marketplace} is one cannot be read`);
+    const own = sources.filter(({ file, settings }) => file !== PROJECT_SETTINGS && turnsOn(settings, plugin.id)).map(({ file }) => file);
+    if (own.length > 0)
+        return untold(`${named(own)} ${own.length === 1 ? 'turns' : 'turn'} it on, and Claude Code fetches a plugin that settings of the person's own turn on: neither a version of it nor its marketplace, ${marketplace}, is on this machine now`);
+    return {
+        state: 'absent',
+        detail: `${PROJECT_SETTINGS} alone turns it on, and Claude Code fetches no plugin that a project's settings alone turn on, unless its marketplace lists it by a relative path or a seed directory holds it: no marketplace ${marketplace} is recorded as fetched or declared in settings, and no version of the plugin is in a cache (${roots.map((root) => join(root.directory, 'cache')).join(', ')})`,
+    };
+}
 /** Where the plugin is on, as a person would look it up. */
 function isOn(plugin) {
     return `the spec-harness plugin is on (${plugin.id} in ${plugin.file})`;
@@ -443,9 +771,30 @@ function turnOff(plugin) {
     return `turn the plugin off for this project with claude plugin disable ${plugin.id} --scope local`;
 }
 const PARTS = literal({
-    hooks: { brings: 'the guard hooks', twice: 'every write is guarded twice', skipped: 'init writes none', entry: "spec-harness's hooks", them: 'them' },
-    server: { brings: 'the server', twice: 'the server is registered twice', skipped: 'init registers none', entry: 'the spec-harness server', them: 'it' },
+    hooks: { brings: 'the guard hooks', twice: 'every write is guarded twice', skipped: 'init writes none', entry: "spec-harness's hooks", them: 'them', none: 'no hook' },
+    server: { brings: 'the server', twice: 'the server is registered twice', skipped: 'init registers none', entry: 'the spec-harness server', them: 'it', none: 'no server' },
 });
+/** How to have a plugin that is not on this machine brought to it, in the commands Claude Code's plugin pages give. */
+function bring(plugin) {
+    return `install it here, with claude plugin install ${plugin.id} once its marketplace is added`;
+}
+/** That the plugin settings turn on is not on this machine, and why. */
+function isAbsent(plugin, detail, brought) {
+    return `${isOn(plugin)} and is not on this machine, so it brings ${brought} here: ${detail}`;
+}
+/**
+ * What init says of a Claude Code file where the plugin that settings turn
+ * on is not on this machine. It writes nothing on that reading alone: a
+ * plugin that is there after all would bring the same `part` a second time.
+ * A file that holds init's entry already is `present`.
+ */
+export function describeAbsent(plugin, detail, part, present) {
+    const words = PARTS[part];
+    const absent = isAbsent(plugin, detail, words.none);
+    if (present)
+        return `${absent}. This file holds ${words.entry}; with the plugin installed as well, ${words.twice}: ${turnOff(plugin)}`;
+    return `${absent}. On that reading alone ${words.skipped}, since with a plugin that is there after all ${words.twice}: ${bring(plugin)}, or to have ${words.them} here instead, ${turnOff(plugin)} and run init again`;
+}
 /**
  * What init says of a Claude Code file it leaves alone because the plugin is
  * on and brings the same `part`. A file that holds init's entry already is a
@@ -463,22 +812,75 @@ export function describeSkipped(plugin, part, present, elsewhere = []) {
     }
     return `${isOn(plugin)} and brings ${words.brings}, so ${words.skipped}: with both, ${words.twice}. To have ${words.them} here instead, for every clone of the repository, ${turnOff(plugin)} and run init again`;
 }
-/** Which of the four the wiring is. `both` is a double install, and doctor fails it; either of init's entries counts. */
+/** Why the plugin settings turn on is not on this machine, or `null` where it is, may be, or none is on. */
+function absence(wiring) {
+    return wiring.presence?.state === 'absent' ? wiring.presence.detail : null;
+}
+/**
+ * Which of the four the wiring is. `both` is a double install, and doctor
+ * fails it; either of init's entries counts. A plugin that is not on this
+ * machine brings nothing to it, and is not counted.
+ */
 export function wiringState(wiring) {
     const init = wiring.hooks.length > 0 || wiring.server;
-    if (wiring.plugin === null)
+    if (wiring.plugin === null || absence(wiring) !== null)
         return init ? 'init' : 'none';
     return init ? 'both' : 'plugin';
 }
+/**
+ * Whether hooks that would guard are switched off: `disableAllHooks` in a
+ * settings file, where a settings file holds the guard hooks or a plugin
+ * that may be on this machine brings them. A guard someone set up, which
+ * checks no write.
+ */
+export function guardSwitchedOff(wiring) {
+    return wiring.hooksOff !== null && (wiring.hooks.length > 0 || (wiring.plugin !== null && absence(wiring) === null));
+}
+/**
+ * What doctor and init say of `disableAllHooks` in `file`. `guarded` is
+ * whether there are guard hooks for it to switch off; without any it is a
+ * note on what the key would do to them.
+ */
+export function describeHooksOff(file, guarded) {
+    const off = `"disableAllHooks" is true in ${file}, so Claude Code runs no hook of the user's, the project's or the local settings, and none of a plugin`;
+    if (!guarded)
+        return `note: ${off}: the hooks init writes, and those the plugin brings, would not run while it stands`;
+    return `${off}: no write is guarded. Take the key out of ${file}, or set it to false, to have the guard back. Hooks of managed settings, and of a plugin managed settings force on, keep running, and no managed settings are read here`;
+}
+/**
+ * What doctor adds of the plugin settings turn on, where it is not simply on
+ * this machine: that it cannot be told, which is never fine, or that it is
+ * not, beside entries of init's. `null` where there is no more to say: no
+ * plugin, one that is there, and one that is not where nothing else is
+ * wired, which the wiring's own sentence says.
+ */
+export function describePresence(wiring) {
+    const { plugin, presence } = wiring;
+    if (plugin === null || presence === undefined || presence === null || presence.state === 'present')
+        return null;
+    if (presence.state === 'unknown')
+        return `whether ${plugin.id} is on this machine cannot be told: ${presence.detail}. A plugin that is not there brings no hook: Claude Code's /plugin lists it, and its errors`;
+    if (wiring.hooks.length > 0)
+        return `${isAbsent(plugin, presence.detail, 'no hook')}. With the plugin installed as well, ${PARTS.hooks.twice}: ${turnOff(plugin)}`;
+    return wiring.server ? unguarded(plugin, presence.detail) : null;
+}
+/** That the plugin settings turn on is not on this machine and no hook of init's stands in for it, with the two ways to a guard. */
+function unguarded(plugin, detail) {
+    return `${isAbsent(plugin, detail, 'no hook')}, and Claude Code guards no write. To have the guard, ${bring(plugin)}, or ${turnOff(plugin)} and run spec-harness init --write`;
+}
 /** What `doctor` says of the wiring, and what to do when it is doubled or missing. */
 export function describeClaudeCode(wiring) {
     const { plugin } = wiring;
     const entries = [...wiring.hooks.map((file) => `the guard hooks in ${file}`), ...(wiring.server ? ['the server in .mcp.json'] : [])].join(', ');
+    const own = `init's entries: ${entries}`;
     if (plugin === null) {
         if (entries === '')
             return 'neither the spec-harness plugin nor the hooks init writes, so Claude Code guards no write: run spec-harness init --write, or install the plugin';
-        return `init's entries: ${entries}`;
+        return own;
     }
+    const absent = absence(wiring);
+    if (absent !== null)
+        return entries === '' ? unguarded(plugin, absent) : own;
     if (entries === '')
         return `${isOn(plugin)} and brings the guard hooks and the server`;
     const twice = [...(wiring.hooks.length > 0 ? [PARTS.hooks.twice] : []), ...(wiring.server ? [PARTS.server.twice] : [])].join(' and ');
@@ -721,6 +1123,10 @@ export function describeGitHook(hook) {
             return `${hook.file} runs spec-harness, but is not executable, so git skips it: chmod +x ${hook.file}`;
         case 'other':
             return `${hook.file} does not run spec-harness: add the line "${GIT_HOOK_LINE}" to it`;
+        case 'stops':
+            return `${hook.file} is ${hook.what}, not a hook, and git stops every commit at it, since it cannot run it ("cannot spawn" on Windows, "cannot exec" elsewhere): nothing is checked there, and nothing is committed. Take it away, then run spec-harness init --git-hook --write`;
+        case 'ignored':
+            return `${hook.file} is ${hook.what}, not a hook, and is not executable, so git skips it and runs no hook: take it away, then run spec-harness init --git-hook --write`;
         case 'absent':
             return missingGitHook(hook.file);
         case 'unknown':