@eddyskywalker/dsh-chatgpt-subscription 0.59.0 → 0.60.0

package/lib/codemode.js

@@ -1,3 +1,5 @@
+import { n as PLUGIN_MESSAGE_SOURCE_KIND } from "./llm-compat-u9mor0uu.js";
+import { createUserMessage } from "@deepseek-ai/dsh-llm";
 import { NativeToolExecutor } from "@deepseek-ai/dsh-tool-executor-native";
 import { AsyncLocalStorage } from "node:async_hooks";
 //#region src/host/codemode/discovery.ts
@@ -448,10 +450,18 @@ const DEFAULT_HIDDEN_PREFIXES = Object.freeze(["mcp__"]);
 /**
 * 默认始终原生呈现的名字。
 *
-* 恒定系统提示词里点名了这两个工具（大输出预览的补读工具、调度账本的查询工具），
-* 遮蔽它们会让提示词指向一个模型看不见的名字，所以默认留在原生清单里。
+* 恒定系统提示词或子代理运行时契约里点名要求直接调用这些工具（大输出预览补读、调度账本查询、
+* 进展更新汇报、结构化子代理输出提交，以及 Windows 下替代被撤回 `pwsh` 的 `win_bash`）：
+* 遮蔽它们要么让提示词指向模型看不见的名字并触发整批 `UNKNOWN_TOOL` 重跑，要么让会话顶层
+* 失去唯一可用的 Shell。若某个工具当前未在宿主/子会话注册，保留在此集合中不会凭空暴露它。
 */
-const DEFAULT_NATIVE_TOOLS = Object.freeze(["cache_warmup_result", "dispatch_ledger"]);
+const DEFAULT_NATIVE_TOOLS = Object.freeze([
+	"cache_warmup_result",
+	"dispatch_ledger",
+	"progress_update",
+	"structured_output",
+	"win_bash"
+]);
 /**
 * 把原始配置归一化。
 *
@@ -462,12 +472,8 @@ function createRules(config) {
 	const options = normalizeConfig(config);
 	return {
 		options,
-		hidden: new Set(options.hiddenTools),
-		native: /* @__PURE__ */ new Set([
-			...options.nativeTools,
-			options.runToolName,
-			...options.metaTools
-		])
+		hidden: /* @__PURE__ */ new Set([...options.hiddenTools, ...options.metaTools]),
+		native: /* @__PURE__ */ new Set([...options.nativeTools, options.runToolName])
 	};
 }
 /**
@@ -491,6 +497,8 @@ function normalizeConfig(config) {
 		runToolName,
 		maxParallelSubCalls: positiveInteger(source.maxParallelSubCalls, 10),
 		maxSubCalls: positiveInteger(source.maxSubCalls, 512),
+		explicitMaxSubCalls: typeof source.maxSubCalls === "number" && Number.isInteger(source.maxSubCalls) && source.maxSubCalls > 0,
+		maxSubCallsPerMinute: positiveInteger(source.maxSubCallsPerMinute, 1024),
 		guard: source.guard !== false,
 		sdkSection: source.sdkSection !== false,
 		debug: source.debug !== false
@@ -561,7 +569,7 @@ function summarizeHidden(names) {
 *
 * ## 恒定契约
 *
-* 这段正文**只**依赖入参里的两个工具名与部署级的 `programFormat`。它刻意不含遮蔽
+* 这段正文**只**依赖入参里的两个工具名与部署级的 `language` / `programFormat`。它刻意不含遮蔽
 * 工具的数量、namespace 分布、会话 id 或时间，因此同一部署下逐字节恒定：挂载或卸载
 * MCP 服务端不会改写它，前缀缓存不会因为它失效。
 *
@@ -569,26 +577,40 @@ function summarizeHidden(names) {
 * @returns 说明段正文。
 */
 function buildCodemodeSectionText(input) {
+	const python = input.language === "python";
 	const retained = input.programFormat === "repl";
 	const listTool = input.metaTools[0] ?? "code_tools_list";
 	const searchTool = input.metaTools[1] ?? "code_tools_search";
 	const describeTool = input.metaTools[2] ?? "code_tools_describe";
+	const run = input.runToolName;
+	const example = python ? [
+		"```py",
+		"# standard tools and hidden tools alike",
+		"import asyncio",
+		"files = await tools.glob({\"pattern\": \"src/**/*.ts\"})",
+		"rows = await asyncio.gather(*(tools.read({\"file_path\": f}) for f in files))",
+		"[r.splitlines()[0] for r in rows if \"TODO\" in r]",
+		"```"
+	] : [
+		"```js",
+		"// standard tools and hidden tools alike",
+		"const files = await tools.glob({ pattern: \"src/**/*.ts\" })",
+		"const rows = await Promise.all(files.map((f) => tools.read({ file_path: f })))",
+		retained ? "rows.filter((r) => r.includes(\"TODO\")).map((r) => r.split(\"\\n\")[0])" : "return rows.filter((r) => r.includes(\"TODO\")).map((r) => r.split(\"\\n\")[0])",
+		"```"
+	];
 	return [
 		"## Code Mode",
 		"",
-		"This session runs in Code Mode. The tools in your tool list are called directly, exactly as usual. A second, larger set of tools is deliberately **not** in your context: every MCP tool, and every tool contributed by a plugin outside this preset. Reach them from inside " + input.runToolName + ".",
+		"This session runs in Code Mode. The tools in your tool list are called directly, exactly as usual. A second, larger set of tools is deliberately **not** in your context: every MCP tool, and every tool contributed by a plugin outside this preset. Reach them from inside " + run + ".",
 		"",
 		"### Calling tools from a program",
 		"",
-		"```js",
-		"// standard tools and hidden tools alike",
-		"const files = await tools.glob({ pattern: \"src/**/*.ts\" })",
-		"const rows = await Promise.all(files.map((f) => tools.read({ file_path: f })))",
-		retained ? "rows.filter((r) => r.includes(\"TODO\")).map((r) => r.split(\"\\n\")[0])" : "return rows.filter((r) => r.includes(\"TODO\")).map((r) => r.split(\"\\n\")[0])",
-		"```",
+		...example,
 		"",
-		retained ? "- A retained TypeScript REPL: top-level declarations, await, and a final expression. Its variables and imported modules survive into your later programs in this session." : "- Erasable TypeScript, run as the body of an async function: top-level await and return work.",
+		python ? retained ? "- A retained Python REPL: top-level await and a final expression. Its variables and imported modules survive into your later programs in this session." : "- Async Python program: top-level await works; print or evaluate a final expression to produce output." : retained ? "- A retained TypeScript REPL: top-level declarations, await, and a final expression. Its variables and imported modules survive into your later programs in this session." : "- Erasable TypeScript, run as the body of an async function: top-level await and return work.",
 		"- Only what you return or console.log reaches the conversation; every intermediate result stays in the program, so filter and aggregate there instead of returning raw payloads.",
+		"- Prefer batching multi-step read/search chains inside one " + run + " program instead of issuing many sequential single-tool turns.",
 		"- Independent read-only calls may overlap under Promise.all; mutating calls run alone, in submission order.",
 		"- A failed sub-call rejects; try/catch or Promise.allSettled it to keep the calls that succeeded. Completed calls are real side effects and are not rolled back.",
 		"",
@@ -782,6 +804,7 @@ function denialFor(call, rules, hooks, batchSignal) {
 	if (isNestedCall(call, batchSignal)) return void 0;
 	if (name === rules.options.runToolName) return void 0;
 	if (!isMaskedName(name, rules, hooks.viewForName(name))) return void 0;
+	if (rules.options.metaTools.includes(name)) return "The discovery tool \"" + name + "\" is callable only from inside " + rules.options.runToolName + ": run a program and call await tools." + name + "(...) there.";
 	const searchTool = rules.options.metaTools[1] ?? rules.options.metaTools[0] ?? "code_tools_search";
 	return "The tool \"" + name + "\" is not part of this session tool list. In Code Mode, tools this preset does not own (MCP servers, plugins outside the preset) are reachable only from inside " + rules.options.runToolName + ": call tools." + searchTool + "({ query: \"...\" }) there to discover it, then call it by exact name.";
 }
@@ -978,17 +1001,17 @@ function asRegistry(tools) {
 * 用自己的名字注册同一件事——把模型写的一段程序交给 `ctx.ptcRuntime` 执行，程序里的每次
 * `tools.<name>(args)` 都是一次真实的工具调用。
 *
-* ## 为什么执行委托给注册表而不是自己跑管线
-*
-* 子调用走公开的 `ctx.tools.execute()`，因此落到**注册表选中的执行器**上：在本预设里就是
-* 原生 executor 的完整管线（pre-policy、审批、around-dispatch、post-execute 一个不少）。
-* 手写这条管线是插件静默丢策略的典型方式，所以这里一行都不抄。
-*
-* ## 子调度的取舍
+* ## 与内核 PTC `run_code` 对齐的使用配置
 *
-* 程序自己用 `Promise.all` 决定并发。本模块只做一件额外的事：把 `isConcurrencySafe` 不为
-* `true` 的调用串行化成互斥段，只读调用放行到 `maxParallelSubCalls` 个并发。与内核的
-* 差别是「只排序同一程序内的子调用」，不与同一模型步的其它调用互相排序。
+* 1. **运行时感知 Schema**：按 `ptcRuntime` 的语言（TypeScript / Python）、程序形态
+*    （`function-body` / 常驻 REPL）、超时预算（`defaultMs` / `maxMs`）与沙箱支持动态投影
+*    描述和参数（含单次提权的 `sandbox_permissions` + `justification`）；同一部署下静态恒定，
+*    不会扰动前缀缓存。
+* 2. **完整子调用调度与上下文转发**：只读并发上限受 `maxParallelSubCalls` 约束，写类调用等待
+*    在飞调用排空后独占执行；程序结算时中止悬空请求并等待已启动子调用落盘；子调用产生的图片块、
+*    `additionalContexts` 与 `concludesTurn` 原样转交给外层步骤。
+* 3. **展示元数据与输出格式化**：声明 `presentCall` 与 `output.presentationMeta`（记录语言），
+*    深层 JSON 结果控制缩进上限，失败时保留已捕获输出与沙箱诊断信息。
 *
 * @module @eddyskywalker/dsh-chatgpt-subscription/host/codemode/transport
 */
@@ -1011,6 +1034,79 @@ const catalogScope = new AsyncLocalStorage();
 function currentCatalogSnapshot() {
 	return catalogScope.getStore();
 }
+/** 允许单次提权的目标沙箱模式（对齐 `@deepseek-ai/dsh-sandbox` 的 `ESCALATION_TARGETS`）。 */
+const ESCALATION_TARGETS = Object.freeze(["workspace-write", "danger-full-access"]);
+/** 与内核 `run_code` 一致的 `description` 参数说明。 */
+const DESCRIPTION_PARAM_DESCRIPTION = "Clear, concise description of what this program does in active voice, 5-10 words (shown in the UI). Examples: \"Count TODO markers across packages\"; \"Read failing test and its fixture\"; \"Rename config key in every cordis.yml\".";
+function buildFlavor(languageName, execution) {
+	return {
+		description: `Execute a ${languageName} program against the available tools. Takes two required arguments: \`code\`, ${execution.programDescription}, and \`description\`, a short summary of what the program does. Call tools as \`await tools.name(args)\`. ${execution.outputInstruction} Image-bearing subtool results are attached after the run.`,
+		codeDescription: execution.codeDescription
+	};
+}
+const TYPESCRIPT_REPL_FLAVOR = buildFlavor("TypeScript", {
+	programDescription: "the program to execute",
+	outputInstruction: "Curate the program output.",
+	codeDescription: "The TypeScript program to execute, following this tool's execution instructions."
+});
+const TYPESCRIPT_FUNCTION_FLAVOR = buildFlavor("TypeScript", {
+	programDescription: "the BODY of an async function (erasable syntax only; top-level `await` and `return` work)",
+	outputInstruction: "Only what you print or return is program output — curate it.",
+	codeDescription: "The program: the body of an async TypeScript function."
+});
+const PYTHON_FLAVOR = buildFlavor("Python", {
+	programDescription: "the program to execute",
+	outputInstruction: "Curate the program output.",
+	codeDescription: "The Python program to execute, following this tool's execution instructions."
+});
+function resolveFlavor(runtime) {
+	if (runtime?.language === "python") return PYTHON_FLAVOR;
+	if (runtime?.language === "typescript" && runtime.programFormat === "repl") return TYPESCRIPT_REPL_FLAVOR;
+	return TYPESCRIPT_FUNCTION_FLAVOR;
+}
+function escalationGuidance(sandboxMode) {
+	return sandboxMode === void 0 ? "" : " A sandbox escalation approves this complete program for one execution only. Nested tools retain their own policies and approvals. Request wider access only after evidence of a denial. Earlier effects may already have completed: inspect them before explicitly retrying. Programs are never replayed automatically.";
+}
+function buildTransportDescription(runtime) {
+	const flavor = resolveFlavor(runtime);
+	const instructions = typeof runtime?.executionInstructions === "string" && runtime.executionInstructions.length > 0 ? ` ${runtime.executionInstructions}` : "";
+	return flavor.description + instructions + " Each program starts in the Session's current directory. Running programs keep their initial directory." + escalationGuidance(runtime?.sandboxMode);
+}
+function buildTransportParameters(runtime) {
+	const flavor = resolveFlavor(runtime);
+	const timeoutDescription = runtime?.timeout !== void 0 ? `Positive elapsed-time budget in milliseconds, including nested tool and approval waits. Default ${String(runtime.timeout.defaultMs)}; capped at ${String(runtime.timeout.maxMs)}. Zero does not disable the deadline.` : "Positive elapsed-time budget in milliseconds, capped by the runtime maximum.";
+	const properties = {
+		code: {
+			type: "string",
+			description: flavor.codeDescription
+		},
+		description: {
+			type: "string",
+			description: DESCRIPTION_PARAM_DESCRIPTION
+		},
+		timeoutMs: {
+			type: "number",
+			description: timeoutDescription
+		}
+	};
+	if (runtime?.sandboxMode !== void 0) {
+		properties["sandbox_permissions"] = {
+			type: "string",
+			enum: [...ESCALATION_TARGETS],
+			description: "Wider sandbox mode for this complete program execution; requires justification and approval."
+		};
+		properties["justification"] = {
+			type: "string",
+			description: "Reason this complete program needs wider access, shown to the user for approval. Use the language of the user’s current request."
+		};
+	}
+	return {
+		type: "object",
+		additionalProperties: false,
+		required: ["code", "description"],
+		properties
+	};
+}
 /**
 * 造 `code_run` 的工具定义。
 *
@@ -1020,28 +1116,10 @@ function currentCatalogSnapshot() {
 */
 function createTransportDefinition(host, rules) {
 	const runToolName = rules.options.runToolName;
-	return {
+	const definition = {
 		name: runToolName,
-		description: "Execute a TypeScript program against the available tools. Takes two required arguments: `code`, the body of an async function (erasable syntax only; top-level await and return work), and `description`, a short summary of what the program does. Call tools as `await tools.name(args)`. Only what you print or return is program output.",
-		parameters: {
-			type: "object",
-			additionalProperties: false,
-			required: ["code", "description"],
-			properties: {
-				code: {
-					type: "string",
-					description: "The program: the body of an async TypeScript function."
-				},
-				description: {
-					type: "string",
-					description: "Clear, concise description of what this program does in active voice, 5-10 words."
-				},
-				timeoutMs: {
-					type: "number",
-					description: "Positive elapsed-time budget in milliseconds, capped by the runtime maximum."
-				}
-			}
-		},
+		description: buildTransportDescription(void 0),
+		parameters: buildTransportParameters(void 0),
 		output: {
 			schema: {
 				type: "object",
@@ -1059,53 +1137,80 @@ function createTransportDefinition(host, rules) {
 						required: ["mode", "denied"],
 						properties: {
 							mode: { type: "string" },
-							denied: { type: "boolean" }
+							denied: { type: "boolean" },
+							enforcement: {
+								type: "string",
+								enum: ["full", "partial"]
+							}
 						}
 					}
 				}
 			},
 			render: (_args, value) => {
-				const parts = [];
-				for (const line of value.logs ?? []) if (line.length > 0) parts.push(line);
-				if (value.result !== void 0) try {
-					parts.push(typeof value.result === "string" ? value.result : JSON.stringify(value.result, null, 2));
-				} catch {
-					parts.push(String(value.result));
-				}
-				if (value.sandbox?.denied === true) parts.push("The " + value.sandbox.mode + " file sandbox denied an operation.");
+				const parts = [(value.logs ?? []).join("\n"), value.result === void 0 ? "" : renderProgramValue(value.result)].filter((part) => part.length > 0);
+				if (value.sandbox?.enforcement === "partial") parts.push("File sandbox enforcement is partial on this host.");
+				if (value.sandbox?.denied === true) parts.push("The " + value.sandbox.mode + " file sandbox denied an operation." + escalationGuidance(host.runtime()?.sandboxMode));
 				return [{
 					type: "text",
 					text: parts.length > 0 ? parts.join("\n") : "(" + runToolName + " completed with no output)"
 				}];
+			},
+			presentationMeta: () => {
+				return { language: host.runtime()?.language === "python" ? "python" : "typescript" };
 			}
 		},
+		presentCall(args) {
+			if (typeof args !== "object" || args === null) return void 0;
+			const record = args;
+			const code = record["code"];
+			const description = record["description"];
+			if (typeof code !== "string" || typeof description !== "string" || description.trim().length === 0) return;
+			return {
+				card: "generic",
+				title: description,
+				kind: "execute",
+				rawInput: code
+			};
+		},
 		async execute(args, exec) {
 			const input = readArguments(args);
 			const runtime = host.runtime();
 			if (runtime === void 0) throw new Error("codemode: no PTC runtime is mounted (ctx.ptcRuntime); the program transport is unavailable");
+			if (input.timeoutMs !== void 0 && runtime.timeout !== void 0 === false && isStrictTimeoutUnsupported(runtime)) throw new Error("timeoutMs is not available for this PTC runtime");
 			const catalog = host.catalog();
-			const runSignal = AbortSignal.any([exec.signal, new AbortController().signal]);
-			const nestedSignal = markNested(runSignal) ?? runSignal;
+			const runController = new AbortController();
+			const onOuterAbort = () => {
+				runController.abort(exec.signal.reason);
+			};
+			if (exec.signal.aborted) runController.abort(exec.signal.reason);
+			else exec.signal.addEventListener("abort", onOuterAbort, { once: true });
+			const nestedSignal = markNested(runController.signal) ?? runController.signal;
 			const owner = host.stateOwner(exec.agent);
-			const limit = rules.options.maxSubCalls;
+			let maxSubCalls = rules.options.maxSubCalls;
 			let attempts = 0;
-			const exclusive = createMutex();
+			const scheduler = createSubCallScheduler(rules.options.maxParallelSubCalls, () => runController.signal.aborted);
 			const definitions = /* @__PURE__ */ new Map();
 			for (const entry of catalog) definitions.set(entry.name, entry);
-			const functions = {};
+			const functions = Object.create(null);
 			for (const entry of catalog) {
 				if (entry.name === runToolName) continue;
-				functions[entry.name] = async (rawArgs) => {
+				const invoke = async (rawArgs) => {
+					if (runController.signal.aborted) throw new Error(runToolName + " run is over; " + entry.name + " not dispatched");
 					const n = ++attempts;
-					if (n > limit) throw new Error("program sub-call limit exceeded: " + String(limit) + " calls");
+					if (n > maxSubCalls) {
+						const limitErr = /* @__PURE__ */ new Error("program sub-call limit exceeded: " + String(maxSubCalls) + " calls");
+						runController.abort(limitErr);
+						throw limitErr;
+					}
 					const parsed = losslessArgs(rawArgs);
+					const loggedArgs = losslessArgs(parsed);
 					const callId = String(exec.callId) + NESTED_CALL_ID_MARKER + String(n);
 					const dispatchLog = createDispatchLog(exec.agent, {
 						rootCallId: rootCallIdOf(String(exec.callId)),
 						parentCallId: String(exec.callId),
 						subCallId: callId,
 						name: entry.name,
-						arguments: parsed
+						arguments: loggedArgs
 					});
 					const run = async () => {
 						dispatchLog.start();
@@ -1124,55 +1229,151 @@ function createTransportDefinition(host, rules) {
 							throw error;
 						}
 						dispatchLog.settle(outcome);
+						if (outcome.error === void 0 && Array.isArray(outcome.content) && hasImageBlock(outcome.content)) {
+							const imageMsg = host.createImageContext?.(outcome.content);
+							if (imageMsg !== void 0) exec.deferContext?.(imageMsg);
+						}
+						if (Array.isArray(outcome.additionalContexts)) for (const contextMsg of outcome.additionalContexts) exec.deferContext?.(contextMsg);
+						if (outcome.error === void 0 && outcome.concluded === true) exec.concludeTurn?.();
+						if (runController.signal.aborted) throw new Error(runToolName + " run is over; " + entry.name + " result discarded");
 						if (outcome.error !== void 0) throw new Error(outcome.error);
 						return outcome.value !== void 0 ? outcome.value : outcome.text ?? null;
 					};
-					return isConcurrencySafe(definitions.get(entry.name), parsed) ? run() : exclusive.run(run);
+					const mode = isConcurrencySafe(definitions.get(entry.name), parsed) ? "parallel" : "exclusive";
+					return scheduler.schedule(mode, run, () => {
+						throw new Error(runToolName + " run is over; " + entry.name + " tool call abandoned");
+					});
 				};
+				Object.defineProperty(functions, entry.name, {
+					enumerable: true,
+					configurable: true,
+					writable: true,
+					value: invoke
+				});
 			}
-			/**
-			* 跑一次程序：每次重取会话授权，因为重试发生在策略变更之后。
-			*
-			* `resolve()` 是新代内核的前置步骤（目录 / 超时 / 文件策略）。老代运行时没有它，
-			* 那时把原始请求直接交给 `run()` 才是当时的契约。
-			*/
-			const attempt = async () => {
-				const authority = await host.runAuthority?.(exec.agent, nestedSignal);
-				const request = {
-					program: input.code,
-					bindings: [{
-						global: "tools",
-						functions
-					}],
-					stateOwner: owner,
-					...authority?.cwd === void 0 ? {} : { cwd: authority.cwd },
-					...authority?.sandboxPolicy === void 0 ? {} : { sandboxPolicy: authority.sandboxPolicy },
-					...input.timeoutMs === void 0 ? {} : { timeoutMs: input.timeoutMs },
-					signal: nestedSignal
-				};
-				const spec = typeof runtime.resolve === "function" ? runtime.resolve(request) : request;
-				return await catalogScope.run(catalog, () => runtime.run(spec));
-			};
-			let result;
 			try {
-				result = await attempt();
-			} catch (error) {
-				if (!isRetainedPolicyChange(error)) throw error;
-				await host.releaseOwner(owner);
-				host.stateOwner(exec.agent);
-				result = await attempt();
+				/**
+				* 跑一次程序：每次重取会话授权，因为重试发生在策略变更之后。
+				*
+				* 单次沙箱提权（`sandbox_permissions`）只在第一次进入前审批一次，且提权后的单次执行不传
+				* `stateOwner`，避免把单次授权固化到常驻环境中（对齐内核 `ptc.ts`）。
+				*/
+				let approvedEscalatedMode;
+				const attempt = async () => {
+					const authority = await host.runAuthority?.(exec.agent, nestedSignal);
+					const standingPolicy = authority?.sandboxPolicy;
+					let effectivePolicy = standingPolicy;
+					let escalated = false;
+					if (input.sandboxPermissions !== void 0 && input.justification !== void 0) {
+						if (standingPolicy === void 0 || typeof host.escalateSandbox !== "function") throw new Error("sandbox_permissions is not available for this PTC runtime");
+						if (approvedEscalatedMode === void 0) {
+							const nextPolicy = await host.escalateSandbox({
+								requestedMode: input.sandboxPermissions,
+								justification: input.justification,
+								standingPolicy,
+								agent: exec.agent,
+								callId: String(exec.callId),
+								toolName: runToolName,
+								signal: exec.signal
+							});
+							effectivePolicy = nextPolicy;
+							approvedEscalatedMode = modeOfPolicy(nextPolicy);
+						} else if (typeof standingPolicy === "object" && standingPolicy !== null) effectivePolicy = {
+							...standingPolicy,
+							mode: approvedEscalatedMode
+						};
+						escalated = modeOfPolicy(effectivePolicy) !== modeOfPolicy(standingPolicy);
+					}
+					const request = {
+						program: input.code,
+						bindings: [{
+							global: "tools",
+							functions,
+							errorClass: {
+								name: "ToolCallError",
+								memberNameProperty: "toolName"
+							}
+						}],
+						...escalated ? {} : { stateOwner: owner },
+						...authority?.cwd === void 0 ? {} : { cwd: authority.cwd },
+						...effectivePolicy === void 0 ? {} : { sandboxPolicy: effectivePolicy },
+						...input.timeoutMs === void 0 ? {} : { timeoutMs: input.timeoutMs },
+						signal: nestedSignal
+					};
+					const spec = typeof runtime.resolve === "function" ? runtime.resolve(request) : request;
+					maxSubCalls = resolveSubCallBudget(spec, rules);
+					return await catalogScope.run(catalog, () => runtime.run(spec));
+				};
+				let result;
+				try {
+					try {
+						result = await attempt();
+					} catch (error) {
+						if (!isRetainedPolicyChange(error)) throw error;
+						await host.releaseOwner(owner);
+						host.stateOwner(exec.agent);
+						result = await attempt();
+					}
+				} finally {
+					runController.abort(runToolName + " settled");
+					await scheduler.drain();
+				}
+				if (result.error !== void 0) {
+					const logsText = Array.isArray(result.logs) && result.logs.length > 0 ? "\nCaptured output:\n" + result.logs.join("\n") : "";
+					const sandboxText = result.sandbox === void 0 ? "" : "\nFile sandbox: " + result.sandbox.mode + (result.sandbox.enforcement === void 0 ? "" : "; enforcement: " + result.sandbox.enforcement) + (result.sandbox.denied ? "; operation denied" : "") + ".";
+					const hint = result.sandbox?.denied ? escalationGuidance(runtime.sandboxMode) : "";
+					throw new Error("program failed (" + result.error.kind + "): " + result.error.message + logsText + sandboxText + hint);
+				}
+				return {
+					logs: [...result.logs ?? []],
+					...result.value === void 0 ? {} : { result: result.value },
+					...result.sandbox === void 0 ? {} : { sandbox: {
+						mode: result.sandbox.mode,
+						denied: result.sandbox.denied,
+						...result.sandbox.enforcement === void 0 ? {} : { enforcement: result.sandbox.enforcement }
+					} }
+				};
+			} finally {
+				exec.signal.removeEventListener("abort", onOuterAbort);
 			}
-			if (result.error !== void 0) throw new Error("program failed (" + result.error.kind + "): " + result.error.message);
-			return {
-				logs: [...result.logs ?? []],
-				...result.value === void 0 ? {} : { result: result.value },
-				...result.sandbox === void 0 ? {} : { sandbox: {
-					mode: result.sandbox.mode,
-					denied: result.sandbox.denied
-				} }
-			};
 		}
 	};
+	Object.defineProperty(definition, "description", {
+		enumerable: true,
+		configurable: true,
+		get: () => buildTransportDescription(safeRuntime(host))
+	});
+	Object.defineProperty(definition, "parameters", {
+		enumerable: true,
+		configurable: true,
+		get: () => buildTransportParameters(safeRuntime(host))
+	});
+	return definition;
+}
+function safeRuntime(host) {
+	try {
+		return host.runtime();
+	} catch {
+		return;
+	}
+}
+/** 只有明确声明了 `timeout: undefined` 自身属性（而非测试假对象省略字段）才视作不支持 `timeoutMs`。 */
+function isStrictTimeoutUnsupported(runtime) {
+	return Object.prototype.hasOwnProperty.call(runtime, "timeout") && runtime.timeout === void 0;
+}
+function modeOfPolicy(policy) {
+	if (typeof policy !== "object" || policy === null) return void 0;
+	const mode = policy.mode;
+	return typeof mode === "string" ? mode : void 0;
+}
+function hasImageBlock(content) {
+	return content.some((block) => typeof block === "object" && block !== null && block.type === "image");
+}
+function resolveSubCallBudget(spec, rules) {
+	if (rules.options.explicitMaxSubCalls) return rules.options.maxSubCalls;
+	if (spec.timeoutMs === null) return Infinity;
+	if (typeof spec.timeoutMs === "number" && Number.isFinite(spec.timeoutMs) && spec.timeoutMs > 0) return Math.max(1, Math.floor(spec.timeoutMs / 6e4 * rules.options.maxSubCallsPerMinute));
+	return rules.options.maxSubCalls;
 }
 /** 没有会话可写时的空记录。 */
 const NO_DISPATCH_LOG = Object.freeze({
@@ -1183,21 +1384,6 @@ const NO_DISPATCH_LOG = Object.freeze({
 const DISPATCH_LOG_TEXT_LIMIT = 8e3;
 /**
 * 造一条子调用的回放记录。
-*
-* 内核自己的 PTC 传输会为每条子调用 append `tool/ptc-dispatch-start` /
-* `tool/ptc-dispatch`，界面（`tool-call-tree`）靠这一对事件把子调用画到父调用下面。
-* 本行的程序交给内核运行时执行，而那两条事件不在运行时的对外契约里，只能在这里补。
-*
-* 三条约束：
-*
-* 1. **时序诚实**：`-start` 只在真正进入执行 lane 之后写，排队中的调用不写；
-* 2. **必须成对**：只写 start 会留下永远不收尾的行，比不显示更糟；
-* 3. **绝不带崩程序**：append 只是日志侧工作，异常一律吞掉——老代 harness 没有这两
-*    种事件类型，那里应当表现为「没有回放」，而不是 `code_run` 失败。
-*
-* @param agent - 调用方 agent（`agent.session.append` 的宿主）。
-* @param entry - 这次子调用的身份与参数。
-* @returns 回放记录；没有会话可写时是空实现。
 */
 function createDispatchLog(agent, entry) {
 	const session = typeof agent === "object" && agent !== null ? agent.session : void 0;
@@ -1232,12 +1418,6 @@ function createDispatchLog(agent, entry) {
 }
 /**
 * 把内容块裁到日志能承受的长度。
-*
-* 程序本身拿到的值不受影响；这里只是回放副本，所以宁可截断也不让一条子调用把整份
-* 大文件写进会话记录。
-*
-* @param content - 原始内容块。
-* @returns 可写进事件的副本。
 */
 function clipContent(content) {
 	if (content === void 0) return [];
@@ -1254,12 +1434,6 @@ function clipContent(content) {
 }
 /**
 * 一条调用所属调用树的根 id。
-*
-* `code_run` 不会被本行自己的程序嵌套调用，所以顶层工作量下就是它自己；这里仍按
-* `:ptc:` 前缀剥一层，避免将来出现嵌套时把根写错。
-*
-* @param callId - 本次调用的 id。
-* @returns 根 id。
 */
 function rootCallIdOf(callId) {
 	const at = callId.indexOf(NESTED_CALL_ID_MARKER);
@@ -1269,6 +1443,18 @@ function rootCallIdOf(callId) {
 function isRetainedPolicyChange(error) {
 	return (error instanceof Error ? error.message : String(error)).includes("release the retained environment before changing its sandbox policy");
 }
+/** 校验单次沙箱提权参数配对（对齐 `@deepseek-ai/dsh-sandbox` 的 `validateEscalationArgs`）。 */
+function validateEscalationArgs(sandboxPermissions, justification) {
+	if (sandboxPermissions !== void 0 && justification === void 0) throw new Error("invalid escalation: sandbox_permissions requires a justification");
+	if (justification !== void 0 && sandboxPermissions === void 0) throw new Error("invalid escalation: justification is only valid together with sandbox_permissions");
+	if (sandboxPermissions === void 0 && justification === void 0) return {};
+	if (typeof sandboxPermissions !== "string" || !ESCALATION_TARGETS.includes(sandboxPermissions)) throw new Error("invalid sandbox_permissions: expected \"workspace-write\" or \"danger-full-access\"");
+	if (typeof justification !== "string" || justification.trim().length === 0) throw new Error("invalid justification: expected a non-empty sentence");
+	return {
+		sandboxPermissions,
+		justification
+	};
+}
 /** 校验并读出工具参数。 */
 function readArguments(args) {
 	if (typeof args !== "object" || args === null) throw new Error("codemode: expected an arguments object");
@@ -1277,16 +1463,19 @@ function readArguments(args) {
 	const description = record["description"];
 	if (typeof code !== "string" || code.trim().length === 0) throw new Error("codemode: invalid code: expected a non-empty string");
 	if (typeof description !== "string" || description.trim().length === 0) throw new Error("codemode: invalid description: expected a non-empty string");
+	const escalation = validateEscalationArgs(record["sandbox_permissions"], record["justification"]);
 	const timeoutMs = record["timeoutMs"];
 	if (timeoutMs === void 0) return {
 		code,
-		description
+		description,
+		...escalation
 	};
 	if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs) || timeoutMs <= 0) throw new Error("codemode: invalid timeoutMs: expected a positive finite number");
 	return {
 		code,
 		description,
-		timeoutMs
+		timeoutMs,
+		...escalation
 	};
 }
 /** 子调用参数必须是可无损 JSON 化的值。 */
@@ -1307,14 +1496,161 @@ function isConcurrencySafe(entry, args) {
 		return false;
 	}
 }
-/** 一个 FIFO 互斥段：写类调用串行执行。 */
-function createMutex() {
-	let tail = Promise.resolve();
-	return { run(task) {
-		const next = tail.then(task, task);
-		tail = next.catch(() => void 0);
-		return next;
-	} };
+/**
+* 子调用并发与互斥调度器（对齐内核 `ptc.ts` 的读写屏障）：
+*
+* - `parallel` 调用可并发重叠，最多 `maxParallel` 个同时在飞；
+* - `exclusive` 调用必须等待所有已在飞调用结算后独占运行，并在自身结算后才放行后续调用；
+* - 排队期间若外层运行已中止，直接放弃且不启动任务（保证未启动调用零 `start` 事件）；
+* - `drain()` 等待全部已启动任务结算。
+*/
+function createSubCallScheduler(maxParallel, isAborted) {
+	const cap = Math.max(1, maxParallel);
+	const queue = [];
+	const inFlight = /* @__PURE__ */ new Set();
+	let exclusiveActive = false;
+	const pump = () => {
+		while (queue.length > 0) {
+			const head = queue[0];
+			if (isAborted()) {
+				queue.shift();
+				head.abandon();
+				continue;
+			}
+			if (exclusiveActive) return;
+			if (head.mode === "exclusive") {
+				if (inFlight.size > 0) return;
+				exclusiveActive = true;
+				queue.shift();
+				head.start();
+				return;
+			}
+			if (inFlight.size >= cap) return;
+			queue.shift();
+			head.start();
+		}
+	};
+	return {
+		schedule(mode, task, onAbandon) {
+			return new Promise((resolve, reject) => {
+				queue.push({
+					mode,
+					abandon() {
+						try {
+							onAbandon();
+						} catch (error) {
+							reject(error);
+						}
+					},
+					start() {
+						const tracked = task().then(resolve, reject).finally(() => {
+							inFlight.delete(tracked);
+							if (mode === "exclusive") exclusiveActive = false;
+							pump();
+						}).then(() => void 0, () => void 0);
+						inFlight.add(tracked);
+					}
+				});
+				pump();
+			});
+		},
+		async drain() {
+			pump();
+			while (inFlight.size > 0) {
+				await Promise.allSettled([...inFlight]);
+				pump();
+			}
+		}
+	};
+}
+const JSON_INDENT = "  ";
+const MAX_JSON_INDENT_CHARS = 10;
+/** 迭代式 JSON 渲染：与内核 `ptc.ts` 一致，深于 5 层后自动紧凑化，防止深层缩进膨胀。 */
+function renderProgramValue(value) {
+	if (typeof value === "string") return value;
+	let normalized;
+	try {
+		normalized = JSON.parse(JSON.stringify(value));
+	} catch {
+		return String(value);
+	}
+	if (typeof normalized === "string") return normalized;
+	if (normalized === void 0) return "";
+	const chunks = [];
+	const tasks = [{
+		kind: "value",
+		value: normalized,
+		depth: 0,
+		compact: false
+	}];
+	for (let task = tasks.pop(); task !== void 0; task = tasks.pop()) {
+		if (task.kind === "text") {
+			chunks.push(task.text);
+			continue;
+		}
+		const current = task.value;
+		if (current === null || typeof current === "boolean" || typeof current === "number") {
+			chunks.push(String(current));
+			continue;
+		}
+		if (typeof current === "string") {
+			chunks.push(JSON.stringify(current));
+			continue;
+		}
+		const compact = task.compact || (task.depth + 1) * 2 > MAX_JSON_INDENT_CHARS;
+		const childDepth = task.depth + 1;
+		if (Array.isArray(current)) {
+			chunks.push("[");
+			if (current.length === 0) {
+				chunks.push("]");
+				continue;
+			}
+			tasks.push({
+				kind: "text",
+				text: compact ? "]" : `\n${JSON_INDENT.repeat(task.depth)}]`
+			});
+			for (let index = current.length - 1; index >= 0; index -= 1) {
+				tasks.push({
+					kind: "value",
+					value: current[index],
+					depth: childDepth,
+					compact
+				});
+				tasks.push({
+					kind: "text",
+					text: compact ? index === 0 ? "" : "," : `${index === 0 ? "\n" : ",\n"}${JSON_INDENT.repeat(childDepth)}`
+				});
+			}
+			continue;
+		}
+		if (typeof current === "object") {
+			const record = current;
+			const keys = Object.keys(record);
+			chunks.push("{");
+			if (keys.length === 0) {
+				chunks.push("}");
+				continue;
+			}
+			tasks.push({
+				kind: "text",
+				text: compact ? "}" : `\n${JSON_INDENT.repeat(task.depth)}}`
+			});
+			for (let index = keys.length - 1; index >= 0; index -= 1) {
+				const key = keys[index];
+				tasks.push({
+					kind: "value",
+					value: record[key],
+					depth: childDepth,
+					compact
+				});
+				tasks.push({
+					kind: "text",
+					text: compact ? `${index === 0 ? "" : ","}${JSON.stringify(key)}:` : `${index === 0 ? "\n" : ",\n"}${JSON_INDENT.repeat(childDepth)}${JSON.stringify(key)}: `
+				});
+			}
+		}
+	}
+	return chunks.join("");
 }
 //#endregion
 //#region src/entry-codemode.ts
@@ -1348,6 +1684,11 @@ const name = "codemode";
 const inject = ["tools", "systemPrompt"];
 /** 决策环长度：只留给 `code_debug`。 */
 const DEBUG_RING = 50;
+/** 严格加宽阶梯（对齐 `@deepseek-ai/dsh-sandbox` 的 `WIDER_MODES`）。 */
+const WIDER_SANDBOX_MODES = {
+	"read-only": ["workspace-write", "danger-full-access"],
+	"workspace-write": ["danger-full-access"]
+};
 /**
 * 装配本行。
 *
@@ -1409,12 +1750,50 @@ function apply(ctx, config = {}) {
 	let catalog = [];
 	const debugRing = [];
 	let firstDescribeLogged = false;
+	const escalateSandbox = async (input) => {
+		const record = typeof input.standingPolicy === "object" && input.standingPolicy !== null ? input.standingPolicy : void 0;
+		const effectiveMode = typeof record?.["mode"] === "string" ? record["mode"] : void 0;
+		if (record === void 0 || effectiveMode === void 0) throw new Error("sandbox_permissions is not available for this PTC runtime");
+		if (input.requestedMode === effectiveMode) return input.standingPolicy;
+		if (!(WIDER_SANDBOX_MODES[effectiveMode] ?? []).includes(input.requestedMode)) throw new Error(`sandbox escalation to "${input.requestedMode}" is not strictly wider than this call's current "${effectiveMode}" mode`);
+		const approver = serviceOf("approval");
+		if (typeof approver?.request !== "function") throw new Error(`sandbox escalation to "${input.requestedMode}" requires approval, but no approval service is composed`);
+		if (input.agent === void 0) throw new Error(`sandbox escalation to "${input.requestedMode}" requires approval, but the call has no agent to route it through`);
+		const outcome = await approver.request({
+			agent: input.agent,
+			toolName: input.toolName,
+			callId: input.callId,
+			reason: `escalate sandbox to ${input.requestedMode}: ${input.justification}`,
+			displayReason: {
+				en: `Allow this program to run once with ${input.requestedMode} access: ${input.justification}`,
+				zh: `允许本次程序以 ${input.requestedMode} 权限单次运行：${input.justification}`
+			},
+			signal: input.signal
+		});
+		switch (outcome) {
+			case "allowed-once": return {
+				...record,
+				mode: input.requestedMode
+			};
+			case "rejected": throw new Error(`the user rejected escalating this program to "${input.requestedMode}"; it stays denied, so stop and explain instead of working around it`);
+			case "cancelled": throw new Error(`approval for escalating to "${input.requestedMode}" was cancelled`);
+			case "unavailable": throw new Error(`sandbox escalation to "${input.requestedMode}" requires approval, but no approval channel is available`);
+			default: throw new Error(`unexpected approval outcome: ${String(outcome)}`);
+		}
+	};
 	const host = {
 		catalog: () => catalog,
 		runtime: runtimeOf,
 		stateOwner: (agent) => retention.owner(agent),
 		releaseOwner: (owner) => retention.release(owner),
 		runAuthority,
+		escalateSandbox,
+		createImageContext(content) {
+			return createUserMessage({
+				content,
+				source: { kind: PLUGIN_MESSAGE_SOURCE_KIND }
+			});
+		},
 		async callTool(request) {
 			const call = {
 				type: "tool-call",
@@ -1436,16 +1815,20 @@ function apply(ctx, config = {}) {
 			const result = batch.results?.[0]?.result;
 			if (result === void 0) return { error: "sub-call produced no result" };
 			const content = result.content ?? [];
+			const additionalContexts = Array.isArray(batch.additionalContexts) && batch.additionalContexts.length > 0 ? batch.additionalContexts : void 0;
 			if (result.isError === true) return {
 				error: errorTextOf(result),
 				content,
-				...errorInfoOf(result)
+				...errorInfoOf(result),
+				...additionalContexts === void 0 ? {} : { additionalContexts }
 			};
 			const meta = result.meta;
 			return {
 				...result.value !== void 0 ? { value: result.value } : { text: textOf(result.content) },
 				content,
-				...meta === void 0 ? {} : { meta }
+				...meta === void 0 ? {} : { meta },
+				...additionalContexts === void 0 ? {} : { additionalContexts },
+				...batch.concluded === true ? { concluded: true } : {}
 			};
 		}
 	};
@@ -1461,11 +1844,15 @@ function apply(ctx, config = {}) {
 		delegate,
 		view,
 		viewForName: (toolName) => resolveNameView(tools, scopeKey, toolName),
-		sectionText: () => buildCodemodeSectionText({
-			runToolName: rules.options.runToolName,
-			metaTools: rules.options.metaTools,
-			programFormat: runtimeOf()?.programFormat
-		}),
+		sectionText: () => {
+			const runtime = runtimeOf();
+			return buildCodemodeSectionText({
+				runToolName: rules.options.runToolName,
+				metaTools: rules.options.metaTools,
+				language: runtime?.language,
+				programFormat: runtime?.programFormat
+			});
+		},
 		onCatalog: (definitions) => {
 			catalog = definitions.map(toCatalogEntry).filter((entry) => entry !== void 0);
 		},