@eddyskywalker/dsh-chatgpt-subscription 0.59.0 → 0.61.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
@@ -110,13 +112,19 @@ function searchDefinition(name, rules, catalog) {
 							additionalProperties: false,
 							required: [
 								"name",
+								"namespace",
 								"description",
 								"parameters"
 							],
 							properties: {
 								name: { type: "string" },
+								namespace: {
+									type: "string",
+									description: "Namespace of the tool: an MCP server name, or \"plugin\"."
+								},
 								description: { type: "string" },
-								parameters: {}
+								parameters: {},
+								output: { description: "The tool's declared output schema, when it has one." }
 							}
 						}
 					}
@@ -124,7 +132,7 @@ function searchDefinition(name, rules, catalog) {
 			},
 			render: (_args, value) => [{
 				type: "text",
-				text: value.tools.length === 0 ? "No tool matched that query, and this session has no tools to browse." : (value.fallback === true ? "No exact match. These are the callable tools, grouped by namespace — call one by exact name, or refine the query:" : "") + value.tools.map((hit) => hit.name + "\n  " + hit.description + "\n  parameters: " + safeJson(hit.parameters)).join("\n\n")
+				text: value.tools.length === 0 ? "No tool matched that query, and this session has no tools to browse." : (value.fallback === true ? "No exact match. These are the callable tools, grouped by namespace — call one by exact name, or refine the query:" : "") + value.tools.map((hit) => hit.name + "  [" + hit.namespace + "]\n  " + hit.description + "\n  parameters: " + safeJson(hit.parameters) + (hit.output === void 0 ? "" : "\n  output: " + safeJson(hit.output))).join("\n\n")
 			}]
 		},
 		async execute(args) {
@@ -149,8 +157,10 @@ function searchDefinition(name, rules, catalog) {
 			const hits = scored.slice(0, limit);
 			if (hits.length > 0) return { tools: hits.map((row) => ({
 				name: row.indexed.entry.name,
+				namespace: namespaceOfName(row.indexed.entry.name),
 				description: clip(row.indexed.entry.description),
-				parameters: row.indexed.entry.parameters
+				parameters: row.indexed.entry.parameters,
+				...row.indexed.entry.output === void 0 ? {} : { output: row.indexed.entry.output }
 			})) };
 			return {
 				tools: browseByNamespace(candidates, limit),
@@ -181,13 +191,15 @@ function describeDefinition(name, catalog) {
 				properties: {
 					found: { type: "boolean" },
 					name: { type: "string" },
+					namespace: { type: "string" },
 					description: { type: "string" },
-					parameters: {}
+					parameters: {},
+					output: { description: "The tool's declared output schema, when it has one." }
 				}
 			},
 			render: (_args, value) => [{
 				type: "text",
-				text: value.found !== true ? "No tool named that is callable from this session." : String(value.name) + "\n" + String(value.description) + "\nparameters: " + safeJson(value.parameters)
+				text: value.found !== true ? "No tool named that is callable from this session." : String(value.name) + "  [" + String(value.namespace) + "]\n" + String(value.description) + "\nparameters: " + safeJson(value.parameters) + (value.output === void 0 ? "" : "\noutput: " + safeJson(value.output))
 			}]
 		},
 		async execute(args) {
@@ -198,8 +210,10 @@ function describeDefinition(name, catalog) {
 			return {
 				found: true,
 				name: entry.name,
+				namespace: namespaceOfName(entry.name),
 				description: clip(entry.description),
-				parameters: entry.parameters
+				parameters: entry.parameters,
+				...entry.output === void 0 ? {} : { output: entry.output }
 			};
 		}
 	};
@@ -270,8 +284,10 @@ function browseByNamespace(entries, limit) {
 		if (rows.length >= limit) return rows;
 		rows.push({
 			name: entry.name,
+			namespace,
 			description: clip(namespace + ": " + entry.description),
-			parameters: entry.parameters
+			parameters: entry.parameters,
+			...entry.output === void 0 ? {} : { output: entry.output }
 		});
 	}
 	return rows;
@@ -448,10 +464,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 +486,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 +511,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 +583,7 @@ function summarizeHidden(names) {
 *
 * ## 恒定契约
 *
-* 这段正文**只**依赖入参里的两个工具名与部署级的 `programFormat`。它刻意不含遮蔽
+* 这段正文**只**依赖入参里的两个工具名与部署级的 `language` / `programFormat`。它刻意不含遮蔽
 * 工具的数量、namespace 分布、会话 id 或时间，因此同一部署下逐字节恒定：挂载或卸载
 * MCP 服务端不会改写它，前缀缓存不会因为它失效。
 *
@@ -569,34 +591,51 @@ 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",
+		"found = await tools.glob({\"pattern\": \"src/**/*.ts\"})",
+		"pages = await asyncio.gather(*(tools.read({\"file_path\": p}) for p in found[\"paths\"]))",
+		"[l[\"text\"] for page in pages for l in page[\"lines\"] if \"TODO\" in l[\"text\"]]",
+		"```"
+	] : [
+		"```js",
+		"// standard tools and hidden tools alike",
+		"const { paths } = await tools.glob({ pattern: \"src/**/*.ts\" })",
+		"const pages = await Promise.all(paths.map((p) => tools.read({ file_path: p })))",
+		retained ? "pages.flatMap((r) => r.lines.filter((l) => l.text.includes(\"TODO\")).map((l) => l.text))" : "return pages.flatMap((r) => r.lines.filter((l) => l.text.includes(\"TODO\")).map((l) => l.text))",
+		"```"
+	];
 	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.",
+		"- File, search, and shell tool results are named-field objects, never bare strings (whereas `job_list` returns a bare array): `glob` answers `{ root, paths }`, `grep` answers `{ matches }` with matches shaped `{ path, lineNumber, line }`, `read` answers `{ path, offset, lines, totalLines }` with `lines` items shaped `{ number, text }`, and `win_bash` answers `{ stdout, stderr, exitCode }`. A named-field object carries its list or text inside those fields — `r.lines.map((l) => l.text)` — so never call `.map`, `.filter`, `.split`, `.splitlines` or `in` on the envelope itself.",
+		"- Discovery returns whole objects too: `" + listTool + "` answers `{ tools: [{ name, description, namespace }] }`, `" + searchTool + "` answers `{ tools: [{ name, namespace, description, parameters, output? }], fallback? }`, and `" + describeTool + "` answers `{ found, name?, namespace?, description?, parameters?, output? }`.",
+		"- Tool argument objects and `return` values must be lossless JSON: **never leave `undefined` in an object property value** — `{ a: x.opt }` fails the call when `x.opt === undefined`. Omit the key, write `x.opt ?? null`, or print it with `console.log`.",
+		"- 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.",
 		"",
 		"### Discovery API (callable from inside a program)",
 		"",
 		"- tools." + listTool + "({ namespace? }) - every callable tool as { name, description, namespace }, hidden ones included.",
-		"- tools." + searchTool + "({ query, limit?, namespace? }) - ranked matches with their full parameter schemas; the intended first step. Query with the English keywords the tool is likely named and described with (tool names and descriptions are English); a phrase in another language is only matched literally.",
-		"- tools." + describeTool + "({ name }) - one tool description and complete parameter schema.",
+		"- tools." + searchTool + "({ query, limit?, namespace? }) - ranked matches with their full parameter schemas and output schema when the tool declares one; the intended first step. Query with the English keywords the tool is likely named and described with (tool names and descriptions are English); a phrase in another language is only matched literally.",
+		"- tools." + describeTool + "({ name }) - one tool description, its complete parameter schema, and its output schema when declared.",
 		"",
 		"If a hidden tool name is called directly instead of from a program, the call is refused and the refusal names the discovery call to make."
 	].join("\n");
@@ -782,6 +821,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 +1018,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 +1051,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 +1133,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,120 +1154,275 @@ 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 lane = createCommitLane(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();
-						let outcome;
-						try {
-							outcome = await host.callTool({
-								name: entry.name,
-								args: parsed,
-								callId,
-								signal: nestedSignal,
+					const mode = isConcurrencySafe(definitions.get(entry.name), parsed) ? "parallel" : "exclusive";
+					return lane.schedule(mode, {
+						start() {
+							dispatchLog.start();
+						},
+						body: async () => await host.callTool({
+							name: entry.name,
+							args: parsed,
+							callId,
+							signal: nestedSignal,
+							agent: exec.agent,
+							toolSet: exec.toolSet
+						}),
+						/**
+						* 提交阶段：按**提交顺序**逐条执行，落在会话里的副作用因此与提交顺序一致。
+						*
+						* 内核把这几步全部放在同一条有序 lane 里（`ptc.ts` 的 commit 游标）：回放内容
+						* 投影、settle 事件、图片与附加上下文、`concludeTurn`、放行互斥屏障。并发的
+						* body 谁先跑完都不影响这一串的顺序——否则界面里的子调用记录会错位，延迟上下文
+						* 也会插到错误的位置。
+						*/
+						async commit(parked) {
+							if (!parked.ok) {
+								dispatchLog.settle({ error: messageOf$1(parked.error) });
+								throw parked.error;
+							}
+							const outcome = parked.value;
+							const isError = outcome.error !== void 0;
+							const content = await shapeDispatchContent(host, {
 								agent: exec.agent,
-								toolSet: exec.toolSet
+								name: entry.name,
+								arguments: loggedArgs,
+								isError,
+								content: clipContent(outcome.content)
 							});
-						} catch (error) {
-							dispatchLog.settle({ error: error instanceof Error ? error.message : String(error) });
-							throw error;
+							dispatchLog.settle({
+								...outcome,
+								content
+							});
+							if (!isError && 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 (!isError && 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;
+						},
+						abandon() {
+							throw new Error(runToolName + " run is over; " + entry.name + " tool call abandoned");
 						}
-						dispatchLog.settle(outcome);
-						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);
+					});
 				};
+				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;
+				/** 这次运行在入口那边的登记；结算时释放（重跑会重新登记一次）。 */
+				let untrackRun = () => {};
+				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);
+					}
+					untrackRun();
+					const runMode = modeOfPolicy(effectivePolicy);
+					untrackRun = host.trackRun?.({
+						agent: exec.agent,
+						controller: runController,
+						...runMode === void 0 ? {} : { mode: runMode }
+					}) ?? (() => {});
+					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 lane.drain();
+					untrackRun();
+				}
+				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 +1433,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;
@@ -1223,7 +1458,7 @@ function createDispatchLog(agent, entry) {
 			write("tool/ptc-dispatch", {
 				...base,
 				isError: outcome.error !== void 0,
-				content: clipContent(outcome.content),
+				content: Array.isArray(outcome.content) ? outcome.content : [],
 				...outcome.meta === void 0 ? {} : { meta: outcome.meta },
 				...outcome.errorInfo === void 0 ? {} : { error: outcome.errorInfo }
 			});
@@ -1232,12 +1467,6 @@ function createDispatchLog(agent, entry) {
 }
 /**
 * 把内容块裁到日志能承受的长度。
-*
-* 程序本身拿到的值不受影响；这里只是回放副本，所以宁可截断也不让一条子调用把整份
-* 大文件写进会话记录。
-*
-* @param content - 原始内容块。
-* @returns 可写进事件的副本。
 */
 function clipContent(content) {
 	if (content === void 0) return [];
@@ -1254,12 +1483,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,24 +1492,42 @@ 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");
 	const record = args;
 	const code = record["code"];
 	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 code !== "string" || code.trim().length === 0) {
+		const received = Object.keys(record);
+		throw new Error("codemode: invalid code: expected a non-empty string" + (received.length === 0 ? "" : " (received keys: " + received.join(", ") + "; pass program source in \"code\")"));
+	}
 	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 +1548,246 @@ 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` 的 ordered commit lane）。
+*
+* - `start()`（记 start 事件 + 启动 body）在 lane 里按提交顺序执行：`parallel` body 之间
+*   可以并发重叠，最多 `maxParallel` 个同时在飞；
+* - `commit()`（记 settle 事件 + 转发图片/附加上下文 + `concludeTurn` + 放行互斥屏障）
+*   按**提交顺序**逐条执行：前一条没提交完，后一条的结果不会先落到会话里；
+* - `exclusive` 调用等所有在飞 body 结算后独占运行，并独占到自己 commit 完成才放行后续；
+* - 排队期间若外层运行已中止，直接放弃且不启动任务（未启动调用零 `start` 事件）；
+* - `drain()` 等到 lane 彻底静止（所有 body 结算、所有 commit 完成）才返回。
+*
+* 程序拿到的值在 commit 里结算（与内核同）：body 结束不保证顺序，提交才是顺序。
+*
+* @param maxParallel - 同时在飞的上限。
+* @param isAborted - 外层运行是否已中止。
+* @returns 调度入口与排空。
+*/
+function createCommitLane(maxParallel, isAborted) {
+	const cap = Math.max(1, maxParallel);
+	const queue = [];
+	const commitQueue = [];
+	const inFlight = /* @__PURE__ */ new Set();
+	let exclusiveActive = false;
+	let driving = false;
+	let driverRun = Promise.resolve();
+	let wake;
+	const wakeup = () => {
+		const release = wake;
+		wake = void 0;
+		release?.();
+	};
+	/**
+	* 唯一的有序车道：每一轮先提交队首已结算的调用，再在有空位时启动下一个排队调用，
+	* 否则睡到「有 body 结算或有新提交」为止。三条队列全空即静止。
+	*/
+	const drive = () => {
+		if (driving) return driverRun;
+		driving = true;
+		driverRun = (async () => {
+			try {
+				for (;;) {
+					const signal = new Promise((resolve) => {
+						wake = resolve;
+					});
+					const commitHead = commitQueue[0];
+					if (commitHead !== void 0 && commitHead.settled) {
+						commitQueue.shift();
+						await commitHead.commit();
+						if (commitHead.mode === "exclusive") exclusiveActive = false;
+						continue;
+					}
+					const head = queue[0];
+					if (head !== void 0) {
+						if (isAborted()) {
+							queue.shift();
+							head.abandon();
+							continue;
+						}
+						if (!exclusiveActive && (head.mode === "exclusive" ? inFlight.size === 0 : inFlight.size < cap)) {
+							if (head.mode === "exclusive") exclusiveActive = true;
+							queue.shift();
+							commitQueue.push(head);
+							head.start();
+							const flight = head.flight.finally(() => {
+								inFlight.delete(flight);
+								wakeup();
+							});
+							inFlight.add(flight);
+							continue;
+						}
+					}
+					if (queue.length === 0 && commitQueue.length === 0 && inFlight.size === 0) return;
+					await signal;
+				}
+			} finally {
+				driving = false;
+				wake = void 0;
+			}
+		})();
+		return driverRun;
+	};
+	return {
+		schedule(mode, task) {
+			return new Promise((resolve, reject) => {
+				let parked;
+				const entry = {
+					mode,
+					settled: false,
+					flight: Promise.resolve(),
+					start() {
+						task.start();
+						entry.flight = (async () => {
+							try {
+								parked = {
+									ok: true,
+									value: await task.body()
+								};
+							} catch (error) {
+								parked = {
+									ok: false,
+									error
+								};
+							}
+							entry.settled = true;
+							wakeup();
+						})();
+					},
+					async commit() {
+						const result = parked;
+						if (result === void 0) return;
+						try {
+							resolve(await task.commit(result));
+						} catch (error) {
+							reject(error);
+						}
+					},
+					abandon() {
+						try {
+							task.abandon();
+						} catch (error) {
+							reject(error);
+						}
+					}
+				};
+				queue.push(entry);
+				wakeup();
+				drive();
+			});
+		},
+		async drain() {
+			await drive();
+		}
+	};
+}
+/**
+* 回放内容的投影：先按日志上限裁剪，再交给入口的 `tools/ptc-dispatch-log` 瀑布。
+*
+* 瀑布失败**不**影响这条记录：回落裁剪后的原始内容（内核 `ptc.ts` 同此）。
+*/
+async function shapeDispatchContent(host, dispatch) {
+	if (typeof host.shapeDispatchLog !== "function") return dispatch.content;
+	try {
+		const shaped = await host.shapeDispatchLog(dispatch);
+		return Array.isArray(shaped) ? shaped : dispatch.content;
+	} catch {
+		return dispatch.content;
+	}
+}
+/** 一个抛出值的消息。 */
+function messageOf$1(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+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 +1821,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"]
+};
 /**
 * 装配本行。
 *
@@ -1403,18 +1881,128 @@ function apply(ctx, config = {}) {
 	if (typeof context.effect === "function") context.effect(() => () => {
 		retention.dispose();
 	}, "codemode retained environments");
+	/** 在飞运行：会话键 → 该会话里正在跑的程序。 */
+	const activeRuns = /* @__PURE__ */ new Map();
+	/**
+	* 登记一只在飞运行，返回运行结算时的 disposer。
+	*
+	* 传输层每轮运行（含常驻环境换策略后的重跑）都登记一次，入口因此知道「这一轮跑在哪个
+	* 会话、当时的沙箱模式是什么」。会话切模式时，模式不匹配的运行必须停：常驻环境换策略
+	* 会抛错，而已经跑起来的那一轮不能继续用旧权限往下写。
+	*/
+	const trackRun = (run) => {
+		const key = sessionKeyOf(run.agent);
+		if (key === void 0) return () => void 0;
+		const record = {
+			controller: run.controller,
+			...run.mode === void 0 ? {} : { mode: run.mode }
+		};
+		let bucket = activeRuns.get(key);
+		if (bucket === void 0) {
+			bucket = /* @__PURE__ */ new Set();
+			activeRuns.set(key, bucket);
+		}
+		bucket.add(record);
+		return () => {
+			const current = activeRuns.get(key);
+			if (current === void 0) return;
+			current.delete(record);
+			if (current.size === 0) activeRuns.delete(key);
+		};
+	};
+	/**
+	* 会话的 `sandbox/mode` 事件：生效模式已经变了的在飞运行直接取消（内核 `PtcCalls` 同此）。
+	*
+	* 只取消「能确认模式变了」的那些：拿不到模式（运行时不管沙箱）或模式相同的运行一律不动。
+	*/
+	const cancelOnModeChange = (session, event) => {
+		if (typeof event !== "object" || event === null) return;
+		const record = event;
+		if (record.type !== "sandbox/mode") return;
+		const mode = (typeof record.data === "object" && record.data !== null ? record.data : void 0)?.mode;
+		if (typeof mode !== "string") return;
+		const key = sessionKeyOf(session);
+		if (key === void 0) return;
+		for (const run of activeRuns.get(key) ?? []) if (run.mode !== void 0 && run.mode !== mode) run.controller.abort(/* @__PURE__ */ new Error("sandbox mode changed"));
+	};
+	if (typeof context.on === "function") try {
+		const off = context.on("session/event", cancelOnModeChange, { global: true });
+		if (typeof context.effect === "function") context.effect(() => () => {
+			if (typeof off === "function") off();
+		}, "codemode sandbox mode cancellation");
+	} catch (error) {
+		log("warn", "[codemode] could not subscribe to session/event; an in-flight code_run keeps running after the session sandbox mode changes: " + messageOf(error));
+	}
+	/**
+	* 把一条子调用回放记录交给 `tools/ptc-dispatch-log` 瀑布（内核 `ptc.ts` 的同名钩子）。
+	*
+	* 监听器的失败必须在这里吞掉：它决定的只是日志副本长什么样，不是程序拿到的结果。内核
+	* 用 `scopeTarget(tools, agent)` 当接收方；本包不依赖 `@deepseek-ai/dsh-scope`，直接以
+	* `tools` 为接收方——作用域过滤由宿主自己的监听器完成。
+	*/
+	const shapeDispatchLog = async (dispatch) => {
+		const waterfall = context.waterfall;
+		if (typeof waterfall !== "function") return dispatch.content;
+		try {
+			const shaped = await waterfall.call(context, tools, "tools/ptc-dispatch-log", dispatch, () => Promise.resolve(dispatch.content));
+			return Array.isArray(shaped) ? shaped : dispatch.content;
+		} catch (error) {
+			log("warn", "tools: ptc-dispatch-log listener failed for " + dispatch.name + ": " + messageOf(error) + "; logging the original settled content");
+			return dispatch.content;
+		}
+	};
 	const scopeKey = findScopeKey(ctx);
 	if (rules.options.nativeScope && scopeKey === void 0) log("warn", "[codemode] no registry scope tag on this context: masking falls back to name rules only (" + rules.options.hiddenPrefixes.join(", ") + "). Mount this row inside an agent preset to hide every tool the preset does not own.");
 	/** 最近一次 describe 收到的完整定义集（含被遮蔽的）。 */
 	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 }
+			});
+		},
+		trackRun,
+		shapeDispatchLog,
 		async callTool(request) {
 			const call = {
 				type: "tool-call",
@@ -1436,16 +2024,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 +2053,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);
 		},
@@ -1497,10 +2093,13 @@ function toCatalogEntry(definition) {
 	if (typeof toolName !== "string" || toolName.length === 0) return void 0;
 	const description = typeof record["description"] === "string" ? record["description"] : "";
 	const safe = record["isConcurrencySafe"];
+	const declaredOutput = record["output"];
+	const output = typeof declaredOutput === "object" && declaredOutput !== null ? declaredOutput.schema : void 0;
 	return {
 		name: toolName,
 		description,
 		parameters: record["parameters"],
+		...output === void 0 ? {} : { output },
 		...typeof safe === "function" ? { isConcurrencySafe: safe } : {}
 	};
 }
@@ -1546,6 +2145,24 @@ function errorInfoOf(result) {
 function nonEmptyString(value) {
 	return typeof value === "string" && value.length > 0 ? value : void 0;
 }
+/**
+* 一个会话的身份键。
+*
+* 优先用会话 id（与内核 `session/event` 监听器里的 `session.id` 对齐）；取不到 id 时退回
+* 会话对象本身——调用方 agent 上的 `session` 与事件里的会话是同一个对象，靠身份比对同样
+* 成立。连会话都没有时返回 `undefined`，这类运行不参与取消。
+*
+* @param value - 一个 agent，或一个会话对象。
+* @returns 会话 id / 会话对象，或 `undefined`。
+*/
+function sessionKeyOf(value) {
+	if (typeof value !== "object" || value === null) return void 0;
+	const nested = value.session;
+	const session = typeof nested === "object" && nested !== null ? nested : value;
+	const id = session.id;
+	if (typeof id === "string" && id.length > 0) return id;
+	return session;
+}
 /** 把内容块里的文本拼起来。 */
 function textOf(content) {
 	if (!Array.isArray(content)) return "";