@deksden-com/dd-flow-cli 0.9.0-beta.7 → 0.9.0-beta.74

package/dist/services/hooks.js

@@ -8,12 +8,14 @@ import { parseJsonObject } from "../shared/json.js";
 import { ensureDir, resolveProjectRoot } from "../storage/paths.js";
 import { appendAudit } from "./audit.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, settleLifecycleNoEffectRejection } from "./lifecycle-invocations.js";
+import { commandHasOption, commandOption, commandPosition, shellSuffixOffset, parseLifecycleCommand, unwrapShellCommand } from "./lifecycle-command.js";
 import { registerProject, requireProjectByRoot } from "./projects.js";
 import { activeFlowSessionsForProject, bindObservedFlowSession, flowSessionPayloadFromRegisterCommand, recordFlowSessionObservation } from "./sessions.js";
 const defaultProfileName = "default";
 const maxSanitizedSummaryLength = 1600;
-const sharedEntries = [
+export const codexHomeSharedEntries = [
     "auth.json",
     "auth.bk",
     "sessions",
@@ -50,7 +52,7 @@ 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 }
     };
@@ -268,7 +270,13 @@ 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 parentProviderSessionId = rawChildProviderSessionId ? codexNativeParentId(payload, rawChildProviderSessionId) : null;
     const turnId = stringValue(payload.turn_id);
     const toolName = stringValue(payload.tool_name) ?? toolNameFromPayload(payload);
     const command = lifecycleCommandFromPayload(payload);
@@ -293,32 +301,57 @@ export function handleCodexHook(context, input) {
             }
         };
     }
-    const { flowPayload, stageStart, stageResume, workStart, bootstrapStageStart, commandProjectRoot } = lifecycle;
+    const { flowPayload, stageStart, stageFinish, stagePause, stageResume, workStart, workFinish, workFail, bootstrapStageStart, commandProjectRoot } = lifecycle;
     const matchKey = commandProjectRoot ? lifecycleMatchKey(lifecycle, commandProjectRoot) : null;
     // 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 project = projectForHook(context, input.projectRoot ?? commandProjectRoot, stringValue(payload.cwd));
+    let project;
+    try {
+        project = projectForHook(context, input.projectRoot ?? commandProjectRoot, stringValue(payload.cwd));
+    }
+    catch (error) {
+        // A terminal command outside a registered flow gets no trusted receipt;
+        // the CLI will fail closed if it is actually executed. This keeps hooks
+        // inert for unrelated shell-parser probes and stale project directories.
+        if (stageFinish || stagePause || workFinish || workFail)
+            return { ok: true, observed: false, reason: "project_not_registered" };
+        throw error;
+    }
     if (!project)
         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;
+    // 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 storageId = providerSessionId ? storageSessionId(nativeSessionIdentity("codex-desktop", providerSessionId)) : null;
+    const parentSessionId = parentProviderSessionId ? storageSessionId(nativeSessionIdentity("codex-desktop", parentProviderSessionId)) : null;
+    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: stringValue(payload.cwd) ?? null });
+    const bindingOwnerId = providerSessionId ?? rootProviderSessionId;
+    const binding = bindingOwnerId ? upsertSessionBindingFromPayload(context, project, bindingOwnerId, payload) : undefined;
     const observedSession = flowPayload
-        ? bindObservedFlowSession(context, project, { ...flowPayload, harness: "codex-desktop", provider_session_id: sessionId ?? flowPayload.provider_session_id ?? null }, storageId ?? undefined)
+        ? bindObservedFlowSession(context, project, {
+            ...flowPayload,
+            harness: "codex-desktop",
+            provider_session_id: providerSessionId ?? flowPayload.provider_session_id ?? null,
+            parent_session_id: parentSessionId
+        }, storageId ?? undefined)
         : undefined;
     const effectiveSessionId = observedSession?.session_id ?? storageId;
     const protocolId = observedSession?.protocol_id ?? binding?.protocol_id ?? null;
-    const eventKey = hookEventKey(payload, eventName, toolName, command);
     const inserted = recordHookEvent(context, {
         projectId: project.id,
         protocolId,
         harness: "codex-desktop",
-        providerSessionId: sessionId ?? null,
-        parentSessionId: null,
+        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: stringValue(payload.agent_id) ?? null,
+        agentId: rawChildProviderSessionId ?? null,
         turnId: turnId ?? null,
         eventName,
         toolName: toolName ?? null,
@@ -345,9 +378,10 @@ export function handleCodexHook(context, input) {
         observed: inserted,
         duplicate: !inserted,
         event_key: eventKey,
-        session: sessionId ? nativeSessionIdentity("codex-desktop", sessionId) : null,
+        session: providerSessionId ? nativeSessionIdentity("codex-desktop", providerSessionId) : null,
+        ...(parentProviderSessionId ? { parent_session: nativeSessionIdentity("codex-desktop", parentProviderSessionId) } : {}),
         protocol_id: protocolId,
-        ...(sessionId && (flowPayload || stageStart || stageResume || workStart)
+        ...(providerSessionId && (flowPayload || stageStart || stageFinish || stagePause || stageResume || workStart || workFinish || workFail || lifecycle.invocation.operation === "recovery_accept")
             ? {
                 hookSpecificOutput: {
                     hookEventName: "PreToolUse",
@@ -358,117 +392,138 @@ export function handleCodexHook(context, input) {
             : {})
     };
 }
-/** 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 firstLine = fs.readFileSync(transcript, "utf8").split("\n", 1)[0];
+        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")
+    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 params = objectRecord(notification.params);
-    const update = objectRecord(params.update);
-    if (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" || !commandOption(parsed.invocation, "invocation-id"))
+        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)
         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 && 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
-        });
+    if (lifecycle.commandProjectRoot && resolveProjectRoot(lifecycle.commandProjectRoot) !== expectedRoot) {
+        throw new AppError("project_mismatch", "ZCode lifecycle command project root does not match the controlled workspace", 1, { expected: expectedRoot, actual: lifecycle.commandProjectRoot });
     }
-    const matchKey = lifecycleMatchKey(lifecycle, expectedRoot);
-    if (bootstrapStageStart)
+    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);
+    }
+    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);
+    if (lifecycle.analysis.kind === "compound") {
+        if (lifecycle.analysis.reason !== "shell_composition")
+            throw new AppError("compound_lifecycle_command", "Ambiguous shell cannot authorize a lifecycle replacement", 1, { reason: lifecycle.analysis.reason });
+        if (invocationId) {
+            const error = { code: "compound_lifecycle_command", message: "dd-flow lifecycle commands must be a standalone ZCode Bash tool call", exitCode: 1,
+                details: { standalone_command: lifecycle.invocation.command } };
+            settleLifecycleNoEffectRejection(context, invocationId, lifecycle.invocation.command, error, { daemonId, rootSessionId: rootProviderSessionId, sessionId: providerSessionId, parentSessionId: parentProviderSessionId ?? null, toolCallId: toolUseId });
+            return { ok: true, observed: false, invocation_id: invocationId, no_effect: true, error };
+        }
+        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 eventKey = crypto.createHash("sha256").update(JSON.stringify(["zcode-acp", daemonId, providerSessionId, toolUseId])).digest("hex");
+    const rewritten = invocationId ? command : commandWithHookEvent(command, eventKey);
+    if (!invocationId && rewritten === command && commandOption(lifecycle.invocation, "hook-event-id") !== eventKey)
+        throw new AppError("zcode_hook_rewrite_unsupported", "ZCode requires a direct lifecycle command whose exact receipt can be delivered", 1);
+    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);
+    const matchKey = lifecycleMatchKey(lifecycle, expectedRoot);
+    const eventNameForReceipt = invocationId ? "ToolCallObserved" : "PreToolUse";
+    const persist = () => {
+        assertHookEventReplay(context, { projectId: project.id, eventKey, harness: "zcode-acp", providerSessionId, parentSessionId, daemonId, sessionId, turnId: null, eventName: eventNameForReceipt, toolName: toolName ?? "Bash", matchKey, cwd: expectedRoot });
+        const observedSession = lifecycle.flowPayload ? bindObservedFlowSession(context, project, {
+            ...lifecycle.flowPayload, harness: "zcode-acp", provider_session_id: providerSessionId,
+            parent_session_id: parentSessionId, provider: stringValue(observedProfile.provider) ?? null,
+            model: stringValue(observedProfile.model) ?? null, reasoning: stringValue(observedProfile.reasoning) ?? null,
+            mode: stringValue(observedProfile.mode) ?? null, agent_id: stringValue(hook.agent_id) ?? stringValue(hook.agentId) ?? null
+        }, sessionId) : undefined;
+        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: observedSession?.protocol_id ?? 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, runId: observedSession?.run_id ?? null, protocolId: observedSession?.protocol_id ?? null, 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,
-        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
+    if (!invocationId)
+        return persist();
+    const receipt = observeLifecycleInvocation(context, {
+        id: invocationId, command, identity: { daemonId, rootSessionId: rootProviderSessionId, sessionId: providerSessionId, parentSessionId: parentProviderSessionId ?? null, toolCallId: toolUseId },
+        recordReceipt: () => { persist(); 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
-    };
+    return { ok: true, observed: !receipt.duplicate, duplicate: receipt.duplicate, event_key: receipt.eventKey, invocation_id: invocationId };
 }
 /** Convert a Grok Build PreToolUse hook into a trusted lifecycle receipt. */
 export function handleGrokEvent(context, input) {
@@ -491,7 +546,7 @@ export function handleGrokEvent(context, input) {
             standalone_command: lifecycle.invocation.command
         });
     }
-    const { flowPayload, stageStart, stageResume, workStart, bootstrapStageStart, commandProjectRoot } = lifecycle;
+    const { flowPayload, stageStart, stageFinish, stagePause, stageResume, workStart, workFinish, workFail, bootstrapStageStart, commandProjectRoot } = lifecycle;
     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, {
@@ -514,12 +569,13 @@ 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
     })).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 observedSession = flowPayload ? bindObservedFlowSession(context, project, {
+        ...flowPayload, harness: "grok-acp", provider_session_id: providerSessionId, agent_id: agentId ?? null, parent_session_id: parentSessionId
+    }, sessionId) : undefined;
     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)
@@ -535,20 +591,32 @@ export function handleGrokEvent(context, input) {
     });
     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)
+    return (flowPayload || stageStart || stageFinish || stagePause || stageResume || workStart || workFinish || workFail || lifecycle.invocation.operation === "recovery_accept")
         ? { ...result, hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput: { ...(rawInput ?? {}), command: commandWithHookEvent(command, eventKey) } } }
         : result;
 }
 /** 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 +624,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,43 +646,50 @@ 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)
         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 });
+        throw new AppError("compound_lifecycle_command", `dd-flow lifecycle commands must be a standalone ${label} 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 });
+        throw new AppError("project_mismatch", `${label} lifecycle command project root does not match the controlled workspace`, 1, { expected: expectedRoot, actual: commandProjectRoot });
     }
     const matchKey = lifecycleMatchKey(lifecycle, expectedRoot);
     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);
+    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 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 }
+        reasoning: stringValue(droid ? profile.reasoning : profile.variant) ?? null, mode: stringValue(droid ? profile.mode : profile.agent) ?? null, agent_type: stringValue(droid ? profile.agent_type : profile.agent) ?? null,
+        metadata: droid ? { droid_version: stringValue(event.runtime_version) ?? null } : { 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;
     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,
         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 });
     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 };
@@ -667,11 +744,58 @@ 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;
+    if (commandHasOption(analysis.invocation, "hook-event-id")) {
+        if (commandOption(analysis.invocation, "hook-event-id") !== eventKey)
+            throw new AppError("hook_event_mismatch", "The command specifies a receipt from another tool invocation", 1);
         return command;
-    return `${command.trim()} --hook-event-id ${JSON.stringify(eventKey)}`;
+    }
+    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 +816,46 @@ 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")
     };
 }
+// 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) {
-    const { invocation, bootstrapStageStart, stageStart, stageResume, workStart, stageName, runId, workId, contextSha256 } = facts;
+    const { invocation, bootstrapStageStart, stageStart, stageFinish, stagePause, stageResume, workStart, workFinish, workFail, stageName, runId, workId, contextSha256 } = facts;
+    if (invocation.operation === "recovery_accept") {
+        const run = commandPosition(invocation, 0), recovery = commandOption(invocation, "recovery-id");
+        return run && recovery ? recoveryAcceptMatchKey(run, recovery, projectRoot) : null;
+    }
     if (bootstrapStageStart)
         return bootstrapMatchKey({
             projectRoot,
@@ -720,12 +865,86 @@ function lifecycleMatchKey(facts, projectRoot) {
         });
     if (stageStart && runId && stageName)
         return stageStartMatchKey(runId, stageName, projectRoot, contextSha256);
+    if (stageFinish && runId && stageName)
+        return stageLifecycleMatchKey("stage_finish", runId, stageName, projectRoot);
+    if (stagePause && runId && stageName && workId)
+        return stageLifecycleMatchKey("stage_pause", runId, stageName, projectRoot, workId);
     if (stageResume && runId && stageName && workId)
         return stageResumeMatchKey(runId, stageName, workId, projectRoot);
     if (workStart && workId)
-        return workStartMatchKey(workId, projectRoot);
+        return workStartMatchKey(workId, projectRoot, commandOption(invocation, "recovery-id"));
+    if (workFinish && workId)
+        return workLifecycleMatchKey("work_finish", workId, projectRoot);
+    if (workFail && workId)
+        return workLifecycleMatchKey("work_fail", workId, projectRoot);
     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) {
+        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");
+}
+/** 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 matchKey = workLifecycleMatchKey(input.operation, input.workId, input.projectRoot);
+    const eventKey = input.eventKey ?? findRecentMatchingHookEvent(context, {
+        projectId: input.projectId, matchKey, 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 !== matchKey) {
+        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 });
+    }
+    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 matchKey = stageLifecycleMatchKey(input.operation, input.runId, input.stage, input.projectRoot, input.workId);
+    const eventKey = input.eventKey ?? findRecentMatchingHookEvent(context, {
+        projectId: input.projectId, matchKey, 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 !== matchKey) {
+        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 });
+    }
+    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 +960,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 +997,26 @@ 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
+    const find = () => context.db.all(`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.
+       AND harness IN ('codex-desktop', 'antigravity-cli')
+       AND (? IS NULL OR session_id = ?)
+     ORDER BY id DESC LIMIT 2`, [input.projectId, input.matchKey, 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 and updatedInput; managed ZCode requires its issued --invocation-id.`, 1);
     }
-    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; provide its exact hook event ID`, 1, { match_key: input.matchKey, 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,7 +1039,7 @@ 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 = new Set([workStartMatchKey(input.workId, input.projectRoot, input.recoveryId), workStartMatchKey(shortWorkReference(input.workId), 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)) {
         throw new AppError("trusted_work_launch_required", "work start requires one fresh matching PreToolUse event", 1, { work_id: input.workId, event_key: input.eventKey });
@@ -832,7 +1057,9 @@ export function assertStageStartHookEvent(context, input) {
     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 });
     }
-    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);
@@ -863,23 +1090,24 @@ 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]);
+    const eventKey = input.eventKey ?? findRecentMatchingHookEvent(context, { projectId: input.projectId, matchKey, 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 !== matchKey || 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) {
@@ -969,7 +1197,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 +1220,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 +1233,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 {
@@ -1029,7 +1257,8 @@ function commandHook(command, statusMessage) {
     return { type: "command", command, timeout: 5, 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) {
@@ -1263,12 +1492,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 +1523,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));