@cjhyy/code-shell-core 0.7.1 → 0.8.0

package/dist/engine/turn-loop.js

@@ -4,9 +4,11 @@
  * Following Claude Code's po_() pattern:
  * pre_check → model_call → post_check → tool_exec → context_mgmt → hook_notify → next turn
  */
-import { initialTurnState, newTurnId } from "./turn-state.js";
+import { randomUUID } from "node:crypto";
+import { buildAgentDirectionMessage } from "../tool-system/builtin/agent-notifications.js";
+import { newTurnId } from "./turn-state.js";
 import { formatFriendlyError } from "./friendly-error.js";
-import { projectGoalJudgeToolResult, } from "../hooks/goal-stop-hook.js";
+import { buildGoalJudgeRuntimeContext } from "./goal-judge-context.js";
 import { wrapHookMessages } from "../hooks/inject.js";
 import { ContextLimitError } from "../exceptions.js";
 import { logger } from "../logging/logger.js";
@@ -18,9 +20,9 @@ import { isAbortError } from "../llm/client-base.js";
 import { crossedReactiveThreshold } from "./reactive-threshold.js";
 import { COMPLETE_GOAL_TOOL_NAME } from "../tool-system/builtin/complete-goal.js";
 import { CANCEL_GOAL_TOOL_NAME } from "../tool-system/builtin/cancel-goal.js";
-import { redactSensitiveToolResultsInMessages, toolResultForDisplay, toolResultTranscriptText, toolResultsForDisplay, } from "../tool-system/tool-result-redaction.js";
-import { addTokenUsage, cacheHitRateFromUsage, cumulativeCacheHitRate, } from "./session-usage.js";
-import { createGoalBudgetTracker, recordGoalUsage, goalBudgetTerminationReason, applyGoalExtension, limitProximity, GOAL_DEFAULT_MAX_STOP_BLOCKS, } from "./goal.js";
+import { redactSensitiveToolResultsInMessages, SENSITIVE_TOOL_RESULT_PLACEHOLDER, toolResultForDisplay, toolResultTranscriptText, toolResultsForDisplay, } from "../tool-system/tool-result-redaction.js";
+import { addTokenUsage, cacheHitRateFromUsage, cumulativeCacheHitRate, } from "../session/usage.js";
+import { createGoalBudgetTracker, recordGoalUsage, goalBudgetTerminationReason, applyGoalExtension, limitProximity, isSameGoalVersion, normalizeGoal, GOAL_DEFAULT_MAX_STOP_BLOCKS, } from "../goal/lifecycle.js";
 /**
  * 把一个 ToolResult 映射成发给 LLM 的 tool_result ContentBlock。
  * 有 contentBlocks(view_image 的图片块)就原样用作 content;否则
@@ -87,6 +89,57 @@ export class TurnLoop {
      * being re-emitted every turn while still within the approach threshold.
      */
     approachAnnounced = false;
+    /** Latest coalesced Goal edit/resume reminder, consumed at a safe point. */
+    pendingGoalControlMessage = null;
+    /** Pause/delete requested while a Goal run is in flight. The current
+     * model/tool step is allowed to settle, then the loop stops before starting
+     * another model request. */
+    goalControlStopRequested = false;
+    /** Auxiliary tool-summary calls started by this loop and revoked by Goal pause/delete. */
+    activeToolSummaryControllers = new Set();
+    /**
+     * Apply a user goal edit/pause/resume to the live loop. Passing undefined
+     * pauses goal-driving at the next step boundary; a goal value resumes it.
+     * Usage accumulated before an edit is retained, while a pause/resume starts
+     * a fresh run-scoped budget window (matching a later persisted resume).
+     */
+    updateGoal(goal, controlMessage, limits) {
+        const normalized = normalizeGoal(goal);
+        if (!normalized) {
+            this.config = { ...this.config, goal: undefined };
+            this.goalTracker = null;
+            this.pendingGoalControlMessage = null;
+            this.goalControlStopRequested = true;
+            for (const controller of this.activeToolSummaryControllers)
+                controller.abort();
+            this.activeToolSummaryControllers.clear();
+            this.stopBlockCount = 0;
+            this.approachAnnounced = false;
+            return;
+        }
+        const next = { ...normalized, goalId: normalized.goalId ?? randomUUID() };
+        const wasPaused = !this.config.goal;
+        this.config = {
+            ...this.config,
+            goal: next,
+            ...(typeof limits?.maxTurns === "number" && limits.maxTurns > 0
+                ? { maxTurns: Math.max(this.config.maxTurns, Math.floor(limits.maxTurns)) }
+                : {}),
+            ...(typeof limits?.maxStopBlocks === "number" && limits.maxStopBlocks > 0
+                ? { maxStopBlocks: Math.floor(limits.maxStopBlocks) }
+                : {}),
+        };
+        this.goalControlStopRequested = false;
+        this.pendingGoalControlMessage = controlMessage?.trim()
+            ? { goalId: next.goalId, revision: next.revision, text: controlMessage.trim() }
+            : null;
+        if (this.goalTracker && !wasPaused)
+            this.goalTracker.goal = next;
+        else
+            this.goalTracker = createGoalBudgetTracker(next, Date.now());
+        this.stopBlockCount = 0;
+        this.approachAnnounced = false;
+    }
     /**
      * Extend the in-flight run's limits (TODO 3.1 — 运行中续轮/加预算). Mutates
      * the maxTurns ceiling, the maxStopBlocks cap, and/or the live goal budgets;
@@ -163,6 +216,8 @@ export class TurnLoop {
         this.approachAnnounced = true;
         this.config.onStream?.({
             type: "goal_progress",
+            goalId: this.config.goal.goalId,
+            revision: this.config.goal.revision,
             status: "approaching_limit",
             round: this.stopBlockCount,
             turnsRemaining: prox.turnsRemaining,
@@ -177,6 +232,16 @@ export class TurnLoop {
     config) {
         this.deps = deps;
         this.config = config;
+        const normalizedGoal = normalizeGoal(this.config.goal);
+        if (normalizedGoal) {
+            this.config = {
+                ...this.config,
+                goal: { ...normalizedGoal, goalId: normalizedGoal.goalId ?? randomUUID() },
+            };
+        }
+        else if (this.config.goal !== undefined) {
+            this.config = { ...this.config, goal: undefined };
+        }
         for (const msg of this.config.freshImageMessages ?? []) {
             this.pendingImageMessages.add(msg);
         }
@@ -359,10 +424,17 @@ export class TurnLoop {
             promptTokensConfidence: overhead > 0 ? "medium" : "low",
         });
     }
-    recordResponseUsage(usage) {
+    recordResponseUsage(usage, requestKind = "primary", recordCacheDiagnostics = true) {
         this.currentTurnUsage = addTokenUsage(this.currentTurnUsage, usage);
+        this.deps.onAgentUsage?.(usage);
         this.currentCumulativeUsage = this.deps.recordCumulativeUsage?.(usage);
-        this.deps.recordCacheReadDiagnostics?.(usage);
+        if (recordCacheDiagnostics && this.deps.recordCacheReadDiagnostics) {
+            this.deps.recordCacheReadDiagnostics({
+                usage,
+                requestKind,
+                fingerprint: this.deps.model.getPromptPrefixFingerprint(this.deps.systemPrompt, this.deps.tools),
+            });
+        }
     }
     emitCtxFromUsage(usage, messages) {
         if (!this.config.onStream)
@@ -429,16 +501,18 @@ export class TurnLoop {
      */
     async run(initialMessages) {
         const result = await this.runUnredacted(initialMessages);
-        return { ...result, messages: this.redactConsumedSensitiveToolResults(result.messages) };
+        return {
+            ...result,
+            ...(result.reason === "completed" && this.goalControlStopRequested
+                ? { completionKind: "goal_control_stop" }
+                : {}),
+            messages: this.redactConsumedSensitiveToolResults(result.messages),
+        };
     }
     async runUnredacted(initialMessages) {
         let messages = [...initialMessages];
         let finalText = "";
         const budgetTracker = createBudgetTracker();
-        // Recent execution evidence for the built-in Goal judge. Values enter this
-        // window only after irreversible sensitive-data removal, non-text omission,
-        // and per-item truncation at the current-round ToolResult boundary.
-        const goalToolResults = [];
         const sensitiveGoalResultTools = this.config.goal
             ? new Set(this.deps.tools.filter((tool) => tool.sensitiveResult).map((tool) => tool.name))
             : undefined;
@@ -449,7 +523,6 @@ export class TurnLoop {
         if (!this.goalTracker && this.config.goal) {
             this.goalTracker = createGoalBudgetTracker(this.config.goal, Date.now());
         }
-        const goalTracker = this.goalTracker;
         // Fresh run: re-arm the approaching-limit announcement.
         this.approachAnnounced = false;
         // run() must never reject: the engine's post-run bookkeeping (saveState
@@ -461,8 +534,12 @@ export class TurnLoop {
         // hook emits, guards) and surfaces them as a model_error result.
         try {
             while (this.turnCount < this.config.maxTurns) {
-                const preTurnGoalTermination = goalTracker
-                    ? goalBudgetTerminationReason(goalTracker, Date.now())
+                if (this.goalControlStopRequested) {
+                    messages = this.redactConsumedSensitiveToolResults(messages);
+                    return { text: finalText, reason: "completed", messages };
+                }
+                const preTurnGoalTermination = this.goalTracker
+                    ? goalBudgetTerminationReason(this.goalTracker, Date.now())
                     : undefined;
                 if (preTurnGoalTermination) {
                     this.config.onStream?.({
@@ -478,6 +555,7 @@ export class TurnLoop {
                         reason: "goal_budget_exhausted",
                         messages,
                         goalTermination: preTurnGoalTermination,
+                        goalTerminationRound: this.stopBlockCount,
                     };
                 }
                 this.turnCount++;
@@ -507,8 +585,18 @@ export class TurnLoop {
                 // they join THIS step's request — no abort, no lost in-flight work. Same
                 // loop-top user-push pattern as turnStartInjection / turn-limit warnings
                 // below. Push to transcript too so they persist + survive resume.
+                // Bind self-reported Goal terminal tools to the revision that was
+                // actually visible when this model step began. An edit/pause/delete can
+                // arrive while context management, the model request, or its tool batch
+                // is in flight; a late complete_goal/cancel_goal from that old prompt
+                // must never terminate the newer revision.
+                const requestedGoalVersion = this.config.goal ? { ...this.config.goal } : undefined;
                 await this.consumeQueuedSteer(messages, "normal_step");
-                const state = initialTurnState(this.turnCount);
+                if (this.goalControlStopRequested) {
+                    messages = this.redactConsumedSensitiveToolResults(messages);
+                    return { text: finalText, reason: "completed", messages };
+                }
+                this.deps.onAgentControlState?.("model");
                 // Per-turn correlation ID. Every log written through `tlog` (or any
                 // child derived from it) is stamped with `turn` + `turnId`, so
                 // `jq 'select(.turnId == "...")'` reconstructs one turn's timeline.
@@ -523,11 +611,6 @@ export class TurnLoop {
                 tlog.info("turn.start", { cat: "turn", messageCount: messages.length });
                 // Tag downstream tool-exec / permission lines with this turn's IDs.
                 this.deps.toolExecutor.setLogger(tlog);
-                this.config.onStream?.({
-                    type: "stream_request_start",
-                    turnNumber: this.turnCount,
-                    messageId: assistantMessageId,
-                });
                 const turnStartHook = await this.emitHook("on_turn_start", {
                     turnNumber: this.turnCount,
                 });
@@ -535,6 +618,10 @@ export class TurnLoop {
                 if (turnStartInjection) {
                     messages.push(turnStartInjection);
                 }
+                if (this.goalControlStopRequested) {
+                    messages = this.redactConsumedSensitiveToolResults(messages);
+                    return { text: finalText, reason: "completed", messages };
+                }
                 // Approaching max turns: inject a warning so the model can wrap up.
                 // (Model-facing only — the user-facing "再续" marker is handled by
                 // maybeAnnounceApproachingLimit below, which also watches the stop-block
@@ -587,6 +674,10 @@ export class TurnLoop {
                         this.markStopped();
                         return { text: finalText, reason: "aborted_streaming", messages };
                     }
+                    if (this.goalControlStopRequested) {
+                        messages = this.redactConsumedSensitiveToolResults(messages);
+                        return { text: finalText, reason: "completed", messages };
+                    }
                 }
                 // No pre-llm ctx emit here: the messages-only estimate would be ~16k
                 // smaller than the real prompt (system + tools not included), making
@@ -614,8 +705,17 @@ export class TurnLoop {
                         messages.push(compactInjection);
                     }
                 }
+                if (this.goalControlStopRequested) {
+                    messages = this.redactConsumedSensitiveToolResults(messages);
+                    return { text: finalText, reason: "completed", messages };
+                }
                 messages = this.appendVolatileContextMessages(messages);
                 // Model call (with streaming fallback and max_output_tokens continuation)
+                this.config.onStream?.({
+                    type: "stream_request_start",
+                    turnNumber: this.turnCount,
+                    messageId: assistantMessageId,
+                });
                 // Track tool IDs streamed during this turn to avoid duplicate UI events
                 this.streamedToolIds.clear();
                 // Tool queue is created before the call, but enqueue happens only after
@@ -627,10 +727,18 @@ export class TurnLoop {
                 }
                 catch (err) {
                     if (err instanceof ContextLimitError) {
+                        if (this.goalControlStopRequested) {
+                            messages = this.redactConsumedSensitiveToolResults(messages);
+                            return { text: finalText, reason: "completed", messages };
+                        }
                         // Progressive recovery: drop oldest API rounds, up to 3 retries
                         const { dropOldestRounds } = await import("../context/compaction.js");
                         let recovered = false;
                         for (let retry = 1; retry <= 3; retry++) {
+                            if (this.goalControlStopRequested) {
+                                messages = this.redactConsumedSensitiveToolResults(messages);
+                                return { text: finalText, reason: "completed", messages };
+                            }
                             tlog.warn("turn.ptl_recovery", { cat: "turn", retry, roundsToDrop: retry });
                             messages = dropOldestRounds(messages, retry);
                             try {
@@ -685,12 +793,12 @@ export class TurnLoop {
                 }
                 // Charge every provider response to the run-scoped Goal budget before
                 // any truncation path can retry or continue the outer turn loop.
-                if (goalTracker && response.usage) {
+                if (this.goalTracker && response.usage) {
                     const used = (response.usage.promptTokens ?? 0) + (response.usage.completionTokens ?? 0);
-                    recordGoalUsage(goalTracker, used);
+                    recordGoalUsage(this.goalTracker, used);
                 }
-                let budgetTermination = goalTracker
-                    ? goalBudgetTerminationReason(goalTracker, Date.now())
+                let budgetTermination = this.goalTracker
+                    ? goalBudgetTerminationReason(this.goalTracker, Date.now())
                     : undefined;
                 // Feed actual token usage back to the context manager so subsequent
                 // compaction decisions use hybrid (actual + delta) estimation rather than
@@ -748,10 +856,10 @@ export class TurnLoop {
                         // Don't fire another continuation call if the user cancelled — without
                         // this an abort during a truncated response could still issue up to 3
                         // more model calls, emitting text after Stop.
-                        if (this.config.signal?.aborted)
+                        if (this.config.signal?.aborted || this.goalControlStopRequested)
                             break;
-                        budgetTermination = goalTracker
-                            ? goalBudgetTerminationReason(goalTracker, Date.now())
+                        budgetTermination = this.goalTracker
+                            ? goalBudgetTerminationReason(this.goalTracker, Date.now())
                             : undefined;
                         if (budgetTermination)
                             break;
@@ -772,16 +880,16 @@ export class TurnLoop {
                                 this.stopBlockCount = 0;
                             }
                             if (contResponse.usage?.promptTokens !== undefined) {
-                                this.recordResponseUsage(contResponse.usage);
+                                this.recordResponseUsage(contResponse.usage, "continuation");
                                 continuedResponse = true;
                             }
-                            if (goalTracker && contResponse.usage) {
+                            if (this.goalTracker && contResponse.usage) {
                                 const used = (contResponse.usage.promptTokens ?? 0) +
                                     (contResponse.usage.completionTokens ?? 0);
-                                recordGoalUsage(goalTracker, used);
+                                recordGoalUsage(this.goalTracker, used);
                             }
-                            budgetTermination = goalTracker
-                                ? goalBudgetTerminationReason(goalTracker, Date.now())
+                            budgetTermination = this.goalTracker
+                                ? goalBudgetTerminationReason(this.goalTracker, Date.now())
                                 : undefined;
                             combinedText += contResponse.text;
                             if (budgetTermination ||
@@ -821,13 +929,13 @@ export class TurnLoop {
                 // is force-stopped regardless of what the model wants to do next (stop OR
                 // continue with tool calls). This is the unattended-safety backstop, so
                 // it sits BEFORE the "tool calls?" branch — both paths pass the gate.
-                budgetTermination = goalTracker
-                    ? (budgetTermination ?? goalBudgetTerminationReason(goalTracker, Date.now()))
+                budgetTermination = this.goalTracker
+                    ? (budgetTermination ?? goalBudgetTerminationReason(this.goalTracker, Date.now()))
                     : undefined;
-                if (goalTracker && budgetTermination) {
+                if (this.goalTracker && budgetTermination) {
                     tlog.info("turn.goal_budget_exhausted", {
                         cat: "goal",
-                        tokensUsed: goalTracker.tokensUsed,
+                        tokensUsed: this.goalTracker.tokensUsed,
                         tokenBudget: this.config.goal?.tokenBudget,
                         timeBudgetMs: this.config.goal?.timeBudgetMs,
                     });
@@ -845,6 +953,7 @@ export class TurnLoop {
                         reason: "goal_budget_exhausted",
                         messages,
                         goalTermination: budgetTermination,
+                        goalTerminationRound: this.stopBlockCount,
                     };
                 }
                 // Post-check: tool calls?
@@ -864,28 +973,31 @@ export class TurnLoop {
                     if (await this.consumeQueuedSteer(messages, "finalize_backfill")) {
                         continue;
                     }
+                    // A steer accepted while an async tool was launching must be
+                    // answered before parking the run. Keep the tool's yield request
+                    // pending across that extra model round, then park once the model
+                    // has replied and there is still no background result to consume.
+                    if (this.deps.consumeToolRunYield?.() === "background_notification") {
+                        tlog.info("turn.background_notification_wait_after_steer", { cat: "turn" });
+                        messages = this.redactConsumedSensitiveToolResults(messages);
+                        return {
+                            text: finalText,
+                            reason: "completed",
+                            messages,
+                            completionKind: "background_wait",
+                        };
+                    }
                     // on_stop seam: the model wants to stop. Give handlers (Goal mode)
                     // a chance to BLOCK termination and keep the agent working. A
                     // handler returning continueSession=true injects its messages and
                     // we run another turn instead of returning. Bounded by
                     // maxStopBlocks (consecutive) and the outer maxTurns ceiling.
                     const maxStopBlocks = this.config.maxStopBlocks ?? GOAL_DEFAULT_MAX_STOP_BLOCKS;
-                    if (goalTracker) {
-                        this.deps.updateGoalJudgeContext?.({
-                            toolResults: goalToolResults.map((item) => ({
-                                ...item,
-                            })),
-                            progress: {
-                                turnCount: this.turnCount,
-                                stopRound: this.stopBlockCount + 1,
-                                elapsedMs: Math.max(0, Date.now() - goalTracker.startedAtMs),
-                                tokensUsed: goalTracker.tokensUsed,
-                                tokenBudget: goalTracker.goal.tokenBudget,
-                                timeBudgetMs: goalTracker.goal.timeBudgetMs,
-                                maxTurns: this.config.maxTurns,
-                                maxStopBlocks,
-                            },
-                        });
+                    if (this.goalTracker) {
+                        const judgeMessages = this.stripVolatileContextMessages(messages);
+                        this.deps.publishGoalJudgeContext?.(buildGoalJudgeRuntimeContext(judgeMessages, {
+                            sensitiveToolResultRedactions: this.sensitiveToolResultRedactions,
+                        }));
                     }
                     const stopHook = await this.emitHook("on_stop", {
                         goal: this.config.goal,
@@ -900,16 +1012,16 @@ export class TurnLoop {
                         hookGoalTermination === "time_budget_exhausted"
                         ? hookGoalTermination
                         : undefined;
-                    const postJudgeBudgetTermination = goalTracker
-                        ? (hookBudgetTermination ?? goalBudgetTerminationReason(goalTracker, Date.now()))
+                    const postJudgeBudgetTermination = this.goalTracker
+                        ? (hookBudgetTermination ?? goalBudgetTerminationReason(this.goalTracker, Date.now()))
                         : undefined;
-                    if (goalTracker && postJudgeBudgetTermination) {
+                    if (this.goalTracker && postJudgeBudgetTermination) {
                         tlog.info("turn.goal_budget_exhausted_after_judge", {
                             cat: "goal",
                             reason: postJudgeBudgetTermination,
-                            tokensUsed: goalTracker.tokensUsed,
-                            tokenBudget: goalTracker.goal.tokenBudget,
-                            timeBudgetMs: goalTracker.goal.timeBudgetMs,
+                            tokensUsed: this.goalTracker.tokensUsed,
+                            tokenBudget: this.goalTracker.goal.tokenBudget,
+                            timeBudgetMs: this.goalTracker.goal.timeBudgetMs,
                         });
                         this.config.onStream?.({
                             type: "assistant_message",
@@ -924,9 +1036,10 @@ export class TurnLoop {
                             reason: "goal_budget_exhausted",
                             messages,
                             goalTermination: postJudgeBudgetTermination,
+                            goalTerminationRound: this.stopBlockCount,
                         };
                     }
-                    if (goalTracker && hookGoalTermination === "judge_prompt_too_large") {
+                    if (this.goalTracker && hookGoalTermination === "judge_prompt_too_large") {
                         tlog.warn("turn.goal_judge_prompt_too_large", { cat: "goal" });
                         this.config.onStream?.({
                             type: "assistant_message",
@@ -953,6 +1066,8 @@ export class TurnLoop {
                         // up with stopBlockCount so the UI can show "第 N 轮".
                         this.config.onStream?.({
                             type: "goal_progress",
+                            goalId: this.config.goal?.goalId,
+                            revision: this.config.goal?.revision,
                             status: "not_met",
                             round: this.stopBlockCount,
                             gaps: goalVerdict?.gaps || undefined,
@@ -991,11 +1106,6 @@ export class TurnLoop {
                             stopBlockCount: this.stopBlockCount,
                             maxStopBlocks,
                         });
-                        this.config.onStream?.({
-                            type: "goal_progress",
-                            status: "exhausted",
-                            round: this.stopBlockCount,
-                        });
                         goalTermination = "stop_blocks_exhausted";
                         this.config.onStream?.({
                             type: "assistant_message",
@@ -1011,18 +1121,28 @@ export class TurnLoop {
                         // rounds = prior blocks + this accepted final round.
                         this.config.onStream?.({
                             type: "goal_progress",
+                            goalId: this.config.goal.goalId,
+                            revision: this.config.goal.revision,
                             status: "met",
                             round: this.stopBlockCount + 1,
                         });
                     }
+                    const goalTerminationRound = goalTermination ? this.stopBlockCount : undefined;
                     this.stopBlockCount = 0;
                     if (await this.consumeQueuedSteer(messages, "finalize_backfill")) {
                         continue;
                     }
                     messages = this.redactConsumedSensitiveToolResults(messages);
-                    return { text: finalText, reason: "completed", messages, goalTermination };
+                    return {
+                        text: finalText,
+                        reason: "completed",
+                        messages,
+                        goalTermination,
+                        goalTerminationRound,
+                    };
                 }
                 // Tool execution phase
+                this.deps.onAgentControlState?.("tool-batch");
                 tlog.info("turn.tool_use", {
                     cat: "turn",
                     tools: response.toolCalls.map((t) => t.toolName),
@@ -1063,20 +1183,13 @@ export class TurnLoop {
                 // Record results in transcript and stream
                 const resultBlocks = [];
                 for (const result of results) {
-                    if (goalTracker) {
-                        goalToolResults.push(projectGoalJudgeToolResult(result, this.turnCount, sensitiveGoalResultTools?.has(result.toolName) === true));
-                        // Never evict the front of one legal batch: the default executor may
-                        // return 25 results in a turn. Keep at least maxToolCallsPerTurn so
-                        // the judge renderer can preserve metadata for the entire newest batch.
-                        const residencyLimit = Math.max(20, this.config.maxToolCallsPerTurn);
-                        if (goalToolResults.length > residencyLimit) {
-                            goalToolResults.splice(0, goalToolResults.length - residencyLimit);
-                        }
-                    }
                     resultBlocks.push(toolResultToBlock(result));
                     const streamResult = toolResultForDisplay(result);
-                    const transcriptResult = toolResultTranscriptText(result);
-                    if (result.sensitive && transcriptResult !== undefined) {
+                    const sensitiveByMetadata = sensitiveGoalResultTools?.has(result.toolName) === true;
+                    const transcriptResult = sensitiveByMetadata
+                        ? SENSITIVE_TOOL_RESULT_PLACEHOLDER
+                        : toolResultTranscriptText(result);
+                    if ((result.sensitive || sensitiveByMetadata) && transcriptResult !== undefined) {
                         this.sensitiveToolResultRedactions.set(result.id, transcriptResult);
                     }
                     this.deps.transcript.appendToolResult(result.id, result.toolName, transcriptResult, result.error, result.sensitive ? undefined : result.contentBlocks);
@@ -1086,13 +1199,15 @@ export class TurnLoop {
                 // best-effort observability — a thrown onStream handler, a failed dynamic
                 // import, or a rejecting summarize must never surface as an unhandled
                 // rejection (Node can treat those as fatal). Swallow at the tail. (B-2)
-                if (this.config.onStream) {
+                if (this.config.onStream && this.deps.model.summarize && !this.goalControlStopRequested) {
+                    const summaryController = new AbortController();
+                    this.activeToolSummaryControllers.add(summaryController);
                     void import("./tool-summary.js")
                         .then(({ generateToolUseSummary }) => {
-                        if (!this.deps.model.summarize)
+                        if (this.goalControlStopRequested || summaryController.signal.aborted)
                             return;
-                        return generateToolUseSummary(toolCalls, toolResultsForDisplay(results), this.deps.model.summarize).then((summary) => {
-                            if (summary) {
+                        return generateToolUseSummary(toolCalls, toolResultsForDisplay(results), this.deps.model.summarize, summaryController.signal).then((summary) => {
+                            if (summary && !summaryController.signal.aborted) {
                                 this.config.onStream?.({
                                     type: "tool_summary",
                                     summary,
@@ -1106,6 +1221,9 @@ export class TurnLoop {
                             cat: "turn",
                             error: err.message,
                         });
+                    })
+                        .finally(() => {
+                        this.activeToolSummaryControllers.delete(summaryController);
                     });
                 }
                 const toolResultMessage = { role: "user", content: resultBlocks };
@@ -1136,6 +1254,31 @@ export class TurnLoop {
                 // Tool results just pushed; recompute ctx so the bar updates *before*
                 // the next model round-trip — large tool outputs can move it sharply.
                 this.emitCtxFromMessages(messages);
+                // A trusted tool launched asynchronous work whose completion is routed
+                // back into this Session. End this run at the tool boundary instead of
+                // asking the model for another step with no new evidence; the queued
+                // completion notification will wake the Session and continue normally.
+                // This precedes complete_goal so a single batch cannot launch unfinished
+                // background work and simultaneously claim the enclosing Goal is done.
+                if (this.deps.peekToolRunYield?.() === "background_notification") {
+                    // Close the current model turn before a queued steer re-drives it;
+                    // interrupt-and-redrive swaps the turn signal at this boundary.
+                    this.finalizeModelTurn();
+                    if (await this.consumeQueuedSteer(messages, "finalize_backfill")) {
+                        continue;
+                    }
+                }
+                if (this.deps.peekToolRunYield?.() === "background_notification" &&
+                    this.deps.consumeToolRunYield?.() === "background_notification") {
+                    tlog.info("turn.background_notification_wait", { cat: "turn" });
+                    messages = this.redactConsumedSensitiveToolResults(messages);
+                    return {
+                        text: finalText,
+                        reason: "completed",
+                        messages,
+                        completionKind: "background_wait",
+                    };
+                }
                 // Goal mode P0: explicit completion. If the model called complete_goal,
                 // it has DECLARED the goal done — short-circuit to "completed" WITHOUT
                 // running the judge hook. The tool's result is already in `messages`
@@ -1145,16 +1288,33 @@ export class TurnLoop {
                 // the model just declared finished (the judge's onMet does this when IT
                 // decides; a self-report must do the same, else the goal outlives its
                 // completion and re-arms every follow-up turn).
-                if (goalTracker && toolCalls.some((tc) => tc.toolName === COMPLETE_GOAL_TOOL_NAME)) {
-                    tlog.info("turn.goal_self_reported_complete", { cat: "goal" });
-                    this.stopBlockCount = 0;
-                    this.deps.clearPersistedGoal?.();
-                    this.finalizeModelTurn();
-                    if (await this.consumeQueuedSteer(messages, "finalize_backfill")) {
-                        continue;
+                const completeGoalRequested = !!this.goalTracker &&
+                    isSameGoalVersion(requestedGoalVersion, this.config.goal) &&
+                    toolCalls.some((tc) => tc.toolName === COMPLETE_GOAL_TOOL_NAME);
+                if (completeGoalRequested) {
+                    const persisted = this.deps.clearPersistedGoal?.("completed") !== false;
+                    if (persisted) {
+                        tlog.info("turn.goal_self_reported_complete", { cat: "goal" });
+                        this.config.onStream?.({
+                            type: "goal_progress",
+                            goalId: this.config.goal?.goalId,
+                            revision: this.config.goal?.revision,
+                            status: "met",
+                            round: this.stopBlockCount + 1,
+                        });
+                        this.stopBlockCount = 0;
+                        this.finalizeModelTurn();
+                        if (await this.consumeQueuedSteer(messages, "finalize_backfill")) {
+                            continue;
+                        }
+                        messages = this.redactConsumedSensitiveToolResults(messages);
+                        return { text: finalText, reason: "completed", messages };
                     }
-                    messages = this.redactConsumedSensitiveToolResults(messages);
-                    return { text: finalText, reason: "completed", messages };
+                    tlog.warn("turn.goal_self_reported_complete_persist_failed", { cat: "goal" });
+                    messages.push({
+                        role: "user",
+                        content: "<system-reminder>complete_goal 未能持久化完成状态；目标仍处于活动状态。请不要宣称已经结束，并在会话状态恢复可写后重试。</system-reminder>",
+                    });
                 }
                 // Goal mode: user-initiated cancellation. cancel_goal is the "strong
                 // intent" escape hatch — honor it ONLY when confirm===true (the guard the
@@ -1162,15 +1322,35 @@ export class TurnLoop {
                 // persisted goal so it never re-arms; an unconfirmed call is a no-op here
                 // (the tool's own result string already told the model it was ignored).
                 const confirmedCancel = toolCalls.some((tc) => tc.toolName === CANCEL_GOAL_TOOL_NAME && tc.args?.confirm === true);
-                if (goalTracker && confirmedCancel) {
-                    tlog.info("turn.goal_user_cancelled", { cat: "goal" });
-                    this.stopBlockCount = 0;
-                    this.deps.clearPersistedGoal?.();
-                    this.finalizeModelTurn();
-                    if (await this.consumeQueuedSteer(messages, "finalize_backfill")) {
-                        continue;
+                if (this.goalTracker &&
+                    isSameGoalVersion(requestedGoalVersion, this.config.goal) &&
+                    confirmedCancel &&
+                    !completeGoalRequested) {
+                    const persisted = this.deps.clearPersistedGoal?.("cancelled") !== false;
+                    if (persisted) {
+                        tlog.info("turn.goal_user_cancelled", { cat: "goal" });
+                        this.stopBlockCount = 0;
+                        this.config.onStream?.({
+                            type: "goal_cleared",
+                            goalId: this.config.goal?.goalId,
+                            revision: this.config.goal?.revision,
+                        });
+                        this.finalizeModelTurn();
+                        if (await this.consumeQueuedSteer(messages, "finalize_backfill")) {
+                            continue;
+                        }
+                        return {
+                            text: finalText,
+                            reason: "completed",
+                            messages,
+                            completionKind: "goal_control_stop",
+                        };
                     }
-                    return { text: finalText, reason: "completed", messages };
+                    tlog.warn("turn.goal_user_cancelled_persist_failed", { cat: "goal" });
+                    messages.push({
+                        role: "user",
+                        content: "<system-reminder>cancel_goal 未能持久化删除状态；目标仍处于活动状态。请在会话状态恢复可写后重试。</system-reminder>",
+                    });
                 }
                 // Token budget check
                 const totalOutputTokens = this.deps.model.getOutputTokens?.() ?? 0;
@@ -1192,7 +1372,12 @@ export class TurnLoop {
                         continue;
                     }
                     messages = this.redactConsumedSensitiveToolResults(messages);
-                    return { text: finalText, reason: "completed", messages };
+                    return {
+                        text: finalText,
+                        reason: "completed",
+                        messages,
+                        completionKind: "limit_stop",
+                    };
                 }
                 if (budgetDecision === "nudge") {
                     messages.push({
@@ -1265,6 +1450,12 @@ export class TurnLoop {
             messages = this.redactConsumedSensitiveToolResults(messages);
             return { text: finalText, reason: "model_error", messages };
         }
+        // Pause/delete may have landed while the final allowed tool batch was
+        // draining. Do not cross that safe boundary into an extra summary request.
+        if (this.goalControlStopRequested) {
+            messages = this.redactConsumedSensitiveToolResults(messages);
+            return { text: finalText, reason: "completed", messages };
+        }
         // Max turns reached — do one final summarization call (no tools)
         logger.warn("turn.max_turns_reached", {
             cat: "turn",
@@ -1272,6 +1463,11 @@ export class TurnLoop {
             turnCount: this.turnCount,
         });
         await this.consumeQueuedSteer(messages, "finalize_backfill");
+        if (this.goalControlStopRequested) {
+            messages = this.redactConsumedSensitiveToolResults(messages);
+            return { text: finalText, reason: "completed", messages };
+        }
+        this.deps.onAgentControlState?.("model");
         const hasPendingSensitiveToolResults = this.sensitiveToolResultRedactions.size > 0;
         messages = this.prepareMessagesForModel(messages);
         if (hasPendingSensitiveToolResults) {
@@ -1284,19 +1480,27 @@ export class TurnLoop {
         else {
             messages = this.deps.contextManager.manage(messages);
         }
+        if (this.goalControlStopRequested) {
+            messages = this.redactConsumedSensitiveToolResults(messages);
+            return { text: finalText, reason: "completed", messages };
+        }
         messages.push({
             role: "user",
             content: "<system-reminder>Turn limit reached. Provide a final summary of what you accomplished and what remains to be done. Do NOT call any tools.</system-reminder>",
         });
         this.emitCtxFromMessages(messages);
         try {
+            if (this.goalControlStopRequested) {
+                messages = this.redactConsumedSensitiveToolResults(messages);
+                return { text: finalText, reason: "completed", messages };
+            }
             const summaryResponse = await this.deps.model.call(this.deps.systemPrompt, this.prepareMessagesForModel(messages), [], // No tools available for summary turn
             this.config.onStream, this.config.signal, this.modelCallRecordingOptions());
             if (summaryResponse.usage?.promptTokens !== undefined) {
-                this.recordResponseUsage(summaryResponse.usage);
+                this.recordResponseUsage(summaryResponse.usage, "primary", false);
             }
-            if (goalTracker && summaryResponse.usage) {
-                recordGoalUsage(goalTracker, (summaryResponse.usage.promptTokens ?? 0) + (summaryResponse.usage.completionTokens ?? 0));
+            if (this.goalTracker && summaryResponse.usage) {
+                recordGoalUsage(this.goalTracker, (summaryResponse.usage.promptTokens ?? 0) + (summaryResponse.usage.completionTokens ?? 0));
             }
             if (this.config.signal?.aborted) {
                 this.markStopped();
@@ -1330,6 +1534,7 @@ export class TurnLoop {
             reason: "max_turns",
             messages,
             ...(this.config.goal ? { goalTermination: "max_turns_exhausted" } : {}),
+            ...(this.config.goal ? { goalTerminationRound: this.stopBlockCount } : {}),
         };
     }
     /**
@@ -1388,6 +1593,14 @@ export class TurnLoop {
             // really just a cancel. The signal is the authoritative cancel source.
             if (isAbortError(err) || this.config.signal?.aborted)
                 throw err;
+            // Pause/delete arrived while the streaming attempt was in flight. A
+            // non-streaming fallback would be a brand-new provider request after the
+            // promised safe boundary, so revoke any partial stream and synthesize an
+            // empty settled step instead.
+            if (this.goalControlStopRequested) {
+                this.config.onStream?.({ type: "tombstone", messageId: assistantMessageId });
+                return { text: "", toolCalls: [], stopReason: "stop" };
+            }
             // Sensitive tool results are model-facing exactly once. A streaming
             // fallback would re-send the same pending plaintext in a second request,
             // so fail the turn and let the unified exit redact returned history.
@@ -1413,8 +1626,25 @@ export class TurnLoop {
         return this.turnCount;
     }
     async consumeQueuedSteer(messages, source) {
-        const steered = this.deps.consumeSteer?.(source) ?? [];
         let consumed = false;
+        const goalControl = this.pendingGoalControlMessage;
+        this.pendingGoalControlMessage = null;
+        if (goalControl &&
+            this.config.goal?.paused !== true &&
+            this.config.goal?.goalId === goalControl.goalId &&
+            (this.config.goal?.revision ?? 1) === (goalControl.revision ?? 1)) {
+            const content = `<system-reminder>\n${goalControl.text}\n</system-reminder>`;
+            const message = { role: "user", content };
+            messages.push(message);
+            this.deps.transcript.appendMessage("user", content, {
+                injected: true,
+                source: "goal-control",
+            });
+            consumed = true;
+        }
+        const directionConsumed = await this.consumeQueuedAgentDirections(messages, source);
+        const steered = this.deps.consumeSteer?.(source) ?? [];
+        consumed ||= directionConsumed;
         for (let index = 0; index < steered.length; index++) {
             const item = steered[index];
             const { id, text, clientMessageId } = item;
@@ -1460,6 +1690,42 @@ export class TurnLoop {
         }
         return consumed;
     }
+    async consumeQueuedAgentDirections(messages, source) {
+        if (!this.deps.consumeAgentDirections)
+            return false;
+        this.deps.onAgentControlState?.("safe-point");
+        const directions = this.deps.consumeAgentDirections();
+        if (directions.length === 0)
+            return false;
+        directions.sort((left, right) => left.sequence - right.sequence);
+        const content = buildAgentDirectionMessage(directions);
+        const envelopeIds = directions.map((item) => item.id);
+        const correlationIds = directions
+            .map((item) => item.correlationId)
+            .filter((value) => value !== undefined);
+        const hook = await this.emitHook("agent_direction_submit", {
+            source: "agent-direction",
+            authority: "agent",
+            prompt: directions.map((item) => item.payload.prompt).join("\n"),
+            envelopeIds,
+            correlationIds,
+            safePoint: source,
+        });
+        const message = { role: "user", content };
+        messages.push(message);
+        this.deps.transcript.appendMessage("user", content, {
+            injected: true,
+            authority: "agent",
+            source: "agent-direction",
+            envelopeIds,
+            correlationIds,
+        });
+        this.deps.onAgentDirectionsDelivered?.(envelopeIds);
+        const hookInjection = wrapHookMessages(hook.messages);
+        if (hookInjection)
+            messages.push(hookInjection);
+        return true;
+    }
     /**
      * Generate synthetic error tool_results for any dangling tool_use blocks
      * that never received results (e.g. because the API call failed).