@deksden-com/dd-flow-cli 0.9.0-beta.52 → 0.9.0-beta.53

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @deksden-com/dd-flow-cli
 
+## 0.9.0-beta.53
+
+### Patch Changes
+
+- Admit managed ZCode lifecycle commands through durable invocation receipts, with exact native identity, bounded waits, retained outcomes and explicit validated retries. Preserve recovery generations, cooperative settlement, immutable recovery evidence and scoped snapshots. Keep Grok native hook responses and stable parent identity, and qualify the installed ZCode native event contract without requiring child hooks. Use Node 26 for the guarded release workflow.
+
 ## 0.9.0-beta.52
 
 ### Patch Changes

package/dist/build-info.json

@@ -1,8 +1,8 @@
 {
   "cli_package": "@deksden-com/dd-flow-cli",
-  "cli_version": "0.9.0-beta.52",
-  "cli_commit": "9f8e20f5aab016e2e7246b8939af9e4ad91e37dc",
-  "built_at": "2026-09-12T14:24:25.044Z",
+  "cli_version": "0.9.0-beta.53",
+  "cli_commit": "db14065f43f320bc69dacbec425cd04eac8236ae",
+  "built_at": "2026-09-13T02:52:44.434Z",
   "built_with_canon": {
     "version": "4.1.0",
     "commit": "ef349bf47cba1c987468e51d73a0dbadbd48dc1f",

package/dist/cli/help.js

@@ -583,17 +583,27 @@ handler resolves the registered project from cwd. The option is only a manual
 override.
 
 Managed homes isolate dd-flow hooks while sharing selected Codex state from the source home.`
+    ],
+    [
+        "zcode hook",
+        `dd-flow zcode hook - handle a synchronous native ZCode PreToolUse callback
+
+Usage:
+  dd-flow zcode hook handle --project-root <root> --json
+
+The managed ZCode native hook supplies the callback on stdin. It records the
+receipt before returning a rewritten tool input with --hook-event-id.`
     ],
     [
         "zcode event",
-        `dd-flow zcode event - ingest a zcode-acp session/update notification
+        `dd-flow zcode event - ingest a zcode-acp session/update notification as evidence
 
 Usage:
   dd-flow zcode event handle --project-root <root> --json
   dd-flow zcode usage ingest --project-root <root> --json
 
-Both payloads are read from stdin. The event adapter retains lifecycle identity;
-the usage adapter retains cumulative provider counters for RUN accounting.`
+Both payloads are read from stdin. Native hooks own lifecycle admission; ACP
+events and usage retain secondary evidence for RUN accounting.`
     ],
     [
         "droid event",

package/dist/cli/run-cli.js

@@ -1,5 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
+import { quote } from "shell-quote";
+import { assertLifecycleInvocationCurrent, awaitLifecycleInvocation, issueLifecycleInvocation, isRetryableLifecycleRejection, lifecycleInvocationScope, retryLifecycleInvocationCommand, settleLifecycleInvocation } from "../services/lifecycle-invocations.js";
 import { createContext, createRouterContext } from "../runtime/context.js";
 import { migrateStoreWriter } from "../storage/writer-migration.js";
 import { helpForArgs } from "./help.js";
@@ -11,7 +13,7 @@ import { blockPlanItem, completePlanItem, getPlanStatus, skipPlanItem, startPlan
 import { cancelMergeQueueJob, claimNextMergeJob, claimMergeJob, claimMergeBundle, completeMergeBundle, completeMergeJob, failMergeBundle, failMergeJob, getMergeBundleStatus, getMergeQueueStatus, noteMergeJob, waitNextMergeJob } from "../services/merge-queue.js";
 import { getMergeWorkerStatus, oneShotMergeClaim, startMergeWorker, stopProjectMergeWorker } from "../services/merge-worker.js";
 import { cleanupApply, cleanupScan } from "../services/cleanup.js";
-import { getCodexHomeStatus, getCodexHooksStatus, handleCodexHook, handleAgyEvent, handleDroidEvent, handleGrokEvent, handleOpenCodeEvent, handleZcodeEvent, isolatedDdFlowHomeFromHookStdin, claimBootstrapHookEvent, findRecentMatchingHookEvent, stageStartMatchKey, initCodexHome, installCodexHooks, planCodexHome, printCodexHomeEnv, printCodexHooks, removeCodexHome, removeCodexHooks } from "../services/hooks.js";
+import { getCodexHomeStatus, getCodexHooksStatus, handleCodexHook, handleAgyEvent, handleDroidEvent, handleGrokEvent, handleOpenCodeEvent, handleZcodeHook, handleZcodeEvent, isolatedDdFlowHomeFromHookStdin, claimBootstrapHookEvent, findRecentMatchingHookEvent, stageStartMatchKey, initCodexHome, installCodexHooks, planCodexHome, printCodexHomeEnv, printCodexHooks, removeCodexHome, removeCodexHooks } from "../services/hooks.js";
 import { bootstrapWorktree, closeWorktree, createWorktreeRecord, getWorktreeStatus, planWorktree } from "../services/worktrees.js";
 import { acquireLaneLock, cancelLaneWaiter, checkLaneWorkspace, getLaneWaiters, getLaneStatus, heartbeatLaneLock, releaseLaneLock, setLaneWorkspace, waitAcquireLaneLock, waitForLaneLock } from "../services/lanes.js";
 import { getProjectConfigStatus, setProjectConfigValue } from "../services/config.js";
@@ -73,6 +75,7 @@ export async function runCli(args, io = defaultIo, env = process.env) {
     const output = parseOutputOptions(args);
     const progress = progressForCommand(output.args);
     let heartbeat;
+    let invocationSettlement;
     try {
         if (output.args.length === 1 && output.args[0] === "--version") {
             const payload = getCliVersionReport();
@@ -115,9 +118,37 @@ export async function runCli(args, io = defaultIo, env = process.env) {
         }
         const dispatchContext = routed?.inProcess
             ? createContext({ ...env, DD_FLOW_ENGINE_MODE: "1", DD_FLOW_ENGINE_HOME: "in-process", DD_FLOW_ROUTED_FROM: getCliVersionReport().cli.version }, databaseModeForCommand(output.args, classification))
-            : createContext(env, databaseModeForCommand(output.args, classification));
+            : createContext({ ...env }, databaseModeForCommand(output.args, classification));
         preflightCliCompatibility(dispatchContext, output.args, env, scopeProjectRoot);
-        const result = await dispatch(output.args, dispatchContext, io, scopeProjectRoot, classification, output);
+        dispatchContext.env.DD_FLOW_INVOCATION_READONLY = classification.mode === "read_only_diagnostics" ? "1" : undefined;
+        let dispatchArgs = output.args;
+        let retainedOutcome;
+        const invocationId = optionalOption(parseArgs(output.args.slice(2)), "invocation-id");
+        if (invocationId) {
+            const command = quote(["dd-flow", ...output.args]);
+            const admission = await awaitLifecycleInvocation(dispatchContext, { id: invocationId, command,
+                assertCurrent: scope => assertLifecycleInvocationCurrent(dispatchContext, scope, command) });
+            if (admission.replay)
+                retainedOutcome = admission.outcome;
+            else {
+                invocationSettlement = { context: dispatchContext, id: invocationId };
+                dispatchArgs = [...output.args, "--hook-event-id", admission.eventKey];
+                dispatchContext.env.DD_FLOW_INVOCATION_SCOPE = JSON.stringify(lifecycleInvocationScope(dispatchContext, invocationId));
+                dispatchContext.env.DD_FLOW_CURRENT_INVOCATION = invocationId;
+            }
+        }
+        if (retainedOutcome?.error) {
+            const error = retainedOutcome.error;
+            throw new AppError(error.code, error.message, error.exitCode, error.details);
+        }
+        const result = retainedOutcome ? retainedOutcome.result : await dispatch(dispatchArgs, dispatchContext, io, scopeProjectRoot, classification, output);
+        if (invocationSettlement) {
+            const completed = invocationSettlement;
+            invocationSettlement = undefined;
+            // A failure to persist an already completed result is an unknown reply,
+            // not a failed operation eligible for a new productive retry.
+            settleLifecycleInvocation(completed.context, completed.id, { result });
+        }
         const refreshWarnings = refreshDashboardsAfterMutation(dispatchContext, output.args, result, scopeProjectRoot);
         const resultWithWarnings = addWarnings(result, refreshWarnings);
         if (heartbeat)
@@ -136,6 +167,27 @@ export async function runCli(args, io = defaultIo, env = process.env) {
     catch (error) {
         if (heartbeat)
             clearInterval(heartbeat);
+        if (invocationSettlement) {
+            // Optional retry preparation must never prevent recording the primary
+            // operation rejection. Otherwise a known failure becomes an unknown run.
+            if (isAppError(error) && isRetryableLifecycleRejection(error.code)) {
+                try {
+                    error.details.retry_command = retryLifecycleInvocationCommand(invocationSettlement.context, invocationSettlement.id);
+                    error.details.retry_instruction = "Correct only the evidenced defect, then use retry_command with the required result input. Reissuing the old command only reads its retained outcome.";
+                }
+                catch (retryError) {
+                    error.details.retry_preparation_error = String(retryError);
+                }
+            }
+            try {
+                settleLifecycleInvocation(invocationSettlement.context, invocationSettlement.id, { error: isAppError(error)
+                        ? { code: error.code, message: error.message, exitCode: error.exitCode, details: error.details }
+                        : { code: "unexpected", message: String(error), exitCode: 1, details: {} } });
+            }
+            catch (persistenceError) {
+                io.stderr.write(`Invocation settlement persistence failed: ${String(persistenceError)}\n`);
+            }
+        }
         const payload = isAppError(error)
             ? { ok: false, error: { code: error.code, message: error.message, details: error.details } }
             : { ok: false, error: { code: "unexpected", message: String(error) } };
@@ -520,6 +572,13 @@ function shortSha(value) {
 async function dispatch(args, context, io, scopeProjectRoot = null, classification = classifyCliOperation(args, context.env), output = parseOutputOptions(args)) {
     const [family, command, ...rest] = args;
     const parsed = parseArgs(rest);
+    if (family === "zcode" && command === "invocation" && parsed.positional[0] === "prepare") {
+        const payload = JSON.parse(await readStdin(io.stdin));
+        if (typeof payload.command !== "string" || !payload.scope || typeof payload.scope !== "object")
+            throw new AppError("usage", "Expected command and managed scope on stdin", 2);
+        assertLifecycleInvocationCurrent(context, payload.scope, payload.command);
+        return { ok: true, ...issueLifecycleInvocation(context, payload.command, payload.scope) };
+    }
     if (family === "storage" && command === "migrate-writer") {
         if (parsed.positional.length || [...parsed.options.keys()].some(key => !["database", "backup", "offline"].includes(key)) || [...parsed.options.values()].some(values => values.length !== 1))
             throw new AppError("usage", "Usage: dd-flow storage migrate-writer --database ABSOLUTE_DB --backup NEW_ABSOLUTE_FILE --offline", 2);
@@ -1146,6 +1205,9 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
     if (family === "codex" && command === "hook") {
         return dispatchCodexHook(context, parsed, await readStdin(io.stdin));
     }
+    if (family === "zcode" && command === "hook") {
+        return dispatchZcodeHook(context, parsed, await readStdin(io.stdin));
+    }
     if (family === "zcode" && command === "event") {
         return dispatchZcodeEvent(context, parsed, await readStdin(io.stdin));
     }
@@ -2249,6 +2311,15 @@ function dispatchZcodeEvent(context, parsed, stdin) {
     }
     throw new AppError("usage", `Unknown zcode event action: ${action}`, 2);
 }
+function dispatchZcodeHook(context, parsed, stdin) {
+    if (requiredPosition(parsed, 0, "zcode hook action") !== "handle")
+        throw new AppError("usage", "Unknown zcode hook action", 2);
+    const result = handleZcodeHook(context, { projectRoot: requiredOption(parsed, "project-root"), stdin });
+    if (result && typeof result === "object" && !Array.isArray(result) && "hookSpecificOutput" in result) {
+        return { hookSpecificOutput: result.hookSpecificOutput };
+    }
+    return {};
+}
 function dispatchGrokEvent(context, parsed, stdin) {
     const action = requiredPosition(parsed, 0, "grok event action");
     if (action === "handle") {

package/dist/harness-runtime/bin/dd-grok.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { durableDaemonStart, inspectDaemonOperation } from "../lib/daemon-operations.mjs";
-import { spawn } from "node:child_process";
+import { invokeNativeHook } from "../lib/native-hook-command.mjs";
 import { cancelSession, createSession, doctor, forkSession, inspectSession, promptFromFile, promptSession } from "../lib/dd-grok.mjs";
 import { callDaemon, serveDaemon, startDaemon, stopDaemon } from "../lib/dd-grok-daemon.mjs";
 
@@ -9,9 +9,8 @@ function common(options) { return { bin: options["grok-bin"], journal: options.j
 async function readStdin() { let value = ""; process.stdin.setEncoding("utf8"); for await (const chunk of process.stdin) value += chunk; return value; }
 async function hook(options) {
   const stdin = await readStdin(); const payload = JSON.parse(stdin || "{}"); const identity = await callDaemon(options["state-dir"], "hook.resolve", { sessionId: payload.sessionId ?? payload.session_id });
-  const enriched = { ...payload, _meta: { ...(payload._meta ?? {}), ddGrok: identity } }; const args = ["grok", "event", "handle", "--project-root", options["project-root"], "--json"]; const command = options["dd-flow-bin"]; const target = /\.[cm]?js$/.test(command) ? { command: process.execPath, args: [command, ...args] } : { command, args };
-  await new Promise((resolve, reject) => { const child = spawn(target.command, target.args, { env: { ...process.env, DD_FLOW_HOME: options["dd-flow-home"] }, stdio: ["pipe", "ignore", "pipe"] }); let stderr = ""; child.stderr.setEncoding("utf8").on("data", (chunk) => (stderr += chunk)); child.on("error", reject); child.on("close", (code) => code === 0 ? resolve() : reject(new Error(stderr || "dd-flow rejected Grok hook"))); child.stdin.end(`${JSON.stringify(enriched)}\n`); });
-  return { decision: "allow" };
+  const enriched = { ...payload, _meta: { ...(payload._meta ?? {}), ddGrok: identity } }; const args = ["grok", "event", "handle", "--project-root", options["project-root"], "--json"]; const command = options["dd-flow-bin"];
+  return invokeNativeHook({ bin: command, args, home: options["dd-flow-home"], payload: enriched });
 }
 
 try {

package/dist/harness-runtime/bin/dd-zcode.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { durableDaemonStart, inspectDaemonOperation } from "../lib/daemon-operations.mjs";
+import { invokeNativeHook } from "../lib/native-hook-command.mjs";
 import { cancelChild, cancelSession, createSession, doctor, forkSession, inspectSession, promptFromFile, promptSession } from "../lib/dd-zcode.mjs";
 import { callDaemon, serveDaemon, startDaemon, stopDaemon } from "../lib/dd-zcode-daemon.mjs";
 
@@ -29,6 +30,15 @@ function common(options) {
   };
 }
 
+async function readStdin() { let value = ""; process.stdin.setEncoding("utf8"); for await (const chunk of process.stdin) value += chunk; return value; }
+async function hook(options) {
+  const payload = JSON.parse((await readStdin()) || "{}");
+  const identity = await callDaemon(options["state-dir"], "hook.resolve", { sessionId: payload.session_id ?? payload.sessionId });
+  const command = options["dd-flow-bin"]; const args = ["zcode", "hook", "handle", "--project-root", options["project-root"], "--json"];
+
+  return invokeNativeHook({ bin: command, args, home: options["dd-flow-home"], payload: { ...payload, _meta: { ...(payload._meta ?? {}), ddZcode: identity } } });
+}
+
 try {
   const { positional, options } = parse(process.argv.slice(2)); const [family, command] = positional; let result;
   const answers = options["answers-file"] ? JSON.parse(await promptFromFile(options["answers-file"])) : undefined;
@@ -39,6 +49,7 @@ try {
   else if (family === "daemon" && command === "status") result = await callDaemon(shared.stateDir, "daemon.status");
   else if (family === "daemon" && command === "operation") result = await inspectDaemonOperation(shared.stateDir, options["operation-id"]);
   else if (family === "daemon" && command === "stop") result = await stopDaemon({ stateDir: shared.stateDir, cancelTree: options["cancel-tree"], timeoutMs: shared.timeoutMs });
+  else if (family === "hook" && command === "handle") { process.stdout.write(`${JSON.stringify(await hook(options))}\n`); process.exit(0); }
   else if (family === "session") {
     const params = { ...shared, answers, ...(command === "create" || command === "prompt" ? { prompt: options["prompt-file"] ? await promptFromFile(options["prompt-file"]) : options.prompt } : {}), ...(command === "fork" ? { target: JSON.parse(options["target-json"] ?? "null") } : {}) };
     // promptSessionWithBridge owns the meaningful deadline: it fails when its
@@ -56,8 +67,9 @@ try {
     else if (command === "cancel-child") result = await cancelChild(params);
     else if (command === "fork") result = await forkSession(params);
     else throw new Error(`unknown session command: ${command}`);
-  } else throw new Error("usage: dd-zcode doctor | daemon start|status|stop | session create|prompt|inspect|status|resume|cancel|cancel-child|fork [options] --json");
+  } else throw new Error("usage: dd-zcode doctor | daemon start|status|stop | hook handle | session create|prompt|inspect|status|resume|cancel|cancel-child|fork [options] --json");
   process.stdout.write(`${JSON.stringify({ ok: true, ...result })}\n`);
 } catch (error) {
+  if (process.argv[2] === "hook") { process.stdout.write(`${JSON.stringify({ decision: "deny", reason: error.message })}\n`); process.exit(2); }
   process.stderr.write(`${JSON.stringify({ ok: false, error: error.message, ...(error.code ? { code: error.code, retryable: error.retryable === true, details: error.details } : {}) })}\n`); process.exit(1);
 }

package/dist/harness-runtime/lib/dd-grok-daemon.mjs

@@ -73,25 +73,10 @@ async function writeHook(paths, config, entryPath) {
 }
 
 async function observeAcpToolCall(config, identity, message) {
-  if (!config.ddFlowBin) return;
-  const update = message?.params?.update;
-  const sessionId = message?.params?.sessionId;
-  const command = update?.rawInput?.command ?? update?.rawInput?.cmd;
-  if (update?.sessionUpdate !== "tool_call" || !sessionId || typeof command !== "string" || !command.includes("dd-flow")) return;
-  const eventId = update?._meta?.eventId ?? `${sessionId}:${update.toolCallId ?? createHash("sha256").update(command).digest("hex")}`;
-  const payload = {
-    hook_event_name: "PreToolUse",
-    tool_name: update?._meta?.["x.ai/tool"]?.name ?? "run_terminal_command",
-    tool_input: { command }, session_id: sessionId, event_id: eventId,
-    _meta: { ddGrok: identity }
-  };
-  const target = executable(config.ddFlowBin, ["grok", "event", "handle", "--project-root", config.projectRoot, "--json"]);
-  await new Promise((resolve, reject) => {
-    const child = spawn(target.command, target.args, { env: { ...process.env, DD_FLOW_HOME: config.ddFlowHome }, stdio: ["pipe", "ignore", "pipe"] }); let stderr = "";
-    child.stderr.setEncoding("utf8").on("data", (chunk) => (stderr += chunk)); child.on("error", reject);
-    child.on("close", (code) => code === 0 ? resolve() : reject(new DaemonError("grok_hook_failed", stderr || "dd-flow rejected Grok ACP tool event")));
-    child.stdin.end(`${JSON.stringify(payload)}\n`);
-  });
+  // Grok's synchronous native hook owns admission. This ACP mirror is
+  // observational only; forwarding it used to create a second receipt after
+  // the command had already run.
+  void config; void identity; void message;
 }
 
 async function copyAuth(paths, source) {

package/dist/harness-runtime/lib/dd-zcode-daemon.mjs

@@ -151,6 +151,9 @@ export async function startDaemon(options) {
   }
   await removeSocket(paths.socket, paths.dir);
   const versions = await doctor({ bin: config.bin, zcodePath: config.zcodePath });
+  if (hasFlowContext && versions.compatible !== true) {
+    throw new DaemonError("zcode_lifecycle_unqualified", "ZCode native event identity is not qualified for managed CLI admission; inspect lifecycle_qualification before starting E2E.", false, { observed_runtime: versions.observed_runtime, lifecycle_qualification: versions.lifecycle_qualification });
+  }
   const resourceProcess = await registerDaemonProcess(config, {
     kind: "zcode-daemon", owner: `zcode:${path.basename(paths.dir)}`, operation: `zcode-daemon:${path.basename(paths.dir)}`,
     stdout: paths.log, stderr: paths.log,
@@ -229,11 +232,18 @@ export class DaemonRuntime {
   }
 
   track(result, topology = result?.evidence?.subagents) {
-    if (result?.provider_session_id) { const existing = this.sessions.get(result.provider_session_id); this.sessions.set(result.provider_session_id, {
+    if (result?.provider_session_id) { const existing = this.sessions.get(result.provider_session_id); const suppliedParent = result.parent_provider_session_id;
+      if (existing && suppliedParent !== undefined && suppliedParent !== existing.parent_provider_session_id) {
+        throw new DaemonError("session_ancestry_conflict", "ZCode Session parent changed after it was recorded", false, { session_id: result.provider_session_id, expected_parent: existing.parent_provider_session_id, actual_parent: suppliedParent });
+      }
+      const parent = suppliedParent ?? existing?.parent_provider_session_id ?? null;
+      const parentRoot = parent ? this.sessions.get(parent)?.root_provider_session_id ?? null : null;
+      this.sessions.set(result.provider_session_id, {
       provider_session_id: result.provider_session_id,
-      adapter_session_id: result.adapter_session_id ?? result.provider_session_id,
-      parent_provider_session_id: result.parent_provider_session_id ?? null,
-      topology: topology ?? null,
+      adapter_session_id: result.adapter_session_id ?? existing?.adapter_session_id ?? result.provider_session_id,
+      parent_provider_session_id: parent,
+      root_provider_session_id: existing?.root_provider_session_id ?? (parent ? parentRoot : result.provider_session_id),
+      topology: topology ?? existing?.topology ?? null,
       completed_turns: existing?.completed_turns ?? 0,
     }); }
     if (result?.adapter_session_id) this.liveAdapters.add(result.adapter_session_id);
@@ -289,6 +299,12 @@ export class DaemonRuntime {
       active_tree: this.state.active_tree, active_operation: this.activeProductive,
       sessions: [...this.sessions.values()], config: this.state.config,
     };
+    if (operation === "hook.resolve") {
+      const sessionId = String(params.sessionId ?? "");
+      const session = this.sessions.get(sessionId);
+      if (!session?.root_provider_session_id) throw new DaemonError("hook_identity_unknown", "ZCode hook Session is not a tracked controlled Session", false, { session_id: sessionId });
+      return { daemonId: this.state.daemon_id, rootProviderSessionId: session.root_provider_session_id, parentProviderSessionId: session.parent_provider_session_id ?? null, observedProfile: this.bridge.modelProfiles?.get(sessionId) ?? {} };
+    }
     if (operation === "session.create") return await this.productive(operation, async () => await createSessionWithBridge(this.bridge, this.options(params), this.initialized));
     if (operation === "session.prompt") {
       const result = await this.productive(operation, async () => { await this.requireSettled(params); return await promptSessionWithBridge(this.bridge, this.options(params)); });

package/dist/harness-runtime/lib/dd-zcode.mjs

@@ -1,5 +1,7 @@
 import { observedTimeout } from "./observation-clock.mjs";
+import { invokeNativeHook } from "./native-hook-command.mjs";
 import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
 import { appendFile, mkdir, readFile } from "node:fs/promises";
 import path from "node:path";
 import readline from "node:readline";
@@ -53,6 +55,7 @@ class Journal {
     if (!this.file) return;
     const line = JSON.stringify({ order: ++this.order, observed_at: now(), kind, payload });
     this.pending = this.pending.then(() => appendFile(this.file, `${line}\n`));
+    return this.pending;
   }
   async flush() { await this.pending; }
 }
@@ -64,6 +67,7 @@ export class AcpBridge {
     this.pending = new Map();
     this.sessionActivity = new Map();
     this.notifications = Promise.resolve();
+    this.lifecycleNotifications = new Set();
     this.notificationError = null;
     this.bridgeStderr = "";
     this.toolCalls = new Map();
@@ -127,6 +131,16 @@ export class AcpBridge {
       this.assistantText.set(sessionId, `${this.assistantText.get(sessionId) ?? ""}${message.params.update.content.text ?? ""}`);
     }
     this.observeToolCall(message);
+    if (message.method === "session/update" && this.options.onLifecycleNotification) {
+      const observer = this.options.onLifecycleNotification;
+      const pending = Promise.resolve().then(() => observer(message)).catch(async error => {
+        this.notificationError ??= error;
+        await this.journal.write("notification_failure", { code: error.code ?? "invocation_observation_failed", message: error.message,
+          session_id: message.params?.sessionId ?? null, tool_call_id: update?.toolCallId ?? null, event_time: now(), delivery_stage: "lifecycle_receipt", completeness: "incomplete" });
+      });
+      this.lifecycleNotifications.add(pending);
+      void pending.then(() => this.lifecycleNotifications.delete(pending), () => this.lifecycleNotifications.delete(pending));
+    }
     if (message.id !== undefined && message.method) { void this.answer(message).catch((error) => this.rejectAll(error)); return; }
     if (message.id !== undefined) {
       const pending = this.pending.get(message.id);
@@ -148,7 +162,14 @@ export class AcpBridge {
     }
     if (message.method) this.notifications = this.notifications
       .then(async () => { await this.observeModelUpdate(message); await this.options.onNotification?.(message); })
-      .catch((error) => { this.notificationError ??= error; if (error.code === "profile_integrity_violation") this.rejectAll(error); });
+      .catch(async (error) => {
+        const failure = { code: error.code ?? "notification_observation_failed", message: error.message, session_id: message.params?.sessionId ?? null, tool_call_id: message.params?.update?.toolCallId ?? null, event_time: now(), delivery_stage: "acp_evidence", completeness: "incomplete" };
+        try { await this.journal.write("notification_failure", failure); }
+        catch (persistenceError) { process.stderr.write(`${JSON.stringify({ ...failure, persistence_error: persistenceError.message })}\n`); }
+        // Evidence loss does not retroactively revoke a committed native hook.
+        // Permission/profile integrity is a separate, still-fatal contract.
+        if (error.code === "profile_integrity_violation") { this.notificationError ??= error; this.rejectAll(error); }
+      });
   }
 
   observeToolCall(message) {
@@ -249,7 +270,7 @@ export class AcpBridge {
   notify(method, params = {}) { this.send({ jsonrpc: "2.0", method, params }); }
   send(message) { this.journal.write("outbound", message); this.child.stdin.write(`${JSON.stringify(message)}\n`); }
   rejectAll(error) { for (const pending of this.pending.values()) { clearTimeout(pending.timer); if (pending.idleTimer) clearInterval(pending.idleTimer); pending.reject(error); } this.pending.clear(); }
-  async flush() { await this.notifications; await this.journal.flush(); if (this.notificationError) throw this.notificationError; }
+  async flush() { await Promise.all([...this.lifecycleNotifications]); await this.notifications; await this.journal.flush(); if (this.notificationError) throw this.notificationError; }
   async close() {
     let flushError = null;
     try { await this.flush(); } catch (error) { flushError = error; }
@@ -437,8 +458,6 @@ async function withBridge(options, operation) {
 }
 
 function flowForwarder(options, rootProviderSessionId, bridge) {
-  if (!options.ddFlowBin) return undefined;
-  const projectRoot = absolute(options.projectRoot, "--project-root");
   return async (notification) => {
     if (notification.method !== "session/update") return;
     const update = notification.params?.update;
@@ -447,10 +466,52 @@ function flowForwarder(options, rootProviderSessionId, bridge) {
     const childId = notification.params?.update?._meta?.zcodeRuntime?.childSessionId;
     const observed = bridge?.modelProfiles?.get(childId ?? rootProviderSessionId) ?? {};
     if (childId && !observed.model) await observeModel({ journal: options.journal, harness: "zcode-acp", sessionId: childId, parentSessionId: rootProviderSessionId, requested: profile(options), observed, source: "zcode.child_tool_event", evidence: "unavailable" });
-    const payload = zcodeLifecycleEnvelope(notification, { ...options, observedProfile: observed }, rootProviderSessionId);
-    const stdout = await runWithStdin(options.ddFlowBin, ["zcode", "event", "handle", "--project-root", projectRoot, "--json"], `${JSON.stringify(payload)}\n`, options.ddFlowHome ? { DD_FLOW_HOME: absolute(options.ddFlowHome, "--dd-flow-home") } : {});
-    const receipt = stdout ? JSON.parse(stdout) : {};
-    if (receipt.ok === false) fail(`dd-flow rejected ZCode event: ${JSON.stringify(receipt.error ?? receipt)}`);
+    // Native PreToolUse has already admitted (or denied) the command. ACP is
+    // intentionally only journal/model evidence: its serialized delivery can
+    // lag behind execution and must never mint a second lifecycle receipt.
+  };
+}
+
+/** Preserve native tool ownership independently of slow secondary evidence.
+ * Rehydration uses this same session's retained inbound journal, not model text. */
+export async function zcodeInvocationObserver(options, rootProviderSessionId, send = invokeNativeHook) {
+  if (!options.ddFlowBin) return async () => {};
+  const owners = new Map();
+  const remember = message => {
+    const update = message.params?.update;
+    if (message.method !== "session/update" || update?.sessionUpdate !== "tool_call") return null;
+    if (options.adapterSessionId && message.params?.sessionId !== options.adapterSessionId) return null;
+    const native = update._meta?.zcodeRuntime ?? {};
+    if (native.source === "subagent" && !native.childSessionId) throw Object.assign(new Error("Native subagent event has no physical child identity"), { code: "zcode_child_identity_missing" });
+    const session = native.childSessionId ?? rootProviderSessionId;
+    const key = update.toolCallId;
+    if (!key || typeof session !== "string") return null;
+    if (owners.has(key) && owners.get(key) !== session) throw Object.assign(new Error("Native tool id has conflicting Session ownership"), { code: "zcode_tool_identity_conflict" });
+    owners.set(key, session);
+    return { update, native, session };
+  };
+  if (options.journal) {
+    try {
+      const contents = await readFile(options.journal, "utf8");
+      for (const line of contents.split("\n").filter(Boolean)) {
+        const event = JSON.parse(line);
+        if (event.kind === "inbound") remember(event.payload);
+      }
+    } catch (error) { if (error.code !== "ENOENT") throw error; }
+  }
+  return async message => {
+    const facts = remember(message);
+    if (!facts || !options.ddFlowBin) return;
+    const { update, native, session } = facts;
+    const command = update.rawInput?.command ?? update.rawInput?.cmd;
+    const toolName = update._meta?.claudeCode?.toolName;
+    if (!["Bash", "bash", "execute"].includes(toolName) || typeof command !== "string" || !/(?:^|\s)--invocation-id\s/.test(command)) return;
+    const parent = session === rootProviderSessionId ? null : owners.get(native.parentToolCallId);
+    if (session !== rootProviderSessionId && !parent) throw Object.assign(new Error("Native child has no confirmed immediate parent tool owner"), { code: "zcode_parent_identity_missing" });
+    await send({ bin: options.ddFlowBin, home: options.ddFlowHome,
+      args: ["zcode", "event", "handle", "--project-root", options.projectRoot ?? options.cwd, "--json"],
+      payload: { ...message, _meta: { ddZcode: { daemonId: options.daemonId, rootProviderSessionId, parentProviderSessionId: parent } } },
+    });
   };
 }
 
@@ -480,13 +541,26 @@ async function forwardUsage(options, providerSessionId, usage, toolCalls) {
   await runWithStdin(options.ddFlowBin, ["zcode", "usage", "ingest", "--project-root", projectRoot, "--json"], `${JSON.stringify(payload)}\n`, options.ddFlowHome ? { DD_FLOW_HOME: absolute(options.ddFlowHome, "--dd-flow-home") } : {});
 }
 
+export function zcodeLifecycleQualification(sha256, bridgeCommit, harnessContract) {
+  // Behavioural evidence: dd-eval production-invocations probe, 2026-09-13.
+  // Pin both providers of native event identity, not a string in the bundle.
+  const qualified = sha256 === "e9f1868c0fdb863537ed910ee3828b9be96b8c2fd805473f63b439e1113266b8"
+    && bridgeCommit === "43f654bccdbb1aa4f4fb4617f7315c4336dbcde0" && harnessContract === ZCODE_HARNESS_CONTRACT;
+  return { status: qualified ? "qualified" : "unqualified", mechanism: "cli-invocation@1", sha256,
+    capabilities: qualified ? ["root", "concurrent_children", "child_continuation"] : [],
+    native_nested_children: false, reason: qualified ? null : "native_event_contract_unqualified" };
+}
+
 export async function doctor(options = {}) {
   const zcodeAcp = await commandOutput(options.bin, ["--version"]);
   const zcodeAcpCommit = await commandOutput(options.bin, ["--dd-harness-commit"]);
   const ddHarness = await commandOutput(options.bin, ["--dd-harness-version"]);
   const zcodePath = options.zcodePath ?? process.env.ZCODE_PATH ?? "/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs";
   const zcode = await commandOutput(zcodePath, ["--version"]);
-  return { compatible: true, observed_runtime: { zcode, zcode_acp: zcodeAcp, zcode_acp_commit: zcodeAcpCommit, dd_harness_contract: ddHarness || ZCODE_HARNESS_CONTRACT } };
+  const native = await readFile(zcodePath);
+  const sha256 = createHash("sha256").update(native).digest("hex");
+  const qualification = zcodeLifecycleQualification(sha256, zcodeAcpCommit, ddHarness);
+  return { compatible: qualification.status === "qualified", lifecycle_qualification: qualification, observed_runtime: { zcode, zcode_acp: zcodeAcp, zcode_acp_commit: zcodeAcpCommit, dd_harness_contract: ddHarness } };
 }
 
 export async function createSession(options) {
@@ -527,6 +601,8 @@ export async function promptSessionWithBridge(bridge, options) {
   let forward;
   bridge.configure({ ...options, onNotification: async (event) => { await forward?.(event); await options.onNotification?.(event); } });
   const identity = await controlledIdentity(bridge, { ...options, cwd }); forward = flowForwarder(options, identity.providerSessionId, bridge);
+  await bridge.journal.flush();
+  bridge.configure({ onLifecycleNotification: await zcodeInvocationObserver({ ...options, adapterSessionId: identity.adapterSessionId }, identity.providerSessionId) });
   const profile_receipt = await applyProfile(bridge, identity.adapterSessionId, requested, options.assertDispatch);
   options.assertDispatch?.();
   await forwardUsage(options, identity.providerSessionId, await bridge.request("zcode/session/usage", { sessionId: identity.adapterSessionId }), bridge.toolSummary(identity.adapterSessionId));

package/dist/harness-runtime/lib/native-hook-command.mjs

@@ -0,0 +1,33 @@
+import { spawn } from "node:child_process";
+
+/** Preserve the native hook protocol across the CLI process boundary. */
+export async function invokeNativeHook({ bin, args, payload, home, timeoutMs = 15_000 }) {
+  const script = /\.[cm]?js$/.test(bin);
+  const output = await new Promise((resolve, reject) => {
+    const child = spawn(script ? process.execPath : bin, [...(script ? [bin] : []), ...args], {
+      env: { ...process.env, DD_FLOW_HOME: home }, stdio: ["pipe", "pipe", "pipe"]
+    });
+    let stdout = "", stderr = "", failure;
+    const stop = error => { failure ??= error; child.kill("SIGKILL"); };
+    const timer = setTimeout(() => stop(Object.assign(new Error("Native hook admission timed out"), { code: "native_hook_timeout" })), timeoutMs);
+    child.stdout.setEncoding("utf8").on("data", chunk => { stdout += chunk; if (stdout.length > 1_048_576) stop(new Error("Native hook response exceeds protocol limit")); });
+    child.stderr.setEncoding("utf8").on("data", chunk => { stderr = (stderr + chunk).slice(-65_536); });
+    child.stdin.on("error", error => { failure ??= error; });
+    child.on("error", error => { clearTimeout(timer); reject(error); });
+    child.on("close", code => {
+      clearTimeout(timer);
+      if (failure) return reject(failure);
+      if (code !== 0) {
+        let record;
+        try { record = JSON.parse(stderr.trim()).error; } catch { /* Non-JSON stderr remains diagnostic evidence. */ }
+        return reject(Object.assign(new Error(record?.message ?? (stderr.trim() || "Native hook admission failed")), { code: record?.code ?? "native_hook_failed", details: record?.details }));
+      }
+      resolve(stdout);
+    });
+    child.stdin.end(`${JSON.stringify(payload)}\n`);
+  });
+  let result;
+  try { result = JSON.parse(output); } catch { throw Object.assign(new Error("Invalid native hook JSON response"), { code: "native_hook_response_invalid" }); }
+  if (!result || typeof result !== "object" || Array.isArray(result) || result.ok === false) throw Object.assign(new Error("Native hook did not return a successful protocol object"), { code: "native_hook_response_invalid" });
+  return result;
+}

package/dist/services/cli-operation-classifier.js

@@ -104,6 +104,8 @@ function isRouterNative(args) {
     if (first === "storage" && args[1] === "migrate-writer")
         return true;
     return (first === "codex" && args[1] === "hook" && args[2] === "handle")
+        || (first === "zcode" && args[1] === "hook" && args[2] === "handle")
+        || (first === "zcode" && args[1] === "invocation" && args[2] === "prepare")
         || (first === "zcode" && args[1] === "event" && args[2] === "handle")
         || (first === "zcode" && args[1] === "usage" && args[2] === "ingest")
         || (first === "grok" && args[1] === "event" && args[2] === "handle")

package/dist/services/eval-snapshots.js

@@ -391,7 +391,7 @@ function detachSnapshotRuntimeOwners(context, snapshot, manifest) {
         throw new AppError("snapshot_control_requires_recovery", "A fenced RUN requires explicit recovery, not a stage-entry fork", 1);
     if (context.db.get("SELECT 1 FROM merge_requests WHERE status IN ('dispatching','active','waiting_user','action_required','recovery_required') LIMIT 1"))
         throw new AppError("snapshot_execution_active", "A stage-entry fork cannot discard an unresolved MERGE execution", 1);
-    const detachedTables = ["run_control_admissions", "run_control_stage_admissions", "run_control_operations", "run_control_workers", "run_controls", "run_controller_events", "run_controller_operations", "run_controllers", "run_recovery_bindings", "work_recovery_segments", "run_recovery_guards", "work_launches", "merge_servers", "merge_sessions", "lane_locks", "lane_waiters"].filter(hasTable);
+    const detachedTables = ["lifecycle_invocations", "run_control_admissions", "run_control_stage_admissions", "run_control_operations", "run_control_workers", "run_controls", "run_controller_events", "run_controller_operations", "run_controllers", "run_recovery_bindings", "work_recovery_segments", "run_recovery_guards", "work_launches", "merge_servers", "merge_sessions", "lane_locks", "lane_waiters"].filter(hasTable);
     const runTables = Object.fromEntries([...detachedTables, "runs", "merge_requests", "sessions", "work_sessions"].map(table => [table, context.db.all(`SELECT * FROM ${table}`)]));
     const resourceFile = path.join(context.ddFlowHome, "runtime.sqlite");
     const resources = fs.existsSync(resourceFile) ? new DatabaseSync(resourceFile) : null;

package/dist/services/external-work-launch.js

@@ -10,6 +10,7 @@ import { resolveExecutionPolicy, runtimeHarness, validateExecutionOverride } fro
 import { assertRunMutationAllowed } from "./run-recovery.js";
 import { assertWorkLaunchReady, workStartCommand } from "./work-registry.js";
 import { initCodexHome } from "./hooks.js";
+import { managedInvocationContext } from "./lifecycle-invocations.js";
 /**
  * Creates an external provider root for one already-created Work.  The launch
  * is not a Work claim: only the worker's trusted `work start` hook binds it.
@@ -48,7 +49,7 @@ export async function launchExternalWork(context, input) {
     fs.mkdirSync(root, { recursive: true });
     const now = context.now();
     const flowExecutable = prepareHarnessFlowExecutable(context, root);
-    const env = { ...context.env, DD_FLOW_BIN: flowExecutable };
+    const env = { ...context.env, DD_FLOW_BIN: flowExecutable, DD_FLOW_INVOCATION_SCOPE: undefined, DD_FLOW_CURRENT_INVOCATION: undefined };
     // An external Codex root is a fresh thread, so it does not inherit the
     // coordinator's managed PreToolUse hook.  Its first `work start` must emit
     // that hook event to bind the Work to the physical session.
@@ -57,7 +58,7 @@ export async function launchExternalWork(context, input) {
         initCodexHome(context, { projectRoot: run.project_root, profile: `external-${operationId}`, targetHome: codexHome, ...(context.env.CODEX_HOME ? { sourceHome: context.env.CODEX_HOME } : {}) });
         env.CODEX_HOME = codexHome;
     }
-    const runtimeContext = { ...context, env };
+    let runtimeContext = { ...context, env };
     const runtimeOwner = { schema_id: "dd-flow/runtime-owner@1", owner_id: `run:${work.run_id}:work:${work.work_id}`, role: "worker", project_id: work.project_id, run_id: work.run_id, work_id: work.work_id, operation_id: operationId, state_dir: root, dd_flow_home: context.ddFlowHome, dd_flow_bin: flowExecutable, resource_home: context.env.DD_FLOW_RESOURCE_HOME ?? context.ddFlowHome, budget: runtimeBudgetForRun(context, work.project_id, work.run_id) };
     const executable = resolveHarnessCommand(context.ddFlowHome, runtimeHarness(resolved.worker), "adapter");
     context.db.run("INSERT INTO work_launches (operation_id, work_id, profile_json, profile_hash, status, state_dir, journal_path, provider_session_id, adapter_receipt_json, created_at, updated_at) VALUES (?, ?, ?, ?, 'launching', ?, ?, NULL, NULL, ?, ?)", [operationId, work.work_id, JSON.stringify({ ...resolved, runtime_adapter: { executable, owner: runtimeOwner } }), resolved.profile_hash, root, journal, now, now]);
@@ -73,6 +74,8 @@ export async function launchExternalWork(context, input) {
             throw new AppError("harness_adapter_invalid", "Harness adapter did not return a typed Session id", 1, { work_id: work.work_id, harness: runtimeHarness(resolved.worker) });
         // Retain the physical root before any subsequent guard or prompt can fail.
         context.db.run("UPDATE work_launches SET provider_session_id = ?, adapter_receipt_json = ?, updated_at = ? WHERE operation_id = ?", [sessionId, JSON.stringify({ create: created }), context.now(), operationId]);
+        runtimeContext = managedInvocationContext(runtimeContext, { harness: runtimeHarness(resolved.worker), stateDir: root, sessionId,
+            projectRoot: run.project_root, runId: work.run_id, generation });
         assertRunMutationAllowed(context, work.project_id, work.run_id, generation);
         assertWorkLaunchReady(context, work.work_id);
         const promptFile = path.join(root, "launch.md");