@zihanw/pi-forge 0.5.8 → 0.5.9

package/docs/development/setup.md

@@ -55,18 +55,18 @@ Set `CHROME_PATH` when Chrome/Chromium is outside a standard location. CI runs t
 
 ## Pi compatibility
 
-Pi-forge treats Pi-owned SDK packages (`pi-agent-core`, `pi-ai`, `pi-coding-agent`, `pi-tui`, and `typebox`) as host-provided optional peers, not private runtime dependencies. Published Forge 0.5.7 declared peer range `>=0.87.0 <0.88.0`. Forge 0.5.8 expands supported peers to the union:
+Pi-forge treats Pi-owned SDK packages (`pi-agent-core`, `pi-ai`, `pi-coding-agent`, `pi-tui`, and `typebox`) as host-provided optional peers, not private runtime dependencies. Published Forge 0.5.7 declared peer range `>=0.87.0 <0.88.0`. Forge 0.5.9 expands supported peers to the union:
 ```
->=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.1.0
+>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.4.0
 ```
-The repository dev SDK fixtures are updated to `1.0.2` with `typebox@1.3.27`. The minimum supported version remains `0.87.0`; there is no claim of dual 0.86 runtime support. The running host supplies one coherent SDK instance, avoiding duplicate packages and exact-version locks while expressing the actual API requirement. See the [Pi 1.0 compatibility guide](../guides/pi-1-compatibility.md).
+The repository dev SDK fixtures are updated to `1.3.0` with `typebox@1.3.27`. The minimum supported version remains `0.87.0`; there is no claim of dual 0.86 runtime support. The running host supplies one coherent SDK instance, avoiding duplicate packages and exact-version locks while expressing the actual API requirement. See the [Pi 1.0 compatibility guide](../guides/pi-1-compatibility.md).
 
 The repository keeps exact SDK versions as development/test fixtures for reproducibility. Exact fixtures do not constrain which Pi version may load the published extension.
 
 Release validation and smoke testing verify:
 
 - the documented minimum supported Pi version (`0.87.0`);
-- the current Pi version at release time (`1.0.2`), with earlier 1.0 patch releases (`1.0.0`, `1.0.1`) as compatibility lanes;
+- the current Pi version at release time (`1.3.0`), with earlier releases (`1.0.0`, `1.0.1`, `1.0.2`, `1.0.4`, `1.1.0`, `1.2.0`) as compatibility lanes;
 - an automated or scheduled probe of npm `latest`.
 
 Run packed installation tests against specific target versions using environment variables:
@@ -75,11 +75,11 @@ Run packed installation tests against specific target versions using environment
 # Verify packed install against pinned minimum (0.87.0):
 PI_TEST_VERSION=0.87.0 TYPEBOX_TEST_VERSION=1.3.7 npm run check:packed
 
-# Verify packed install against current Pi 1.0.2:
-PI_TEST_VERSION=1.0.2 TYPEBOX_TEST_VERSION=1.3.27 npm run check:packed
+# Verify packed install against current Pi 1.3.0:
+PI_TEST_VERSION=1.3.0 TYPEBOX_TEST_VERSION=1.3.27 npm run check:packed
 ```
 
-Ordinary Linux/macOS/Windows CI uses Pi 1.0.2; older supported versions, including minimum 0.87.0 and Pi 1.0.0/1.0.1, are explicit Linux compatibility lanes; passing CI on the exact release commit is a release gate (not claimed as already passed for an unreleased source patch).
+Ordinary Linux/macOS/Windows CI uses Pi 1.3.0; older supported versions, including minimum 0.87.0 and Pi 1.0.0/1.0.1/1.0.2/1.0.4/1.1.0/1.2.0, are explicit Linux compatibility lanes; passing CI on the exact release commit is a release gate (its result is not recorded in this document).
 
 Document the tested range separately from peer constraints. Pi-coupled experimental subagent capabilities must preflight against the actual host and fail closed with a precise compatibility diagnostic when required APIs are unavailable; ordinary stacks and profiles should remain usable.
 
@@ -91,3 +91,9 @@ Document the tested range separately from peer constraints. Pi-coupled experimen
 - `@zihanw/pi-subagent-runtime` owns execution lifecycle and fresh-process backends (a dependency of the optional package, not of the main package).
 
 See the [public API policy](../reference/public-api.md).
+
+### Coherent fixtures versus fresh consumers
+
+Compatibility CI pins the four SDKs and, for 1.x, codemode/MCP/telemetry/chord to the same exact version and asserts resolved versions. These are explicit coherent fixtures, not ordinary fresh consumer resolution. By default the packed check keeps normal npm resolution and verifies the installed four-SDK family; the ordinary 1.3.0 jobs (all three platforms) are the unconstrained normal-consumer gate. Compatibility lanes set `PI_TEST_COHERENT_UPSTREAM=1`, which also pins codemode/MCP/telemetry/chord to the host version inside the packed consumers and is printed in the log. This is required because fresh unconstrained installs of Pi 1.0.1–1.1.x now resolve their caret ranges to newer, incompatible upstream releases (observed 2026-10-20: Pi 1.1.0 + pi-codemode 1.3.0 fails with a missing `MCP_TYPESCRIPT_PREAMBLE` export) independently of Forge. Fixture success on those lanes says Forge works on that host family; it does not claim that a fresh unconstrained install of that old Pi works.
+
+Pi 1.3 pins its internal Pi dependencies exactly; normal 1.3 consumers resolve the four SDKs plus codemode/MCP/telemetry to 1.3.0 without a fixture overlay. Real-SDK regressions cover default/modifier transcript tool restoration, resumed Preset initial/allow/deny policy, Capability additions, and disabling a Preset back to the policy owner's saved startup baseline (with distinguishable external changes reconciled). This does not change tool authorization or enable every default-active extension tool on resume.

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

@@ -2,6 +2,28 @@
 
 [Documentation](../README.md) · [简体中文](../zh-CN/guides/pi-1-compatibility.md)
 
+## Forge 0.5.9: Pi 1.1 / 1.2 / 1.3
+
+Forge 0.5.9 pins development SDKs to **1.3.0** and expands the four optional SDK peers to:
+
+```text
+>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.4.0
+```
+
+This is not an implicit promise for Pi 1.4 or other 0.x hosts. Historical 0.87/0.99/1.0 CI lanes remain, including 1.0.2, with 1.0.4, 1.1.0 and 1.2.0 explicit; ordinary jobs use 1.3.0. Compatibility jobs assert the resolved family and explicitly pin 1.x codemode/MCP/telemetry/chord as coherent fixtures. Their packed consumers get the same pins through `PI_TEST_COHERENT_UPSTREAM=1`; ordinary packed checks (the 1.3.0 jobs) keep normal npm resolution. This matters because fresh unconstrained installs of Pi 1.0.1–1.1.x now pull newer, incompatible codemode/MCP releases through upstream carets (for example Pi 1.1.0 + pi-codemode 1.3.0 fails with a missing `MCP_TYPESCRIPT_PREAMBLE` export) independently of Forge. Fixture success means Forge works on that host family, not that a fresh unconstrained install of that old Pi works.
+
+Pi 1.2 emits `before_agent_start` for idle custom wakes (including Subagents completion notifications), with no `prompt`; startup is already busy (`isIdle() === false`). Forge resolves `runtime.lastUserMessage` once from the current branch's compaction-aware preview projection before compiling System blocks, using the existing latest non-empty user-content helper. No eligible content yields empty; custom content is not a user prompt. Existing preview rendering is retained (including `[image]` for image content). This is role-based history, not authenticated human identity. The snapshot survives tool followups until settlement. Each actual start, including custom starts, resets turn-frequency rewriting; busy steering does not invent a start or user message.
+
+Ordinary and legacy user events retain their authoritative expanded prompt, even empty/image-only. Older hosts that do not emit the custom-start event are not retrofitted with it. The tests characterize that host distinction rather than claiming 1.2 custom-start behavior on 1.1.
+
+**Known limitation on Pi 1.1 and earlier:** these hosts start idle custom wakes (for example a Subagents completion notification that wakes the parent) without any `before_agent_start`, so Forge never sees that run start. The wake request and its tool followups are sent without the Preset's System blocks; tool policy still applies. This is unchanged from 0.5.8 and was verified on Pi 1.1.0. Ordinary user turns and busy steering are not affected. If you rely on background completion wakes, use Pi 1.2 or later.
+
+Pi 1.3 keeps the custom-start/System contract. It additionally restores the transcript's active tool loadout on default/modifier-based session creation; explicit tool selections still override restoration. Forge recomputes the effective selection using its Preset (`tools.initial`, allow/deny) and active Capabilities, rather than trusting stale restored tools. Disabling a Preset restores the tool-policy owner's saved pre-policy startup baseline, reconciling distinguishable external changes; a reduced transcript loadout must not erase that saved baseline. No new enabled-membership execution restriction is introduced. Real-SDK persisted-session regressions cover these paths with offline faux streams.
+
+Pi 1.3's internal SDK/codemode/MCP/telemetry dependencies are exact pins. Normal 1.3 consumers therefore resolve the seven Pi packages to 1.3.0 without the historical fixture overlay; this does not retroactively fix older releases' caret-resolution drift.
+
+The 0.5.8 section below records the previous release's policy (peers through `<1.1.0`); it is kept as history and is not the current peer range.
+
 ## Forge 0.5.8 versus older packages
 
 This guide covers the **Forge 0.5.8** compatibility patch. Installing the older `@zihanw/pi-forge@0.5.7` does not install these changes: that artifact still declares Pi peers `>=0.87.0 <0.88.0`.
@@ -16,6 +38,16 @@ Minimum Pi remains 0.87.0. Development pins are Pi 1.0.2 and `typebox@1.3.27`. T
 
 This patch changes dependency/test coverage and documentation, **not** tool authorization, Capability ownership, usage aggregation, or personal configuration.
 
+## Unsupported-host boundaries
+
+Forge requires upstream Pi's `systemPromptOptions` and `context_with_system` contract. Forks such as oh-my-pi (OMP) remain unsupported; graceful missing-input handling is not OMP support or certification of a fork's tool permissions.
+
+- CLI preset/profile application checks command-only prompt APIs before changing selection or model. Ordinary lifecycle contexts need no command-only getter.
+- Fresh-session auto-profile model/thinking settings and preset/tool selection still apply early, potentially before first-turn prompt compatibility is observed. They are not deferred or automatically rolled back on later unsupported-input detection.
+- Missing required inputs trigger one warning per session, clear stale compilation captures, and latch off new preset/profile application and preset compilation/preview, including an already-open Web editor's Preview. This detection does **not** abort provider dispatch or automatically clear independently applied tool policy; Forge continues applying/checking its policy.
+- `/preset use none` (or `off`) explicitly disables the preset. A new session resets the latch and warning budget; tree navigation, compaction, and agent settlement do not. Fix the host contract before retrying in a new session.
+- Detection is not universal or guaranteed at startup. Valid options and successful `pi.on()` registration cannot prove that `context_with_system` will actually run; Forge does not infer hook support from registration alone.
+
 ## Native MCP: migrate exact names deliberately
 
 Pi 0.99.2+ normalizes native MCP names, for example `mcp__demo-server__ping` becomes `mcp__demo_server__ping`. Same-server tool collisions such as `a-b` and `a_b` receive hash suffixes; conflicting normalized server names are rejected.
@@ -64,9 +96,9 @@ Published subagents 0.5.3 does not support `tools.initial`. Its pending feature
 ```bash
 # Override both when testing a different host than the installed development 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.3.0 TYPEBOX_TEST_VERSION=1.3.27 npm run check:packed
 ```
 
 Without overrides, packed checks use the coherent installed SDK family and its declared TypeBox version, not a hardcoded historical pin. Both consumers use normal npm peer resolution and check the installed versions. An optional sibling, when present, uses its declared runtime dependency; this is not a test of an unreleased local runtime.
 
-Ordinary Linux/macOS/Windows CI uses pinned Pi 1.0.2; explicit compatibility lanes (0.87.0 through 1.0.1) and scheduled latest-Pi probes run on Linux. Exact-release CI remains a release gate, not a claim that this source patch has already passed remote or real-provider testing.
+Ordinary Linux/macOS/Windows CI uses pinned Pi 1.3.0; explicit compatibility lanes (0.87.0 through 1.2.0, including 1.0.2) and scheduled latest-Pi probes run on Linux. CI on the exact release commit remains a release gate; this document does not record its result or any real-provider testing.

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.9 supports `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.4.0` (dev SDK 1.3.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.
 
@@ -230,7 +230,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.9 supports `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.4.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.9 expands them to `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.4.0` (development SDK pinned to 1.3.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.9 supports `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.4.0`; dev SDK updated to 1.3.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/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,26 @@
 
 [中文文档](../README.md) · [English](../../guides/pi-1-compatibility.md)
 
+## 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 流覆盖这些路径；不引入新的 enabled-membership 执行权限限制。
+
+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 +36,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 后缀；服务器名规范化冲突会被拒绝。
@@ -64,9 +94,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.3.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.3.0；显式兼容（0.87.0 至 1.2.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.9 支持联合范围 `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.4.0`（开发 SDK 更新至 1.3.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`，因而配置不具备向下降级兼容性。
 
@@ -230,7 +230,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.9 支持 `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.4.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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zihanw/pi-forge",
-	"version": "0.5.8",
+	"version": "0.5.9",
 	"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.4.0",
+		"@earendil-works/pi-ai": ">=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.4.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.4.0",
+		"@earendil-works/pi-tui": ">=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.4.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.3.0",
+		"@earendil-works/pi-ai": "1.3.0",
+		"@earendil-works/pi-coding-agent": "1.3.0",
+		"@earendil-works/pi-tui": "1.3.0",
 		"@types/node": "22.20.1",
 		"@vitejs/plugin-vue": "6.0.8",
 		"playwright-core": "1.61.1",