03. 工具和权限

翻译说明： 本页是与英文源规格一一对应的机器辅助翻译。代码、协议字段和标识符保持原文；如翻译与英文源事实有歧义，以英文版本为准。

应用的决定：D003、D004、D005、D006、D013、D015、D093、D114、D115、D181、D186、 D189、D190、D195（ADR 0057）、D315、D384（ADR 0211）、ADR 0087

0. 冻结政策总结

主题	决定
默认模式	Agent
Agent 工具	读取 / Glob / Grep / 写入 / 编辑 / Bash + 已注册的插件工具
Plan 工具	读取 / Glob / Grep / BrowserPreview / Bash / SubmitPlan + 声明 plan-safe 动作的插件工具
Goal 工具	读取 / Glob / Grep / BrowserPreview / Bash / SubmitGoal + 声明 plan-safe 动作的插件工具
Plan 和 Goal 硬拒绝	写入 / 编辑 / 没有 `planSafeActions` 的插件工具 / 未知工具 / 另一类的提交工具
插件 `planSafeActions`	非空的 `action` 字符串数组；运行时在 Plan/Goal 中隐藏没有该列表的插件工具，host 放行已列出的工具，plugin-runtime 拒绝列表外的任何动作（ADR 0211）
权限超时	120秒→拒绝
允许会话范围	工具名称
重击风格	非交互式；具有流输出的选定主机目录外壳
Edit 契约	行锚定操作 + 整文件 `tag`；不再有 `old_string`/`new_string`（ADR 0087）
询问工具	交互式多问题工具；无有效期期限；跳过的答案变成空输出字段

1. Goal

让代理完成工作，但默认情况下仍处于控制之下。

2. MVP内置工具

工具	风险	描述
`Read`	低	读取工作区中的文件；返回带行号的内容和 `[path#TAG]` 头
`new_context`	低	在下一个回合边界处启动一个新的上下文窗口；不接受任何参数并且不改变环境状态
`Glob`	低	按模式列出文件
`Grep`	低	内容搜索；本机有 `rg` 时优先用，否则进程内搜索；为每个文件生成 `tag`
`BrowserPreview`	低	在随应用打包的浏览器插件中打开与工作区相关的预览（若 `pi.browser` 被禁用则失败）
`EnterPlanMode`	低	主机验证后，将相同的 Agent 从 Agent 移动到 Plan
`SubmitPlan`	低	在新的 `.pi/plan/*.md` 工件中保留精确的 Markdown 字节并请求批准
`EnterGoalMode`	低	主机验证后，将相同的 Agent 从 Agent 移动到 Goal
`SubmitGoal`	低	在新的 `.pi/goal/*.md` 工件中保留精确的 Markdown 字节并请求批准
`Write`	高	Create/overwrite 文件；返回写入后的 `tag`
`Edit`	高	通过针对已校验 `tag` 的行锚定操作修改文件（18）
`Bash`	高	执行命令
`asktool`	低	询问一个或多个用户问题并将提交的答案作为工具输出返回

名称可以在实现过程中进行微调，但语义保持一致。

2. 1 延期辅助工具（D185、ADR 0048）

按照 pi 的编码代理默认值，第一个 Agent 请求仅激活 Read、Bash、Edit 和 Write； Glob 和 Grep 按需加载。 Plan 和 Goal 保留其 read/inspection 核心。Skill 有意不作延迟：/skill-id 调用会指示模型调用它，而模式中不存在的工具根本无法被调用，因此只要技能目录非空，它就会随第一个请求一起发送（D404、ADR 0230）。运行时还注册功能无需预先发送其完整模式：

Agent 模式下的 Glob 和 Grep
BrowserPreview
PluginCheck、PluginScaffold 和 PluginPack
插件声明的代理工具

这些工具出现在有界的 # On-demand tools 目录中，具有紧凑的结构描述。该模型使用确切的名称调用本地 ToolSearch 工具或能力查询；匹配的模式在下一个模型回合中可用。 sidecar 在每个新用户提示开始时重置此延迟集。主机权限、workspace/scratch 遏制、超时和审核规则加载工具时不会改变。 ToolSearch 本身从不执行工作区操作并且永远不会绕过 host-core 策略。

3. 常用工具约束

每个非交互式执行工具都必须具有：

JSON 架构/类型框参数定义 2、超时 3.工作空间路径验证 4.输出截断策略
跟踪ID
结构化结果

asktool 是交互式异常：它有一个类型化的请求事件，等待渲染器响应没有过期，并返回有界结构化工具结果。停止回合可以解决跳过的未决问题。

4. 路径规则

本机文件和搜索工具强制执行不同的路径形状（D208、ADR 0069）：

Read.path 是现有的常规文件。返回一个目录 INVALID_ARGUMENT 具有结构化 Glob 建议，而不是通用建议执行失败。
Glob.path 是目录搜索根。
Grep.path 可以是一个文件或一棵目录树。直接命名的文件是在没有步行兄弟姐妹的情况下进行搜索，而 include 仍然过滤其基础名称和每个产出预算保持不变。本机 PATH（以及 Unix login PATH）上有 rg 时 Grep 优先调用它，缺失或失败则回退到进程内搜索（D315）。面向模型的结果契约不变。

工具结果中的工作区相对路径使用 / 表示平台分隔符。在 POSIX 系统中，文件名里的字面量反斜杠保持不变，以确保结果可以回传给 Read 或 Edit；Windows 路径分隔符会被规范化为 /。

Agent 模式使 host-core/JSON 在 D185 下保持延迟。每个新用户提示都会重置它们的激活，因此目录发现通过 ToolSearch 激活 Glob 对于该提示，而不是猜测文件名或在目录。

运行时为每个规范参数名接受一个别名，并在主机看到调用之前把它折叠掉（D273）：

工具	规范名	接受的别名
`Read` / `Write` / `Edit` / `BrowserPreview`	`path`	`file_path`
`Glob` / `Grep`	`pattern`	`query`

两种拼写在 schema 中都是可选的，运行时要求恰好提供其中一个；两个都没给的调用以 INVALID_ARGUMENT 失败。当一次调用同时带上两个时，规范名胜出。Bash.timeout 在 schema 中放宽到 100000000，好让毫秒值先通过校验：超过 21,600 秒上限的值按毫秒读取并换算成秒，再夹到 21,600 秒（D273 / D329）。范围内的值（包括 600 和 1800）按秒读取。

对于持久的 sessionId，workspaceRoot 是从该会话的持久的项目绑定。它不是从可变的活动侧边栏读取的执行时的选项卡。
默认情况下，所有文件路径均相对于已解析的 workspaceRoot
标准化后，它们必须仍然驻留在工作空间内，除非调用收到显式外部路径许可
.. 转义和符号链接转义是外部路径请求，不是隐式的访问
符号链接在获得许可后立即执行之前再次解析批准，因此批准不能跳过规范化步骤
例外（D114）：会话临时目录内的绝对路径是 sessionId/workspaceRoot/workspaceRoot 的第二个合法根 — 请参阅§4b。两个根都运行相同的词汇+符号链接遏制防御。 sessionId/workspaceRoot/workspaceRoot/../Read 只能通过权限来寻址两个根之外的显式路径政策如下；拒绝或未经批准的请求将返回 TOOL_DENIED。

4a。显式外部路径权限

显式 path 参数在会话工作区之外解析，并且刮根是一项单独的功能。主机正常之前检查一下低风险自动允许决策：

auto 允许无卡外部路径；
ask和accept-edits发出普通权限卡；
allow-once 仅执行当前调用，而 allow-session 紧随其后现有的每个工具会话授予范围；
拒绝、超时或取消永远不会执行该操作；
相对 .. 转义和符号链接转义使用与绝对相同的规则路径；
成功的外部 ../Read/Write 结果携带 root: "external" 和绝对规范路径；外部 ../Read 匹配是绝对的因此访问在记录中仍然可见。

该例外仅适用于显式路径参数。它不扩展工作区根目录、Bash 的工作目录或任何隐式目录路径。

4b.会话临时目录 (D114)

Temporary/intermediate 代理生成的文件（一次性脚本，下载数据、草稿）不得弄脏用户的项目或其 git 状态。每个 session 在工作区之外获取一个临时目录：

text

<data_dir>/scratch/<sessionId>/

粘贴到作曲器中的操作系统剪贴板文件和图像通过以下方式具体化 Electron 主要低于 <data_dir>/scratch/<sessionId>/pasted/ 之前的绝对路径被捕获为瞬态输入框引用并序列化为 @ 及时发送参考。他们使用与其他会话相同的生命周期暂存数据并且不输入工作区、工件或持久提示作为二进制内容。

寻址。 该模型仅通过绝对路径寻址；路径在系统提示中公布。相对刀具路径始终解析反对工作区。 Bash 还导出 PI_SCRATCH_DIR。
遏制。 resolve_tool_path 首先尝试工作空间根目录，然后暂存根，应用相同的两层防御（词汇 .. 规范化+规范化祖先符号链接检查）到每个。符号链接植入内部的划痕无法到达工作区或其他任何地方。
权限。 Write/Edit，其 path 在词汇上位于会话的临时根自动允许，无需权限卡 - 他们不能触摸项目。词法检查仅跳过提示；执行仍在经过完整的解析器，因此它不是逃逸向量。 Plan 和 Goal 可以不公开 Write/Edit，因此临时自动允许规则无法使这些工具两者均可使用。契约模式 Bash 调用仍可能创建或变异当其权限模式允许时，擦除数据。
工件。 成功的暂存写入不会记录在 artifacts 表；工件驱动的文件选项卡代表工作区仅可交付成果，而文件界面仍可浏览活动的工作区。工具结果携带 root: "workspace" | "scratch" 来实现此目的决策和 UI 渲染显式。
工具覆盖率。 Write/Edit/path 使用工作区和暂存根； Write/Edit 默认情况下使用工作空间根目录，并且可以显式搜索范围临时目录或明确批准的外部目录。的模型应该使用有界本机搜索工具而不是 shell 目录散步。 BrowserPreview 在 v1 中仍然与工作区相关。它的主进程处理程序从原始持久会话中解析根，并且渲染器事件携带sessionId；选定的前台工作区从未使用过用于背景预览。
生命周期。 在第一个 Write/Edit/path 上延迟创建或会话的输入框剪贴板粘贴。使用 session.delete 删除。一个启动扫描删除会话不再存在的暂存目录和目录超过 7 天未受影响（crash/force-quit 后备；没有预定作业需要）。
项目切换不会重定向或取消后台会话的工具；会话 A 和 B 分别保留在项目 A 和 B 的沙箱中。
Temporary/path-less 会话没有工作空间根目录，即使是另一个项目是可见的。如果没有会话项目，高风险工具将不可用。
无法解析为持久会话的旧调用可能会使用选定的仅在兼容性窗口期间托管工作区。
会话 lookup/storage 错误使工具请求失败；它绝不能是被视为丢失的旧会话或重定向到选定的工作区。

4c。消息拥有的审核快照和回滚

Write 和 Edit 是结构化审核边界。对于一个成功的工作区根突变，host-core 在执行前捕获前一个文件并向工具结果添加有界审查证据：

type ReviewChange = {
  version: 1;
  snapshotId: string;
  messageId: string;
  path: string;
  operation: "write" | "edit" | "delete";
  status: "added" | "modified" | "deleted";
  state: "active" | "rolledBack";
  additions: number;
  deletions: number;
  hunks: DiffHunk[];
  binary?: boolean;
  truncated?: boolean;
  reversible: boolean;
};

渲染器保留并显示此记录以及工具消息；它不会从 Git、HEAD 或当前脏树重新计算 Review。
临时根、失败、拒绝和无法解析的写入没有 review 记录。二进制或超大内容可能会省略大块并且是不可逆的。
回滚由主机拥有并受哈希保护。它恢复以前捕获的字节，或删除新创建的文件，仅当当前内容仍然存在时等于后工具哈希。稍后的编辑将返回 conflict 而不进行触摸文件。完成的回滚会使该路径的会话快照条目失效，因此模型无法继续针对回滚已替换的 tag 进行编辑。
携带 MV DEST 的 Edit 在一次工具调用下记录两条条目——源删除和目标创建——回滚要么同时恢复两者，要么都不恢复。REM 记录为一次删除，其回滚恢复已捕获的字节。哈希保护使用完整摘要，而不是 16 位 tag。
查看工作区之外的实时快照文件，并随其一起删除会议;孤立会话目录在主机启动时被清除。

4d。突变排序和编辑恢复

Write 和 Edit 在每个会话中序列化。 Read/search 工具可能并行继续，不同的会话可能会变异不同的根同时，但一个会话永远不会有两个正在进行的突变。主持人持有在消耗全局突变槽之前每个会话突变允许，所以排队的突变在等待早期编辑时无法保留容量。

Edit 命名位置并且只提供新内容；它从不匹配已有文本。每次调用都携带由最后显示该内容的工具生成的整文件 tag，当 tag 无法哈希出实时文件、或锚点引用了本会话从未显示过的行时，主机拒绝该调用。完整契约——tag 计算、会话快照存储、操作语法、块解析、寄存器与漂移恢复——见 18-line-anchored-edit-contract；本节只保留排序与循环保护规则。代理突变工作流程是：

当交付内容位于广告中的工作空间。
如果专用工作树位于该根目录之外，请在以下目录中执行一项受保护的编辑使用 Bash 构建该工作树并验证结果差异。
编辑或补丁检查失败后，对当前的文件执行一次新的 Read 定位并重新生成一次更改。一旦某条路径用完它的恢复额度（18-line-anchored-edit-contract §9.3），该提示符中针对该路径的下一次失败 Edit——或第二个失败的 shell patch 命令（apply_patch、 git apply 或 patch）——返回终止工具结果，因此代理报告确切的不匹配后停止。不要手动编辑旧的统一差异大块标头或继续修复循环。
保持一条路径的突变是连续的，即使 read/search 调用是并行发行。

其 reveal 完整的 EDIT_LINES_UNSEEN 拒绝不受第 3 步重新读取的约束：错误本身已经显示了缺失的行并将其并入会话来源集，因此原样重试同一个 tag 即可应用。那次重试同时也是 EDIT_LINES_UNSEEN 在该路径上唯一的宽限，因此第二次确实会计入保护限额。

序列化同时保护快照存储，生产者与 Edit 都会修改它：没有按会话的突变许可，一次并发记录可能落在校验与写入之间。

在一个提示内同一路径累计三次失败后（见 18-line-anchored-edit-contract §9.3），第 3 次计数的失败 Edit——或第 3 次失败的 shell 修补命令（apply_patch、git apply 或 patch）——返回带有错误专属恢复提示的终止工具结果，代理随后停止并报告准确的不匹配。不要手动编辑旧的 unified-diff 块头，也不要继续修复循环。

5. Bash 规则

主机执行基线：

需要一个项目绑定的会话工作区
默认 cwd = 原始会话的 workspaceRoot
默认需要确认
设置强制 60 秒超时；接受 1 秒至 21,600 秒覆盖（D329）
分别流式传输 stdout 和 stderr，然后返回有界的最终输出
截断大输出而不混合两个流
没有交互式 TTY (MVP)
以非零值退出的命令返回 ok: false、isError: true 和 errorCode: TOOL_FAILED，同时保留其 exitCode、stdout 和 stderr 在 content 中，以便代理可以诊断命令而无需盲目重试。

Shell 目录 (D190) 公开稳定 ID windows-powershell、windows-pwsh、cmd、平台支持的 git-bash 和 bash。楼主坚持 defaultCommandShell；如果那个持续的选择后来变得不可用，有效的目录选择有意回退到第一个可用的目录平台外壳。一轮固定有效的 shell ID 和方言。 Bash 仍然存在 tool/protocol 名称，请求中单独携带固定的 shell ID。主机核心在生成之前再次解析该条目并拒绝更改的 ID/dialect 与 COMMAND_SHELL_CHANGED；设置写入拒绝不可用或 COMMAND_SHELL_INVALID 的平台 ID 错误。没有任意可执行路径或可执行路径哈希被接受作为 shell 标识。

PI_DESKTOP_BASH env 覆盖（bash 可执行文件的路径）
Unix：众所周知的位置（/bin/bash、/usr/bin/bash、/usr/local/bin/bash、Homebrew），然后是 PATH
Windows：来自 Git 的 Windows 的 bash.exe — 派生自 PATH 上的 git，然后是标准安装目录，然后是排除 System32 中的 WSL 启动器的 PATH

Unix 调用 bash -lc（登录 shell 为 Finder/Dock 启动保留配置文件路径）； Windows 使用 CREATE_NO_WINDOW 调用 bash -c
在 Unix 上，Bash 工具另外探测用户的登录 shell 以获取其信息路径 — $SHELL（回退 /bin/zsh → /bin/bash → /bin/sh） -lic 'printf %s "$PATH"'，5 秒范围内，每个进程缓存 — 并注入它进入每个子流程。 bash -lc 仅提供 bash 配置文件；上 macOS 默认 shell 是 zsh，因此 nvm/pnpm/Homebrew 初始化于否则，~/.zshrc / ~/.zprofile 对代理命令将不可见。探测是尽力而为：缺少 shell、非零退出或超时回退主机 PATH 不变。 Agent 命令保留 POSIX bash (D181 / ADR 0045)。
安装程序中没有捆绑 bash：Windows 的 Git 是 Windows 的先决条件（无论如何，该应用程序都需要 git）
解决失败返回稳定的 SHELL_NOT_FOUND 并提供安装指导
Windows PowerShell 和 cmd 使用其本机非交互式调用。
PowerShell 7 先解析 %ProgramFiles%\PowerShell\7（宿主进程为 32 位时为 ProgramW6432）下的 pwsh.exe，再回退到 PATH，覆盖机器级安装、Store、用户级与便携安装。它与 Windows PowerShell 5.1 共用同一调用契约，且从不被隐式选中，因此不会改变既有用户的默认 shell。解析失败返回 SHELL_NOT_FOUND，并列出已搜索的位置。
Git Bash 使用发现的 Git 来执行 Windows 可执行文件。
Unix Bash 使用经过批准的系统 Bash 条目。
用户中止和超时在返回之前终止整个进程树。

初始拒绝名单（可扩展）：

直接reading/writing工作空间外的敏感路径
未经确认的破坏性操作（由权限层控制的策略）

6. 权限模型

风险级别

风险	示例	默认政策
低	会话根目录内的 Read/Glob/Grep	自动允许
中等	低风险 network/metadata	政策确认或允许
高	Write/Edit/Bash	默认确认

决策类型

allow-once
allow-session
deny

稍后可能会添加：

allow-always-for-tool
allow-always-for-command-pattern

权限模式 (D115/D132)

高风险工具调用如何获得批准由权限模式控制：

模式	Write/Edit	Bash / 插件工具
`ask`（默认）	确认	确认
`accept-edits`	自动允许	确认
`auto`	自动允许	自动允许

显式外部工作空间路径是低风险行的一个例外：它是仅在 auto 中允许自动； ask 和 accept-edits 都证实了这一点。

每个工具调用的解析顺序 (host-core tools.execute)：

会话的持久化 permission_mode，除非是 inherit
应用程序设置中的全局 defaultPermissionMode (ask / accept-edits / auto) 3.ask

规则：

会话值存储在 sessions.permission_mode 中（inherit | ask | accept-edits | auto，默认 inherit，架构 v5）和通过 session.configure permissionMode 设置。
Plan 的硬拒绝胜过 Write/Edit 以及缺少 planSafeActions 的插件工具的所有权限模式。 auto 无法重新启用隐藏或拒绝的工具。
会话根目录内的低风险工具（allow-once/allow-session/deny）自动允许每种模式都和以前一样。
BrowserPreview 是显式只读 UI 检查功能，并且是在两种操作模式下均可用。
Plan 保留权限模式选择器。 Bash 在 ask 下得到确认并且 accept-edits，并且在 auto 下自动允许；因此 Plan 正在规划意图，而不是严格的只读安全配置文件。
allow-session 赠款继续在 ask 下运作，范围仅限于会议；在 BrowserPreview/ask 下，根本不需要它们。
暂存目录写入 (D114) 在每种模式下都保持无提示。
UI：设置→分段全局默认；输入框在中显示每个会话的芯片 Agent、Plan 和 Goal 的菜单提供了三种有效模式，无需单独的 global-default/inherit 条目。芯片和选定的菜单项显示有效模式；选择一个项目会存储该显式会话覆盖。现有的继承会话继续通过全局设置，直到用户选择一种模式。
强制执行仅适用于 host-core； sidecar/model 从未被告知模式并且不能影响它。

7. 权限流程

text

tool call
 → policy.evaluate()
 → allow? execute
 → need confirm? push to UI
 → deny? return tool error result

权限确认超时：

120秒后，自动拒绝（D005：失败关闭，不永远挂起）

8. 工具结果对模型的可见性

成功结果：给予模型
失败结果：提供给模型（带有错误信息）
用户拒绝：给模型明确的“用户拒绝权限”
敏感信息：在 persisting/displaying 之前进行编辑

9. 审计

各工具调用记录：

会话ID
转号
工具呼叫ID
工具名称
参数哈希/预览
存在显式路径时的 externalPathPermission 分类
决定
持续时间
成功/错误代码

MVP 可以通过写入 SQLite 或日志文件来启动。

审计行可以保留既有的分段时长字段用于取证检查：prompted （是否出示许可卡）、permissionWaitMs、durationMs（工具体）、 overheadMs（主机簿记）和 totalMs。拒绝调用携带工具体为零的相同字段。这些是结构化审计字段，不会作为 timing 日志行写入进程日志。关于当前的关键日志策略，请参见 09.日志记录和可观测性。

10. 操作模式矩阵

模式	Read/Glob/Grep	BrowserPreview	Write/Edit	重击	插件
Agent	允许	允许	许可政策	许可政策	注册风险政策
Plan	允许	允许	否认	Plan/`ask`：确认； `auto`：允许	仅 plan-safe 动作
Goal	允许	允许	否认	Plan/`ask`：确认； `auto`：允许	仅 plan-safe 动作

注释

权限 UI 之前，Plan 和 Goal 硬拒绝 Write/Edit 以及没有 planSafeActions 的插件工具；直接主机调用不能绕过矩阵。声明了非空列表的插件工具会被放行；运行器仍会拒绝列表外的任何动作（ADR 0211）。
Agent 模式使用权限卡或选定的自动策略 Write/Edit/Bash 和注册的插件工具。
当用户选择“自动”时，Plan 和 Goal Bash 可能会改变工作区或暂存状态；用户界面必须使这种权衡可见。
仅针对活动会话记住每个 toolName 的允许会话
会话授权遵循 sessionId 跨项目选项卡开关，并且永远不会由另一个会话或临时会话继承

10. 1 Plan 和 Goal 控制工具

new_context 在每种模式下都可用，无需确认：它只询问在下一回合边界压缩的运行时间，主机将在其上执行此操作一旦达到硬预算（参见 02-代理运行时 §5.1)。提交工具仅在其自己的合同模式下可用，并且必须是其辅助批次中唯一的工具调用。它保留了类型目录下新的独特工件中的确切 Markdown 字节（.pi/plan/*.md 为 SubmitPlan，.pi/goal/*.md 为 SubmitGoal）在创建一项待批准之前通过 host-core。 EnterPlanMode 和 EnterGoalMode 仅在 Agent 中可用，并且每个工具调用必须是唯一的在其批次中。主机验证持久模式、提案类型和任何转换之前的 active-turn/configuration 边界；可见的工具列表是指导，而不是安全边界。

10. 2 委派和子代理工具范围（D201、ADR 0062）

Task 仅在 Agent 模式下可用，并且仅当会话至少有一个子代理定义。 Plan 和 Goal 是只读合同协商，因此具有 Bash、Edit 或 Write 的代表将直接穿过它们。

定义声明其委托可以调用的工具。默认名称仅来自七个工作工具 Read、 Glob、Grep、BrowserPreview、Bash、Edit 和 Write。未声明 tools 时得到 Read、Glob、Grep；tools: "*" 表示全部七个。无法识别的名称会被删除并带有解析警告。

文档可以用 tools: inherit 或 tools: [inherit, Bash] 选择继承父会话的实时工具目录（ADR 0246 / D415）。Task 启动时运行时把 toolCatalog （含延迟的插件/MCP 工具）与可分配的额外工具取并集，再去掉 Task / TaskWait / TaskList / TaskStop、EnterPlanMode / EnterGoalMode、 asktool、new_context 和 ToolSearch。内置定义不默认开启。inherit 写在 Markdown 和设置里；host-core 会保留该标记，因此只有 inherit 的文档仍能加载。插件工具、Skill 和 MCP 工具只通过这一 opt-in 到达委托，不能写进可分配白名单。

没有 tools: inherit 时，委托可用的工具来自其定义，而不是其会话：它无法因为父级拥有某个工具而获得该工具，会话也不能把修改权限借给只读委托。委托调用由会话运行时构建并通过相同的 tools.execute 路径，因此路径规则（§4）、Bash 规则（§5）、权限模式（§6）、操作模式矩阵（§10）和审计（§9）保持不变，并针对拥有该调用的会话评估。

内置定义与用户定义还可以声明 permission: inherit | ask | accept-edits | auto（ADR 0089，默认 inherit）。使用默认的 inherit（包括所有内置定义）时， sidecar 不附加覆盖，委托使用会话的有效权限模式；因此父会话为 auto 时，明确的外部路径也不会再次弹出授权卡。项目定义随仓库一起到来，其 scope 会在解析时被丢弃并留下警告，克隆仓库永远不会获得权限升级。只有合格的内置或用户定义显式声明非 inherit scope 时，sidecar 才会附加它，并由 host-core 在该模式下裁决。scope 只是权限模式覆盖：契约模式的硬拒绝和外部路径门禁（§4.1）仍然生效；显式 accept-edits 仅自动允许工作区和 scratch 根内的 Write/Edit，外部路径及其他工具仍按其正常审批边界处理。

来自代表的权限请求带有提出请求的代表的姓名，因此卡可以说明哪位代表想要通话（请参阅 04-ux/03-permission-ux.md §6a)。会话范围的 allow-session 拨款仍按 toolName 和每个会话进行：一名代表对 Bash 的批准适用于整个会议，包括家长和其他代表。

11. 插件工具

插件可通过 agentTools 贡献工具。Agent 模式能看到每一个已注册的插件工具。Plan 和 Goal 只看到 planSafeActions 列表非空的工具（ADR 0211 / D384）：

舱单声明
用户授予 agent.tool.register 3.PluginManager将它们注册到ToolHost中 4.执行经过统一的permission/audit/timeout包装器

没有 planSafeActions 的插件工具在 Plan 和 Goal 中对模型隐藏。直接尝试返回 PLUGIN_DISABLED_IN_PLAN — _IN_PLAN 代码由两个合约共享模式而不是每种重复 - 并且作为合同模式政策进行审核否认。当列表存在时，host-core 放行该工具，plugin-runtime 拒绝列表外的任何 action，返回 PERMISSION_DENIED。对于 Agent，缺失或无效的插件风险默认为 medium，并且从不仅凭风险授予合同模式访问权限。

命名：

内部全名：plugin.<pluginId>.<toolName>
暴露给模型的名称：强制前缀 plugin_<pluginIdSafe>_<toolName> (D015) 以避免冲突

12. 未来的扩展

MCP 工具
工具组切换
命令允许列表/拒绝列表
空运行模式
预览后应用补丁

图片生成与编辑

GenerateImages 是仅供 Agent 使用的高风险能力，可信桌面执行请求前必须由 host-core 授权。即使处于 Auto，Plan/Goal 仍被拒绝。取消、限制和结果语义见图片生成规格。

03. 工具和权限 ​

0. 冻结政策总结 ​

1. Goal ​

2. MVP内置工具 ​

2. 1 延期辅助工具（D185、ADR 0048） ​

3. 常用工具约束 ​

4. 路径规则 ​

4a。显式外部路径权限 ​

4b.会话临时目录 (D114) ​

4c。消息拥有的审核快照和回滚 ​

4d。突变排序和编辑恢复 ​

5. Bash 规则 ​

6. 权限模型 ​

风险级别 ​

决策类型 ​

权限模式 (D115/D132) ​

7. 权限流程 ​

8. 工具结果对模型的可见性 ​

9. 审计 ​

10. 操作模式矩阵 ​

注释 ​

10. 1 Plan 和 Goal 控制工具 ​

10. 2 委派和子代理工具范围（D201、ADR 0062） ​

11. 插件工具 ​

12. 未来的扩展 ​

图片生成与编辑 ​