@descent-vtt/spec-harness 0.15.0 → 0.16.0

package/dist/configure.d.ts

@@ -24,8 +24,20 @@ export declare const PROJECT_DIR_OR_HERE = "${CLAUDE_PROJECT_DIR:-.}";
  * path is one argument whatever it holds, and no shell is involved.
  */
 export declare const GUARD_HOOK: Readonly<Json>;
-/** `.claude/settings.json`, or the plugin's hooks, with the guard hooks merged in; `null` when they are already there. */
-export declare function mergeClaudeSettings(current: Json): Json | null;
+/**
+ * `.claude/settings.json`, or the plugin's hooks, with the guard hooks merged
+ * in; `null` when they are already there.
+ *
+ * An event has the guard where Claude Code starts init's own line under it
+ * for a write. Where the settings hold another line of the hook that it
+ * starts for a write, one `isHook` knows as the hook's by the words after
+ * the harness's command, nothing is merged in at all: the line is a
+ * person's, a second one beside it would run for every write as well, and
+ * 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.
+ */
+export declare function mergeClaudeSettings(current: Json, isHook?: (words: readonly string[]) => boolean): Json | null;
 /** The server's entry, reading the project at `projectDir`: {@link PROJECT_DIR} for the plugin, {@link PROJECT_DIR_OR_HERE} for a project. */
 export declare function mcpServer(projectDir: string): Json;
 /**
@@ -35,8 +47,6 @@ export declare function mcpServer(projectDir: string): Json;
  * fields.
  */
 export declare function mergeMcp(current: Json): Json | null;
-/** Whether Claude Code settings hold the guard hooks, as this release or 0.1 wrote them. */
-export declare function holdsGuard(settings: unknown): boolean;
 /** A line of the harness's in Claude Code's settings: what follows its command there. */
 export interface WrittenHook {
     /** The events whose hooks hold the line, of the two the guard answers. */
@@ -62,6 +72,8 @@ export interface WrittenHook {
  * alone.
  */
 export declare function writtenHooks(settings: unknown): WrittenHook[];
+/** Whether Claude Code starts a line for a write, by the tools it is waited on for: one whose tools cannot be told is taken as started. */
+export declare function isStarted(tools: readonly string[] | null): boolean;
 /** What doctor reports of one line of Claude Code's hook. */
 export interface HookReport {
     /** The settings file that holds it, as a person finds it. */
@@ -69,25 +81,43 @@ export interface HookReport {
     readonly events: readonly string[];
     /** What follows the harness's command, as written. */
     readonly line: readonly string[];
-    /** `unknown`: a shell reads the line before the hook does, so what the hook is handed cannot be told. */
-    readonly state: 'guards' | 'off' | 'unknown';
+    /**
+     * `guards`: Claude Code waits on the hook before a write, and the hook
+     * checks it. `off`: the hook checks no write, for a line it cannot read or
+     * a root that is no directory. `held`: the hook holds every write, for a
+     * brief the line names that is not one. `unstarted`: Claude Code waits on
+     * the line before no write, so it is not the guard. `unknown`: what the
+     * hook is handed, or which writes it is started for, cannot be told here.
+     */
+    readonly state: 'guards' | 'off' | 'held' | 'unstarted' | 'unknown';
     readonly onFailure: 'block' | null;
-    /** What there is to say of the line, or `null` for the line a release wrote, which guards. */
+    /** What there is to say of what the hook does with the line, or `null`. */
     readonly detail: string | null;
+    /** The writing tools Claude Code waits on the line before a write by, where the hook can refuse it; `null` where that cannot be told. */
+    readonly before: readonly string[] | null;
+    /** The writing tools Claude Code starts the line after a write by, where the hook can warn of it; `null` where that cannot be told. */
+    readonly after: readonly string[] | null;
+    /** What there is to say of the two, or `null` where they are every tool that writes, as init has it. */
+    readonly cover: string | null;
     /** What `onFailure` changes, where the entry sets it to `"block"`. */
     readonly note: string | null;
 }
+/** The words handed over for every line of the harness's in the settings files, for a caller that has to ask something of each before it reports them. */
+export declare function handedLines(sources: readonly ClaudeSettings[], project: string): string[][];
 /**
  * The lines of Claude Code's hook in the settings files, each with what the
- * hook does with it. `read` is the hook's own reading of the words it is
- * handed (usage.ts), `null` for a line that is not its; the words are handed
- * to it as Claude Code hands them to the hook, each `${CLAUDE_PROJECT_DIR}`
- * filled with `project`.
+ * hook does with it and which writes Claude Code starts it for. `read` is
+ * the hook's own reading of the words it is handed (usage.ts), `null` for a
+ * line that is not its; the words are handed to it as Claude Code hands them
+ * to the hook, each `${CLAUDE_PROJECT_DIR}` filled with `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: a problem, and doctor exits 1 for it.
+ * directory, 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.
  */
 export declare function reportHooks(sources: readonly ClaudeSettings[], project: string, read: (words: readonly string[]) => HookLine | null): HookReport[];
 /** Whether a project's `.mcp.json` registers a server under the harness's name, however it runs it. */
@@ -115,15 +145,17 @@ export declare function enabledPlugin(sources: readonly ClaudeSettings[]): Enabl
  * 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
  * double install for the person to settle: init removes nothing, since the
- * file is the repository's and a clone without the plugin relies on it.
+ * file is the repository's and a clone without the plugin relies on it. So
+ * is an entry `elsewhere`, in a settings file of the person's own, which
+ * init does not write and doctor fails all the same.
  */
-export declare function describeSkipped(plugin: EnabledPlugin, part: 'hooks' | 'server', present: boolean): string;
+export declare function describeSkipped(plugin: EnabledPlugin, part: 'hooks' | 'server', present: boolean, elsewhere?: readonly string[]): string;
 /** How Claude Code is wired to the harness: the plugin, init's entries, both or neither. */
 export interface ClaudeCodeWiring {
     readonly plugin: EnabledPlugin | null;
-    /** The settings files that hold the guard hooks. */
+    /** The settings files that hold the guard hooks: a line of the hook that Claude Code starts for a write, before it or after. */
     readonly hooks: readonly string[];
-    /** Each line of the hook in those files, with what the hook does with it. */
+    /** Each line of the hook in the settings files, with what the hook does with it and the writes it is started for. */
     readonly lines: readonly HookReport[];
     /** Whether `.mcp.json` registers the server. */
     readonly server: boolean;

package/dist/configure.js

@@ -8,6 +8,8 @@
  * nothing to add.
  */
 import { isAbsolute } from 'node:path';
+import { runInNewContext } from 'node:vm';
+import { WRITING_TOOLS } from './hooks.js';
 import { literal } from './literal.js';
 import { parseGlobList } from './vendor/spec-core/pattern/index.js';
 import { CLAUDE_CODE_MINIMUM } from './versions.js';
@@ -36,7 +38,11 @@ export const PROJECT_DIR = '${CLAUDE_PROJECT_DIR}';
  */
 export const PROJECT_DIR_OR_HERE = '${CLAUDE_PROJECT_DIR:-.}';
 const HOOK_MATCHER = 'Edit|Write|MultiEdit|NotebookEdit';
-const GUARDED_EVENTS = ['PreToolUse', 'PostToolUse'];
+/** 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';
+/** The event after a call that succeeded, where a hook can only tell the model what it wrote. */
+const AFTER = 'PostToolUse';
+const GUARDED_EVENTS = [BEFORE, AFTER];
 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
@@ -63,9 +69,96 @@ function upgraded(group) {
         return group;
     return { ...group, hooks: hooks.map((hook) => (isLegacyGuard(hook) ? { ...hook, command: 'node', args: [...GUARD_ARGS] } : hook)) };
 }
-/** `.claude/settings.json`, or the plugin's hooks, with the guard hooks merged in; `null` when they are already there. */
-export function mergeClaudeSettings(current) {
+/**
+ * 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
+ * (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.
+ */
+function matchedTools(matcher) {
+    if (matcher === undefined || matcher === '' || matcher === '*')
+        return WRITING_TOOLS;
+    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);
+}
+/**
+ * How long the reading of one pattern may take, in milliseconds of the
+ * clock. A sane matcher is read in about half of one (ADR-0005), so only a
+ * pattern that backtracks without end meets it; on a machine under load an
+ * ordinary one may, and is then said as one that cannot be told, where an
+ * idle machine reads it.
+ */
+const PATTERN_BUDGET = 100;
+/**
+ * The writing tools a matcher that is a pattern matches, or `null` where it
+ * 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:
+ * `^((((([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
+ * takes a timeout where a test in this one takes none, and what throws
+ * there, a pattern that is none or the stop itself, is a matcher that
+ * cannot be told. The shape of a pattern does not say which will: groups in
+ * a row backtrack as nested ones do.
+ */
+function patternTools(source) {
+    try {
+        const matched = runInNewContext('tools.filter((tool) => new RegExp(source).test(tool))', { tools: WRITING_TOOLS, source }, { timeout: PATTERN_BUDGET });
+        return matched;
+    }
+    catch {
+        return null;
+    }
+}
+/** 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;
+}
+/**
+ * The writing tools whose call Claude Code hands an entry under `event` and
+ * waits for it on, or `null` where that cannot be told here. Before a write
+ * an entry in the background answers too late to refuse it, so it is waited
+ * on for none (the reference, Run hooks in the background). An `if` has the
+ * 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) {
+    if (event === BEFORE && inBackground(hook))
+        return [];
+    if (hook['if'] !== undefined)
+        return null;
+    return matchedTools(matcher);
+}
+/**
+ * `.claude/settings.json`, or the plugin's hooks, with the guard hooks merged
+ * in; `null` when they are already there.
+ *
+ * An event has the guard where Claude Code starts init's own line under it
+ * for a write. Where the settings hold another line of the hook that it
+ * starts for a write, one `isHook` knows as the hook's by the words after
+ * the harness's command, nothing is merged in at all: the line is a
+ * person's, a second one beside it would run for every write as well, and
+ * 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.
+ */
+export function mergeClaudeSettings(current, isHook = () => false) {
     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)));
+    if (theirs)
+        return null;
     let changed = false;
     const next = { ...hooks };
     for (const event of GUARDED_EVENTS) {
@@ -73,7 +166,7 @@ export function mergeClaudeSettings(current) {
         const before = Array.isArray(listed) ? listed : [];
         const groups = before.map(upgraded);
         const replaced = groups.some((group, index) => group !== before[index]);
-        const present = groups.some((group) => hooksOf(group).some(isGuard));
+        const present = harnessEntries({ hooks: { [event]: groups } }).some((entry) => isGuard(entry.hook) && isStarted(toolsOf(entry)));
         if (!present)
             groups.push({ matcher: HOOK_MATCHER, hooks: [{ ...GUARD_HOOK, args: [...GUARD_ARGS] }] });
         if (replaced || !present) {
@@ -107,16 +200,6 @@ export function mergeMcp(current) {
 function field(file, key) {
     return isObject(file) ? file[key] : undefined;
 }
-/** Whether Claude Code settings hold the guard hooks, as this release or 0.1 wrote them. */
-export function holdsGuard(settings) {
-    const hooks = field(settings, 'hooks');
-    if (!isObject(hooks))
-        return false;
-    return GUARDED_EVENTS.some((event) => {
-        const groups = hooks[event];
-        return Array.isArray(groups) && groups.some((group) => hooksOf(group).some((hook) => isGuard(hook) || isLegacyGuard(hook)));
-    });
-}
 /** The harness's command on a line: its script, or its name, alone or at the end of a path. */
 function isLauncher(word) {
     const name = word.split(/[\\/]/).at(-1);
@@ -125,8 +208,6 @@ 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_./:=@%+,-]/;
 function writtenHook(hook) {
-    if (!isObject(hook))
-        return null;
     const { command, args } = hook;
     if (typeof command !== 'string')
         return null;
@@ -156,26 +237,49 @@ function writtenHook(hook) {
  * alone.
  */
 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 }));
+        if (same === undefined)
+            found.push({ events: [event], words, shell, blocks });
+        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);
+}
+/**
+ * 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);
+}
+/** Every entry that runs the harness under the two events the guard answers, in the order the settings hold them. */
+function harnessEntries(settings) {
     const hooks = field(settings, 'hooks');
     if (!isObject(hooks))
         return [];
-    const found = [];
-    for (const event of GUARDED_EVENTS) {
+    return GUARDED_EVENTS.flatMap((event) => {
         const groups = hooks[event];
         if (!Array.isArray(groups))
-            continue;
-        for (const hook of groups.flatMap(hooksOf)) {
+            return [];
+        return groups.flatMap((group) => hooksOf(group).flatMap((hook) => {
+            if (!isObject(hook))
+                return [];
             const written = writtenHook(hook);
             if (written === null)
-                continue;
-            const same = found.find((other) => other.shell === written.shell && other.blocks === written.blocks && sameStrings(other.words, written.words));
-            if (same === undefined)
-                found.push({ events: [event], ...written });
-            else if (!same.events.includes(event))
-                same.events.push(event);
-        }
-    }
-    return found;
+                return [];
+            return [{ ...written, event, matcher: field(group, 'matcher'), hook }];
+        }));
+    });
+}
+/** Whether Claude Code starts a line for a write, by the tools it is waited on for: one whose tools cannot be told is taken as started. */
+export function isStarted(tools) {
+    return tools === null || tools.length > 0;
 }
 /**
  * The release of Claude Code that reads `onFailure` on a hook's entry, by its
@@ -191,42 +295,116 @@ function describeOnFailure(where, blocks, 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`;
 }
+/** Names as a sentence lists them: one, two with "and", more with commas before it. Never asked of none. */
+function named(names) {
+    const last = names.at(-1);
+    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;
+}
+/** What a line's entries under `event` hold that decides when Claude Code starts them, as written. */
+function entriesUnder(event, entries) {
+    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 background = inBackground(hook) ? ' in the background' : '';
+        const rule = hook['if'] === undefined ? '' : ` with "if" ${JSON.stringify(hook['if'])}`;
+        return `${pattern}${background}${rule}`;
+    });
+    return `under ${event} it has ${named([...new Set(said)])}`;
+}
+/**
+ * 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.
+ */
+function describeCover(where, before, after, entries) {
+    const parts = [];
+    const left = (tools) => WRITING_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)})`);
+    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)})`);
+    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)})`);
+    }
+    if (after === null)
+        parts.push(`which writes it is started after cannot be told here (${entriesUnder(AFTER, entries)})`);
+    else if (after.length === 0)
+        parts.push(`it is started after no write, so it warns of none (${entriesUnder(AFTER, entries)})`);
+    else if (left(after).length > 0)
+        parts.push(`it is started after a write by ${named(after)} alone (${entriesUnder(AFTER, entries)})`);
+    return parts.length === 0 ? null : `${where}: ${parts.join('; ')}`;
+}
+/** 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));
+}
+/** The words handed over for every line of the harness's in the settings files, for a caller that has to ask something of each before it reports them. */
+export function handedLines(sources, project) {
+    return sources.flatMap(({ settings }) => writtenHooks(settings).map((hook) => handedWords(hook.words, project)));
+}
 /**
  * The lines of Claude Code's hook in the settings files, each with what the
- * hook does with it. `read` is the hook's own reading of the words it is
- * handed (usage.ts), `null` for a line that is not its; the words are handed
- * to it as Claude Code hands them to the hook, each `${CLAUDE_PROJECT_DIR}`
- * filled with `project`.
+ * hook does with it and which writes Claude Code starts it for. `read` is
+ * the hook's own reading of the words it is handed (usage.ts), `null` for a
+ * line that is not its; the words are handed to it as Claude Code hands them
+ * to the hook, each `${CLAUDE_PROJECT_DIR}` filled with `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: a problem, and doctor exits 1 for it.
+ * directory, 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.
  */
 export function reportHooks(sources, project, read) {
-    return sources.flatMap(({ file, settings }) => writtenHooks(settings).flatMap((hook) => {
-        const handed = read(hook.words.map((word) => word.split(PROJECT_DIR).join(project)));
-        if (handed === null)
-            return [];
-        const both = GUARDED_EVENTS.every((event) => hook.events.includes(event));
-        // An empty word is shown as a shell spells one, where joined it would not show at all.
-        // 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 written = { file, events: hook.events, line: hook.words, onFailure: hook.blocks ? 'block' : null };
-        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) }];
-        }
-        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) }];
-        }
-        // What a release wrote: its hook, and nothing after it.
-        if (sameStrings(hook.words, ['hook', 'claude']))
-            return [{ ...written, state: 'guards', detail: null, note: describeOnFailure(where, hook.blocks, false) }];
-        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: describeOnFailure(where, hook.blocks, false) }];
-    }));
+    return sources.flatMap(({ file, settings }) => {
+        const entries = harnessEntries(settings);
+        return writtenHooks(settings).flatMap((hook) => {
+            const handed = read(handedWords(hook.words, project));
+            if (handed === null)
+                return [];
+            const both = GUARDED_EVENTS.every((event) => hook.events.includes(event));
+            // An empty word is shown as a shell spells one, where joined it would not show at all.
+            // 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) };
+            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) }];
+            }
+            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 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 (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 }];
+            }
+            if (before === null)
+                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 }];
+            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 }];
+        });
+    });
 }
 /** Whether a project's `.mcp.json` registers a server under the harness's name, however it runs it. */
 export function registersServer(mcp) {
@@ -272,12 +450,17 @@ const PARTS = literal({
  * 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
  * double install for the person to settle: init removes nothing, since the
- * file is the repository's and a clone without the plugin relies on it.
+ * file is the repository's and a clone without the plugin relies on it. So
+ * is an entry `elsewhere`, in a settings file of the person's own, which
+ * init does not write and doctor fails all the same.
  */
-export function describeSkipped(plugin, part, present) {
+export function describeSkipped(plugin, part, present, elsewhere = []) {
     const words = PARTS[part];
     if (present)
         return `${isOn(plugin)} and brings ${words.brings} this file holds as well, so ${words.twice}: take ${words.entry} out of this file, or ${turnOff(plugin)}`;
+    if (elsewhere.length > 0) {
+        return `${isOn(plugin)} and brings ${words.brings} ${named(elsewhere)} ${elsewhere.length === 1 ? 'holds' : 'hold'} as well, so ${words.twice}: take ${words.entry} out there, or ${turnOff(plugin)}. init writes none here`;
+    }
     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. */