@deftai/directive-core 0.108.0 → 0.109.1

package/dist/hooks/tools.d.ts

@@ -1,12 +1,17 @@
+import type { ClassifyHookHost } from "./classify/types.js";
 /** Host spellings that install-time matchers and runtime classification share. */
-export declare const DIRECT_WRITE_TOOL_NAMES: readonly ["Edit", "Write", "WriteFile", "CreateFile", "MultiEdit", "NotebookEdit", "StrReplace", "SearchReplace", "Delete", "DeleteFile", "ApplyPatch", "apply_patch"];
+export declare const DIRECT_WRITE_TOOL_NAMES: readonly ["Edit", "Write", "WriteFile", "CreateFile", "MultiEdit", "NotebookEdit", "StrReplace", "SearchReplace", "Delete", "DeleteFile", "ApplyPatch", "apply_patch", "write", "search_replace"];
 /** PreToolUse spawn / sub-agent dispatch tools (#1185 / #2437). */
 export declare const SPAWN_TOOL_NAMES: readonly ["Task", "SubagentStart", "spawn_subagent", "start_agent", "CreateAgent"];
 /**
  * Host spellings for Shell/Bash execution tools (#2711).
  * Used for runtimeAuthority scopes.push / scopes.merge classification.
+ *
+ * `monitor` is Grok Build's second shell surface (#3987 audit): it executes an
+ * arbitrary shell command in the background, so leaving it out reproduces the
+ * `run_terminal_command` gap one tool over.
  */
-export declare const SHELL_TOOL_NAMES: readonly ["Shell", "Bash", "BashTool", "shell", "bash"];
+export declare const SHELL_TOOL_NAMES: readonly ["Shell", "Bash", "BashTool", "shell", "bash", "run_terminal_command", "monitor"];
 /** Env override forcing hook-level read-only write denial (#1185). */
 export declare const READ_ONLY_HOOK_ENV = "DEFT_HOOK_READ_ONLY";
 export declare function isDirectWriteTool(toolName: string): boolean;
@@ -32,6 +37,48 @@ export declare const MCP_PUSH_MERGE_BARE_NAMES: readonly ["merge_pull_request",
 export declare const DIRECT_WRITE_HOOK_MATCHER: string;
 export declare const SPAWN_HOOK_MATCHER: string;
 export declare const SHELL_HOOK_MATCHER: string;
+/** Mutation tool names a host emits, grouped by the matcher that must carry them. */
+export interface HostMutationToolCatalog {
+    readonly directWrite: readonly string[];
+    readonly shell: readonly string[];
+    readonly spawn: readonly string[];
+}
+/**
+ * One host's audited tool surface (#3987 acceptance item 2).
+ *
+ * The audit answers one question per tool name the host emits: is it in
+ * `mutation` (and therefore required to be a literal token of the deposited
+ * matcher AND recognized by the runtime classifier), or is it in `nonMutation`
+ * with the written reason it stays outside the gate? A name in neither is the
+ * silent gap this record exists to make loud.
+ *
+ * `unobservedReason` is the honest third state. The deposit asserting a
+ * spelling is not evidence that the host emits it, so a host whose PreToolUse
+ * payloads have not been observed says so rather than publishing a guess as
+ * coverage.
+ */
+export interface HostToolSurfaceAudit {
+    readonly mutation: HostMutationToolCatalog;
+    readonly nonMutation: Readonly<Record<string, string>>;
+    /** Null when the audit covers every name the host emits. */
+    readonly unobservedReason: string | null;
+    /** Where the observation came from, so a reader can re-run it. */
+    readonly source: string;
+}
+/**
+ * Per-host tool-surface audit (#3987). Read by the deterministic deposit
+ * coverage check, which fails closed when a host is absent from this table —
+ * so a newly supported host cannot silently ship with no coverage claim.
+ */
+export declare const HOST_TOOL_SURFACE_AUDIT: Readonly<Record<ClassifyHookHost, HostToolSurfaceAudit>>;
+/**
+ * Known Grok mutation tool names. Deposited matchers must cover each name (#3987).
+ * Projection of the per-host audit; kept as a named export for the #3990 tests.
+ */
+export declare const GROK_MUTATION_TOOL_CATALOG: HostMutationToolCatalog;
+/** Grok tools that are intentionally not mutation-gated, each with its reason. */
+export declare const GROK_NON_MUTATION_TOOLS: Readonly<Record<string, string>>;
+export declare function matcherHasLiteralToken(matcher: string, toolName: string): boolean;
 /**
  * PreToolUse matcher for MCP-class push/merge tools (#2711).
  * Regex-friendly for Claude/nested hosts. Prefer broad install match +

package/dist/hooks/tools.js

@@ -12,6 +12,8 @@ export const DIRECT_WRITE_TOOL_NAMES = [
     "DeleteFile",
     "ApplyPatch",
     "apply_patch",
+    "write",
+    "search_replace",
 ];
 /** PreToolUse spawn / sub-agent dispatch tools (#1185 / #2437). */
 export const SPAWN_TOOL_NAMES = [
@@ -24,8 +26,20 @@ export const SPAWN_TOOL_NAMES = [
 /**
  * Host spellings for Shell/Bash execution tools (#2711).
  * Used for runtimeAuthority scopes.push / scopes.merge classification.
+ *
+ * `monitor` is Grok Build's second shell surface (#3987 audit): it executes an
+ * arbitrary shell command in the background, so leaving it out reproduces the
+ * `run_terminal_command` gap one tool over.
  */
-export const SHELL_TOOL_NAMES = ["Shell", "Bash", "BashTool", "shell", "bash"];
+export const SHELL_TOOL_NAMES = [
+    "Shell",
+    "Bash",
+    "BashTool",
+    "shell",
+    "bash",
+    "run_terminal_command",
+    "monitor",
+];
 /** Env override forcing hook-level read-only write denial (#1185). */
 export const READ_ONLY_HOOK_ENV = "DEFT_HOOK_READ_ONLY";
 function normalizedToolName(toolName) {
@@ -87,6 +101,87 @@ export const MCP_PUSH_MERGE_BARE_NAMES = [
 export const DIRECT_WRITE_HOOK_MATCHER = DIRECT_WRITE_TOOL_NAMES.join("|");
 export const SPAWN_HOOK_MATCHER = SPAWN_TOOL_NAMES.join("|");
 export const SHELL_HOOK_MATCHER = SHELL_TOOL_NAMES.join("|");
+/**
+ * Per-host tool-surface audit (#3987). Read by the deterministic deposit
+ * coverage check, which fails closed when a host is absent from this table —
+ * so a newly supported host cannot silently ship with no coverage claim.
+ */
+export const HOST_TOOL_SURFACE_AUDIT = {
+    grok: {
+        mutation: {
+            directWrite: ["write", "search_replace"],
+            shell: ["run_terminal_command", "monitor"],
+            spawn: ["spawn_subagent"],
+        },
+        nonMutation: {
+            read_file: "read",
+            grep: "read",
+            list_dir: "read",
+            search_tool: "read",
+            web_search: "read",
+            web_fetch: "read",
+            todo_write: "session-local non-product scratch",
+            get_command_or_subagent_output: "poll, not a mutation; elapsed bound is evaluateInFlight",
+            wait_commands_or_subagents: "poll over already-dispatched work",
+            kill_command_or_subagent: "process control",
+            scheduler_delete: "removes a scheduled task; mutates no product path",
+            scheduler_list: "read",
+            enter_plan_mode: "session posture",
+            exit_plan_mode: "session posture",
+            image_gen: "writes generated media to session scratch, never a tracked product path",
+            image_edit: "writes generated media to session scratch, never a tracked product path",
+            image_to_video: "writes generated media to session scratch, never a tracked product path",
+            reference_to_video: "writes generated media to session scratch, never a tracked product path",
+            scheduler_create: "spawn-class and NOT covered: gating it routes a scheduling primitive through the " +
+                "full spawn stack (ritual + active xBRIEF), a new deny class that needs a deliberate " +
+                "policy decision rather than a coverage edit (#3987 residual)",
+            use_tool: "mcp-class and NOT covered: the dispatcher classifies on the outer tool name, and the " +
+                "MCP tool actually invoked is nested in tool_input.tool_name, so a matcher entry alone " +
+                "buys a hook invocation and no enforcement; reading the inner name is a classifier " +
+                "change, not a matcher change (#3987 residual)",
+        },
+        unobservedReason: null,
+        source: "Observed directly on Grok Build: this host's published tool list, plus the 5,354-call " +
+            "session census recorded on issue #3987.",
+    },
+    claude: {
+        mutation: { directWrite: [], shell: ["Bash"], spawn: [] },
+        nonMutation: {},
+        unobservedReason: "Only the shell spelling is established (`Bash`, re-derived from the deposits by the " +
+            "#3987 panel's completing seat 5471374558 F8). No PreToolUse payload for this host has " +
+            "been observed in this tree, so the direct-write and spawn spellings stay unclaimed " +
+            "rather than asserted from the deposit that is supposed to be under test.",
+        source: "Issue #3987 comment 5471374558 finding F8.",
+    },
+    codex: {
+        mutation: { directWrite: ["apply_patch"], shell: ["shell"], spawn: [] },
+        nonMutation: {},
+        unobservedReason: "Shell (`shell`) and the apply_patch write form are established — F8 for the shell " +
+            "spelling, #3614 for the Codex apply_patch payload path. The rest of this host's surface " +
+            "has not been observed in this tree.",
+        source: "Issue #3987 comment 5471374558 finding F8; #3614 Codex apply_patch handling.",
+    },
+    cursor: {
+        mutation: { directWrite: [], shell: [], spawn: [] },
+        nonMutation: {},
+        unobservedReason: "Unverified. Nothing in this tree establishes which tool names Cursor emits on " +
+            "preToolUse: the deposit asserts a matcher string and the fixture corpus asserts the " +
+            "framework's own assumption, neither of which observes the host. Cursor could be a " +
+            "second zero-coverage host by the exact mechanism that produced #3987 (5471374558 F8), " +
+            "and claiming coverage here would hide that.",
+        source: "Issue #3987 comment 5471374558 finding F8.",
+    },
+};
+/**
+ * Known Grok mutation tool names. Deposited matchers must cover each name (#3987).
+ * Projection of the per-host audit; kept as a named export for the #3990 tests.
+ */
+export const GROK_MUTATION_TOOL_CATALOG = HOST_TOOL_SURFACE_AUDIT.grok.mutation;
+/** Grok tools that are intentionally not mutation-gated, each with its reason. */
+export const GROK_NON_MUTATION_TOOLS = HOST_TOOL_SURFACE_AUDIT.grok.nonMutation;
+export function matcherHasLiteralToken(matcher, toolName) {
+    return matcher.split("|").includes(toolName);
+}
 /**
  * PreToolUse matcher for MCP-class push/merge tools (#2711).
  * Regex-friendly for Claude/nested hosts. Prefer broad install match +

package/dist/init-deposit/agent-hooks.d.ts

@@ -27,6 +27,8 @@ export declare const CURSOR_TOOL_BEFORE_TIMEOUT_SECONDS = 30;
 /** Nested Claude/Grok/Codex command-hook default timeout (seconds). */
 export declare const NESTED_HOOK_TIMEOUT_SECONDS = 5;
 export type AgentHookPath = (typeof AGENT_HOOK_PATHS)[number];
+/** Deposit file each supported host reads its PreToolUse registration from. */
+export declare const AGENT_HOOK_PATH_BY_HOST: Readonly<Record<HookHost, AgentHookPath>>;
 export type AgentHookRegistrationStatus = "healthy" | "disabled" | "missing" | "drifted";
 /** Whether the host receives a compact/resume hook deposit (#2113). */
 export type AgentHookCompactSupport = "deposited" | "unsupported";
@@ -43,6 +45,14 @@ export interface AgentHookDepositResult {
 }
 /** Merge Directive-owned project hook entries without replacing user configuration. */
 export declare function writeAgentHookDeposit(projectRoot: string, io?: InitDepositIo, hostHooksPolicy?: HostHooksPolicy, travelSeams?: HookRuntimeTravelSeams): AgentHookDepositResult;
+/**
+ * PreToolUse matchers a host would actually match against, read from the
+ * deposited file rather than regenerated from the constants (#3987).
+ *
+ * Null means the deposit is absent or unreadable — a different failure with a
+ * different remediation, already reported by `inspectAgentHookDeposit`.
+ */
+export declare function depositedPreToolUseMatchers(projectRoot: string, host: HookHost): readonly string[] | null;
 /** Read-only registration probe shared by verify and doctor. */
 export declare function inspectAgentHookDeposit(projectRoot: string, hostHooksPolicy?: HostHooksPolicy): AgentHookInspection[];
 //# sourceMappingURL=agent-hooks.d.ts.map

package/dist/init-deposit/agent-hooks.js

@@ -34,6 +34,13 @@ export const CURSOR_SESSION_HOOK_TIMEOUT_SECONDS = 5;
 export const CURSOR_TOOL_BEFORE_TIMEOUT_SECONDS = 30;
 /** Nested Claude/Grok/Codex command-hook default timeout (seconds). */
 export const NESTED_HOOK_TIMEOUT_SECONDS = 5;
+/** Deposit file each supported host reads its PreToolUse registration from. */
+export const AGENT_HOOK_PATH_BY_HOST = {
+    claude: AGENT_HOOK_PATHS[0],
+    grok: AGENT_HOOK_PATHS[1],
+    cursor: AGENT_HOOK_PATHS[2],
+    codex: AGENT_HOOK_PATHS[3],
+};
 function object(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value)
         ? value
@@ -404,6 +411,38 @@ function hasCursorRegistration(config) {
         preTool.some((entry) => isCursorToolBeforeEntry(entry, MCP_HOOK_MATCHER)) &&
         preCompact.some((entry) => object(entry)?.command === command("cursor", "session.compact")));
 }
+/**
+ * PreToolUse matchers a host would actually match against, read from the
+ * deposited file rather than regenerated from the constants (#3987).
+ *
+ * Null means the deposit is absent or unreadable — a different failure with a
+ * different remediation, already reported by `inspectAgentHookDeposit`.
+ */
+export function depositedPreToolUseMatchers(projectRoot, host) {
+    const path = join(resolve(projectRoot), AGENT_HOOK_PATH_BY_HOST[host]);
+    if (!existsSync(path))
+        return null;
+    let config;
+    try {
+        config = readConfig(path);
+    }
+    catch {
+        return null;
+    }
+    const hooks = object(config.hooks);
+    if (hooks === null)
+        return [];
+    const matcherOf = (entry) => {
+        const matcher = object(entry)?.matcher;
+        return typeof matcher === "string" ? [matcher] : [];
+    };
+    if (host === "cursor") {
+        const entries = Array.isArray(hooks.preToolUse) ? hooks.preToolUse : [];
+        return entries.filter(isManagedCursorEntry).flatMap(matcherOf);
+    }
+    const entries = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : [];
+    return entries.filter((entry) => isManagedNestedGroupForHost(entry, host)).flatMap(matcherOf);
+}
 /** Read-only registration probe shared by verify and doctor. */
 export function inspectAgentHookDeposit(projectRoot, hostHooksPolicy = loadHostHooksPolicyFromProject(projectRoot)) {
     const definitions = [

package/dist/init-deposit/gitignore.d.ts

@@ -25,6 +25,13 @@ export interface ReconstituteDepositResult {
     readonly reconstituted: boolean;
 }
 export type GitLsFiles = (projectDir: string, paths: readonly string[]) => string | null;
+/**
+ * Strip leading/trailing slashes so `.deft/cache/` and `.deft/cache` match.
+ * Globs are not expanded: a writer covered only by a glob fails closed (#3612).
+ */
+export declare function normalizeGitignorePath(p: string): string;
+export declare function gitignoreRuleCoversPath(rule: string, relPath: string): boolean;
+export declare function ignoreSetCoversPath(rules: readonly string[], relPath: string): boolean;
 /**
  * Reports whether `.deft/core` is tracked in git. Returns `null` when git is
  * unavailable or the tree is not a repository (treated as greenfield).

package/dist/init-deposit/gitignore.js

@@ -31,6 +31,13 @@ export const CANONICAL_GITIGNORE_BASELINE = [
     ".deft/last-session.json",
     ".deft/occupancy.json",
     ".deft/routing.local.json",
+    // #3612: remaining runtime writer roots kept at historical names (on-disk
+    // contracts). Relocating them would break existing consumer state.
+    ".deft/authz/",
+    ".deft/delivery-attempts/",
+    ".deft/metrics/",
+    ".deft/escalations/",
+    ".deft/approved-scope/",
     // Agent-host working state (#3502). Selective, NEVER blanket `.claude/`:
     // `.claude/settings.json`, `.claude/skills/` and `.claude/commands/` are
     // MANAGED DEPOSITS (agent-hooks.ts / skill-discovery-hosts.ts) and must stay
@@ -105,6 +112,23 @@ function gitignoreCoversLine(present, line) {
     }
     return false;
 }
+/**
+ * Strip leading/trailing slashes so `.deft/cache/` and `.deft/cache` match.
+ * Globs are not expanded: a writer covered only by a glob fails closed (#3612).
+ */
+export function normalizeGitignorePath(p) {
+    return p.replaceAll("\\", "/").replace(/^\/+/, "").replace(/\/+$/, "");
+}
+export function gitignoreRuleCoversPath(rule, relPath) {
+    const r = normalizeGitignorePath(stripGitignoreInlineComment(rule));
+    const p = normalizeGitignorePath(relPath);
+    if (!r || r.startsWith("#"))
+        return false;
+    return r === p || p.startsWith(`${r}/`);
+}
+export function ignoreSetCoversPath(rules, relPath) {
+    return rules.some((rule) => gitignoreRuleCoversPath(rule, relPath));
+}
 function collectPresentGitignoreLines(existing) {
     const present = new Set();
     for (const raw of existing.split("\n")) {

package/dist/init-deposit/host-tool-coverage.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Deterministic host tool-surface coverage check (#3987 acceptance item 3).
+ *
+ * #3990 shipped a Grok-only catalog asserted by a unit test against the
+ * generated matcher constants. That cannot catch what the acceptance item
+ * names: a host whose deposit went stale, or a host added with no coverage
+ * claim at all (5471374558 F7). This check reads the deposited files, walks
+ * every supported host, and fails closed on four distinct silences:
+ *
+ * 1. A supported host with no audit entry — the "new host drops out of
+ *    coverage" case. The typed `HOST_TOOL_SURFACE_AUDIT` record makes this a
+ *    compile error inside this package; the runtime check covers hosts added
+ *    to the deposit list alone.
+ * 2. A catalogued mutation tool name that is not a literal token of any
+ *    deposited matcher — the "renamed tool drops out of coverage" case. Read
+ *    from the deposit, so a stale file fails even when the constants are right.
+ * 3. A catalogued mutation tool name the runtime classifier does not place in
+ *    the same group. The deposited matcher is a literal alternation while the
+ *    classifier lowercases and strips punctuation, so the two layers can
+ *    disagree on a name that is present in both.
+ * 4. An audit entry that claims something without saying why: an empty
+ *    out-of-scope reason, a host claiming a fully observed surface while naming
+ *    no mutation tool, or a non-mutation entry the classifier actually gates.
+ */
+import { type HookHost } from "../hooks/dispatcher.js";
+import { type HostHooksPolicy } from "../policy/host-hooks.js";
+import { type AgentHookPath } from "./agent-hooks.js";
+export type HostToolCoverageFindingKind = 
+/** Supported host with no entry in the audit table. */
+"missing-audit"
+/** Catalogued mutation name absent from every deposited matcher. */
+ | "uncovered-tool"
+/** Deposited name the runtime classifier does not place in the same group. */
+ | "unclassified-tool"
+/** Audit entry that asserts without a written reason. */
+ | "unexplained-entry";
+export interface HostToolCoverageFinding {
+    readonly host: HookHost;
+    readonly path: AgentHookPath;
+    readonly kind: HostToolCoverageFindingKind;
+    readonly toolName: string | null;
+    readonly detail: string;
+}
+/**
+ * Read-only per-host coverage probe over the deposited matchers.
+ * A host whose deposit is missing or unreadable is skipped: that is a
+ * registration failure with its own remediation, reported by
+ * `inspectAgentHookDeposit`, and reporting it twice hides which one to fix.
+ */
+export declare function inspectHostToolCoverage(projectRoot: string, hostHooksPolicy: HostHooksPolicy): readonly HostToolCoverageFinding[];
+/** Remediation line for the coverage class, distinct from the deposit-refresh one. */
+export declare const HOST_TOOL_COVERAGE_RECOVERY: string;
+//# sourceMappingURL=host-tool-coverage.d.ts.map

package/dist/init-deposit/host-tool-coverage.js

@@ -0,0 +1,150 @@
+/**
+ * Deterministic host tool-surface coverage check (#3987 acceptance item 3).
+ *
+ * #3990 shipped a Grok-only catalog asserted by a unit test against the
+ * generated matcher constants. That cannot catch what the acceptance item
+ * names: a host whose deposit went stale, or a host added with no coverage
+ * claim at all (5471374558 F7). This check reads the deposited files, walks
+ * every supported host, and fails closed on four distinct silences:
+ *
+ * 1. A supported host with no audit entry — the "new host drops out of
+ *    coverage" case. The typed `HOST_TOOL_SURFACE_AUDIT` record makes this a
+ *    compile error inside this package; the runtime check covers hosts added
+ *    to the deposit list alone.
+ * 2. A catalogued mutation tool name that is not a literal token of any
+ *    deposited matcher — the "renamed tool drops out of coverage" case. Read
+ *    from the deposit, so a stale file fails even when the constants are right.
+ * 3. A catalogued mutation tool name the runtime classifier does not place in
+ *    the same group. The deposited matcher is a literal alternation while the
+ *    classifier lowercases and strips punctuation, so the two layers can
+ *    disagree on a name that is present in both.
+ * 4. An audit entry that claims something without saying why: an empty
+ *    out-of-scope reason, a host claiming a fully observed surface while naming
+ *    no mutation tool, or a non-mutation entry the classifier actually gates.
+ */
+import { HOOK_HOSTS } from "../hooks/dispatcher.js";
+import { HOST_TOOL_SURFACE_AUDIT, isDirectWriteTool, isShellTool, isSpawnTool, matcherHasLiteralToken, } from "../hooks/tools.js";
+import { isHostHookDepositEnabled } from "../policy/host-hooks.js";
+import { AGENT_HOOK_PATH_BY_HOST, depositedPreToolUseMatchers, } from "./agent-hooks.js";
+const CLASSIFIERS = {
+    directWrite: isDirectWriteTool,
+    shell: isShellTool,
+    spawn: isSpawnTool,
+};
+const MUTATION_GROUPS = ["directWrite", "shell", "spawn"];
+function auditFor(host) {
+    return HOST_TOOL_SURFACE_AUDIT[host];
+}
+function checkAuditShape(host, path, audit) {
+    const findings = [];
+    const mutationNames = MUTATION_GROUPS.flatMap((group) => audit.mutation[group]);
+    if (audit.unobservedReason !== null && audit.unobservedReason.trim().length === 0) {
+        findings.push({
+            host,
+            path,
+            kind: "unexplained-entry",
+            toolName: null,
+            detail: "unobservedReason is present but empty — say what was not observed, or set it null.",
+        });
+    }
+    if (audit.unobservedReason === null && mutationNames.length === 0) {
+        findings.push({
+            host,
+            path,
+            kind: "unexplained-entry",
+            toolName: null,
+            detail: "the audit claims a fully observed surface yet names no mutation tool. Either list the " +
+                "host's mutation spellings or record why the surface is unobserved.",
+        });
+    }
+    if (audit.source.trim().length === 0) {
+        findings.push({
+            host,
+            path,
+            kind: "unexplained-entry",
+            toolName: null,
+            detail: "source is empty — a coverage claim must name where it was observed.",
+        });
+    }
+    for (const [toolName, reason] of Object.entries(audit.nonMutation)) {
+        if (reason.trim().length === 0) {
+            findings.push({
+                host,
+                path,
+                kind: "unexplained-entry",
+                toolName,
+                detail: "listed out of scope with no written reason.",
+            });
+            continue;
+        }
+        const gated = MUTATION_GROUPS.find((group) => CLASSIFIERS[group](toolName));
+        if (gated !== undefined) {
+            findings.push({
+                host,
+                path,
+                kind: "unexplained-entry",
+                toolName,
+                detail: `recorded as out of scope, but the runtime classifier gates it as ${gated}.`,
+            });
+        }
+    }
+    return findings;
+}
+/**
+ * Read-only per-host coverage probe over the deposited matchers.
+ * A host whose deposit is missing or unreadable is skipped: that is a
+ * registration failure with its own remediation, reported by
+ * `inspectAgentHookDeposit`, and reporting it twice hides which one to fix.
+ */
+export function inspectHostToolCoverage(projectRoot, hostHooksPolicy) {
+    const findings = [];
+    for (const host of HOOK_HOSTS) {
+        const path = AGENT_HOOK_PATH_BY_HOST[host];
+        if (!isHostHookDepositEnabled(host, hostHooksPolicy))
+            continue;
+        const audit = auditFor(host);
+        if (audit === undefined) {
+            findings.push({
+                host,
+                path,
+                kind: "missing-audit",
+                toolName: null,
+                detail: "supported host has no entry in HOST_TOOL_SURFACE_AUDIT, so nothing states which of " +
+                    "its tool names must be covered.",
+            });
+            continue;
+        }
+        findings.push(...checkAuditShape(host, path, audit));
+        const matchers = depositedPreToolUseMatchers(projectRoot, host);
+        if (matchers === null)
+            continue;
+        for (const group of MUTATION_GROUPS) {
+            for (const toolName of audit.mutation[group]) {
+                if (!matchers.some((matcher) => matcherHasLiteralToken(matcher, toolName))) {
+                    findings.push({
+                        host,
+                        path,
+                        kind: "uncovered-tool",
+                        toolName,
+                        detail: `${group} tool is absent from every deposited PreToolUse matcher.`,
+                    });
+                }
+                if (!CLASSIFIERS[group](toolName)) {
+                    findings.push({
+                        host,
+                        path,
+                        kind: "unclassified-tool",
+                        toolName,
+                        detail: `${group} tool is not recognized by the runtime ${group} classifier.`,
+                    });
+                }
+            }
+        }
+    }
+    return findings;
+}
+/** Remediation line for the coverage class, distinct from the deposit-refresh one. */
+export const HOST_TOOL_COVERAGE_RECOVERY = "Recovery: run `deft update` to re-deposit the current matchers. If a finding survives that, " +
+    "the tool name is missing from Directive's own catalog rather than from your deposit — report " +
+    "it upstream with the host and tool name. Audit record: .deft/core/docs/host-tool-surface-audit.md (#3987).";
+//# sourceMappingURL=host-tool-coverage.js.map

package/dist/init-deposit/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./agent-hooks.js";
 export * from "./headless-manifest.js";
+export * from "./host-tool-coverage.js";
 export * from "./init-deposit.js";
 export * from "./init-dispatch.js";
 export * from "./legacy-detect.js";

package/dist/init-deposit/index.js

@@ -1,5 +1,6 @@
 export * from "./agent-hooks.js";
 export * from "./headless-manifest.js";
+export * from "./host-tool-coverage.js";
 export * from "./init-deposit.js";
 export * from "./init-dispatch.js";
 export * from "./legacy-detect.js";

package/dist/init-deposit/init-deposit.js

@@ -10,6 +10,7 @@ import { homedir, platform } from "node:os";
 import { basename, join, resolve } from "node:path";
 import { assertDepositContained } from "../deposit/contain.js";
 import { copyTree } from "../deposit/copy-tree.js";
+import { assertLiveProcedureDepositClean } from "../deposit/live-procedure-targets.js";
 import { prunePythonArtifactsFromDeposit } from "../deposit/python-free.js";
 import { resolveInstalledContentRoot } from "../deposit/resolve-content.js";
 import { readCorePackageVersion } from "../engine-version.js";
@@ -173,8 +174,10 @@ export async function runInitDeposit(args, io, seams = {}) {
     const resolveContent = seams.resolveContentRoot ?? resolveInstalledContentRoot;
     const copyContent = seams.copyContent ?? copyTree;
     const contentRoot = await resolveContent();
+    assertLiveProcedureDepositClean(contentRoot);
     await reconstituteDepositFromContent(contentRoot, deftDir, copyContent);
     await prunePythonArtifactsFromDeposit(deftDir, projectDir, io);
+    assertLiveProcedureDepositClean(deftDir);
     ensureInitGitignoreLines(projectDir, io);
     ensurePrettierIgnoreLines(projectDir, io);
     const nowIso = seams.nowIso ?? (() => new Date().toISOString().replace(/\.\d{3}Z$/, "Z"));

package/dist/init-deposit/refresh.js

@@ -13,6 +13,7 @@ import { platform as osPlatform } from "node:os";
 import { join, resolve } from "node:path";
 import { assertDepositContained } from "../deposit/contain.js";
 import { replaceTree } from "../deposit/copy-tree.js";
+import { assertLiveProcedureDepositClean } from "../deposit/live-procedure-targets.js";
 import { prunePythonArtifactsFromDeposit } from "../deposit/python-free.js";
 import { resolveInstalledContentRoot } from "../deposit/resolve-content.js";
 import { manifestTagToVersion, parseInstallManifest } from "../doctor/manifest.js";
@@ -476,9 +477,12 @@ export async function runRefreshDeposit(args, io, seams = {}) {
     const strategy = alreadyCurrent ? "no-op" : "file-swap";
     if (alreadyCurrent) {
         io.printf("[deft update] Framework payload already current; skipping payload copy.\n");
+        // C3 even when VERSION matches: skip-copy is not skip-validation (#3602).
+        assertLiveProcedureDepositClean(contentRoot);
         // #2913: still fail-closed reconcile so dst-only leftovers cannot linger when
         // VERSION already matches (e.g. pre-#2804 additive deposits). Does not re-stamp.
         await reconcileDepositToContentPackage(deftDir, contentRoot, io);
+        assertLiveProcedureDepositClean(deftDir);
         migrateLegacyInstallManifest(projectDir, join(deftDir, "VERSION"));
         // #3117: ensure a readable live generation token exists without advancing
         // when the payload did not swap (already-current). stampLiveGeneration is a
@@ -504,8 +508,11 @@ export async function runRefreshDeposit(args, io, seams = {}) {
     }
     else {
         // Full-tree replace (or injected seam). Additive copy is no longer the default.
+        // C3 the incoming package BEFORE replace so a reject cannot leave a broken deposit.
+        assertLiveProcedureDepositClean(contentRoot);
         await copyContent(contentRoot, deftDir);
         await prunePythonArtifactsFromDeposit(deftDir, projectDir, io);
+        assertLiveProcedureDepositClean(deftDir);
         // #2913 / #2804 / #2347: fail-closed delete-not-in-source BEFORE VERSION stamp.
         // replaceTree already drops dst-only paths; reconcile verifies and covers
         // additive seams. Throws => no VERSION rewrite (refuse stamp until clean).

package/dist/init-deposit/runtime-writers.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Runtime writer paths that land in a consumer working tree (#3612).
+ *
+ * The ignore baselines and this list are coupled: every exported writer path
+ * constant MUST appear here, and a fail-closed test asserts the ignore set
+ * covers each entry on both shipped surfaces. New writers join this registry;
+ * they do not get a silent extra .deft/ name.
+ */
+/**
+ * Imported writer path constants. Order is the lockstep contract with
+ * runtime-writer-paths.json (Go reads that file).
+ */
+export declare const RUNTIME_WRITER_PATHS: readonly string[];
+//# sourceMappingURL=runtime-writers.d.ts.map

package/dist/init-deposit/runtime-writers.js

@@ -0,0 +1,33 @@
+/**
+ * Runtime writer paths that land in a consumer working tree (#3612).
+ *
+ * The ignore baselines and this list are coupled: every exported writer path
+ * constant MUST appear here, and a fail-closed test asserts the ignore set
+ * covers each entry on both shipped surfaces. New writers join this registry;
+ * they do not get a silent extra .deft/ name.
+ */
+import { AUTHZ_DIR } from "../authz/types.js";
+import { DEFAULT_TASK_CACHE_ROOT } from "../cache/task-cache/constants.js";
+import { SESSION_COMPLETED_MARKER_REL } from "../check/session-completed-ac.js";
+import { DELIVERY_ATTEMPT_DIR } from "../delivery-attempt/types.js";
+import { ESCALATION_DIR } from "../escalation/types.js";
+import { PROJECT_LOCAL_METRICS_DIR } from "../metrics/resolve-metrics-home.js";
+import { APPROVED_SCOPE_DIR } from "../scope-provenance/digest.js";
+import { AC_PASS_BANK_DIR } from "../session/ac-pass-banking.js";
+import { VERIFY_AC_SESSION_CACHE_DIR } from "../session/verify-ac-session-cache.js";
+/**
+ * Imported writer path constants. Order is the lockstep contract with
+ * runtime-writer-paths.json (Go reads that file).
+ */
+export const RUNTIME_WRITER_PATHS = Object.freeze([
+    AC_PASS_BANK_DIR,
+    VERIFY_AC_SESSION_CACHE_DIR,
+    SESSION_COMPLETED_MARKER_REL.join("/"),
+    AUTHZ_DIR,
+    DELIVERY_ATTEMPT_DIR,
+    PROJECT_LOCAL_METRICS_DIR,
+    ESCALATION_DIR,
+    APPROVED_SCOPE_DIR,
+    DEFAULT_TASK_CACHE_ROOT,
+]);
+//# sourceMappingURL=runtime-writers.js.map