@descent-vtt/spec-harness 0.18.0 → 0.20.0

package/dist/hooks.js

@@ -36,6 +36,20 @@ const PATH_FIELDS = ['file_path', 'path', 'notebook_path'];
 function isObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+/**
+ * The event Claude Code runs as a session starts, resumes, is cleared or
+ * compacted, or is forked: no tool is named, and the hook checks what every
+ * write of the session will need (ADR-0005).
+ */
+export const SESSION_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 the configuration asks
+ * for it (ADR-0005). No tool is named.
+ */
+export const TURN_END = 'Stop';
+/** The events that name no tool, which the hook answers of the session and not of a write. */
+const NO_TOOL = [SESSION_START, TURN_END];
 /** Reads a Claude Code hook's stdin, or says why it cannot. */
 export function parseClaudeHook(raw) {
     let value;
@@ -49,24 +63,94 @@ export function parseClaudeHook(raw) {
         return { error: 'the hook input is not a JSON object' };
     const event = value['hook_event_name'];
     const tool = value['tool_name'];
-    if (typeof event !== 'string' || typeof tool !== 'string')
+    if (typeof event !== 'string' || (typeof tool !== 'string' && !NO_TOOL.includes(event)))
         return { error: 'the hook input names no event or tool' };
+    // A session's start and a turn's end name no tool, and are read as naming none.
+    const named = typeof tool === 'string' ? tool : '';
     const input = isObject(value['tool_input']) ? value['tool_input'] : {};
     const paths = [];
-    if (WRITING_TOOLS.includes(tool)) {
+    if (WRITING_TOOLS.includes(named)) {
         for (const field of PATH_FIELDS) {
             const path = input[field];
             if (typeof path === 'string' && path !== '' && !paths.includes(path))
                 paths.push(path);
         }
     }
-    const cwd = value['cwd'];
-    return { event, tool, cwd: typeof cwd === 'string' ? cwd : null, paths };
+    const text = (field) => {
+        const found = value[field];
+        return typeof found === 'string' ? found : null;
+    };
+    return { event, tool: named, cwd: text('cwd'), paths, session: text('session_id'), call: text('tool_use_id') };
+}
+/**
+ * The answer as a session starts: what would hold every write of it, in
+ * one line, for the person as `systemMessage` and for Claude as
+ * `additionalContext`; or nothing, where all is well. Always exit 0: the
+ * event cannot block, and a check that fails must not keep a session from
+ * starting.
+ */
+export function sessionResponse(problem) {
+    if (problem === null)
+        return NONE;
+    const said = `spec-harness: ${problem}`;
+    return { stdout: `${JSON.stringify({ systemMessage: said, hookSpecificOutput: { hookEventName: SESSION_START, additionalContext: said } })}\n`, exitCode: 0 };
+}
+/**
+ * The answer as a turn ends: the report, in one `systemMessage`, or
+ * nothing, where there is nothing to report. Always exit 0, and never a
+ * field that has Claude go on: `decision`, `additionalContext` and exit 2
+ * each continue the turn under Stop, and `continue: false` would stop one
+ * another hook continues. Claude Code shows a `systemMessage` to the person
+ * from an entry it waits on, and hands it to Claude on the next turn from
+ * one it runs in the background, as `init` writes it (ADR-0005, ADR-0012).
+ */
+export function turnResponse(report) {
+    if (report === null)
+        return NONE;
+    return { stdout: `${JSON.stringify({ systemMessage: report })}\n`, exitCode: 0 };
+}
+/**
+ * The answer before the one write a configuration that does not load lets
+ * through, a write to the configuration file itself: no decision, so that
+ * the person's own permission prompt stands as for any write the guard
+ * passes, and the line that says why every other write is held, for the
+ * person as `systemMessage` and for Claude as `additionalContext`, which
+ * Claude Code's hooks reference has a PreToolUse hook's answer carry
+ * (ADR-0005). Exit 0.
+ */
+export function mendResponse(said) {
+    const line = `spec-harness: ${said}`;
+    return { stdout: `${JSON.stringify({ systemMessage: line, hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: line } })}\n`, exitCode: 0 };
+}
+/** The answer that says nothing and decides nothing: the write goes on as the person's own permissions have it. */
+export const NONE = { stdout: '', exitCode: 0 };
+/**
+ * The answer where the hook checks nothing and says so, a question it cannot
+ * read or a line of its own that turns the guard off: one line, as
+ * `systemMessage`, which Claude Code's hooks reference has shown to the
+ * person on every event the hook answers, and exit 0. It decides nothing,
+ * so the call goes on as it would without the hook. It was exit 1, which
+ * the reference counts as a hook that failed: under `onFailure: "block"`,
+ * which holds the call of a hook that cannot start, it held every write of
+ * a session for a line only a write can mend (ADR-0005).
+ */
+export function warningResponse(said) {
+    return { stdout: `${JSON.stringify({ systemMessage: `spec-harness: ${said}` })}\n`, exitCode: 0 };
 }
-const NONE = { stdout: '', exitCode: 0 };
 function reasonOf(decisions) {
     return decisions.map((decision) => `spec-harness: ${decision.message}. Next: ${decision.hint}.`).join('\n');
 }
+/** The answer after a write: the warnings, as additional context for the model, or nothing. */
+export function afterResponse(warnings) {
+    if (warnings.length === 0)
+        return NONE;
+    return {
+        stdout: `${JSON.stringify({
+            hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: reasonOf(warnings) },
+        })}\n`,
+        exitCode: 0,
+    };
+}
 /**
  * The answer to a Claude Code hook: a refusal or a question before a write,
  * a warning after one, or nothing.
@@ -89,19 +173,91 @@ export function claudeResponse(event, decisions) {
             exitCode: 0,
         };
     }
-    if (event === 'PostToolUse') {
-        const warned = decisions.filter((decision) => decision.verdict === 'warn');
-        if (warned.length === 0)
-            return NONE;
-        return {
-            stdout: `${JSON.stringify({
-                hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: reasonOf(warned) },
-            })}\n`,
-            exitCode: 0,
-        };
-    }
+    if (event === 'PostToolUse')
+        return afterResponse(warningsOf(decisions));
     return NONE;
 }
+/** The decisions a run after the write would say: those that warn, each by its message and next step. */
+export function warningsOf(decisions) {
+    return decisions.filter((decision) => decision.verdict === 'warn').map(({ message, hint }) => ({ message, hint }));
+}
+/**
+ * What the hook reads besides its question and its line, as it decides: the
+ * project Claude Code names, the brief the environment names, and the
+ * branch a forge's CI names on a detached head (ADR-0004).
+ */
+export const CALL_VARIABLES = [
+    'CLAUDE_PROJECT_DIR',
+    'SPEC_BRIEF',
+    'GITHUB_HEAD_REF',
+    'GITHUB_REF_TYPE',
+    'GITHUB_REF_NAME',
+    'CI_MERGE_REQUEST_SOURCE_BRANCH_NAME',
+    'CI_COMMIT_BRANCH',
+];
+/** An id the hook names a file by: what Claude Code's ids are made of, and nothing a path could climb out by. */
+const ID = /^[\w-]{1,256}$/;
+/**
+ * The session a question is in, which spec-brief's answers are kept for,
+ * or `null` where it names none in the form Claude Code's ids have: such a
+ * question has every answer asked for afresh (ADR-0002).
+ */
+export function sessionOf(request) {
+    // The pattern reads null as "null", and what is answered is the session,
+    // null: the test of null is the compiler's, and its mutant equivalent.
+    return request.session !== null && ID.test(request.session) ? request.session : null;
+}
+/**
+ * The call a question is about, or `null` where it does not say which
+ * session and call it is, or says it in a form no file is named by.
+ */
+export function callRecord(request, line, started, env, release) {
+    const { session, call } = request;
+    if (session === null || call === null || !ID.test(session) || !ID.test(call))
+        return null;
+    return {
+        release,
+        session,
+        call,
+        tool: request.tool,
+        paths: request.paths,
+        cwd: request.cwd,
+        line: [line.root ?? null, line.brief ?? null, line.base ?? null],
+        started,
+        env: CALL_VARIABLES.map((name) => env[name] ?? null),
+    };
+}
+/** The name of the file a call's decisions are kept under. */
+export function callFile(record) {
+    return `${record.session}.${record.call}.json`;
+}
+/** What a run before the write keeps for the run after it: the call, and the warnings it decided. */
+export function keptCall(record, warnings) {
+    return `${JSON.stringify({ record, warnings })}\n`;
+}
+function isWarning(value) {
+    return isObject(value) && typeof value['message'] === 'string' && typeof value['hint'] === 'string';
+}
+/**
+ * The warnings kept for this call, or `null` where what was kept is not
+ * JSON, is another call's, or holds anything but warnings: such a call is
+ * decided as it was before anything was kept (ADR-0002).
+ */
+export function warningsKept(text, record) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        // Read as an empty object, a text that is not JSON holds no record
+        // either: that mutant is equivalent.
+        return null;
+    }
+    if (!isObject(value) || JSON.stringify(value['record']) !== JSON.stringify(record))
+        return null;
+    const warnings = value['warnings'];
+    return Array.isArray(warnings) && warnings.every(isWarning) ? warnings.map(({ message, hint }) => ({ message, hint })) : null;
+}
 /**
  * The answer to git's pre-commit hook: every file the commit would change
  * that the round may not, and exit 1 if any is refused. A warning prints and

package/dist/hooks.js.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The guard, spoken in the languages that ask it: an agent's pre- and\n * post-tool hooks, and git's pre-commit.\n *\n * Claude Code sends a hook one JSON object on stdin naming the tool and its\n * input. A file-editing tool names its file under `file_path`, `path` or\n * `notebook_path` depending on the tool and the release; all three are read,\n * because a guard that missed a renamed field would allow everything.\n *\n * What the answer may not do matters as much as what it does. Returning\n * `allow` from a pre-tool hook skips the person's own permission prompt, so\n * the guard never says `allow`: it says `deny`, or `ask`, or nothing. A\n * warning - a write outside the scope when the repository asked only to be\n * warned - is told to the model after the write, through the post-tool hook's\n * additional context, where it cannot unlock anything.\n */\n\nimport type { Decision } from './guard.js';\n\n/**\n * The tools whose input names a file they write, by every name a release of\n * Claude Code has had for one. The hook reads a path from each: a name more\n * costs nothing, and a Claude Code that still has the tool may send it.\n */\nexport const WRITING_TOOLS: readonly string[] = ['Edit', 'Write', 'MultiEdit', 'NotebookEdit'];\n\n/**\n * Those of them a Claude Code the harness runs under can call\n * (`CLAUDE_CODE_MINIMUM`, versions.ts). Its tools reference\n * (https://code.claude.com/docs/en/tools-reference, read 2026-10-12) has\n * `Edit`, `Write` and `NotebookEdit` in its table of tools, and no\n * `MultiEdit`, which its permissions page calls a legacy tool; and the tool\n * inputs each release declares hold a `MultiEdit` up to 1.0.128 and none\n * from 2.0.0 on (ADR-0005). So what doctor and init say of the writes a\n * line is started for names these alone: a tool nobody can call leaves no\n * write unchecked.\n */\nexport const CALLABLE_TOOLS: readonly string[] = ['Edit', 'Write', 'NotebookEdit'];\n\nconst PATH_FIELDS: readonly string[] = ['file_path', 'path', 'notebook_path'];\n\nexport interface HookRequest {\n  readonly event: string;\n  readonly tool: string;\n  /** The session's working directory, when the hook says. */\n  readonly cwd: string | null;\n  /** Files the tool writes, as the tool named them - absolute, usually. */\n  readonly paths: readonly string[];\n}\n\ntype Json = Record<string, unknown>;\n\nfunction isObject(value: unknown): value is Json {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\n/** Reads a Claude Code hook's stdin, or says why it cannot. */\nexport function parseClaudeHook(raw: string): HookRequest | { readonly error: string } {\n  let value: unknown;\n  try {\n    value = JSON.parse(raw);\n  } catch {\n    return { error: 'the hook input is not JSON' };\n  }\n  if (!isObject(value)) return { error: 'the hook input is not a JSON object' };\n  const event = value['hook_event_name'];\n  const tool = value['tool_name'];\n  if (typeof event !== 'string' || typeof tool !== 'string') return { error: 'the hook input names no event or tool' };\n  const input = isObject(value['tool_input']) ? value['tool_input'] : {};\n  const paths: string[] = [];\n  if (WRITING_TOOLS.includes(tool)) {\n    for (const field of PATH_FIELDS) {\n      const path = input[field];\n      if (typeof path === 'string' && path !== '' && !paths.includes(path)) paths.push(path);\n    }\n  }\n  const cwd = value['cwd'];\n  return { event, tool, cwd: typeof cwd === 'string' ? cwd : null, paths };\n}\n\nexport interface HookResponse {\n  /** What to print on stdout: JSON, or nothing. */\n  readonly stdout: string;\n  readonly exitCode: number;\n}\n\nconst NONE: HookResponse = { stdout: '', exitCode: 0 };\n\nfunction reasonOf(decisions: readonly Decision[]): string {\n  return decisions.map((decision) => `spec-harness: ${decision.message}. Next: ${decision.hint}.`).join('\\n');\n}\n\n/**\n * The answer to a Claude Code hook: a refusal or a question before a write,\n * a warning after one, or nothing.\n */\nexport function claudeResponse(event: string, decisions: readonly Decision[]): HookResponse {\n  if (event === 'PreToolUse') {\n    const denied = decisions.filter((decision) => decision.verdict === 'deny');\n    const asked = decisions.filter((decision) => decision.verdict === 'ask');\n    const decided = denied.length > 0 ? { verdict: 'deny', list: denied } : asked.length > 0 ? { verdict: 'ask', list: asked } : null;\n    if (decided === null) return NONE;\n    return {\n      stdout: `${JSON.stringify({\n        hookSpecificOutput: {\n          hookEventName: 'PreToolUse',\n          permissionDecision: decided.verdict,\n          permissionDecisionReason: reasonOf(decided.list),\n        },\n      })}\\n`,\n      exitCode: 0,\n    };\n  }\n  if (event === 'PostToolUse') {\n    const warned = decisions.filter((decision) => decision.verdict === 'warn');\n    if (warned.length === 0) return NONE;\n    return {\n      stdout: `${JSON.stringify({\n        hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: reasonOf(warned) },\n      })}\\n`,\n      exitCode: 0,\n    };\n  }\n  return NONE;\n}\n\n/**\n * The answer to git's pre-commit hook: every file the commit would change\n * that the round may not, and exit 1 if any is refused. A warning prints and\n * lets the commit through; a question has no one to ask in git, so it refuses.\n */\nexport function gitResponse(decisions: readonly Decision[]): { readonly text: string; readonly exitCode: number } {\n  const lines: string[] = [];\n  let refused = 0;\n  for (const decision of decisions) {\n    if (decision.verdict === 'allow') continue;\n    const blocking = decision.verdict === 'deny' || decision.verdict === 'ask';\n    if (blocking) refused += 1;\n    lines.push(`${blocking ? 'refused' : 'warning'}  ${decision.message}`, `         ${decision.hint}`);\n  }\n  if (refused > 0) lines.push(`spec-harness: ${refused} file(s) this round may not change; the commit was stopped`);\n  return { text: lines.length === 0 ? '' : `${lines.join('\\n')}\\n`, exitCode: refused > 0 ? 1 : 0 };\n}\n"]}
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The guard, spoken in the languages that ask it: an agent's pre- and\n * post-tool hooks, and git's pre-commit.\n *\n * Claude Code sends a hook one JSON object on stdin naming the tool and its\n * input. A file-editing tool names its file under `file_path`, `path` or\n * `notebook_path` depending on the tool and the release; all three are read,\n * because a guard that missed a renamed field would allow everything.\n *\n * What the answer may not do matters as much as what it does. Returning\n * `allow` from a pre-tool hook skips the person's own permission prompt, so\n * the guard never says `allow`: it says `deny`, or `ask`, or nothing. A\n * warning - a write outside the scope when the repository asked only to be\n * warned - is told to the model after the write, through the post-tool hook's\n * additional context, where it cannot unlock anything.\n */\n\nimport type { Decision } from './guard.js';\n\n/**\n * The tools whose input names a file they write, by every name a release of\n * Claude Code has had for one. The hook reads a path from each: a name more\n * costs nothing, and a Claude Code that still has the tool may send it.\n */\nexport const WRITING_TOOLS: readonly string[] = ['Edit', 'Write', 'MultiEdit', 'NotebookEdit'];\n\n/**\n * Those of them a Claude Code the harness runs under can call\n * (`CLAUDE_CODE_MINIMUM`, versions.ts). Its tools reference\n * (https://code.claude.com/docs/en/tools-reference, read 2026-10-12) has\n * `Edit`, `Write` and `NotebookEdit` in its table of tools, and no\n * `MultiEdit`, which its permissions page calls a legacy tool; and the tool\n * inputs each release declares hold a `MultiEdit` up to 1.0.128 and none\n * from 2.0.0 on (ADR-0005). So what doctor and init say of the writes a\n * line is started for names these alone: a tool nobody can call leaves no\n * write unchecked.\n */\nexport const CALLABLE_TOOLS: readonly string[] = ['Edit', 'Write', 'NotebookEdit'];\n\nconst PATH_FIELDS: readonly string[] = ['file_path', 'path', 'notebook_path'];\n\nexport interface HookRequest {\n  readonly event: string;\n  readonly tool: string;\n  /** The session's working directory, when the hook says. */\n  readonly cwd: string | null;\n  /** Files the tool writes, as the tool named them - absolute, usually. */\n  readonly paths: readonly string[];\n  /** The session and the tool call the question is about, when it says: `session_id` and `tool_use_id`. */\n  readonly session: string | null;\n  readonly call: string | null;\n}\n\ntype Json = Record<string, unknown>;\n\nfunction isObject(value: unknown): value is Json {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\n/**\n * The event Claude Code runs as a session starts, resumes, is cleared or\n * compacted, or is forked: no tool is named, and the hook checks what every\n * write of the session will need (ADR-0005).\n */\nexport const SESSION_START = 'SessionStart';\n\n/**\n * The event Claude Code runs as its main agent finishes a turn, under which\n * the hook reports what the work tree holds, where the configuration asks\n * for it (ADR-0005). No tool is named.\n */\nexport const TURN_END = 'Stop';\n\n/** The events that name no tool, which the hook answers of the session and not of a write. */\nconst NO_TOOL: readonly string[] = [SESSION_START, TURN_END];\n\n/** Reads a Claude Code hook's stdin, or says why it cannot. */\nexport function parseClaudeHook(raw: string): HookRequest | { readonly error: string } {\n  let value: unknown;\n  try {\n    value = JSON.parse(raw);\n  } catch {\n    return { error: 'the hook input is not JSON' };\n  }\n  if (!isObject(value)) return { error: 'the hook input is not a JSON object' };\n  const event = value['hook_event_name'];\n  const tool = value['tool_name'];\n  if (typeof event !== 'string' || (typeof tool !== 'string' && !NO_TOOL.includes(event))) return { error: 'the hook input names no event or tool' };\n  // A session's start and a turn's end name no tool, and are read as naming none.\n  const named = typeof tool === 'string' ? tool : '';\n  const input = isObject(value['tool_input']) ? value['tool_input'] : {};\n  const paths: string[] = [];\n  if (WRITING_TOOLS.includes(named)) {\n    for (const field of PATH_FIELDS) {\n      const path = input[field];\n      if (typeof path === 'string' && path !== '' && !paths.includes(path)) paths.push(path);\n    }\n  }\n  const text = (field: string): string | null => {\n    const found = value[field];\n    return typeof found === 'string' ? found : null;\n  };\n  return { event, tool: named, cwd: text('cwd'), paths, session: text('session_id'), call: text('tool_use_id') };\n}\n\n/**\n * The answer as a session starts: what would hold every write of it, in\n * one line, for the person as `systemMessage` and for Claude as\n * `additionalContext`; or nothing, where all is well. Always exit 0: the\n * event cannot block, and a check that fails must not keep a session from\n * starting.\n */\nexport function sessionResponse(problem: string | null): HookResponse {\n  if (problem === null) return NONE;\n  const said = `spec-harness: ${problem}`;\n  return { stdout: `${JSON.stringify({ systemMessage: said, hookSpecificOutput: { hookEventName: SESSION_START, additionalContext: said } })}\\n`, exitCode: 0 };\n}\n\n/**\n * The answer as a turn ends: the report, in one `systemMessage`, or\n * nothing, where there is nothing to report. Always exit 0, and never a\n * field that has Claude go on: `decision`, `additionalContext` and exit 2\n * each continue the turn under Stop, and `continue: false` would stop one\n * another hook continues. Claude Code shows a `systemMessage` to the person\n * from an entry it waits on, and hands it to Claude on the next turn from\n * one it runs in the background, as `init` writes it (ADR-0005, ADR-0012).\n */\nexport function turnResponse(report: string | null): HookResponse {\n  if (report === null) return NONE;\n  return { stdout: `${JSON.stringify({ systemMessage: report })}\\n`, exitCode: 0 };\n}\n\nexport interface HookResponse {\n  /** What to print on stdout: JSON, or nothing. */\n  readonly stdout: string;\n  readonly exitCode: number;\n}\n\n/**\n * The answer before the one write a configuration that does not load lets\n * through, a write to the configuration file itself: no decision, so that\n * the person's own permission prompt stands as for any write the guard\n * passes, and the line that says why every other write is held, for the\n * person as `systemMessage` and for Claude as `additionalContext`, which\n * Claude Code's hooks reference has a PreToolUse hook's answer carry\n * (ADR-0005). Exit 0.\n */\nexport function mendResponse(said: string): HookResponse {\n  const line = `spec-harness: ${said}`;\n  return { stdout: `${JSON.stringify({ systemMessage: line, hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: line } })}\\n`, exitCode: 0 };\n}\n\n/** The answer that says nothing and decides nothing: the write goes on as the person's own permissions have it. */\nexport const NONE: HookResponse = { stdout: '', exitCode: 0 };\n\n/**\n * The answer where the hook checks nothing and says so, a question it cannot\n * read or a line of its own that turns the guard off: one line, as\n * `systemMessage`, which Claude Code's hooks reference has shown to the\n * person on every event the hook answers, and exit 0. It decides nothing,\n * so the call goes on as it would without the hook. It was exit 1, which\n * the reference counts as a hook that failed: under `onFailure: \"block\"`,\n * which holds the call of a hook that cannot start, it held every write of\n * a session for a line only a write can mend (ADR-0005).\n */\nexport function warningResponse(said: string): HookResponse {\n  return { stdout: `${JSON.stringify({ systemMessage: `spec-harness: ${said}` })}\\n`, exitCode: 0 };\n}\n\nfunction reasonOf(decisions: readonly Warning[]): string {\n  return decisions.map((decision) => `spec-harness: ${decision.message}. Next: ${decision.hint}.`).join('\\n');\n}\n\n/** What a warning after a write says: a decision's message and its next step. */\nexport type Warning = Pick<Decision, 'message' | 'hint'>;\n\n/** The answer after a write: the warnings, as additional context for the model, or nothing. */\nexport function afterResponse(warnings: readonly Warning[]): HookResponse {\n  if (warnings.length === 0) return NONE;\n  return {\n    stdout: `${JSON.stringify({\n      hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: reasonOf(warnings) },\n    })}\\n`,\n    exitCode: 0,\n  };\n}\n\n/**\n * The answer to a Claude Code hook: a refusal or a question before a write,\n * a warning after one, or nothing.\n */\nexport function claudeResponse(event: string, decisions: readonly Decision[]): HookResponse {\n  if (event === 'PreToolUse') {\n    const denied = decisions.filter((decision) => decision.verdict === 'deny');\n    const asked = decisions.filter((decision) => decision.verdict === 'ask');\n    const decided = denied.length > 0 ? { verdict: 'deny', list: denied } : asked.length > 0 ? { verdict: 'ask', list: asked } : null;\n    if (decided === null) return NONE;\n    return {\n      stdout: `${JSON.stringify({\n        hookSpecificOutput: {\n          hookEventName: 'PreToolUse',\n          permissionDecision: decided.verdict,\n          permissionDecisionReason: reasonOf(decided.list),\n        },\n      })}\\n`,\n      exitCode: 0,\n    };\n  }\n  if (event === 'PostToolUse') return afterResponse(warningsOf(decisions));\n  return NONE;\n}\n\n/** The decisions a run after the write would say: those that warn, each by its message and next step. */\nexport function warningsOf(decisions: readonly Decision[]): Warning[] {\n  return decisions.filter((decision) => decision.verdict === 'warn').map(({ message, hint }) => ({ message, hint }));\n}\n\n/**\n * What the hook reads besides its question and its line, as it decides: the\n * project Claude Code names, the brief the environment names, and the\n * branch a forge's CI names on a detached head (ADR-0004).\n */\nexport const CALL_VARIABLES: readonly string[] = [\n  'CLAUDE_PROJECT_DIR',\n  'SPEC_BRIEF',\n  'GITHUB_HEAD_REF',\n  'GITHUB_REF_TYPE',\n  'GITHUB_REF_NAME',\n  'CI_MERGE_REQUEST_SOURCE_BRANCH_NAME',\n  'CI_COMMIT_BRANCH',\n];\n\n/**\n * A tool call, as both of its hooks see it: the release, the session and\n * the call, the tool and its paths, the session's directory, what the\n * hook's line gives, the directory the hook was started in, and the\n * variables it reads (ADR-0002). What a run before the write keeps is\n * answered after it only to a run for which all of it is the same.\n */\nexport interface CallRecord {\n  readonly release: string;\n  readonly session: string;\n  readonly call: string;\n  readonly tool: string;\n  readonly paths: readonly string[];\n  readonly cwd: string | null;\n  readonly line: readonly (string | null)[];\n  readonly started: string;\n  readonly env: readonly (string | null)[];\n}\n\n/** An id the hook names a file by: what Claude Code's ids are made of, and nothing a path could climb out by. */\nconst ID = /^[\\w-]{1,256}$/;\n\n/**\n * The session a question is in, which spec-brief's answers are kept for,\n * or `null` where it names none in the form Claude Code's ids have: such a\n * question has every answer asked for afresh (ADR-0002).\n */\nexport function sessionOf(request: HookRequest): string | null {\n  // The pattern reads null as \"null\", and what is answered is the session,\n  // null: the test of null is the compiler's, and its mutant equivalent.\n  return request.session !== null && ID.test(request.session) ? request.session : null;\n}\n\n/**\n * The call a question is about, or `null` where it does not say which\n * session and call it is, or says it in a form no file is named by.\n */\nexport function callRecord(\n  request: HookRequest,\n  line: Readonly<{ root: string | undefined; brief: string | undefined; base: string | undefined }>,\n  started: string,\n  env: Readonly<Record<string, string | undefined>>,\n  release: string,\n): CallRecord | null {\n  const { session, call } = request;\n  if (session === null || call === null || !ID.test(session) || !ID.test(call)) return null;\n  return {\n    release,\n    session,\n    call,\n    tool: request.tool,\n    paths: request.paths,\n    cwd: request.cwd,\n    line: [line.root ?? null, line.brief ?? null, line.base ?? null],\n    started,\n    env: CALL_VARIABLES.map((name) => env[name] ?? null),\n  };\n}\n\n/** The name of the file a call's decisions are kept under. */\nexport function callFile(record: CallRecord): string {\n  return `${record.session}.${record.call}.json`;\n}\n\n/** What a run before the write keeps for the run after it: the call, and the warnings it decided. */\nexport function keptCall(record: CallRecord, warnings: readonly Warning[]): string {\n  return `${JSON.stringify({ record, warnings })}\\n`;\n}\n\nfunction isWarning(value: unknown): value is Warning {\n  return isObject(value) && typeof value['message'] === 'string' && typeof value['hint'] === 'string';\n}\n\n/**\n * The warnings kept for this call, or `null` where what was kept is not\n * JSON, is another call's, or holds anything but warnings: such a call is\n * decided as it was before anything was kept (ADR-0002).\n */\nexport function warningsKept(text: string, record: CallRecord): Warning[] | null {\n  let value: unknown;\n  try {\n    value = JSON.parse(text);\n  } catch {\n    // Read as an empty object, a text that is not JSON holds no record\n    // either: that mutant is equivalent.\n    return null;\n  }\n  if (!isObject(value) || JSON.stringify(value['record']) !== JSON.stringify(record)) return null;\n  const warnings = value['warnings'];\n  return Array.isArray(warnings) && warnings.every(isWarning) ? warnings.map(({ message, hint }) => ({ message, hint })) : null;\n}\n\n/**\n * The answer to git's pre-commit hook: every file the commit would change\n * that the round may not, and exit 1 if any is refused. A warning prints and\n * lets the commit through; a question has no one to ask in git, so it refuses.\n */\nexport function gitResponse(decisions: readonly Decision[]): { readonly text: string; readonly exitCode: number } {\n  const lines: string[] = [];\n  let refused = 0;\n  for (const decision of decisions) {\n    if (decision.verdict === 'allow') continue;\n    const blocking = decision.verdict === 'deny' || decision.verdict === 'ask';\n    if (blocking) refused += 1;\n    lines.push(`${blocking ? 'refused' : 'warning'}  ${decision.message}`, `         ${decision.hint}`);\n  }\n  if (refused > 0) lines.push(`spec-harness: ${refused} file(s) this round may not change; the commit was stopped`);\n  return { text: lines.length === 0 ? '' : `${lines.join('\\n')}\\n`, exitCode: refused > 0 ? 1 : 0 };\n}\n"]}

package/dist/round.d.ts

@@ -127,10 +127,18 @@ export declare function claudeCodeWiring(root: string, io: CliIO, pattern?: Patt
  * wrong with the name when no round can work under it. Every other command
  * stops there. A diagnosis says it, being what a person runs when the guard
  * holds a write they expected it to pass.
+ *
+ * `branch` is whether the name no round can work under is the branch's: a
+ * brief it names that spec-brief does not know, or has archived. The hook
+ * reads the same branch and holds every write under such a name, which is a
+ * setup that holds every write, as a hook's line naming such a brief is
+ * (ADR-0004). A name the flag gives is the question doctor was asked, and
+ * holds no write of anyone's.
  */
 export declare function diagnoseBrief(workspace: Workspace, options: Pick<Options, 'brief'>, env: CliIO['env']): Promise<{
     readonly id: string | null;
     readonly problem: string | null;
+    readonly branch: boolean;
 }>;
 export interface AuditResult {
     readonly brief: BriefRow;

package/dist/round.js

@@ -17,9 +17,9 @@ import { fileURLToPath } from 'node:url';
 import { readArchivePlan, readGuardRun } from './answers.js';
 import { SiblingOutputError } from './briefs.js';
 import { sameId } from './branch.js';
-import { commasUnder, enabledPlugin, exportedFile, handedLines, hooksDisabled, HOSTED_REGISTRY, isStarted, loadsPlugin, MARKETPLACE_REGISTRY, patternReader, pluginMarketplace, pluginPresence, PROJECT_SETTINGS, registersServer, reportHooks, SPEC_BRIEF_CONFIGS, wiringState, } from './configure.js';
+import { arrayMatcher, enabledPlugin, exportedFile, handedLines, hooksDisabled, HOSTED_REGISTRY, isStarted, loadsPlugin, MARKETPLACE_REGISTRY, matchingUnder, patternReader, pluginMarketplace, pluginPresence, PROJECT_SETTINGS, readsOnFailure, registersServer, reportHooks, SPEC_BRIEF_CONFIGS, startsSessions, wiringState, } from './configure.js';
 import { readRules, renderContext } from './context.js';
-import { isDirectory, readJsonObject, readText, repositoryPath, stateDirectory, writeAtomic } from './fs.js';
+import { isDirectory, isFile, readJsonObject, readText, repositoryPath, stateDirectory, writeAtomic } from './fs.js';
 import { blameLine, changes, commonDirectory, isUncommitted, mergeBase, remoteDefault, revision, show, verifyCommit, workTreeRoot } from './git.js';
 import { decide } from './guard.js';
 import { diffManifest, ecosystemOf, readManifestNames } from './manifests.js';
@@ -310,7 +310,10 @@ export function pluginFile(root) {
         // or on the missing key inside this block, which the catch reads as no
         // installed copy: `exports?.` and `target !== null` are equivalent to
         // their mutants here. So is the encoding: a Buffer parses as its text.
-        const manifest = JSON.parse(readFileSync(join(installed, 'package.json'), 'utf8'));
+        // Only a file is read: what stands there and is none is no installed
+        // copy, as a manifest with no exports is (ADR-0002).
+        const file = join(installed, 'package.json');
+        const manifest = isFile(file) ? JSON.parse(readFileSync(file, 'utf8')) : {};
         const target = exportedFile(manifest.exports?.['./spec-brief-plugin']);
         if (target !== null)
             candidates.push(join(installed, target));
@@ -447,13 +450,21 @@ export async function claudeCodeWiring(root, io, pattern = patternReader(), repo
     const roots = marketplace === null ? [] : await Promise.all(pluginDirectories(io.env).map((directory) => pluginsRoot(directory, marketplace)));
     const presence = plugin === null ? null : pluginPresence(plugin, sources, roots);
     const server = registersServer(await readJsonObject(join(root, '.mcp.json')));
+    // A line under SessionStart is the hook's by the hook's own reading of it, as any line is.
+    // A root on it that is no directory is a line of the hook that is off, and
+    // one all the same, so the mutant of the test for a directory is
+    // equivalent.
+    const isHook = (words) => claudeHookLine(words, parseOptions, root, (path) => isDirectory(resolve(root, path))) !== null;
+    const sessionStart = sources.some(({ settings }) => startsSessions(settings, isHook));
+    // init writes its hooks into the project's file alone, and none where an array unloads it.
+    const unloaded = arrayMatcher(sources.find(({ file }) => file === PROJECT_SETTINGS).settings);
     const under = (release) => {
-        const lines = reportHooks(sources, root, (words) => read.get(JSON.stringify(words)), pattern, commasUnder(release));
+        const lines = reportHooks(sources, root, (words) => read.get(JSON.stringify(words)), pattern, matchingUnder(release), readsOnFailure(release));
         // A line Claude Code starts for no write, before one or after, is in no
         // one's way: it is said, and the file is not counted for it.
         const hooks = sources.map(({ file }) => file).filter((file) => lines.some((line) => line.file === file && (isStarted(line.before) || isStarted(line.after))));
         // In the order a document has them, which a script may compare by the byte.
-        return { plugin, presence, hooksOff: hooksDisabled(sources), hooks, lines, server, release };
+        return { plugin, presence, hooksOff: hooksDisabled(sources), hooks, lines, server, sessionStart, release, unloaded };
     };
     const untold = under(null);
     const asked = reported ? wiringState(untold) !== 'none' : JSON.stringify(untold.lines) !== JSON.stringify(reportHooks(sources, root, (words) => read.get(JSON.stringify(words)), pattern));
@@ -516,25 +527,34 @@ async function hookLineHere(words, root, io) {
  * wrong with the name when no round can work under it. Every other command
  * stops there. A diagnosis says it, being what a person runs when the guard
  * holds a write they expected it to pass.
+ *
+ * `branch` is whether the name no round can work under is the branch's: a
+ * brief it names that spec-brief does not know, or has archived. The hook
+ * reads the same branch and holds every write under such a name, which is a
+ * setup that holds every write, as a hook's line naming such a brief is
+ * (ADR-0004). A name the flag gives is the question doctor was asked, and
+ * holds no write of anyone's.
  */
 export async function diagnoseBrief(workspace, options, env) {
     if (options.brief !== undefined && isBlank(options.brief))
-        return { id: null, problem: emptyValue('--brief', 'brief', options.brief) };
+        return { id: null, problem: emptyValue('--brief', 'brief', options.brief), branch: false };
     const id = namedId(workspace, options, env);
     // A spec-brief that cannot be run is a row of the report, with the reason.
     if (workspace.siblings.locate('spec-brief').kind !== 'found')
-        return { id, problem: null };
+        return { id, problem: null, branch: false };
     try {
         // Where nothing names a brief, spec-brief is not asked (ADR-0004), and
         // there is no problem to state.
-        return { id, problem: describeActive(await activeBrief(workspace, options, env)).problem };
+        const active = await activeBrief(workspace, options, env);
+        const branch = (active.kind === 'unknown' || active.kind === 'archived') && active.source === 'branch';
+        return { id, problem: describeActive(active).problem, branch };
     }
     catch (error) {
         // Asking spec-brief throws nothing but this, so the check is equivalent
         // to its mutant; it keeps any other error the stack it needs.
         if (!(error instanceof SiblingError))
             throw error;
-        return { id, problem: `spec-brief could not say whether it knows brief ${id}: ${error.message}` };
+        return { id, problem: `spec-brief could not say whether it knows brief ${id}: ${error.message}`, branch: false };
     }
 }
 async function archiveReasons(workspace, brief, base) {
@@ -611,6 +631,9 @@ export async function listEscalations(workspace) {
     const directory = await escalationDirectory(workspace);
     const out = [];
     for (const name of (await readdir(directory)).filter((n) => n.endsWith('.json')).sort()) {
+        // What is no file is no request, and is passed over as one that cannot be read is.
+        if (!isFile(join(directory, name)))
+            continue;
         try {
             // A Buffer parses as its text, so the encoding is equivalent to its mutant.
             const request = JSON.parse(await readFile(join(directory, name), 'utf8'));