@deksden-com/dd-flow-cli 0.9.0-beta.10 → 0.9.0-beta.100

package/dist/services/hooks.js

@@ -2,18 +2,22 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { parse, stringify } from "smol-toml";
+import { parse, stringify, TomlError } from "smol-toml";
 import { AppError } from "../shared/errors.js";
+import { entityReferenceVariants } from "../shared/entity-references.js";
 import { parseJsonObject } from "../shared/json.js";
-import { ensureDir, resolveProjectRoot } from "../storage/paths.js";
+import { canonicalPath, ensureDir, resolveProjectRoot } from "../storage/paths.js";
 import { appendAudit } from "./audit.js";
+import { prepareTextFile, prepareJsonText, prepareError } from "../cli/input-preparation.js";
 import { nativeSessionIdentity, storageSessionId } from "./session-identity.js";
-import { commandHasOption, commandOption, commandPosition, parseLifecycleCommand, unwrapShellCommand } from "./lifecycle-command.js";
+import { assertRecoveryHookCurrent } from "./run-recovery.js";
+import { observeLifecycleInvocation } from "./lifecycle-invocations.js";
+import { commandHasOption, commandOption, commandPosition, shellSuffixOffset, parseLifecycleCommand, lifecycleCommandFromPayload, continuationCommand } from "./lifecycle-command.js";
 import { registerProject, requireProjectByRoot } from "./projects.js";
-import { activeFlowSessionsForProject, bindObservedFlowSession, flowSessionPayloadFromRegisterCommand, recordFlowSessionObservation } from "./sessions.js";
+import { activeFlowSessionsForProject, recordFlowSessionObservation } from "./sessions.js";
 const defaultProfileName = "default";
 const maxSanitizedSummaryLength = 1600;
-const sharedEntries = [
+export const codexHomeSharedEntries = [
     "auth.json",
     "auth.bk",
     "sessions",
@@ -50,22 +54,28 @@ export function planCodexHome(context, input) {
         config_path: paths.configPath,
         hooks_path: paths.hooksPath,
         owned_files: ["config.toml", "hooks.json", ".dd-flow-home.json", "log/", ".tmp/", "tmp/"],
-        shared_entries: sharedEntries,
+        shared_entries: codexHomeSharedEntries,
         exists: fs.existsSync(paths.targetHome),
         codex_env: { CODEX_HOME: paths.targetHome }
     };
 }
-export function initCodexHome(context, input) {
+export function prepareCodexHome(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const profile = resolveProfileName(input.profile);
     const paths = resolveHomePaths(context, project, profile, input);
+    if (canonicalPath(paths.sourceHome, false) === canonicalPath(paths.targetHome, false))
+        throw new AppError("validation", "Managed Codex home must differ from its source home", 2);
+    const config = readTomlIfExists(path.join(paths.sourceHome, "config.toml"));
+    return { project, profile, paths, config };
+}
+export function initCodexHome(context, input, prepared = prepareCodexHome(context, input)) {
+    const { project, profile, paths, config } = prepared;
     const now = context.now();
     ensureDir(paths.targetHome);
     ensureDir(path.join(paths.targetHome, "log"));
     ensureDir(path.join(paths.targetHome, ".tmp"));
     ensureDir(path.join(paths.targetHome, "tmp"));
     const linked = createSharedLinks(paths.sourceHome, paths.targetHome);
-    const config = readTomlIfExists(path.join(paths.sourceHome, "config.toml"));
     fs.writeFileSync(paths.configPath, stringify(withManagedConfig(config, paths.sourceHome, paths.targetHome)));
     writeJsonFile(paths.hooksPath, expectedHooksConfig(project.root));
     writeJsonFile(path.join(paths.targetHome, ".dd-flow-home.json"), {
@@ -136,7 +146,7 @@ export function printCodexHomeEnv(context, input) {
         command_prefix: `CODEX_HOME=${JSON.stringify(record.target_home)}`
     };
 }
-export function removeCodexHome(context, input) {
+export function prepareCodexHomeRemoval(context, input) {
     if (!["keep-shared", "remove-owned"].includes(input.mode)) {
         throw new AppError("validation", "--mode must be keep-shared or remove-owned", 2);
     }
@@ -144,9 +154,30 @@ export function removeCodexHome(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const profile = resolveProfileName(input.profile);
     const record = homeProfile(context, project.id, profile);
+    if (record && record.status !== "removed" && fs.existsSync(record.target_home)) {
+        let marker;
+        try {
+            const value = JSON.parse(fs.readFileSync(path.join(record.target_home, ".dd-flow-home.json"), "utf8"));
+            if (!value || typeof value !== "object" || Array.isArray(value))
+                throw new Error("Invalid marker");
+            marker = value;
+        }
+        catch {
+            throw new AppError("runtime_artifact_invalid", "Managed Codex home ownership marker is missing or invalid; refusing removal", 1, { target_home: record.target_home });
+        }
+        if (marker.managed_by !== "dd-flow-cli" || marker.project_id !== project.id || marker.profile !== profile || marker.target_home !== record.target_home || marker.source_home !== record.source_home || canonicalPath(record.target_home, false) === canonicalPath(record.source_home, false)) {
+            throw new AppError("runtime_artifact_invalid", "Managed Codex home ownership does not match its registration; refusing removal", 1, { target_home: record.target_home });
+        }
+    }
+    return { project, profile, record, mode };
+}
+export function removeCodexHome(context, input) {
+    const { project, profile, record, mode } = prepareCodexHomeRemoval(context, input);
     if (!record) {
         return { ok: true, removed: false, profile, status: "not_initialized" };
     }
+    if (record.status === "removed")
+        return { ok: true, removed: false, profile, status: "already_removed" };
     const removedEntries = [];
     for (const relative of ["config.toml", "hooks.json", ".dd-flow-home.json", "log", ".tmp", "tmp"]) {
         const target = path.join(record.target_home, relative);
@@ -207,7 +238,7 @@ export function getCodexHooksStatus(context, input) {
         recorded
     };
 }
-export function installCodexHooks(context, input) {
+export function prepareCodexHooks(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const target = resolveHookTarget(input.target);
     const location = requireHookLocation(context, project, target, resolveProfileName(input.profile));
@@ -217,9 +248,16 @@ export function installCodexHooks(context, input) {
             hooks_path: location.hooksPath
         });
     }
-    const existing = readJsonIfExists(location.hooksPath) ?? {};
-    const backup = target === "default" && fs.existsSync(location.hooksPath) ? backupFile(location.hooksPath, context.now()) : null;
+    const text = fs.existsSync(location.hooksPath) ? prepareTextFile(location.hooksPath, "hooks configuration").text : null;
+    const existing = text === null ? {} : prepareJsonText(text, { file: location.hooksPath }).value;
+    if (!existing || typeof existing !== "object" || Array.isArray(existing) || (existing.hooks !== undefined && (!existing.hooks || typeof existing.hooks !== "object" || Array.isArray(existing.hooks) || Object.values(existing.hooks).some(entries => !Array.isArray(entries)))))
+        return prepareError(new AppError("validation", "Hooks configuration requires an object with event arrays", 2), { file: location.hooksPath });
+    return { project, target, location, existing, text };
+}
+export function installCodexHooks(context, input, prepared = prepareCodexHooks(context, input)) {
+    const { project, target, location, existing, text } = prepared;
     const nextConfig = mergeHooksConfig(existing, project.root);
+    const backup = target === "default" && text !== null ? backupFile(location.hooksPath, context.now(), text) : null;
     ensureDir(path.dirname(location.hooksPath));
     writeJsonFile(location.hooksPath, nextConfig);
     recordHookInstallation(context, project.id, installationScope(target, location.profile, location.hooksPath), location.hooksPath, true, "none");
@@ -238,20 +276,11 @@ export function installCodexHooks(context, input) {
         expected_hash: hashObject(expectedHooksConfig(project.root))
     };
 }
-export function removeCodexHooks(context, input) {
-    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
-    const target = resolveHookTarget(input.target);
-    const location = requireHookLocation(context, project, target, resolveProfileName(input.profile));
-    if (target === "default" && !input.yes) {
-        throw new AppError("confirmation_required", "Direct default Codex home mutation requires --yes", 1, {
-            target,
-            hooks_path: location.hooksPath
-        });
-    }
-    const existing = readJsonIfExists(location.hooksPath) ?? {};
+export function removeCodexHooks(context, input, prepared = prepareCodexHooks(context, input)) {
+    const { project, target, location, existing, text } = prepared;
     const hadManaged = hasManagedHooks(existing, project.root);
-    const backup = target === "default" && fs.existsSync(location.hooksPath) ? backupFile(location.hooksPath, context.now()) : null;
     const nextConfig = removeManagedHooks(existing, project.root);
+    const backup = target === "default" && text !== null ? backupFile(location.hooksPath, context.now(), text) : null;
     ensureDir(path.dirname(location.hooksPath));
     writeJsonFile(location.hooksPath, nextConfig);
     recordHookInstallation(context, project.id, installationScope(target, location.profile, location.hooksPath), location.hooksPath, false, "not_installed");
@@ -268,207 +297,292 @@ export function handleCodexHook(context, input) {
     if (eventName !== "PreToolUse") {
         return { ok: true, observed: false, reason: "event_not_participating", event: eventName };
     }
-    const sessionId = stringValue(payload.session_id);
+    const rootProviderSessionId = stringValue(payload.session_id) ?? null;
+    // Codex deliberately retains its legacy root session_id inside a
+    // thread-spawned subagent. `agent_id` is the current child Thread id and
+    // therefore the only valid identity for a fresh Work.
+    const rawChildProviderSessionId = stringValue(payload.agent_id) ?? null;
+    const providerSessionId = rawChildProviderSessionId ?? rootProviderSessionId;
     const turnId = stringValue(payload.turn_id);
     const toolName = stringValue(payload.tool_name) ?? toolNameFromPayload(payload);
     const command = lifecycleCommandFromPayload(payload);
     if (!command)
         return { ok: true, observed: false, reason: "non_bash_tool" };
     const lifecycle = lifecycleFacts(command);
-    if (!lifecycle)
+    if (!lifecycle && !continuationCommand(command))
         return { ok: true, observed: false, reason: "event_not_participating", event: eventName };
+    const parentProviderSessionId = rawChildProviderSessionId ? codexNativeParentId(payload, rawChildProviderSessionId) : null;
     // Resume legitimately receives an answer through stdin. It is matched by
     // immutable lifecycle arguments below; never reject or rewrite that pipe.
-    if (lifecycle.analysis.kind === "compound") {
-        return {
-            ok: false,
-            observed: false,
-            reason: "compound_lifecycle_command",
-            message: "Run the dd-flow lifecycle invocation as the first technical action and as one standalone Bash command in this same Session.",
-            standalone_command: lifecycle.invocation.command,
-            hookSpecificOutput: {
-                hookEventName: "PreToolUse",
-                permissionDecision: "deny",
-                permissionDecisionReason: `dd-flow lifecycle commands must be standalone. Retry in this same Session: ${lifecycle.invocation.command}`
-            }
-        };
+    const bootstrapStageStart = lifecycle?.bootstrapStageStart;
+    const invocationId = lifecycle ? commandOption(lifecycle.invocation, "invocation-id") : undefined;
+    if (invocationId || context.env.DD_FLOW_DAEMON_ID) {
+        const proof = context.codexHookProof;
+        if (!proof || proof.daemonId !== context.env.DD_FLOW_DAEMON_ID || proof.rootSessionId !== rootProviderSessionId
+            || proof.sessionId !== providerSessionId || proof.parentSessionId !== parentProviderSessionId
+            || proof.toolCallId !== payload.tool_use_id || proof.command !== command) {
+            throw new AppError("native_hook_unproven", "Managed Codex admission requires its active native hook delivery, not a manual handler call", 1, { ...(invocationId ? { invocation_id: invocationId } : {}), effect: "no_effect" });
+        }
     }
-    const { flowPayload, stageStart, stageResume, workStart, bootstrapStageStart, commandProjectRoot } = lifecycle;
-    const matchKey = commandProjectRoot ? lifecycleMatchKey(lifecycle, commandProjectRoot) : null;
+    const nativeProjectRoot = context.codexHookProof?.projectRoot ?? input.projectRoot;
     // A bootstrap stage is the first stateful command for a new materialized project.
     // Its PreToolUse event arrives before stage start can register that project.
-    if (bootstrapStageStart && commandProjectRoot) {
-        registerProject(context, { root: commandProjectRoot });
+    const bootstrapRoot = nativeProjectRoot ?? stringValue(payload.cwd);
+    if (bootstrapStageStart && bootstrapRoot) {
+        registerProject(context, { root: bootstrapRoot });
     }
-    const project = projectForHook(context, input.projectRoot ?? commandProjectRoot, stringValue(payload.cwd));
-    if (!project)
+    const project = projectForHook(context, nativeProjectRoot, stringValue(payload.cwd));
+    if (!project) {
+        if (invocationId)
+            throw new AppError("project_not_registered", "Managed lifecycle invocation has no registered project", 1, { project_root: nativeProjectRoot ?? null });
         return { ok: true, observed: false, reason: "unrelated_cwd" };
-    const binding = sessionId ? upsertSessionBindingFromPayload(context, project, sessionId, payload) : undefined;
-    const storageId = sessionId ? storageSessionId(nativeSessionIdentity("codex-desktop", sessionId)) : null;
-    const observedSession = flowPayload
-        ? bindObservedFlowSession(context, project, { ...flowPayload, harness: "codex-desktop", provider_session_id: sessionId ?? flowPayload.provider_session_id ?? null }, storageId ?? undefined)
-        : undefined;
-    const effectiveSessionId = observedSession?.session_id ?? storageId;
-    const protocolId = observedSession?.protocol_id ?? binding?.protocol_id ?? null;
+    }
+    let matchKey = lifecycle ? lifecycleMatchKey(lifecycle, project.root) : null;
+    // Codex retains the root session_id for a thread-spawned child, while the
+    // payload transcript belongs to the current agent_id. Keep lineage separate
+    // from ownership: otherwise a child overwrites the root transcript binding.
     const eventKey = hookEventKey(payload, eventName, toolName, command);
-    const inserted = recordHookEvent(context, {
-        projectId: project.id,
-        protocolId,
-        harness: "codex-desktop",
-        providerSessionId: sessionId ?? null,
-        parentSessionId: null,
-        sessionId: effectiveSessionId,
-        agentId: stringValue(payload.agent_id) ?? null,
-        turnId: turnId ?? null,
-        eventName,
-        toolName: toolName ?? null,
-        status: "observed",
-        payload,
-        eventKey,
-        matchKey,
-        transcriptPath: binding?.transcript_path ?? null,
-        cwd: stringValue(payload.cwd) ?? null
-    });
-    if (effectiveSessionId) {
-        recordFlowSessionObservation(context, {
+    const storageId = providerSessionId ? storageSessionId(nativeSessionIdentity("codex-desktop", providerSessionId)) : null;
+    const parentSessionId = parentProviderSessionId ? storageSessionId(nativeSessionIdentity("codex-desktop", parentProviderSessionId)) : null;
+    const eventCwd = stringValue(payload.cwd) ?? project.root;
+    assertHookEventReplay(context, { projectId: project.id, eventKey, harness: "codex-desktop", providerSessionId: providerSessionId ?? null, parentSessionId, daemonId: stringValue(context.env.DD_FLOW_DAEMON_ID) ?? null, sessionId: storageId, turnId: turnId ?? null, eventName, toolName: toolName ?? null, matchKey, cwd: eventCwd });
+    const bindingOwnerId = providerSessionId ?? rootProviderSessionId;
+    // Resolve legacy transcript discovery before acquiring the receipt write lock.
+    const transcriptPath = stringValue(payload.transcript_path)
+        ?? (bindingOwnerId ? sessionBinding(context, project.id, bindingOwnerId)?.transcript_path ?? locateCodexTranscript(bindingOwnerId, context.env.CODEX_HOME) : null);
+    const persist = (scope) => {
+        if (scope)
+            matchKey = lifecycleMatchKey(lifecycleFacts(scope.command), project.root, scope);
+        const binding = bindingOwnerId ? upsertSessionBindingFromPayload(context, project, bindingOwnerId, payload, transcriptPath) : undefined;
+        const effectiveSessionId = storageId;
+        const protocolId = binding?.protocol_id ?? null;
+        const inserted = recordHookEvent(context, {
             projectId: project.id,
-            sessionId: effectiveSessionId,
-            runId: observedSession?.run_id ?? null,
             protocolId,
-            cwd: stringValue(payload.cwd) ?? null,
+            harness: "codex-desktop",
+            providerSessionId: providerSessionId ?? null,
+            parentSessionId,
+            // Pinned by the owning app-server process, never derived from current RUN
+            // state or an agent-supplied shell command/payload.
+            daemonId: stringValue(context.env.DD_FLOW_DAEMON_ID) ?? null,
+            sessionId: effectiveSessionId,
+            agentId: rawChildProviderSessionId ?? null,
+            turnId: turnId ?? null,
+            eventName,
             toolName: toolName ?? null,
-            eventKey
+            status: "observed",
+            payload,
+            eventKey,
+            matchKey,
+            transcriptPath: binding?.transcript_path ?? null,
+            cwd: stringValue(payload.cwd) ?? project.root
         });
-    }
-    return {
+        if (effectiveSessionId) {
+            recordFlowSessionObservation(context, {
+                projectId: project.id,
+                sessionId: effectiveSessionId,
+                protocolId,
+                cwd: eventCwd,
+                toolName: toolName ?? null,
+                eventKey
+            });
+        }
+        return { inserted, protocolId };
+    };
+    const common = {
         ok: true,
-        observed: inserted,
-        duplicate: !inserted,
         event_key: eventKey,
-        session: sessionId ? nativeSessionIdentity("codex-desktop", sessionId) : null,
-        protocol_id: protocolId,
-        ...(sessionId && (flowPayload || stageStart || stageResume || workStart)
+        session: providerSessionId ? nativeSessionIdentity("codex-desktop", providerSessionId) : null,
+        ...(parentProviderSessionId ? { parent_session: nativeSessionIdentity("codex-desktop", parentProviderSessionId) } : {}),
+        protocol_id: null
+    };
+    if (!lifecycle) {
+        const persisted = context.db.writeTransaction(() => persist());
+        return { ...common, observed: persisted.inserted, duplicate: !persisted.inserted };
+    }
+    if (invocationId || context.env.DD_FLOW_DAEMON_ID) {
+        const daemonId = stringValue(context.env.DD_FLOW_DAEMON_ID);
+        const toolCallId = stringValue(payload.tool_use_id) ?? stringValue(payload.event_id) ?? stringValue(payload.delivery_id) ?? stringValue(payload.id);
+        if (!daemonId || !rootProviderSessionId || !providerSessionId || !toolCallId)
+            throw new AppError("codex_identity_missing", "Managed Codex lifecycle hook has no complete native invocation identity", 1, { invocation_id: invocationId });
+        const receipt = observeLifecycleInvocation(context, {
+            ...(invocationId ? { id: invocationId } : {}),
+            command,
+            harness: "codex-desktop",
+            identity: { daemonId, rootSessionId: rootProviderSessionId, sessionId: providerSessionId, parentSessionId: parentProviderSessionId, toolCallId },
+            recordReceipt: scope => { persist(scope); return eventKey; }
+        });
+        const stored = context.db.get("SELECT protocol_id FROM hook_events WHERE project_id = ? AND event_key = ?", [project.id, receipt.eventKey]);
+        const admittedInvocationId = receipt.invocationId ?? invocationId;
+        if (admittedInvocationId)
+            return { ...common, protocol_id: stored?.protocol_id ?? null, observed: !receipt.duplicate, duplicate: receipt.duplicate, event_key: receipt.eventKey, invocation_id: admittedInvocationId };
+        return {
+            ...common,
+            protocol_id: stored?.protocol_id ?? null,
+            observed: !receipt.duplicate,
+            duplicate: receipt.duplicate,
+            hookSpecificOutput: {
+                hookEventName: "PreToolUse",
+                permissionDecision: "allow",
+                updatedInput: { ...objectRecord(payload.tool_input), command: commandWithHookEvent(command, eventKey) }
+            }
+        };
+    }
+    const persisted = persist();
+    return {
+        ...common,
+        protocol_id: persisted.protocolId,
+        observed: persisted.inserted,
+        duplicate: !persisted.inserted,
+        ...(providerSessionId
             ? {
                 hookSpecificOutput: {
                     hookEventName: "PreToolUse",
                     permissionDecision: "allow",
-                    updatedInput: { command: commandWithHookEvent(command, eventKey) }
+                    updatedInput: { ...objectRecord(payload.tool_input), command: commandWithHookEvent(command, eventKey) }
                 }
             }
             : {})
     };
 }
-/** Convert a zcode-acp Bash tool notification into the same trusted lifecycle receipt used by Codex hooks. */
+/** The hook protocol does not carry the immediate parent. Recover it only from this child's own native transcript. */
+function codexNativeParentId(payload, childId) {
+    const transcript = stringValue(payload.transcript_path);
+    if (!transcript || !path.isAbsolute(transcript))
+        return null;
+    try {
+        const descriptor = fs.openSync(transcript, "r");
+        const chunks = [];
+        try {
+            for (;;) {
+                const buffer = Buffer.alloc(4096);
+                const length = fs.readSync(descriptor, buffer, 0, buffer.length, null);
+                if (!length)
+                    break;
+                const newline = buffer.subarray(0, length).indexOf(10);
+                chunks.push(buffer.subarray(0, newline < 0 ? length : newline));
+                if (newline >= 0)
+                    break;
+            }
+        }
+        finally {
+            fs.closeSync(descriptor);
+        }
+        const firstLine = Buffer.concat(chunks).toString("utf8");
+        if (!firstLine)
+            return null;
+        const record = JSON.parse(firstLine);
+        return record.type === "session_meta" && record.payload?.id === childId && typeof record.payload.parent_thread_id === "string"
+            ? record.payload.parent_thread_id
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** ACP is asynchronous evidence. Only an explicitly issued invocation may use
+ * it as the receipt that its CLI waits for; this is not a PreToolUse hook. */
 export function handleZcodeEvent(context, input) {
     const notification = parseJsonObject(input.stdin || "{}", "zcode ACP notification");
-    if (notification.method !== "session/update")
-        return { ok: true, observed: false, reason: "event_not_participating" };
-    const params = objectRecord(notification.params);
-    const update = objectRecord(params.update);
-    if (update.sessionUpdate !== "tool_call")
+    const params = objectRecord(notification.params), update = objectRecord(params.update);
+    if (notification.method !== "session/update" || update.sessionUpdate !== "tool_call")
         return { ok: true, observed: false, reason: "event_not_participating" };
-    const updateMeta = objectRecord(update._meta);
-    const claudeCode = objectRecord(updateMeta.claudeCode);
-    const runtime = objectRecord(updateMeta.zcodeRuntime);
-    const toolName = stringValue(claudeCode.toolName) ?? stringValue(update.kind);
-    const rawInput = objectRecord(update.rawInput);
+    const rawInput = objectRecord(update.rawInput), meta = objectRecord(update._meta), native = objectRecord(meta.zcodeRuntime);
+    const toolName = stringValue(objectRecord(meta.claudeCode).toolName);
+    if (toolName !== "Bash" && toolName !== "bash" && toolName !== "execute")
+        return { ok: true, observed: false, reason: "non_bash_tool" };
     const command = stringValue(rawInput.command) ?? stringValue(rawInput.cmd);
-    if (!command || (toolName && toolName !== "Bash" && toolName !== "bash" && update.kind !== "execute")) {
+    const parsed = command ? parseLifecycleCommand(command) : { kind: "none" };
+    if (parsed.kind === "none")
+        return { ok: true, observed: false, reason: "acp_evidence_only" };
+    const controlled = objectRecord(objectRecord(notification._meta).ddZcode);
+    const providerSessionId = stringValue(native.childSessionId) ?? stringValue(controlled.rootProviderSessionId);
+    return recordZcodeLifecycle(context, { projectRoot: input.projectRoot, stdin: JSON.stringify({
+            session_id: providerSessionId, tool_use_id: update.toolCallId, tool_name: toolName, tool_input: rawInput,
+            agent_id: native.agentId, _meta: { ddZcode: controlled }
+        }) }, commandOption(parsed.invocation, "invocation-id"));
+}
+/**
+ * Accept the synchronous native ZCode PreToolUse callback. Invocation-ID
+ * commands instead rendezvous with their ACP event while the CLI awaits
+ * admission; the native hook must not create a competing receipt for them.
+ */
+export function handleZcodeHook(context, input) {
+    return recordZcodeLifecycle(context, input);
+}
+function recordZcodeLifecycle(context, input, invocationId) {
+    const hook = parseJsonObject(input.stdin || "{}", "ZCode hook event");
+    const eventName = stringValue(hook.hook_event_name) ?? stringValue(hook.hookEventName);
+    if (eventName && eventName !== "PreToolUse" && eventName !== "pre_tool_use")
+        return { ok: true, observed: false, reason: "event_not_participating" };
+    const toolName = stringValue(hook.tool_name) ?? stringValue(hook.toolName);
+    const rawInput = objectRecord(hook.tool_input ?? hook.toolInput);
+    const command = stringValue(rawInput.command) ?? stringValue(rawInput.cmd) ?? stringValue(hook.command);
+    if (!command || (toolName && toolName !== "Bash" && toolName !== "bash" && toolName !== "execute"))
         return { ok: true, observed: false, reason: "non_bash_tool" };
-    }
     const lifecycle = lifecycleFacts(command);
-    if (!lifecycle)
+    if (!lifecycle && !continuationCommand(command))
         return { ok: true, observed: false, reason: "event_not_participating" };
-    if (lifecycle.analysis.kind === "compound") {
-        throw new AppError("compound_lifecycle_command", "dd-flow lifecycle commands must be a standalone ZCode Bash tool call", 1, {
-            standalone_command: lifecycle.invocation.command
-        });
-    }
-    const { flowPayload, bootstrapStageStart, commandProjectRoot } = lifecycle;
+    if (!invocationId && lifecycle && commandOption(lifecycle.invocation, "invocation-id"))
+        return { ok: true, observed: false, reason: "cli_invocation_owns_admission" };
     const expectedRoot = resolveProjectRoot(input.projectRoot);
-    if (commandProjectRoot && resolveProjectRoot(commandProjectRoot) !== expectedRoot) {
-        throw new AppError("project_mismatch", "ZCode lifecycle command project root does not match the controlled workspace", 1, {
-            expected: expectedRoot,
-            actual: commandProjectRoot
-        });
+    const meta = objectRecord(hook._meta);
+    const ddZcode = objectRecord(meta.ddZcode);
+    const providerSessionId = stringValue(hook.session_id) ?? stringValue(hook.sessionId);
+    const rootProviderSessionId = stringValue(ddZcode.rootProviderSessionId);
+    const parentProviderSessionId = stringValue(ddZcode.parentProviderSessionId);
+    const daemonId = stringValue(ddZcode.daemonId);
+    if (!providerSessionId || !rootProviderSessionId || !daemonId) {
+        throw new AppError("zcode_identity_missing", "ZCode native hook has no controlled Session identity", 1);
     }
-    const matchKey = lifecycleMatchKey(lifecycle, expectedRoot);
-    if (bootstrapStageStart)
+    if (providerSessionId === rootProviderSessionId ? parentProviderSessionId : !parentProviderSessionId) {
+        throw new AppError("zcode_identity_missing", "ZCode native hook has inconsistent Session ancestry", 1);
+    }
+    const toolUseId = stringValue(hook.tool_use_id) ?? stringValue(hook.toolUseId) ?? stringValue(hook.event_id) ?? stringValue(hook.eventId);
+    if (!toolUseId)
+        throw new AppError("zcode_hook_event_missing", "ZCode native hook has no tool-use ID", 1);
+    const eventKey = crypto.createHash("sha256").update(JSON.stringify(["zcode-acp", daemonId, providerSessionId, toolUseId])).digest("hex");
+    const rewritten = invocationId ? command : commandWithHookEvent(command, eventKey);
+    if (lifecycle?.bootstrapStageStart)
         registerProject(context, { root: expectedRoot });
     const project = requireProjectByRoot(context, expectedRoot);
-    const envelopeMeta = objectRecord(notification._meta);
-    const ddZcode = objectRecord(envelopeMeta.ddZcode);
-    const observedProfile = objectRecord(ddZcode.observedProfile);
-    const rootProviderSessionId = stringValue(ddZcode.rootProviderSessionId) ?? stringValue(params.sessionId);
-    const daemonId = stringValue(ddZcode.daemonId);
-    if (!rootProviderSessionId)
-        throw new AppError("zcode_identity_missing", "ZCode ACP event has no root provider Session ID", 1);
-    const childProviderSessionId = stringValue(runtime.childSessionId);
-    const providerSessionId = childProviderSessionId ?? rootProviderSessionId;
     const sessionId = storageSessionId(nativeSessionIdentity("zcode-acp", providerSessionId));
-    const parentSessionId = childProviderSessionId ? storageSessionId(nativeSessionIdentity("zcode-acp", rootProviderSessionId)) : null;
-    const agentId = stringValue(runtime.agentId);
-    const observedSession = flowPayload ? bindObservedFlowSession(context, project, {
-        ...flowPayload,
-        harness: "zcode-acp",
-        provider_session_id: providerSessionId,
-        agent_id: agentId ?? null,
-        parent_session_id: parentSessionId
-    }, sessionId) : undefined;
-    const eventKey = stringValue(update.toolCallId) ?? crypto.createHash("sha256").update(JSON.stringify({
-        harness: "zcode-acp", providerSessionId, command
-    })).digest("hex");
-    const payload = {
-        session_id: providerSessionId,
-        agent_id: agentId,
-        cwd: expectedRoot,
-        tool_name: toolName ?? "Bash",
-        tool_input: rawInput,
-        command,
-        provider: stringValue(observedProfile.provider),
-        model: stringValue(observedProfile.model),
-        reasoning: stringValue(observedProfile.reasoning),
-        mode: stringValue(observedProfile.mode),
-        agent_type: stringValue(runtime.source)
+    const parentSessionId = parentProviderSessionId ? storageSessionId(nativeSessionIdentity("zcode-acp", parentProviderSessionId)) : null;
+    const observedProfile = objectRecord(ddZcode.observedProfile);
+    let matchKey = lifecycle ? lifecycleMatchKey(lifecycle, expectedRoot) : null;
+    const eventNameForReceipt = invocationId ? "ToolCallObserved" : "PreToolUse";
+    const persist = (scope) => {
+        if (scope)
+            matchKey = lifecycleMatchKey(lifecycleFacts(scope.command), expectedRoot, scope);
+        assertHookEventReplay(context, { projectId: project.id, eventKey, harness: "zcode-acp", providerSessionId, parentSessionId, daemonId, sessionId, turnId: null, eventName: eventNameForReceipt, toolName: toolName ?? "Bash", matchKey, cwd: expectedRoot });
+        const payload = { ...hook, session_id: providerSessionId, cwd: expectedRoot, tool_name: toolName ?? "Bash", tool_input: rawInput,
+            command, provider: stringValue(observedProfile.provider), model: stringValue(observedProfile.model), reasoning: stringValue(observedProfile.reasoning), mode: stringValue(observedProfile.mode) };
+        const inserted = recordHookEvent(context, {
+            projectId: project.id, protocolId: null, harness: "zcode-acp", providerSessionId, parentSessionId,
+            daemonId, sessionId, agentId: stringValue(hook.agent_id) ?? stringValue(hook.agentId) ?? null, turnId: null,
+            eventName: eventNameForReceipt, toolName: toolName ?? "Bash", status: "observed", payload, eventKey, matchKey,
+            transcriptPath: stringValue(hook.transcript_path) ?? null, cwd: expectedRoot
+        });
+        recordFlowSessionObservation(context, { projectId: project.id, sessionId, cwd: expectedRoot, toolName: toolName ?? "Bash", eventKey });
+        const result = { ok: true, observed: inserted, duplicate: !inserted, event_key: eventKey, harness: "zcode-acp", session: nativeSessionIdentity("zcode-acp", providerSessionId), ...(parentProviderSessionId ? { parent_session: nativeSessionIdentity("zcode-acp", parentProviderSessionId) } : {}), daemon_id: daemonId };
+        return { ...result, hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput: { ...rawInput, command: rewritten } } };
     };
-    const inserted = recordHookEvent(context, {
-        projectId: project.id,
-        protocolId: observedSession?.protocol_id ?? null,
+    if (!lifecycle)
+        return context.db.writeTransaction(() => persist());
+    let persistedResult;
+    const receipt = observeLifecycleInvocation(context, {
+        ...(invocationId ? { id: invocationId } : {}), command,
         harness: "zcode-acp",
-        providerSessionId,
-        parentSessionId,
-        daemonId: daemonId ?? null,
-        sessionId,
-        agentId: agentId ?? null,
-        turnId: null,
-        eventName: "PreToolUse",
-        toolName: toolName ?? "Bash",
-        status: "observed",
-        payload,
-        eventKey,
-        matchKey,
-        transcriptPath: null,
-        cwd: expectedRoot
+        identity: { daemonId, rootSessionId: rootProviderSessionId, sessionId: providerSessionId, parentSessionId: parentProviderSessionId ?? null, toolCallId: toolUseId },
+        recordReceipt: scope => { persistedResult = persist(scope); return eventKey; }
     });
-    recordFlowSessionObservation(context, {
-        projectId: project.id,
-        sessionId,
-        runId: observedSession?.run_id ?? null,
-        protocolId: observedSession?.protocol_id ?? null,
-        cwd: expectedRoot,
-        toolName: toolName ?? "Bash",
-        eventKey
-    });
-    return {
-        ok: true,
-        observed: inserted,
-        duplicate: !inserted,
-        event_key: eventKey,
-        harness: "zcode-acp",
-        session: nativeSessionIdentity("zcode-acp", providerSessionId),
-        ...(childProviderSessionId ? { parent_session: nativeSessionIdentity("zcode-acp", rootProviderSessionId) } : {}),
-        daemon_id: daemonId ?? null
-    };
+    const admittedInvocationId = receipt.invocationId ?? invocationId;
+    if (admittedInvocationId)
+        return { ok: true, observed: !receipt.duplicate, duplicate: receipt.duplicate, event_key: receipt.eventKey, invocation_id: admittedInvocationId };
+    // Without an issued managed attempt this is still ordinary hook evidence.
+    // Preserve persist()'s replay result instead of overwriting it with the
+    // admission layer's non-authoritative duplicate flag.
+    return persistedResult ?? persist();
 }
 /** Convert a Grok Build PreToolUse hook into a trusted lifecycle receipt. */
 export function handleGrokEvent(context, input) {
@@ -484,21 +598,11 @@ export function handleGrokEvent(context, input) {
         return { ok: true, observed: false, reason: "non_bash_tool" };
     }
     const lifecycle = lifecycleFacts(command);
-    if (!lifecycle)
+    if (!lifecycle && !continuationCommand(command))
         return { ok: true, observed: false, reason: "event_not_participating" };
-    if (lifecycle.analysis.kind === "compound") {
-        throw new AppError("compound_lifecycle_command", "dd-flow lifecycle commands must be a standalone Grok Build tool call", 1, {
-            standalone_command: lifecycle.invocation.command
-        });
-    }
-    const { flowPayload, stageStart, stageResume, workStart, bootstrapStageStart, commandProjectRoot } = lifecycle;
+    const bootstrapStageStart = lifecycle?.bootstrapStageStart;
     const expectedRoot = resolveProjectRoot(input.projectRoot);
-    if (commandProjectRoot && resolveProjectRoot(commandProjectRoot) !== expectedRoot) {
-        throw new AppError("project_mismatch", "Grok Build lifecycle command project root does not match the controlled workspace", 1, {
-            expected: expectedRoot, actual: commandProjectRoot
-        });
-    }
-    const matchKey = lifecycleMatchKey(lifecycle, expectedRoot);
+    const matchKey = lifecycle ? lifecycleMatchKey(lifecycle, expectedRoot) : null;
     if (bootstrapStageStart)
         registerProject(context, { root: expectedRoot });
     const project = requireProjectByRoot(context, expectedRoot);
@@ -514,41 +618,50 @@ export function handleGrokEvent(context, input) {
     const parentSessionId = isChild ? storageSessionId(nativeSessionIdentity("grok-acp", stringValue(ddGrok.parentProviderSessionId) ?? rootProviderSessionId)) : null;
     const daemonId = stringValue(ddGrok.daemonId);
     const agentId = stringValue(hook.agent_id) ?? stringValue(hook.agentId);
-    const observedSession = flowPayload ? bindObservedFlowSession(context, project, {
-        ...flowPayload, harness: "grok-acp", provider_session_id: providerSessionId, agent_id: agentId ?? null, parent_session_id: parentSessionId
-    }, sessionId) : undefined;
     const eventKey = stringValue(hook.event_id) ?? stringValue(hook.eventId) ?? crypto.createHash("sha256").update(JSON.stringify({
-        harness: "grok-acp", providerSessionId, command, turn: hook.turn_id ?? hook.turnId ?? null
+        harness: "grok-acp", providerSessionId, toolUseId: hook.tool_use_id ?? hook.toolUseId ?? null,
+        promptId: hook.prompt_id ?? hook.promptId ?? null, command, turn: hook.turn_id ?? hook.turnId ?? null
     })).digest("hex");
+    assertHookEventReplay(context, { projectId: project.id, eventKey, harness: "grok-acp", providerSessionId, parentSessionId, daemonId: daemonId ?? null, sessionId, turnId: stringValue(hook.turn_id) ?? stringValue(hook.turnId) ?? null, eventName: "PreToolUse", toolName: toolName ?? "Bash", matchKey, cwd: expectedRoot });
     const payload = {
         ...hook, session_id: providerSessionId, agent_id: agentId, cwd: expectedRoot, tool_name: toolName ?? "Bash", tool_input: rawInput,
         command, provider: stringValue(observedProfile.provider), model: stringValue(observedProfile.model), reasoning: stringValue(observedProfile.reasoning), mode: stringValue(observedProfile.mode), agent_type: stringValue(hook.subagent_type) ?? stringValue(hook.subagentType)
     };
     const inserted = recordHookEvent(context, {
-        projectId: project.id, protocolId: observedSession?.protocol_id ?? null, harness: "grok-acp", providerSessionId, parentSessionId,
+        projectId: project.id, protocolId: null, harness: "grok-acp", providerSessionId, parentSessionId,
         daemonId: daemonId ?? null, sessionId, agentId: agentId ?? null, turnId: stringValue(hook.turn_id) ?? stringValue(hook.turnId) ?? null,
         eventName: "PreToolUse", toolName: toolName ?? "Bash", status: "observed", payload, eventKey, matchKey, transcriptPath: null, cwd: expectedRoot
     });
     recordFlowSessionObservation(context, {
-        projectId: project.id, sessionId, runId: observedSession?.run_id ?? null, protocolId: observedSession?.protocol_id ?? null,
+        projectId: project.id, sessionId,
         cwd: expectedRoot, toolName: toolName ?? "Bash", eventKey
     });
     const result = { ok: true, observed: inserted, duplicate: !inserted, event_key: eventKey, session: nativeSessionIdentity("grok-acp", providerSessionId),
         ...(isChild ? { parent_session: nativeSessionIdentity("grok-acp", stringValue(ddGrok.parentProviderSessionId) ?? rootProviderSessionId) } : {}), daemon_id: daemonId ?? null };
-    return (flowPayload || stageStart || stageResume || workStart)
-        ? { ...result, hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput: { ...(rawInput ?? {}), command: commandWithHookEvent(command, eventKey) } } }
-        : result;
+    return { ...result, hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput: { ...rawInput, command: commandWithHookEvent(command, eventKey) } } };
 }
 /** Convert a controlled OpenCode tool hook into the shared lifecycle receipt. */
 export function handleOpenCodeEvent(context, input) {
     const event = parseJsonObject(input.stdin || "{}", "OpenCode tool event");
-    const agy = event.source_harness === "antigravity-cli";
-    const harness = agy ? "antigravity-cli" : "opencode-server";
     if (event.schema_id !== "dd-flow/opencode-tool-event@1")
         throw new AppError("unsupported_opencode_event_schema", "Unsupported OpenCode event schema", 1);
+    return handleControlledToolEvent(context, input, event, event.source_harness === "antigravity-cli" ? "antigravity-cli" : "opencode-server");
+}
+/** Accept adapter-observed Factory identity, never a model-supplied Session ID. */
+export function handleDroidEvent(context, input) {
+    const event = parseJsonObject(input.stdin || "{}", "Droid tool event");
+    if (event.schema_id !== "dd-flow/droid-tool-event@1")
+        throw new AppError("unsupported_droid_event_schema", "Unsupported Droid event schema", 1);
+    return handleControlledToolEvent(context, input, event, "droid-cli");
+}
+function handleControlledToolEvent(context, input, event, harness) {
+    const agy = harness === "antigravity-cli";
+    const droid = harness === "droid-cli";
+    const label = droid ? "Droid" : agy ? "Antigravity" : "OpenCode";
+    const errorPrefix = droid ? "droid" : agy ? "agy" : "opencode";
     const phase = stringValue(event.phase);
     if (phase !== "before" && phase !== "after")
-        throw new AppError("unsupported_opencode_event_schema", "OpenCode event phase must be before or after", 1);
+        throw new AppError(`unsupported_${errorPrefix}_event_schema`, `${label} event phase must be before or after`, 1);
     const session = objectRecord(event.session);
     const profile = objectRecord(event.profile);
     const rawInput = objectRecord(event.input);
@@ -556,16 +669,18 @@ export function handleOpenCodeEvent(context, input) {
     const nativeParentId = stringValue(session.parent_provider_session_id);
     const daemonId = stringValue(event.daemon_id);
     const toolCallId = stringValue(event.tool_call_id);
-    const eventId = stringValue(event.event_id) ?? toolCallId;
+    const eventId = stringValue(event.event_id) ?? (droid ? undefined : toolCallId);
     const toolName = stringValue(event.tool);
     const directory = stringValue(session.directory);
-    if (!providerSessionId || !daemonId || !toolCallId || !eventId || !toolName || !directory || !path.isAbsolute(directory)) {
-        throw new AppError("opencode_session_identity_invalid", "OpenCode event is missing trusted physical identity", 1);
+    if (!providerSessionId || !daemonId || (!droid && !toolCallId) || !eventId || !toolName || !directory || !path.isAbsolute(directory)) {
+        throw new AppError(`${errorPrefix}_session_identity_invalid`, `${label} event is missing trusted physical identity`, 1);
     }
     const expectedRoot = resolveProjectRoot(input.projectRoot);
     if (resolveProjectRoot(directory) !== expectedRoot) {
-        throw new AppError(agy ? "agy_directory_mismatch" : "opencode_directory_mismatch", `${agy ? "Antigravity" : "OpenCode"} Session directory does not match the controlled workspace`, 1, { expected: expectedRoot, actual: directory });
+        throw new AppError(`${errorPrefix}_directory_mismatch`, `${label} Session directory does not match the controlled workspace`, 1, { expected: expectedRoot, actual: directory });
     }
+    if (droid && nativeParentId === providerSessionId)
+        throw new AppError("droid_session_identity_invalid", "A Droid Session cannot parent itself", 1);
     const sessionId = storageSessionId(nativeSessionIdentity(harness, providerSessionId));
     const parentSessionId = nativeParentId ? storageSessionId(nativeSessionIdentity(harness, nativeParentId)) : null;
     const command = stringValue(rawInput.command) ?? stringValue(rawInput.cmd) ?? stringValue(rawInput.CommandLine);
@@ -576,45 +691,40 @@ export function handleOpenCodeEvent(context, input) {
             projectId: project.id, protocolId: null, harness, providerSessionId, parentSessionId,
             daemonId, sessionId, agentId: stringValue(session.agent_id) ?? null, turnId: stringValue(event.message_id) ?? null,
             eventName: "PostToolUse", toolName, status: "observed", payload: { session_id: providerSessionId, cwd: expectedRoot, tool_name: toolName, status: objectRecord(event.outcome).status },
-            eventKey: baseKey, matchKey: null, transcriptPath: null, cwd: expectedRoot
+            eventKey: baseKey, matchKey: null, transcriptPath: droid ? stringValue(event.transcript_path) ?? null : null, cwd: expectedRoot
         });
         return { ok: true, observed: inserted, duplicate: !inserted, event_key: baseKey, phase, harness, session: nativeSessionIdentity(harness, providerSessionId), ...(nativeParentId ? { parent_session: nativeSessionIdentity(harness, nativeParentId) } : {}) };
     }
-    if (!command || !["bash", "Bash", "run_command", "run_terminal_command", "RunTerminalCommand"].includes(toolName)) {
+    if (!command || !(droid ? ["Execute"] : ["bash", "Bash", "run_command", "run_terminal_command", "RunTerminalCommand"]).includes(toolName)) {
         return { ok: true, observed: false, reason: command ? "non_bash_tool" : "event_not_participating" };
     }
     const lifecycle = lifecycleFacts(command);
-    if (!lifecycle)
+    if (!lifecycle && !continuationCommand(command))
         return { ok: true, observed: false, reason: "event_not_participating" };
-    if (lifecycle.analysis.kind === "compound") {
-        throw new AppError("compound_lifecycle_command", `dd-flow lifecycle commands must be a standalone ${agy ? "Antigravity" : "OpenCode"} shell tool call`, 1, { standalone_command: lifecycle.invocation.command });
-    }
-    const { flowPayload, bootstrapStageStart, commandProjectRoot } = lifecycle;
-    if (commandProjectRoot && resolveProjectRoot(commandProjectRoot) !== expectedRoot) {
-        throw new AppError("project_mismatch", "OpenCode lifecycle command project root does not match the controlled workspace", 1, { expected: expectedRoot, actual: commandProjectRoot });
-    }
-    const matchKey = lifecycleMatchKey(lifecycle, expectedRoot);
+    const bootstrapStageStart = lifecycle?.bootstrapStageStart;
+    const matchKey = lifecycle ? lifecycleMatchKey(lifecycle, expectedRoot) : null;
     if (bootstrapStageStart)
         registerProject(context, { root: expectedRoot });
     const project = requireProjectByRoot(context, expectedRoot);
+    if (droid) {
+        const existing = context.db.get("SELECT harness, provider_session_id, parent_session_id, daemon_id, match_key, tool_name FROM hook_events WHERE project_id = ? AND event_key = ?", [project.id, baseKey]);
+        if (existing && (existing.harness !== harness || existing.provider_session_id !== providerSessionId || existing.parent_session_id !== parentSessionId || existing.daemon_id !== daemonId || existing.match_key !== matchKey || existing.tool_name !== toolName)) {
+            throw new AppError("droid_event_replay_mismatch", "Droid event ID was already observed with different lifecycle identity", 1);
+        }
+    }
     const agentId = stringValue(session.agent_id);
-    const observedSession = flowPayload ? bindObservedFlowSession(context, project, {
-        ...flowPayload, harness, provider_session_id: providerSessionId, agent_id: agentId ?? null,
-        parent_session_id: parentSessionId, provider: stringValue(profile.provider) ?? null, model: stringValue(profile.model) ?? null,
-        reasoning: stringValue(profile.variant) ?? null, mode: stringValue(profile.agent) ?? null, agent_type: stringValue(profile.agent) ?? null,
-        metadata: { opencode_version: stringValue(event.server_version) ?? null, api_fingerprint: stringValue(event.api_fingerprint) ?? null, plugin_sha256: stringValue(event.plugin_sha256) ?? null, native_project_id: stringValue(session.project_id) ?? null }
-    }, sessionId) : undefined;
+    assertHookEventReplay(context, { projectId: project.id, eventKey: baseKey, harness, providerSessionId, parentSessionId, daemonId, sessionId, turnId: stringValue(event.message_id) ?? null, eventName: "PreToolUse", toolName, matchKey, cwd: expectedRoot });
     const payload = {
         session_id: providerSessionId, agent_id: agentId, cwd: expectedRoot, tool_name: toolName, tool_input: rawInput, command,
-        provider: stringValue(profile.provider), model: stringValue(profile.model), reasoning: stringValue(profile.variant),
-        mode: stringValue(profile.agent), agent_type: stringValue(profile.agent)
+        provider: stringValue(profile.provider), model: stringValue(profile.model), reasoning: stringValue(droid ? profile.reasoning : profile.variant),
+        mode: stringValue(droid ? profile.mode : profile.agent), agent_type: stringValue(droid ? profile.agent_type : profile.agent)
     };
     const inserted = recordHookEvent(context, {
-        projectId: project.id, protocolId: observedSession?.protocol_id ?? null, harness, providerSessionId, parentSessionId,
+        projectId: project.id, protocolId: null, harness, providerSessionId, parentSessionId,
         daemonId, sessionId, agentId: agentId ?? null, turnId: stringValue(event.message_id) ?? null, eventName: "PreToolUse", toolName,
-        status: "observed", payload, eventKey: baseKey, matchKey, transcriptPath: null, cwd: expectedRoot
+        status: "observed", payload, eventKey: baseKey, matchKey, transcriptPath: droid ? stringValue(event.transcript_path) ?? null : null, cwd: expectedRoot
     });
-    recordFlowSessionObservation(context, { projectId: project.id, sessionId, runId: observedSession?.run_id ?? null, protocolId: observedSession?.protocol_id ?? null, cwd: expectedRoot, toolName, eventKey: baseKey });
+    recordFlowSessionObservation(context, { projectId: project.id, sessionId, cwd: expectedRoot, toolName, eventKey: baseKey });
     const result = { ok: true, observed: inserted, duplicate: !inserted, event_key: baseKey, phase, harness, session: nativeSessionIdentity(harness, providerSessionId), ...(nativeParentId ? { parent_session: nativeSessionIdentity(harness, nativeParentId) } : {}), daemon_id: daemonId };
     return agy ? result : { ...result, hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput: { ...rawInput, command: commandWithHookEvent(command, baseKey) } } };
 }
@@ -631,6 +741,13 @@ export function handleAgyEvent(context, input) {
     const toolName = stringValue(event.tool);
     if (!directory || !providerSessionId || !daemonId || !eventId || !toolName)
         throw new AppError("agy_session_identity_invalid", "Antigravity event is missing trusted physical identity", 1);
+    const rawInput = objectRecord(event.input);
+    const command = stringValue(rawInput.command) ?? stringValue(rawInput.cmd) ?? stringValue(rawInput.CommandLine);
+    const invalidStep = !Number.isSafeInteger(event.step_index) || Number(event.step_index) < 0;
+    const invalidExecution = event.execution_num !== undefined && (!Number.isSafeInteger(event.execution_num) || Number(event.execution_num) < 0);
+    if (event.phase === "before" && command && (lifecycleFacts(command) || continuationCommand(command)) && (invalidStep || invalidExecution)) {
+        throw new AppError("agy_native_call_identity_missing", "Participating Antigravity lifecycle calls require a native step identity and a valid execution identity when provided", 1, { phase: "prepare", effect: "no_effect", recoverable: false });
+    }
     const translated = {
         schema_id: "dd-flow/opencode-tool-event@1", source_harness: "antigravity-cli", phase: event.phase, event_id: eventId,
         daemon_id: daemonId, tool_call_id: eventId, tool: toolName, input: event.input,
@@ -663,15 +780,56 @@ export function isolatedDdFlowHomeFromHookStdin(stdin) {
  * hook contract intentionally narrow: unwrap only that whole-command form,
  * then apply the same lifecycle parser to its actual shell payload.
  */
-function lifecycleCommandFromPayload(payload) {
-    const command = commandFromPayload(payload);
-    return command ? unwrapShellCommand(command) : undefined;
-}
-function commandWithHookEvent(command, eventKey) {
+/**
+ * Adds the receipt to the command that the shell will execute.  Heredoc input
+ * belongs to that command too, but an option appended after its delimiter is a
+ * second shell command rather than an argument, so insert it before `<<`.
+ */
+export function commandWithHookEvent(command, eventKey) {
     const analysis = parseLifecycleCommand(command);
-    if (analysis.kind !== "standalone" || !analysis.invocation.rewriteSafe || commandHasOption(analysis.invocation, "hook-event-id"))
+    if (analysis.kind !== "standalone")
         return command;
-    return `${command.trim()} --hook-event-id ${JSON.stringify(eventKey)}`;
+    if (commandHasOption(analysis.invocation, "hook-event-id")) {
+        return command;
+    }
+    const option = `--hook-event-id '${eventKey.replaceAll("'", "'\\''")}'`;
+    if (analysis.invocation.rewriteSafe) {
+        const index = shellSuffixOffset(command);
+        return `${command.slice(0, index).trimEnd()} ${option} ${command.slice(index)}`.trimEnd();
+    }
+    if (!analysis.invocation.wrapped && analysis.invocation.heredoc && allowsStdinLifecycleCompound(lifecycleFacts(command))) {
+        const index = firstHeredoc(command);
+        if (index >= 0)
+            return `${command.slice(0, index).trimEnd()} ${option} ${command.slice(index)}`;
+    }
+    return command;
+}
+function firstHeredoc(command) {
+    let quoteState = null;
+    let escaped = false;
+    for (let index = 0; index < command.length - 1; index += 1) {
+        const char = command[index];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (char === "\\" && quoteState !== "'") {
+            escaped = true;
+            continue;
+        }
+        if (quoteState) {
+            if (char === quoteState)
+                quoteState = null;
+            continue;
+        }
+        if (char === "'" || char === '"') {
+            quoteState = char;
+            continue;
+        }
+        if (char === "<" && command[index + 1] === "<" && command[index + 2] !== "<")
+            return index;
+    }
+    return -1;
 }
 /**
  * Recognise the small shell surface used by generated dd-flow lifecycle
@@ -692,25 +850,51 @@ function lifecycleFacts(command) {
         return null;
     const invocation = analysis.invocation;
     const stageStart = invocation.operation === "stage_start";
+    const stageFinish = invocation.operation === "stage_finish";
+    const stagePause = invocation.operation === "stage_pause";
     const stageResume = invocation.operation === "stage_resume";
     const workStart = invocation.operation === "work_start";
+    const workFinish = invocation.operation === "work_finish";
+    const workFail = invocation.operation === "work_fail";
     return {
         analysis,
         invocation,
-        flowPayload: flowSessionPayloadFromRegisterCommand(invocation),
         stageStart,
+        stageFinish,
+        stagePause,
         stageResume,
-        workStart,
+        workStart, workFinish, workFail,
         bootstrapStageStart: stageStart && commandHasOption(invocation, "bootstrap"),
         commandProjectRoot: commandOption(invocation, "project-root"),
-        stageName: stageStart || stageResume ? commandOption(invocation, "stage") : undefined,
-        runId: stageStart || stageResume ? commandPosition(invocation, 0) : undefined,
-        workId: stageResume ? commandOption(invocation, "work") : workStart ? commandPosition(invocation, 0) : undefined,
+        stageName: stageStart || stageFinish || stagePause || stageResume ? commandOption(invocation, "stage") : undefined,
+        runId: stageStart || stageFinish || stagePause || stageResume ? commandPosition(invocation, 0) : undefined,
+        workId: stagePause || stageResume ? commandOption(invocation, "work") : workStart || workFinish || workFail ? commandPosition(invocation, 0) : undefined,
         contextSha256: commandOption(invocation, "context-sha256")
     };
 }
-function lifecycleMatchKey(facts, projectRoot) {
-    const { invocation, bootstrapStageStart, stageStart, stageResume, workStart, stageName, runId, workId, contextSha256 } = facts;
+// Worker completion and the two HITL commands intentionally take their
+// payload from stdin. Their generated pipe/heredoc is one lifecycle command,
+// not a second authority. Everything else remains standalone-only.
+function allowsStdinLifecycleCompound(facts) {
+    const operation = facts.invocation.operation;
+    return facts.analysis.kind === "standalone" && facts.invocation.heredoc && !facts.invocation.wrapped
+        && ((operation === "work_finish" && commandHasOption(facts.invocation, "result-stdin"))
+            || (operation === "stage_start" && commandHasOption(facts.invocation, "intake-stdin"))
+            || (operation === "stage_pause" && commandHasOption(facts.invocation, "question-stdin"))
+            || (operation === "stage_resume" && commandHasOption(facts.invocation, "answer-stdin")));
+}
+function lifecycleMatchKey(facts, projectRoot, scope) {
+    // Observe the actual argument without validating it. A mistyped project
+    // must not leave a receipt matching a later, corrected non-rewriting call.
+    if (!scope && facts.commandProjectRoot && canonicalPath(facts.commandProjectRoot, false) !== canonicalPath(projectRoot, false))
+        return null;
+    const { invocation, bootstrapStageStart, stageStart, stageFinish, stagePause, stageResume, workStart, workFinish, workFail, stageName, runId, workId, contextSha256 } = facts;
+    const effectiveRoot = scope?.projectRoot ?? projectRoot;
+    const effectiveRunId = scope?.runId ?? runId;
+    if (invocation.operation === "recovery_accept") {
+        const run = commandPosition(invocation, 0), recovery = commandOption(invocation, "recovery-id");
+        return (scope?.runId ?? run) && recovery ? recoveryAcceptMatchKey((scope?.runId ?? run), recovery, effectiveRoot) : null;
+    }
     if (bootstrapStageStart)
         return bootstrapMatchKey({
             projectRoot,
@@ -718,14 +902,100 @@ function lifecycleMatchKey(facts, projectRoot) {
             intakeMode: contextSha256 ? "context" : commandHasOption(invocation, "intake-stdin") ? "stdin" : "file",
             ...(contextSha256 ? { contextSha256 } : {})
         });
-    if (stageStart && runId && stageName)
-        return stageStartMatchKey(runId, stageName, projectRoot, contextSha256);
-    if (stageResume && runId && stageName && workId)
-        return stageResumeMatchKey(runId, stageName, workId, projectRoot);
+    if (stageStart && effectiveRunId && stageName)
+        return stageStartMatchKey(effectiveRunId, stageName, effectiveRoot, contextSha256);
+    if (stageFinish && effectiveRunId && stageName)
+        return stageLifecycleMatchKey("stage_finish", effectiveRunId, stageName, effectiveRoot);
+    if (stagePause && effectiveRunId && stageName && workId)
+        return stageLifecycleMatchKey("stage_pause", effectiveRunId, stageName, effectiveRoot, workId);
+    if (stageResume && effectiveRunId && stageName && workId)
+        return stageResumeMatchKey(effectiveRunId, stageName, workId, effectiveRoot);
     if (workStart && workId)
-        return workStartMatchKey(workId, projectRoot);
+        return workStartMatchKey(workId, effectiveRoot, commandOption(invocation, "recovery-id"));
+    if (workFinish && workId)
+        return workLifecycleMatchKey("work_finish", workId, effectiveRoot);
+    if (workFail && workId)
+        return workLifecycleMatchKey("work_fail", workId, effectiveRoot);
     return null;
 }
+/** Observe exact immutable command attribution before reading model-supplied
+ * result files. This does not claim or authorize the lifecycle mutation. */
+export function observeCommandHook(context, command) {
+    const facts = lifecycleFacts(command);
+    if (!facts || facts.analysis.kind !== "standalone" || !facts.commandProjectRoot)
+        return;
+    const project = context.db.get("SELECT id FROM projects WHERE root = ?", [resolveProjectRoot(facts.commandProjectRoot)]);
+    if (!project)
+        return; // Bootstrap has not registered a project yet.
+    const matchKey = lifecycleMatchKey(facts, facts.commandProjectRoot);
+    if (!matchKey)
+        return;
+    let key = commandOption(facts.invocation, "hook-event-id");
+    if (!key && commandOption(facts.invocation, "invocation-id"))
+        return;
+    if (!key) {
+        try {
+            key = findRecentMatchingHookEvent(context, { projectId: project.id, matchKey, errorCode: "trusted_session_binding_required", operation: facts.invocation.operation }).eventKey;
+        }
+        catch {
+            return;
+        } // Dispatch still owns its mandatory admission error.
+    }
+    const event = context.db.get("SELECT id FROM hook_events WHERE project_id = ? AND event_key = ? AND match_key = ? AND status = 'observed'", [project.id, key, matchKey]);
+    if (event)
+        context.observeLifecycleHook?.(project.id, event.id);
+}
+export function stageLifecycleMatchKey(operation, runId, stage, projectRoot, workId) {
+    return crypto.createHash("sha256").update(JSON.stringify({ operation, run_id: runId, stage, project_root: resolveProjectRoot(projectRoot), ...(workId ? { work_id: workId } : {}) })).digest("hex");
+}
+export function recoveryAcceptMatchKey(runId, recoveryId, projectRoot) {
+    return crypto.createHash("sha256").update(JSON.stringify({ operation: "recovery_accept", run_id: runId, recovery_id: recoveryId, project_root: resolveProjectRoot(projectRoot) })).digest("hex");
+}
+export function workLifecycleMatchKey(operation, workId, projectRoot) {
+    return crypto.createHash("sha256").update(JSON.stringify({ operation, work_id: workId, project_root: resolveProjectRoot(projectRoot) })).digest("hex");
+}
+function workLifecycleMatchKeys(operation, workId, projectRoot) {
+    return entityReferenceVariants(workId).map((reference) => workLifecycleMatchKey(operation, reference, projectRoot));
+}
+function stageLifecycleMatchKeys(operation, runId, stage, projectRoot, workId) {
+    const runReferences = entityReferenceVariants(runId);
+    const workReferences = workId ? entityReferenceVariants(workId) : [undefined];
+    return [...new Set(runReferences.flatMap((runReference) => workReferences.map((workReference) => stageLifecycleMatchKey(operation, runReference, stage, projectRoot, workReference))))];
+}
+/** Claims a Work terminal command only after its exact hook receipt has proved
+ * the physical Session that issued it. Work code performs the owner check. */
+export function claimWorkLifecycleHookEvent(context, input) {
+    const matchKeys = workLifecycleMatchKeys(input.operation, input.workId, input.projectRoot);
+    const eventKey = input.eventKey ?? findRecentMatchingHookEvent(context, {
+        projectId: input.projectId, matchKey: matchKeys, errorCode: "trusted_session_binding_required", operation: input.operation.replace("_", " ")
+    }).eventKey;
+    const event = context.db.get("SELECT id, session_id, match_key, status FROM hook_events WHERE project_id = ? AND event_key = ?", [input.projectId, eventKey]);
+    if (!event?.session_id || event.status !== "observed" || !event.match_key || !matchKeys.includes(event.match_key)) {
+        const reason = !event ? "event_missing" : !event.session_id ? "identity_missing" : event.status !== "observed" ? "event_consumed" : "target_mismatch";
+        throw new AppError("trusted_session_binding_required", `${input.operation.replace("_", " ")} requires one fresh matching PreToolUse hook event`, 1, { work_id: input.workId, event_key: eventKey, reason, observed_status: event?.status ?? null });
+    }
+    const claimed = context.db.run("UPDATE hook_events SET status = 'claimed', claimed_at = ? WHERE id = ? AND status = 'observed'", [context.now(), event.id]);
+    if (claimed.changes !== 1)
+        throw new AppError("trusted_session_binding_required", "matching Work lifecycle hook event was already claimed", 1, { work_id: input.workId });
+    return hookSessionIdentity(context, input.projectId, eventKey);
+}
+/** Claims a lifecycle command only after its exact hook receipt has proved the
+ * physical Session that issued it. Stage code performs the Work-owner check. */
+export function claimStageLifecycleHookEvent(context, input) {
+    const matchKeys = stageLifecycleMatchKeys(input.operation, input.runId, input.stage, input.projectRoot, input.workId);
+    const eventKey = input.eventKey ?? findRecentMatchingHookEvent(context, {
+        projectId: input.projectId, matchKey: matchKeys, errorCode: "trusted_session_binding_required", operation: input.operation.replace("_", " ")
+    }).eventKey;
+    const event = context.db.get("SELECT id, session_id, match_key, status FROM hook_events WHERE project_id = ? AND event_key = ?", [input.projectId, eventKey]);
+    if (!event?.session_id || event.status !== "observed" || !event.match_key || !matchKeys.includes(event.match_key)) {
+        const reason = !event ? "event_missing" : !event.session_id ? "identity_missing" : event.status !== "observed" ? "event_consumed" : "target_mismatch";
+        throw new AppError("trusted_session_binding_required", `${input.operation.replace("_", " ")} requires one fresh matching PreToolUse hook event`, 1, { run_id: input.runId, stage: input.stage, event_key: eventKey, reason, observed_status: event?.status ?? null });
+    }
+    const claimed = context.db.run("UPDATE hook_events SET status = 'claimed', claimed_at = ? WHERE id = ? AND status = 'observed'", [context.now(), event.id]);
+    if (claimed.changes !== 1)
+        throw new AppError("trusted_session_binding_required", "matching lifecycle hook event was already claimed", 1, { run_id: input.runId, stage: input.stage });
+    return hookSessionIdentity(context, input.projectId, eventKey);
+}
 /** Trusted session identity is created by PreToolUse, never supplied by an agent. */
 export function sessionIdForHookEvent(context, projectId, eventKey) {
     const event = context.db.get("SELECT session_id FROM hook_events WHERE project_id = ? AND event_key = ?", [projectId, eventKey]);
@@ -741,6 +1011,7 @@ export function hookSessionIdentity(context, projectId, eventKey) {
      WHERE he.project_id = ? AND he.event_key = ?`, [projectId, eventKey]);
     if (!event?.session_id)
         throw new AppError("hook_event_not_found", "stage start requires a trusted PreToolUse hook event", 1, { event_key: eventKey });
+    context.observeLifecycleHook?.(projectId, event.id);
     return {
         hookEventId: event.id,
         harness: event.harness,
@@ -777,21 +1048,30 @@ export function claimRecentMatchingHookEvent(context, input) {
 /** Finds the trusted event that a stage- or Work-specific claimant will atomically claim. */
 export function findRecentMatchingHookEvent(context, input) {
     const freshAfter = new Date(Date.parse(context.now()) - 60_000).toISOString();
-    const find = () => context.db.get(`SELECT id, event_key FROM hook_events
-     WHERE project_id = ? AND match_key = ? AND status = 'observed' AND created_at >= ?
-     ORDER BY id DESC LIMIT 1`, [input.projectId, input.matchKey, freshAfter]);
-    let event = find();
-    // Some harnesses publish nested-agent tool events concurrently with command
-    // execution. Give the trusted event a short bounded window to reach SQLite.
+    const matchKeys = Array.isArray(input.matchKey) ? [...new Set(input.matchKey)] : [input.matchKey];
+    const placeholders = matchKeys.map(() => "?").join(", ");
+    const find = () => context.db.all(`SELECT id, event_key FROM hook_events
+     WHERE project_id = ? AND match_key IN (${placeholders}) AND status = 'observed' AND created_at >= ?
+       AND NOT (COALESCE(json_extract(outcome_json, '$.effect'), '') = 'no_effect'
+         AND COALESCE(json_extract(outcome_json, '$.disposition'), '') IN ('correctable', 'fatal'))
+       AND harness IN ('codex-desktop', 'antigravity-cli')
+       AND (? IS NULL OR session_id = ?)
+     ORDER BY id DESC LIMIT 2`, [input.projectId, ...matchKeys, freshAfter, input.sessionId ?? null, input.sessionId ?? null]);
+    let events = find();
+    // Only the qualified non-rewriting transports may correlate the original
+    // command: Codex Desktop and Antigravity. New harnesses fail closed by default.
     const deadline = Date.now() + 250;
-    while (!event?.event_key && Date.now() < deadline) {
+    while (events.length === 0 && Date.now() < deadline) {
         Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
-        event = find();
+        events = find();
+    }
+    if (events.length === 0 || !events[0]?.event_key) {
+        throw new AppError(input.errorCode, `${input.operation} requires a trusted lifecycle receipt. Check native hook delivery; managed commands are admitted from committed native identity, not from model-supplied invocation IDs or updatedInput.`, 1, { reason: "event_missing" });
     }
-    if (!event?.event_key) {
-        throw new AppError(input.errorCode, `${input.operation} requires one matching harness lifecycle event. Stay in this Session and retry the exact standalone lifecycle command; do not create a new Session.`, 1);
+    if (events.length > 1) {
+        throw new AppError("ambiguous_lifecycle_receipt", `${input.operation} has more than one fresh matching lifecycle event; stop and let the controller reconcile native delivery`, 1, { reason: "multiple_live_events", match_keys: matchKeys, event_keys: events.map((event) => event.event_key) });
     }
-    return { id: event.id, eventKey: event.event_key };
+    return { id: events[0].id, eventKey: events[0].event_key };
 }
 /** Fallback for Desktop paths that execute the original command after a hook rewrite. */
 export function claimBootstrapHookEvent(context, input) {
@@ -814,9 +1094,9 @@ export function bootstrapMatchKey(input) {
     })).digest("hex");
 }
 export function claimWorkStartHookEvent(context, input) {
-    const expected = new Set([workStartMatchKey(input.workId, input.projectRoot), workStartMatchKey(shortWorkReference(input.workId), input.projectRoot)]);
+    const expected = entityReferenceVariants(input.workId).map((reference) => workStartMatchKey(reference, input.projectRoot, input.recoveryId));
     const event = context.db.get("SELECT id, session_id, agent_id, turn_id, transcript_path, model, agent_type, match_key, status FROM hook_events WHERE project_id = ? AND event_key = ?", [input.projectId, input.eventKey]);
-    if (!event?.session_id || event.status !== "observed" || !event.match_key || !expected.has(event.match_key)) {
+    if (!event?.session_id || event.status !== "observed" || !event.match_key || !expected.includes(event.match_key)) {
         throw new AppError("trusted_work_launch_required", "work start requires one fresh matching PreToolUse event", 1, { work_id: input.workId, event_key: input.eventKey });
     }
     const claimed = context.db.run("UPDATE hook_events SET status = 'claimed', claimed_at = ? WHERE id = ? AND status = 'observed'", [context.now(), event.id]);
@@ -824,15 +1104,16 @@ export function claimWorkStartHookEvent(context, input) {
         throw new AppError("trusted_work_launch_required", "matching work-start hook event was already claimed", 1, { work_id: input.workId });
     return hookSessionIdentity(context, input.projectId, input.eventKey);
 }
-function shortWorkReference(id) { return /^WRK-\d{3,}(?:-|$)/.exec(id)?.[0]?.replace(/-$/, "") ?? id; }
 /** Claims the exact non-bootstrap stage entry which starts a coordinator Work. */
 export function assertStageStartHookEvent(context, input) {
-    const expected = stageStartMatchKey(input.runId, input.stage, input.projectRoot, input.contextSha256);
+    const expected = entityReferenceVariants(input.runId).map((reference) => stageStartMatchKey(reference, input.stage, input.projectRoot, input.contextSha256));
     const event = context.db.get("SELECT session_id, match_key, status FROM hook_events WHERE project_id = ? AND event_key = ?", [input.projectId, input.eventKey]);
-    if (!event?.session_id || event.status !== "observed" || event.match_key !== expected) {
-        throw new AppError("trusted_stage_launch_required", "stage start requires one fresh matching PreToolUse event", 1, { run_id: input.runId, stage: input.stage, event_key: input.eventKey, expected_match_key: expected, observed_match_key: event?.match_key ?? null, observed_status: event?.status ?? null });
+    if (!event?.session_id || event.status !== "observed" || !event.match_key || !expected.includes(event.match_key)) {
+        throw new AppError("trusted_stage_launch_required", "stage start requires one fresh matching PreToolUse event", 1, { run_id: input.runId, stage: input.stage, event_key: input.eventKey, expected_match_keys: expected, observed_match_key: event?.match_key ?? null, observed_status: event?.status ?? null });
     }
-    return hookSessionIdentity(context, input.projectId, input.eventKey);
+    const identity = hookSessionIdentity(context, input.projectId, input.eventKey);
+    assertRecoveryHookCurrent(context, input.projectId, input.runId, identity);
+    return identity;
 }
 export function claimStageStartHookEvent(context, input) {
     assertStageStartHookEvent(context, input);
@@ -862,24 +1143,25 @@ export function stageResumeMatchKey(runId, stage, workId, projectRoot) {
 }
 /** Claims the resume command observed in the Session that received the user answer. */
 export function claimStageResumeHookEvent(context, input) {
-    const matchKey = stageResumeMatchKey(input.runId, input.stage, input.workId, input.projectRoot);
-    const freshAfter = new Date(Date.parse(context.now()) - 60_000).toISOString();
-    const event = input.eventKey
-        ? context.db.get("SELECT id, event_key, session_id, match_key, status FROM hook_events WHERE project_id = ? AND event_key = ?", [input.projectId, input.eventKey])
-        : context.db.get("SELECT id, event_key, session_id, match_key, status FROM hook_events WHERE project_id = ? AND session_id = ? AND match_key = ? AND status = 'observed' AND created_at >= ? ORDER BY id DESC LIMIT 1", [input.projectId, input.sessionId ?? "", matchKey, freshAfter]);
-    if (!event?.event_key || !event.session_id || event.match_key !== matchKey || event.status !== "observed") {
+    const matchKeys = entityReferenceVariants(input.runId).flatMap((runReference) => entityReferenceVariants(input.workId).map((workReference) => stageResumeMatchKey(runReference, input.stage, workReference, input.projectRoot)));
+    const eventKey = input.eventKey ?? findRecentMatchingHookEvent(context, { projectId: input.projectId, matchKey: matchKeys, sessionId: input.sessionId ?? "", errorCode: "trusted_stage_resume_required", operation: "stage resume" }).eventKey;
+    const event = context.db.get("SELECT id, event_key, session_id, match_key, status FROM hook_events WHERE project_id = ? AND event_key = ?", [input.projectId, eventKey]);
+    if (!event?.event_key || !event.session_id || !event.match_key || !matchKeys.includes(event.match_key) || event.status !== "observed") {
         throw new AppError("trusted_stage_resume_required", "stage resume requires one fresh matching PreToolUse event", 1, { run_id: input.runId, stage: input.stage, work_id: input.workId });
     }
+    const identity = hookSessionIdentity(context, input.projectId, event.event_key);
+    assertRecoveryHookCurrent(context, input.projectId, input.runId, identity);
     const claimed = context.db.run("UPDATE hook_events SET status = 'claimed', claimed_at = ? WHERE id = ? AND status = 'observed'", [context.now(), event.id]);
     if (claimed.changes !== 1)
         throw new AppError("trusted_stage_resume_required", "matching stage-resume hook event was already claimed", 1, { run_id: input.runId, stage: input.stage });
-    return hookSessionIdentity(context, input.projectId, event.event_key);
+    return identity;
 }
-export function workStartMatchKey(workId, projectRoot) {
+export function workStartMatchKey(workId, projectRoot, recoveryId) {
     return crypto.createHash("sha256").update(JSON.stringify({
         operation: "work_start",
         work_id: workId,
-        project_root: resolveProjectRoot(projectRoot)
+        project_root: resolveProjectRoot(projectRoot),
+        ...(recoveryId ? { recovery_id: recoveryId } : {})
     })).digest("hex");
 }
 export function hookStatusForProject(context, projectId) {
@@ -919,6 +1201,8 @@ export function codexHookEventsForProject(context, projectId) {
      FROM hook_events WHERE project_id = ? ORDER BY created_at DESC, id DESC LIMIT 20`, [projectId]);
 }
 function resolveProfileName(profile) {
+    if (profile !== undefined && (typeof profile !== "string" || !profile.trim()))
+        throw new AppError("validation", "--profile must be nonempty text", 2);
     return sanitizeProfile(profile ?? defaultProfileName);
 }
 function sanitizeProfile(value) {
@@ -946,11 +1230,12 @@ function readTomlIfExists(file) {
     if (!fs.existsSync(file)) {
         return {};
     }
+    const { text } = prepareTextFile(file, "Codex config");
     try {
-        return parse(fs.readFileSync(file, "utf8"));
+        return parse(text);
     }
     catch (error) {
-        throw new AppError("validation", `Invalid TOML in ${file}: ${String(error)}`, 2);
+        throw new AppError("validation", `Invalid TOML in ${file}`, 2, { file, ...(error instanceof TomlError ? { line: error.line, column: error.column } : {}) });
     }
 }
 function withManagedConfig(config, sourceHome, targetHome) {
@@ -969,7 +1254,7 @@ function objectTable(value) {
 function createSharedLinks(sourceHome, targetHome) {
     const linked = [];
     const skipped = [];
-    for (const entry of sharedEntries) {
+    for (const entry of codexHomeSharedEntries) {
         const source = path.join(sourceHome, entry);
         const target = path.join(targetHome, entry);
         if (!fs.existsSync(source)) {
@@ -992,7 +1277,7 @@ function createSharedLinks(sourceHome, targetHome) {
     return { linked, skipped };
 }
 function removeSharedSymlinks(targetHome) {
-    for (const entry of sharedEntries) {
+    for (const entry of codexHomeSharedEntries) {
         const target = path.join(targetHome, entry);
         if (fs.existsSync(target) && fs.lstatSync(target).isSymbolicLink()) {
             fs.rmSync(target);
@@ -1005,7 +1290,7 @@ function removeDirIfEmpty(dir) {
     }
 }
 function sharedEntryStatus(sourceHome, targetHome) {
-    return sharedEntries.map((entry) => {
+    return codexHomeSharedEntries.map((entry) => {
         const source = path.join(sourceHome, entry);
         const target = path.join(targetHome, entry);
         return {
@@ -1026,10 +1311,14 @@ function hookEntry(matcher, command, statusMessage) {
     return { matcher, hooks: [commandHook(command, statusMessage)] };
 }
 function commandHook(command, statusMessage) {
-    return { type: "command", command, timeout: 5, statusMessage };
+    // Hook admission is synchronous (the CLI must see a committed receipt), but
+    // the old 5s budget was shorter than a cold CLI/store open under fan-out.
+    // Startup owns migrations; this budget only covers the bounded hot path.
+    return { type: "command", command, timeout: 30, statusMessage };
 }
 function hookCommand(event) {
-    const handler = `PATH="\${HOME}/Library/pnpm:/opt/homebrew/bin:/usr/local/bin:\${PATH}" dd-flow codex hook handle --event ${event} --json`;
+    const args = `codex hook handle --event ${event} --json`;
+    const handler = `if [ -n "\${DD_FLOW_BIN:-}" ]; then "$DD_FLOW_BIN" ${args}; else PATH="\${DD_FLOW_HOME:+\${DD_FLOW_HOME}/bin:}\${PATH}:\${HOME}/Library/pnpm:/opt/homebrew/bin:/usr/local/bin" dd-flow ${args}; fi`;
     return `/bin/bash -c 'log_dir="\${DD_FLOW_HOME:-\${HOME}/.dd-flow}/logs"; mkdir -p "$log_dir"; log="$log_dir/codex-hook.log"; printf "%s event=${event} phase=start pid=%s\\n" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$$" >>"$log"; ${handler} 2> >(tee -a "$log" >&2); status=$?; printf "%s event=${event} phase=finish pid=%s exit=%s\\n" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$$" "$status" >>"$log"; exit "$status"'`;
 }
 function resolveHookTarget(target) {
@@ -1205,11 +1494,10 @@ function recordHookInstallation(context, projectId, scope, configPath, installed
 function installationScope(target, profile, hooksPath) {
     return target === "isolated" ? `isolated:${profile}` : `default:${path.dirname(hooksPath)}`;
 }
-function upsertSessionBindingFromPayload(context, project, sessionId, payload) {
+function upsertSessionBindingFromPayload(context, project, sessionId, payload, transcriptPath) {
     const existing = sessionBinding(context, project.id, sessionId);
     const now = context.now();
     const cwd = stringValue(payload.cwd) ?? existing?.cwd ?? null;
-    const transcriptPath = stringValue(payload.transcript_path) ?? existing?.transcript_path ?? locateCodexTranscript(sessionId, context.env.CODEX_HOME);
     context.db.run(`INSERT INTO codex_session_bindings
       (session_id, project_id, protocol_id, handshake_id, cwd, transcript_path, status, created_at, updated_at)
      VALUES (?, ?, NULL, NULL, ?, ?, 'active', ?, ?)
@@ -1263,12 +1551,11 @@ function sessionBinding(context, projectId, sessionId) {
     return context.db.get("SELECT * FROM codex_session_bindings WHERE project_id = ? AND session_id = ?", [projectId, sessionId]);
 }
 function recordHookEvent(context, input) {
-    const existing = context.db.get("SELECT id FROM hook_events WHERE project_id = ? AND event_key = ?", [input.projectId, input.eventKey]);
-    if (existing)
+    if (assertHookEventReplay(context, input))
         return false;
     context.db.run(`INSERT INTO hook_events
-      (project_id, protocol_id, harness, provider_session_id, parent_session_id, daemon_id, session_id, agent_id, turn_id, transcript_path, provider, model, reasoning, mode, agent_type, cwd, event_key, match_key, event_name, tool_name, status, sanitized_summary, created_at)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+        (project_id, protocol_id, harness, provider_session_id, parent_session_id, daemon_id, session_id, agent_id, turn_id, transcript_path, provider, model, reasoning, mode, agent_type, cwd, event_key, match_key, event_name, tool_name, status, sanitized_summary, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
         input.projectId,
         input.protocolId,
         input.harness,
@@ -1295,6 +1582,23 @@ function recordHookEvent(context, input) {
     ]);
     return true;
 }
+/** A duplicate delivery is harmless only when all durable identity facts match. */
+function assertHookEventReplay(context, input) {
+    const existing = context.db.get(`SELECT harness, provider_session_id, parent_session_id, daemon_id, session_id, turn_id, event_name, tool_name, match_key, cwd
+       FROM hook_events WHERE project_id = ? AND event_key = ?`, [input.projectId, input.eventKey]);
+    if (existing) {
+        const observed = {
+            harness: input.harness, provider_session_id: input.providerSessionId, parent_session_id: input.parentSessionId,
+            daemon_id: input.daemonId ?? null, session_id: input.sessionId, turn_id: input.turnId,
+            event_name: input.eventName, tool_name: input.toolName, match_key: input.matchKey, cwd: input.cwd
+        };
+        if (Object.entries(observed).some(([key, value]) => existing[key] !== value)) {
+            throw new AppError("hook_event_replay_mismatch", "Lifecycle event ID was already observed with different immutable identity", 1, { event_key: input.eventKey });
+        }
+        return true;
+    }
+    return false;
+}
 function projectForHook(context, explicitRoot, cwd) {
     if (explicitRoot)
         return requireProjectByRoot(context, resolveProjectRoot(explicitRoot));
@@ -1321,14 +1625,6 @@ function hookEventKey(payload, eventName, toolName, command) {
         command
     })).digest("hex");
 }
-function commandFromPayload(payload) {
-    const direct = stringValue(payload.command);
-    if (direct) {
-        return direct;
-    }
-    const toolInput = objectRecord(payload.tool_input);
-    return stringValue(toolInput.command) ?? stringValue(toolInput.cmd);
-}
 function toolNameFromPayload(payload) {
     const toolInput = objectRecord(payload.tool_input);
     return stringValue(toolInput.name);
@@ -1371,10 +1667,10 @@ function writeJsonFile(file, value) {
     ensureDir(path.dirname(file));
     fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
 }
-function backupFile(file, now) {
+function backupFile(file, now, text) {
     const suffix = now.replace(/[:.]/g, "-");
     const backup = `${file}.${suffix}.bak`;
-    fs.copyFileSync(file, backup);
+    fs.writeFileSync(backup, text, { mode: 0o600 });
     return backup;
 }
 function hashObject(value) {