@jskit-ai/assistant-core 0.1.226 → 0.1.228

package/src/server/conversation/claudeTurn.js

@@ -1,5 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
+import { AsyncLocalStorage } from "node:async_hooks";
 import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
 import { claudeMessageBlocks, deleteClaudeConversationHistory, readClaudeHistory, requireClaudeSessionId, retireClaudeConversationHistory } from "./claudeHistory.js";
 import { bindClaudeConversationAccount, claudeCodeArguments, createClaudeAccountQueries, createClaudeCodeProcess, stopClaudeCodeProcess } from "./claudeProcess.js";
 import { claudeApplicationToolResponse } from "./claudeTools.js";
@@ -12,6 +14,10 @@ function failure(message, code = "assistant_claude_turn_failed") {
 const text = value => String(value ?? "").trim();
 const now = () => new Date().toISOString();
 
+function hasPendingClaudeStartup(entry) {
+  return entry.startupCleanup?.pending === true && entry.startupCleanup.executionId === entry.executionId;
+}
+
 export function claudeNativeMessageId(id) {
   const value = createHash("sha256").update(String(id)).digest("hex");
   return `${value.slice(0, 8)}-${value.slice(8, 12)}-4${value.slice(13, 16)}-8${value.slice(17, 20)}-${value.slice(20, 32)}`;
@@ -23,7 +29,7 @@ export async function waitForClaudeConversationTurn(conversation, input = {}, {
   interruptedMessage = "Claude was interrupted when the application disconnected."
 } = {}) {
   const entry = conversation.state;
-  if (entry.executionId && !entry.process) await conversation.stop(interruptedMessage);
+  if (entry.executionId && !entry.process && !hasPendingClaudeStartup(entry)) await conversation.stop(interruptedMessage);
   if (!entry.turn?.active) return conversation.read(input);
   const timeoutMs = Math.min(
     Number(input.timeoutMs) > 0 ? Number(input.timeoutMs) : defaultTimeoutMs,
@@ -98,29 +104,42 @@ export async function runClaudeRenewalTurn(conversation, {
   }
 }
 
-export function createClaudeConversationGoals({ conversationId, readHistory, readState, interrupt, send }) {
-  const goalError = message => failure(message, "assistant_claude_goal_failed");
+export function createClaudeConversationGoals({ conversationId, readHistory, readState, interrupt, send, readRetainedGoal, saveRetainedGoal }) {
+  // These checks run before interrupt/send. Native execution and receipt
+  // failures keep their own codes and must not be treated as safe rejections.
+  const goalError = message => Object.assign(failure(message, "conversation_invalid_goal"), {
+    statusCode: 400, delivery: "not-sent"
+  });
 
-  async function read() {
-    const { goal = null } = await readHistory();
+  async function read(history = null) {
+    const { goal = null } = history || await readHistory();
+    const retained = readRetainedGoal?.();
+    if (retained) return { ...retained };
     const state = readState();
-    return goal ? { ...goal, status: goal.status === "complete" ? "complete" :
+    return goal ? { ...goal, status: ["complete", "blocked"].includes(goal.status) ? goal.status :
       state.running && state.active ? "active" : "paused" } : null;
   }
 
-  async function update(input = {}, { interrupt: interruptGoal = interrupt, send: sendGoal = send } = {}) {
+  async function update(input = {}, { interrupt: interruptGoal = interrupt, send: sendGoal = send, signal } = {}) {
     const goal = await read();
+    signal?.throwIfAborted();
     const action = input.action;
     if (action !== "set" && (!goal || input.threadId !== conversationId ||
         input.createdAt !== goal.createdAt || input.objective !== goal.objective)) {
       throw goalError("The Claude goal changed. Refresh before trying again.");
     }
     if (input.tokenBudget != null) throw goalError("Claude goals do not support a token budget.");
-    if (action === "pause") {
+    if (action === "pause" || action === "block") {
+      const reason = typeof input.reason === "string" ? input.reason.trim() : "";
+      if (action === "block" && (!reason || reason.length > 1000 || goal.status !== "active")) {
+        throw goalError("An active Claude goal needs a blocker reason of up to 1,000 characters.");
+      }
+      if (goal.status !== "complete") await saveRetainedGoal({ ...goal,
+        status: action === "block" ? "blocked" : "paused", ...(action === "block" ? { reason } : {}) });
       await interruptGoal();
     } else if (action === "cancel") {
       await interruptGoal();
-      await sendGoal({ message: "/goal clear" });
+      await sendGoal({ message: "/goal clear", signal });
     } else if (action === "set" || action === "resume") {
       const objective = String((action === "set" ? input.objective : goal.objective) ?? "").trim();
       if (!objective || objective.length > 4000 || /^(clear|stop|off|reset|none|cancel)$/iu.test(objective)) {
@@ -129,7 +148,7 @@ export function createClaudeConversationGoals({ conversationId, readHistory, rea
       if (action === "set" && goal && goal.status !== "complete") {
         throw goalError("Cancel the existing goal before setting another.");
       }
-      await sendGoal({ message: `/goal ${objective}` });
+      await sendGoal({ message: `/goal ${objective}`, signal });
     } else throw goalError("Unknown Claude goal action.");
   }
 
@@ -142,6 +161,7 @@ export function createClaudeConversationOwner({
   disconnectedMessage = "Claude was interrupted when the application disconnected."
 }) {
   const entries = new Map();
+  const applicationCall = new AsyncLocalStorage();
   const closingSessions = new Set();
   let closing = false;
   const createProcess = process.create || createClaudeCodeProcess;
@@ -163,7 +183,7 @@ export function createClaudeConversationOwner({
     return Boolean(owner && entry && !closing && !closingSessions.has(entry.context.key) &&
       entries.get(entry.key) === entry && entry.command === command && command.entry === entry &&
       command.admitted && !command.signal.aborted && !command.toolFailure &&
-      !entry.disposed && !entry.stopping && !entry.stopPending && !entry.observationError &&
+      !entry.disposed && !entry.stopping && !entry.stopPending && !entry.goalToolStop && !entry.observationError &&
       entry.process === owner.process && entry.executionId === owner.executionId &&
       entry.accountIdentity === owner.accountIdentity && entry.id === owner.threadId &&
       entry.turn?.id === owner.turnId && entry.turn.active && native.turnId === owner.turnId && native.active);
@@ -216,10 +236,19 @@ export function createClaudeConversationOwner({
       executionId: state.executionId || (recoveringCleanup ? cleanupExecutionId : ""), preparationRevision: 0,
       accountIdentities: state.accountIdentities || (state.accountIdentity ? { anthropic: state.accountIdentity } : {}),
       accountIdentity: state.accountIdentity || "", sent: state.sent === true, nativeWorkdir: state.nativeWorkdir || nativeWorkdir,
-      lastMessageId: state.lastMessageId || "", turn: state.turnId ? {
+      lastMessageId: state.lastMessageId || "", pausedGoal: state.pausedGoal || null, blockedGoal: state.blockedGoal || null, turn: state.turnId ? {
         id: state.turnId, active: ["starting", "active", "finalizing"].includes(state.state),
         state: state.state, startedAt: now(), updatedAt: now()
       } : null };
+    for (const [field, status] of [["pausedGoal", "paused"], ["blockedGoal", "blocked"]]) {
+      const retained = entry[field];
+      if (retained && (retained.threadId !== id || typeof retained.objective !== "string" ||
+          !retained.objective.trim() || !Number.isFinite(retained.createdAt) || retained.status !== status ||
+          status === "blocked" && (typeof retained.reason !== "string" || !retained.reason.trim() || retained.reason.length > 1000))) {
+        throw createError("The retained Claude goal is invalid. Restore its saved conversation state.");
+      }
+    }
+    if (entry.pausedGoal && entry.blockedGoal) throw createError("The saved Claude goal cannot be both paused and blocked.");
     entry.nativeTurn = createClaudeConversationTurn({ conversationId: id, entry,
       onEvent: event => onEvent(entry, event),
       process: {
@@ -234,6 +263,14 @@ export function createClaudeConversationOwner({
     });
     entry.goals = createClaudeConversationGoals({ conversationId: id,
       readHistory: () => readHistory(entry),
+      readRetainedGoal: () => entry.pausedGoal || entry.blockedGoal,
+      async saveRetainedGoal(goal) {
+        const previous = { pausedGoal: entry.pausedGoal, blockedGoal: entry.blockedGoal };
+        entry.pausedGoal = goal.status === "paused" ? goal : null;
+        entry.blockedGoal = goal.status === "blocked" ? goal : null;
+        try { await store.save(entry); }
+        catch (error) { Object.assign(entry, previous); throw error; }
+      },
       readState: () => ({ running: Boolean(entry.process), active: store.releaseExecution ? entry.nativeTurn.read().active : Boolean(entry.turn?.active) }),
       interrupt: () => interrupt(entry), send: input => send(entry, input) });
     entries.set(key, entry);
@@ -273,10 +310,13 @@ export function createClaudeConversationOwner({
   }
 
   async function ensureReady(entry) {
-    if (entry.process) await ensureProcess(entry);
-    else {
+    if (entry.process) {
+      // Status reads retain active instructions; apply changes at idle admission.
+      if (store.releaseExecution ? entry.nativeTurn.read().active : entry.turn?.active) await bindAccount(entry);
+      else await ensureProcess(entry);
+    } else {
       await bindAccount(entry);
-      if (entry.executionId) await entry.nativeTurn.stopProcess("Claude's previous process exit could not be confirmed.");
+      if (entry.executionId && !hasPendingClaudeStartup(entry)) await entry.nativeTurn.stopProcess("Claude's previous process exit could not be confirmed.");
       // The first Send prepares host hooks before starting the native process.
     }
     return { ok: true, thread: { id: entry.id }, turn: snapshot(entry), workdir: entry.context.workdir };
@@ -296,6 +336,24 @@ export function createClaudeConversationOwner({
     return entry.nativeTurn.prepare(configuration);
   }
 
+  async function readContextUsage(entry, input = {}) {
+    input.signal?.throwIfAborted();
+    const native = await ensureProcess(entry, input);
+    input.signal?.throwIfAborted();
+    const usage = await native.client.request({ subtype: "get_context_usage", detail: "summary" });
+    input.signal?.throwIfAborted();
+    const usedTokens = usage?.totalTokens;
+    const maximum = usage?.maxTokens;
+    const threshold = usage?.autoCompactThreshold ?? maximum;
+    if (!Number.isSafeInteger(usedTokens) || usedTokens < 0 ||
+        !Number.isSafeInteger(maximum) || maximum < 1 ||
+        !Number.isSafeInteger(threshold) || threshold < 1 || typeof usage.model !== "string" || !usage.model) {
+      throw createError("Claude's current context usage is unavailable.");
+    }
+    return { model: usage.model, usedTokens,
+      windowTokens: usage.isAutoCompactEnabled === false ? maximum : Math.min(maximum, threshold) };
+  }
+
   async function stopForTerminal(entry, application) {
     if (entry.turn?.active) throw createError("Stop the current turn before opening the Claude Code terminal.");
     if (closing || closingSessions.has(entry.context.key) || application?.sessionClosing) throw createError("This session is closing.");
@@ -326,17 +384,23 @@ export function createClaudeConversationOwner({
     let prepared = process.prepare ? process.prepare(entry, configuration, context) : { workdir: entry.nativeWorkdir };
     if (prepared && typeof prepared.then === "function") prepared = await prepared;
     entry.nativeWorkdir = prepared.workdir;
-    const history = await readHistory(entry);
-    entry.sent ||= history.exists;
+    if (!entry.sent) entry.sent = (await readHistory(entry)).exists;
     entry.stopping = false;
     entry.profile = configuration.profile;
     let options = process.configure(entry, configuration, { context, prepared });
     if (options && typeof options.then === "function") options = await options;
     assertPreparing();
+    let startupCleanup;
+    let retainedGoalClear;
+    let startedExecutionId;
     try { entry.process = await createProcess({ ...options,
       workdir: entry.nativeWorkdir, sessionId: entry.id, resume: entry.sent,
       onStarted: async (executionId, stop) => {
-        if (typeof stop === "function") entry.startupCleanup = { 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 });
@@ -345,6 +409,23 @@ export function createClaudeConversationOwner({
         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();
+        }
+        // A retained Pause disarms only the native goal hook before a new
+        // authored input is admitted. This local command is not an AI turn.
+        if (retainedGoalClear) {
+          if (frame.type === "result" && frame.user_message_uuid === retainedGoalClear.id) {
+            if (frame.local_command === "goal" && frame.is_error !== true && frame.subtype === "success") retainedGoalClear.resolve();
+            else retainedGoalClear.reject(createError("Claude could not suspend its retained goal checker."));
+          }
+          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__")) {
@@ -359,12 +440,14 @@ export function createClaudeConversationOwner({
         }
         await entry.nativeTurn.receive(frame);
       },
-      ...(store.releaseExecution || entry.command?.tools ? {
+      ...(store.releaseExecution || options.applicationTools || entry.command?.tools ? {
         async onControlRequest(request, { signal }) {
           const active = entry.command;
           const suppliedTools = !store.releaseExecution && active?.tools;
           const owner = active?.nativeOwner;
-          const work = claudeApplicationToolResponse(request, { schemas: entry.toolSchemas || [], turn: active, signal,
+          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 ||
@@ -379,13 +462,14 @@ export function createClaudeConversationOwner({
                   active.failure.reject(error);
                 }
               }
-            } : {}) });
+            } : {}) }));
           active?.toolWork.add(work);
           try { return await work; }
           finally { active?.toolWork.delete(work); }
         }
       } : {}),
       onFailure: async error => {
+        retainedGoalClear?.reject(error);
         if (store.releaseExecution) {
           entry.nativeTurn.invalidateInstructions();
           try { await entry.nativeTurn.stopProcess(error.message); }
@@ -412,6 +496,8 @@ export function createClaudeConversationOwner({
         if (entry.startupCleanup?.executionId === error.executionId) entry.startupCleanup = null;
       }
       throw error;
+    } finally {
+      if (startupCleanup) startupCleanup.pending = false;
     }
     try { assertPreparing(); }
     catch (error) {
@@ -419,6 +505,27 @@ export function createClaudeConversationOwner({
       throw error;
     }
     if (entry.startupCleanup?.executionId === entry.executionId) entry.startupCleanup = null;
+    if (entry.pausedGoal || entry.blockedGoal) {
+      const completion = Promise.withResolvers();
+      completion.promise.catch(() => {});
+      retainedGoalClear = { ...completion, id: randomUUID() };
+      const timer = setTimeout(() => completion.reject(createError("Claude timed out suspending its retained goal checker.")), 30_000);
+      try {
+        await entry.process.client.send("/goal clear", { messageId: retainedGoalClear.id, sessionId: entry.id });
+        await completion.promise;
+        const cleared = await readHistory(entry);
+        if (cleared.goal || cleared.goalCommandId !== retainedGoalClear.id) {
+          throw createError("Claude has not saved the retained goal's native clear receipt.");
+        }
+        assertPreparing();
+      } catch (error) {
+        await entry.nativeTurn.stopProcess(error.message);
+        throw Object.assign(error, { delivery: "not-sent" });
+      } finally {
+        clearTimeout(timer);
+        retainedGoalClear = null;
+      }
+    }
     return entry.process;
   }
 
@@ -438,9 +545,26 @@ export function createClaudeConversationOwner({
         return { ok: true, delivered: true, duplicate: true, thread: { id: entry.id }, turn: snapshot(entry) };
       }
     }
-    const native = command ? command.steering ? entry.process : await entry.nativeTurn.prepare(command.prepared) : await ensureProcess(entry, input);
+    let native;
+    try {
+      if (!command && entry.main && entry.turn?.active && entry.process) {
+        // Main steering keeps the active instruction installation, just like
+        // command steering. Refresh guidance on the next idle admission.
+        // Account replacement must still confirm cleanup before any new send.
+        if (preparation.account) await bindAccount(entry);
+        native = entry.process || await ensureProcess(entry, input);
+      } else {
+        native = command ? command.steering ? entry.process : await entry.nativeTurn.prepare(command.prepared) : await ensureProcess(entry, input);
+      }
+    } catch (error) {
+      // Preparation may start or resume the process, but has not written this
+      // authored input. Keep its failure distinct from a lost native receipt.
+      throw Object.assign(error, { delivery: "not-sent" });
+    }
     if (command && !command.steering) command.signal.throwIfAborted();
     const steering = command ? command.steering === true : Boolean(entry.turn?.active);
+    const sendNow = steering && native.client.supportsSendNow?.() === true;
+    if (input.signal?.aborted) throw Object.assign(createError("The goal command was stopped before delivery."), { delivery: "not-sent" });
     if (steering) {
       if (command) {
         await command.beforeDispatch({ threadId: entry.id });
@@ -448,11 +572,13 @@ export function createClaudeConversationOwner({
       }
       try {
         await entry.nativeTurn.interruptGeneration(command ? entry.process.client : native.client,
-          command ? { timeoutMs: command.timeoutMs } : undefined);
-        if (command) command.interrupted = true;
+          { ...(command ? { timeoutMs: command.timeoutMs } : {}), sendNow });
+        if (command) command.interrupted = !sendNow;
       } catch (error) {
         if (!command) await entry.nativeTurn.stopProcess(error.message);
-        throw error;
+        // Interruption precedes this input's pipe write. Preserve that definite
+        // non-delivery so a failed interrupt cannot strand an attempted receipt.
+        throw Object.assign(error, { delivery: "not-sent" });
       }
     }
     const prompt = command ? undefined : await preparation.message(entry, input, { context, message, steering, renewal });
@@ -524,8 +650,9 @@ export function createClaudeConversationOwner({
     try {
       if (command) command.attempted = true;
       else await input.onPromptSending?.({ threadId: entry.id, displayAttachments: input.displayAttachments, turnMetadata: actorMetadata });
+      if (input.signal?.aborted) throw Object.assign(createError("The goal command was stopped before delivery."), { delivery: "not-sent" });
       await entry.nativeTurn.send(command ? entry.process.client : native.client, command ? preparation.message(entry, input) : prompt,
-        { messageId: uuid, accept, ...(command ? { timeoutMs: command.timeoutMs } : {}) });
+        { messageId: uuid, accept, sendNow, ...(command ? { timeoutMs: command.timeoutMs } : {}) });
     } catch (error) {
       if (!command) await entry.nativeTurn.stopProcess(error.message);
       throw error;
@@ -547,12 +674,26 @@ export function createClaudeConversationOwner({
   }
 
   async function read(entry, input = {}) {
-    if (entry.executionId && !entry.process) await entry.nativeTurn.stopProcess(disconnectedMessage);
+    if (entry.executionId && !entry.process && !hasPendingClaudeStartup(entry)) await entry.nativeTurn.stopProcess(disconnectedMessage);
     const history = await readHistory(entry);
     const messages = new Map(history.messages.map(message => [message.id, message]));
+    const savedOutputs = new Map(history.messages.filter(message => message.outputId).map(message => [message.outputId, message]));
     const current = entry.nativeTurn.read();
-    for (const message of current.messages) messages.set(message.id, message);
-    return { ...entry.nativeTurn.readResult(), ok: true, messages: [...messages.values()], text: current.text || history.text,
+    for (const message of current.messages) {
+      const saved = savedOutputs.get(message.outputId);
+      if (saved && saved.id !== message.id && saved.userId === message.userId) {
+        // Native history can contain the completed block before its frame has
+        // drained through live callbacks. Keep that text once, retaining a
+        // verified Stop's commentary classification rather than inventing a FINAL.
+        messages.set(saved.id, { ...saved,
+          ...(current.status === "interrupted" && message.complete && message.role === "commentary" ? { role: "commentary" } : {}) });
+      } else messages.set(message.id, { ...messages.get(message.id), ...message });
+    }
+    const requestIds = new Map((input.requestMessageIds || [input.messageId]).filter(id => typeof id === "string" && id)
+      .map(id => [claudeNativeMessageId(id), id]));
+    return { ...entry.nativeTurn.readResult(), ok: true,
+      messages: [...messages.values()].map(message => ({ ...message,
+        ...(message.userId ? { requestMessageId: requestIds.get(message.userId) || "" } : {}) })), text: current.text || history.text,
       admitted: history.userIds.includes(claudeNativeMessageId(input.messageId || "")) };
   }
 
@@ -686,7 +827,7 @@ export function createClaudeConversationOwner({
 
   async function recover(restoredEntries) {
     for (const entry of restoredEntries) {
-      if (!entry.process && (entry.executionId || entry.turn?.active)) await entry.nativeTurn.stopProcess(disconnectedMessage);
+      if (!entry.process && !hasPendingClaudeStartup(entry) && (entry.executionId || entry.turn?.active)) await entry.nativeTurn.stopProcess(disconnectedMessage);
     }
   }
 
@@ -715,18 +856,58 @@ export function createClaudeConversationOwner({
 
   async function readGoal(entry) {
     await bindAccount(entry);
-    return { status: "available", threadId: entry.id, goal: await entry.goals.read() };
+    const history = await readHistory(entry);
+    return { status: "available", threadId: entry.id, goal: await entry.goals.read(history), goalCommandId: history.goalCommandId || null };
   }
 
   async function updateGoal(entry, input, operations) {
     await bindAccount(entry);
-    try { await entry.goals.update(input, operations); }
-    catch (error) {
-      if (error.code !== "assistant_claude_goal_failed") throw error;
-      throw createError(error.message);
+    const call = applicationCall.getStore();
+    const selfStop = ["pause", "block"].includes(input.action) && call?.entry === entry &&
+      call.toolUseId && currentApplicationCommand(entry, call.command, call.owner);
+    const messageId = input.messageId || randomUUID();
+    await entry.goals.update(input, { ...operations,
+      ...(selfStop ? { interrupt: async () => {} } : {}),
+      send: command => operations?.send ? operations.send(command) : send(entry, { ...command, messageId }) });
+    if (selfStop && currentApplicationCommand(entry, call.command, call.owner)) {
+      // This scope identifies the already-authorized native invocation; it does
+      // not grant tool authority. Retain its exact process until its tool_result
+      // arrives instead of interrupting the MCP request that is returning here.
+      const pending = { process: call.owner.process, executionId: call.owner.executionId, toolUseId: call.toolUseId };
+      pending.stop = (reason = "") => {
+        if (entry.goalToolStop !== pending || pending.stopping) return;
+        clearTimeout(pending.timer);
+        if (entry.process !== pending.process || entry.executionId !== pending.executionId) {
+          entry.goalToolStop = null;
+          return;
+        }
+        pending.stopping = true;
+        const work = reason || !entry.turn?.active ? entry.nativeTurn.stopProcess(reason) : interrupt(entry);
+        void work.catch(error => call.command.failure.reject(error));
+      };
+      entry.goalToolStop = pending;
+      pending.timer = setTimeout(() => pending.stop("Claude did not acknowledge its goal tool response before the time limit."), 30_000);
+      pending.timer.unref();
+    } else if (!selfStop && ["pause", "block"].includes(input.action)) await entry.nativeTurn.stopProcess();
+    let result;
+    if (!["pause", "block"].includes(input.action)) {
+      const deadline = Date.now() + (operations?.attachmentTimeoutMs ?? 30_000);
+      for (;;) {
+        const history = await readHistory(entry);
+        if (history.goalCommandId === claudeNativeMessageId(messageId)) {
+          if (entry.pausedGoal || entry.blockedGoal) { entry.pausedGoal = null; entry.blockedGoal = null; await store.save(entry); }
+          result = { status: "available", threadId: entry.id, goal: await entry.goals.read(history), goalCommandId: history.goalCommandId };
+          break;
+        }
+        if (operations?.signal?.aborted) throw operations.signal.reason;
+        if (Date.now() >= deadline) throw Object.assign(failure(
+          "Claude accepted the goal command, but its goal attachment is not available yet. Check its original receipt before trying again.",
+          "assistant_claude_goal_attachment_pending"), { delivery: "accepted", statusCode: 503 });
+        await delay(Math.min(250, Math.max(1, deadline - Date.now())), undefined, { signal: operations?.signal });
+      }
     }
     await onEvent(entry, { type: "goal-updated" });
-    return { ok: true, status: "available", threadId: entry.id, goal: await entry.goals.read() };
+    return { ok: true, ...(result || await readGoal(entry)) };
   }
 
   function renewal(entry, input, options, { context, acquire }) {
@@ -774,7 +955,7 @@ export function createClaudeConversationOwner({
       entry.command = active;
       entry.toolSchemas = active.tools?.schemas || [];
     }
-    const value = await send(entry, { ...command.input.nativeMessage, onPromptSending: command.beforeDispatch,
+    const value = await send(entry, { ...command.input.nativeMessage, signal: command.input.signal, onPromptSending: command.beforeDispatch,
       onNativeReceipt: command.onNativeReceipt, onReceiptPersisted: command.onReceiptPersisted }, { applicationCommand });
     const completion = value.conversationTurn ? entry.completion?.promise : null;
     const delivered = { value, completion };
@@ -811,7 +992,7 @@ export function createClaudeConversationOwner({
         timeoutMs, steering: true, interrupted: false, attempted: false, admitted: false };
       try { await dispatch(control, { input, context, signal }, { acquire, entry, dispatch: nativeDispatch }); }
       catch (error) {
-        if (nativeDispatch.attempted && !nativeDispatch.admitted) error.delivery = "uncertain";
+        if (nativeDispatch.attempted && !nativeDispatch.admitted && error.delivery !== "not-sent") error.delivery = "uncertain";
         if (nativeDispatch.interrupted || nativeDispatch.attempted) completion.reject(error);
         throw error;
       }
@@ -903,13 +1084,13 @@ export function createClaudeConversationOwner({
     }
     if (control.current === active) control.current = null;
     if (problem) {
-      if (binding && nativeDispatch.attempted && !nativeDispatch.admitted) problem.delivery = "uncertain";
+      if (binding && nativeDispatch.attempted && !nativeDispatch.admitted && problem.delivery !== "not-sent") problem.delivery = "uncertain";
       throw problem;
     }
     if (!binding) return { value: delivered.value };
   }
 
-  return Object.freeze({ applicationToolsSupported: true, entries, closingSessions, get closing() { return closing; }, createAccountQueries, open, acquire, createConversation, snapshot, readRetainedTurn, readFinalAssistantResult, readHistory, ensureReady, ensureProcess, stopForTerminal, prepareTerminal, send, startTurn,
+  return Object.freeze({ applicationToolsSupported: true, entries, closingSessions, get closing() { return closing; }, createAccountQueries, open, acquire, createConversation, snapshot, readRetainedTurn, readFinalAssistantResult, readHistory, ensureReady, ensureProcess, readContextUsage, stopForTerminal, prepareTerminal, send, startTurn,
     interrupt, read, inspectAdmission, hasActiveTemporaryConversation, hasActiveConversation, retireConversationHistory, reconcileSessions, restoreSessionEntries, closeSession, closeProject, invalidateRuntimes, drain, forget, close, deleteConversation, recover, stopSelected, wait, stopConversation,
     readGoal, updateGoal, renewal, run, steer, cancel });
 }
@@ -1018,6 +1199,8 @@ export function createClaudeConversationTurn({ conversationId, onEvent = async (
   }
 
   async function stopProcess(reason = "", { preparing = false } = {}) {
+    clearTimeout(entry.goalToolStop?.timer);
+    entry.goalToolStop = null;
     if (!preparing) entry.preparationRevision++;
     invalidateFinalAssistantResult();
     // Runtime bindings commit execution release before dropping the handle.
@@ -1143,6 +1326,7 @@ export function createClaudeConversationTurn({ conversationId, onEvent = async (
   }
 
   async function publishMessage(message) {
+    if (!message.userId && currentCommandId) message = { ...message, userId: currentCommandId };
     messages.set(message.id, message);
     const owner = acceptedInput;
     const completeAssistant = message.complete && message.role === "assistant";
@@ -1191,7 +1375,10 @@ export function createClaudeConversationTurn({ conversationId, onEvent = async (
     if (frame.type === "command_lifecycle" || frame.type === "user") {
       const uuid = frame.type === "user" ? frame.uuid : frame.command_uuid;
       if (frame.type === "user" && !inFlight.has(uuid) && !admissions.has(uuid)) return;
-      if (frame.state === "started" || frame.type === "user") currentCommandId = uuid;
+      // Native notifications have their own lifecycle UUIDs, including work
+      // folded into this input. They must not steal its receipt/result owner.
+      if ((frame.state === "started" || frame.type === "user") && inFlight.has(uuid)) currentCommandId = uuid;
+      if (frame.state === "completed") inFlight.delete(uuid);
       if (frame.state === "cancelled" && steering) {
         inFlight.delete(uuid);
         steering.resolve();
@@ -1225,15 +1412,23 @@ export function createClaudeConversationTurn({ conversationId, onEvent = async (
         }
       }
       if (frame.subtype === "local_command_output" && frame.content) {
-        await publishMessage({ id: `claude_${frame.uuid}`, role: "commentary", text: frame.content, complete: true });
+        await publishMessage({ id: `claude_${frame.uuid}`, role: "commentary", text: frame.content, complete: true,
+          data: { native: { engineId: "claude", type: "system", subtype: "local_command_output" } } });
       }
+      const previousTaskCount = tasks.size;
       if (frame.subtype === "background_tasks_changed") {
         tasks.clear();
         for (const task of frame.tasks || []) if (task.task_id && !task.ambient) tasks.add(task.task_id);
       }
       if (frame.subtype === "task_started" && frame.task_id && !frame.ambient) tasks.add(frame.task_id);
       if (["task_notification", "task_updated"].includes(frame.subtype) &&
-          ["completed", "failed", "stopped", "killed"].includes(frame.status || frame.patch?.status)) tasks.delete(frame.task_id);
+          ["completed", "failed", "stopped", "killed"].includes(frame.status || frame.patch?.status)) {
+        tasks.delete(frame.task_id);
+      }
+      // Inventory removal can precede the task notification and the main model's
+      // response to it. A foreground result written while that worker was live
+      // cannot complete this follow-up or retire its admitted application tools.
+      if (tasks.size < previousTaskCount) outcome = null;
       if (["background_tasks_changed", "task_started", "task_notification", "task_updated"].includes(frame.subtype)) {
         if (tasks.size && turnId && !active && !cancelling) {
           generation++;
@@ -1249,7 +1444,7 @@ export function createClaudeConversationTurn({ conversationId, onEvent = async (
       if (event.type === "message_start") messageId = event.message?.id || frame.uuid;
       const id = `claude_${messageId}_${event.index}`;
       if (event.type === "content_block_start" && ["text", "thinking"].includes(event.content_block?.type)) {
-        messages.set(id, { id, outputId: id, complete: false, role: event.content_block.type === "thinking" ? "thinking" : "assistant",
+        messages.set(id, { id, outputId: id, userId: currentCommandId, complete: false, role: event.content_block.type === "thinking" ? "thinking" : "assistant",
           text: event.content_block.text || event.content_block.thinking || "" });
       } else if (event.type === "content_block_delta") {
         const block = messages.get(id);
@@ -1274,6 +1469,7 @@ export function createClaudeConversationTurn({ conversationId, onEvent = async (
         await flushAssistantMessages(apiMessageId, "commentary");
       }
       for (const block of claudeMessageBlocks(frame)) {
+        block.userId = currentCommandId;
         checkOutput(block.text, block.role);
         // Native split frames arrive before their block's stop event. Keep that
         // existing live identity without replacing the saved frame UUID.
@@ -1283,7 +1479,10 @@ export function createClaudeConversationTurn({ conversationId, onEvent = async (
             message.id.startsWith(prefix) && /^\d+$/u.test(message.id.slice(prefix.length)));
           if (live.length === 1 && (!Object.hasOwn(frame, "apiBlockIndex") ||
               Number.isSafeInteger(frame.apiBlockIndex) && frame.apiBlockIndex >= 0 &&
-              live[0].id === `${prefix}${frame.apiBlockIndex}`)) block.outputId = live[0].id;
+              live[0].id === `${prefix}${frame.apiBlockIndex}`)) {
+            block.outputId = live[0].id;
+            block.userId = live[0].userId || block.userId;
+          }
         }
         if (apiMessageId && block.role === "assistant") {
           const role = assistantRoles.get(apiMessageId);
@@ -1308,7 +1507,10 @@ export function createClaudeConversationTurn({ conversationId, onEvent = async (
       const message = failed ? (frame.errors || []).join("; ") || output || frame.subtype : "";
       result = failed ? "" : output;
       if (result && ![...messages.values()].some((block) => block.complete && block.role === "assistant" && block.text === result)) {
-        await publishMessage({ id: `claude_${frame.uuid || turnId}_result`, role: "assistant", text: result, complete: true });
+        await publishMessage({ id: `claude_${frame.uuid || turnId}_result`, role: "assistant", text: result, complete: true,
+          ...(typeof frame.local_command === "string" && frame.local_command ? {
+            data: { native: { engineId: "claude", type: "result", command: frame.local_command, output: "stdout" } }
+          } : {}) });
       }
       inFlight.delete(currentCommandId);
       if (steering) {
@@ -1320,7 +1522,7 @@ export function createClaudeConversationTurn({ conversationId, onEvent = async (
       await publish({ type: "diagnostic", stage: "native_result", status: outcome.status,
         terminalReason: frame.terminal_reason, active, pendingCommands: inFlight.size, backgroundTasks: tasks.size });
     }
-    if ((frame.type === "system" || frame.type === "result") &&
+    if ((frame.type === "system" || frame.type === "result" || frame.type === "command_lifecycle" && frame.state === "completed") &&
         active && !cancelling && outcome && inFlight.size === 0 && tasks.size === 0) {
       active = false;
       phase = "";
@@ -1348,6 +1550,18 @@ export function createClaudeConversationTurn({ conversationId, onEvent = async (
     admissions.clear();
     inFlight.clear();
     tasks.clear();
+    // Verified process cleanup can precede Claude's terminal generation frame.
+    // Retain already displayed text for the existing transcript reader, with
+    // its original input/output identity and no completed-answer receipt.
+    for (const pending of pendingAssistantMessages.values()) for (const block of pending) {
+      if (block.outputId && block.outputId !== block.id) messages.delete(block.outputId);
+      messages.set(block.id, { ...block, role: "commentary" });
+    }
+    for (const [id, block] of messages) {
+      if (block.complete === false && block.role === "assistant" && block.text) {
+        messages.set(id, { ...block, complete: true, role: "commentary" });
+      }
+    }
     pendingAssistantMessages.clear();
     assistantRoles.clear();
     steering?.reject(failure(reason));
@@ -1404,8 +1618,12 @@ export function createClaudeConversationTurn({ conversationId, onEvent = async (
       acceptedInput = null;
       clearFinalAssistantResult();
     },
-    async send(client, message, { messageId: uuid, accept, timeoutMs = 30_000 } = {}) {
-      if (!active || stopped || cancelling) throw failure("Claude has no active turn for this message.");
+    async send(client, message, { messageId: uuid, accept, timeoutMs = 30_000, sendNow = false } = {}) {
+      if (!active || stopped || cancelling) throw Object.assign(
+        failure("Claude has no active turn for this message.", !active && !stopped && !cancelling
+          ? "conversation_steer_turn_finished" : "assistant_claude_turn_failed"),
+        { delivery: "not-sent", ...(!active && !stopped && !cancelling ? { statusCode: 409 } : {}) }
+      );
       if (!uuid || typeof accept !== "function" || admissions.has(uuid)) throw new TypeError("A distinct message id and admission writer are required.");
       clearFinalAssistantResult();
       acceptedInput = null;
@@ -1421,7 +1639,7 @@ export function createClaudeConversationTurn({ conversationId, onEvent = async (
       )), timeoutMs);
       admissions.set(uuid, { ...admitted, accept, timer, receiptOwner });
       try {
-        await Promise.all([client.send(message, { messageId: uuid, sessionId: conversationId }), admitted.promise]);
+        await Promise.all([client.send(message, { messageId: uuid, sessionId: conversationId, ...(sendNow ? { sendNow: true } : {}) }), admitted.promise]);
       } catch (error) {
         if (inputOwner === receiptOwner) invalidateFinalAssistantResult();
         throw error;
@@ -1429,17 +1647,23 @@ export function createClaudeConversationTurn({ conversationId, onEvent = async (
         clearTimeout(timer);
       }
     },
-    async interruptGeneration(client, { timeoutMs = 30_000 } = {}) {
-      if (!active || steering || cancelling) throw failure("This Claude turn cannot accept steering now.");
-      // A completed main loop can still own background work. There is no
-      // generation left to interrupt or second terminal result to wait for.
-      if (outcome && inFlight.size === 0) {
+    async interruptGeneration(client, { timeoutMs = 30_000, sendNow = false } = {}) {
+      if (!active || steering || cancelling) {
+        const completed = !active && !steering && !stopped && !cancelling && outcome?.status === "completed";
+        throw Object.assign(failure("This Claude turn cannot accept steering now.", completed
+          ? "conversation_steer_turn_finished" : "assistant_claude_turn_failed"),
+        { delivery: "not-sent", ...(completed ? { statusCode: 409 } : {}) });
+      }
+      // Targeted Send now admits the new input before asking the native loop to
+      // make way; unlike plain Stop it preserves background agents. A completed
+      // main loop also has no further interruption result to wait for.
+      if (sendNow || outcome && inFlight.size === 0) {
         // The next input owns completion now. A task finishing during host
         // preparation must not settle this turn using the previous result.
         outcome = null;
         acceptedInput = null;
         clearFinalAssistantResult();
-        await publish({ type: "diagnostic", stage: "steering_background_only", backgroundTasks: tasks.size });
+        await publish({ type: "diagnostic", stage: sendNow ? "steering_send_now" : "steering_background_only", backgroundTasks: tasks.size });
         return;
       }
       // Streaming user input otherwise queues behind the entire running turn.
@@ -1454,7 +1678,10 @@ export function createClaudeConversationTurn({ conversationId, onEvent = async (
         await Promise.all([client.interrupt(), Promise.race([
           steering.promise,
           new Promise((_, reject) => {
-            timer = setTimeout(() => reject(failure("Claude did not confirm the interrupted generation.")), timeoutMs);
+            timer = setTimeout(() => reject(Object.assign(failure(
+              "Claude did not confirm the interrupted generation. This instruction was not sent; retry after reconnecting.",
+              "assistant_claude_interrupt_timeout"
+            ), { statusCode: 503 })), timeoutMs);
           })
         ])]);
         await publish({ type: "diagnostic", stage: "steering_confirmed", pendingCommands: inFlight.size, backgroundTasks: tasks.size });