03. 权限用户体验

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

1. Goal

使高风险的本地行动可见、可中断且可预测。

2. 模式矩阵

模式	Read/Glob/Grep	BrowserPreview	Write/Edit	重击	插件
Agent	允许	允许	许可政策	许可政策	注册风险政策
Plan	允许	允许	否认	Read/Glob/Grep/BrowserPreview：确认； auto：允许	否认
Goal	允许	允许	否认	Read/Glob/Grep/BrowserPreview：确认； auto：允许	否认

Read/Glob/Grep allow 单元格应用于会话工作空间内的路径 并抓根。两个根之外的显式路径是一个例外： auto 允许这样做，而 ask 和 accept-edits 显示与以下相同的内联卡 其他权限控制工具。该卡的参数预览包括 请求的路径，并且外部结果在记录中保持绝对。

决策来源：D003/D189/D190/D195 (ADR 0057)。

Plan 和 Goal 使该权限模式控件保持可见。他们是契约者 意图，而不是严格的只读安全配置文件：Bash 命令可能会发生变化 当用户选择“自动”时，工作区或暂存状态。 Write/Edit/plugin 工具 在权限卡之前被主机拒绝，无论是授予还是自动。

3. 决策类型

• allow-once
• allow-session（范围按工具名称，D006）
• deny

MVP 中没有 allow-always。

4. 许可卡状态

pending → allowed_once
pending → allowed_session
pending → denied
pending → timeout_denied

• 请求由 sessionId 和 requestId 键入。
• 没有子代理的会话最多有一个待处理的请求，因为它的 代理循环已暂停。并行代表 (§6a) 可以放入多个代表 飞行；不同的会议仍在等待独立的批准。
• 替换或解决一个请求永远不会删除另一个会话的请求 或同一会话中的新请求。

5. 超时

• 默认超时：120 秒
• 超时：自动 deny
• UI 明确显示超时状态
• Agent 收到工具错误结果：用户拒绝/超时

6. 卡片内容要求

必须显示：

1.工具名称 2、风险等级 3.简短的理由 4.args预览（如果需要则进行编辑） 5. 工作空间环境 6. 操作：允许一次/允许会话/拒绝

该卡仅在其原始会话的记录中内联呈现。 后台请求保持挂起状态，无需打开覆盖层，更改 活动 page/project/session，或移动键盘焦点。打开该会话 亮出其卡牌，上面有原来的绝对倒计时期限。

解决请求永远不会启动导航。任何生成的工具工件都是 记录在同一会话保留的工作面板上下文中。如果该会话是 在完成之前背景化，工件不得打开或调整大小 可见面板；显式返回会话会恢复其保留的面板 打开状态、选项卡、活动选项卡和浏览器资源，无需临时面板 open/close 循环介入对话。

6a。来自并行委托的排队请求（D201、ADR 0062）

并行子代理可以同时停止在门控工具上，因此 会话保存一个待处理请求的队列，最早的在前，而不是单个槽。 另一种选择——一叠用户无法区分的通话卡片——不是 有责任的。

• 只有队列的头部被渲染并负责。剩下的等等 无形地；他们的代表仍然受阻，这是预期的背压。
• 答案按 requestId 匹配，而不是按位置匹配，因此迟到的答案可以 只能清除它所回答的请求，而永远无法解决后继者。
• 主机自行关闭的请求（过期、取消的工具调用）被删除 toolCallId 来自队列中的任何位置，因此一张从未显示过的卡片仍然存在 叶子。 120 秒的截止时间 (§5) 从每个请求到达时算起，无论是排队的还是 not — 因此，请求可能会在等待期间过期，并且主机自己会拒绝 是代表所看到的。
• 中止拒绝整个队列，而不仅仅是可见的卡：排队的委托 否则将在用户已经请求的停止之后保持其工具调用处于活动状态 为.
• 没有任何待处理的会话根本没有队列，因此“此会话是否需要 注意”仍然是存在检查，侧边栏指示器保持不变。

该卡在适用时在第 6 条之上添加了两条出处线：

• 谁提出了要求 — “由 <agent> 子代理提出要求” — 仅代表代表出席 请求，所以父母自己的请求看起来和今天一模一样；
• 有多少个等待 - “N 个请求正在等待” - 所以回答确实如此 看起来它还没有完成会议的问题。

会话授权未更改，并且仍按每个会话的 toolName：代表的 “允许会议”还涵盖家长和其他代表 （03-runtime/03-tools-and-permissions.md §10.2）。

7. 等待期间的 Composer 交互

• 用户可以继续编辑文本
• 发送另一个提示或更改活动会话 mode/provider/model/permission 当 pending Plan 或 Goal 批准存在时被阻止
• 特别是对于待决的 Plan 或 Goal 提案，现有草案将被保留并 提示符变为只读。输入框模式、思维、许可、模式、 发送控件被禁用；批准界面的批准和拒绝操作 保持启用状态。
• 当输入左侧的 Composer Agent/Plan/Goal 芯片和模型选择器重新启用时 主机因拒绝、过期或中断而关闭批准；终端 提案快照不是门
• Abort并发取消回合并显式拒绝匹配的主机 许可请求；后期清理无法清除更换请求
• 另一个会话保持独立 editable/runnable 和它自己的挂起 请求不受影响

8. 会话授予表面

活动会话授权（toolName、grantAt、clear action）仍由运行时拥有。 持久的赠款管理表面被推迟到主机支持的设置为止 模式存在；设置不得呈现无法持久或影响的控件 权限运行时。

9. Plan 和 Goal 合同审批卡

Plan 和 Goal 批准不是通用工具许可卡。它们被渲染 在 SubmitPlan(...) 或 SubmitGoal(...) 之后的原始会话中内联 导致 host-core 在新的不可变中保留确切的 Markdown 字节 .pi/plan/*.md 或 .pi/goal/*.md 工件。

该卡片仅显示结构化标题和确切工件的开场白 路径。它不会呈现提交的 question/description、状态或 批准 validity/deadline。它仅提供：

• 以明确的目标权限模式批准（Ask、Accept edits、 或 Auto；该设备会记住最后选择的模式，并且是 默认为下次审批）
• 拒绝，停止运行并使合约状态保持活动状态；稍后 轮流必须提交新的完整 snapshot/artifact

该卡有不同的 pending、resolving、approved、queued、running、 rejected、expired 和 interrupted 状态。批准仅适用于 匹配实时 proposal/session/turn/tool-call/version 请求和截止日期 距创建正好 30 分钟。 Renderer状态保留最新的 每个会话的 proposal/execution 快照仅适用于当前渲染器生命周期， 由现场主办方活动驱动；只有 pending 是可操作的或 Composer 门。 Renderer 重新加载可能会恢复仍待处理的行，而无需重置其截止日期 虽然同一主机仍然活着，但不重新水化被拒绝，过期， approved/completed，或中断的终端卡。这样的卡可能会保留 仅在重新加载之前可见且不可操作。启动中断标记待处理 和 queued/running 工作中断 在 RPC 服务之前，不提供过时的操作，并且从不重放它。过期使用 PLAN_APPROVAL_TIMEOUT。已批准的中断运行将保留会话 在 Agent 中； UI 不需要显示其中断的终端快照 完全重新启动 Host/app 后。

10. 验收

1. Plan 和 Goal 在每种权限模式下均拒绝 Write/Edit/plugins 2.“Ask”和“Accept”编辑下的 Plan 和 Goal Bash 提示，无需确认即可运行 在自动下，突变权衡可见 3、Agent模式使用普通高危权限策略
2. UI + 工具结果中的超时变为拒绝 5.allow-session 仅抑制相同 toolName 的重复提示 6.并发会话请求保持隔离，永远不会接管可见的 对话或其工作小组；批准后工件仍分配给 请求的发起会话
3. Plan/Goal 批准仅显示标题和工件开启器，记住 在此设备上选择下次批准的权限模式，并将其发送 仅批准模式；没有 question/description、validity/deadline、状态、 呈现内联 Markdown/hash/byte-size 或 revision/feedback 操作
4. 拒绝、过期、中止、崩溃、陈旧响应和持久性失败关闭 待处理的 Plan/Goal 在其合约状态下工作，没有执行能力；一个 稍后提示可能会修改并提交新的不可变工件
5. 主机重启中断pending/queued/running工作，无重放或陈旧 操作并在 Agent 中保留已批准的中断会话；没有终端 重启后需要卡恢复