From 3f6fdf22616e7f589d428e680c876420ce1aa703 Mon Sep 17 00:00:00 2001 From: DoodleBears Date: Sun, 15 Nov 2026 21:19:19 +0900 Subject: [PATCH 01/14] docs(approval): record confirmed Bot template policy Record the accepted design and existing-spec differences without runtime or storage changes. Issue: #4203 Agent-Task: codex/local/01a1df05-43d2-7380-84a0-99084cd0f49c --- GLOSSARY.md | 4 +- GLOSSARY.zh.md | 4 +- changes/4203-bot-approval-design.md | 11 ++ ...-reviewer-session-answer-tool-approvals.md | 2 + ...ps-deterministic-authorization-separate.md | 31 +++++ docs/architecture/bot-approval-policy.md | 109 +++++++++++++++++ docs/architecture/bot-approval-policy.zh.md | 111 ++++++++++++++++++ .../botharness-architecture.en.md | 8 ++ docs/architecture/botharness-architecture.md | 8 ++ 9 files changed, 284 insertions(+), 4 deletions(-) create mode 100644 changes/4203-bot-approval-design.md create mode 100644 docs/adr/0342-bot-approval-selects-one-template-and-keeps-deterministic-authorization-separate.md create mode 100644 docs/architecture/bot-approval-policy.md create mode 100644 docs/architecture/bot-approval-policy.zh.md diff --git a/GLOSSARY.md b/GLOSSARY.md index 89e70e7a78..c43ad807bb 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -226,11 +226,11 @@ A revocable instruction, explicitly saved by the Web Human or a currently author _Avoid_: Workspace Grant, provider Service Grant, sandbox preset, inferred command similarity **Approval Template**: -A Profile-wide, Human-written Markdown policy that says which tool approvals may be allowed, refused or sent to the Human. A PersonaBot selects one or none; selecting, clearing or editing a template in use needs a Human decision or an explicitly saved Tool Approval Rule in the dedicated management scope (ADR-0249). +A shared, Human-written natural-language policy containing Always ask guidance, Always allow guidance and free text for an Approval Reviewer. A PersonaBot uses at most one effective template, through global inheritance or a specific selection, or disables the Reviewer ([ADR-0342](docs/adr/0342-bot-approval-selects-one-template-and-keeps-deterministic-authorization-separate.md)). _Avoid_: approval mode, auto mode, Tool Approval Rule **Approval Reviewer**: -The model that applies a PersonaBot's Approval Template to one pending approval request inside an Approval Review Session, without tool results in its context, and answers allow, reject with a reason, or ask Human. Its failure always falls back to the Human card. +The model that applies a PersonaBot's effective Approval Template to one pending request inside an Approval Review Session, without tool results in its context, and either allows that request once or asks the Human. Its interpretation is fallible, and its failure falls back to the Human card. _Avoid_: classifier, guardian, auto-approver **Approval Review Session**: diff --git a/GLOSSARY.zh.md b/GLOSSARY.zh.md index 7b9e65a97c..5182c4aba8 100644 --- a/GLOSSARY.zh.md +++ b/GLOSSARY.zh.md @@ -225,11 +225,11 @@ Web Human 或当前获授权的外部审核人显式保存且可撤销的规则 _避免使用_:Workspace Grant、Provider Service Grant、sandbox preset、推断的命令相似性 **Approval Template**: -Profile 级、由 Human 用 Markdown 写成的审批规范,说明哪些工具审批可以允许、拒绝或交给 Human。每个 PersonaBot 选用一份或不选;选用、取消或修改正在使用的模板,需要 Human 决定,或在独立管理范围中显式保存的 Tool Approval Rule(ADR-0249)。 +由 Human 编写、供 Approval Reviewer 使用的共享自然语言审批策略,包含 Always ask、Always allow 与 free text。PersonaBot 通过继承全局或选择特定模板,至多使用一份有效模板,也可关闭 Reviewer([ADR-0342](docs/adr/0342-bot-approval-selects-one-template-and-keeps-deterministic-authorization-separate.md))。 _避免使用_:approval mode、auto mode、Tool Approval Rule **Approval Reviewer**: -在 Approval Review Session 里按 PersonaBot 的 Approval Template 判断一条待审批请求的模型;上下文不含工具结果;结论是允许、拒绝并附理由,或交给 Human。它出错时一律退回 Human 审批卡。 +在 Approval Review Session 中按 PersonaBot 的有效 Approval Template 判断一条待审批请求的模型,上下文不含工具结果,结果为仅放行本次或交给 Human。它的理解可能出错;发生故障时退回 Human 审批卡。 _避免使用_:classifier、guardian、auto-approver **Approval Review Session**: diff --git a/changes/4203-bot-approval-design.md b/changes/4203-bot-approval-design.md new file mode 100644 index 0000000000..24a1a6a362 --- /dev/null +++ b/changes/4203-bot-approval-design.md @@ -0,0 +1,11 @@ +--- +section: Documentation +--- + +## en + +- Documented the Human-confirmed Bot approval design: one effective shared template, explicit inheritance and deletion fallback, and a Reviewer that either approves once or asks the Human; runtime permissions and storage are unchanged ([#4203](https://github.com/BotHarness/DeepSeekBot/issues/4203), [#4211](https://github.com/BotHarness/DeepSeekBot/issues/4211)). + +## zh + +- 记录 Human 已确认的 Bot 审批设计:一份有效共享模板、显式继承与删除回退,以及仅批准本次或转交 Human 的 Reviewer;运行权限及存储均未改变([#4203](https://github.com/BotHarness/DeepSeekBot/issues/4203)、[#4211](https://github.com/BotHarness/DeepSeekBot/issues/4211))。 diff --git a/docs/adr/0207-an-approval-template-lets-a-reviewer-session-answer-tool-approvals.md b/docs/adr/0207-an-approval-template-lets-a-reviewer-session-answer-tool-approvals.md index 9d0e3e16e0..a752c27d1a 100644 --- a/docs/adr/0207-an-approval-template-lets-a-reviewer-session-answer-tool-approvals.md +++ b/docs/adr/0207-an-approval-template-lets-a-reviewer-session-answer-tool-approvals.md @@ -6,6 +6,8 @@ Issues: [#1821](https://github.com/BotHarness/DeepSeekBot/issues/1821), [#1823]( # An Approval Template lets a reviewer Session answer a Bot's tool approvals +> Design amendment (2026-11-15): [ADR-0342](0342-bot-approval-selects-one-template-and-keeps-deterministic-authorization-separate.md) changes template selection/composition and Reviewer outcomes as an accepted, unimplemented target. The historical decision below is not proof that the new target has shipped. [ADR-0249](0249-every-approval-card-can-save-explicit-tool-authorization.md) already amends the mandatory per-use management policy. + A PersonaBot that hits a Tool approval card stops until a Human answers it. Nobody answers when the Human is away or the work runs for hours, and the Bot stalls. The @-wake end-to-end runs saw this whenever a model called `todo_write` or `send_message` and nobody clicked: the run timed out with no fault in the wake path. Saved Tool Approval Rules help only for calls the Human has already seen, and full access removes every check at once. The owner asked for a middle ground in their own terms: a written rulebook per Bot that a separate, clean model Session applies on the Human's behalf. Claude Code's auto mode and OpenAI Codex's auto-review are the same shape: a second model answers the approval, and the human keeps the final word through rules and fallbacks. ## Decision diff --git a/docs/adr/0342-bot-approval-selects-one-template-and-keeps-deterministic-authorization-separate.md b/docs/adr/0342-bot-approval-selects-one-template-and-keeps-deterministic-authorization-separate.md new file mode 100644 index 0000000000..af51461ffa --- /dev/null +++ b/docs/adr/0342-bot-approval-selects-one-template-and-keeps-deterministic-authorization-separate.md @@ -0,0 +1,31 @@ +--- +Status: Accepted +Date: 2026-11-15 +Issues: [#4203](https://github.com/BotHarness/DeepSeekBot/issues/4203), [#4211](https://github.com/BotHarness/DeepSeekBot/issues/4211) +--- + +# ADR-0342: Bot approval selects one template and keeps deterministic authorization separate + +Accepted by the Human after a design interview and explicit confirmation on 2026-11-15. This is a target design, not an implementation or permission change. The full contract and specification differences are in [Bot approval policy](https://github.com/BotHarness/BotHarness/blob/main/docs/architecture/bot-approval-policy.md) ([中文](https://github.com/BotHarness/BotHarness/blob/main/docs/architecture/bot-approval-policy.zh.md)). Storage and SQLite migration remain separate work. + +## Context and decision + +ADR-0207 introduced a Human-written Markdown template selected by each Bot and a model Reviewer with allow, reject and ask-Human outcomes. Issue #4203 and E3 #4211 propose natural-language Always ask, Always allow and free text, but combine a shared template with Bot-local extra rows. That layered policy makes it harder to know which policy is effective and what a shared edit changes. + +A Bot instead has one of three choices: dynamically inherit the optional global selection, select a specific shared template, or disable the Reviewer. A specific selection replaces the global template completely. New Bots inherit; existing Bots retain their specific selection or disabled state. Shared templates remain reusable; creation explicitly chooses a blank template or a copy, and saving explicitly distinguishes saving alone from saving and applying to the current Bot. + +The three template sections are natural-language Reviewer instructions. Always ask takes precedence over Always allow; free text supplements them without cancelling their requirements. The Reviewer returns only allow for the current request or ask-human. Conflicts, insufficient coverage, uncertainty and failures go to the Human. It neither rejects autonomously nor creates reusable Tool Approval Rules. This trades autonomous rejection for Human control over requests the model will not approve; rejection-based Reviewer circuit breaking no longer applies. + +Deterministic authorization is resolved before calling the model. Human-saved card rules stay Bot-scoped, show their source and scope, remain revocable, and are neither template rows interpreted by the model nor copied with templates. Full Access is not blanket exemption from the irreversible external-effect approval proposed by E2 #4210. Actual tool-effect admission belongs to that work; this decision does not implement it. Natural-language instructions are fallible and are not deterministic security boundaries. + +Each Review uses the template version captured at its start. Edits and selection changes affect later Reviews, accepting that an already-started Review can finish with the previous policy. Approval records retain the template identity and version used. This does not waive current ownership, Grant, scope or authorization-revocation checks. + +Deleting a referenced template requires one explicit second confirmation listing affected Bots and their resulting choices. Specific references fall back to inherit-global. If the template is also the global default, deletion clears that default; affected inherited Bots consequently have no Reviewer. This deliberate, disclosed change differs from a missing/corrupt template or Reviewer failure, which goes to the Human without silently rewriting choices. Users need not remove references one by one. + +## Authority and alternatives + +The existing application-defined approval owner remains responsible for decisions. Bot-level selection and policy are application concepts, not DSH-native modes. Effective policy management cannot be authorized by the model Reviewer or Full Access; a Human decision or an explicitly saved rule covering that management operation is required, preserving ADR-0249's separate management scope and current execution fences. + +This amends ADR-0207's template selection, Markdown-only policy shape, three Reviewer outcomes and rejection circuit breaker as target design, not retroactive runtime fact. ADR-0249 continues to govern explicit management authorization. The existing issue bodies are not rewritten by this record. + +Rejected alternatives were global-plus-Bot layering (ambiguous effective policy), applying new defaults to old disabled Bots (implicit opt-in), autonomous model rejection (removes the Human's decision on unapproved requests), hidden copies/application (unclear scope), and refusing deletion until every reference is removed (unnecessary repeated work). The selected design makes defaults dynamic and deletion easier, at the cost of a carefully disclosed bulk change and immutable policy snapshots for already-started Reviews. diff --git a/docs/architecture/bot-approval-policy.md b/docs/architecture/bot-approval-policy.md new file mode 100644 index 0000000000..9a063a4cd9 --- /dev/null +++ b/docs/architecture/bot-approval-policy.md @@ -0,0 +1,109 @@ +# Bot approval policy + +Status: Human-confirmed target design, 2026-11-15. Runtime behavior is unchanged by this documentation. [中文](bot-approval-policy.zh.md). + +[ADR-0342](../adr/0342-bot-approval-selects-one-template-and-keeps-deterministic-authorization-separate.md) owns the durable choices and trade-offs. This document owns the integrated target behavior. GitHub issues own delivery status. Neither this interview nor these documents authorize implementation, live permission changes or a SQLite migration. + +## One effective template + +The Profile has an optional global default selected from its shared Approval Template library. Each Bot chooses exactly one mode: + +| Choice | Effective Reviewer policy | +| ----------------- | ----------------------------------------------------------------- | +| Inherit global | The currently selected global template; no copy or extra Bot rows | +| Specific template | That shared template, replacing the global template completely | +| Off | No template Reviewer | + +Several Bots can select the same template. A global selection change reaches inheriting Bots; editing a shared template reaches every Bot whose effective selection uses it. Neither change modifies a Bot using another specific template or Off. A global default of none disables the Reviewer only for inheriting Bots. + +Disabling the Reviewer does not revoke deterministic rules or change Full Access. + +New Bots default to inheritance. Existing Bots retain their previous specific template or Off; an absent legacy field must not silently become opt-in. This fixes compatibility semantics, not a persistence format or migration plan. + +## Natural-language policy and Reviewer outcomes + +Every template contains individual natural-language Always ask rows, individual natural-language Always allow rows, and free text. These describe behavior for the Reviewer, rather than command regexes or deterministic predicates. + +The Reviewer is instructed to give Always ask precedence over Always allow. Free text supplements the policy without cancelling requirements from those sections. An unclear overlap, uncovered behavior or uncertainty produces ask-human. Interpretation can be wrong; the section names provide no hard guarantee that every matching real-world action will be recognized. + +There are only two model outcomes: + +- allow: approve this request once, without creating a standing rule; +- ask-human: present the Human approval card, where the Human can approve or reject. + +The target removes autonomous model reject. Consequently, the current model-rejection counters and rejection-triggered pause/resume mechanism do not apply. Existing historical decisions are implementation evidence, not proof that this target has shipped. + +## Deterministic authorization and effect admission + +The target first uses deterministic code to determine whether the action needs approval and resolve valid deterministic authorization. A covered request does not incur a model call. An uncovered request uses the effective Reviewer policy or goes to the Human when the Reviewer is disabled. + +Full Access does not by itself waive the external-effect approval proposed in [E2 #4210](https://github.com/BotHarness/DeepSeekBot/issues/4210). The concrete effect declarations and admission mechanism remain in [E1 #4205](https://github.com/BotHarness/DeepSeekBot/issues/4205), E2 and [E4 #4212](https://github.com/BotHarness/DeepSeekBot/issues/4212). No claim is made that arbitrary behavior can be inferred reliably from a command string. + +Card-created Tool Approval Rules remain deterministic, Bot-scoped authorizations with their existing role, authority scope and execution checks. They appear in the Always allow table with a source such as “From approval card”, their scope and a revoke action. Their display alongside natural-language rows does not change how either kind executes. They are not written into the shared template, granted to other Bots using it, or included in template copies. A natural-language row cannot override an already matched deterministic rule; the Human must revoke that rule to return those requests to review. + +Current ownership, Workspace Grant, device-target and rule-revocation checks remain independent of model permission. Effective policy management skips the model Reviewer and Full Access, but may use an explicitly saved authorization covering that management operation under ADR-0249. Existing ordinary rules do not gain management authority. Management approval identifies affected Bots. + +## Creation, editing and deletion + +Creation explicitly offers starting blank or creating from an explicitly selected existing template. A copy is independent, without a continuing link to its source. Saving explicitly offers “Save only” and “Save and use for this Bot”; creation alone does not change a Bot's selection. Editing the shared original and creating a new template must be explicit choices; no implicit copy or shared edit is inferred from the current Bot page. + +Deleting a referenced template uses a second confirmation listing affected Bots and the resulting effective selection. The user does not need to detach each Bot: + +| Reference | Confirmed deletion result | +| --------------------------------------------- | ------------------------------------------------------------------------ | +| Bot specifically selects the deleted template | Change that Bot to inherit global | +| Global selects the deleted template | Clear the global selection | +| Bot inherits global | Keep inheritance; if the global default was deleted, no Reviewer remains | +| Bot selects another template or Off | Keep its choice | + +If the global default is another template, Bots falling back to inheritance use that template. Confirmation must disclose that result, not merely say the deleted template will be removed. Deterministic rules and Full Access are not revoked or changed by this operation. + +## Review snapshots and failures + +Each Review captures its template identity, version and content when it begins. Edits and selection changes affect later Reviews; already-started Reviews may finish using their captured version. Review records retain that identity/version. This is policy-version consistency, not an exception to current authorization and execution fences. + +Missing or unreadable selected templates, unavailable models, timeouts and malformed Reviewer replies all route the current request to the Human with the reason. They do not select another template, allow silently, or rewrite Bot/global choices. A deliberately empty global selection is not a load failure. A confirmed deletion's fallback is an explicit management action, not an error-recovery fallback. + +## Existing specifications and implementation + +The source baseline inspected was fc29d448467392b1e9ed2f3d048d3d1df0b14381. These are static observations, not a live-Host verification: + +| Aspect | Existing fact or specification | Confirmed target | +| ------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | +| Selection | Single optional Bot field; no global default in plugin.ts:2491 | Global inheritance, specific selection or Off | +| Policy shape | ADR-0207 specifies whole Markdown; #4203 and E3 specify three parts plus Bot extra rows | Three parts in one selected template; no extra Bot layer | +| Reviewer output | approval-reviewer.ts:189 has allow/reject/ask-human | allow/ask-human only | +| Rule precedence | tool-approval.ts:306–349 resolves Full Access and saved rules before Reviewer | Keep deterministic authorization first; retain E2's changed effect admission target | +| Card rules | #4203 and E3 AC-3 retain deterministic execution and source labels | Preserve that requirement and Bot ownership | +| Referenced deletion | Previously unresolved in this interview | Confirm once, disclose effects and fall back to inheritance | + +Source files: [Bot record](../../packages/core/src/bots/persona-bot.ts), [template lookup](../../packages/core/src/plugin.ts), [Reviewer](../../packages/core/src/workspaces/approval-reviewer.ts), [approval owner](../../packages/core/src/workspaces/tool-approval.ts), [rules](../../packages/core/src/workspaces/tool-approval-rules.ts). ADR-0205/0207/0239/0249 explain the historical evolution; ADR-0207 alone is not the current complete pipeline. + +On 2026-11-15, [#4203](https://github.com/BotHarness/DeepSeekBot/issues/4203), E1, E2, [E3 #4211](https://github.com/BotHarness/DeepSeekBot/issues/4211) and E4 were open, unassigned, with zero comments. No claim or new-scope implementation PR was found in the checked evidence; this does not prove no implementation exists. The local gh CLI lacked authentication, so timeline completeness was not established. Existing template/Reviewer and card-rule capabilities have merged predecessors, including PRs #1835 and #2739. No issue or comment was created or edited during the interview. + +This target modifies #4203/E3's selection composition and the existing Reviewer outcome contract, preserves the three-part editor and deterministic source-labelled card rules, and retains the E2 direction. Reconciliation belongs in those existing issues; no duplicate issue is needed. SQLite migration #4227 is outside this design. Performance PR #4228 is unrelated and was not modified or monitored. + +## Research boundary + +The inspected project .claude/settings.json contains only allow entries for Bash(pnpm evidence:publish:_) and Bash(pnpm evidence:check:_); it contains no ask, deny, hooks or defaultMode. This is project-file evidence, not an audit of the effective user/managed/runtime settings. No secrets were printed. + +The official Claude Code [permissions documentation](https://code.claude.com/docs/en/permissions.md#manage-permissions), read on 2026-11-15, distinguishes enforced permission configuration from natural-language guidance, evaluates deny before ask before allow, and describes Bash wildcard patterns rather than regexes. [Memory guidance](https://code.claude.com/docs/en/memory.md#claude-md-vs-auto-memory) describes CLAUDE.md as context. [Auto-mode configuration](https://code.claude.com/docs/en/auto-mode-config.md) documents natural-language hard_deny, soft_deny and allow, separately from deterministic permissions and shell-allow handling. Those field names and Claude-specific precedence are research evidence, not BotHarness APIs or guarantees. Engine source and effective runtime settings were not audited. + +## Interview decision trace + +- Q1–Q3: replacement rather than layering; three Bot choices; natural-language Reviewer guidance. +- Q4–Q7: reusable shared templates; two model outcomes; deterministic rules first; empty global selection disables inherited review. +- Q8–Q10: natural-language precedence; E2 effect admission despite Full Access; fixed template versions per Review. +- Q11–Q13: failure routes to Human; Bot-owned card rules; existing management-authority boundary. +- Q14 and its follow-up: the Human replaced implicit copy/customization with explicit blank-or-copy creation and explicit save-only versus save-and-apply. +- Q15: the Human replaced deletion refusal with one second confirmation and disclosed bulk fallback to inheritance. +- Q16–Q18: preserve existing Bot choices; no standing rules from model allow; clear the global selection when its default is deleted. +- Final confirmation: the Human accepted the complete summary before any design documentation was written. + +## Delivery and verification boundary + +The User confirmed the design after questions Q1–Q18 and a complete summary. There are no outstanding product decisions in that interview tree. Implementation mechanics, CLI contracts, storage/version representation and migration are future work, not silently selected here. The existing application-defined approval owner remains the owner; DSH-native approval/request, Session and API Gateway seams are not replaced by a second authority. + +Future delivery must demonstrate inherited versus specific/Off behavior, Reviewer conflict/uncertainty routing, deterministic bypass without an LLM call, Bot-only card-rule scope, disclosed deletion fallback, captured policy versions, failure routing and management refusal without valid authority. These are acceptance requirements, not claims that tests or the runtime already implement them. + +Performance assessment: this change edits documentation only, introduces no dependency and changes no runtime hot path, so no runtime benchmark is warranted. Future E2/E3 work must separately budget added admission work and model calls, prove deterministic hits make no Reviewer call, and verify the affected real journey under the repository's performance policy. diff --git a/docs/architecture/bot-approval-policy.zh.md b/docs/architecture/bot-approval-policy.zh.md new file mode 100644 index 0000000000..8181a7615e --- /dev/null +++ b/docs/architecture/bot-approval-policy.zh.md @@ -0,0 +1,111 @@ +# Bot 级自动审批策略 + +状态:Human 于 2026-11-15 确认的目标设计,尚未实施。本文档不改变运行行为。[English](bot-approval-policy.md)。 + +[ADR-0342](../adr/0342-bot-approval-selects-one-template-and-keeps-deterministic-authorization-separate.md) 记录长期决策与权衡,本文整合目标行为;GitHub issue 记录交付状态。设计确认不授权实施功能、更改运行权限或推进 SQLite 迁移。 + +## 一份有效模板 + +Profile 有一个可选的全局默认模板,来源是共享 Approval Template 库。每个 Bot 明确选择一种状态: + +| Bot 选择 | 有效 Reviewer 策略 | +| ------------ | ----------------------------------------------- | +| 继承全局 | 动态使用全局当前选择;不复制、不叠加 Bot 额外行 | +| 特定模板 | 使用该共享模板,完整替换全局模板 | +| 关闭自动审批 | 不使用模板 Reviewer | + +多个 Bot 可以选同一份模板。切换全局选择影响继承它的 Bot;编辑共享模板影响所有实际使用它的 Bot。使用另一份特定模板或关闭的 Bot 不受影响。全局未选模板时,继承它的 Bot 停用 Reviewer。 + +关闭 Reviewer 不撤销确定性授权,也不改变 Full Access。 + +新 Bot 默认继承;既有 Bot 保持原有特定模板或关闭状态,不能把旧数据的缺省字段自动解释为启用继承。本次只确认兼容语义,不选择存储格式或迁移方案。 + +## 三部分自然语言与 Reviewer 结果 + +每份模板包含逐条自然语言 Always ask、逐条自然语言 Always allow、free text。它们帮助 Reviewer 理解行为,不是 Bash 正则、通配表达式或确定性谓词。 + +给 Reviewer 的指导是:Always ask 优先于 Always allow;free text 补充判断,不取消前两部分的要求。覆盖不清、未覆盖或无法确定时交给 Human。模型可能理解错误,因此这些名称不构成“现实中符合描述的行为必定被识别”的硬保证。 + +模型只有两个结果: + +- allow:仅批准当前请求,不生成可复用授权。 +- ask-human:展示 Human 审批卡,由 Human 批准或拒绝。 + +目标取消模型自主 reject,原先由模型拒绝次数触发的熔断及恢复逻辑不再适用。既有拒绝历史是实现证据,不代表本目标已经交付。 + +## 确定性授权与效果准入 + +先由代码判断行为是否需要审批,再处理有效的确定性授权;已覆盖的请求不调用 LLM。未覆盖时使用有效模板 Reviewer;未启用 Reviewer 则交给 Human。 + +Full Access 本身不豁免 [E2 #4210](https://github.com/BotHarness/DeepSeekBot/issues/4210) 所指的不可撤销外部调用审批。具体效果声明与准入机制仍属于 [E1 #4205](https://github.com/BotHarness/DeepSeekBot/issues/4205)、E2 与 [E4 #4212](https://github.com/BotHarness/DeepSeekBot/issues/4212),本次不实施,也不声称能从任意命令文本可靠推断其全部行为。 + +卡片 Always allow 保存的 Tool Approval Rule 是确定性授权,继续绑定具体 Bot、角色、授权范围及执行检查。在 Always allow 表格共同展示时,必须标注“来自卡片”、作用范围及撤销入口;共同展示不改变两类条目的执行方式。它不写入共享模板,不授权使用同模板的其他 Bot,也不随模板复制。已经命中确定性规则时,模板中的自然语言不会覆盖它;需要重新审核时,由 Human 撤销该规则。 + +当前所有权、Workspace Grant、设备目标及授权撤销检查独立于模型判断。生效中的策略管理跳过 Reviewer 与 Full Access,须由 Human 决定,或使用 ADR-0249 独立管理范围中确实覆盖该操作的显式已保存授权。旧普通规则不因此获得管理权限。管理审批展示受影响的 Bot。 + +## 显式创建、编辑和删除 + +创建时,用户显式选择“从零创建”或“基于已有模板创建”,后者明确选择来源,得到独立副本,不保留持续继承关系。保存时明确区分“仅保存”和“保存并用于当前 Bot”;创建本身不切换 Bot 选择。 + +编辑共享原件与创建新模板必须显式区分;不能根据当前 Bot 页面隐式复制,也不能把局部编辑悄悄传播给其他 Bot。 + +删除使用二次确认,列出受影响 Bot 及删除后的有效选择,不要求用户逐个解除引用: + +| 引用关系 | 确认删除后的结果 | +| ---------------------- | ------------------------------------------- | +| Bot 明确选择被删模板 | 将该 Bot 改为继承全局 | +| 全局选择被删模板 | 清空全局默认选择 | +| Bot 继承全局 | 保持继承;若删的是全局默认,则停用 Reviewer | +| Bot 使用其他模板或关闭 | 保持原选择 | + +如果全局仍选另一份模板,回退继承的 Bot 随即使用它,确认信息必须说明这一结果,而不只是说“删除模板”。删除不撤销确定性授权,不改变 Full Access。 + +## Review 快照与失败 + +每次 Review 开始时固定所用模板身份、版本和内容。编辑及选择切换影响之后开始的 Review;已开始的 Review 可以按旧版本完成,记录保留当次身份与版本。该快照不豁免实时所有权、范围、Grant 和已撤销授权的执行检查。 + +所选模板缺失或无法读取、模型不可用、超时、返回格式错误,均将当前请求交给 Human 并显示原因;不自动允许、不换另一模板、不改写 Bot 或全局选择。主动未选全局模板不是加载失败。确认删除后的回退是显式管理操作,不是故障恢复。 + +## 与现有规格及代码的差异 + +静态核查基线为 fc29d448467392b1e9ed2f3d048d3d1df0b14381,不是 live Host 验证: + +| 事项 | 原有事实或规格 | 本次确认目标 | +| ---------- | -------------------------------------------------------------- | -------------------------------------------------- | +| 模板选择 | Bot 单个可选字段,plugin.ts:2491 无全局默认层 | 继承全局/特定模板/关闭 | +| 模板结构 | ADR-0207 为整段 Markdown;#4203、E3 为三部分加 Bot 额外行 | 一份选定模板的三部分,不叠加 Bot 层 | +| 模型输出 | approval-reviewer.ts:189 为 allow/reject/ask-human | 仅 allow/ask-human | +| 确定性顺序 | tool-approval.ts:306–349 先 Full Access、保存规则,再 Reviewer | 保留确定性授权优先,同时保留 E2 改变效果准入的方向 | +| 卡片规则 | #4203、E3 AC-3 要求保留确定性执行及来源标签 | 延续,并保持 Bot 归属 | +| 引用中删除 | 本次访谈前尚未确定 | 二次确认后统一回退继承,删除默认时清空全局 | + +代码来源:[Bot 记录](../../packages/core/src/bots/persona-bot.ts)、[模板查找](../../packages/core/src/plugin.ts)、[Reviewer](../../packages/core/src/workspaces/approval-reviewer.ts)、[审批 owner](../../packages/core/src/workspaces/tool-approval.ts)、[规则](../../packages/core/src/workspaces/tool-approval-rules.ts)。ADR-0205/0207/0239/0249 记录演进,不能单独把 ADR-0207 当作当前完整管线。 + +2026-11-15 核查时,[#4203](https://github.com/BotHarness/DeepSeekBot/issues/4203)、E1、E2、[E3 #4211](https://github.com/BotHarness/DeepSeekBot/issues/4211)、E4 均 open、无 assignee、全部评论为 0。所查证据未发现认领记录或新范围的可核实实施 PR,但不能据此断言绝无实施。本机 gh 未认证,未确认 timeline 事件的完整性。旧模板 Reviewer 与卡片规则已有合并前身,例如 PR #1835、#2739。访谈未创建、认领或编辑任何 issue/评论。 + +本次修改 #4203/E3 的模板组合关系及既有 Reviewer 结果集合;延续三部分编辑方式、卡片规则来源展示和 E2 方向。后续应在现有规格协调差异,不创建重复 issue。本设计不推进 SQLite 迁移 #4227;性能 PR #4228 独立,未修改或监控。 + +## Claude Code 研究边界 + +本 worktree 的 .claude/settings.json 只有 Bash(pnpm evidence:publish:_) 与 Bash(pnpm evidence:check:_) 两项 allow,无项目级 ask、deny、hooks、defaultMode。这仅是项目文件事实,不代表用户、managed 或运行时有效配置;未输出秘密。 + +2026-11-15 查阅的官方 [permissions 文档](https://code.claude.com/docs/en/permissions.md#manage-permissions) 区分执行配置与自然语言指导,按 deny、ask、allow 顺序判断,并将 Bash 模式描述为通配语法,而非正则。[Memory 文档](https://code.claude.com/docs/en/memory.md#claude-md-vs-auto-memory) 将 CLAUDE.md 定义为上下文。[Auto mode 配置](https://code.claude.com/docs/en/auto-mode-config.md) 另有自然语言 hard_deny、soft_deny、allow,与确定性权限及 Shell allow 的处理分开。这些字段及 Claude 专属优先级只是研究来源,不是 BotHarness API,也不提供模型判断的硬保证。未复核 Claude Code 引擎源码或有效运行配置。 + +## 访谈决策溯源 + +- Q1–Q3:替换而非叠加;Bot 三态;模板为自然语言指导。 +- Q4–Q7:共享库复用;模型仅两个结果;确定性规则优先;全局未选时停用继承的 Reviewer。 +- Q8–Q10:自然语言优先级;保留 E2 对 Full Access 的效果准入;每次 Review 固定版本。 +- Q11–Q13:失败转 Human;卡片规则归 Bot;保持管理授权边界。 +- Q14 及补充:Human 将隐式复制定制改为显式选择从零或基于模板创建,并确认仅保存/保存并应用。 +- Q15:Human 将禁止引用中删除改为二次确认,告知影响后统一回退继承,避免逐个解除引用。 +- Q16–Q18:保持既有 Bot 选择;模型放行不存规则;删除全局默认时清空全局。 +- 最终确认:Human 确认完整汇总后,才开始写入设计文档。 + +## 确认与交付边界 + +Human 在 Q1–Q18 分轮访谈后确认了完整汇总;原设计树无未决产品分支。实现机制、CLI 契约、版本表示、持久化格式与迁移留待实施任务,不在本文偷偷作决定。既有应用定义的审批 owner 仍持有决定权;不新设另一套权威,不替换 DSH-native approval/request、Session 或 API Gateway seam。 + +后续交付须验证:继承/特定/关闭的有效选择;冲突及不确定转 Human;确定性命中时没有 LLM 调用;卡片规则只授权所属 Bot;删除结果披露及回退;Review 固定版本;故障转 Human;无有效管理授权时拒绝策略变更。这是未来验收要求,不是已实现或已通过测试的声明。 + +性能评估:本次只有文档变更,无新依赖、无运行热路径变化,因此免运行性能基准。未来 E2/E3 须分别预算新增准入工作及模型调用,证明确定性命中不调用 Reviewer,并依仓库性能规则验证实际旅程。 diff --git a/docs/architecture/botharness-architecture.en.md b/docs/architecture/botharness-architecture.en.md index d4a6531753..386f197816 100644 --- a/docs/architecture/botharness-architecture.en.md +++ b/docs/architecture/botharness-architecture.en.md @@ -388,6 +388,14 @@ Native Session authorization remains Web-only; Workspace/Service authority is no [ADR-0175](../adr/0175-external-tool-rules-retain-current-creator-authority.md); real-platform feedback and the broader all-opaque IM confirmation remain separate gates. +## Accepted target: Bot approval policy (not implemented) + +The Human-confirmed design of 2026-11-15 gives each Bot one choice: dynamically inherit the optional global template, select a specific shared template that replaces the global policy, or disable the Reviewer. It does not combine a shared template with Bot-local extra rows. Always ask, Always allow and free text are natural-language guidance, not deterministic permission guarantees. Deterministic authorization is resolved first; the Reviewer only allows this request once or asks the Human, without autonomous rejection or saved-rule creation. Full Access does not blanket-exempt the external-effect admission target in E2. + +Template creation sources and application are explicit. Deletion requires a second confirmation naming affected Bots and their resulting choices; specific references fall back to inheritance, and deleting the global default clears that selection. Each Review captures its template version at start, while later edits affect new Reviews. Missing policy or Reviewer failures go to the Human without silently changing selections. New Bots inherit; existing Bots retain their choices. Effective policy management preserves ADR-0249's separate management authorization and execution checks. + +The full target, implementation observations and #4203/E3 specification differences are in [Bot approval policy](https://github.com/BotHarness/BotHarness/blob/main/docs/architecture/bot-approval-policy.md) ([中文](https://github.com/BotHarness/BotHarness/blob/main/docs/architecture/bot-approval-policy.zh.md)) and [ADR-0342](../adr/0342-bot-approval-selects-one-template-and-keeps-deterministic-authorization-separate.md). This accepted design does not change runtime behavior, authorize feature implementation or a SQLite migration, or rewrite the GitHub specifications. Historical implementation records below are separate from this target. + ## 5 · Orchestrator and Assignment control plane M6 adds application-owned account/shared roots, separate grantable `files/` and protected Bot Memory, current audience checks (including for the Owner's own Bots), and the bound `core.currentRoots(session, kind)` seam for M12. The persistence, migration, M9 lifecycle and wire contracts are in [M6 runtime boundaries](team-mode-m6-runtime.md). diff --git a/docs/architecture/botharness-architecture.md b/docs/architecture/botharness-architecture.md index 887f2b1254..4bde3662df 100644 --- a/docs/architecture/botharness-architecture.md +++ b/docs/architecture/botharness-architecture.md @@ -646,6 +646,14 @@ The application-defined `ConnectionsDialog` presents pairing and device manageme [ADR-0202](../adr/0202-phone-push-is-a-content-free-projection-of-the-activity-list.md)([#1655](https://github.com/BotHarness/DeepSeekBot/issues/1655)):应用定义的 Push delivery 模块(`packages/core/src/push/`)是 Activity 的投影,不另设通知权威。Activity 表或 PersonaBot 的审批、提问、私密输入计数变化时(以及每分钟一次的兜底扫描),模块读取 `action` 项与未读的 `replies` 项,对每台已登记的配对设备只发送一次新项,并经 Expo Push Service 投递;推送标题为频道名(`#名称`,私信为 PersonaBot 名称),正文为所需操作加上工具与主要参数、问题或消息的简短预览(折叠空白,最多 140 字符);私密输入请求不含内容([ADR-0213](../adr/0213-phone-push-shows-the-channel-and-a-short-preview.md))。数据字段只含 Host 标识、Activity 项标识、PersonaBot 标识与读取请求所需的 Channel/消息标识,并携带未处理 Human 操作数作为角标。设备经设备网关的 `/botharness-device/push` 登记 Expo push token、切换各类通知、发送测试通知;撤销设备或 Expo 回报 `DeviceNotRegistered` 时删除 token。发送失败有界重试,结果写入不含内容的 `push` 开发者日志。App 保存每台配对的 Host,点按通知先切换到对应 Host,再打开该审批、提问或私信。 +## 已确认目标:Bot 级自动审批策略(尚未实施) + +2026-11-15 的设计访谈确认:Bot 在动态继承全局、选择特定模板、关闭 Reviewer 三态中选一,特定模板完整替换全局,不再叠加 Bot 额外行。模板包含自然语言 Always ask、Always allow 与 free text;确定性授权先处理,Reviewer 只批准当前调用或转 Human,不自主拒绝、不创建规则。Full Access 不一概豁免 E2 的外部效果审批目标。自然语言理解不是硬权限边界,卡片保存的规则仍归具体 Bot 并标注来源。 + +共享模板的创建来源与应用动作均由用户显式选择;删除时二次确认并列出受影响 Bot,特定引用统一回退继承,删除全局默认时同时清空全局。Review 固定开始时的模板版本,后续编辑影响新 Review;模板缺失或 Reviewer 故障转 Human,不静默修改选择。新 Bot 默认继承,旧 Bot 保持原选择;生效中的策略管理仍受 ADR-0249 的独立管理授权及执行检查约束。 + +完整确认内容、实现事实及与 #4203/E3 的差异见 [Bot 审批策略](https://github.com/BotHarness/BotHarness/blob/main/docs/architecture/bot-approval-policy.md)([中文](https://github.com/BotHarness/BotHarness/blob/main/docs/architecture/bot-approval-policy.zh.md))与 [ADR-0342](../adr/0342-bot-approval-selects-one-template-and-keeps-deterministic-authorization-separate.md)。此处是目标设计,不代表下文历史实现记录已经改变;不授权功能实施或 SQLite 迁移,也未改写现有 GitHub 规格。 + ## 5 · Orchestrator 与 Assignment control plane M6 adds application-owned account/shared roots, separate grantable `files/` and protected Bot Memory, current audience checks (including for the Owner's own Bots), and the bound `core.currentRoots(session, kind)` seam for M12. The persistence, migration, M9 lifecycle and wire contracts are in [M6 runtime boundaries](team-mode-m6-runtime.md). From c78ea5cea853868914f5560eb83cc8b36decdc5f Mon Sep 17 00:00:00 2001 From: DoodleBears Date: Sun, 15 Nov 2026 22:42:58 +0900 Subject: [PATCH 02/14] Add effective approval-template selection and versioned Human fallback Issue: #4211 Agent-Task: codex/local/01a1df40-f8b0-76b1-86c4-e91fed15087b --- .../features/approval-templates.md | 31 +-- changes/4211-effective-approval-template.md | 11 + docs/architecture/bot-approval-policy.md | 2 + docs/architecture/bot-approval-policy.zh.md | 4 +- docs/architecture/botharness-architecture.md | 6 +- docs/bot-cli.md | 27 +-- docs/bot-cli.zh.md | 27 +-- packages/client/src/client/actions.ts | 8 +- .../src/client/approval-template-entry.tsx | 131 ++++------- .../src/client/approval-template-library.tsx | 29 ++- packages/client/src/client/bridge.ts | 39 +++- packages/client/src/client/locale.ts | 8 + packages/client/src/client/store.ts | 1 + .../client/src/client/tool-approval-card.tsx | 3 + .../core/src/bots/cli-approval-templates.ts | 26 ++- packages/core/src/bots/registry.ts | 1 + packages/core/src/bridge/methods.ts | 65 +++++- packages/core/src/bridge/rpc.ts | 8 + packages/core/src/channels/channel.ts | 1 + packages/core/src/plugin.ts | 24 +- .../core/src/workspaces/approval-reviewer.ts | 15 +- .../core/src/workspaces/approval-templates.ts | 35 ++- .../core/src/workspaces/grant-execution.ts | 19 +- packages/core/src/workspaces/tool-approval.ts | 211 +++++++----------- .../core/test/approval-reviewer-model.test.ts | 7 +- packages/core/test/approval-reviewer.test.ts | 145 +++++++++--- .../test/approval-template-library.test.ts | 52 ++++- .../core/test/auto-approval-breaker.test.ts | 161 ++++--------- packages/core/test/bridge-methods.test.ts | 4 + packages/core/test/bridge-rpc.test.ts | 1 + packages/core/test/plugin.test.ts | 1 + scripts/cli-ui-inventory.json | 4 +- tsdown.config.ts | 2 + 33 files changed, 665 insertions(+), 444 deletions(-) create mode 100644 changes/4211-effective-approval-template.md diff --git a/.agents/skills/verify-deepseekbot/features/approval-templates.md b/.agents/skills/verify-deepseekbot/features/approval-templates.md index c412596a34..8950d837c1 100644 --- a/.agents/skills/verify-deepseekbot/features/approval-templates.md +++ b/.agents/skills/verify-deepseekbot/features/approval-templates.md @@ -1,29 +1,32 @@ # Approval Templates and auto approval -A Human writes Approval Templates, a PersonaBot selects one, and the Approval Reviewer answers that Bot's operation approvals by the template's text before any card is posted (ADR-0207). +A Bot inherits the optional global default, selects one complete shared template, or disables its Reviewer (ADR-0342). Deterministic authorization runs first; Reviewer outcomes are allow for this call or ask-human. ## Sub-features -- `library` is Bot settings → Auto approval: every template with `Built-in` or its file name, its description and the Bots that use it. `New` creates one; `View` opens a built-in read-only with `Copy`; `Edit` opens a Human template with `Save` and `Delete`. -- `cli` is `deepseekbot approval-template list|show|create|edit|delete` and `approval-template-set `. Files live in `$DSH_HOME/botharness/approval-templates/.md`. -- `select` is the Bot's channel settings → Auto approval page, or the composer workspace panel. -- `reviewer` leaves a folded `Auto-approved by