@zergai/ztc 0.2.7-dev.36236183737 → 0.3.1-dev.36465749722

package/dist/App.js

@@ -527,7 +527,21 @@ export const App = () => {
                 return;
             try {
                 streamedResponse.current = false;
-                const result = await runAgent.run(requestMessages, signal);
+                const priorIds = new Set(requestMessages.map(message => message.id));
+                const stopCheckpoints = runAgent.on(event => {
+                    if (event.type !== 'history_checkpoint')
+                        return;
+                    const ordered = event.messages;
+                    setMessages(prev => [...prev.filter(message => priorIds.has(message.id)), ...ordered,
+                        ...prev.filter(message => !priorIds.has(message.id) && (message.role === 'system' || message.role === 'tool'))]);
+                });
+                let result;
+                try {
+                    result = await runAgent.run(requestMessages, signal);
+                }
+                finally {
+                    stopCheckpoints();
+                }
                 if (isActive && !isActive())
                     return;
                 if (!streamedResponse.current) {
@@ -539,7 +553,7 @@ export const App = () => {
                         addMessage({
                             role: 'assistant',
                             content: result.content,
-                            toolCalls: result.toolCalls.length > 0 ? result.toolCalls : undefined,
+                            toolCalls: result.turnMessages?.length ? undefined : result.toolCalls.length > 0 ? result.toolCalls : undefined,
                             // Keep the provider's reasoning trace alongside usage: reasoning
                             // models expect the assistant message replayed with its
                             // reasoning_content, and dropping it here strips every later turn.

package/dist/agent/agent.d.ts

@@ -2,6 +2,8 @@ import { Message, ToolCall, AgentEvent } from '../types.js';
 import { AgentBackend, BackendRequest, TokenUsage } from './backends/index.js';
 import type { ClientToolCallResult } from './backends/types.js';
 import type { ApiRetrySettings } from '../config/types.js';
+import { type ExecutionSettings } from '../config/execution.js';
+import { type ExecutionContext } from './runtime/execution_context.js';
 import { Policy } from './runtime/policy.js';
 import { Tracer } from './runtime/tracing.js';
 import type { Tool } from './tools/types.js';
@@ -26,6 +28,14 @@ export interface AgentConfig {
         allow_fallbacks: boolean;
     };
     maxIterations?: number;
+    execution?: ExecutionSettings;
+    sessionId?: string;
+    runtimeFacts?: {
+        mode?: string;
+        mux?: boolean;
+        configScope?: string;
+        outputLimitSource?: string;
+    };
     /**
      * Retry/timeout policy for LLM requests. Renderer hosts normally leave this
      * undefined so the config-file setting applies; an explicit value wins.
@@ -54,8 +64,10 @@ export interface AgentConfig {
      */
     maxConsecutiveAutoContinues?: number;
     /**
-     * Pin the first real user message into request.system for long single-task
-     * sessions. Defaults to true. Hosted multi-turn chat should set false.
+     * Local task sessions: append current execution facts and any explicitly
+     * pinned goal to request.system. User messages are never automatically
+     * pinned. Hosted multi-turn chat should set false, which leaves
+     * request.system exactly as configured.
      */
     pinTaskHeader?: boolean;
     /**
@@ -105,7 +117,7 @@ export interface AgentRunResult {
     usage?: TokenUsage;
     stopReason: 'complete' | 'interactive' | 'max_iterations';
     reasoning?: string;
-    /** Ordered model-facing messages produced during a turn that accepted steering. */
+    /** Ordered model-facing messages produced during every turn. */
     turnMessages?: Message[];
 }
 export interface HarnessToolCallResult {
@@ -240,11 +252,9 @@ export declare class Agent {
      */
     private _taskHeader;
     /**
-     * Drop the pinned task so the NEXT conversation re-captures its own first user
-     * message. Wired into the /clear-only path (clearTransientState), never into
+     * Drop the explicitly pinned task for the next conversation. Wired into the /clear-only path (clearTransientState), never into
      * /compact — the pin must survive compaction (that is the whole point of R7).
-     * Null (not '') so systemWithTaskHeader recaptures rather than treating it as
-     * "no task found."
+     * Null represents no explicitly pinned goal.
      */
     clearPinnedTask(): void;
     /**
@@ -257,10 +267,11 @@ export declare class Agent {
      * for the whole run. A driver that starts or switches a goal calls this so
      * request.system and the goal's per-turn re-injection name the same objective.
      *
-     * A blank value falls back to recapturing, matching clearPinnedTask.
+     * A blank value clears the pin, matching clearPinnedTask.
      */
     setPinnedTask(task: string): void;
     /** Append the pinned task header (R7) to the static system prompt. */
+    getExecutionContext(): ExecutionContext;
     private systemWithTaskHeader;
     /**
      * Execute one terminal turn. A host binding makes the remote conversation the
@@ -268,6 +279,7 @@ export declare class Agent {
      * the same core loop used by unhosted ZTC.
      */
     run(messages: Message[], signal?: AbortSignal, takeSteering?: () => Message[]): Promise<AgentRunResult>;
+    private runBound;
     private runCore;
     /**
      * Release the backend. The backend lives as long as the Agent — the run loop

package/dist/agent/agent.js

@@ -7,6 +7,11 @@ import { mergeTokenUsage } from './backends/token_usage.js';
 import { isTransportCodeError, isTransportMessageError } from './backends/transport_errors.js';
 import { inferDefaultProvider, getDefaultApiKeyForProvider, getDefaultModelForProvider } from '../config/defaults.js';
 import { resolveApiRetrySettings } from '../config/api_retry.js';
+import { resolveExecutionSettings } from '../config/execution.js';
+import { createRecoveryGuard } from './runtime/recovery.js';
+import { listCommandJobs, interruptCommandJobs } from './runtime/command_jobs.js';
+import { describeExecutionContext } from './runtime/execution_context.js';
+import { scheduleToolBatch, commandStillRunning } from './runtime/tool_scheduler.js';
 import { AllowAllPolicy } from './runtime/policy.js';
 import { NoopTracer } from './runtime/tracing.js';
 import { defaultTools as baseDefaultTools } from './tools/registry.js';
@@ -208,6 +213,9 @@ export class Agent {
             maxTokens: config.maxTokens,
             routePlan: config.routePlan,
             maxIterations: config.maxIterations || 10,
+            execution: resolveExecutionSettings(config.execution),
+            sessionId: config.sessionId ?? randomUUID(),
+            runtimeFacts: config.runtimeFacts ?? {},
             apiRetry: resolveApiRetrySettings({ apiRetry: config.apiRetry }),
             llmRequestTimeoutMs: resolveLlmRequestTimeoutMs(config.llmRequestTimeoutMs, config.apiRetry?.requestTimeoutMs),
             tools: config.tools || (ambientDiscovery ? defaultTools : []),
@@ -574,6 +582,7 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                     .map(item => ({
                     tool_use_id: item.tool_use_id,
                     content: typeof item.content === 'string' ? item.content : String(item.content ?? ''),
+                    is_error: item.is_error,
                 }));
             }
             catch {
@@ -668,7 +677,7 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                     content = content.slice(0, SYNTH_RESULT_CAP) + `\n[truncated — ${content.length} chars total]`;
                 }
                 emittedToolResultIds.add(tc.id);
-                return { tool_use_id: tc.id, content };
+                return { tool_use_id: tc.id, content, is_error: Boolean(tc.error) || tc.result == null };
             });
             if (toolResults.length === 0)
                 continue;
@@ -687,12 +696,30 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
     }
     buildRequest(messages, availableTools = this.config.tools) {
         // Repair any orphaned tool_use blocks before building request
+        if (this.config.pinTaskHeader) {
+            const facts = describeExecutionContext({ ...this.getExecutionContext(), tools: availableTools.map(tool => tool.definition.name) });
+            const latestFacts = [...messages].reverse().find(message => typeof message.metadata?.executionContext === 'string')?.metadata?.executionContext;
+            if (facts !== latestFacts) {
+                const latestUser = [...messages].reverse().find(message => message.role === 'user');
+                if (latestUser)
+                    latestUser.metadata = { ...latestUser.metadata, executionContext: facts };
+            }
+        }
         const repairedMessages = this.repairConversationHistory(messages);
+        // Facts are attached to the user/tool-result turn that observed them. Keep
+        // earlier snapshots immutable so provider threads can reuse their prefix.
+        const contextMessages = this.config.pinTaskHeader ? repairedMessages.flatMap(message => {
+            const facts = message.metadata?.executionContext;
+            return typeof facts === 'string' ? [message, {
+                    id: `${message.id}_execution`, role: 'user', content: facts, timestamp: message.timestamp,
+                    metadata: { synthetic: true },
+                }] : [message];
+        }) : repairedMessages;
         return {
             model: this.config.model,
             maxTokens: this.config.maxTokens,
             system: this.systemWithTaskHeader(messages),
-            messages: this.formatMessages(repairedMessages),
+            messages: this.formatMessages(contextMessages),
             tools: getRequestToolDefinitions(availableTools, this.discoveredTools, this.config.deferToolSchemas !== false, this.alwaysLoadedToolNames),
             // A container pin identifies a cached prompt prefix, so the transport has to
             // know when this conversation is no longer sending the prefix its container
@@ -918,11 +945,9 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
      */
     _taskHeader = null;
     /**
-     * Drop the pinned task so the NEXT conversation re-captures its own first user
-     * message. Wired into the /clear-only path (clearTransientState), never into
+     * Drop the explicitly pinned task for the next conversation. Wired into the /clear-only path (clearTransientState), never into
      * /compact — the pin must survive compaction (that is the whole point of R7).
-     * Null (not '') so systemWithTaskHeader recaptures rather than treating it as
-     * "no task found."
+     * Null represents no explicitly pinned goal.
      */
     clearPinnedTask() {
         this._taskHeader = null;
@@ -937,23 +962,27 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
      * for the whole run. A driver that starts or switches a goal calls this so
      * request.system and the goal's per-turn re-injection name the same objective.
      *
-     * A blank value falls back to recapturing, matching clearPinnedTask.
+     * A blank value clears the pin, matching clearPinnedTask.
      */
     setPinnedTask(task) {
         const trimmed = task.trim();
         this._taskHeader = trimmed.length > 0 ? trimmed : null;
     }
     /** Append the pinned task header (R7) to the static system prompt. */
-    systemWithTaskHeader(messages) {
-        if (!this.config.pinTaskHeader) {
+    getExecutionContext() {
+        return {
+            mode: this.config.runtimeFacts.mode ?? 'normal', cwd: this._cwd,
+            tools: this.getConfiguredToolNames(), mux: this.config.runtimeFacts.mux ?? false,
+            configScope: this.config.runtimeFacts.configScope ?? 'host configuration',
+            maxTokens: this.config.maxTokens,
+            outputLimitSource: this.config.runtimeFacts.outputLimitSource ?? (this.config.maxTokens === undefined ? 'provider default' : 'explicit configuration'),
+            settings: resolveExecutionSettings(this.config.execution), jobs: listCommandJobs(this.config.sessionId),
+        };
+    }
+    systemWithTaskHeader(_messages) {
+        // Hosted chat owns its system prompt: no local execution facts and no pin.
+        if (!this.config.pinTaskHeader)
             return this.config.systemPrompt;
-        }
-        if (this._taskHeader === null) {
-            const firstUser = messages.find(m => m.role === 'user' && !m.metadata?.synthetic && !m.metadata?.toolResult && typeof m.content === 'string' && m.content.trim().length > 0);
-            this._taskHeader = firstUser ? firstUser.content.trim().slice(0, 2000) : '';
-        }
-        // Shared loop_policy formatting (identical to SubAgent.run); returns the
-        // base prompt unchanged when there is no captured task.
         return pinnedTaskSystem(this.config.systemPrompt, this._taskHeader);
     }
     /**
@@ -962,6 +991,17 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
      * the same core loop used by unhosted ZTC.
      */
     async run(messages, signal, takeSteering) {
+        const onInterrupt = () => { if (this.config.execution.interruptBackgroundJobs)
+            void interruptCommandJobs(this.config.sessionId); };
+        signal?.addEventListener('abort', onInterrupt, { once: true });
+        try {
+            return await this.runBound(messages, signal, takeSteering);
+        }
+        finally {
+            signal?.removeEventListener('abort', onInterrupt);
+        }
+    }
+    async runBound(messages, signal, takeSteering) {
         const binding = this.#conversationBinding;
         if (!binding)
             return this.runCore(messages, signal, takeSteering);
@@ -1048,7 +1088,6 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
         }
         const allToolCalls = [];
         const turnMessages = [];
-        let acceptedSteering = false;
         let iterations = 0;
         // Each turn gets its own auto-continue budget; a long-running Agent must
         // not inherit one spent by the previous turn.
@@ -1072,6 +1111,7 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
         // reproduced a byte-identical result as non-progressing (F8 churn / F1
         // re-fire). Result-equality (not raw repeat count) spares legitimate polling.
         const applyRepeatGuard = createRepeatGuard();
+        const recovery = createRecoveryGuard(this.config.execution);
         try {
             while (iterations < this.config.maxIterations) {
                 if (signal?.aborted) {
@@ -1189,10 +1229,6 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                         stopReason = 'complete';
                         break;
                     }
-                    // Claude requests multiple tool_use blocks in a single response only
-                    // when they are independent, so running them concurrently is safe and
-                    // significantly faster for multi-file reads, searches, etc.
-                    //
                     // Per-batch dedup for `recall_tool_response`: two recalls of the same
                     // inner tool_use_id in one assistant turn share a single execute. The
                     // outer toolBlock.id pairing is preserved for each block so the
@@ -1210,7 +1246,7 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                             data: { tool: toolBlock.name },
                         });
                         const guarded = applyRepeatGuard(toolBlock.name, toolBlock.input, content);
-                        return { toolCall, toolResult: { tool_use_id: toolBlock.id, content: guarded } };
+                        return { toolCall, toolResult: { tool_use_id: toolBlock.id, content: guarded, is_error: false } };
                     };
                     const recordToolError = (toolBlock, toolCall, error, effectiveArgs) => {
                         toolCall.completedAt = new Date();
@@ -1229,6 +1265,7 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                             toolResult: {
                                 tool_use_id: toolBlock.id,
                                 content: applyRepeatGuard(toolBlock.name, toolBlock.input, `Error: ${error}`),
+                                is_error: true,
                             },
                         };
                     };
@@ -1245,7 +1282,7 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                     // It must be the only executable call in this provider response; the
                     // current agent is rebuilt before any subsequent iteration.
                     const exclusiveTransitionId = toolUseBlocks.find((toolBlock) => toolBlock.name === 'plan_mode')?.id ?? null;
-                    const toolPromises = toolUseBlocks.map(async (toolBlock) => {
+                    const combined = await scheduleToolBatch(toolUseBlocks, this.config.tools, this.config.execution, async (toolBlock, skipReason) => {
                         const toolCall = {
                             id: toolBlock.id,
                             name: toolBlock.name,
@@ -1259,6 +1296,8 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                             data: { tool: toolBlock.name }
                         });
                         this.emit({ type: 'tool_start', tool: toolBlock.name, args: toolBlock.input, toolCallId: toolBlock.id });
+                        if (skipReason)
+                            return recordToolError(toolBlock, toolCall, skipReason);
                         if (exclusiveTransitionId !== null
                             && toolBlock.id !== exclusiveTransitionId) {
                             return recordToolError(toolBlock, toolCall, 'Skipped because plan_mode is an exclusive safety transition; retry after the plan agent is active.');
@@ -1298,6 +1337,7 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                                         context: {
                                             cwd: this._cwd,
                                             toolCallId: toolBlock.id,
+                                            sessionId: this.config.sessionId,
                                             signal,
                                             toolResponseStore: this.toolResponseStore,
                                             discoveredTools: this.discoveredTools,
@@ -1321,6 +1361,7 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                                     context: {
                                         cwd: this._cwd,
                                         toolCallId: toolBlock.id,
+                                        sessionId: this.config.sessionId,
                                         signal,
                                         toolResponseStore: this.toolResponseStore,
                                         discoveredTools: this.discoveredTools,
@@ -1344,21 +1385,17 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                             const error = err.message;
                             return recordToolError(toolBlock, toolCall, error);
                         }
-                    });
-                    const combined = await Promise.all(toolPromises);
+                    }, result => result.toolCall.status === 'error' || commandStillRunning(result.toolResult.content), signal, exclusiveTransitionId);
                     allToolCalls.push(...combined.map(r => r.toolCall));
                     const partial = Boolean(signal?.aborted);
                     const toolResults = combined.map(r => {
                         const { rendered } = this.toolResponseStore.put(r.toolResult.tool_use_id, r.toolCall.name, r.toolResult.content, partial, {
                             sourcePath: extractSourcePath(r.toolCall.name, r.toolCall.args),
                             dedupable: r.toolCall.status === 'complete',
+                            isError: r.toolResult.is_error,
                         });
-                        return { tool_use_id: r.toolResult.tool_use_id, content: rendered };
+                        return { tool_use_id: r.toolResult.tool_use_id, content: rendered, is_error: r.toolResult.is_error };
                     });
-                    // Check abort after tool execution so cancel takes effect immediately
-                    if (signal?.aborted) {
-                        throw new AgentError('Cancelled', 'CANCELLED');
-                    }
                     // Real work happened, so the turn has demonstrably not stalled on
                     // narration: give it a fresh continuation budget.
                     this._consecutiveAutoContinues = 0;
@@ -1367,14 +1404,6 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                         .filter(this.isTextBlock)
                         .map(b => b.text)
                         .join('\n');
-                    // Stream any text content that came with tool calls (important for user feedback!)
-                    if (textContent && textContent.trim()) {
-                        if (!this._lastResponseStreamed)
-                            await this.emitStreamText(textContent, signal);
-                        // Last non-empty text wins — empty iterations preserve the prior value
-                        // so maxIterations exhaustion still has something to return.
-                        lastToolTurnText = textContent;
-                    }
                     const toolUseMessage = {
                         id: `assistant_${Date.now()}`,
                         role: 'assistant',
@@ -1394,6 +1423,29 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                     };
                     messages.push(toolResultMessage);
                     turnMessages.push(toolResultMessage);
+                    this.emit({ type: 'history_checkpoint', messages: [...turnMessages] });
+                    if (signal?.aborted)
+                        throw new AgentError('Cancelled', 'CANCELLED');
+                    // Stream any text content that came with tool calls (important for user feedback!)
+                    if (textContent && textContent.trim() && !signal?.aborted) {
+                        if (!this._lastResponseStreamed)
+                            await this.emitStreamText(textContent, signal);
+                        // Last non-empty text wins — empty iterations preserve the prior value
+                        // so maxIterations exhaustion still has something to return.
+                        lastToolTurnText = textContent;
+                    }
+                    const recoveryAction = recovery(combined.map(result => ({ name: result.toolCall.name,
+                        content: result.toolResult.content, isError: result.toolResult.is_error })));
+                    if (recoveryAction === 'stop')
+                        throw new AgentError('Automatic recovery budget exhausted after repeated tool failures. Inspect the retained results and current capabilities before retrying.', 'RECOVERY_EXHAUSTED');
+                    if (recoveryAction === 'recover') {
+                        const recoveryMessage = { id: `recovery_${randomUUID()}`, role: 'user',
+                            content: '[Recovery] Repeated failures share the same cause. Stop that sequence. Inspect current capabilities and active jobs, then make one changed recovery attempt. Use file/stdin tools for scripts and raw Ctrl+C for stuck shell input, then read the pane in the same response or immediately afterward. A silent running-job poll allows one further inspection before stopping; do not repeat empty polls. Continue authorized work; use ask_user only for a concrete missing prerequisite. Do not repeat an acknowledgement as proof of success.',
+                            metadata: { synthetic: true }, timestamp: new Date() };
+                        messages.push(recoveryMessage);
+                        turnMessages.push(recoveryMessage);
+                        this.emit({ type: 'history_checkpoint', messages: [...turnMessages] });
+                    }
                     // An explicit terminal tool may supply the answer after its bookkeeping
                     // succeeds. Keep the tool-use/result pair above for conversation replay.
                     if (combined.length === 1 && combined[0].toolCall.status === 'complete') {
@@ -1432,7 +1484,6 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                         if (steering.length > 0) {
                             messages.push(...steering);
                             turnMessages.push(...steering);
-                            acceptedSteering = true;
                         }
                     }
                 }
@@ -1488,7 +1539,7 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
             usage: totalUsage || undefined,
             stopReason,
             ...(finalReasoning ? { reasoning: finalReasoning } : {}),
-            ...(acceptedSteering ? { turnMessages } : {}),
+            turnMessages,
         };
     }
     /**
@@ -1526,6 +1577,7 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                 context: {
                     cwd: this._cwd,
                     toolCallId,
+                    sessionId: this.config.sessionId,
                     signal: options.signal,
                     toolResponseStore: this.toolResponseStore,
                     discoveredTools: this.discoveredTools,

package/dist/agent/backends/gemini.js

@@ -22,7 +22,7 @@ export class GeminiBackend extends BaseBackend {
                     const resultText = typeof block.content === 'string'
                         ? block.content
                         : block.content.map(b => b.type === 'text' ? b.text : '[image]').join('\n');
-                    return { text: `Function result: ${resultText}` };
+                    return { text: `Function ${block.tool_use_id} ${block.is_error ? 'error' : 'result'}: ${resultText}` };
                 }
                 if (block.type === 'tool_use') {
                     // Convert tool_use to function call format for Gemini

package/dist/agent/backends/openai_format.js

@@ -36,7 +36,7 @@ export function buildOpenAIMessages(request) {
                 toolUses.push({ id: block.id, name: block.name, input: block.input });
             }
             else if (block.type === 'tool_result') {
-                toolResults.push({ tool_use_id: block.tool_use_id, content: block.content });
+                toolResults.push({ tool_use_id: block.tool_use_id, content: block.content, is_error: block.is_error });
             }
             else if (block.type === 'image') {
                 mediaParts.push({
@@ -80,7 +80,7 @@ export function buildOpenAIMessages(request) {
                 out.push({
                     role: 'tool',
                     tool_call_id: tr.tool_use_id,
-                    content: resultText,
+                    content: tr.is_error && !/^error\b/i.test(resultText) ? `Error: ${resultText}` : resultText,
                 });
             }
             // A tool_result merged with a later real user message: OpenAI still

package/dist/agent/backends/openai_responses.js

@@ -179,7 +179,7 @@ export function buildResponsesInput(messages) {
                     input.push({
                         type: 'function_call_output',
                         call_id: block.tool_use_id,
-                        output: resultText,
+                        output: block.is_error && !/^error\b/i.test(resultText) ? `Error: ${resultText}` : resultText,
                     });
                     break;
                 }

package/dist/agent/backends/types.d.ts

@@ -29,6 +29,7 @@ export interface ToolResultBlock {
     type: 'tool_result';
     tool_use_id: string;
     content: string | Array<RequestTextBlock | ToolResultImageBlock>;
+    is_error?: boolean;
 }
 export interface ToolUseRequestBlock {
     type: 'tool_use';

package/dist/agent/commands/config.js

@@ -116,7 +116,7 @@ const STATUS_LINE_USAGE = [
 export const configCommand = {
     name: 'config',
     description: 'Manage configuration',
-    usage: '[show|reset|scope|local|global|key|provider|endpoint|openai-compat|auth-mode|model|effort|display|spinner|statusline|goal-max-turns|manifests-dir|context-progress-bar|workflows] [value]',
+    usage: '[show|reset|scope|local|global|key|provider|endpoint|openai-compat|auth-mode|model|max-tokens|effort|display|spinner|statusline|goal-max-turns|manifests-dir|context-progress-bar|workflows] [value]',
     agentRunnable: true,
     category: 'config',
     handler: async (args, ctx) => {
@@ -139,6 +139,20 @@ export const configCommand = {
             return;
         }
         switch (subCmd) {
+            case 'max-tokens': {
+                const input = value.trim().toLowerCase();
+                if (input && input !== 'default' && (!/^[1-9]\d*$/.test(input) || !Number.isSafeInteger(Number(input)))) {
+                    ctx.addMessage({ role: 'system', content: 'Max tokens must be a positive whole number, or default.' });
+                    return;
+                }
+                if (input) {
+                    ctx.config.set('maxTokens', input === 'default' ? undefined : Number(input));
+                    await ctx.config.save();
+                    ctx.reloadAgent();
+                }
+                ctx.addMessage({ role: 'system', content: `Output cap: ${ctx.config.get().maxTokens ?? 'provider default'}; source: ${ctx.config.getMaxTokensSource?.() ?? 'host configuration'}; config write scope: ${ctx.config.getConfigScope?.() ?? 'global'}. Use /config max-tokens <number|default>.` });
+                return;
+            }
             case 'reset': {
                 if (rest.length > 0) {
                     ctx.addMessage({ role: 'system', content: 'Usage: /config reset' });

package/dist/agent/commands/settings.js

@@ -1,3 +1,4 @@
+import { resolveExecutionSettings } from '../../config/execution.js';
 import { accountsCommand } from './accounts.js';
 import { authCommand } from './auth.js';
 import { activeProfile, builtinProfileEmulation, listConfigProfiles } from '../../config/profiles.js';
@@ -209,6 +210,16 @@ export async function buildSettingsCategories(ctx) {
                 },
             ],
         },
+        {
+            name: 'Execution',
+            settings: Object.entries(resolveExecutionSettings(config.execution)).map(([key, value]) => ({
+                name: `execution_${key}`, label: { shellPanePolicy: 'Shell pane creation', readConcurrency: 'Concurrent reads',
+                    maxCallsPerResponse: 'Calls per response', recovery: 'Failure recovery', repeatedFailureLimit: 'Repeated failure threshold',
+                    recoveryAttempts: 'Recovery attempts', interruptBackgroundJobs: 'Cancel background jobs on interrupt', maxBackgroundJobs: 'Background command limit' }[key],
+                value: String(value), type: typeof value === 'number' ? 'text' : 'select',
+                options: (key === 'shellPanePolicy' ? ['on_request', 'auto'] : key === 'recovery' ? ['automatic', 'pause'] : typeof value === 'boolean' ? ['false', 'true'] : []).map(option => ({ value: option, label: option })),
+            })),
+        },
         {
             name: 'Accounts',
             settings: [{
@@ -1025,6 +1036,18 @@ function openCustomPaneManager(ctx, reopen) {
     showList();
 }
 function applySettingChange(ctx, setting, value) {
+    if (setting.startsWith('execution_')) {
+        const key = setting.slice('execution_'.length);
+        const current = resolveExecutionSettings(ctx.config.get().execution);
+        if (!(key in current))
+            throw new Error(`Unknown execution setting: ${key}`);
+        const parsed = typeof current[key] === 'number' ? Number(value) : typeof current[key] === 'boolean' ? value === 'true' : value;
+        const next = { ...current, [key]: parsed };
+        if (String(resolveExecutionSettings(next)[key]) !== value)
+            throw new Error(`Invalid value for ${key}: ${value}`);
+        ctx.config.set('execution', next);
+        return;
+    }
     if (setting.startsWith('toolPermission_')) {
         const capability = setting.slice('toolPermission_'.length);
         if (!['file_read', 'file_write', 'shell_exec', 'network', 'screen_capture', 'computer_control', 'ml_inference'].includes(capability)) {

package/dist/agent/commands/status.js

@@ -1,3 +1,4 @@
+import { describeExecutionContext } from '../runtime/execution_context.js';
 import { resolveAuthMode } from '../../config.js';
 import { formatRuntimeSummary, getRuntimeInfo } from '../../runtime_info.js';
 import { getWorkflowRegistry } from '../../workflows/registry_handle.js';
@@ -44,10 +45,12 @@ export const statusCommand = {
         catch (error) {
             routeError = error instanceof Error ? error.message : String(error);
         }
+        const execution = ctx.getExecutionContext?.();
         ctx.addMessage({
             role: 'system',
             content: [
                 'Status:',
+                ...(execution ? [describeExecutionContext(execution)] : []),
                 `  API Key: ${hasKey ? '✓ configured' : '✗ not set (use /config key <key>)'}`,
                 `  Platform Auth: ${isAuthenticated ? '✓ configured' : '✗ not set'}`,
                 `  Provider: ${provider}`,

package/dist/agent/commands/types.d.ts

@@ -14,6 +14,7 @@ export interface ConfigController {
     set: <K extends keyof ZTCConfig>(key: K, value: ZTCConfig[K]) => void;
     setGlobal?: <K extends keyof ZTCConfig>(key: K, value: ZTCConfig[K]) => void;
     getConfigScope?: () => ZTCConfigScope;
+    getMaxTokensSource?: () => string;
     setConfigScope?: (scope: ZTCConfigScope) => void;
     clearSessionOverrides?: () => void;
     withConfigScope?: <T>(scope: ZTCConfigScope, fn: () => T | Promise<T>) => Promise<T>;
@@ -304,6 +305,7 @@ export interface CommandContext {
     exit: () => void;
     /** Current session ID. Used by /rename and other session-scoped commands. */
     getSessionId?: () => string;
+    getExecutionContext?: () => import('../runtime/execution_context.js').ExecutionContext | undefined;
     /** Current user-set session name (live, post-rename). Undefined if not named. */
     getSessionName?: () => string | undefined;
     /**

package/dist/agent/completion_state.js

@@ -20,10 +20,10 @@ export function incompleteModelResponseMessage(stopReason, maxTokens, outputToke
     if (limited || exhausted) {
         if (maxTokens === undefined) {
             return 'Model reached the provider\'s output limit (including reasoning). '
-                + 'Set maxTokens within the model\'s limit or lower reasoning effort, then retry; the incomplete response was not accepted.';
+                + 'Use /config max-tokens <number> within the model\'s limit or lower reasoning effort, then retry; completed tool work is retained and the incomplete response was not accepted.';
         }
         return `Model reached the output limit (maxTokens: ${maxTokens}, including reasoning). `
-            + 'Increase maxTokens and retry; the incomplete response was not accepted.';
+            + 'Set /config max-tokens <number> or /config max-tokens default, then retry. Completed tool work is retained; the incomplete response was not accepted.';
     }
     return INCOMPLETE_MODEL_RESPONSE_MESSAGE;
 }

package/dist/agent/factory.js

@@ -677,7 +677,7 @@ export function createAgentFromConfig(options) {
         emulationMappingPrompt,
         skillPrompt: effectiveSkillPrompt,
         modePrompt,
-        muxEnabled: paneToolsEnabled,
+        muxEnabled: filteredToolNames.has('create_terminal_pane'),
         agentsContext: projectContext,
         runtimeContext,
         askUserAvailable: filteredToolNames.has('ask_user'),
@@ -715,6 +715,12 @@ export function createAgentFromConfig(options) {
         // Hosted runtimes never pin the task header; other callers may opt in.
         pinTaskHeader: hostRuntime ? false : options.pinTaskHeader,
         tools: filteredTools,
+        execution: options.config.execution,
+        sessionId: options.sessionId,
+        runtimeFacts: { mode, mux: Boolean(options.muxMode || effectivePaneMode),
+            configScope: configStore.getConfigScope(),
+            outputLimitSource: options.config.maxTokens === configStore.get().maxTokens ? configStore.getMaxTokensSource() : 'host configuration',
+        },
         // Agent-domain tools (ZTC_AGENT_DOMAIN) are the host's curated surface — ship
         // their schemas every turn instead of hiding them behind the deferred-tool
         // search corpus (which the mode allowlist can also strip).