2026-08-25implementedarchitecturearchived 2026-09-04

Rename code-mode to ptc — the transport is named PTC, user-facing copy says PTC mode

将 code-mode 重命名为 ptc——传输层命名为 PTC，用户文案使用 PTC mode

The tool-registry presentation mode that exposes tools through a generated SDK and the `run_code` transport shipped under the name Code Mode, while the client preset that selects it already shipped as "PTC mode" (locale `presetPtcName: 'PTC mode'`, zh `PTC 模式`). One feature had two names: config values, plugin and event names, files, and documentation said `code`/`code-mode`, and the user-facing name said "PTC mode".

.agents/notes/archived/architecture/2026-08-25-rename-code-mode-to-ptc.md

English

Problem

The tool-registry presentation mode that exposes tools through a generated SDK and the run_code transport shipped under the name Code Mode, while the client preset that selects it already shipped as "PTC mode" (locale presetPtcName: 'PTC mode', zh PTC 模式). One feature had two names: config values, plugin and event names, files, and documentation said code/code-mode, and the user-facing name said "PTC mode". A pre-release rename must update every reference together — no compatibility aliases.

Decision

The feature is renamed to PTC (programmatic tool calls). Code identifiers use ptc — the transport is not a sibling of plan-mode, so the identifier does not carry -mode. User-facing prose keeps "PTC mode" (EN) / "PTC 模式" (zh), matching the shipped preset name.

Renamed in this PR:

config value tools.mode: 'code' → 'ptc' (ToolPresentationMode and the zod unions in dsh-tools and dsh-agent-tool-presentation)
preset directory presets/code/ → presets/ptc/ (preset id ptc)
source and test files code-mode.ts → ptc.ts and friends; root demo demo:code-mode → demo:ptc (scripts/demo-ptc.mjs)
the dispatch waterfall tools/code-dispatch-log → tools/ptc-dispatch-log and types CodeDispatch* → PtcDispatch*
prompt rule tools:code-only → tools:ptc-only
prose "Code Mode" → "PTC mode" / "PTC 模式" in docs, READMEs, and the eight implemented Agent Notes whose topic names the feature (those files were renamed in place)

The session-persistent vocabulary remains deferred: the durable event types tool/code-dispatch / tool/code-dispatch-start, the logged plugin name tools-code-mode, and the sub-call id segment :code:. Renaming those values is a structural Session-format change and requires its own adjacent edge after the identity v0-to-v1 foundation.

Kept unchanged: run_code and its code parameter (they name the program payload, not the mode), CodeSdkLanguage, CodeRunFailedError, the dsh-code-runtime* package family, the third-party codex-code-mode-host binary name, and every frozen archived note.

Alternatives considered

ptc-mode identifiers — rejected: PTC is a tool-presentation transport, not a mode in the plan-mode sense, and the identifier should not claim that kinship.
Surface-only rename — rejected: the pre-release stance updates every reference together.
Renaming run_code too — rejected: the tool name describes running a program, not the mode, and is model-facing API surface.
Renaming the durable event vocabulary without an adjacent edge — rejected: renaming tool/code-dispatch* in place would make pre-rename Session logs unreadable; that rename requires a later structural format version and explicit migration.

Consequences

Configs with mode: code and preset ids code are unsupported on this build. The session-persistent vocabulary still says tool/code-dispatch*, tools-code-mode, and :code:; the identity v0-to-v1 edge preserves those values, so no structural version change belongs to this rename. A later adjacent edge must rename that vocabulary and refresh the dispatch-bearing fixtures (version mechanics). The shipped decision this note renames is the PTC foundation note.

中文

问题

通过生成的 SDK 与 run_code 传输层向模型呈现工具的注册表模式，发布时用的名字是 Code Mode；而选择该模式的客户端预设早已以「PTC mode」发布（locale presetPtcName: 'PTC mode'，中文 PTC 模式）。同一功能有两套名字：配置值、插件与事件名、文件与文档写的是 code／code-mode，用户可见的名字却是「PTC mode」。预发布阶段的更名必须一次性更新所有引用——不加任何兼容别名。

决策

该功能更名为 PTC（programmatic tool calls，程序化工具调用）。代码标识符使用 ptc——该传输层并非 plan-mode 的同类模式，因此标识符不带 -mode。用户可见文案沿用「PTC mode」（英文）／「PTC 模式」（中文），与已发布的预设名一致。

本 PR 完成的重命名包括：

配置值 tools.mode: 'code' → 'ptc'（ToolPresentationMode 以及 dsh-tools、dsh-agent-tool-presentation 中的 zod union）
预设目录 presets/code/ → presets/ptc/（预设 id 为 ptc）
源文件与测试文件 code-mode.ts → ptc.ts 等；根 demo demo:code-mode → demo:ptc（scripts/demo-ptc.mjs）
分发 waterfall tools/code-dispatch-log → tools/ptc-dispatch-log，类型 CodeDispatch* → PtcDispatch*
提示词规则 tools:code-only → tools:ptc-only
文档、README 与八个以该功能命名的 implemented Agent Note 中的文案 "Code Mode" → "PTC mode"／"PTC 模式"（这些 Note 文件一并就地改名）

会话持久词汇继续延后处理：持久事件类型 tool/code-dispatch／tool/code-dispatch-start、日志中的插件名 tools-code-mode、子调用 id 段 :code:。重命名这些值属于结构性 Session 格式变更，必须在恒等 v0-to-v1 基础之后拥有自己的相邻迁移边。

保持不变：run_code 及其 code 参数（它们描述程序载荷，而非模式）、CodeSdkLanguage、CodeRunFailedError、dsh-code-runtime* 包族、第三方二进制名 codex-code-mode-host，以及所有冻结的 archived Note。

备选方案

使用 ptc-mode 标识符——否决：PTC 是工具呈现传输层，不是 plan-mode 意义上的模式，标识符不应宣示这种亲缘关系。
仅重命名表面——否决：预发布立场要求一次性更新所有引用。
连 run_code 一起改名——否决：该工具名描述的是运行程序，不是模式，而且是对模型可见的 API 表面。
不提供相邻迁移边就重命名持久事件词汇——否决：就地重命名 tool/code-dispatch* 会让更名前的 Session 日志无法读取；该重命名需要后续结构格式版本与显式迁移。

后果

配置中写 mode: code、预设 id 为 code，在本构建上不再受支持。会话持久词汇仍为 tool/code-dispatch*、tools-code-mode 与 :code:；恒等 v0-to-v1 迁移边会保留这些值，因此本次更名不包含结构版本变更。后续相邻迁移边必须重命名该词汇并刷新包含分发的 fixture（参见版本机制）。本 Note 所更名的已发布决策是 PTC 基础 Note。