@deftai/directive-core 0.109.0 → 0.109.1

package/dist/session/occupancy.js

@@ -19,6 +19,25 @@
  * composite hook write gate measures the tree's verified ritual owner against
  * the occupant that issued the grant, not against the writer.
  *
+ * Parent and child, answered per identity-source kind (#3954, and it does not
+ * have one answer). On a `host-env` host the parent and its dispatched children
+ * are different actors, because the host publishes a different id into each
+ * agent session. The answer there is identity, not automatic membership: each
+ * side resolves its own owner through the shared lookup chain below and claims
+ * its own worktree, which is where the dispatch envelope already puts it.
+ * Membership stays explicit and owner-issued for the deliberate same-tree case,
+ * and it stays affordable only that way -- 32 grants at a four-hour TTL against
+ * a twenty-minute lease means granting on every dispatch exhausts a busy
+ * parent's lease inside a day. The revocation trigger is therefore the owner's
+ * own `occupancy:grant --revoke`, or expiry; releasing a child's lease on its
+ * terminal event is dispatcher lifecycle in `child-occupancy.ts` (#3999).
+ * On a `payload` host parent and subagents share one id, so there is no foreign
+ * child lease to admit and nothing to grant -- and the live consequence is the
+ * inverse one: `owns` is true for both, so a parent's `occupancy:release`
+ * removes a working child's lease mid-flight with no denial. That is a property
+ * of shared host identity, not of this module; a bearer boundary cannot
+ * distinguish two processes presenting one string.
+ *
  * Concurrency model:
  * - Assumptions: local filesystem; cooperating processes on one machine.
  * - Guarantees: mutual exclusion under crash-free operation; detect-and-abort
@@ -40,7 +59,8 @@ import { containedRemove, containedWrite } from "../fs/contained-write.js";
 import { assertWriteTargetSafe } from "../fs/projection-containment.js";
 import { assertAppendLockOwned, withAppendLock } from "../slice/lock.js";
 import { SWARM_WORKER_ROLES } from "../swarm/routing.js";
-import { ambientHostSessionOwner } from "./host-session-owner.js";
+import { recordChildOccupancyLease } from "./child-occupancy.js";
+import { ambientHostSessionOwner, claimsHostSessionIdShape, parseCanonicalHostSessionId, } from "./host-session-owner.js";
 import { stableJson } from "./json.js";
 import { parseTimestamp, timestampIso } from "./time.js";
 export const OCCUPANCY_SCHEMA_VERSION = 1;
@@ -258,25 +278,73 @@ export function formatOccupancyMemberAdministrationRefusal(record, grant, verb)
         `Ask the occupant (session ${record.sessionId}) to run it, or wait for the grant to expire.`);
 }
 /**
- * The owner a claim is made under: an explicit id, then `DEFT_SESSION_ID`, then
- * the id the running host published, then a mint.
+ * The one lookup order every occupancy surface shares (#3954): an explicit
+ * `--session-id`, then `DEFT_SESSION_ID`, then the owner the running host
+ * published.
+ *
+ * The terminal is the caller's, not this function's. Claim mints, because
+ * claiming establishes an identity where none exists. Release, heartbeat and
+ * grant/revoke are proving one, so they take the empty string and keep the
+ * diagnosis written for it -- a shared mint would replace "you presented
+ * nothing" with a plausible id no later hook will ever present, on every host
+ * that publishes no owner of its own.
+ *
+ * Disagreement is reported, not resolved. The order stands, so an explicit id
+ * beats the environment and the environment beats the host; what changes is
+ * that a refused caller is told the host names someone else, which is the state
+ * a stale inherited `DEFT_SESSION_ID` produces and the one an operator cannot
+ * otherwise see.
+ */
+export function resolvePresentedIdentity(input = {}) {
+    const env = input.env ?? process.env;
+    const hostOwner = ambientHostSessionOwner(env);
+    const disagreement = (chosen) => hostOwner !== null && hostOwner !== chosen ? hostOwner : null;
+    const explicit = input.sessionId?.trim();
+    if (explicit) {
+        return {
+            sessionId: explicit,
+            source: "explicit",
+            disagreeingHostOwner: disagreement(explicit),
+        };
+    }
+    const envId = env.DEFT_SESSION_ID?.trim();
+    if (envId) {
+        return { sessionId: envId, source: "environment", disagreeingHostOwner: disagreement(envId) };
+    }
+    if (hostOwner !== null) {
+        return { sessionId: hostOwner, source: "host", disagreeingHostOwner: null };
+    }
+    return { sessionId: "", source: "none", disagreeingHostOwner: null };
+}
+/**
+ * Name a claimer-versus-presenter split on a refusal, or return "" (#3954).
+ *
+ * Appended only to denials: while the caller is admitted the split costs it
+ * nothing, and on a refusal it is the one fact that explains why an id the
+ * operator believes is theirs is being treated as a stranger's.
+ */
+export function formatPresentedIdentityDisagreement(identity) {
+    const other = identity.disagreeingHostOwner;
+    if (other === null)
+        return "";
+    const named = identity.source === "explicit" ? "The id passed on the command line" : "DEFT_SESSION_ID";
+    return (`\n${named} names session ${identity.sessionId}, but this host published ` +
+        `${other}. Those are different sessions: re-run with ` +
+        `\`--session-id=${commandSessionId(other, "<host-published-id>")}\` to act as the host owner.`);
+}
+/**
+ * The owner a claim is made under: the shared lookup chain, then a mint.
  *
  * The host step is what makes an identified host's claim reachable (#3873).
  * Minting instead binds the lease to an id no later hook process can present,
  * so the session that claimed the worktree is refused by its own lease. The
- * mint stays as the last resort for hosts that publish nothing.
+ * mint stays as the last resort for hosts that publish nothing, and it is the
+ * one terminal the prove-surfaces deliberately do not share (#3954).
  */
 export function resolveOccupancySessionId(input = {}) {
-    const explicit = input.sessionId?.trim();
-    if (explicit)
-        return explicit;
-    const env = input.env ?? process.env;
-    const envId = env.DEFT_SESSION_ID?.trim();
-    if (envId)
-        return envId;
-    const hostOwner = ambientHostSessionOwner(env);
-    if (hostOwner !== null)
-        return hostOwner;
+    const presented = resolvePresentedIdentity(input).sessionId;
+    if (presented.length > 0)
+        return presented;
     return (input.newSessionId ?? randomUUID)();
 }
 export function readOccupancy(projectRoot) {
@@ -318,7 +386,10 @@ export function applyWorktreeOccupancy(projectRoot, input = {}) {
             sessionId: incoming,
             record: live,
             path,
-            message: formatOccupancyRemediation(live, now),
+            // A granted child reads the member refusal rather than an offer of the
+            // write grant it already holds (#3954 item 5): membership admits writes,
+            // and claiming the lease stays owner-only.
+            message: membershipOwnerDenial(live, incoming, now, "session:start"),
             code: 1,
         };
     }
@@ -343,7 +414,7 @@ export function applyWorktreeOccupancy(projectRoot, input = {}) {
                 sessionId: incoming,
                 record: liveLocked,
                 path,
-                message: formatOccupancyRemediation(liveLocked, now),
+                message: membershipOwnerDenial(liveLocked, incoming, now, "session:start"),
                 code: 1,
             };
         }
@@ -364,6 +435,9 @@ export function applyWorktreeOccupancy(projectRoot, input = {}) {
             grants: liveLocked === null ? [] : liveOccupancyGrants(liveLocked, now),
         }, fence);
         const action = liveLocked !== null ? "heartbeat" : "claimed";
+        if (action === "claimed") {
+            maybeRecordChildOccupancyOnClaim(projectRoot, incoming, input.env);
+        }
         return {
             action,
             sessionId: record.sessionId,
@@ -376,6 +450,32 @@ export function applyWorktreeOccupancy(projectRoot, input = {}) {
         };
     }, input.lockDeps);
 }
+/**
+ * Stamp the dispatch-recorded child occupancy store at claim time (#3999).
+ * Pre-dispatch / worktree mkdir cannot know a host-env child's occupancy
+ * owner; the claiming process does. Heartbeat `agent_id` on this host is the
+ * raw GROK_SESSION_ID, so that is the store key the terminal monitor looks up.
+ */
+function maybeRecordChildOccupancyOnClaim(projectRoot, occupancyOwner, env) {
+    const resolved = env ?? process.env;
+    const grokRaw = resolved.GROK_SESSION_ID?.trim() ?? "";
+    const agentId = grokRaw.length > 0 ? grokRaw : occupancyHost(env);
+    if (agentId.length === 0 || agentId === "none")
+        return;
+    const parentId = occupancyAddress(env);
+    try {
+        recordChildOccupancyLease(projectRoot, {
+            agentId,
+            parentId,
+            occupancyOwner,
+            worktreePath: resolve(projectRoot),
+            identitySourceKind: grokRaw.length > 0 ? "host-env" : "payload",
+        });
+    }
+    catch {
+        // Claim already succeeded; a missing dispatch record is a no-op on terminal.
+    }
+}
 export function stealOccupancy(projectRoot, input = {}) {
     const now = input.now ?? new Date();
     const path = occupancyPath(projectRoot);
@@ -506,10 +606,26 @@ export function stealOccupancy(projectRoot, input = {}) {
         };
     }, input.lockDeps);
 }
+/**
+ * Release the caller's own lease.
+ *
+ * Owner-only, deliberately (#3954 item 4, answering the open question the
+ * design-critique arc left for the builder). Letting an unidentified caller
+ * release the occupant the lease file itself records would make possession of
+ * that file path into authority to delete a live lease, which is exactly what
+ * the `!expired && !owns` refusal exists to prevent -- and the cooperative
+ * bearer model (#3755) has no second check behind it. The unreachable printed
+ * recovery is fixed by the shared lookup chain instead: on a host that
+ * publishes an owner, the occupant now resolves itself and a bare
+ * `occupancy:release` is the occupant, so the message the deny prints is one
+ * the party it addresses can actually run.
+ */
 export function releaseOccupancy(projectRoot, input = {}) {
     const now = input.now ?? new Date();
     const path = occupancyPath(projectRoot);
-    const caller = input.sessionId?.trim() || (input.env ?? process.env).DEFT_SESSION_ID?.trim() || "";
+    const identity = resolvePresentedIdentity(input);
+    const caller = identity.sessionId;
+    const split = formatPresentedIdentityDisagreement(identity);
     return withOccupancyLock(projectRoot, (fence) => {
         const existing = readOccupancy(projectRoot);
         if (existing === null) {
@@ -530,7 +646,7 @@ export function releaseOccupancy(projectRoot, input = {}) {
                 sessionId: caller,
                 record: existing,
                 path,
-                message: membershipOwnerDenial(existing, caller, now, "occupancy:release"),
+                message: membershipOwnerDenial(existing, caller, now, "occupancy:release") + split,
                 code: 1,
             };
         }
@@ -555,7 +671,7 @@ export function releaseOccupancy(projectRoot, input = {}) {
                 sessionId: caller,
                 record: still,
                 path,
-                message: membershipOwnerDenial(still, caller, now, "occupancy:release"),
+                message: membershipOwnerDenial(still, caller, now, "occupancy:release") + split,
                 code: 1,
             };
         }
@@ -570,10 +686,18 @@ export function releaseOccupancy(projectRoot, input = {}) {
         };
     }, input.lockDeps);
 }
+/**
+ * Refuse an owner-only verb, saying which of the three the caller is.
+ *
+ * The caller is passed to `formatOccupancyRemediation` as the presented id
+ * (#3954): every one of these surfaces now resolves an actor the caller may not
+ * have chosen explicitly, so a refusal that does not name what was presented
+ * leaves it guessing which identity it was refused under.
+ */
 function membershipOwnerDenial(live, caller, now, verb) {
     const grant = occupancyGrantFor(live, caller, now);
     return grant === null
-        ? formatOccupancyRemediation(live, now)
+        ? formatOccupancyRemediation(live, now, caller)
         : formatOccupancyMemberAdministrationRefusal(live, grant, verb);
 }
 /**
@@ -588,7 +712,9 @@ function membershipOwnerDenial(live, caller, now, verb) {
 export function grantOccupancyMembership(projectRoot, input = {}) {
     const now = input.now ?? new Date();
     const path = occupancyPath(projectRoot);
-    const owner = input.sessionId?.trim() || (input.env ?? process.env).DEFT_SESSION_ID?.trim() || "";
+    const identity = resolvePresentedIdentity(input);
+    const owner = identity.sessionId;
+    const split = formatPresentedIdentityDisagreement(identity);
     const child = input.childSessionId?.trim() ?? "";
     const role = input.role?.trim() ?? "";
     if (owner.length === 0) {
@@ -624,6 +750,46 @@ export function grantOccupancyMembership(projectRoot, input = {}) {
             code: 2,
         };
     }
+    // #3954 item 3. A child id under the reserved `host:` prefix must be a
+    // well-formed canonical owner: measured, `host:nosuchhost:v9:zzzz` and
+    // `host:grok:v1:!!!not-base64url!!!` were granted and then admitted as
+    // `member` by the write gate, so the lease read as membership while admitting
+    // nobody. An id outside that prefix is still accepted, because a child on a
+    // host with no identity contract presents whatever `DEFT_SESSION_ID` holds
+    // and refusing that would deny a grant nothing has measured wrong.
+    if (claimsHostSessionIdShape(child) && parseCanonicalHostSessionId(child) === null) {
+        return {
+            action: "denied",
+            sessionId: owner,
+            record: readOccupancy(projectRoot),
+            path,
+            message: `occupancy:grant refuses the child id ${child}: the \`host:\` prefix is reserved for ` +
+                "host-published identity, and this is not a well-formed owner " +
+                "(`host:<provider>:v1:<base64url>`), so no session could ever present it. Pass the id " +
+                "the child's own host publishes, or an opaque id the child sets as DEFT_SESSION_ID.",
+            code: 2,
+        };
+    }
+    // Same defect one step subtler: re-prefixing the owner's own payload under a
+    // second provider passes the shape check and is a self-grant in disguise --
+    // no session on that other host would present it, and the owner already holds
+    // the lease outright.
+    const childParts = parseCanonicalHostSessionId(child);
+    const ownerParts = parseCanonicalHostSessionId(owner);
+    if (childParts !== null &&
+        ownerParts !== null &&
+        childParts.rawSessionId === ownerParts.rawSessionId) {
+        return {
+            action: "denied",
+            sessionId: owner,
+            record: readOccupancy(projectRoot),
+            path,
+            message: `occupancy:grant refuses the child id ${child}: it carries this lease owner's own host ` +
+                `session (${ownerParts.rawSessionId}) under provider ${childParts.provider}. That is a ` +
+                "self-grant across a provider prefix, and the child it names cannot exist.",
+            code: 2,
+        };
+    }
     if (!SWARM_WORKER_ROLES.includes(role)) {
         return {
             action: "denied",
@@ -661,7 +827,7 @@ export function grantOccupancyMembership(projectRoot, input = {}) {
                 sessionId: owner,
                 record: live,
                 path,
-                message: membershipOwnerDenial(live, owner, now, "occupancy:grant"),
+                message: membershipOwnerDenial(live, owner, now, "occupancy:grant") + split,
                 code: 1,
             };
         }
@@ -742,7 +908,11 @@ export function grantOccupancyMembership(projectRoot, input = {}) {
 export function revokeOccupancyMembership(projectRoot, input = {}) {
     const now = input.now ?? new Date();
     const path = occupancyPath(projectRoot);
-    const owner = input.sessionId?.trim() || (input.env ?? process.env).DEFT_SESSION_ID?.trim() || "";
+    const identity = resolvePresentedIdentity(input);
+    const owner = identity.sessionId;
+    const split = formatPresentedIdentityDisagreement(identity);
+    // Revoke deliberately skips the grant-time child-id checks: a malformed grant
+    // written before those checks existed must stay withdrawable (#3954 item 3).
     const child = input.childSessionId?.trim() ?? "";
     if (owner.length === 0 || child.length === 0) {
         return {
@@ -775,7 +945,7 @@ export function revokeOccupancyMembership(projectRoot, input = {}) {
                 sessionId: owner,
                 record: live,
                 path,
-                message: membershipOwnerDenial(live, owner, now, "occupancy:grant --revoke"),
+                message: membershipOwnerDenial(live, owner, now, "occupancy:grant --revoke") + split,
                 code: 1,
             };
         }
@@ -1006,7 +1176,9 @@ memberSessionId) {
 export function heartbeatOccupancy(projectRoot, input = {}) {
     const now = input.now ?? new Date();
     const path = occupancyPath(projectRoot);
-    const caller = input.sessionId?.trim() || (input.env ?? process.env).DEFT_SESSION_ID?.trim() || "";
+    const identity = resolvePresentedIdentity(input);
+    const caller = identity.sessionId;
+    const split = formatPresentedIdentityDisagreement(identity);
     if (caller.length === 0) {
         return {
             action: "denied",
@@ -1042,7 +1214,7 @@ export function heartbeatOccupancy(projectRoot, input = {}) {
             sessionId: caller,
             record: live,
             path,
-            message: membershipOwnerDenial(live, caller, now, "occupancy:heartbeat"),
+            message: membershipOwnerDenial(live, caller, now, "occupancy:heartbeat") + split,
             code: 1,
         };
     }
@@ -1072,10 +1244,18 @@ export function heartbeatOccupancy(projectRoot, input = {}) {
         code: 0,
     };
 }
-/** Close-out identity comes from the launch manifest or DEFT_SESSION_ID — never occupancy.json. */
+/**
+ * Close-out identity comes from the launch manifest, `DEFT_SESSION_ID`, or the
+ * owner the running host published — never occupancy.json (#3954).
+ *
+ * Reading the lease for identity would be the anonymous recorded-occupant
+ * release refused in `releaseOccupancy`; the host step is the same shared
+ * lookup chain every other occupancy surface uses, so a cohort launched on a
+ * host that publishes an owner can close out without an explicit id.
+ */
 export function releaseSwarmOccupancy(projectRoot, input = {}) {
     const env = input.env ?? process.env;
-    const sessionId = input.sessionId?.trim() || env.DEFT_SESSION_ID?.trim() || "";
+    const sessionId = resolvePresentedIdentity({ sessionId: input.sessionId, env }).sessionId;
     if (sessionId.length === 0) {
         const occupant = readOccupancy(projectRoot);
         return {
@@ -1083,9 +1263,9 @@ export function releaseSwarmOccupancy(projectRoot, input = {}) {
             sessionId: "",
             record: occupant,
             path: occupancyPath(projectRoot),
-            message: "swarm close-out has no occupancy_session_id (manifest missing or predates the field) " +
-                "and DEFT_SESSION_ID is unset. Re-establish an aligned owner with " +
-                "session:start --steal --confirm --occupant <reported-session-id> " +
+            message: "swarm close-out has no occupancy_session_id (manifest missing or predates the field), " +
+                "DEFT_SESSION_ID is unset, and this host published no owner. Re-establish an aligned " +
+                "owner with session:start --steal --confirm --occupant <reported-session-id> " +
                 "--session-id=<your-session-id>.",
             code: 1,
         };

package/dist/swarm/complete-cohort.js

@@ -496,6 +496,8 @@ export function completeCohort(args) {
             }
         }
         if (result.ok && sessionId.length > 0) {
+            // Launcher occupancy only. Child owner leases release on the
+            // orchestration terminal transition (#3999), not here.
             const released = releaseSwarmOccupancy(projectRoot, {
                 env,
                 sessionId,

package/dist/swarm/pre-dispatch.js

@@ -177,6 +177,8 @@ function runBegin(input) {
     // heuristic, so accept an on-disk worktree as the second arming signal.
     const armTarget = resolve(input.projectRoot, input.targetId.trim());
     if (looksLikeFilesystemTarget(input.targetId) || looksLikeWorktreeDir(armTarget)) {
+        // Heartbeat dir only. Child occupancy owner is recorded at claim time
+        // (#3999): this parent process does not know a host-env child's id.
         ensureSubagentStatusDir(armTarget);
     }
     // Exclusive lock → reload → evaluate → begin+save (same decision under lock;

package/dist/swarm/subagent-status-dir.d.ts

@@ -6,6 +6,7 @@
  * worktree create and at pre-dispatch begin so a later missing record is
  * exit 1. Does not write heartbeat records or liveness onto the C2 manifest.
  */
+import { type ChildOccupancyDispatchInput } from "../session/child-occupancy.js";
 /**
  * True when a resolved path is an on-disk git worktree, i.e. it carries a `.git`
  * entry (a file for `git worktree add` trees, a directory for the main clone).
@@ -23,5 +24,5 @@ export declare function looksLikeWorktreeDir(resolvedPath: string): boolean;
  * Returns the directory path, or null when the worktree is not on disk yet
  * (do not mkdir a stray tree for a branch-name target).
  */
-export declare function ensureSubagentStatusDir(worktreeRoot: string): string | null;
+export declare function ensureSubagentStatusDir(worktreeRoot: string, childLease?: Omit<ChildOccupancyDispatchInput, "worktreePath">): string | null;
 //# sourceMappingURL=subagent-status-dir.d.ts.map

package/dist/swarm/subagent-status-dir.js

@@ -7,8 +7,9 @@
  * exit 1. Does not write heartbeat records or liveness onto the C2 manifest.
  */
 import { existsSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { defaultScratchDir } from "../orchestration/subagent-monitor.js";
+import { recordChildOccupancyLease, } from "../session/child-occupancy.js";
 /**
  * True when a resolved path is an on-disk git worktree, i.e. it carries a `.git`
  * entry (a file for `git worktree add` trees, a directory for the main clone).
@@ -31,12 +32,20 @@ export function looksLikeWorktreeDir(resolvedPath) {
  * Returns the directory path, or null when the worktree is not on disk yet
  * (do not mkdir a stray tree for a branch-name target).
  */
-export function ensureSubagentStatusDir(worktreeRoot) {
+export function ensureSubagentStatusDir(worktreeRoot, childLease) {
     const trimmed = worktreeRoot.trim();
     if (trimmed.length === 0 || !existsSync(trimmed))
         return null;
     const dir = defaultScratchDir(trimmed);
     mkdirSync(dir, { recursive: true });
+    // Optional: parent already knows the child's occupancy owner (spawn return).
+    // Host-env production claims also record via applyWorktreeOccupancy (#3999).
+    if (childLease !== undefined) {
+        recordChildOccupancyLease(trimmed, {
+            ...childLease,
+            worktreePath: resolve(trimmed),
+        });
+    }
     return dir;
 }
 //# sourceMappingURL=subagent-status-dir.js.map

package/dist/swarm/worktrees.js

@@ -198,6 +198,7 @@ export function resolveWorktreeMap(mapping, baseBranch, createMissing = true, op
                     `but requested base '${trimmedBase}' resolves to ${requestedOid}; ` +
                     `this is a snapshot check at resolution time, not a pin on the worker's start revision`);
             }
+            // Heartbeat dir only. Child occupancy owner is recorded at claim (#3999).
             ensureSubagentStatusDir(entry._abs);
             continue;
         }
@@ -205,6 +206,7 @@ export function resolveWorktreeMap(mapping, baseBranch, createMissing = true, op
             throw new MissingWorktreeError(`story '${entry.story_id}' maps to '${entry.worktree_path}' which is not a registered git worktree and create_missing is disabled`);
         }
         createWorktree(root, entry._abs, trimmedBase, git);
+        // Heartbeat dir only. Child occupancy owner is recorded at claim (#3999).
         ensureSubagentStatusDir(entry._abs);
     }
     return resolved.map(({ story_id, worktree_path, base_branch }) => ({

package/dist/verify-env/agent-hooks.d.ts

@@ -1,4 +1,5 @@
 import { type AgentHookInspection } from "../init-deposit/agent-hooks.js";
+import { type HostToolCoverageFinding, inspectHostToolCoverage } from "../init-deposit/host-tool-coverage.js";
 import type { HostHooksPolicy } from "../policy/host-hooks.js";
 import type { OutputStream } from "./verify-hooks-installed.js";
 export interface AgentHookHealthResult {
@@ -6,7 +7,11 @@ export interface AgentHookHealthResult {
     readonly message: string;
     readonly stream: OutputStream;
     readonly registrations: readonly AgentHookInspection[];
+    /** Host tool-surface coverage gaps found alongside registration health (#3987). */
+    readonly coverage: readonly HostToolCoverageFinding[];
 }
 /** Read-only P0 agent-host registration health, independent of git hooks. */
-export declare function evaluateAgentHooks(projectRoot: string, hostHooksPolicy?: HostHooksPolicy): AgentHookHealthResult;
+export declare function evaluateAgentHooks(projectRoot: string, hostHooksPolicy?: HostHooksPolicy, 
+/** Test seam for the #3987 tool-surface coverage probe. */
+inspectCoverage?: typeof inspectHostToolCoverage): AgentHookHealthResult;
 //# sourceMappingURL=agent-hooks.d.ts.map

package/dist/verify-env/agent-hooks.js

@@ -1,6 +1,7 @@
 import { statSync } from "node:fs";
 import { resolve } from "node:path";
 import { inspectAgentHookDeposit } from "../init-deposit/agent-hooks.js";
+import { HOST_TOOL_COVERAGE_RECOVERY, inspectHostToolCoverage, } from "../init-deposit/host-tool-coverage.js";
 import { loadHostHooksPolicyFromProject, UNUSED_HOST_HOOKS_RECOVERY, } from "../policy/host-hooks.js";
 function isDirectory(path) {
     try {
@@ -11,7 +12,9 @@ function isDirectory(path) {
     }
 }
 /** Read-only P0 agent-host registration health, independent of git hooks. */
-export function evaluateAgentHooks(projectRoot, hostHooksPolicy = loadHostHooksPolicyFromProject(projectRoot)) {
+export function evaluateAgentHooks(projectRoot, hostHooksPolicy = loadHostHooksPolicyFromProject(projectRoot), 
+/** Test seam for the #3987 tool-surface coverage probe. */
+inspectCoverage = inspectHostToolCoverage) {
     const root = resolve(projectRoot);
     if (!isDirectory(root)) {
         return {
@@ -19,9 +22,11 @@ export function evaluateAgentHooks(projectRoot, hostHooksPolicy = loadHostHooksP
             message: `❌ deft agent hooks: project root ${root} does not exist (config error).`,
             stream: "stderr",
             registrations: [],
+            coverage: [],
         };
     }
     const registrations = inspectAgentHookDeposit(root, hostHooksPolicy);
+    const coverage = inspectCoverage(root, hostHooksPolicy);
     const unhealthy = registrations.filter((entry) => entry.status === "missing" || entry.status === "drifted");
     if (unhealthy.length > 0) {
         return {
@@ -34,6 +39,25 @@ export function evaluateAgentHooks(projectRoot, hostHooksPolicy = loadHostHooksP
                 UNUSED_HOST_HOOKS_RECOVERY,
             stream: "stderr",
             registrations,
+            coverage,
+        };
+    }
+    // #3987: a structurally current registration can still leave a host tool
+    // uncovered, which is the failure this issue is about — a deposit the host
+    // never matches is enforcement that never runs.
+    if (coverage.length > 0) {
+        return {
+            code: 1,
+            message: "❌ deft agent hook tool-surface coverage INCOMPLETE:\n" +
+                coverage
+                    .map((finding) => `  - ${finding.host}: ${finding.kind}` +
+                    `${finding.toolName === null ? "" : ` \`${finding.toolName}\``} ` +
+                    `at ${finding.path} — ${finding.detail}`)
+                    .join("\n") +
+                `\n  ${HOST_TOOL_COVERAGE_RECOVERY}`,
+            stream: "stderr",
+            registrations,
+            coverage,
         };
     }
     const disabledHosts = registrations
@@ -48,9 +72,11 @@ export function evaluateAgentHooks(projectRoot, hostHooksPolicy = loadHostHooksP
             "DEFT_HOOK_READ_ONLY=1 and explore subagent_type. Codex runtime trust is user-controlled and must be reviewed with `/hooks`; shell/MCP policy is deferred." +
             (disabledHosts.length > 0
                 ? ` Intentional hostHooks disabled: ${disabledHosts.join(", ")}.`
-                : ""),
+                : "") +
+            " Per-host mutation tool names verified against the deposited matchers (#3987).",
         stream: "stdout",
         registrations,
+        coverage,
     };
 }
 //# sourceMappingURL=agent-hooks.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-core",
-  "version": "0.109.0",
+  "version": "0.109.1",
   "description": "TypeScript engine core for the Directive framework.",
   "license": "MIT",
   "type": "module",
@@ -390,8 +390,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@deftai/directive-content": "^0.109.0",
-    "@deftai/directive-types": "^0.109.0",
+    "@deftai/directive-content": "^0.109.1",
+    "@deftai/directive-types": "^0.109.1",
     "archiver": "^8.0.0"
   },
   "scripts": {