@deftai/directive-core 0.106.0 → 0.108.0

package/dist/freshness/bind.js

@@ -3,7 +3,7 @@
  *
  * Host-agnostic storage:
  * - Default (no sessionId): `.deft/session-bind.json` — single-operator convenience.
- * - With sessionId: `.deft/session-binds/<safeId>.json` — isolated multi-session binds.
+ * - With sessionId: `.deft/session-binds/<sha256-slice>.json` — isolated multi-session binds.
  *
  * Multi-agent hosts MUST pass a stable host session identity when binding and
  * reporting so one session cannot certify another as current.
@@ -26,14 +26,44 @@ export function sessionBindPath(projectRoot, sessionId) {
     }
     return join(root, SESSION_BINDS_DIR_REL, safeSessionFileName(id));
 }
+function sessionIdHash(sessionId) {
+    return createHash("sha256").update(sessionId.trim(), "utf8").digest("hex").slice(0, 24);
+}
 /**
  * Stable filesystem-safe file name for a host session id.
- * Keeps a short prefix for debug, hashes the rest to avoid path injection.
- * Character filter is O(n) (no regex) — CodeQL poly-redos on uncontrolled ids.
+ *
+ * Hash only (#3768): a 24-hex SHA-256 slice of the id. Hex cannot carry a path
+ * separator, so path injection is structurally impossible, and the name stays
+ * derivable from the id — lookup is one computed path, never a directory scan.
+ *
+ * Records written before #3768 also carried the first 32 characters of the id
+ * (`legacySessionFileName`). Dropping that prefix is hygiene, not a security
+ * fix: the same id is already published in `.deft/occupancy.json`,
+ * `.deft/ritual-state.json` and the bind record body (#3611 / #3754).
+ *
+ * Coupling warning: if `.deft/` JSON bodies are ever tightened (say to `0600`)
+ * while names still carry the prefix, the prefix becomes independently
+ * load-bearing — directory read permission alone would recover an id that the
+ * file mode was meant to protect. Anyone tightening those modes must keep bind
+ * names prefix-free.
  */
 export function safeSessionFileName(sessionId) {
+    return `${sessionIdHash(sessionId)}.json`;
+}
+/**
+ * Pre-#3768 record name: sanitized 32-character id prefix plus the same hash.
+ *
+ * Existing records are **tolerated, not migrated**. `readBoundGeneration` falls
+ * back to this name when the hash-only record is absent, so freshness pins
+ * written before the rename are not orphaned; writes always use the hash-only
+ * name, so the next bind supersedes the legacy record. Both names derive from
+ * the id, so the fallback stays O(1) and adds no directory scan.
+ *
+ * Character filter is O(n) (no regex) — CodeQL poly-redos on uncontrolled ids.
+ */
+export function legacySessionFileName(sessionId) {
     const trimmed = sessionId.trim();
-    const hash = createHash("sha256").update(trimmed, "utf8").digest("hex").slice(0, 24);
+    const hash = sessionIdHash(trimmed);
     let prefix = "";
     for (let i = 0; i < trimmed.length && prefix.length < 32; i++) {
         const ch = trimmed[i] ?? "";
@@ -60,6 +90,12 @@ export function safeSessionFileName(sessionId) {
     const base = prefix.length > 0 ? `${prefix}-${hash}` : hash;
     return `${base}.json`;
 }
+/**
+ * Derived path of a pre-#3768 record. Read fallback only — never a write target.
+ */
+export function legacySessionBindPath(projectRoot, sessionId) {
+    return join(resolve(projectRoot), SESSION_BINDS_DIR_REL, legacySessionFileName(sessionId));
+}
 function nowIsoDefault() {
     return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
 }
@@ -108,12 +144,7 @@ export function parseBoundGeneration(raw) {
         ...(payloadLoaded ? { payloadLoaded: true } : {}),
     };
 }
-/** Read the session bind record (null when absent/unreadable). */
-export function readBoundGeneration(projectRoot, options = {}) {
-    const path = sessionBindPath(projectRoot, options.sessionId);
-    if (!existsSync(path)) {
-        return null;
-    }
+function readBoundAt(path, wantSessionId) {
     try {
         const text = readFileSync(path, "utf8");
         const bound = parseBoundGeneration(JSON.parse(text));
@@ -122,8 +153,7 @@ export function readBoundGeneration(projectRoot, options = {}) {
         }
         // When reading a session-scoped bind, refuse a record whose embedded
         // sessionId disagrees (tamper / wrong file).
-        const want = typeof options.sessionId === "string" ? options.sessionId.trim() : "";
-        if (want.length > 0 && bound.sessionId && bound.sessionId !== want) {
+        if (wantSessionId.length > 0 && bound.sessionId && bound.sessionId !== wantSessionId) {
             return null;
         }
         return bound;
@@ -132,6 +162,22 @@ export function readBoundGeneration(projectRoot, options = {}) {
         return null;
     }
 }
+/** Read the session bind record (null when absent/unreadable). */
+export function readBoundGeneration(projectRoot, options = {}) {
+    const want = typeof options.sessionId === "string" ? options.sessionId.trim() : "";
+    const path = sessionBindPath(projectRoot, options.sessionId);
+    if (existsSync(path)) {
+        return readBoundAt(path, want);
+    }
+    if (want.length === 0) {
+        return null;
+    }
+    // Pre-#3768 records are tolerated, not migrated: one extra derived path and
+    // still no directory scan, so pins written under the old name resolve until
+    // the next bind supersedes them.
+    const legacy = legacySessionBindPath(projectRoot, want);
+    return existsSync(legacy) ? readBoundAt(legacy, want) : null;
+}
 function writeBoundAt(projectRoot, bound, sessionId) {
     const root = resolve(projectRoot);
     const target = sessionBindPath(projectRoot, sessionId);

package/dist/hooks/classify/host-session-identity.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Cooperative host-session identity and exact lifecycle-command rewriting (#3611).
+ *
+ * This is payload classification, not authentication. Host hook JSON is locally
+ * forgeable under the occupancy model's cooperating-process assumption.
+ */
+export declare const HOST_IDENTITY_PROVIDERS: readonly ["codex", "claude", "cursor"];
+export type HookHostIdentityProvider = (typeof HOST_IDENTITY_PROVIDERS)[number];
+export declare const MAX_HOOK_HOST_IDENTITY_UTF8_BYTES = 512;
+export type HookHostIdentityStatus = "ok" | "missing" | "invalid" | "conflict" | "unsupported";
+export type HookHostIdentityResolution = {
+    readonly status: "ok";
+    readonly provider: HookHostIdentityProvider;
+    readonly rawSessionId: string;
+    readonly sessionId: string;
+    readonly message: null;
+} | {
+    readonly status: Exclude<HookHostIdentityStatus, "ok">;
+    readonly provider: string;
+    readonly rawSessionId: null;
+    readonly sessionId: null;
+    readonly message: string;
+};
+/**
+ * Resolve the stable conversation/session-family key documented by each host.
+ *
+ * - Codex: `session_id` (parent and subagents share it).
+ * - Claude Code: `session_id` (`agent_id` is deliberately not the owner key).
+ * - Cursor: `conversation_id`; simultaneous `session_id` must agree.
+ * - Grok/unknown: no guessed payload identity; callers keep explicit/env flow.
+ */
+export declare function resolveHookHostIdentity(host: string, payload: unknown): HookHostIdentityResolution;
+export declare const EXACT_LIFECYCLE_VERBS: readonly ["session:start", "session:ready", "session:end", "occupancy:steal", "occupancy:release", "occupancy:heartbeat", "swarm:launch"];
+export type ExactLifecycleVerb = (typeof EXACT_LIFECYCLE_VERBS)[number];
+export interface ExactLifecycleCommandRewrite {
+    readonly kind: "rewrite";
+    readonly verb: ExactLifecycleVerb;
+    readonly originalCommand: string;
+    readonly rewrittenCommand: string;
+    readonly updatedInput: Record<string, unknown>;
+}
+export interface ExactLifecycleCommandConflict {
+    readonly kind: "conflict";
+    readonly verb: ExactLifecycleVerb;
+    readonly existingSessionId: string;
+    readonly requestedSessionId: string;
+    readonly message: string;
+}
+export type ExactLifecycleCommandResult = ExactLifecycleCommandRewrite | ExactLifecycleCommandConflict | null;
+/** Logical lifecycle verb for one exact, simple shell command; otherwise null. */
+export declare function exactLifecycleCommandVerb(payload: unknown): ExactLifecycleVerb | null;
+interface SessionIdArgs {
+    readonly status: "absent" | "present" | "invalid";
+    readonly values: readonly string[];
+}
+export interface ExactLifecycleCommandInspection {
+    readonly verb: ExactLifecycleVerb;
+    readonly task: boolean;
+    readonly rewriteSafe: boolean;
+    readonly requiresOwner: boolean;
+    readonly sessionIdStatus: SessionIdArgs["status"];
+    readonly sessionId: string | null;
+}
+/** Inspect one exact lifecycle command without requiring a host identity. */
+export declare function inspectExactLifecycleCommand(payload: unknown): ExactLifecycleCommandInspection | null;
+/**
+ * Append a canonical host owner to one exact Directive lifecycle command.
+ *
+ * The returned `updatedInput` is a complete shallow clone of the original
+ * host tool input. `null` means no safe rewrite. An explicit foreign identity
+ * is surfaced as a conflict so dispatcher wiring can deny instead of replacing
+ * operator input.
+ */
+export declare function rewriteExactLifecycleCommand(payload: unknown, sessionId: string): ExactLifecycleCommandResult;
+export {};
+//# sourceMappingURL=host-session-identity.d.ts.map

package/dist/hooks/classify/host-session-identity.js

@@ -0,0 +1,470 @@
+/**
+ * Cooperative host-session identity and exact lifecycle-command rewriting (#3611).
+ *
+ * This is payload classification, not authentication. Host hook JSON is locally
+ * forgeable under the occupancy model's cooperating-process assumption.
+ */
+import { isShellTool } from "../tools.js";
+import { record, toolInputRecord } from "./payload.js";
+import { hookToolName } from "./tool-name.js";
+export const HOST_IDENTITY_PROVIDERS = ["codex", "claude", "cursor"];
+export const MAX_HOOK_HOST_IDENTITY_UTF8_BYTES = 512;
+function hasControlCharacter(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const unit = value.charCodeAt(index);
+        if (unit <= 0x1f || (unit >= 0x7f && unit <= 0x9f))
+            return true;
+    }
+    return false;
+}
+function hasUnpairedUtf16Surrogate(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const unit = value.charCodeAt(index);
+        if (unit >= 0xd800 && unit <= 0xdbff) {
+            const next = value.charCodeAt(index + 1);
+            if (!(next >= 0xdc00 && next <= 0xdfff))
+                return true;
+            index += 1;
+            continue;
+        }
+        if (unit >= 0xdc00 && unit <= 0xdfff)
+            return true;
+    }
+    return false;
+}
+function identityField(input, fieldName) {
+    if (!(fieldName in input))
+        return { status: "missing", value: null };
+    const raw = input[fieldName];
+    if (typeof raw !== "string" ||
+        raw.length === 0 ||
+        raw !== raw.trim() ||
+        hasControlCharacter(raw) ||
+        hasUnpairedUtf16Surrogate(raw) ||
+        Buffer.byteLength(raw, "utf8") > MAX_HOOK_HOST_IDENTITY_UTF8_BYTES) {
+        return { status: "invalid", value: null };
+    }
+    return { status: "ok", value: raw };
+}
+function unresolvedHostIdentity(status, provider, message) {
+    return { status, provider, rawSessionId: null, sessionId: null, message };
+}
+function canonicalHostSessionId(provider, rawSessionId) {
+    const encoded = Buffer.from(rawSessionId, "utf8").toString("base64url");
+    return `host:${provider}:v1:${encoded}`;
+}
+function resolvedHostIdentity(provider, rawSessionId) {
+    return {
+        status: "ok",
+        provider,
+        rawSessionId,
+        sessionId: canonicalHostSessionId(provider, rawSessionId),
+        message: null,
+    };
+}
+/**
+ * Resolve the stable conversation/session-family key documented by each host.
+ *
+ * - Codex: `session_id` (parent and subagents share it).
+ * - Claude Code: `session_id` (`agent_id` is deliberately not the owner key).
+ * - Cursor: `conversation_id`; simultaneous `session_id` must agree.
+ * - Grok/unknown: no guessed payload identity; callers keep explicit/env flow.
+ */
+export function resolveHookHostIdentity(host, payload) {
+    if (!HOST_IDENTITY_PROVIDERS.includes(host)) {
+        return unresolvedHostIdentity("unsupported", host, `Host ${host || "<empty>"} has no verified payload identity contract.`);
+    }
+    const provider = host;
+    const input = record(payload);
+    if (input === null) {
+        return unresolvedHostIdentity("invalid", provider, `${provider} hook payload is not an object.`);
+    }
+    if (provider === "codex" || provider === "claude") {
+        const session = identityField(input, "session_id");
+        if (session.status !== "ok") {
+            return unresolvedHostIdentity(session.status, provider, `${provider} hook payload ${session.status === "missing" ? "omits" : "has invalid"} session_id.`);
+        }
+        return resolvedHostIdentity(provider, session.value);
+    }
+    const conversation = identityField(input, "conversation_id");
+    if (conversation.status !== "ok") {
+        return unresolvedHostIdentity(conversation.status, provider, `Cursor hook payload ${conversation.status === "missing" ? "omits" : "has invalid"} conversation_id.`);
+    }
+    const simultaneousSession = identityField(input, "session_id");
+    if (simultaneousSession.status === "invalid") {
+        return unresolvedHostIdentity("invalid", provider, "Cursor hook payload has invalid session_id alongside conversation_id.");
+    }
+    if (simultaneousSession.status === "ok" && simultaneousSession.value !== conversation.value) {
+        return unresolvedHostIdentity("conflict", provider, "Cursor hook identity conflict: conversation_id and session_id differ.");
+    }
+    return resolvedHostIdentity(provider, conversation.value);
+}
+export const EXACT_LIFECYCLE_VERBS = [
+    "session:start",
+    "session:ready",
+    "session:end",
+    "occupancy:steal",
+    "occupancy:release",
+    "occupancy:heartbeat",
+    "swarm:launch",
+];
+const DIRECT_LIFECYCLE_VERBS = {
+    "session:start": "session:start",
+    "session:ready": "session:ready",
+    "session:end": "session:end",
+    "occupancy:steal": "occupancy:steal",
+    "occupancy:release": "occupancy:release",
+    "occupancy:heartbeat": "occupancy:heartbeat",
+    "swarm-launch": "swarm:launch",
+};
+const CANONICAL_OWNER_PATTERN = /^host:(?:codex|claude|cursor):v1:[A-Za-z0-9_-]+$/;
+// Shell expansion markers are deliberately absent: `$`/backticks for POSIX,
+// `@` splatting for PowerShell, and `%NAME%` expansion for command shells.
+// Backslashes are inspectable so Windows path-bearing lifecycle commands fail
+// closed, but they remain outside the auto-approved rewrite surface below.
+const INSPECTABLE_TOKEN_PATTERN = /^[A-Za-z0-9_./\\:+=,-]+$/;
+const LIFECYCLE_ARGUMENT_POLICIES = {
+    "session:start": {
+        booleanFlags: new Set([
+            "--json",
+            "--no-history",
+            "--read-only",
+            "--with-network",
+            "--rearm",
+            "--hard-budget",
+            "--compact",
+            "--steal",
+            "--confirm",
+        ]),
+        valueFlags: new Set([
+            "--tier",
+            "--defer",
+            "--task-size",
+            "--ceremony-task-size",
+            "--model-tier",
+            "--ceremony-model-tier",
+            "--project-shape",
+            "--ceremony-project-shape",
+            "--ceremony-depth",
+            "--max-turns",
+            "--max-budget",
+            "--session-id",
+            "--occupant",
+            "--project-root",
+        ]),
+        rewriteUnsafeFlags: new Set(["--project-root"]),
+    },
+    "session:ready": {
+        booleanFlags: new Set(["--json", "--with-network"]),
+        valueFlags: new Set(["--repo", "--session-id", "--project-root"]),
+        rewriteUnsafeFlags: new Set(["--project-root"]),
+    },
+    "session:end": {
+        booleanFlags: new Set(),
+        valueFlags: new Set(["--session-id", "--project-root"]),
+        rewriteUnsafeFlags: new Set(["--project-root"]),
+    },
+    "occupancy:steal": {
+        booleanFlags: new Set(["--confirm"]),
+        valueFlags: new Set(["--occupant", "--session-id", "--project-root"]),
+        rewriteUnsafeFlags: new Set(["--project-root"]),
+    },
+    "occupancy:release": {
+        booleanFlags: new Set(),
+        valueFlags: new Set(["--session-id", "--project-root"]),
+        rewriteUnsafeFlags: new Set(["--project-root"]),
+    },
+    "occupancy:heartbeat": {
+        booleanFlags: new Set(),
+        valueFlags: new Set(["--session-id", "--project-root"]),
+        rewriteUnsafeFlags: new Set(["--project-root"]),
+    },
+    "swarm:launch": {
+        booleanFlags: new Set([
+            "--autonomous",
+            "--no-create-worktrees",
+            "--enforce-gates",
+            "--no-audit",
+        ]),
+        valueFlags: new Set([
+            "--stories",
+            "--paths",
+            "--group",
+            "--worktree-map",
+            "--base-branch",
+            "--allocation-plan-id",
+            "--batching-rationale",
+            "--operator-approval",
+            "--output",
+            "--gate-clearances",
+            "--project-root",
+            "--session-id",
+        ]),
+        rewriteUnsafeFlags: new Set([
+            "--paths",
+            "--worktree-map",
+            "--output",
+            "--gate-clearances",
+            "--project-root",
+            "--no-audit",
+        ]),
+        separateOnlyValueFlags: new Set([
+            "--stories",
+            "--paths",
+            "--group",
+            "--worktree-map",
+            "--base-branch",
+            "--allocation-plan-id",
+            "--batching-rationale",
+            "--operator-approval",
+            "--output",
+            "--gate-clearances",
+            "--project-root",
+        ]),
+    },
+};
+function lifecycleArgumentValueIsRewriteSafe(verb, flag, value) {
+    if (verb !== "swarm:launch" || flag !== "--stories")
+        return true;
+    // `swarm:launch --stories` accepts both logical IDs and filesystem paths.
+    // Only the ID form belongs in the auto-approved rewrite bridge; path-bearing
+    // invocations must keep the host's ordinary permission decision.
+    return value
+        .split(",")
+        .every((story) => story.length > 0 &&
+        !story.endsWith(".json") &&
+        !story.includes("/") &&
+        !story.includes("\\"));
+}
+/**
+ * Validate the complete CLI argument surface before returning an allow+rewrite.
+ * Path rebinding/destination flags and unknown/future flags are recognized but
+ * kept outside the auto-rewrite bridge. Supported hosts must carry the matching
+ * owner explicitly before those commands retain normal permission handling.
+ */
+function analyzeLifecycleArguments(verb, args) {
+    const policy = LIFECYCLE_ARGUMENT_POLICIES[verb];
+    let rewriteSafe = true;
+    let readOnly = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const token = args[index] ?? "";
+        if (policy.booleanFlags.has(token)) {
+            if (verb === "session:start" && token === "--read-only")
+                readOnly = true;
+            if (policy.rewriteUnsafeFlags.has(token))
+                rewriteSafe = false;
+            continue;
+        }
+        const equals = token.indexOf("=");
+        if (equals > 0) {
+            const flag = token.slice(0, equals);
+            const value = token.slice(equals + 1);
+            if (!policy.valueFlags.has(flag)) {
+                rewriteSafe = false;
+                continue;
+            }
+            if (policy.rewriteUnsafeFlags.has(flag))
+                rewriteSafe = false;
+            if (policy.separateOnlyValueFlags?.has(flag) === true)
+                rewriteSafe = false;
+            // Keep malformed session identity visible to inspection so the
+            // dispatcher can deny ambiguity instead of silently skipping rewrite.
+            if (value.length === 0 && flag !== "--session-id")
+                rewriteSafe = false;
+            if (!lifecycleArgumentValueIsRewriteSafe(verb, flag, value))
+                rewriteSafe = false;
+            continue;
+        }
+        if (!policy.valueFlags.has(token)) {
+            rewriteSafe = false;
+            continue;
+        }
+        if (policy.rewriteUnsafeFlags.has(token))
+            rewriteSafe = false;
+        const value = args[index + 1];
+        if (value === undefined) {
+            if (token !== "--session-id")
+                rewriteSafe = false;
+            continue;
+        }
+        if (value.startsWith("--"))
+            rewriteSafe = false;
+        if (!lifecycleArgumentValueIsRewriteSafe(verb, token, value))
+            rewriteSafe = false;
+        // Match the real lifecycle parsers: known value flags consume the next
+        // argv token even when it begins with `--`. This prevents a swallowed
+        // `--session-id=...` from being mistaken for an effective owner.
+        index += 1;
+    }
+    return { rewriteSafe, readOnly };
+}
+/**
+ * Inspect single-space-separated lifecycle commands while excluding shell
+ * quoting, substitution, redirection, chaining, aliases, and wrappers.
+ * Windows path separators remain inspectable but make rewriting unsafe.
+ */
+function exactLifecycleInvocation(command) {
+    if (command.length === 0 || command !== command.trim())
+        return null;
+    const tokens = command.split(" ");
+    if (tokens.some((token) => token.length === 0 || !INSPECTABLE_TOKEN_PATTERN.test(token))) {
+        return null;
+    }
+    if (tokens.length < 2)
+        return null;
+    const executable = tokens[0];
+    const verb = tokens[1];
+    if (executable === "deft" || executable === "directive") {
+        const typedVerb = verb === undefined ? undefined : DIRECT_LIFECYCLE_VERBS[verb];
+        if (typedVerb === undefined)
+            return null;
+        const forwardedArgs = tokens.slice(2);
+        const { rewriteSafe, readOnly } = analyzeLifecycleArguments(typedVerb, forwardedArgs);
+        const requiresOwner = typedVerb !== "session:start" || !readOnly;
+        return {
+            verb: typedVerb,
+            task: false,
+            forwardedArgs,
+            rewriteSafe: rewriteSafe && forwardedArgs.every((token) => !token.includes("\\")),
+            requiresOwner,
+        };
+    }
+    if (executable !== "task")
+        return null;
+    if (!EXACT_LIFECYCLE_VERBS.includes(verb ?? ""))
+        return null;
+    const typedVerb = verb;
+    if (tokens.length === 2) {
+        return {
+            verb: typedVerb,
+            task: true,
+            forwardedArgs: [],
+            rewriteSafe: true,
+            requiresOwner: true,
+        };
+    }
+    // Go Task's canonical CLI_ARGS boundary. Flags without `--` are ambiguous
+    // Task CLI flags and must not receive an auto-approving rewrite.
+    if (tokens[2] !== "--")
+        return null;
+    const forwardedArgs = tokens.slice(3);
+    const { rewriteSafe, readOnly } = analyzeLifecycleArguments(typedVerb, forwardedArgs);
+    const requiresOwner = typedVerb !== "session:start" || !readOnly;
+    return {
+        verb: typedVerb,
+        task: true,
+        forwardedArgs,
+        rewriteSafe: rewriteSafe && forwardedArgs.every((token) => !token.includes("\\")),
+        requiresOwner,
+    };
+}
+function exactLifecyclePayload(payload) {
+    const toolName = hookToolName(payload);
+    if (toolName === null || !isShellTool(toolName)) {
+        return null;
+    }
+    const input = record(payload);
+    if (input === null)
+        return null;
+    const toolInput = toolInputRecord(input);
+    if (toolInput === null || typeof toolInput.command !== "string")
+        return null;
+    const originalCommand = toolInput.command;
+    const invocation = exactLifecycleInvocation(originalCommand);
+    return invocation === null ? null : { invocation, originalCommand, toolInput };
+}
+/** Logical lifecycle verb for one exact, simple shell command; otherwise null. */
+export function exactLifecycleCommandVerb(payload) {
+    return exactLifecyclePayload(payload)?.invocation.verb ?? null;
+}
+function sessionIdArgs(verb, args) {
+    const policy = LIFECYCLE_ARGUMENT_POLICIES[verb];
+    const values = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const token = args[i] ?? "";
+        if (token.startsWith("--session-id=")) {
+            const value = token.slice("--session-id=".length);
+            if (value.length === 0)
+                return { status: "invalid", values: [] };
+            values.push(value);
+            continue;
+        }
+        if (token === "--session-id") {
+            const value = args[i + 1];
+            if (value === undefined ||
+                value.length === 0 ||
+                (verb === "swarm:launch" && value.startsWith("--"))) {
+                return { status: "invalid", values: [] };
+            }
+            values.push(value);
+            i += 1;
+            continue;
+        }
+        if (token.indexOf("=") < 0 && policy.valueFlags.has(token) && args[i + 1] !== undefined)
+            i += 1;
+    }
+    if (values.length === 0)
+        return { status: "absent", values };
+    if (values.length !== 1)
+        return { status: "invalid", values };
+    return { status: "present", values };
+}
+/** Inspect one exact lifecycle command without requiring a host identity. */
+export function inspectExactLifecycleCommand(payload) {
+    const exact = exactLifecyclePayload(payload);
+    if (exact === null)
+        return null;
+    const session = sessionIdArgs(exact.invocation.verb, exact.invocation.forwardedArgs);
+    return {
+        verb: exact.invocation.verb,
+        task: exact.invocation.task,
+        rewriteSafe: exact.invocation.rewriteSafe,
+        requiresOwner: exact.invocation.requiresOwner,
+        sessionIdStatus: session.status,
+        sessionId: session.status === "present" ? (session.values[0] ?? null) : null,
+    };
+}
+/**
+ * Append a canonical host owner to one exact Directive lifecycle command.
+ *
+ * The returned `updatedInput` is a complete shallow clone of the original
+ * host tool input. `null` means no safe rewrite. An explicit foreign identity
+ * is surfaced as a conflict so dispatcher wiring can deny instead of replacing
+ * operator input.
+ */
+export function rewriteExactLifecycleCommand(payload, sessionId) {
+    if (!CANONICAL_OWNER_PATTERN.test(sessionId))
+        return null;
+    const exact = exactLifecyclePayload(payload);
+    if (exact === null)
+        return null;
+    const { invocation, originalCommand, toolInput } = exact;
+    if (!invocation.rewriteSafe || !invocation.requiresOwner)
+        return null;
+    const existing = sessionIdArgs(invocation.verb, invocation.forwardedArgs);
+    if (existing.status === "invalid")
+        return null;
+    if (existing.status === "present") {
+        const existingSessionId = existing.values[0] ?? "";
+        if (existingSessionId === sessionId)
+            return null;
+        return {
+            kind: "conflict",
+            verb: invocation.verb,
+            existingSessionId,
+            requestedSessionId: sessionId,
+            message: `Lifecycle command ${invocation.verb} already names a different ` +
+                "--session-id; refusing rewrite.",
+        };
+    }
+    const taskForwarding = invocation.task && originalCommand.split(" ").length === 2 ? " --" : "";
+    const rewrittenCommand = `${originalCommand}${taskForwarding} --session-id=${sessionId}`;
+    return {
+        kind: "rewrite",
+        verb: invocation.verb,
+        originalCommand,
+        rewrittenCommand,
+        updatedInput: { ...toolInput, command: rewrittenCommand },
+    };
+}
+//# sourceMappingURL=host-session-identity.js.map

package/dist/hooks/classify/index.d.ts

@@ -5,9 +5,10 @@
  * Policy / ritual / scope / permission emission stay in dispatcher + CLI adapter.
  */
 export { classifyHookPayload } from "./classify.js";
-export { hookMcpArgsText, hookPathSet, hookShellCommand, hookWriteTargetPath, } from "./paths.js";
+export { EXACT_LIFECYCLE_VERBS, type ExactLifecycleCommandConflict, type ExactLifecycleCommandInspection, type ExactLifecycleCommandResult, type ExactLifecycleCommandRewrite, type ExactLifecycleVerb, exactLifecycleCommandVerb, HOST_IDENTITY_PROVIDERS, type HookHostIdentityProvider, type HookHostIdentityResolution, type HookHostIdentityStatus, inspectExactLifecycleCommand, MAX_HOOK_HOST_IDENTITY_UTF8_BYTES, resolveHookHostIdentity, rewriteExactLifecycleCommand, } from "./host-session-identity.js";
+export { hookApplyPatchBodyPaths, hookMcpArgsText, hookMutationTargetPaths, hookPathSet, hookShellCommand, hookWriteTargetPath, } from "./paths.js";
 export { fieldPresent, fieldString, firstString, hookPayloadTopLevelKeys, record, toolInputRecord, } from "./payload.js";
-export { parseHookStdin, stripUtf8Bom } from "./stdin.js";
+export { applyPatchMutationPaths, parseHookStdin, stripUtf8Bom } from "./stdin.js";
 export { hookToolName, inferCursorDirectWriteToolName, type MissingToolNameInput, missingToolNameMessage, } from "./tool-name.js";
 export type { ClassifyHookHost, ClassifyHookPayloadInput, HookClassification, HookPayloadContext, HookWriteIntent, ParsedHookPayload, } from "./types.js";
 export { CLASSIFY_HOOK_HOSTS } from "./types.js";