内置工具清单
tool-catalog.md 由 scripts/gen-tool-catalog.ts 生成（真实启动每个工具插件读 ctx.tools.schemas()），共 24 个包条目、51 个工具名（21 个 tool-* 包 + dsh-tools + dsh-plan-mode + dsh-schedule；另有 shipped alias subagent_fork）：
| 类别 | 工具 |
|---|---|
| 交互与计划 | ask_user_question（暂停等人类答案）、exit_plan_mode |
| 代码执行 | run_code（TS async 函数体，await tools.name(args) 调其它工具；Code Mode 保留通道） |
| Shell | bash（每次全新 shell，支持 run_in_background 注册 jobs）、bash 持久 PTY 变体（按部署二选一）、pwsh |
| 文件系统 | read / write / edit / read_image、str_replace_editor（view/create/str_replace/insert）、glob / grep（经 ctx.subprocess 跑内置 ripgrep，不依赖宿主 rg；超限走 spill） |
| 终端 PTY | terminal_open/send/read/signal/list/close（owner 隔离，opt-in） |
| 后台任务 | job_list / job_output / job_kill（后台 bash、PTY、subagent 共用控制器） |
| Subagent/编排 | subagent(+subagent_fork)、send_message / interrupt_agent / list_agents、report（子→父）、workflow（JS 编排脚本 fan-out）、ralph（fresh-agent 循环） |
| 目标与调度 | create_goal / get_goal / update_goal（需 direct-human root authority）、schedule_create/delete/list |
| 知识与查询 | skill、lsp（goToDefinition/findReferences/hover；缺席返回 LSP_UNAVAILABLE）、session_event_read/search/trace、session_search/trace（opt-in）、todo_write |
| Web | web_fetch / web_search（provider 隐藏在 ctx.web 后：deepseek/exa/perplexity/fetch-http） |
| 动态扩展 | cordis_define/run/stop/undefine + cordis_inspect_*（让模型定义/激活动态 Cordis 包；刻意不进任何出货树，需 ctx.dynamicCordisRunner，带 vm sandbox） |
工具执行管线（10 阶段）
三个 waterfall 均可变换调用（完整 Mermaid 图见上游 tool-execution-pipeline.md）：
- 记录与展示：assistant 消息含 tool-call block → 先记
tool/callsession 事件（执行前落日志），UI 显示 pending 卡片。参数一次性物化为 lossless-JSON 深冻结——参数不可被改写（历史、审计、UI、执行必须一致）。 tools/pre-executewaterfall：hooks、permission、sandbox 策略在此。返回PreToolDecision: allow | deny(reason) | ask(reason?)。ctx.approval一次性审批（仅 ask 分支）：仅allowed-once放行（见 security-sandbox）。- 注册的 monotonic guards（
ToolGuard）：只能 deny 或弃权，没有 allow 结果——后续 listener 无法把 denial 翻回 permission。 tools/executewaterfall（around-dispatch）：timeout/retry/metrics 包装器；只可替换exec.signal（registry 会与 caller 原 signal 重新 fuse）。随后执行工具execute()body。（tool-fs 写变更在 body 内先过fs/write-intent/fs/edit-intent单槽决策 waterfall——read-before-write 策略由 fs-observation-policy 实现。）tools/post-executewaterfall：PostToolDecision— accept（可替换 content 或 value 二选一）、block（结果变带纠正反馈的 isError）、附加additionalContexts。- Registry 外层 normalization：无损快照，失败转 JSON-safe
isError。 ToolDefinition.finalizeContent：工具自有的最后一道 content-only 同步不变量。tools/resultemit：冻结的权威最终结果，观察者只读、失败被隔离。- 落事件与 UI：记
tool/resultsession 事件（唯一 model-facing 结果）；additionalContexts以 FIFO 在 tool results 之后注入 user/message。
调度：registry 用 executionMode() 分类每个调用为 parallel / exclusive——只有显式 true 才并行，fail-closed；agent loop 据此组织 barrier 与滚动池。未知工具/抛错都变结构化错误（UNKNOWN_TOOL），不终止回合。
工具开发契约要点
（详见 extension-development）defineTool 自动校验参数；execute() 返回唯一规范 JSON 值（output.schema），由 output.render(args, value) 渲染模型可见内容；抛错 = isError；遵守 exec.signal；长任务走 ctx.jobs；UI 卡片 presentCall/presentResult 必须是 args 的纯函数（流式和 replay 都会跑）。
Code Mode（code-runtime）
ctx.codeRuntime（可选 seam）是 run_code 背后的执行底座：
CodeRunRequest { program, bindings, signal? }：program 以 async 函数体运行（顶层 await/return）；默认值（时间预算、输出上限）是实现侧配置，请求里无隐藏旋钮。CodeRunResult { value?, logs[], error? }：错误是结果字段而非 rejection。失败分类正交：exception | timeout | abort | worker-exit | invalid-output | output-limit。- bindings：每个 namespace 成为程序内全局对象（Code Mode 传
tools）；参数/返回值必须 lossless JSON；binding 名按敌意输入处理（null-prototype）。 - 描述符：
language（只有 typescript 有已发布后端 worker-thread）与isolation（worker-thread|process|container，纯诊断标签，不是安全声明）。 - registry 在
mode: code下run_code是唯一 wire 贡献，其它工具以生成的 SDK 声明；子调用重新进入完整受保护管线。mode: code下模型直连原生工具名会被拒为UNKNOWN_TOOL。
配置体系（config-catalog）
scripts/gen-config-catalog.ts 生成（约 105 个带配置的包条目）：收录每个可加载包的 config: 块声明 + JSDoc + Requires:（inject 的服务键）。生成器交叉校验 runtime schemastery schema 与粘贴声明。三轴参考：部署轴看 config-catalog、接线轴看 subsystem 页 Cordis API 区、模型轴看 tool-catalog。
相关页面
- security-sandbox — pre-execute 阶段的审批/沙箱强制
- extension-development — 写一个工具插件的完整步骤