@jskit-ai/assistant-core 0.2.7 → 0.2.9

package/src/server/conversation/claudeProcess.js

@@ -13,15 +13,31 @@ const statusReads = new Map();
 const STATUS_RETRY_MS = 30_000;
 const CLAUDE_EXIT_WAIT_MS = 5_000;
 
+/** A Claude process whose caller records no execution identity. */
+function ignoreProcessStart() {}
+
+/** A Claude process whose caller keeps no state after its connection fails. */
+function ignoreProcessFailure() {}
+
+/** Account queries outside a conversation owner borrow no running process. */
+function noOwnedProcesses() {
+  return [];
+}
+
+/** Account queries outside a conversation owner never close for reconnection. */
+function neverClosing() {
+  return false;
+}
+
 /** Person-facing cause for a Claude process that ended without being stopped. */
 export function claudeUnexpectedExitMessage(processExit = {}) {
   const resume = "The conversation so far is saved; send a message to continue.";
-  if (Number(processExit?.taskLimit?.count) > 0) {
+  if (Number(processExit.taskLimit?.count) > 0) {
     return "Claude stopped unexpectedly: the server refused to create more processes or threads for it " +
       `(process/thread limit reached). ${resume}`;
   }
-  if (processExit?.signal) return `Claude stopped unexpectedly: it was terminated by ${processExit.signal}. ${resume}`;
-  if (Number.isInteger(processExit?.code)) {
+  if (processExit.signal) return `Claude stopped unexpectedly: it was terminated by ${processExit.signal}. ${resume}`;
+  if (Number.isInteger(processExit.code)) {
     return `Claude stopped unexpectedly with exit code ${processExit.code}. ${resume}`;
   }
   return `Claude stopped unexpectedly. ${resume}`;
@@ -38,12 +54,22 @@ async function fileRevision(file) {
   }
 }
 
-export async function readClaudeCodeAuthStatus({
-  env = process.env, credentialHome = { home: env.HOME || homedir() }, command = "claude", commandRunner, signal
-} = {}) {
-  if (credentialHome?.ok === false) return { loggedIn: false, error: credentialHome.error };
+/**
+ * The CLI's own account status, cached until its credentials change.
+ * @param {object} options
+ * @param {import("@jskit-ai/kernel/server/types").RuntimeEnv} options.env
+ * @param {{ home: string, ok?: boolean, error?: string }} [options.credentialHome] The account's home; the environment's HOME when not given.
+ * @param {string} [options.command]
+ * @param {(request: Record<string, any>) => Promise<Record<string, any>>} options.commandRunner
+ * @param {AbortSignal} [options.signal]
+ */
+export async function readClaudeCodeAuthStatus({ env, credentialHome, command = "claude", commandRunner, signal }) {
+  if (!env) throw new TypeError("readClaudeCodeAuthStatus requires the application's environment, such as process.env.");
+  const accountHome = credentialHome ?? { home: env.HOME || homedir() };
+  if (accountHome.ok === false) return { loggedIn: false, error: accountHome.error };
+  // readable-check: allow method-probe - input validation: the capture runner a host hands the account status read
   if (typeof commandRunner !== "function") throw new TypeError("Claude account status requires its host capture runner.");
-  const configRoot = env.CLAUDE_CONFIG_DIR || path.join(credentialHome.home, ".claude");
+  const configRoot = env.CLAUDE_CONFIG_DIR || path.join(accountHome.home, ".claude");
   // Inspect file metadata only. Claude still owns reading and validating credentials.
   // Sign-in writes .credentials.json and sign-out removes it. Claude Code also
   // rewrites .claude.json during turns and after every status read, so that
@@ -51,13 +77,13 @@ export async function readClaudeCodeAuthStatus({
   const revision = await fileRevision(path.join(configRoot, ".credentials.json"));
   // One entry per account, whichever command path or host runner reads it: only
   // the account's location and its identity variables count.
-  const key = jsonHash([configRoot, credentialHome.home, Object.entries(env).filter(([name, value]) =>
+  const key = jsonHash([configRoot, accountHome.home, Object.entries(env).filter(([name, value]) =>
     value && (name === "CLAUDE_CODE_OAUTH_TOKEN" || name.startsWith("ANTHROPIC_"))).sort()]);
   const previous = statusReads.get(key);
   if (previous?.revision === revision && (previous.pending || previous.expiresAt > Date.now())) return previous.value;
   const entry = { revision, pending: true, expiresAt: 0 };
   statusReads.set(key, entry);
-  entry.value = readNativeClaudeCodeAuthStatus({ env, credentialHome, command, commandRunner, signal }).then(({ status, unfinished }) => {
+  entry.value = readNativeClaudeCodeAuthStatus({ env, credentialHome: accountHome, command, commandRunner, signal }).then(({ status, unfinished }) => {
     // Keychain changes cannot be observed with file metadata on macOS.
     if (process.platform !== "darwin") {
       // Claude's answer holds until its credentials change. A read the host timed
@@ -99,7 +125,7 @@ function claudeCodeAuthStatus(result) {
   }
 }
 
-/** Exact existing native connection pin, shared with stopped metadata conversion. */
+/** A native connection's exact pin, shared with stopped metadata conversion. */
 export function claudeConnectionIdentity(configRoot, providerId, baseUrl, apiKey) {
   return jsonHash([configRoot, providerId, baseUrl, apiKey]);
 }
@@ -142,6 +168,7 @@ export async function verifyClaudeProviderKey(provider, apiKey, fetchImpl) {
     throw new Error(`${provider.label} could not be reached through Claude Code. Your previous connection is unchanged; try again.`);
   }
   if (!response.ok) {
+    // readable-check: allow optional-call - platform object: another fetch implementation's Response may lack a readable body
     await response.body?.cancel?.();
     throw new Error(response.status === 401 || response.status === 403
       ? `${provider.label} rejected this key. Check the key and the required account plan.`
@@ -287,8 +314,20 @@ export function claudeCatalogueModels(initialization) {
  * usage is shared by `accountIdentity` with every other owner in the process, so
  * that identity names exactly one Claude account. `configRoot` is the account's
  * Claude configuration directory, whose credentials the model list follows.
+ * @param {object} options
+ * @param {(request: { signal: AbortSignal, purpose: string }) => Promise<ClaudeCodeProcess>} options.createProcess
+ * @param {(context: Record<string, any>) => Promise<string>} options.accountIdentity
+ * @param {string} options.configRoot
+ * @param {() => Iterable<{ process: ClaudeCodeProcess | null, stopping?: unknown, accountIdentity: string }>} [options.processes]
+ * @param {() => boolean} [options.isClosing]
  */
-export function createClaudeAccountQueries({ createProcess, accountIdentity, configRoot, processes = () => [], isClosing = () => false }) {
+export function createClaudeAccountQueries({
+  createProcess,
+  accountIdentity,
+  configRoot,
+  processes = noOwnedProcesses,
+  isClosing = neverClosing
+}) {
   const error = message => Object.assign(new Error(message), { code: "claude_account_query_failed" });
   const accountProcessStops = new Set();
   const accountReads = new Set();
@@ -349,112 +388,141 @@ export function createClaudeAccountQueries({ createProcess, accountIdentity, con
       fileRevision(command)]));
   }
 
-  return Object.freeze({
-    async readCatalogue(context) {
-      const expectedRevision = revision;
-      assertCurrent(expectedRevision);
-      const identity = await accountIdentity(context);
-      assertCurrent(expectedRevision);
-      // An answer is kept until its account, credentials or executable change, so
-      // reading it again starts no Claude.
-      const kept = catalog?.identity === identity ? catalog : null;
-      if (kept && kept.revision === await catalogueRevision(kept.command)) {
-        assertCurrent(expectedRevision);
-        return kept.value;
-      }
-      if (!catalogStarts.has(identity)) catalogStarts.set(identity, (async () => {
-        // A conversation's process answers with what it knew when it started, so
-        // the list comes from a Claude started for this read.
-        const { value, command } = await readAccountProcess(identity, expectedRevision, "catalogue",
-          async (native) => ({ value: await native.initialization, command: native.command }));
-        const answered = await catalogueRevision(command);
-        if (identity !== await accountIdentity(context)) throw error("The signed-in Claude account changed. Refresh the model list.");
-        assertCurrent(expectedRevision);
-        catalog = { identity, command, revision: answered, value };
-        return value;
-      })().finally(() => { catalogStarts.delete(identity); }));
-      return catalogStarts.get(identity);
-    },
-    async readPlanUsage(context) {
-      const expectedRevision = revision;
+  async function readCatalogue(context) {
+    const expectedRevision = revision;
+    assertCurrent(expectedRevision);
+    const identity = await accountIdentity(context);
+    assertCurrent(expectedRevision);
+    // An answer is kept until its account, credentials or executable change, so
+    // reading it again starts no Claude.
+    const kept = catalog?.identity === identity ? catalog : null;
+    if (kept && kept.revision === await catalogueRevision(kept.command)) {
       assertCurrent(expectedRevision);
-      const identity = await accountIdentity(context);
+      return kept.value;
+    }
+    if (!catalogStarts.has(identity)) catalogStarts.set(identity, (async () => {
+      // A conversation's process answers with what it knew when it started, so
+      // the list comes from a Claude started for this read.
+      const { value, command } = await readAccountProcess(identity, expectedRevision, "catalogue",
+        async (native) => ({ value: await native.initialization, command: native.command }));
+      const answered = await catalogueRevision(command);
+      if (identity !== await accountIdentity(context)) throw error("The signed-in Claude account changed. Refresh the model list.");
       assertCurrent(expectedRevision);
-      // One reading per account, whichever owner asks; a started process is stopped after its read.
-      let usage = planUsageReads.get(identity);
-      if (!usage) {
-        usage = { liveReadAt: -Infinity, temporaryReadAt: -Infinity, reading: null, pending: null };
-        planUsageReads.set(identity, usage);
-      }
-      usageAccounts.add(identity);
-      if (usage.pending) return usage.pending;
-      const live = Boolean(ownedProcess(identity));
-      const liveDue = live && Date.now() - usage.liveReadAt >= PLAN_USAGE_LIVE_READ_MS;
-      // A one-shot Claude starts only when neither a verified reading nor a one-shot
-      // read is from the last idle interval.
-      const temporaryDue = () => Date.now() - Math.max(usage.temporaryReadAt, usage.reading?.checkedAt ?? -Infinity) >=
-        PLAN_USAGE_IDLE_READ_MS;
-      if (!liveDue && (live || !temporaryDue())) return presentPlanUsage(usage.reading);
-      const pending = (async () => {
-        // A live process's held endpoint read is its own, so a fresh one-shot Claude
-        // may still reach the endpoint when the live answer cannot prove it is current.
-        for (const borrow of liveDue ? [true, false] : [false]) {
-          if (!borrow && !temporaryDue()) break;
-          usage[borrow ? "liveReadAt" : "temporaryReadAt"] = Date.now();
-          let value;
-          try {
-            value = await readAccountProcess(identity, expectedRevision, "usage", (native) => native.client.request(
-              { subtype: "get_usage", skip_behaviors: true }), { borrow });
-          } catch (cause) {
-            if (borrow || !liveDue) throw cause;
-            assertCurrent(expectedRevision);
-            break;
-          }
-          if (identity !== await accountIdentity(context)) return { status: "unavailable", windows: [] };
+      catalog = { identity, command, revision: answered, value };
+      return value;
+    })().finally(() => { catalogStarts.delete(identity); }));
+    return catalogStarts.get(identity);
+  }
+
+  async function readPlanUsage(context) {
+    const expectedRevision = revision;
+    assertCurrent(expectedRevision);
+    const identity = await accountIdentity(context);
+    assertCurrent(expectedRevision);
+    // One reading per account, whichever owner asks; a started process is stopped after its read.
+    let usage = planUsageReads.get(identity);
+    if (!usage) {
+      usage = { liveReadAt: -Infinity, temporaryReadAt: -Infinity, reading: null, pending: null };
+      planUsageReads.set(identity, usage);
+    }
+    usageAccounts.add(identity);
+    if (usage.pending) return usage.pending;
+    const live = Boolean(ownedProcess(identity));
+    const liveDue = live && Date.now() - usage.liveReadAt >= PLAN_USAGE_LIVE_READ_MS;
+    // A one-shot Claude starts only when neither a verified reading nor a one-shot
+    // read is from the last idle interval.
+    const temporaryDue = () => Date.now() - Math.max(usage.temporaryReadAt, usage.reading?.checkedAt ?? -Infinity) >=
+      PLAN_USAGE_IDLE_READ_MS;
+    if (!liveDue && (live || !temporaryDue())) return presentPlanUsage(usage.reading);
+    const pending = (async () => {
+      // A live process's held endpoint read is its own, so a fresh one-shot Claude
+      // may still reach the endpoint when the live answer cannot prove it is current.
+      for (const borrow of liveDue ? [true, false] : [false]) {
+        if (!borrow && !temporaryDue()) break;
+        usage[borrow ? "liveReadAt" : "temporaryReadAt"] = Date.now();
+        let value;
+        try {
+          value = await readAccountProcess(identity, expectedRevision, "usage", (native) => native.client.request(
+            { subtype: "get_usage", skip_behaviors: true }), { borrow });
+        } catch (cause) {
+          if (borrow || !liveDue) throw cause;
           assertCurrent(expectedRevision);
-          // An answer that cannot prove it is current keeps the last verified reading.
-          if (claudePlanUsageVerified(value)) {
-            usage.reading = { ...claudePlanUsage(value), identity };
-            break;
-          }
+          break;
+        }
+        if (identity !== await accountIdentity(context)) return { status: "unavailable", windows: [] };
+        assertCurrent(expectedRevision);
+        // An answer that cannot prove it is current keeps the last verified reading.
+        if (claudePlanUsageVerified(value)) {
+          usage.reading = { ...claudePlanUsage(value), identity };
+          break;
         }
-        return presentPlanUsage(usage.reading);
-      })().finally(() => {
-        usageReads.delete(pending);
-        if (usage.pending === pending) usage.pending = null;
-      });
-      // Requests that arrive while the account is read share that read.
-      usage.pending = pending;
-      usageReads.add(pending);
-      return pending;
-    },
-    // A native usage change lets the next request read again without hiding the last reading.
-    invalidateUsage() {
-      for (const identity of usageAccounts) {
-        const usage = planUsageReads.get(identity);
-        if (usage) usage.liveReadAt = -Infinity;
       }
-    },
-    async invalidate() {
-      revision++;
-      // Dropped at once: a read started before this cannot store its answer.
-      catalog = null;
-      for (const controller of accountReads) controller.abort(error("Claude account query was cancelled for reconnection."));
-      await Promise.allSettled([...catalogStarts.values(), ...usageReads]);
-      // The account changed: the next request for an account this owner used reads again.
-      for (const identity of usageAccounts) planUsageReads.delete(identity);
-      usageAccounts.clear();
-      for (const native of accountProcessStops) await stopAccountProcess(native);
+      return presentPlanUsage(usage.reading);
+    })().finally(() => {
+      usageReads.delete(pending);
+      if (usage.pending === pending) usage.pending = null;
+    });
+    // Requests that arrive while the account is read share that read.
+    usage.pending = pending;
+    usageReads.add(pending);
+    return pending;
+  }
+
+  /** A native usage change lets the next request read again without hiding the last reading. */
+  function invalidateUsage() {
+    for (const identity of usageAccounts) {
+      const usage = planUsageReads.get(identity);
+      if (usage) usage.liveReadAt = -Infinity;
     }
+  }
+
+  async function invalidate() {
+    revision++;
+    // Dropped at once: a read started before this cannot store its answer.
+    catalog = null;
+    for (const controller of accountReads) controller.abort(error("Claude account query was cancelled for reconnection."));
+    await Promise.allSettled([...catalogStarts.values(), ...usageReads]);
+    // The account changed: the next request for an account this owner used reads again.
+    for (const identity of usageAccounts) planUsageReads.delete(identity);
+    usageAccounts.clear();
+    for (const native of accountProcessStops) await stopAccountProcess(native);
+  }
+
+  return Object.freeze({
+    readCatalogue,
+    readPlanUsage,
+    invalidateUsage,
+    invalidate
   });
 }
 
-/** Native startup and handshake; an execution host owns processes and their identity. */
+/**
+ * @typedef {Awaited<ReturnType<typeof createClaudeCodeProcess>>} ClaudeCodeProcess
+ */
+
+/**
+ * Native startup and handshake; an execution host owns processes and their identity.
+ * @param {object} options
+ * @param {string} [options.command]
+ * @param {import("./localExecution.js").ConversationExecution} [options.execution]
+ * @param {import("@jskit-ai/kernel/server/types").RuntimeEnv} options.env
+ * @param {string} [options.workdir]
+ * @param {(frame: Record<string, any>) => Promise<unknown>} [options.onEvent]
+ * @param {(request: Record<string, any>, context: { signal: AbortSignal }) => Promise<unknown>} [options.onControlRequest]
+ * @param {(error: Error) => unknown} [options.onFailure]
+ * @param {(executionId: string, stop: () => Promise<Record<string, any>>) => unknown} [options.onStarted]
+ * @param {object} [options.executionLimits]
+ * @param {AbortSignal} [options.signal]
+ * @param {Record<string, any>} [options.commandWrapper]
+ * @param {number} [options.initializationTimeoutMs]
+ * @param {(stage: string) => void} [options.onInitializationProgress]
+ */
 export async function createClaudeCodeProcess({
-  command = "claude", execution = createLocalConversationExecution(), env = process.env,
-  workdir, onEvent, onControlRequest, onFailure, onStarted, executionLimits, signal, commandWrapper,
-  initializationTimeoutMs = 30_000, onInitializationProgress, ...options
-} = {}) {
+  command = "claude", execution = createLocalConversationExecution(), env,
+  workdir, onEvent, onControlRequest, onFailure = ignoreProcessFailure, onStarted = ignoreProcessStart, executionLimits, signal,
+  commandWrapper, initializationTimeoutMs = 30_000, onInitializationProgress, ...options
+}) {
+  if (!env) throw new TypeError("createClaudeCodeProcess requires the application's environment, such as process.env.");
   if (commandWrapper !== undefined) validateCommandWrapper(commandWrapper);
   const environment = { ...env, DISABLE_AUTOUPDATER: "1" };
   for (const name of ["DBUS_SESSION_BUS_ADDRESS", "DBUS_STARTER_ADDRESS", "DBUS_STARTER_BUS_TYPE",
@@ -479,7 +547,7 @@ export async function createClaudeCodeProcess({
     signal?.throwIfAborted();
     native = await execution.start({ command, args: claudeCodeArguments(options), cwd: workdir,
       env: environment, stream: true, limits: executionLimits });
-    await onStarted?.(native.id, stop);
+    await onStarted(native.id, stop);
     signal?.throwIfAborted();
     const stream = Duplex.from({ readable: native.stdout, writable: native.stdin });
     // A lost stream usually means the process ended. Its exit details arrive
@@ -489,11 +557,11 @@ export async function createClaudeCodeProcess({
       if (failure?.code === "assistant_claude_observation_lost" && exited && !stopped && !stopping) {
         const processExit = failure.processExit || await Promise.race([
           exited.catch(() => null),
-          new Promise((resolve) => setTimeout(resolve, CLAUDE_EXIT_WAIT_MS, null).unref?.())
+          new Promise((resolve) => setTimeout(resolve, CLAUDE_EXIT_WAIT_MS, null).unref())
         ]);
         if (processExit) Object.assign(failure, { processExit, message: claudeUnexpectedExitMessage(processExit) });
       }
-      return onFailure?.(failure);
+      return onFailure(failure);
     };
     client = createClaudeJsonClient({ stream, onEvent, onFailure: describeFailure,
       onControlRequest(request, context) {
@@ -525,7 +593,13 @@ export async function createClaudeCodeProcess({
     }, error => {
       if (!stopped && !stopping) stream.destroy(error);
     });
-    return { client, initialization, executionId: native.id, command, stop };
+    return Object.freeze({
+      client,
+      initialization,
+      executionId: native.id,
+      command,
+      stop
+    });
   } catch (error) {
     // A rejected start may already own an execution and its cleanup proof.
     // Only a returned native handle transfers that cleanup to this owner.

package/src/server/conversation/claudeProcessStart.js

@@ -0,0 +1,214 @@
+import { randomUUID } from "node:crypto";
+import { createClaudeCodeProcess } from "./claudeProcess.js";
+import { claudeApplicationToolResponse } from "./claudeTools.js";
+
+export function hasPendingClaudeStartup(entry) {
+  return entry.startupCleanup?.pending === true && entry.startupCleanup.executionId === entry.executionId;
+}
+
+/**
+ * Starts a retained entry's Claude process: it fences preparation, routes the
+ * process's frames and application tool calls, keeps startup custody, and
+ * suspends a retained goal before the first prompt. Local commands (goal clear,
+ * compaction) run on that process outside the turn view.
+ * @param {{
+ *   store: import("./claudeTurn.js").ClaudeConversationStore,
+ *   process: import("./claudeTurn.js").ClaudeConversationProcessHost,
+ *   createError: import("./claudeTurn.js").ClaudeConversationErrorFactory,
+ *   onEvent: import("./claudeTurn.js").ClaudeConversationEventHandler,
+ *   bound: boolean,
+ *   readHistory: (entry: import("./claudeTurn.js").ClaudeConversationEntry) => Promise<Record<string, any>>,
+ *   isClosing: (contextKey: string) => boolean,
+ *   applicationCall: import("node:async_hooks").AsyncLocalStorage<Record<string, any>>,
+ *   currentApplicationCommand: (entry: import("./claudeTurn.js").ClaudeConversationEntry, command: Record<string, any>, owner?: Record<string, any>) => boolean
+ * }} options
+ */
+export function createClaudeProcessStart({
+  store,
+  process,
+  createError,
+  onEvent,
+  bound,
+  readHistory,
+  isClosing,
+  applicationCall,
+  currentApplicationCommand
+}) {
+  const createProcess = process.create || createClaudeCodeProcess;
+
+  async function startProcess(entry, configuration) {
+    const context = entry.context;
+    const revision = entry.preparationRevision;
+    const assertPreparing = () => {
+      if (revision !== entry.preparationRevision || entry.disposed || isClosing(context.key)) {
+        throw createError("Claude preparation was stopped while this session was closing or changing.", { code: "conversation_claude_preparation_stopped" });
+      }
+    };
+    assertPreparing();
+    let prepared = process.prepare ? process.prepare(entry, configuration, context) : { workdir: entry.nativeWorkdir };
+    // readable-check: allow method-probe - data: a host prepares the workdir synchronously or with a promise; a synchronous one starts without yielding
+    if (prepared && typeof prepared.then === "function") prepared = await prepared;
+    entry.nativeWorkdir = prepared.workdir;
+    if (!entry.sent) entry.sent = (await readHistory(entry)).exists;
+    entry.stopping = false;
+    entry.profile = configuration.profile;
+    let options = process.configure(entry, configuration, { context, prepared });
+    // readable-check: allow method-probe - data: a host configures the process synchronously or with a promise; a synchronous one starts without yielding
+    if (options && typeof options.then === "function") options = await options;
+    assertPreparing();
+    let startupCleanup;
+    let startedExecutionId;
+    const processToken = {};
+    try { entry.process = await createProcess({ ...options,
+      workdir: entry.nativeWorkdir, sessionId: entry.id, resume: entry.sent,
+      onStarted: async (executionId, stop) => {
+        startedExecutionId = executionId;
+        if (typeof stop === "function") {
+          startupCleanup = { executionId, stop, pending: true };
+          entry.startupCleanup = startupCleanup;
+        }
+        if (entry.executionId !== executionId) {
+          entry.executionId = executionId;
+          await store.save(entry, { execution: true });
+          await onEvent(entry, { type: "execution", context, executionId });
+        }
+        assertPreparing();
+      },
+      async onEvent(frame) {
+        const pending = entry.goalToolStop;
+        if (pending && pending.executionId === startedExecutionId && entry.process === pending.process &&
+            frame.type === "user" && !frame.parent_tool_use_id && Array.isArray(frame.message?.content) &&
+            frame.message.content.some(block => block.type === "tool_result" && block.tool_use_id === pending.toolUseId)) {
+          // The CLI has consumed the tool response. Do not join process cleanup
+          // on its event reader: interrupt/exit also needs that reader to drain.
+          pending.stop();
+        }
+        // Local commands (retained goal clear, compaction) are not AI turns.
+        // Their frames stay out of the turn view until their own result.
+        const local = entry.localCommand;
+        if (local?.processToken === processToken) {
+          if (frame.type === "result" && frame.user_message_uuid === local.id) {
+            if (frame.local_command === local.name && frame.is_error !== true && frame.subtype === "success") local.resolve();
+            else local.reject(createError(local.failureMessage, { code: local.failureCode }));
+          }
+          return;
+        }
+        const current = entry.command;
+        if (current && frame.type === "assistant" && !frame.parent_tool_use_id) {
+          for (const tool of frame.message?.content || []) if (tool.type === "tool_use" && tool.id && tool.name?.startsWith("mcp__application__")) {
+            if (current.nativeToolCount >= current.maximumToolCalls && !current.nativeTools.has(tool.id)) {
+              throw new Error("Claude exceeded the application tool-call limit.");
+            }
+            if (!current.nativeTools.has(tool.id)) {
+              current.nativeToolCount++;
+              current.nativeTools.set(tool.id, { name: tool.name, input: tool.input, messageId: current.messageId });
+            }
+          }
+        }
+        await entry.nativeTurn.receive(frame);
+      },
+      ...(bound || options.applicationTools || entry.command?.tools ? {
+        async onControlRequest(request, { signal }) {
+          const active = entry.command;
+          const suppliedTools = !bound && active?.tools;
+          const owner = active?.nativeOwner;
+          const work = applicationCall.run({ entry, command: active, owner,
+            toolUseId: request.message?.params?._meta?.["claudecode/toolUseId"] },
+          () => claudeApplicationToolResponse(request, { schemas: entry.toolSchemas || [], turn: active, signal,
+            ...(suppliedTools ? {
+              assertCurrent(native) {
+                if (!currentApplicationCommand(entry, active, owner) || active.nativeOwner !== owner ||
+                    native.messageId !== active.messageId) throw new Error("Claude's application call belongs to a retired input.");
+              },
+              onExecutionFailure(error, native) {
+                // Already-invoked old work retains its original result. Only
+                // this still-current authored input can fail this native run.
+                if (currentApplicationCommand(entry, active, owner) && active.nativeOwner === owner &&
+                    native.messageId === active.messageId) {
+                  active.toolFailure = error;
+                  active.failure.reject(error);
+                }
+              }
+            } : {}) }));
+          active?.toolWork.add(work);
+          try { return await work; }
+          finally { active?.toolWork.delete(work); }
+        }
+      } : {}),
+      onFailure: async error => {
+        if (entry.localCommand?.processToken === processToken) entry.localCommand.reject(error);
+        if (bound) {
+          entry.nativeTurn.invalidateInstructions();
+          try { await entry.nativeTurn.stopProcess(error.message); }
+          catch (cleanupError) { error = cleanupError; await context.reportFailure(cleanupError); }
+          entry.command?.completion.reject(error);
+          return;
+        }
+        entry.observationError = error.message;
+        await entry.nativeTurn.stopProcess(error.message);
+      }
+    }); } catch (error) {
+      if (error.executionId && error.stopProof?.scopeEmpty !== true && !entry.executionId) {
+        // Streaming startup can fail after host admission, before onStarted.
+        // Retain that custody through the same binding owner for Stop recovery.
+        error.cleanupFailed = true;
+        entry.executionId = error.executionId;
+        try {
+          await store.save(entry, { execution: true });
+          await onEvent(entry, { type: "execution", context, executionId: entry.executionId });
+        } catch (bindingError) { error.bindingError = bindingError; }
+      }
+      if (bound && error.stopProof?.scopeEmpty) {
+        await store.releaseExecution(entry);
+        if (entry.startupCleanup?.executionId === error.executionId) entry.startupCleanup = null;
+      }
+      throw error;
+    } finally {
+      if (startupCleanup) startupCleanup.pending = false;
+    }
+    try { assertPreparing(); }
+    catch (error) {
+      await entry.nativeTurn.stopProcess(error.message);
+      throw error;
+    }
+    if (entry.startupCleanup?.executionId === entry.executionId) entry.startupCleanup = null;
+    entry.processToken = processToken;
+    if (entry.pausedGoal || entry.blockedGoal) {
+      try {
+        const id = await runLocalCommand(entry, "/goal clear", { name: "goal", timeoutMs: 30_000,
+          failureMessage: "Claude could not suspend its retained goal checker.", failureCode: "conversation_claude_goal_suspend_failed",
+          timeoutMessage: "Claude timed out suspending its retained goal checker.", timeoutCode: "conversation_claude_goal_suspend_timeout" });
+        const cleared = await readHistory(entry);
+        if (cleared.goal || cleared.goalCommandId !== id) {
+          throw createError("Claude has not saved the retained goal's native clear receipt.", { code: "conversation_claude_goal_clear_unconfirmed" });
+        }
+        assertPreparing();
+      } catch (error) {
+        await entry.nativeTurn.stopProcess(error.message);
+        throw Object.assign(error, { delivery: "not-sent" });
+      }
+    }
+    return entry.process;
+  }
+
+  async function runLocalCommand(entry, command, { name, timeoutMs, failureMessage, failureCode, timeoutMessage, timeoutCode }) {
+    const completion = Promise.withResolvers();
+    completion.promise.catch(() => {});
+    const local = { ...completion, id: randomUUID(), name, failureMessage, failureCode, processToken: entry.processToken };
+    entry.localCommand = local;
+    const timer = setTimeout(() => completion.reject(createError(timeoutMessage, { code: timeoutCode })), timeoutMs);
+    try {
+      await entry.process.client.send(command, { messageId: local.id, sessionId: entry.id });
+      await completion.promise;
+      return local.id;
+    } finally {
+      clearTimeout(timer);
+      if (entry.localCommand === local) entry.localCommand = null;
+    }
+  }
+
+  return Object.freeze({
+    startProcess,
+    runLocalCommand
+  });
+}