@qilin-agent/tools 3.1.3 → 3.1.5

package/README.i18n.yaml

@@ -5,99 +5,99 @@
 /:
   en: 3b12a77945c0d1e9
   zh: e9af32047e4f658b
-/qilin-tools:
-  en: a4b050d1b91ebf39
-  zh: 2a5cffff9987575d
-/qilin-tools/summary:
+/qilin-agent-tools:
+  en: 04bcb1e79c92cad9
+  zh: 45acefa225993264
+/qilin-agent-tools/summary:
   en: 7fb51274d4f721df
   zh: da9b19633629eefd
-/qilin-tools/table-of-contents:
+/qilin-agent-tools/table-of-contents:
   en: d152484eb41ac6b4
   zh: 09388d293f9be9cb
-/qilin-tools/use-this-package:
-  en: 5157221ba48c5c22
-  zh: 0fd32b2fd246495e
-/qilin-tools/use-this-package/register-a-tool:
+/qilin-agent-tools/use-this-package:
+  en: 6530bbd1b2a98e3f
+  zh: c3ec6a876315c08e
+/qilin-agent-tools/use-this-package/register-a-tool:
   en: 02fce53c21a33d74
   zh: 01110c4714dfd602
-/qilin-tools/use-this-package/configure-the-presentation-mode:
-  en: 623fcab2e684b719
-  zh: cde146b5f4cd610d
-/qilin-tools/use-this-package/restrict-tools-per-agent:
+/qilin-agent-tools/use-this-package/configure-the-presentation-mode:
+  en: 7e438825611cbff6
+  zh: 4b85bf913691640d
+/qilin-agent-tools/use-this-package/restrict-tools-per-agent:
   en: c6f98b2283cc2e47
   zh: c2cdce5d13473f15
-/qilin-tools/use-this-package/enforce-policy-on-calls:
+/qilin-agent-tools/use-this-package/enforce-policy-on-calls:
   en: 1dd4ee9d8cdd2038
   zh: aa3e9790641e521f
-/qilin-tools/use-this-package/host-presentation-descriptors:
+/qilin-agent-tools/use-this-package/host-presentation-descriptors:
   en: d9aec6b6a174584a
   zh: b42039a7015e0364
-/qilin-tools/understand-the-implementation:
+/qilin-agent-tools/understand-the-implementation:
   en: ce7e776e9d516bdb
   zh: 59d2751743db7795
-/qilin-tools/understand-the-implementation/design-concept:
+/qilin-agent-tools/understand-the-implementation/design-concept:
   en: 92e8af53e6067bad
   zh: 33c7b99b42c5acac
-/qilin-tools/understand-the-implementation/source-map:
+/qilin-agent-tools/understand-the-implementation/source-map:
   en: c14e20d6a5c4c408
   zh: ab9dc0fd38006749
-/qilin-tools/understand-the-implementation/execution-and-cancellation:
+/qilin-agent-tools/understand-the-implementation/execution-and-cancellation:
   en: dc44a88997777988
   zh: 56454aeace1c8b77
-/qilin-tools/understand-the-implementation/ptc-mode:
-  en: 3c9d085b862b98e0
-  zh: d243755c77c3432d
-/qilin-tools/understand-the-implementation/extension-points:
+/qilin-agent-tools/understand-the-implementation/ptc-mode:
+  en: 05db4632bd08eb8c
+  zh: d1699b7a159eea9b
+/qilin-agent-tools/understand-the-implementation/extension-points:
   en: c2a14d6f22bc9428
   zh: 89c1414fca465931
-/qilin-tools/further-exploration:
-  en: 890aed31a2a34950
-  zh: d1833fc8d1bb8bca
-/qilin-tools/model-experience:
+/qilin-agent-tools/further-exploration:
+  en: 20c5e038e7b3b0fa
+  zh: 18daabad7c1f582a
+/qilin-agent-tools/model-experience:
   en: 215e7ba838619b7b
   zh: a311da3843709f90
-/qilin-tools/model-experience/normal-tool-schemas:
+/qilin-agent-tools/model-experience/normal-tool-schemas:
   en: 483b01d9bb2cb49a
   zh: 1d95095e76fb0996
-/qilin-tools/model-experience/normal-tool-schemas/what-the-model-sees:
-  en: 1978238355b5755a
-  zh: c65b1c5309ec1831
-/qilin-tools/model-experience/normal-tool-schemas/token-effect:
+/qilin-agent-tools/model-experience/normal-tool-schemas/what-the-model-sees:
+  en: 53d988bc9af2af86
+  zh: a87f2017ee996676
+/qilin-agent-tools/model-experience/normal-tool-schemas/token-effect:
   en: d594b71ff5e4cc87
   zh: dcec1ea0dd2a0fa6
-/qilin-tools/model-experience/normal-tool-schemas/kv-cache-effect:
+/qilin-agent-tools/model-experience/normal-tool-schemas/kv-cache-effect:
   en: 7c5e75964e020b2c
   zh: d50d0402d15232d9
-/qilin-tools/model-experience/ptc-mode-schema-and-system-prompt:
+/qilin-agent-tools/model-experience/ptc-mode-schema-and-system-prompt:
   en: eaefd7303f22977d
   zh: 9c425f9501128224
-/qilin-tools/model-experience/ptc-mode-schema-and-system-prompt/what-the-model-sees:
-  en: ad6b9ea4c514455f
-  zh: fe27c64ce8b0f465
-/qilin-tools/model-experience/ptc-mode-schema-and-system-prompt/what-the-model-sees/typescript-ptc-mode-sdk-instructions-with-bash:
+/qilin-agent-tools/model-experience/ptc-mode-schema-and-system-prompt/what-the-model-sees:
+  en: 2efe3c1c793219e0
+  zh: 40be3fbb1dd63d4e
+/qilin-agent-tools/model-experience/ptc-mode-schema-and-system-prompt/what-the-model-sees/typescript-ptc-mode-sdk-instructions-with-bash:
   en: 3a8df15e4ae32f9e
   zh: fc4a800ba363e835
-/qilin-tools/model-experience/ptc-mode-schema-and-system-prompt/token-effect:
+/qilin-agent-tools/model-experience/ptc-mode-schema-and-system-prompt/token-effect:
   en: 12296fcafc14562c
   zh: f8e9351bb8c6437d
-/qilin-tools/model-experience/ptc-mode-schema-and-system-prompt/kv-cache-effect:
+/qilin-agent-tools/model-experience/ptc-mode-schema-and-system-prompt/kv-cache-effect:
   en: 78906628d634441f
   zh: 492f133aea50cfe3
-/qilin-tools/model-experience/tool-call-history-and-results:
+/qilin-agent-tools/model-experience/tool-call-history-and-results:
   en: a8503137ad03720c
   zh: 611a2dadf7c0c706
-/qilin-tools/model-experience/tool-call-history-and-results/what-the-model-sees:
+/qilin-agent-tools/model-experience/tool-call-history-and-results/what-the-model-sees:
   en: 7c568da5a45e99ab
   zh: 7e78f04448fc5450
-/qilin-tools/model-experience/tool-call-history-and-results/token-effect:
+/qilin-agent-tools/model-experience/tool-call-history-and-results/token-effect:
   en: 8fe3f024f364ed9f
   zh: 89c1d5d24c5f950b
-/qilin-tools/model-experience/tool-call-history-and-results/kv-cache-effect:
+/qilin-agent-tools/model-experience/tool-call-history-and-results/kv-cache-effect:
   en: 2fbf2175168e8244
   zh: ad59a120b54a0996
-/qilin-tools/known-limitations-and-deferred-work:
-  en: 57ba640ee483c163
-  zh: 551dab190d346131
-/qilin-tools/known-limitations-and-deferred-work/dev-note:
+/qilin-agent-tools/known-limitations-and-deferred-work:
+  en: 4cd3c301d258a153
+  zh: f73ad30cd873cfee
+/qilin-agent-tools/known-limitations-and-deferred-work/dev-note:
   en: e67f633dc6fe7773
   zh: 3bb0c20c93f16f98

package/README.md

@@ -25,6 +25,8 @@ Use `qilin-tools` to expose typed capabilities to models, validate calls, enforc
 <a id="use-this-package"></a>
 ## Use this package
 
+Each `run_code` program captures the Session's current working directory when it starts. A nested directory change affects subsequent tool calls, while the running program keeps its initial directory.
+
 Mount `qilin-tools` wherever agents call tools: it provides `ctx.tools`, the registry every tool plugin registers into and the loop dispatches through. Registering a tool is enough to make it visible — the registry feeds its schemas into the system-prompt assembly automatically.
 
 ### Register a tool
@@ -121,11 +123,11 @@ Each typed invocation materializes and freezes parsed arguments, assigns an opaq
 
 ### PTC mode
 
-Under `ptc` or `both`, the registry exposes the reserved `run_code` transport plus a deterministic SDK generated in the loaded runtime's language. Each SDK binding captures a frozen ToolSchema and passes it through the scheduler to its execution context. Before policy, a started call records only pairing ids, name, and normalized arguments; its settle event preserves the rendered result and optional structured error. Description and parameters remain transient and never enter Session events or SDK output. Calls are scheduled through a per-run pool that reuses the native concurrency contract. Under `ptc` alone, a model-direct call naming any other visible tool resolves to `UNKNOWN_TOOL` before policy — the announced surface and the callable surface stay the same. Intermediate binding values are execution-local; only the outer `run_code` result has a hard size cap. The [executor-collapse note](../../../.agents/notes/implemented/bug-fix/2026-08-07-ptc-executor-collapse.md) owns the collapse contract.
+Under `ptc` or `both`, the registry exposes the reserved `run_code` transport plus a deterministic SDK generated in the loaded runtime's language. Each SDK binding captures a frozen ToolSchema and passes it through the scheduler to its execution context. Before policy, a started call records only pairing ids, name, and normalized arguments; its settle event preserves the rendered result, optional presentation metadata, and structured error. Metadata is projected from that call's canonical value and frozen; it changes neither the program value nor model content. Description and parameters remain transient and never enter Session events or SDK output. Calls are scheduled through a per-run pool that reuses the native concurrency contract. Under `ptc` alone, a model-direct call naming any other visible tool resolves to `UNKNOWN_TOOL` before policy — the announced surface and the callable surface stay the same. Intermediate binding values are execution-local; only the outer `run_code` result has a hard size cap. The [executor-collapse note](../../../.agents/notes/implemented/bug-fix/2026-08-07-ptc-executor-collapse.md) owns the collapse contract.
 
 New sub-calls use `<parent>:ptc:<n>` ids. Consumers treat these ids as opaque and correlate events by exact equality; restored historical ids retain their original bytes. The [PTC mode decision](../../../.agents/notes/implemented/feature/2026-06-15-ptc.md) owns durable naming and restoration rules.
 
-`run_code` accepts `timeoutMs` when the mounted runtime supports an override; its schema reports the configured default and maximum, the runtime's usage instructions and the Session working directory. The Node default is 120,000 ms with a 600,000 ms cap, including nested tool and approval waits. A wider `sandbox_permissions` mode requires a non-empty `justification` and approval before the program starts. The grant applies to that complete execution; standing Session policy and nested tools retain their own authority. Programs are never replayed automatically: inspect earlier effects before explicitly retrying a denied program.
+`run_code` accepts `timeoutMs` when the mounted runtime supports an override; its schema reports the configured default and maximum, and the runtime's usage instructions. The Node default is 120,000 ms with a 600,000 ms cap, including nested tool and approval waits. A wider `sandbox_permissions` mode requires a non-empty `justification` and approval before the program starts. The grant applies to that complete execution; standing Session policy and nested tools retain their own authority. Programs are never replayed automatically: inspect earlier effects before explicitly retrying a denied program.
 
 <a id="extension-points"></a>
 ### Extension points

package/README.zh.md

@@ -25,6 +25,8 @@ kind: "package-reference"
 <a id="use-this-package"></a>
 ## 使用本包
 
+每个 `run_code` 程序在启动时捕获 Session 的当前工作目录。嵌套调用改变目录只影响后续工具调用，运行中的程序保留其初始目录。
+
 在任何 agent 调用工具的地方挂载 `qilin-tools`：它提供 `ctx.tools`，即每个工具插件注册进去、循环分发所经过的注册表。注册一个工具就足以让它可见——注册表会自动把其 schema 送入系统提示词组装。
 
 ### 注册工具
@@ -121,11 +123,11 @@ ctx.tools.register(defineTool({
 
 ### PTC mode
 
-在 `ptc` 或 `both` 下，注册表公开保留的 `run_code` 传输以及按所加载运行时语言生成的确定性 SDK。每个 SDK 绑定捕获冻结的 ToolSchema，经由调度器传入该次执行上下文。已开始的调用在策略之前只记录配对 id、名称和规范化参数；其结算事件保留渲染结果与可选结构化错误。描述与参数 schema 仅临时存活，不进入 Session 事件或 SDK 输出。调用通过复用原生并发约定的每次运行独有池调度。在纯 `ptc` 下，模型直呼其他任何可见工具都会在策略之前解析为 `UNKNOWN_TOOL`——通告面与可调用面保持一致。中间绑定值只存在于执行局部；只有外层 `run_code` 结果有硬大小上限。[执行器塌缩 note](../../../.agents/notes/implemented/bug-fix/2026-08-07-ptc-executor-collapse.zh.md) 拥有该收束约定。
+在 `ptc` 或 `both` 下，注册表公开保留的 `run_code` 传输以及按所加载运行时语言生成的确定性 SDK。每个 SDK 绑定捕获冻结的 ToolSchema，经由调度器传入该次执行上下文。已开始的调用在策略之前只记录配对 id、名称和规范化参数；其结算事件保留渲染结果、可选展示元数据与结构化错误。元数据由该调用的规范值投影并冻结，既不改变程序值，也不改变模型内容。描述与参数 schema 仅临时存活，不进入 Session 事件或 SDK 输出。调用通过复用原生并发约定的每次运行独有池调度。在纯 `ptc` 下，模型直呼其他任何可见工具都会在策略之前解析为 `UNKNOWN_TOOL`——通告面与可调用面保持一致。中间绑定值只存在于执行局部；只有外层 `run_code` 结果有硬大小上限。[执行器塌缩 note](../../../.agents/notes/implemented/bug-fix/2026-08-07-ptc-executor-collapse.zh.md) 拥有该收束约定。
 
 新子调用使用 `<parent>:ptc:<n>` 标识。消费方将这些标识视为不透明值，并通过精确相等关联事件；恢复的历史标识保留原始字节。[PTC mode 决策](../../../.agents/notes/implemented/feature/2026-06-15-ptc.zh.md) 负责持久化命名与恢复规则。
 
-当已挂载运行时支持覆盖时，`run_code` 接受 `timeoutMs`；其 schema 报告配置的默认值和上限、运行时使用说明及 Session 工作目录。Node 默认值为 120,000 ms，上限为 600,000 ms，包含嵌套工具和审批等待。更宽的 `sandbox_permissions` 模式要求非空 `justification`，并在程序启动前获得审批。授权仅用于该次完整执行；常驻 Session 策略与嵌套工具保留各自权限。程序不会自动重放：显式重试被拒程序前，应检查先前已发生的效果。
+当已挂载运行时支持覆盖时，`run_code` 接受 `timeoutMs`；其 schema 报告配置的默认值和上限，以及运行时使用说明。Node 默认值为 120,000 ms，上限为 600,000 ms，包含嵌套工具和审批等待。更宽的 `sandbox_permissions` 模式要求非空 `justification`，并在程序启动前获得审批。授权仅用于该次完整执行；常驻 Session 策略与嵌套工具保留各自权限。程序不会自动重放：显式重试被拒程序前，应检查先前已发生的效果。
 
 <a id="extension-points"></a>
 ### 扩展点

package/lib/index.js

@@ -1206,6 +1206,7 @@ function createRunCodeTool(registry, options) {
 					mode: approvedMode
 				};
 			}
+			const cwd = await options.resolveWorkingDirectory(exec);
 			exec.signal.throwIfAborted();
 			const runController = new AbortController();
 			const onOuterAbort = () => {
@@ -1334,7 +1335,8 @@ function createRunCodeTool(registry, options) {
 								arguments: normalized.logged,
 								isError: result.isError,
 								...result.error?.info === void 0 ? {} : { error: result.error.info },
-								content: logged
+								content: logged,
+								...result.meta === void 0 ? {} : { meta: result.meta }
 							});
 						})().finally(() => {
 							logWork.delete(task);
@@ -1418,7 +1420,7 @@ function createRunCodeTool(registry, options) {
 							}
 						}],
 						signal: runController.signal,
-						...exec.agent?.session.header.cwd !== void 0 ? { cwd: exec.agent.session.header.cwd } : {},
+						...cwd !== void 0 ? { cwd } : {},
 						...policy !== void 0 ? { sandboxPolicy: policy } : {},
 						...args.timeoutMs !== void 0 ? { timeoutMs: args.timeoutMs } : {}
 					}));
@@ -1452,7 +1454,7 @@ function createRunCodeTool(registry, options) {
 		get: () => {
 			const runtime = peekRuntime();
 			const instructions = runtime?.executionInstructions;
-			return resolveFlavor(peekRuntime).description + (instructions ? ` ${instructions}` : "") + (runtime === void 0 ? "" : " The working directory is the Session's current directory.") + escalationGuidance(runtime);
+			return resolveFlavor(peekRuntime).description + (instructions ? ` ${instructions}` : "") + (runtime === void 0 ? "" : " Each program starts in the Session's current directory. Running programs keep their initial directory.") + escalationGuidance(runtime);
 		}
 	});
 	Object.defineProperty(definition, "parameters", {
@@ -1762,8 +1764,7 @@ function renderToolsSdk(schemas) {
 *
 * Under `mode: 'ptc'` the native tool schemas are omitted from the request, so this generated
 * SDK is the model's ONLY source for each tool's argument names, required fields, types,
-* descriptions, and canonical output shapes; under `mode: 'both'` the native schemas ship
-* alongside it and it is one of two. Object-shaped arguments and outputs therefore render as one
+* descriptions, and canonical output shapes. Object-shaped arguments and outputs therefore render as one
 * named `TypedDict` per tool (and per nested object), not an opaque `dict[str, Any]`, so the
 * shape survives into the program under the mode that has nothing else to carry it.
 * @module @qilin-agent/tools/src/py-types
@@ -2665,11 +2666,7 @@ function resolveMaxParallelSubCalls(value) {
 var ToolRuntime = class extends Service {
 	static inject = ["systemPrompt"];
 	static Config = z.object({
-		mode: z.union([
-			"native",
-			"ptc",
-			"both"
-		]).default("native"),
+		mode: z.union(["native", "ptc"]).default("native"),
 		maxParallelSubCalls: z.natural().min(1).default(10)
 	});
 	/** Internal staged view consumed by `qilin-agent-loop`'s parallel scheduler. */
@@ -2722,7 +2719,7 @@ var ToolRuntime = class extends Service {
 	* the deployment is inconsistent. Its order places the rule before that
 	* guidance rather than after it.
 	*
-	* `both` renders empty: native calls do execute there, so the rule is false.
+	* Native scopes render no instruction.
 	* @returns the section registration.
 	*/
 	collapseSection() {
@@ -2783,6 +2780,12 @@ var ToolRuntime = class extends Service {
 	*/
 	requirePtcTransport() {
 		this.ptcTransport ??= createRunCodeTool(this, {
+			resolveWorkingDirectory: async (exec) => {
+				if (exec.agent === void 0) return void 0;
+				const directories = this.ctx.get("workingDirectory");
+				if (directories === void 0) throw new Error("qilin-tools: run_code with an Agent requires workingDirectory");
+				return directories.ensure(exec.agent, exec.signal);
+			},
 			requireRuntime: () => this.requirePtcRuntime(this.defaultMode),
 			peekApprover: () => this.ctx.get("approval"),
 			resolveSandboxPolicy: (exec) => {
@@ -2836,14 +2839,9 @@ var ToolRuntime = class extends Service {
 			knownNames: [...view.knownNames]
 		};
 		this.requirePtcRuntime(mode);
-		const schemas = [...view.visible.values()].map((definition) => this.schemaOf(definition, false));
-		if (mode === "ptc") return {
-			schemas: schemas.filter((schema) => schema.name === RUN_CODE_NAME),
-			knownNames: [RUN_CODE_NAME]
-		};
 		return {
-			schemas,
-			knownNames: [...view.knownNames, RUN_CODE_NAME]
+			schemas: [...view.visible.values()].map((definition) => this.schemaOf(definition, false)).filter((schema) => schema.name === RUN_CODE_NAME),
+			knownNames: [RUN_CODE_NAME]
 		};
 	}
 	/**
@@ -3542,7 +3540,7 @@ var ToolRuntime = class extends Service {
 		}
 		const content = snapshotProjection(tool.name, "render", rendered);
 		let meta;
-		if (exec.parent === void 0 && tool.output.presentationMeta !== void 0) {
+		if (tool.output.presentationMeta !== void 0) {
 			let projected;
 			try {
 				projected = tool.output.presentationMeta(exec.arguments, value);

package/lib/types/index.d.ts

@@ -108,7 +108,7 @@ export interface ToolOutputDefinition {
     readonly schema: JsonSchemaNode;
     /** Pure projection from validated arguments and value to Native/model content. */
     render(args: unknown, value: JsonValue): ContentBlock[];
-    /** Pure replayable presentation projection, computed only for top-level calls. */
+    /** Pure replayable presentation projection for native and nested calls. */
     presentationMeta?(args: unknown, value: JsonValue): JsonValue;
 }
 /** A registered tool: its schema plus the execution function. */
@@ -472,15 +472,15 @@ export type PostToolDecision = {
     additionalContexts?: UserMessage[];
 };
 /** How the registry presents its tools to the model (see {@link Config.mode}). */
-export type ToolPresentationMode = 'native' | 'ptc' | 'both';
+export type ToolPresentationMode = 'native' | 'ptc';
 /** Plugin config: how the registered tools are presented to the model. */
 export interface Config {
     /**
      * Model presentation. `native` (default) sends every visible schema; `ptc`
      * sends only `run_code` plus a generated SDK prompt and collapses the
      * executor to the same surface (a model-direct call may only name
-     * `run_code`; `run_code` SDK sub-dispatches keep every visible tool); `both`
-     * sends both forms. PTC mode requires a `ctx.ptcRuntime` whose `language`
+     * `run_code`; `run_code` SDK sub-dispatches keep every visible tool).
+     * PTC mode requires a `ctx.ptcRuntime` whose `language`
      * has a registered SDK renderer (TypeScript or Python) and fail prompt
      * assembly when it is absent or has no renderer. Under `ptc`, native names
      * in `toolOrder` are invalid.
@@ -555,7 +555,7 @@ export declare class ToolRuntime extends Service {
      * the deployment is inconsistent. Its order places the rule before that
      * guidance rather than after it.
      *
-     * `both` renders empty: native calls do execute there, so the rule is false.
+     * Native scopes render no instruction.
      * @returns the section registration.
      */
     private collapseSection;

package/lib/types/index.js

@@ -222,7 +222,7 @@ function resolveMaxParallelSubCalls(value) {
 export class ToolRuntime extends Service {
     static inject = ['systemPrompt'];
     static Config = z.object({
-        mode: z.union(['native', 'ptc', 'both']).default('native'),
+        mode: z.union(['native', 'ptc']).default('native'),
         maxParallelSubCalls: z.natural().min(1).default(10),
     });
     /** Internal staged view consumed by `qilin-agent-loop`'s parallel scheduler. */
@@ -275,7 +275,7 @@ export class ToolRuntime extends Service {
      * the deployment is inconsistent. Its order places the rule before that
      * guidance rather than after it.
      *
-     * `both` renders empty: native calls do execute there, so the rule is false.
+     * Native scopes render no instruction.
      * @returns the section registration.
      */
     collapseSection() {
@@ -348,6 +348,16 @@ export class ToolRuntime extends Service {
      */
     requirePtcTransport() {
         this.ptcTransport ??= createRunCodeTool(this, {
+            resolveWorkingDirectory: async (exec) => {
+                // Only Agent-owned PTC requires directory state; native registries
+                // and unowned programs can run without this service.
+                if (exec.agent === undefined)
+                    return undefined;
+                const directories = this.ctx.get('workingDirectory');
+                if (directories === undefined)
+                    throw new Error('qilin-tools: run_code with an Agent requires workingDirectory');
+                return directories.ensure(exec.agent, exec.signal);
+            },
             requireRuntime: () => this.requirePtcRuntime(this.defaultMode),
             peekApprover: () => this.ctx.get('approval'),
             resolveSandboxPolicy: (exec) => {
@@ -419,13 +429,10 @@ export class ToolRuntime extends Service {
         // language with no SDK renderer.
         this.requirePtcRuntime(mode);
         const schemas = [...view.visible.values()].map(definition => this.schemaOf(definition, false));
-        if (mode === 'ptc') {
-            return {
-                schemas: schemas.filter(schema => schema.name === RUN_CODE_NAME),
-                knownNames: [RUN_CODE_NAME],
-            };
-        }
-        return { schemas, knownNames: [...view.knownNames, RUN_CODE_NAME] };
+        return {
+            schemas: schemas.filter(schema => schema.name === RUN_CODE_NAME),
+            knownNames: [RUN_CODE_NAME],
+        };
     }
     /**
      * Resolve the PTC runtime or throw the actionable misconfiguration error.
@@ -1194,7 +1201,7 @@ export class ToolRuntime extends Service {
         }
         const content = snapshotProjection(tool.name, 'render', rendered);
         let meta;
-        if (exec.parent === undefined && tool.output.presentationMeta !== undefined) {
+        if (tool.output.presentationMeta !== undefined) {
             let projected;
             try {
                 projected = tool.output.presentationMeta(exec.arguments, value);

package/lib/types/ptc.d.ts

@@ -47,6 +47,8 @@ export declare class CodeRunFailedError extends HarnessError {
  * off its public service API and flow here as closures instead.
  */
 export interface RunCodeBridgeOptions {
+    /** Captures the calling Session current directory before program creation. */
+    resolveWorkingDirectory: (exec: ToolRunContext) => Promise<string | undefined>;
     /** Reads the approval channel when a program requests a wider sandbox mode. */
     peekApprover: () => ApprovalService | undefined;
     /** Resolves standing Session authority only for a runtime that enforces file policy. */

package/lib/types/ptc.js

@@ -317,6 +317,7 @@ export function createRunCodeTool(registry, options) {
                 });
                 policy = { ...standingPolicy, mode: approvedMode };
             }
+            const cwd = await options.resolveWorkingDirectory(exec);
             exec.signal.throwIfAborted();
             // The run-scoped abort: follows the outer signal in, and fires when the
             // run settles for ANY reason, so an in-flight sub-dispatch is aborted
@@ -480,6 +481,7 @@ export function createRunCodeTool(registry, options) {
                                 isError: result.isError,
                                 ...result.error?.info === undefined ? {} : { error: result.error.info },
                                 content: logged,
+                                ...result.meta === undefined ? {} : { meta: result.meta },
                             });
                         })().finally(() => { logWork.delete(task); });
                         logWork.add(task);
@@ -590,7 +592,7 @@ export function createRunCodeTool(registry, options) {
                                 errorClass: { name: 'ToolCallError', memberNameProperty: 'toolName' },
                             }],
                         signal: runController.signal,
-                        ...exec.agent?.session.header.cwd !== undefined ? { cwd: exec.agent.session.header.cwd } : {},
+                        ...cwd !== undefined ? { cwd } : {},
                         ...policy !== undefined ? { sandboxPolicy: policy } : {},
                         ...args.timeoutMs !== undefined ? { timeoutMs: args.timeoutMs } : {},
                     }));
@@ -641,7 +643,7 @@ export function createRunCodeTool(registry, options) {
             const instructions = runtime?.executionInstructions;
             return resolveFlavor(peekRuntime).description
                 + (instructions ? ` ${instructions}` : '')
-                + (runtime === undefined ? '' : " The working directory is the Session's current directory.")
+                + (runtime === undefined ? '' : " Each program starts in the Session's current directory. Running programs keep their initial directory.")
                 + escalationGuidance(runtime);
         },
     });

package/lib/types/py-types.d.ts

@@ -7,8 +7,7 @@
  *
  * Under `mode: 'ptc'` the native tool schemas are omitted from the request, so this generated
  * SDK is the model's ONLY source for each tool's argument names, required fields, types,
- * descriptions, and canonical output shapes; under `mode: 'both'` the native schemas ship
- * alongside it and it is one of two. Object-shaped arguments and outputs therefore render as one
+ * descriptions, and canonical output shapes. Object-shaped arguments and outputs therefore render as one
  * named `TypedDict` per tool (and per nested object), not an opaque `dict[str, Any]`, so the
  * shape survives into the program under the mode that has nothing else to carry it.
  * @module @qilin-agent/tools/src/py-types

package/lib/types/py-types.js

@@ -7,8 +7,7 @@
  *
  * Under `mode: 'ptc'` the native tool schemas are omitted from the request, so this generated
  * SDK is the model's ONLY source for each tool's argument names, required fields, types,
- * descriptions, and canonical output shapes; under `mode: 'both'` the native schemas ship
- * alongside it and it is one of two. Object-shaped arguments and outputs therefore render as one
+ * descriptions, and canonical output shapes. Object-shaped arguments and outputs therefore render as one
  * named `TypedDict` per tool (and per nested object), not an opaque `dict[str, Any]`, so the
  * shape survives into the program under the mode that has nothing else to carry it.
  * @module @qilin-agent/tools/src/py-types

package/lib/types/schema.d.ts

@@ -188,7 +188,7 @@ export interface DefineToolOptions<S extends ParameterSchemaSpec, O extends Valu
         readonly schema: O;
         /** Pure Native/model rendering of one validated canonical value. */
         render(args: InferArgs<S>, value: InferValue<NoInfer<O>>): ContentBlock[];
-        /** Pure replayable presentation metadata for direct top-level calls. */
+        /** Pure replayable presentation metadata for native and nested calls. */
         presentationMeta?(args: InferArgs<S>, value: InferValue<NoInfer<O>>): JsonValue;
     };
     /** Requests deferred loading of the tool definition; see {@link @qilin-agent/llm#ToolSchema.deferLoading}. */

package/lib/types/types.d.ts

@@ -5,6 +5,7 @@
  */
 import type { ToolCallId } from '@qilin-agent/llm/brand';
 import type { ContentBlock } from '@qilin-agent/llm/types';
+import type { JsonValue } from '@qilin-agent/util-values';
 /** Payload recorded when one nested PTC mode Tool dispatch starts. */
 export interface PtcDispatchStartEventData {
     rootCallId: ToolCallId;
@@ -17,6 +18,8 @@ export interface PtcDispatchStartEventData {
 export interface PtcDispatchEventData extends PtcDispatchStartEventData {
     isError: boolean;
     content: ContentBlock[];
+    /** Replayable tool-owned presentation metadata, separate from model content. */
+    meta?: JsonValue;
     /** Optional failure identity and raw user-facing detail, outside model-facing content. */
     error?: {
         name: string;
@@ -45,10 +48,10 @@ declare module '@qilin-agent/session/types' {
          * `tool/ptc-dispatch-start` with the same `subCallId`), the tool `name`
          * with the same JSON-normalized `arguments`, and the sub-call's complete
          * durable outcome in `tool/result`'s own vocabulary (`content` + `isError`
-         * + optional structured `error`), so UIs and SDKs render a sub-call through
-         * the exact path used for a native call. Every started sub-call settles
-         * with exactly one of these (abort included: the aborted pipeline result
-         * is an `isError` outcome).
+         * + optional presentation `meta` and structured `error`), so UIs and SDKs
+         * render a sub-call through the exact path used for a native call. Every
+         * started sub-call settles with exactly one of these (abort included: the
+         * aborted pipeline result is an `isError` outcome).
          * Log-only: `deriveMessages()` ignores it, so sub-calls never re-enter
          * model context; persistence and UIs get every call. Appended inside the
          * parent `run_code`'s execution (the bridge drains in-flight dispatches

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@qilin-agent/tools",
   "description": "Tool registry and execution pipeline for the QiLin",
-  "version": "3.1.3",
+  "version": "3.1.5",
   "publishConfig": {
     "access": "public"
   },
@@ -39,33 +39,35 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@qilin-agent/agent": "3.1.3",
-    "@qilin-agent/scope": "3.1.3",
-    "@qilin-agent/ptc-runtime": "3.1.3",
     "@qilin-agent/kylin": "~4.0.3",
-    "@qilin-agent/session": "3.1.3",
-    "@qilin-agent/system-prompt": "3.1.3",
-    "@qilin-agent/user-approval": "3.1.3",
-    "@qilin-agent/llm": "3.1.3",
-    "@qilin-agent/sandbox": "3.1.3",
-    "@qilin-agent/sandbox-policy": "3.1.3"
+    "@qilin-agent/ptc-runtime": "3.1.5",
+    "@qilin-agent/agent": "3.1.5",
+    "@qilin-agent/llm": "3.1.5",
+    "@qilin-agent/system-prompt": "3.1.5",
+    "@qilin-agent/session": "3.1.5",
+    "@qilin-agent/user-approval": "3.1.5",
+    "@qilin-agent/sandbox": "3.1.5",
+    "@qilin-agent/working-directory": "3.1.5",
+    "@qilin-agent/scope": "3.1.5",
+    "@qilin-agent/sandbox-policy": "3.1.5"
   },
   "dependencies": {
-    "@qilin-agent/brand": "3.1.3",
-    "@qilin-agent/util-values": "3.1.3",
+    "@qilin-agent/brand": "3.1.5",
+    "@qilin-agent/util-values": "3.1.5",
     "@qilin-agent/schemastery": "~3.18.3"
   },
   "devDependencies": {
-    "@qilin-agent/agent": "3.1.3",
-    "@qilin-agent/ptc-runtime": "3.1.3",
     "@qilin-agent/kylin": "~4.0.3",
-    "@qilin-agent/llm": "3.1.3",
-    "@qilin-agent/session": "3.1.3",
-    "@qilin-agent/session-projection": "3.1.3",
-    "@qilin-agent/scope": "3.1.3",
-    "@qilin-agent/user-approval": "3.1.3",
-    "@qilin-agent/system-prompt": "3.1.3",
-    "@qilin-agent/sandbox": "3.1.3",
-    "@qilin-agent/sandbox-policy": "3.1.3"
+    "@qilin-agent/agent": "3.1.5",
+    "@qilin-agent/ptc-runtime": "3.1.5",
+    "@qilin-agent/scope": "3.1.5",
+    "@qilin-agent/llm": "3.1.5",
+    "@qilin-agent/session-projection": "3.1.5",
+    "@qilin-agent/system-prompt": "3.1.5",
+    "@qilin-agent/sandbox": "3.1.5",
+    "@qilin-agent/user-approval": "3.1.5",
+    "@qilin-agent/working-directory": "3.1.5",
+    "@qilin-agent/sandbox-policy": "3.1.5",
+    "@qilin-agent/session": "3.1.5"
   }
 }