pi-ptc-subagents 7.1.0 → 7.2.0

package/README.md

@@ -1,23 +1,29 @@
 # pi-ptc-subagents
 
-Programmable tool calling and subagent dispatch for [pi](https://pi.dev) — and a [Kimi Code](https://www.kimi.com/code) plugin (`ptc-tools`, MCP) that brings the same "write one program, batch-call your tools" to Kimi sessions. The npm package name is the pi-face distribution; the Kimi face ships from this repo's releases.
+Programmable tool calling and subagent dispatch for [pi](https://pi.dev) — and a
+[Kimi Code](https://www.kimi.com/code) plugin (`ptc-tools`, MCP) that brings the same
+"write one program, batch-call your tools" to Kimi sessions. The npm package covers pi;
+the Kimi Code plugin ships from this repo's GitHub Releases.
 
-pi calls tools one at a time. This package lets the model write a program that calls them
-in one go — and lets that program spawn pi subagents. Two capabilities. One package.
+pi calls tools one at a time. On pi, the model writes a program that calls them in one
+go — and can spawn pi subagents from inside it. On Kimi Code, the plugin gives the model
+one program tool over a fixed file-tool set.
 
 ```
-full_ptc      model ──▶ ptc_run_code ──▶ program ──┬──▶ tools.read · grep · edit · …   (session tools)
-                                                   └──▶ pi_task_ptc ──▶ pi child ──▶ report
+on pi
+  full_ptc      model ──▶ ptc_run_code ──▶ program ──┬──▶ tools.read · grep · edit · …   (session tools)
+                                                     └──▶ pi_task_ptc ──▶ pi child ──▶ report
 
-codemode_ptc  model ──▶ codemode script ───────────┬──▶ tools.read · grep · edit · …   (session tools)
-                                                   └──▶ pi_task_codemode ──▶ pi child ──▶ report
+  codemode_ptc  model ──▶ codemode script ───────────┬──▶ tools.read · grep · edit · …   (session tools)
+                                                     └──▶ pi_task_codemode ──▶ pi child ──▶ report
 
-                                        one call in, one result back — never the calls in between.
-```
+on kimi (MCP)
+                model ──▶ ptc_run_code ──▶ program ──────▶ tools.read · grep · glob · edit   (fs 四件套, workdir-locked)
 
-Both surfaces are detected from the session. There is no setting.
+                                          one call in, one result back — never the calls in between.
+```
 
-## What you get
+## On pi
 
 - **One program, many tool calls.** `ptc_run_code` and `ptc_workflow` run TypeScript in a
   worker. The program uses the session's tools as `tools.read(...)`, `tools.grep(...)`.
@@ -30,8 +36,6 @@ Both surfaces are detected from the session. There is no setting.
 - **Search, where it belongs.** `web_ds_search` registers only inside dispatched children.
   Off by default.
 
-A call looks like this — the same shape on both surfaces:
-
 ```ts
 // full_ptc, inside ptc_run_code
 const r = await tools.pi_task_ptc({ task: "audit the auth code", wait: true });
@@ -42,7 +46,42 @@ const r = await tools.pi_task_codemode({ task: "audit the auth code", wait: true
 return r.report?.summary ?? r.text;
 ```
 
-## Install
+### Surfaces
+
+- **`full_ptc`** — the PTC pair is model-facing. Programs reach tasks with `pi_task_ptc`.
+- **`codemode_ptc`** — pi's codemode orchestrates. Scripts reach tasks with
+  `pi_task_codemode`; the PTC pair is not registered at all.
+
+Which one you get depends on whether `codemode` is loaded and callable. Nothing to configure.
+
+### PTC mode
+
+On a `full_ptc` session, PTC mode adds a routing lead to the system prompt: batch your
+tool calls into one program. `/ptc off` drops the lead.
+
+It does not hide the built-in tools from the model. pi keeps a tool callable from a
+program only while it is active, so narrowing the loadout would take `tools.read` away
+from the program too — the two cannot both hold on pi 1.4.0.
+
+## The Kimi Code plugin (`ptc-tools`)
+
+Two MCP tools; the host's own tools remain the orchestrator (no subagent door here —
+Kimi Code ships its own Agent tool, so this plugin doesn't duplicate one):
+
+- **`ptc_run_code({ code, description, workdir, timeoutMs? })`** — a TypeScript program in
+  the same vm cell as on pi, over a fixed tool set: `read` / `grep` / `glob` / `edit`.
+  Every path is realpath-checked and confined to `workdir`; `edit` lands atomically and
+  requires a unique `old_string`. No `bash`, no task dispatch inside the program.
+- **`web_ds_search`** — search / open / find, callable directly (no child process needed).
+  Quota is per MCP server process (default 30 calls, `0` = unlimited); the DeepSeek key
+  resolves from env, then Kimi Code's `config.toml`.
+
+Install with `/plugins install https://github.com/a1121611810/pi-ptc-subagents` — the bare repo
+URL tracks the latest GitHub Release (pinned URLs get no update checks); run `/reload` to
+activate. A bundled `ptc` skill teaches the model when to write a program instead of
+fanning out tool calls one by one.
+
+## Install (pi)
 
 ```bash
 pi install npm:pi-ptc-subagents
@@ -60,24 +99,9 @@ To run one build without touching your settings:
 pi -ne -e packages/entry/dist/index.js
 ```
 
-## Surfaces
-
-- **`full_ptc`** — the PTC pair is model-facing. Programs reach tasks with `pi_task_ptc`.
-- **`codemode_ptc`** — pi's codemode orchestrates. Scripts reach tasks with
-  `pi_task_codemode`; the PTC pair is not registered at all.
-
-Which one you get depends on whether `codemode` is loaded and callable. Nothing to configure.
-
-## PTC mode
+Requires Node ≥ 22.19.
 
-On a `full_ptc` session, PTC mode adds a routing lead to the system prompt: batch your
-tool calls into one program. `/ptc mode off` drops the lead.
-
-It does not hide the built-in tools from the model. pi keeps a tool callable from a
-program only while it is active, so narrowing the loadout would take `tools.read` away
-from the program too — the two cannot both hold on pi 1.4.0.
-
-## Configuration
+## Configuration (pi)
 
 `~/.pi/agent/ptc.json` — all optional:
 
@@ -92,19 +116,29 @@ from the program too — the two cannot both hold on pi 1.4.0.
 
 ## Trust posture
 
-Programs run as you. There is no OS sandbox, and a program's tool calls bypass pi's
-`tool_call` hooks. `bash` is not bound by default.
+Programs run in a vm cell on both editions (ADR-0019, v7.0.0): the only door out is
+`tools.*`, which goes through the same tool pipeline as a direct call. Programs do not
+see `process`, `fetch`, or dynamic `import` — code that used them broke in v7.0.0.
+
+That is an alignment of power paths, not a security boundary. There is still no OS
+sandbox: whatever the bound tools can do, a program can do, and a dispatched child is a
+full pi process running as you. `bash` is not in the program binding table on either edition.
 
 ## Compatibility
 
-pi `>= 0.86.0`. Real-machine smoke tests cover 0.86.0 through 1.4, including a program that
-dispatches a real child process. Details:
-[docs/pi-version-matrix.md](./docs/pi-version-matrix.md).
+pi `>= 0.86.0`, tracked against latest (currently 1.4.0). Two version facts matter:
+
+- **In-program `tools.*` needs pi ≥ 0.99.** On 0.86/0.87 a program still evaluates and can
+  still dispatch a task, but session-tool calls fail with a clear version error. The
+  codemode surface itself also only exists from 0.99.
+- Everything else in the 0.86–1.4 range is covered by real-machine smoke tests, including
+  a program that dispatches a real child process. Per-version details:
+  [docs/pi-version-matrix.md](./docs/pi-version-matrix.md).
 
 ## Documentation
 
 - [AGENTS.md](./AGENTS.md) — how this repository is built and guarded
-- [docs/adr/](./docs/adr/) — decisions, 0001–0015
+- [docs/adr/](./docs/adr/) — decisions, 0001–0020
 - [docs/prototypes/](./docs/prototypes/) — spec and status pages
 - [docs/research/](./docs/research/) — evidence notes
 

package/dist/index.js

@@ -2848,7 +2848,8 @@ var TaskRegistry = class {
 				const next = {
 					...current,
 					report: command.report,
-					reportChannel: command.channel
+					reportChannel: command.channel,
+					delivery: command.delivery ?? current.delivery
 				};
 				this.#records.set(command.id, next);
 				this.#emit(next, current);
@@ -3058,12 +3059,12 @@ var FileOutputStorage = class {
 // ../dispatch/src/report.ts
 const REPORT_CONTRACT_BLOCK = [
 	"<child-report-contract>",
-	"Before finishing, you MUST deliver a child report as a fenced JSON block at the very end of your final message:",
+	"Before finishing, deliver a child report — preferably by calling the ptc_child_report tool (its schema fixes the shape); if that tool is not available, put a fenced JSON block at the very end of your final message:",
 	"```json",
 	"{ \"summary\": \"one sentence conclusion\", \"findings\": [{ \"what\": \"claim\", \"evidence\": \"where it comes from\" }], \"files_touched\": [\"relative/path\"], \"usage\": { \"input\": 0, \"output\": 0, \"cost\": 0, \"turns\": 0 } }",
 	"```",
-	"Rules: \"summary\" is your deliverable — answer the task asked, in one sentence. \"findings\" carries load-bearing evidence only; never recap content you merely read. Do NOT write report/summary .md files — your final message is what the parent reads.",
-	"findings/files_touched/usage may be omitted when empty. Your prose answer stays; the report is checked alongside it.",
+	"Rules: the report is a SUMMARY — it is NOT the deliverable. The deliverable is your prose answer, in exactly the format the task asked for; never hide the deliverable inside the JSON block. \"summary\" is one sentence of conclusion. \"findings\" carries load-bearing evidence only; never recap content you merely read. Do NOT write report/summary .md files — your final message is what the parent reads.",
+	"findings/files_touched/usage may be omitted when empty.",
 	"</child-report-contract>"
 ].join("\n");
 function extractReportFromText(text) {
@@ -3158,6 +3159,7 @@ function buildPiArgv(input, context) {
 		].filter(Boolean).join("\n")
 	];
 	argv.push("--no-extensions", "--no-skills");
+	if (input.projectContext === "none") argv.push("--no-context-files");
 	if (supportsNoMcp(context.piVersion)) argv.push("--no-mcp");
 	const model = input.model ?? input.agentModel ?? context.sessionModel;
 	const thinking = input.thinkingLevel ?? input.agentThinkingLevel;
@@ -3220,12 +3222,16 @@ function findAgent(name, dirs, scope = "both") {
 	return null;
 }
 // ../dispatch/src/jsonl.ts
+const MAX_PATHS = 20;
 function parseChildStream(stdout) {
 	let text = "";
 	let toolReport = null;
 	let observedUsage = null;
 	let observedModel = null;
 	let observedProvider = null;
+	const tools = {};
+	const paths = [];
+	let errors = 0;
 	for (const line of stdout.split("\n")) {
 		const trimmed = line.trim();
 		if (!trimmed.startsWith("{")) continue;
@@ -3235,6 +3241,17 @@ function parseChildStream(stdout) {
 		} catch {
 			continue;
 		}
+		if (event.type === "tool_execution_start") {
+			const name = typeof event.toolName === "string" ? event.toolName : "unknown";
+			tools[name] = (tools[name] ?? 0) + 1;
+			const path = event.args?.path;
+			if (typeof path === "string" && path && !paths.includes(path) && paths.length < MAX_PATHS) paths.push(path);
+			continue;
+		}
+		if (event.type === "tool_execution_end") {
+			if (event.isError === true || event.result?.isError === true) errors++;
+			continue;
+		}
 		if (event.type !== "message_end" || !event.message) continue;
 		const message = event.message;
 		if (message.role === "assistant") {
@@ -3262,7 +3279,13 @@ function parseChildStream(stdout) {
 		toolReport,
 		observedUsage,
 		observedModel,
-		observedProvider
+		observedProvider,
+		delivery: {
+			tools,
+			paths,
+			errors,
+			textChars: text.length
+		}
 	};
 }
 var NotificationCenter = class {
@@ -3367,7 +3390,7 @@ var TaskEngine = class {
 		this.#registry = options.registry;
 		this.#slots = options.slots ?? new DispatchSlotCounter();
 		this.#output = options.output ?? new InMemoryOutputStorage();
-		this.#spawn = options.spawnChild ?? ((argv) => spawnChild(argv));
+		this.#spawn = options.spawnChild ?? ((argv, env) => spawnChild(argv, env));
 		this.#gates = options.gates ?? [];
 		this.#buildArgv = options.buildArgv ?? ((input, context) => buildPiArgv(input, context));
 		this.#resolveAgent = options.resolveAgent ?? (() => null);
@@ -3511,6 +3534,11 @@ var TaskEngine = class {
 		};
 		const child = this.#spawn(argv, env);
 		this.#children.set(taskId, child);
+		const timeoutMs = typeof input.timeoutMs === "number" && input.timeoutMs > 0 ? input.timeoutMs : void 0;
+		const timer = timeoutMs ? setTimeout(() => {
+			this.stop(taskId, `timeout after ${timeoutMs}ms`);
+		}, timeoutMs) : void 0;
+		timer?.unref();
 		let text = "";
 		let outputTruncated = false;
 		child.onOutput((chunk) => {
@@ -3523,6 +3551,7 @@ var TaskEngine = class {
 		const exitCode = await new Promise((resolveExit) => {
 			child.onExit((code) => resolveExit(code));
 		});
+		if (timer) clearTimeout(timer);
 		this.#children.delete(taskId);
 		const outputPath = await this.#output.write(taskId, text);
 		const parsed = parseChildStream(text);
@@ -3538,7 +3567,9 @@ var TaskEngine = class {
 			report = extracted.report ?? void 0;
 			channel = extracted.channel;
 		}
-		if (report && !report.usage && parsed.observedUsage) report = {
+		const selfUsage = report?.usage;
+		const selfUsageEmpty = !selfUsage || !selfUsage.input && !selfUsage.output && !selfUsage.cost;
+		if (report && selfUsageEmpty && parsed.observedUsage) report = {
 			...report,
 			usage: parsed.observedUsage
 		};
@@ -3546,7 +3577,8 @@ var TaskEngine = class {
 			kind: "attach-report",
 			id: taskId,
 			report,
-			channel
+			channel,
+			delivery: parsed.delivery
 		});
 		await this.#registry.submit({
 			kind: "attach-output",
@@ -3582,6 +3614,7 @@ var TaskEngine = class {
 			whySuppressed,
 			report: report ?? void 0,
 			reportChannel: channel,
+			delivery: parsed.delivery,
 			outputTruncated
 		};
 	}
@@ -4246,25 +4279,209 @@ function createWebDsSearchTool(context) {
 		}
 	};
 }
+// ../routes/src/surface.ts
+const FALLBACK_SURFACE_MODE = "full_ptc";
+// ../routes/src/registry.ts
+const TOOLS = {
+	ptc_run_code: {
+		name: "ptc_run_code",
+		description: (s) => ["写一段 TypeScript 程序批量调用工具：tools.<name>(args)。支持顶层 await、Promise.all 并行、循环与条件；程序返回值是归约后的结果，中间产物不进上下文。", s === "codemode_ptc" ? "本会话里我从 codemode 脚本可达，模型直走 codemode。" : [
+			"什么时候写程序而不是逐个调工具，看系统提示词 <ptc> 节的路由表。",
+			"程序内可调本会话已启用的同名工具（read / write / edit / grep / find / ls；bash 默认不可用），参数与直接调用该工具完全一致；每次调用返回 Promise，要 await，返回文本结果，失败抛异常。",
+			"例：const files = await tools.find({ pattern: \"*.py\" }); for (const f of files) await tools.write({ path: f, content: body });"
+		].join("")].join("")
+	},
+	ptc_workflow: {
+		name: "ptc_workflow",
+		description: (s) => ["结构化的多阶段程序：script 里可用 workflow.log / workflow.phase / workflow.parallel / workflow.pipeline。适合阶段明确的批处理。", s === "codemode_ptc" ? "本会话里我从 codemode 脚本可达。" : "与 ptc_run_code 的取舍看 <ptc> 节的路由表。"].join("")
+	},
+	pi_task_codemode: {
+		name: "pi_task_codemode",
+		description: () => "建一条子代理任务，默认立刻返回 handle（taskId + label）；wait:true 时阻塞到终态再返回结果。任务在任务记录里排队，由派发引擎起独立 pi 进程执行；完成后的报告与产出经 ptc_task_output 读取。"
+	},
+	ptc_task_list: {
+		name: "ptc_task_list",
+		description: () => "列出在飞的任务与最近完成的任务（最近 10 条已完成）。"
+	},
+	ptc_task_output: {
+		name: "ptc_task_output",
+		description: () => "按 task_id 读一条任务记录：状态、报告、产出。产出超过截断阈值时给尾部与完整产出位置（outputPath）。"
+	},
+	ptc_task_stop: {
+		name: "ptc_task_stop",
+		description: () => "按 task_id 叫停任务：排队中的直接抽掉（canceled），在跑的转 stopping。"
+	}
+};
+const TASK_DOOR_PARAM_DESCRIPTIONS = {
+	task: "孩子要干的活",
+	agent: "已注册的 agent 名字；省略 = 通用孩子",
+	agentScope: "agent 定义的查找范围（user / project / both）",
+	why: "这一刀为什么切出来（调用方自己的话）——它会进孩子的提示词、多花孩子的 token；孩子从 task 里已经能读懂就别传",
+	model: "覆盖孩子跑的模型",
+	thinkingLevel: "覆盖孩子的思考档位——孩子的思考 token 是可调的成本项",
+	wait: "true = 等这个任务完成再返回结果；false = 立刻返回 handle，结果走任务面/通知",
+	label: "后台任务给人看的标签",
+	readOnly: "strict = 孩子只有读工具（read/grep/find/ls，搜索开启时含 web_ds_search）；lenient = 默认全工具。只需要读的活别给写权限",
+	timeoutMs: "孩子的运行时长上限（毫秒）——超了按超时收尸；不传 = 不限（与不传时同）",
+	projectContext: "孩子的项目上下文（AGENTS.md/CLAUDE.md）：auto = 照常加载；none = 不加载——注意 none 只关「注入」不关「知识」：文件还在工作目录里，孩子会自己去翻（实测输入只差约 15%，不是省一半）；这活不需要项目约定就传 none，要孩子遵守项目规矩就照常传（auto 也可能把项目里的写码规矩套进答案）"
+};
+const DELIVERY_CHECK_LEAD = "交付核对（引擎实测）";
+const DELIVERY_CHECK_NOTHING = "这孩子的结论没有依据：重派它，或明说缺口，别替它补数。";
+/** 父面渲染一行交付核对：工具/路径（实测）· 报错 · 正文长度 · 报告条数（自述） */
+function renderDeliveryCheck(input) {
+	const d = input.delivery;
+	if (!d) return "";
+	const calls = Object.entries(d.tools);
+	const totalCalls = calls.reduce((sum, [, count]) => sum + count, 0);
+	const parts = [];
+	if (calls.length > 0) {
+		const tools = calls.map(([name, count]) => `${name}×${count}`).join(" ");
+		const paths = d.paths.length > 0 ? `（${d.paths.slice(0, 5).join("、")}${d.paths.length > 5 ? ` 等 ${d.paths.length} 条` : ""}）` : "";
+		parts.push(`工具 ${tools}${paths}`);
+	} else parts.push("没调用任何工具");
+	parts.push(`报错 ${d.errors}`);
+	parts.push(`正文 ${d.textChars} 字`);
+	const findings = input.findings ?? 0;
+	parts.push(`报告 ${findings} 条（${input.channel ?? "none"}）`);
+	return totalCalls === 0 && findings === 0 && d.textChars === 0 ? `${DELIVERY_CHECK_LEAD}：零产出——${parts.join(" · ")}。${DELIVERY_CHECK_NOTHING}` : `${DELIVERY_CHECK_LEAD}：${parts.join(" · ")}`;
+}
+const ROUTES = [
+	{
+		id: "create-a-task",
+		name: "派一个子代理",
+		when: "材料多、主题互不相干、每份都要读一堆材料时派——父一个人扛会算错（实测 92%→100%，n=3）；成本 10 倍上下，一件能算完的活别派",
+		how: {
+			full_ptc: "tools.pi_task_ptc({ task, label? })（程序内）——task 是孩子的唯一规格（写死路径/命令/交付物格式）；要报告就点名 child report 的 JSON 块（summary/findings），别自创报告格式；汇总前核对孩子产出（delivery），零产出就重派别补数",
+			codemode_ptc: "tools.pi_task_codemode({ task, label? })（脚本内）——task 是孩子的唯一规格（写死路径/命令/交付物格式）；要报告就点名 child report 的 JSON 块（summary/findings），别自创报告格式；汇总前核对孩子产出（delivery），零产出就重派别补数"
+		},
+		fact: "默认不等，立刻返回 handle；任务在任务记录里排队，可经任务面三工具查/停",
+		detail: "docs/routes/create-a-task.md"
+	},
+	{
+		id: "run-one-program",
+		name: "批量调工具的一段程序",
+		when: "连续多次工具调用、结果要过滤/归约后再看",
+		how: {
+			full_ptc: "ptc_run_code({ code, description })",
+			codemode_ptc: "不适用——写程序是 full_ptc 面的编排能力；本面用 codemode 编排、pi_task_codemode 派任务"
+		},
+		fact: "程序内 tools.*；bash 当前不在程序绑定表里（旧 ADR-0040 的 opt-in 尚未接线）；只在本面（full_ptc）注册 PTC 工具",
+		detail: "docs/routes/run-one-program.md"
+	},
+	{
+		id: "run-a-phased-workflow",
+		name: "分阶段 workflow",
+		when: "批处理有明确阶段，要阶段性可见进度",
+		how: {
+			full_ptc: "ptc_workflow({ meta, script, args? })",
+			codemode_ptc: "不适用——同 run-one-program：workflow 是 full_ptc 的编排能力"
+		},
+		fact: "script 内可用 workflow.log/phase/parallel/pipeline；只在本面注册",
+		detail: "docs/routes/run-a-phased-workflow.md"
+	},
+	{
+		id: "use-the-built-in-tools",
+		name: "直接用内置工具",
+		when: "单次调用就够，或每步都要模型判断（写操作、审批敏感）",
+		how: {
+			full_ptc: "程序内 tools.read/grep/find/ls/edit/write；逐个直调走 pi 自己的工具",
+			codemode_ptc: "脚本内 tools.<内置名> 直接调"
+		},
+		fact: "bash 当前不在程序绑定表里（旧 ADR-0040 的 opt-in 尚未接线）",
+		detail: "docs/routes/use-the-built-in-tools.md"
+	},
+	{
+		id: "report-what-you-did",
+		name: "交报告",
+		when: "子代理收工：结论要有证据、副作用与用量要可核对",
+		how: {
+			full_ptc: "孩子的契约：最终消息末尾 fenced JSON（summary/findings/files_touched/usage）；宿主自动解析",
+			codemode_ptc: "同左——契约在孩子的追加提示词里，与 surface 无关"
+		},
+		fact: "reportChannel 恒在四值：tool/prompt-json/none/opted-out；工具通道（ptc_child_report）已是首选",
+		detail: "docs/routes/report-what-you-did.md"
+	},
+	{
+		id: "reach-the-web",
+		name: "上网查资料",
+		when: "需要网页搜索、抓页面、页内找内容——判断力在干活的子代理侧",
+		how: {
+			full_ptc: "派子代理（pi_task_ptc），孩子用 web_ds_search（search/open/find 三动作）",
+			codemode_ptc: "同左——搜索只在子代理进程里注册，父会话没有这个工具"
+		},
+		fact: "webDsSearch 开关默认关（fail-closed）；配额每进程计；概览走 snippet 超预算整条丢弃",
+		detail: "docs/routes/reach-the-web.md"
+	},
+	{
+		id: "manage-a-task",
+		name: "管一个任务",
+		when: "要知道孩子跑得怎样、读它的产出、或叫停它",
+		how: {
+			full_ptc: "ptc_task_list / ptc_task_output / ptc_task_stop（模型直调）——产出里的 delivery 是引擎实测轨迹",
+			codemode_ptc: "同左（模型直调；脚本经结构化返回）——产出里的 delivery 是引擎实测轨迹"
+		},
+		fact: "有任务记录这三个工具才出现在模型面前（ADR-0007）",
+		detail: "docs/routes/manage-a-task.md"
+	}
+];
+const LONG_OUTPUT_GUIDANCE_WITH_REPORT = "产出超过截断阈值（{bytes} 字节）。先看孩子的报告（归约层）：{report}——响应里的 output 是截断后的尾部；报告没收录的完整原文用 read 读记录上的 outputPath。";
+const LONG_OUTPUT_GUIDANCE_NO_REPORT = "产出超过截断阈值（{bytes} 字节），且孩子未交报告（reportChannel=none，散文可信度存疑）。响应里的 output 是截断后的尾部；完整原文用 read 读记录上的 outputPath。";
+function renderLongOutputGuidance(options) {
+	if (options.report && options.reportChannel && options.reportChannel !== "none") {
+		const findings = (options.report.findings ?? []).slice(0, 5).map((f) => `- ${f.what}${f.evidence ? `（证据：${f.evidence}）` : ""}`).join("\n");
+		return LONG_OUTPUT_GUIDANCE_WITH_REPORT.replace("{bytes}", String(options.bytes)).replace("{report}", [`summary: ${options.report.summary}`, findings].filter(Boolean).join("\n"));
+	}
+	return LONG_OUTPUT_GUIDANCE_NO_REPORT.replace("{bytes}", String(options.bytes));
+}
+function renderTaskNotifications(batch) {
+	return [
+		"<bg-task-notifications>",
+		...batch.map((n) => `- task ${n.taskId}${n.label ? ` (${n.label})` : ""}: ${n.status}${n.stopReason ? ` — ${n.stopReason}` : ""}`),
+		"</bg-task-notifications>"
+	].join("\n");
+}
+function estimateTokens(text) {
+	return Math.ceil(text.length / 2);
+}
+const ROUTE_INDEX_LEAD = {
+	full_ptc: "批量调工具默认先写程序（ptc_run_code）；单次调用或要逐步判断、审批敏感的才直连。派不派子代理自己判断——路由表第一行写了代价。",
+	codemode_ptc: "编排写 codemode 脚本；批量派活经脚本内的 pi_task_codemode；要查/停任务用任务面三工具。派不派自己判断——路由表第一行写了代价。"
+};
+function renderRouteIndex(surface, detailBase, nudge = true) {
+	const lines = ROUTES.map((route) => `- ${route.name} — ${route.when}。这面怎么走：${route.how[surface]}。细节：${detailBase ? route.detail.split("/").pop() : route.detail}`);
+	let index = [
+		`<ptc>`,
+		...nudge ? [ROUTE_INDEX_LEAD[surface]] : [],
+		...detailBase ? [`详情目录：${detailBase}`] : [],
+		"路由表（一条一行，详情按需 read）：",
+		...lines,
+		`</ptc>`
+	].join("\n");
+	const tokens = estimateTokens(index);
+	if (tokens > 560) index += `\n> WARNING: index over token budget (${tokens} > 560); move detail into docs/routes/*.md`;
+	return index;
+}
 // ../ptc/src/task-binding.ts
 const TASK_BINDING_NAME = "pi_task_ptc";
 const TASK_DOOR_PARAMETERS = _Object_({
 	task: String$1({
 		minLength: 1,
-		description: "孩子要干的活"
+		description: TASK_DOOR_PARAM_DESCRIPTIONS.task
 	}),
-	agent: Optional(String$1({ description: "已注册的 agent 名字；省略 = 通用孩子" })),
-	why: Optional(String$1({ description: "这一刀为什么切出来（调用方自己的话）" })),
+	agent: Optional(String$1({ description: TASK_DOOR_PARAM_DESCRIPTIONS.agent })),
+	why: Optional(String$1({ description: TASK_DOOR_PARAM_DESCRIPTIONS.why })),
 	agentScope: Optional(Union([
 		Literal("user"),
 		Literal("project"),
 		Literal("both")
-	])),
-	model: Optional(String$1({ description: "覆盖孩子跑的模型" })),
-	thinkingLevel: Optional(String$1()),
-	wait: Optional(Boolean$1({ description: "true = 等这个任务完成再返回结果" })),
-	label: Optional(String$1({ description: "后台任务给人看的标签" })),
-	readOnly: Optional(Union([Literal("strict"), Literal("lenient")]))
+	], { description: TASK_DOOR_PARAM_DESCRIPTIONS.agentScope })),
+	model: Optional(String$1({ description: TASK_DOOR_PARAM_DESCRIPTIONS.model })),
+	thinkingLevel: Optional(String$1({ description: TASK_DOOR_PARAM_DESCRIPTIONS.thinkingLevel })),
+	wait: Optional(Boolean$1({ description: TASK_DOOR_PARAM_DESCRIPTIONS.wait })),
+	label: Optional(String$1({ description: TASK_DOOR_PARAM_DESCRIPTIONS.label })),
+	readOnly: Optional(Union([Literal("strict"), Literal("lenient")], { description: TASK_DOOR_PARAM_DESCRIPTIONS.readOnly })),
+	timeoutMs: Optional(Number$1({ description: TASK_DOOR_PARAM_DESCRIPTIONS.timeoutMs })),
+	projectContext: Optional(Union([Literal("auto"), Literal("none")], { description: TASK_DOOR_PARAM_DESCRIPTIONS.projectContext }))
 });
 function createTaskBinding(door) {
 	return {
@@ -4280,7 +4497,9 @@ function createTaskBinding(door) {
 				thinkingLevel: input.thinkingLevel,
 				agent: input.agent,
 				agentScope: input.agentScope,
-				readOnly: input.readOnly
+				readOnly: input.readOnly,
+				timeoutMs: input.timeoutMs,
+				projectContext: input.projectContext
 			});
 		}
 	};
@@ -4746,151 +4965,6 @@ function renderToolResult(outcome) {
 		fullOutputPath
 	};
 }
-// ../routes/src/surface.ts
-const FALLBACK_SURFACE_MODE = "full_ptc";
-// ../routes/src/registry.ts
-const TOOLS = {
-	ptc_run_code: {
-		name: "ptc_run_code",
-		description: (s) => ["写一段 TypeScript 程序批量调用工具：tools.<name>(args)。支持顶层 await、Promise.all 并行、循环与条件；程序返回值是归约后的结果，中间产物不进上下文。", s === "codemode_ptc" ? "本会话里我从 codemode 脚本可达，模型直走 codemode。" : "什么时候写程序而不是逐个调工具，看系统提示词 <ptc> 节的路由表。"].join("")
-	},
-	ptc_workflow: {
-		name: "ptc_workflow",
-		description: (s) => ["结构化的多阶段程序：script 里可用 workflow.log / workflow.phase / workflow.parallel / workflow.pipeline。适合阶段明确的批处理。", s === "codemode_ptc" ? "本会话里我从 codemode 脚本可达。" : "与 ptc_run_code 的取舍看 <ptc> 节的路由表。"].join("")
-	},
-	pi_task_codemode: {
-		name: "pi_task_codemode",
-		description: () => "建一条子代理任务，默认立刻返回 handle（taskId + label）；wait:true 时阻塞到终态再返回结果。任务在任务记录里排队，由派发引擎起独立 pi 进程执行；完成后的报告与产出经 ptc_task_output 读取。"
-	},
-	ptc_task_list: {
-		name: "ptc_task_list",
-		description: () => "列出在飞的任务与最近完成的任务（最近 10 条已完成）。"
-	},
-	ptc_task_output: {
-		name: "ptc_task_output",
-		description: () => "按 task_id 读一条任务记录：状态、报告、产出。产出超过截断阈值时给尾部与完整产出位置（outputPath）。"
-	},
-	ptc_task_stop: {
-		name: "ptc_task_stop",
-		description: () => "按 task_id 叫停任务：排队中的直接抽掉（canceled），在跑的转 stopping。"
-	}
-};
-const ROUTES = [
-	{
-		id: "create-a-task",
-		name: "派一个子代理",
-		when: "这件事需要它自己的上下文，或者要跟别的活并行",
-		how: {
-			full_ptc: "tools.pi_task_ptc({ task, label? })（程序内）",
-			codemode_ptc: "tools.pi_task_codemode({ task, label? })（脚本内）"
-		},
-		fact: "默认不等，立刻返回 handle；任务在任务记录里排队，可经任务面三工具查/停",
-		detail: "docs/routes/create-a-task.md"
-	},
-	{
-		id: "run-one-program",
-		name: "批量调工具的一段程序",
-		when: "连续多次工具调用、结果要过滤/归约后再看",
-		how: {
-			full_ptc: "ptc_run_code({ code, description })",
-			codemode_ptc: "不适用——写程序是 full_ptc 面的编排能力；本面用 codemode 编排、pi_task_codemode 派任务"
-		},
-		fact: "程序内 tools.*；bash 当前不在程序绑定表里（旧 ADR-0040 的 opt-in 尚未接线）；只在本面（full_ptc）注册 PTC 工具",
-		detail: "docs/routes/run-one-program.md"
-	},
-	{
-		id: "run-a-phased-workflow",
-		name: "分阶段 workflow",
-		when: "批处理有明确阶段，要阶段性可见进度",
-		how: {
-			full_ptc: "ptc_workflow({ meta, script, args? })",
-			codemode_ptc: "不适用——同 run-one-program：workflow 是 full_ptc 的编排能力"
-		},
-		fact: "script 内可用 workflow.log/phase/parallel/pipeline；只在本面注册",
-		detail: "docs/routes/run-a-phased-workflow.md"
-	},
-	{
-		id: "use-the-built-in-tools",
-		name: "直接用内置工具",
-		when: "单次调用就够，或每步都要模型判断（写操作、审批敏感）",
-		how: {
-			full_ptc: "程序内 tools.read/grep/find/ls/edit/write；逐个直调走 pi 自己的工具",
-			codemode_ptc: "脚本内 tools.<内置名> 直接调"
-		},
-		fact: "bash 当前不在程序绑定表里（旧 ADR-0040 的 opt-in 尚未接线）",
-		detail: "docs/routes/use-the-built-in-tools.md"
-	},
-	{
-		id: "report-what-you-did",
-		name: "交报告",
-		when: "子代理收工：结论要有证据、副作用与用量要可核对",
-		how: {
-			full_ptc: "孩子的契约：最终消息末尾 fenced JSON（summary/findings/files_touched/usage）；宿主自动解析",
-			codemode_ptc: "同左——契约在孩子的追加提示词里，与 surface 无关"
-		},
-		fact: "reportChannel 恒在四值：tool/prompt-json/none/opted-out；工具通道（ptc_child_report）已是首选",
-		detail: "docs/routes/report-what-you-did.md"
-	},
-	{
-		id: "reach-the-web",
-		name: "上网查资料",
-		when: "需要网页搜索、抓页面、页内找内容——判断力在干活的子代理侧",
-		how: {
-			full_ptc: "派子代理（pi_task_ptc），孩子用 web_ds_search（search/open/find 三动作）",
-			codemode_ptc: "同左——搜索只在子代理进程里注册，父会话没有这个工具"
-		},
-		fact: "webDsSearch 开关默认关（fail-closed）；配额每进程计；概览走 snippet 超预算整条丢弃",
-		detail: "docs/routes/reach-the-web.md"
-	},
-	{
-		id: "manage-a-task",
-		name: "管一个任务",
-		when: "要知道孩子跑得怎样、读它的产出、或叫停它",
-		how: {
-			full_ptc: "ptc_task_list / ptc_task_output / ptc_task_stop（模型直调）",
-			codemode_ptc: "同左（模型直调；脚本经结构化返回）"
-		},
-		fact: "有任务记录这三个工具才出现在模型面前（ADR-0007）",
-		detail: "docs/routes/manage-a-task.md"
-	}
-];
-const LONG_OUTPUT_GUIDANCE_WITH_REPORT = "产出超过截断阈值（{bytes} 字节）。先看孩子的报告（归约层）：{report}——响应里的 output 是截断后的尾部；报告没收录的完整原文用 read 读记录上的 outputPath。";
-const LONG_OUTPUT_GUIDANCE_NO_REPORT = "产出超过截断阈值（{bytes} 字节），且孩子未交报告（reportChannel=none，散文可信度存疑）。响应里的 output 是截断后的尾部；完整原文用 read 读记录上的 outputPath。";
-function renderLongOutputGuidance(options) {
-	if (options.report && options.reportChannel && options.reportChannel !== "none") {
-		const findings = (options.report.findings ?? []).slice(0, 5).map((f) => `- ${f.what}${f.evidence ? `（证据：${f.evidence}）` : ""}`).join("\n");
-		return LONG_OUTPUT_GUIDANCE_WITH_REPORT.replace("{bytes}", String(options.bytes)).replace("{report}", [`summary: ${options.report.summary}`, findings].filter(Boolean).join("\n"));
-	}
-	return LONG_OUTPUT_GUIDANCE_NO_REPORT.replace("{bytes}", String(options.bytes));
-}
-function renderTaskNotifications(batch) {
-	return [
-		"<bg-task-notifications>",
-		...batch.map((n) => `- task ${n.taskId}${n.label ? ` (${n.label})` : ""}: ${n.status}${n.stopReason ? ` — ${n.stopReason}` : ""}`),
-		"</bg-task-notifications>"
-	].join("\n");
-}
-function estimateTokens(text) {
-	return Math.ceil(text.length / 2);
-}
-const ROUTE_INDEX_LEAD = {
-	full_ptc: "批量调工具默认先写程序（ptc_run_code）；单次调用或要逐步判断、审批敏感的才直连。",
-	codemode_ptc: "编排写 codemode 脚本；批量派活经脚本内的 pi_task_codemode；要查/停任务用任务面三工具。"
-};
-function renderRouteIndex(surface, detailBase, nudge = true) {
-	const lines = ROUTES.map((route) => `- ${route.name} — ${route.when}。这面怎么走：${route.how[surface]}。细节：${detailBase ? route.detail.split("/").pop() : route.detail}`);
-	let index = [
-		`<ptc>`,
-		...nudge ? [ROUTE_INDEX_LEAD[surface]] : [],
-		...detailBase ? [`详情目录：${detailBase}`] : [],
-		"路由表（一条一行，详情按需 read）：",
-		...lines,
-		`</ptc>`
-	].join("\n");
-	const tokens = estimateTokens(index);
-	if (tokens > 560) index += `\n> WARNING: index over token budget (${tokens} > 560); move detail into docs/routes/*.md`;
-	return index;
-}
 // ../ptc/src/render.ts
 function renderPtcResult(surface) {
 	return (result, options, _theme, context) => {
@@ -5083,6 +5157,20 @@ const textResult = (value) => ({
 	}],
 	details: void 0
 });
+function withDeliveryNote(value) {
+	if (!value || typeof value !== "object") return value;
+	const record = value;
+	if (!("reportChannel" in record)) return value;
+	const note = renderDeliveryCheck({
+		delivery: record.delivery,
+		findings: Array.isArray(record.report?.findings) ? record.report.findings.length : 0,
+		channel: record.reportChannel
+	});
+	return note ? {
+		...record,
+		deliveryNote: note
+	} : record;
+}
 const packageRoot = fileURLToPath(new URL("..", import.meta.url));
 const publishedDetailDir = join(packageRoot, "docs", "routes");
 const detailDir = existsSync(publishedDetailDir) ? publishedDetailDir : join(packageRoot, "..", "routes", "docs", "routes");
@@ -5393,7 +5481,7 @@ function createBindingTable(pi, session, getToolContext) {
 		return normalizeToolValue(outcome.result.structuredContent ?? outcome.result.content);
 	}]));
 	const taskBinding = createTaskBinding(session);
-	table[TASK_BINDING_NAME] = (args) => taskBinding.execute(args);
+	table[TASK_BINDING_NAME] = async (args) => withDeliveryNote(await taskBinding.execute(args));
 	return table;
 }
 function registerPtcTools(registerTool, options, surface) {
@@ -5420,10 +5508,10 @@ function registerTaskFace(registerTool, session, surface) {
 			const record = session.registry.get(args.task_id) ?? await session.readArchivedRecord(args.task_id);
 			if (!record) return textResult({ error: `unknown task id ${args.task_id}` });
 			const outputBytes = await session.outputSize(args.task_id);
-			if (outputBytes === void 0) return textResult(record);
+			if (outputBytes === void 0) return textResult(withDeliveryNote(record));
 			if (outputBytes > 51200) {
 				const { text } = applyAdr0015Truncation$1(await session.readOutputTail(args.task_id, 51200) ?? "");
-				return textResult({
+				return textResult(withDeliveryNote({
 					...record,
 					output: text,
 					guidance: renderLongOutputGuidance({
@@ -5431,13 +5519,13 @@ function registerTaskFace(registerTool, session, surface) {
 						report: record.report,
 						reportChannel: record.reportChannel ?? "none"
 					})
-				});
+				}));
 			}
 			const { text } = applyAdr0015Truncation$1(await session.readOutputTail(args.task_id, 51200) ?? "");
-			return textResult({
+			return textResult(withDeliveryNote({
 				...record,
 				output: text
-			});
+			}));
 		}
 	});
 	registerTool({
@@ -5468,14 +5556,17 @@ function registerTaskDoor(registerTool, session, surface) {
 				agentScope: args.agentScope,
 				model: args.model,
 				thinkingLevel: args.thinkingLevel,
-				readOnly: args.readOnly
+				readOnly: args.readOnly,
+				timeoutMs: args.timeoutMs,
+				projectContext: args.projectContext
 			});
+			const shaped = withDeliveryNote(result);
 			return {
-				...textResult(result),
-				structuredContent: result,
+				...textResult(shaped),
+				structuredContent: shaped,
 				isError: result.status === "rejected"
 			};
 		}
 	});
 }
-export { assemblePtcSession, piPtcEntry as default };
+export { assemblePtcSession, piPtcEntry as default, withDeliveryNote };

package/docs/routes/create-a-task.md

@@ -5,17 +5,29 @@
 - `pi_task_ptc`：PTC 程序内的 binding，程序里 `tools.pi_task_ptc({...})`
 - `pi_task_codemode`：注册的工具（exposure: codemode，模型不可见），codemode 脚本里 `tools.pi_task_codemode({...})`
 
-参数：`task`（必填，孩子要干的活）、`label`、`wait`、`why`、`agent`、`agentScope`、`model`、`thinkingLevel`、`readOnly`；
+参数：`task`（必填，孩子要干的活）、`label`、`wait`、`why`、`agent`、`agentScope`、`model`、`thinkingLevel`、`readOnly`、`timeoutMs`；
 agent 定义里的 `tools / model / thinkingLevel / childReport` 由 frontmatter 钉住。
 
-返回 handle：`{ taskId, label?, status: "queued" }`。默认不等；撞闸（随闸门落地）返回
-`{ status: "rejected", errorMessage }`，不抛异常。
+返回 handle：`{ taskId, label?, status: "queued" }`。默认不等；撞闸排队等（ADR-0010），
+不抛异常。唯一的拒绝是派发被关（`/ptc off`，ADR-0004）：此时返回
+`{ status: "rejected", errorMessage }`。
 
 任务建成后在任务记录里排队（满员排队不拒绝，ADR-0010），经
 `ptc_task_list / ptc_task_output / ptc_task_stop` 查/停。
 
+## 什么时候值得派（判据）
+
+- **值得**：主题多、彼此独立、每个都要读一堆材料——父一个人扛会算错，一份材料一个孩子最划算。
+- **不值得**：材料少、一口气能算完——派发只换 0~8% 准确率，代价是 10 倍上下成本。
+- 实测（facts 题：4 份互不相干的档案各交给一个孩子，n=3）：派发档准确率 100%，不派发 92%。
+  ⚠️ **这 8 个点当方向别当效应量**：不派发档自身在两批之间就晃（bare 89%→97%，而那次代码改动对它零影响），
+  差值与波动同量级。稳的是**机制**：父同时扛 4 个主题的多步计算会算错（实测有一轮一个主题 3 条全错），
+  派发后每个孩子只对一份档案就全对。
+
 ## Briefing 纪律（省 token，派发前自查）
 
+- **task 是孩子的唯一规格**：孩子看不到父会话，也看不到别的孩子。父写错，孩子照办，全链一致地错
+  （实测：有一轮父的任务书写了「用文件里给的值」，孩子交回档案里的原始参数，9 条事实全错）。
 - **给确切路径、命令、决策**：孩子看不到父会话。task 里写死一个路径，省孩子一轮探索
   （每轮探索 = 一次工具调用结果 + 推理 token）。
 - **写明最终消息要带回什么**：孩子只回一次。要什么格式、哪些字段，task 里说清。
@@ -24,3 +36,35 @@ agent 定义里的 `tools / model / thinkingLevel / childReport` 由 frontmatter
 - **同域的活合并给一个串行孩子**：每个孩子都付一份固定 harness 税（系统提示词 +
   项目上下文）。多个重叠的小活拆并行 = 同一份探索被付费多次。
 - **孩子不写报告文件**：交付物就是最终消息（含报告 JSON 块），落盘 .md 是浪费。
+- **写清两件事：交付物格式 + 报告块**：孩子要同时交「交付物」和「报告」（末尾 JSON 块，或调
+  `ptc_child_report` 工具）。只写交付物格式时，孩子多半不交报告——父就只剩原始产出可读，只能重算。
+  更别写「恰好 N 行」这类排他措辞：孩子会照排他措辞办，把报告丢掉（实测 3/12 孩子中招，
+  父重算被记成幻觉）。
+  **要报告就点名形状**：「最后附上 child report 的 JSON 块（summary / findings / files_touched /
+  usage）」——实测点名形状 4/4 孩子照交；只说「附上报告块」1/4 交；**自己发明一套报告格式更糟**
+  （实测 4/4 不交契约块：孩子照父的格式办，把契约块顶掉了）。
+- **汇总前核对孩子产出**：任务结果里的 `delivery` 是引擎实测的轨迹（它读了哪些文件、有没有报错），
+  不是孩子的自述。孩子零产出（没读材料、无报告、正文空）就**重派它，或明说缺口——别替它补数**：
+  父补的数没有孩子背书，保真度上等于「父说有、孩子没说」。
+
+## 旋钮（用不用你自己判断）
+
+参数都在参数表里。下面是它们的代价——什么时候值得付，由你判断：
+
+- **`why`**（调用方自己的话）：它进孩子的提示词 = 花孩子的 token。孩子从 task 里已经能读懂为什么要干，就别传。
+- **`readOnly: "strict"`**：孩子的工具表压到 read/grep/find/ls（搜索开启时含 web_ds_search）。
+  只需要读的活别给写权限——省 token，也省掉它改坏东西的可能。
+- **`thinkingLevel` / `model`**：孩子的成本项。活简单就给孩子低档位或更便宜的模型。
+- **`wait: false`**（默认）：立刻返回 handle，结果经任务面/通知回来。多个孩子并行时别在第一个上阻塞。
+- **`timeoutMs`**：孩子的运行时长上限（毫秒）。**不传 = 不限**（默认行为）；传了超时就收尸——
+  慢孩子不再一直烧 token，但它的活可能没干完。给了就别再无脑等它。
+- **`projectContext`**：孩子的项目上下文（AGENTS.md/CLAUDE.md）。`auto`（默认）= 照常加载；
+  `none` = 不加载。**none 只关「注入」，不关「知识」**：文件还在工作目录里，孩子需要时会自己去翻
+  （实测 none 臂的孩子照样读到了项目口径）——所以 none 省的是注入那几百字符，
+  **实测输入只差约 15%，不是省一半**。这活只需要孩子读材料/算数、不需要项目约定时传 `none`；
+  要孩子遵守项目规矩就照常传。**另一头也要知道**：auto 注入的是整个项目文件，孩子可能把里面的
+  写码规矩套到答案上（实测 3 轮 4 条错全是「元 → 分」×100 改写）。
+
+台架口径（2026-10-30，pi 1.4.0，facts 题 n=3）：每个孩子付一份固定 harness 税 ≈ 1800 input token；
+端到端比不派发贵 9~12 倍（官方编排 + 本仓派发 8.7×、本仓编排 + 本仓派发 11.6×；env 修复前是 15~22 倍）。
+**派发值得的是准确性，不是省钱**：同样的题，派发档准确率 100%，不派发 92%（差值见上，与波动同量级）。

package/docs/routes/manage-a-task.md

@@ -7,3 +7,21 @@
 - `ptc_task_stop({ task_id, reason? })`：排队中的抽掉（canceled）；在跑的转 stopping
 
 任务记录是派发的唯一痕迹：每次建任务都建记录，前台任务也一样。
+
+终态记录热存留最近 500 条（决策 29），被挤出的进压缩存档（默认留 30 天，
+`archiveEnabled: false` 则直接删），凭精确 task id 经 `ptc_task_output` 仍读得到。
+
+## 交付核对（delivery）
+
+任务记录与产出里带 `delivery`：**引擎从孩子的进程事件流抽的实测轨迹**，不是孩子的自述。
+
+- `tools`——孩子实际调用了哪些工具、各几次
+- `paths`——它实际碰过的路径（去重，按出现顺序）
+- `errors`——工具执行失败次数
+- `textChars`——孩子最终正文长度（0 = 空交）
+
+另有一行人话 `deliveryNote`，是同一份事实的渲染版。怎么用：
+
+- 结论声称来自某份材料 ⇒ 对一下 `paths` 里有没有那份：**没有 ⇒ 这条结论没有依据**
+- `paths` 空 + 报告 0 条 + 正文 0 字 ⇒ 这孩子零产出：**重派它，或明说缺口，别替它补数**
+- `errors` > 0 ⇒ 它撞过错（路径不对、读不到），先看错在哪再决定重派还是改任务书

package/docs/routes/reach-the-web.md

@@ -1,6 +1,9 @@
-# 上网查资料（web_ds_search，ADR-0001–0049）
+# 上网查资料（web_ds_search · 搜索域）
 
-搜索能力**只活在被派出的子代理里**（父会话不注册这个工具）——「这条来源靠不靠谱」的判断力在干活的子代理侧。
+pi 面上，搜索能力**只活在被派出的子代理里**（父会话不注册这个工具）——「这条来源靠不靠谱」的判断力在干活的子代理侧。
+
+> Kimi 面（`ptc-tools` 插件）例外：`web_ds_search` 模型可直接调用，配额按 MCP server
+> 进程计（默认 30 次），DeepSeek key 走 env → Kimi Code `config.toml` 两级解析。
 
 三动作：
 

package/docs/routes/run-one-program.md

@@ -1,11 +1,13 @@
 # 批量调工具的一段程序（ptc_run_code）
 
 `ptc_run_code({ code, description, timeoutMs? })`：code 是 TypeScript 程序体，
-支持顶层 await 与 return。程序内 `tools.<name>(args)` 调工具：
+支持顶层 await 与 return。程序跑在 **vm 运行格**里：唯一的出口是 `tools.*`（与直调
+同一条工具管线），没有 `process` / `fetch` / 动态 `import`（v7.0.0 起，ADR-0019，
+用过它们的旧代码会断）。程序内 `tools.<name>(args)` 调工具：
 
 - 绑定表 = 内置名单 ∩ 会话活跃工具（`--tools` 收窄的会话不会拿到被滤掉的绑定）
-- `bash` 不在默认表里，需 opt-in 授权（旧 ADR-0040）
+- `bash` 不在程序绑定表里——旧 ADR-0040 的 opt-in 尚未接线，当前没有任何开关能开它
 - 程序返回值是归约后的结果；undefined 返回标记为「无完成值」
 
-默认 2 分钟超时（可经 timeoutMs 下调，上限 10 分钟）。输出超 50 KB 按 pi 截断契约切尾，
+默认 2 分钟超时（可经 timeoutMs 调整）。输出超 50 KB 按 pi 截断契约切尾，
 全文写在临时文件、路径进尾注。

package/docs/routes/use-the-built-in-tools.md

@@ -3,5 +3,6 @@
 单次调用、或每步都需要模型判断的场景（写操作、审批敏感），不要写程序，直接调。
 
 - PTC 程序内：`tools.read / grep / find / ls / edit / write`（绑定表收窄规则见 run-one-program）
-- `bash` 需 opt-in：embedder 的 optIns 参数或 `~/.pi/agent/ptc.json` 的 optInBindings，处处 fail-closed
-- 程序外的逐个直调走 pi 自己的工具调用管线
+- `bash` 不在程序绑定表里（旧 ADR-0040 的 opt-in 尚未接线）——程序里跑 shell 没有路子
+- 程序外的逐个直调走 pi 自己的工具调用管线；注意 pi 内置工具**没有 cwd 囚禁**：
+  strict 只是工具白名单收窄，绝对路径可读工作区外任何可读文件——白名单 ≠ 沙箱

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ptc-subagents",
-  "version": "7.1.0",
+  "version": "7.2.0",
   "description": "Programmable tool calling (PTC) and subagent fan-out for pi",
   "keywords": [
     "pi",