@zihanw/pi-forge 0.5.8 → 0.5.10

package/docs/reference/capabilities.md

@@ -6,7 +6,7 @@ Pi-forge introduces capabilities: session-scoped prompt directives paired with d
 
 ## Requirements and installation
 
-- **Host requirement:** Minimum supported Pi version is 0.87.0. Published Forge 0.5.7 declared peer range `>=0.87.0 <0.88.0`; Forge 0.5.8 supports `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.1.0` (dev SDK 1.0.2, `typebox@1.3.27`; min SDK 0.87 unchanged; no dual 0.86 runtime support claim). Capabilities require Forge 0.5.5. See [Pi 1.0 compatibility guide](../guides/pi-1-compatibility.md).
+- **Host requirement:** Minimum supported Pi version is 0.87.0. Published Forge 0.5.7 declared peer range `>=0.87.0 <0.88.0`; Forge 0.5.8 supported `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.1.0`; Forge 0.5.10 supports `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.5.0` (dev SDK 1.4.0, `typebox@1.3.27`; min SDK 0.87 unchanged; no dual 0.86 runtime support claim). Capabilities require Forge 0.5.5. See [Pi 1.0 compatibility guide](../guides/pi-1-compatibility.md).
 - **Project trust:** Activating capabilities, preset bindings, or manual directives requires a trusted project (`isProjectTrusted()`).
 - **Compatibility:** Configurations utilizing `tools.initial` require a Forge version with this support; older Forge versions may ignore `initial`, so configurations are not downgrade-compatible.
 
@@ -48,6 +48,35 @@ Capabilities are JSON files stored in:
 - **Revocation behavior:** Revoking a binding's authorization (`modelCallable: false`) or removing the binding from the Preset does not retroactively erase active snapshots; human CLI (`/capability disable` or `/capability reset`) or Web panel deactivation is the recovery path.
 - **User vs. Agent ownership and deduplication:** Activations record actor attribution (`user` vs `agent`). Repeated `enable` of an already active capability is idempotent and never performs an automatic owner takeover between user and agent. Takeover requires an explicit deactivation and reactivation cycle.
 
+## Execution authorization (Forge 0.5.10)
+
+With an active Preset's restrictive tool policy, **all tool calls, including nested codemode calls, require Forge authorization**. The effective set starts from `tools.initial` when configured, otherwise the policy-derived baseline, then applies enabled Capability additions and removals under allow/deny. Turning a Capability off immediately revokes execution access for any tool no longer authorized; defaults or another Capability may still authorize it. Running tools are not interrupted. Forge uses this effective set, not Pi's active tool list; allow membership alone does not enable a tool omitted from the effective set. Calls to tools not currently enabled point to `forge_capability` when a Capability can provide access.
+
+An effective tool `P` also authorizes registered `P__*` descendants **from the same registration source**. For example, enabling `mcp` or `mcp__hitch` permits pi-mcp-adapter 6+/7 calls named `mcp__hitch__<tool>` from that source, without listing every child in `allow`. Different or missing registration sources do not grant this access. Preset deny and active Capability remove still block child tools; use an exact deny entry to exclude one child. Capability `remove` uses exact names, not wildcards.
+
+Sync retains already-active tools authorized by the effective set or same-source namespace rule, and tools registered with `deferred` or `codemode` exposure, unless Preset deny or Capability remove excludes them. Retention does not grant execution access: unauthorized discovered tools remain callable so the gate can return an actionable block instead of a misleading “not found”. Other external `direct` tools are removed; missing exposure on older Pi is treated as `direct`. Disabling a Capability still removes its direct additions when no longer authorized. `tools.initial` stays authoritative; deny-only Presets and mixed wildcard allow lists (for example `allow: ["*", "read"]`) without `initial` keep their existing external-addition baseline absorption, which can authorize those tools. Pure selective allow lists (without `*`) do not gain execution authorization from external activation alone. Retention avoids unnecessary removals, not all OpenAI cache fallback.
+
+Without an active Preset or a restrictive tool policy, execution behavior is unchanged. `tools.initial` alone or `allow: ["*"]` alone does not enable the new gate; an allow list containing an entry other than `*`, or a nonempty deny list, does. Existing explicit Capability removals still apply.
+
+This **Preset tool-policy fragment** uses deny (not allow; the two policies are mutually exclusive) to permit enabling `mcp__hitch` while denying one child even after the parent is enabled:
+
+```json
+{
+  "tools": {
+    "deny": ["mcp__hitch__delete"],
+    "initial": ["forge_capability"]
+  }
+}
+```
+
+A Capability can use `"tools": { "add": ["mcp__hitch"], "remove": [] }`. Once enabled, same-source children other than `mcp__hitch__delete` are authorized. Disabling it revokes that namespace access unless another effective parent still authorizes it. Use actual registered names from your session.
+
+### Known limitations
+
+- **Discovery:** codemode `ALL_TOOLS` / `searchTools()` and `tool_search` can still reveal unauthorized names. Forge blocks execution, not discovery.
+- **Model APIs:** codemode `models.generateImages()` (new in Pi 1.0) and `models.classify()` (since 0.99) do not pass through `tool_call`, so Forge cannot block them. Disabling an image Capability does **not** disable these APIs. Only programmatic SDK assembly with `createCodemodeExtension({ models: false })` disables this codemode model access; Pi settings have no equivalent toggle.
+- **Prefix caching:** on OpenAI Responses/Completions transports, any tool removal, including disabling a Capability that removes tools, makes subsequent requests in that session send the full current tool list. Removal detection scans the transcript, so re-enabling tools does not restore incremental delivery while that history remains. This disrupts prefix caching. Anthropic's native `tool_removal` path is unaffected by this fallback. Forge aims to preserve cacheable prefixes where possible, not guarantee cache hits.
+
 ## Preset-authorized Agent controls
 
 Preset `capabilities` bindings support autonomous Agent activation when explicitly authorized:
@@ -230,7 +259,7 @@ Active state is derived deterministically from session events and delivery curso
 
 ## Compatibility and security boundaries
 
-- **Upstream Pi minimum required:** Pi 0.87.0 is the minimum supported host (Forge 0.5.8 supports `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.1.0`; published 0.5.7 peer metadata remains `>=0.87.0 <0.88.0`). Dual 0.86 runtime support is not provided. Extensions that previously manipulated or inspected full System messages in `context` must migrate to the full `context_with_system` hook. See [Pi 1.0 compatibility](../guides/pi-1-compatibility.md).
+- **Upstream Pi minimum required:** Pi 0.87.0 is the minimum supported host (Forge 0.5.10 supports `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.5.0`; Forge 0.5.8 supported `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.1.0`; published 0.5.7 peer metadata remains `>=0.87.0 <0.88.0`). Dual 0.86 runtime support is not provided. Extensions that previously manipulated or inspected full System messages in `context` must migrate to the full `context_with_system` hook. See [Pi 1.0 compatibility](../guides/pi-1-compatibility.md).
 - **Timing with `before_agent_start`:** Any forced System prompt injection via `before_agent_start` continues to execute later than `context_with_system`.
 - **Preceding extension message rewrites:** Pi permits context hooks to rewrite messages. When visible metadata anchors or unanchored events need positioning, Forge requires a unique ordered alignment with the canonical session projection and fails closed if arbitrary preceding rewrites break alignment. Pi may persist queued custom messages absent from a tool follow-up: Forge permits only uniquely alignable custom-message omissions, ignores their regenerated envelope timestamps, and preserves incoming objects without restoring omitted dialogue. A preceding rewrite can therefore conflict with this locator; moving it later does not guarantee safe composition. Broad plugin, warming, and automatic-overflow compatibility remain unverified.
 - **Upstream defect status and protocol limits:** Upstream Pi metadata chunking and semantic-cut defects are NOT patched and remain unfixed upstream. Compaction checkpoint placement is unchanged. Old sessions and former delivery carriers remain untouched and unsupported for continuing capability state; Forge does not migrate old JSONL or rewrite historical summaries. Oh My Pi (OMP) is not supported or promised.

package/docs/reference/features.md

@@ -10,7 +10,7 @@ This file tracks the currently implemented feature surface for agent profiles, t
 - Tarball verification rejects physical `src/` entries and requires the root and subagent compiled entry points.
 - The web editor's HTML page shell and static styles are maintained separately from its browser behavior modules.
 - Strict typed web-editor client modules bundled into one self-contained browser script at build time, with generated-client consistency verification.
-- Supported Node.js baseline is 22.19+. In published 0.5.7, peer metadata required `>=0.87.0 <0.88.0`. Forge 0.5.8 expands supported peers to `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.1.0` (development SDK pinned to 1.0.2 with `typebox@1.3.27`, minimum 0.87.0 unchanged). All five packages remain host-provided optional peers. Exact repository versions are reproducible development/test fixtures rather than runtime constraints. See [Pi 1.0 compatibility guide](../guides/pi-1-compatibility.md).
+- Supported Node.js baseline is 22.19+. In published 0.5.7, peer metadata required `>=0.87.0 <0.88.0`. Forge 0.5.8 expanded supported peers to `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.1.0`; Forge 0.5.10 expands them to `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.5.0` (development SDK pinned to 1.4.0 with `typebox@1.3.27`, minimum 0.87.0 unchanged). All five packages remain host-provided optional peers. Exact repository versions are reproducible development/test fixtures rather than runtime constraints. See [Pi 1.0 compatibility guide](../guides/pi-1-compatibility.md).
 - Project trust check before loading prompt stacks.
 - Footer status showing the active prompt stack.
 
@@ -249,7 +249,7 @@ This file tracks the currently implemented feature surface for agent profiles, t
 
 ## Capabilities and System Updates
 
-- Upstream host requirement: Minimum supported Pi version is 0.87.0 (published 0.5.7 declared `>=0.87.0 <0.88.0`; source compatibility policy supports `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.1.0`; dev SDK updated to 1.0.2 with `typebox@1.3.27`; no dual 0.86 runtime support claim). See [Pi 1.0 compatibility](../guides/pi-1-compatibility.md).
+- Upstream host requirement: Minimum supported Pi version is 0.87.0 (published 0.5.7 declared `>=0.87.0 <0.88.0`; 0.5.10 supports `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.5.0`; dev SDK updated to 1.4.0 with `typebox@1.3.27`; no dual 0.86 runtime support claim). See [Pi 1.0 compatibility](../guides/pi-1-compatibility.md).
 - File-backed capability definitions stored in `.pi/forge/capabilities/<id>.json` (project scope) and `~/.pi/forge/capabilities/<id>.json` (global scope) with schema `schemaVersion: 1`, `type: "pi-forge.capability"`.
 - Literal text content (up to 100,000 characters) without macro, template, or script evaluation.
 - Tool modification patches supporting `add` and `remove` arrays (tool IDs ≤ 128 characters, no whitespace/controls/wildcards, up to 256 tools per array). Capabilities support `add` and `remove` ONLY; candidate `only`/allowlist is not implemented.

package/docs/reference/provider-support.md

@@ -24,7 +24,7 @@ Tool flags only apply when `supportsMidConvoSystemMessages` is also enabled. The
 | API | Instruction text | Tool changes |
 |---|---|---|
 | `anthropic-messages` | With the flag: a `role: "system"` message. Pi holds it until just before the next assistant message, so it never separates a `tool_use` from its `tool_result`; an update recorded before a user message is sent after it. | With `supportsMidConvoToolChanges` and at least one initial tool. **Pi 1.0.1+:** the request-level list stays fixed (initial tools plus a reserved deferred placeholder); later tools are defined by value inside `tool_addition` blocks (a same-name redefinition replaces the earlier definition) and withdrawn by `tool_removal`. **Pi 1.0.0 and earlier:** later tools are appended to the request-level list with `defer_loading`, the list only grows, and a same-name redefinition falls back to the full list. Otherwise (including a session that starts with no active tools, such as `tools.initial: []`): the current list at request level. |
-| `openai-responses`, `openai-codex-responses`, `azure-openai-responses` | With the flag: a `developer` message (reasoning models that accept the developer role) or a `system` message, at its position. | Additions load in place while retained history contains only additions. Any removal or same-name redeclaration anywhere in retained history switches that request to the full current list at request level. |
+| `openai-responses`, `openai-codex-responses`, `azure-openai-responses` | With the flag: a `developer` message (reasoning models that accept the developer role) or a `system` message, at its position. | Additions load in place while retained history contains only additions. Any removal or same-name redeclaration anywhere in retained history switches that and subsequent requests to the full current list at request level while that history remains. |
 | `openai-completions` | With the flag: a `developer` or `system` message at its position. | Additions load in place with `supportsMidConvoToolAdditions`; removals and redeclarations switch to the full current list. |
 | `mistral-conversations` | With the flag: a `system` message at its position. | Always the full current list at request level. |
 | Google Generative AI / Vertex | Always folded into `systemInstruction`; no mid-conversation path. | Full current list. |
@@ -58,7 +58,7 @@ These are single-session observations, not guarantees. Cache reuse is decided by
 - **`anthropic/claude-sonnet-5`, fallback path:** the request after a tool change read nothing from cache, because Pi rewrote the leading system prompt and tool list. The model also questioned the labeled user update before using the new tool.
 - **OpenAI Responses / Codex:** in earlier tests, a removal switched to the full tool list and cache reads dropped to zero; requests with only additions kept the prefix.
 
-To keep caches stable, prefer a flagged model with native tool changes. On Responses-family models, avoid removing tools in a session where cache reuse matters.
+To preserve cacheable prefixes where possible, prefer a flagged model with native tool changes; cache hits are not guaranteed. On OpenAI Responses/Completions transports, any removal, including disabling a Capability that removes tools, makes later session requests send the full current tool list because removal detection scans the transcript. Re-enabling tools does not restore incremental delivery while that history remains. Anthropic's native `tool_removal` path is unaffected by this fallback.
 
 ## Checking your own setup
 

package/docs/zh-CN/concepts/agent-profiles.md

@@ -41,6 +41,8 @@ Agent profile 是项目级或用户全局、带 schema version 的预设，只
 
 最多一个 profile 可以设置 `autoActivate: true`。它只在全新 session 中应用一次，并优先于独立 stack autoload；恢复的 branch 状态优先。无效或冲突的自动启用会 fail closed。
 
+自动 Profile 的设置及预设/工具选择可能在首轮提示词兼容性被观察之前生效。之后检测到缺少必要输入时，不会回滚这些设置、中止 provider 请求派发，或自动清除独立生效的工具策略。CLI 应用前会检查命令专用提示词 API；这不是通用启动检测，也不代表支持 OMP 等分支。详见[不受支持宿主的边界](../guides/pi-1-compatibility.md#不受支持宿主的边界)。
+
 `/profile status` 会把 profile 源定义变化和当前模型/思考等级/stack drift 分开显示。Provenance 只用于 branch 状态报告；reload、resume、tree navigation 和 compaction 不会重新应用 profile。
 
 普通 profile 默认不能委派。Delegation 授权由可选包 `@zihanw/pi-forge-subagents` 通过专用文件持有，使用 `project:<id>` 或 `global:<id>` 完整 key，并可按 profile 覆盖 backend/timeout。裸授权 key 无论位于哪个文件都只是项目 profile 的兼容别名；同 ID 的全局和项目 profile 永不互相继承授权。主包不读取任何 subagent 配置，删除 profile 也不会改动 `subagents.json`。启用前见[前台 delegation](../guides/delegation.md)。

package/docs/zh-CN/guides/pi-1-compatibility.md

@@ -2,6 +2,38 @@
 
 [中文文档](../README.md) · [English](../../guides/pi-1-compatibility.md)
 
+## Forge 0.5.10：Pi 1.4
+
+开发 SDK 固定为 **1.4.0**，四个可选 SDK peer 范围扩大为：
+
+```text
+>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.5.0
+```
+
+最低 Pi 0.87.0 与 `typebox@1.3.27` 保持不变；不自动承诺 Pi 1.5+ 或其他 0.x。常规 CI 与普通打包消费者使用 1.4.0，历史兼容矩阵保留 1.3.0 及已有版本。Forge 0.5.10 还新增下文所述的执行门禁与命名空间授权；不改写 MCP 名称。下方 0.5.9 / 0.5.8 段落保留为历史说明，并非当前 peer 范围。
+
+**Pi 1.4 恢复说明：** Pi 1.4 恢复会话时，会激活该分支从未提到过的扩展工具（例如 transcript 早于 `forge_capability` 时）。Forge 绑定后仍会把执行授权收敛到当前预设与 Capability 的有效范围；active 工具列表可能保留被发现但不可执行的 `deferred`/`codemode` 工具；`tests/pi13-tool-restore.test.ts` 在 1.4 上覆盖了这一点。
+
+## Forge 0.5.9：Pi 1.1 / 1.2 / 1.3
+
+Forge 0.5.9 将开发 SDK 固定为 **1.3.0**，四个可选 SDK peer 范围扩大为：
+
+```text
+>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.4.0
+```
+
+不自动承诺 Pi 1.4 或其他 0.x。历史 CI 保留 1.0.2，并增加 1.0.4 / 1.1.0 / 1.2.0；常规任务使用 1.3.0。兼容任务核对实际解析版本，并明确固定 1.x codemode/MCP/telemetry/chord 为同版本 fixture。这些任务的打包消费者也通过 `PI_TEST_COHERENT_UPSTREAM=1` 使用同样的固定版本；常规打包检查（1.3.0 任务）保持 npm 正常解析。原因是 Pi 1.0.1–1.1.x 的全新无约束安装现在会经上游 caret 拉到更新且不兼容的 codemode/MCP（例如 Pi 1.1.0 + pi-codemode 1.3.0 因缺少 `MCP_TYPESCRIPT_PREAMBLE` 导出而失败），与 Forge 无关。fixture 通过只说明 Forge 在该宿主系列上可用，不代表旧版 Pi 的全新无约束安装可用。
+
+Pi 1.2 的空闲自定义唤醒触发无 `prompt` 的 `before_agent_start`，启动时 `isIdle()` 已为 false。Forge 在编译 System 块之前，通过现有预览投影与历史 helper 一次解析当前分支的 `runtime.lastUserMessage`，直到结算保持工具后续请求的快照。没有符合条件的用户内容则为空；自定义消息不是用户提示。保留 helper 既有渲染（包括图片的 `[image]`）；role=user 不代表经过身份认证的人类。每个实际 start 重置 turn 频率规则；忙碌时 steering 不伪造 start 或用户消息。普通/旧宿主 user 事件仍以展开后的 prompt 为准，包括空文本/仅图片输入。旧宿主不发出 custom-start 时，不伪造该事件。
+
+**Pi 1.1 及更早版本的已知限制：** 这些宿主启动空闲自定义唤醒时（例如 Subagents 完成通知唤醒父会话）不触发任何 `before_agent_start`，Forge 无从得知这一轮开始。该次唤醒请求及其工具后续请求不带预设的 System 块；工具策略照常生效。这一点与 0.5.8 相同，已在 Pi 1.1.0 上实测。普通用户输入和忙碌时的 steering 不受影响。依赖后台完成唤醒的话，请使用 Pi 1.2 或更高版本。
+
+Pi 1.3 保持 custom-start/System 契约，并在默认或修饰符工具选择模式创建会话时恢复 transcript 中的活动工具；显式工具列表仍覆盖恢复。Forge 按预设的 `tools.initial`、allow/deny 与活动能力重新计算有效工具，不能让过期 transcript 越过权限上限或丢失能力工具。停用预设时恢复工具策略所有者保存的启动基线，并协调可区分的外部修改，而不是用经过策略缩减的 transcript 丢弃原基线。真实 SDK 持久化会话测试使用离线 faux 流覆盖这些路径。该 0.5.9 恢复改动未新增执行门禁；Forge 0.5.10 新增下文所述的门禁。
+
+Pi 1.3 内部 SDK/codemode/MCP/telemetry 改为精确版本依赖，普通消费者无需历史 fixture 覆盖即可解析七个 Pi 包为 1.3.0；这不会修复旧版本 caret 的解析漂移。
+
+下文 0.5.8 一节记录上一版本的策略（peer 至 `<1.1.0`），仅作历史保留，不是当前 peer 范围。
+
 ## Forge 0.5.8 与旧版本
 
 本指南介绍 **Forge 0.5.8** 兼容补丁。安装旧版 `@zihanw/pi-forge@0.5.7` 不会获得这些改动；该 artifact 的 Pi peer 范围仍为 `>=0.87.0 <0.88.0`。
@@ -16,6 +48,16 @@ Forge 0.5.8 为四个 Pi SDK 包声明的 peer 策略为：
 
 本补丁只调整依赖、测试覆盖与文档，**不改变**工具授权、Capability 所有权、用量汇总或个人配置。
 
+## 不受支持宿主的边界
+
+Forge 需要上游 Pi 的 `systemPromptOptions` 与 `context_with_system` 契约。oh-my-pi（OMP）等分支仍不受支持；优雅处理缺失输入不等于支持 OMP，也不认证分支的工具权限实现。
+
+- CLI 应用预设/Profile 会在改变选择或模型前检查命令专用的提示词 API；普通生命周期 context 无需提供命令专用 getter。
+- 全新会话的自动 Profile 模型/思考设置及预设/工具选择仍然提前生效，可能早于首轮提示词兼容性被观察到。不会延后应用，也不会在随后检测到缺失输入时自动回滚。
+- 缺少必要输入时每个会话只警告一次，清除过时的编译捕获，并在该会话内锁定拒绝新的预设/Profile 应用及预设编译/预览，包括已打开 Web 编辑器的 Preview。检测**不会**中止 provider 请求派发，也不会自动清除独立生效的工具策略；Forge 仍继续应用并检查其策略。
+- `/preset use none`（或 `off`）可显式禁用预设。新会话会重置锁定状态与警告次数；tree navigation、compaction 和 agent settlement 不会重置。重试前应先修复宿主契约，再新建会话。
+- 检测不覆盖所有宿主，也不保证在启动时完成。有效的选项与成功的 `pi.on()` 注册不能证明 `context_with_system` 真会被调用；Forge 不以注册成功推断 hook 支持。
+
 ## Native MCP：逐项确认精确名称迁移
 
 Pi 0.99.2+ 规范化 native MCP 名称，例如 `mcp__demo-server__ping` 改为 `mcp__demo_server__ping`。同一服务器内 `a-b` 与 `a_b` 等工具名冲突会添加 hash 后缀；服务器名规范化冲突会被拒绝。
@@ -31,7 +73,7 @@ Pi 0.99.2+ 规范化 native MCP 名称，例如 `mcp__demo-server__ping` 改为
 
 ## Discovery 与延迟注册
 
-默认 native MCP 服务器后台连接，不阻塞首个 prompt；`direct` exposure 的启动行为不同。默认工具以 deferred exposure 注册，不列进 codemode description，通过 `searchTools()` / `describeNamespace()` 发现。搜索工具不会授予 Forge Capability，也不会覆盖工具策略。
+默认 native MCP 服务器后台连接，不阻塞首个 prompt；`direct` exposure 的启动行为不同。默认工具以 deferred exposure 注册，不列进 codemode description，通过 `searchTools()` / `describeNamespace()` 发现。搜索工具不会授予 Forge Capability，也不会覆盖工具策略：发现工具不等于获准执行。
 
 Pi 1.0 改进了 resume/reload 后的 deferred 工具恢复。Forge 仍要求 Capability add 的工具已注册；服务器未就绪时，应等待注册后重试原操作。单纯 reload 不保证解决问题。显式策略同步可能替换宿主恢复的 loadout，不应假定所有 pending 工具必须自动恢复。完整慢 MCP resume/reload 需要集成验收，不能拿 catalog mock 测试冒充。
 
@@ -41,13 +83,23 @@ Forge 保留 `mcp_servers` 等外来 System section，包括更新和删除。
 
 在支持原生中途改工具的 Anthropic 模型上，Pi 1.0.1 起请求级工具列表固定为初始工具加一个保留占位工具，之后的每个工具都直接以完整定义写在 `tool_addition` 块里。因此启用或停用 Capability 不再改写请求级工具列表，同名重定义也不再强制发送完整列表。原生路径仍需要至少一个初始工具：会话开始时没有任何活动工具（例如 `tools.initial: []` 的预设）时，每次工具变化都会在请求级别发送当前完整列表。Forge 不改变这一行为，也没有针对 1.0.1 起重新做真实缓存实测。详见 [Provider 支持](../reference/provider-support.md)。
 
-## Codemode 边界保持原样
+## 工具执行与 Codemode 边界（Forge 0.5.10）
 
 Pi 1.0 访问不存在的 `tools` 属性会抛错。检查存在性请用 `"name" in tools`，不要用 `typeof tools.name`。
 
-`tools.initial` 是默认 loadout，**不是按 enabled 集合检查执行的 gate**。在 Preset 许可内、已注册的 deferred/codemode 工具，即使未列入 initial，或添加它的 Capability 已关闭，仍可能经 codemode nested 调用。Preset 的 allow **或** deny 策略和活动 Capability.remove 仍生效；direct 调用还取决于宿主 active loadout。本补丁不改变这些语义，也不让 discovery 自动按授权过滤。
+活跃 Preset 含有限制性的工具策略时，**所有工具调用（包括 codemode 嵌套调用）都必须获得 Forge 授权**。有效集以配置的 `tools.initial` 为起点，否则采用按策略计算的基线，再在 allow/deny 约束下应用已启用 Capability 的添加与移除。关闭 Capability 会立即撤销不再获授权工具的执行权限；默认集或其他 Capability 仍可能授权该工具。不会中断正在执行的工具。Forge 依据这个有效集，而不是 Pi 的 active 工具列表；仅列入 allow 不会启用有效集之外的工具。对当前未启用工具的调用，若可由 Capability 提供权限，拦截提示会指向 `forge_capability`。
+
+有效集中的工具 `P` 还授权**同一注册来源**的已注册 `P__*` 子工具。例如，启用 `mcp` 或 `mcp__hitch` 后，pi-mcp-adapter 6+/7 以 `mcp__hitch__<tool>` 名义发出的同来源调用可以执行，无需把每个子工具写入 `allow`。注册来源不同或缺失时不授予此权限。Preset deny 与活动 Capability remove 仍可阻止子工具；可用精确 deny 项排除单个子工具。Capability `remove` 使用精确名称，不支持通配符。
+
+同步会保留已 active 且由有效集或同来源命名空间规则授权的工具，以及注册 exposure 为 `deferred` 或 `codemode` 的工具，但 Preset deny 或 Capability remove 排除的工具仍会撤掉。保留不授予执行权限：未授权的已发现工具保留在可调用表中，让门禁返回可操作的拦截提示，而非误导性的 “not found”。其他外部激活的 `direct` 工具仍会撤掉；旧 Pi 缺失 exposure 时按 `direct` 处理。关闭 Capability 仍会撤掉其不再获授权的 direct 添加项。`tools.initial` 保持权威；无 `initial` 的仅 deny 预设和混合 wildcard allow（例如 `allow: ["*", "read"]`）保持既有的外部新增吸收进基线语义，可因此授权这些工具。纯选择性 allow（不含 `*`）不会仅因外部激活而获得执行授权。保留减少不必要的撤销，但不能消除所有 OpenAI 缓存回退。
+
+无活跃 Preset 或无限制性工具策略时，执行行为不变。仅 `tools.initial` 或仅 `allow: ["*"]` 不会启用新门禁；allow 列表含有非 `*` 项，或 deny 列表非空时才启用。已有的显式 Capability 移除仍生效。
+
+### 已知限制
 
-`models.generateImages()`（1.0 新增）和 `models.classify()`（0.99 已有）直接调用会话 model registry，不经过 `ctx.executeTool()` / `tool_call`。关闭生图工具**不等于**关闭模型 API。Pi settings 没有 `models: false` 开关；SDK factory `createCodemodeExtension({ models: false })` 需要明确的编程式插件装配。
+- **发现：** codemode `ALL_TOOLS` / `searchTools()` 与 `tool_search` 仍可能显示未授权工具名。Forge 只阻断执行，不过滤发现。
+- **模型 API：** codemode `models.generateImages()`（Pi 1.0 新增）与 `models.classify()`（0.99 已有）不经过 `tool_call`，Forge 无法拦截。关闭生图 Capability **不能**禁用这些 API。只有通过 SDK 编程式装配 `createCodemodeExtension({ models: false })` 才能关闭这类 codemode 模型访问；Pi settings 没有对应开关。
+- **前缀缓存：** 在 OpenAI Responses/Completions 系列传输上，任何工具移除（包括关闭 Capability 导致的工具移除）都会使该会话后续请求发送当前完整工具表。移除检测会扫描转录历史，因此只要该历史仍保留，重新启用工具也不能恢复增量投递。这会破坏前缀缓存。Anthropic 原生 `tool_removal` 路径不受这种回退影响。Forge 旨在尽量保留可缓存前缀，不承诺缓存命中。
 
 Pi 会将 codemode 模型返回的用量计入总账。Forge cache 面板仍分别展示 assistant 用量与显式 `details.forgeNestedUsage`，没有新增任意 native tool/model usage 汇总；不能把两份回执直接重复加总。
 
@@ -64,9 +116,9 @@ agent-core 实验 harness 的移除，不等于我们配套 runtime 使用的 co
 ```bash
 # 目标与已安装开发 SDK 不同时，请同时指定这两个版本。
 PI_TEST_VERSION=0.87.0 TYPEBOX_TEST_VERSION=1.3.7 npm run check:packed
-PI_TEST_VERSION=1.0.2 TYPEBOX_TEST_VERSION=1.3.27 npm run check:packed
+PI_TEST_VERSION=1.4.0 TYPEBOX_TEST_VERSION=1.3.27 npm run check:packed
 ```
 
 不指定时，packed 检查读取一致的已安装 SDK family 及其声明的 TypeBox 版本，不再硬编码旧 pin。两个消费者都使用正常 npm peer 解析，并核对实际安装版本。如果存在 optional sibling，使用它声明的 runtime 依赖；不把这当成未发布本地 runtime 的测试。
 
-常规 Linux/macOS/Windows CI 使用固定的 Pi 1.0.2；显式兼容（0.87.0 至 1.0.1）与 scheduled latest 探针运行在 Linux。目标 release commit 的 CI 仍是发布门槛，不代表当前源码补丁已完成远端平台或真实 provider 验收。
+常规 Linux/macOS/Windows CI 使用固定的 Pi 1.4.0；显式兼容（0.87.0 至 1.3.0，含 1.0.2）与 scheduled latest 探针运行在 Linux。目标 release commit 的 CI 仍是发布门槛；本文不记录其结果，也不代表已完成真实 provider 验收。

package/docs/zh-CN/reference/capabilities.md

@@ -6,7 +6,7 @@ Pi-forge 引入了能力（Capabilities）：会话级动态提示词指令与
 
 ## 环境要求与安装
 
-- **宿主版本：** 最低支持 Pi 0.87.0。已发布的 Forge 0.5.7 声明 peer 范围为 `>=0.87.0 <0.88.0`；Forge 0.5.8 支持联合范围 `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.1.0`（开发 SDK 更新至 1.0.2，`typebox@1.3.27`；最低 SDK 0.87 保持不变；不声称对 0.86 的双重运行时支持）。能力功能需要 Forge 0.5.5。详见 [Pi 1.0 兼容指南](../guides/pi-1-compatibility.md)。
+- **宿主版本：** 最低支持 Pi 0.87.0。已发布的 Forge 0.5.7 声明 peer 范围为 `>=0.87.0 <0.88.0`；Forge 0.5.8 支持 `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.1.0`；Forge 0.5.10 支持联合范围 `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.5.0`（开发 SDK 更新至 1.4.0，`typebox@1.3.27`；最低 SDK 0.87 保持不变；不声称对 0.86 的双重运行时支持）。能力功能需要 Forge 0.5.5。详见 [Pi 1.0 兼容指南](../guides/pi-1-compatibility.md)。
 - **项目信任：** 激活能力、预设绑定或添加手动指令需要项目处于受信任状态（`isProjectTrusted()`）。
 - **兼容性限制：** 包含 `tools.initial` 的配置需要新版 Forge 支持；旧版 Forge 会忽略 `initial`，因而配置不具备向下降级兼容性。
 
@@ -48,6 +48,35 @@ Pi-forge 引入了能力（Capabilities）：会话级动态提示词指令与
 - **授权撤销行为：** 在 Preset 中撤销授权（将 `modelCallable` 设为 `false`）或删除绑定项，不会追溯抹除已激活的快照；用户通过 CLI（`/capability disable` 或 `/capability reset`）或 Web 面板停用是标准恢复路径。
 - **用户与 Agent 所有权及去重：** 激活项记录归属主体（`user` 或 `agent`）。重复 `enable` 已激活的能力具备幂等性，绝不自动在用户与 Agent 之间转移所有权（takeover）。接管必须通过显式关闭后再重新启用。
 
+## 执行授权（Forge 0.5.10）
+
+活跃 Preset 含有限制性的工具策略时，**所有工具调用（包括 codemode 嵌套调用）都必须获得 Forge 授权**。有效集以配置的 `tools.initial` 为起点，否则采用按策略计算的基线，再在 allow/deny 约束下应用已启用 Capability 的添加与移除。关闭 Capability 会立即撤销不再获授权工具的执行权限；默认集或其他 Capability 仍可能授权该工具。不会中断正在执行的工具。Forge 依据这个有效集，而不是 Pi 的 active 工具列表；仅列入 allow 不会启用有效集之外的工具。对当前未启用工具的调用，若可由 Capability 提供权限，拦截提示会指向 `forge_capability`。
+
+有效集中的工具 `P` 还授权**同一注册来源**的已注册 `P__*` 子工具。例如，启用 `mcp` 或 `mcp__hitch` 后，pi-mcp-adapter 6+/7 以 `mcp__hitch__<tool>` 名义发出的同来源调用可以执行，无需把每个子工具写入 `allow`。注册来源不同或缺失时不授予此权限。Preset deny 与活动 Capability remove 仍可阻止子工具；可用精确 deny 项排除单个子工具。Capability `remove` 使用精确名称，不支持通配符。
+
+同步会保留已 active 且由有效集或同来源命名空间规则授权的工具，以及注册 exposure 为 `deferred` 或 `codemode` 的工具，但 Preset deny 或 Capability remove 排除的工具仍会撤掉。保留不授予执行权限：未授权的已发现工具保留在可调用表中，让门禁返回可操作的拦截提示，而非误导性的 “not found”。其他外部激活的 `direct` 工具仍会撤掉；旧 Pi 缺失 exposure 时按 `direct` 处理。关闭 Capability 仍会撤掉其不再获授权的 direct 添加项。`tools.initial` 保持权威；无 `initial` 的仅 deny 预设和混合 wildcard allow（例如 `allow: ["*", "read"]`）保持既有的外部新增吸收进基线语义，可因此授权这些工具。纯选择性 allow（不含 `*`）不会仅因外部激活而获得执行授权。保留减少不必要的撤销，但不能消除所有 OpenAI 缓存回退。
+
+无活跃 Preset 或无限制性工具策略时，执行行为不变。仅 `tools.initial` 或仅 `allow: ["*"]` 不会启用新门禁；allow 列表含有非 `*` 项，或 deny 列表非空时才启用。已有的显式 Capability 移除仍生效。
+
+以下 **Preset 工具策略片段**使用 deny（不同时使用 allow，两种策略互斥），允许启用 `mcp__hitch`，但即使父工具已启用，也禁止其中一个子工具：
+
+```json
+{
+  "tools": {
+    "deny": ["mcp__hitch__delete"],
+    "initial": ["forge_capability"]
+  }
+}
+```
+
+Capability 可配置 `"tools": { "add": ["mcp__hitch"], "remove": [] }`。启用后，除 `mcp__hitch__delete` 外的同来源子工具均获授权。关闭后撤销该命名空间权限，除非仍有其他有效父工具授权它。请使用会话中实际注册的名称。
+
+### 已知限制
+
+- **发现：** codemode `ALL_TOOLS` / `searchTools()` 与 `tool_search` 仍可能显示未授权工具名。Forge 只阻断执行，不过滤发现。
+- **模型 API：** codemode `models.generateImages()`（Pi 1.0 新增）与 `models.classify()`（0.99 已有）不经过 `tool_call`，Forge 无法拦截。关闭生图 Capability **不能**禁用这些 API。只有通过 SDK 编程式装配 `createCodemodeExtension({ models: false })` 才能关闭这类 codemode 模型访问；Pi settings 没有对应开关。
+- **前缀缓存：** 在 OpenAI Responses/Completions 系列传输上，任何工具移除（包括关闭 Capability 导致的工具移除）都会使该会话后续请求发送当前完整工具表。移除检测会扫描转录历史，因此只要该历史仍保留，重新启用工具也不能恢复增量投递。这会破坏前缀缓存。Anthropic 原生 `tool_removal` 路径不受这种回退影响。Forge 旨在尽量保留可缓存前缀，不承诺缓存命中。
+
 ## Preset 授权的 Agent 控制
 
 Preset 的 `capabilities` 绑定支持智能体自主选择与启用能力：
@@ -230,7 +259,7 @@ Forge 在每次发起模型请求时通过两阶段拼装动态投影能力增
 
 ## 兼容性与安全边界
 
-- **要求上游 Pi 最低版本：** 必须使用上游 Pi 0.87.0 或更高版本（Forge 0.5.8 支持 `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.1.0`；已发布 0.5.7 的 peer 元数据保持 `>=0.87.0 <0.88.0` 不变）。不提供对 0.86 的双重运行时支持。之前在 `context` hook 中操作或读取完整 System 消息的第三方扩展必须迁移到 `context_with_system` 完整 hook。详见 [Pi 1.0 兼容指南](../guides/pi-1-compatibility.md)。
+- **要求上游 Pi 最低版本：** 必须使用上游 Pi 0.87.0 或更高版本（Forge 0.5.10 支持 `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.5.0`；Forge 0.5.8 支持 `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.1.0`；已发布 0.5.7 的 peer 元数据保持 `>=0.87.0 <0.88.0` 不变）。不提供对 0.86 的双重运行时支持。之前在 `context` hook 中操作或读取完整 System 消息的第三方扩展必须迁移到 `context_with_system` 完整 hook。详见 [Pi 1.0 兼容指南](../guides/pi-1-compatibility.md)。
 - **`before_agent_start` 注入时机：** `before_agent_start` 阶段强制注入的 System 提示词在 Pi 执行流中仍然晚于 `context_with_system` 生效。
 - **前置扩展上下文改写：** Pi 允许 hook 改写消息。当可见元数据锚点或未锚定事件需要定位时，Forge 要求输入与规范会话投影有唯一的有序对应，否则中止而非猜测（fail-closed）。Pi 可能先保存排队的 custom 消息、但暂不放入工具续跑上下文：Forge 仅容许位置能唯一确定的 custom 消息缺省，忽略其重新生成的外层时间戳；保留传入对象，不擅自把缺省对话补回请求。前置改写因而可能与该定位方式冲突；简单后移不保证组合安全。通用插件、warming、自动 overflow 兼容性仍未全面验收。
 - **上游缺陷与协议限制：** 上游 Pi 元数据分块及语义截断缺陷（semantic-cut defect）未被修复，压缩检查点位置保持不变。旧会话和旧投递载体保持原样，不支持继续恢复能力状态；Forge 不会迁移旧 JSONL 或改写历史摘要。不支持也不承诺 OMP（Oh My Pi）。

package/docs/zh-CN/reference/provider-support.md

@@ -24,7 +24,7 @@ Pi 和 Forge 在每次请求时都读取当前模型的 `compat` 标记：
 | API | 指令正文 | 工具变化 |
 |---|---|---|
 | `anthropic-messages` | 有标记时为 `role: "system"` 消息。Pi 会把它留到下一条 assistant 消息之前再发，因此不会插在 `tool_use` 和对应的 `tool_result` 之间；记录在用户消息之前的更新，实际会发在该用户消息之后。 | 需要 `supportsMidConvoToolChanges` 且至少一个初始工具。**Pi 1.0.1 起：** 请求级工具列表固定不变（初始工具加一个保留的 deferred 占位工具）；之后的工具直接以完整定义写在 `tool_addition` 块里（同名重定义会替换旧定义），用 `tool_removal` 撤下。**Pi 1.0.0 及更早：** 之后的工具带 `defer_loading` 追加到请求级列表，列表只增不减，同名重定义会退回发送完整列表。其他情况（包括会话开始时没有任何活动工具，例如 `tools.initial: []`）在请求级别发送当前列表。 |
-| `openai-responses`、`openai-codex-responses`、`azure-openai-responses` | 有标记时，在原位置发送 `developer` 消息（支持 developer 角色的推理模型）或 `system` 消息。 | 保留的历史中只有新增时，新工具在原位置加载；历史中任何位置出现过移除或同名重声明，这次请求就改为在请求级别发送完整的当前列表。 |
+| `openai-responses`、`openai-codex-responses`、`azure-openai-responses` | 有标记时，在原位置发送 `developer` 消息（支持 developer 角色的推理模型）或 `system` 消息。 | 保留的历史中只有新增时，新工具在原位置加载；历史中任何位置出现过移除或同名重声明，这次及后续请求就改为在请求级别发送完整的当前列表，直到不再保留该历史。 |
 | `openai-completions` | 有标记时，在原位置发送 `developer` 或 `system` 消息。 | 有 `supportsMidConvoToolAdditions` 时新增在原位置加载；移除和重声明改为发送完整的当前列表。 |
 | `mistral-conversations` | 有标记时，在原位置发送 `system` 消息。 | 始终在请求级别发送完整的当前列表。 |
 | Google Generative AI / Vertex | 始终折入 `systemInstruction`，没有会话中路径。 | 完整的当前列表。 |
@@ -58,7 +58,7 @@ Pi 和 Forge 在每次请求时都读取当前模型的 `compat` 标记：
 - **`anthropic/claude-sonnet-5`，fallback 路径：** 工具变化后的那次请求没有读到任何缓存，因为 Pi 改写了首条 system 提示词和工具列表。模型还对带标记的用户更新产生了怀疑，确认后才使用新工具。
 - **OpenAI Responses / Codex：** 之前的测试中，一次移除就改为发送完整工具列表，缓存读取降为 0；只有新增的请求保住了前缀。
 
-想让缓存稳定，优先选用带原生工具变化标记的模型；在 Responses 系列模型上，如果在意缓存复用，尽量不要在同一会话中移除工具。
+为尽量保留可缓存前缀，优先选用带原生工具变化标记的模型；不承诺缓存命中。在 OpenAI Responses/Completions 系列传输上，任何移除（包括关闭 Capability 导致的工具移除）都会因移除检测扫描转录历史，使该会话后续请求发送当前完整工具表。只要该历史仍保留，重新启用工具也不能恢复增量投递。Anthropic 原生 `tool_removal` 路径不受这种回退影响。
 
 ## 检查自己的环境
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zihanw/pi-forge",
-	"version": "0.5.8",
+	"version": "0.5.10",
 	"description": "Pi extension for editable context presets, one-shot agent profiles, tool policy, and request debugging.",
 	"repository": {
 		"type": "git",
@@ -45,10 +45,10 @@
 		]
 	},
 	"peerDependencies": {
-		"@earendil-works/pi-agent-core": ">=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.1.0",
-		"@earendil-works/pi-ai": ">=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.1.0",
-		"@earendil-works/pi-coding-agent": ">=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.1.0",
-		"@earendil-works/pi-tui": ">=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.1.0",
+		"@earendil-works/pi-agent-core": ">=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.5.0",
+		"@earendil-works/pi-ai": ">=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.5.0",
+		"@earendil-works/pi-coding-agent": ">=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.5.0",
+		"@earendil-works/pi-tui": ">=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.5.0",
 		"typebox": "*"
 	},
 	"peerDependenciesMeta": {
@@ -69,10 +69,10 @@
 		}
 	},
 	"devDependencies": {
-		"@earendil-works/pi-agent-core": "1.0.2",
-		"@earendil-works/pi-ai": "1.0.2",
-		"@earendil-works/pi-coding-agent": "1.0.2",
-		"@earendil-works/pi-tui": "1.0.2",
+		"@earendil-works/pi-agent-core": "1.4.0",
+		"@earendil-works/pi-ai": "1.4.0",
+		"@earendil-works/pi-coding-agent": "1.4.0",
+		"@earendil-works/pi-tui": "1.4.0",
 		"@types/node": "22.20.1",
 		"@vitejs/plugin-vue": "6.0.8",
 		"playwright-core": "1.61.1",