@zihanw/pi-forge 0.5.6 → 0.5.8

package/docs/development/roadmap.md

@@ -4,9 +4,19 @@
 
 This file contains forward-looking product work only. Completed capability belongs in the [feature inventory](../reference/features.md), release history in the root [changelog](../../CHANGELOG.md), and completed investigation in the [design archive](../design/README.md).
 
-## Active 0.5.6: regression and UI closeout
+## Active 0.5.8: Pi host compatibility release preparation
 
-The patch preserves the leading SDK System header, protects Preset/Profile edits, preflights Capability conflicts before Preset changes, and corrects auto-profile diagnostics. The user accepted whole-row disabled styling and browser-local resizing of the Presets/Stack items panes. Focused browser regressions and the exact-commit full CI/packed-install gates in the [release process](release.md) close out this patch. No schema change, new history semantics, optional-package publication or installed-host upgrade is implied.
+Forge 0.5.8 aligns host peers, development pins, packed consumers and CI with Pi 1.0.x (tested 1.0.0–1.0.2) while preserving the Pi 0.87.x baseline and explicit 0.99.0–0.99.2 support. The only production source change adds Pi documentation pointers; tool-policy, Capability, model-API and usage semantics remain unchanged. See [compatibility and migration](../guides/pi-1-compatibility.md).
+
+Local release preparation is authorized; the user will review the change list and publish. The final release commit still requires all [release gates](release.md), including exact-commit remote CI. Optional/runtime features and any future exposure-policy redesign remain independent. Publishing does not authorize an installed-host upgrade or reload.
+
+## 0.5.7 Preview and scrolling (completed)
+
+0.5.7 delivered readable role-colored context, collapsible Tools groups, original-order / safe call-paired result views, historical tool JSON disclosure, search/reading-state retention and scroll reachability. See the [changelog](../../CHANGELOG.md) for the published UI release.
+
+## 0.5.6 regression and UI closeout (completed)
+
+0.5.6 delivered leading-System preservation, Preset/Profile edit protection, Capability conflict preflight, auto-profile diagnostics, whole-row disabled styling and browser-local pane resizing. See the [changelog](../../CHANGELOG.md) for the published patch history.
 
 ## 0.5.5 capability baseline (completed)
 
@@ -19,7 +29,7 @@ One active lane at a time:
 3. **Session observability & activity panel (implemented):** derived multi-capability state, actual selected tools, delivery status (`none`, `pending`, `prepared`), presentation indicators, and guarded human disable/reset; real SDK summarizer-input characterization.
 4. **Preset authorization & restricted Agent control (implemented):** live Preset binding schema (`capabilities`), opt-in `modelCallable: true`, and model-callable `forge_capability` tool with fixed list/status/enable/disable schema; per-call trust, binding identity, authorization, and tool policy checks; strict user-vs-agent ownership.
 5. **Capabilities library CRUD, Preset binding editor, and guarded human Web activation picker (delivered in functional source):** dedicated **Capabilities** surface for project/global capability CRUD with `sourceRevision` stale-save guards; dedicated peer Capability bindings editor with finite overrides and live source-effective preview; guarded human Web activation picker (`GET /api/capability-state/available`, `POST /api/capability-state/enable`) with pre-activation preview and session guard plus content fingerprint validation. Parent safeguards enforce raw source/revision coherence, external new bindings stale-save detection, and lifecycle/re-entry fences (`disposed`, `lifecycleRevision`, `sameContext`).
-6. **Main-package 0.5.5 release closeout:** The accepted UI and local full verification closed out on 2026-09-24 (`89c6ba2`); bilingual README B and reviewed continuous media are adopted. UI scope is frozen except for regressions/release blockers. The main package 0.5.5 was published; subsequent patches retain the exact-commit CI and packed-install gates in the [release process](release.md). No paid provider matrix is implied. The optional package and runtime have independent unfinished release work and are not a main-package gate. Repo dev SDK remains pinned to 0.87.0 with peer `>=0.87.0 <0.88.0` (no dual 0.86 support claim).
+6. **Main-package 0.5.5 release closeout:** The accepted UI and local full verification closed out on 2026-09-24 (`89c6ba2`); bilingual README B and reviewed continuous media are adopted. UI scope is frozen except for regressions/release blockers. The main package 0.5.5 was published; subsequent patches retain the exact-commit CI and packed-install gates in the [release process](release.md). No paid provider matrix is implied. The optional package and runtime have independent unfinished release work and are not a main-package gate. At that closeout the dev SDK was 0.87.0 with peer `>=0.87.0 <0.88.0`; the 0.5.8 host policy is documented in [Pi 1.0 compatibility](../guides/pi-1-compatibility.md).
 
 Existing README and optional Pet active-state changes are preserved. No host upgrade, reload or publication follows implicitly from local feature development. Foundation tests are not proof of live 0.5.5 behavior.
 

package/docs/development/setup.md

@@ -55,16 +55,32 @@ 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. The repository dev SDK is pinned to `0.87.0` and the peer requirement is `>=0.87.0 <0.88.0` for the four Pi SDK peers; `typebox` remains `*`. 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.
+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:
+```
+>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.1.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 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 should test:
+Release validation and smoke testing verify:
 
-- the documented minimum supported Pi version;
-- the current Pi version at release time;
+- 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;
 - an automated or scheduled probe of npm `latest`.
 
+Run packed installation tests against specific target versions using environment variables:
+
+```bash
+# 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
+```
+
+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).
+
 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.
 
 ## Package boundaries

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

@@ -0,0 +1,72 @@
+# Pi 1.0 compatibility
+
+[Documentation](../README.md) · [简体中文](../zh-CN/guides/pi-1-compatibility.md)
+
+## 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`.
+
+Forge 0.5.8 declares the following peer policy for the four Pi SDK packages:
+
+```text
+>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.1.0
+```
+
+Minimum Pi remains 0.87.0. Development pins are Pi 1.0.2 and `typebox@1.3.27`. The SDK packages and TypeBox remain host-provided optional peers, not private runtime dependencies. The `>=1.0.0 <1.1.0` range covers Pi 1.0 patch releases; 1.0.0, 1.0.1 and 1.0.2 were tested for this release, and a scheduled CI job tests the newest Pi. Other 0.x intermediate versions and Pi 1.1 or later are not implicitly supported.
+
+This patch changes dependency/test coverage and documentation, **not** tool authorization, Capability ownership, usage aggregation, or personal configuration.
+
+## 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.
+
+Check all exact names in allow/deny, initial, Capability add/remove, scripts and saved loadouts:
+
+- An unregistered Capability **add** is rejected. An old initial name may be omitted, and an old exact allow entry will not allow the new name.
+- **Old exact deny/remove names may simply stop matching the renamed tool.** Do not assume every stale name fails closed. Review restrictions as carefully as additions.
+- Inspect the live registered catalog after servers connect: use the Web editor's refreshed tool picker or extension API `pi.getAllTools()`. The active list alone omits inactive/deferred tools.
+- Explicitly confirm each old-to-new mapping, including collision hashes, before updating configurations. Forge does not guess aliases or apply blanket hyphen replacement.
+
+These rules concern **native MCP**, not third-party adapters such as `pi-mcp-adapter` 2.x. This patch does not migrate adapter configuration or rewrite existing resources.
+
+## Discovery and delayed registration
+
+Default native MCP servers now connect in the background without blocking the first prompt; `direct` exposure has different startup behavior. Default tools are registered with deferred exposure, omitted from codemode's description, and discovered using `searchTools()` / `describeNamespace()`. Discovery does not grant a Forge Capability or override its policy.
+
+Pi 1.0 improves deferred-tool restoration on resume/reload. Forge still requires Capability additions to be registered before activation; when a server is late, wait for registration and retry the intended action. Reload alone is not a guaranteed remedy. Explicit policy sync can replace a restored host loadout, so do not assume pending tools must always reactivate. Full slow-MCP resume/reload behavior needs integration validation, not just catalog-mock tests.
+
+Forge preserves foreign System sections such as `mcp_servers`, including updates and removals. Upstream section updates can change later prompts; this is not a cache-hit guarantee.
+
+## Anthropic tool changes in Pi 1.0.1+
+
+On Anthropic models with native mid-conversation tool changes, Pi 1.0.1 keeps the request-level tool list fixed at the initial tools plus a reserved placeholder and defines every later tool inline in a `tool_addition` block. Enabling or disabling a Capability therefore no longer rewrites the request-level tool list, and a same-name redefinition no longer forces the full list. The native path still needs at least one initial tool: a session that starts with no active tools (for example a Preset with `tools.initial: []`) sends the full current list at request level on every tool change. Forge does not change this behavior, and no new live cache measurements were taken for 1.0.1+. See [provider support](../reference/provider-support.md).
+
+## Codemode boundaries remain unchanged
+
+Pi 1.0 throws when scripts read missing `tools` properties. Use `"name" in tools`, not `typeof tools.name`, to test existence.
+
+`tools.initial` is a default loadout, **not an enabled-membership execution gate**. Registered deferred/codemode tools permitted by the Preset can remain callable through nested codemode even when omitted from initial or after their adding Capability is disabled. Preset allow **or** deny policy and active Capability removes still apply; direct calls also depend on the host's active loadout. This patch does not change those semantics or make discovery authorization-aware.
+
+`models.generateImages()` (new in 1.0) and `models.classify()` (since 0.99) call the session model registry, not `ctx.executeTool()` / `tool_call`. Disabling image tools does **not** disable these model APIs. Pi settings have no `models: false` toggle; the SDK factory `createCodemodeExtension({ models: false })` requires explicit programmatic extension assembly.
+
+Pi accounts for reported codemode model usage. Forge's cache display still separates assistant usage from explicit `details.forgeNestedUsage`; it does not newly aggregate arbitrary native tool/model usage. Do not add both receipts without deduplication.
+
+## TUI and optional packages
+
+Pi 1.0 defaults to fullscreen. To retain ordinary terminal scrollback, set `"tuiMode": "regular"` in Pi settings or use `pi --tui-mode regular`. This does not change Forge's Web UI.
+
+Removing the experimental agent-core harness does not remove the coding-agent `AgentSession` used by our companion runtime. `pi-durable` is still explicitly experimental; this patch does not adopt it or add cross-restart continuation.
+
+Published subagents 0.5.3 does not support `tools.initial`. Its pending feature release can include Pi 1.0 adaptation, but requires its own runtime artifact/floor, TypeBox peer cleanup, bwrap `/tmp` launcher fix, packed tests and approval. Main Forge releases independently; main+optional import smoke does not certify the pending continuation/background features. See [host-port compatibility](../reference/subagent-host-port.md#tool-selection-compatibility).
+
+## Verification
+
+```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
+```
+
+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.

package/docs/guides/web-editor.md

@@ -60,16 +60,32 @@ The resource header identifies the Preset being edited separately from whether i
 - **Policy:** Permission ceiling and default tools are separate cards. Literal/wildcard editing is advanced; skill-list visibility has its own section and is not an execution sandbox.
 - **Preview / Draft diff / Run diff:** Preview is a separate workspace toggle: opening, closing, or changing editor tabs preserves the current editing page. The boundary chevron widens the sidebar; wide mode offers separate shrink and focus buttons. Leaving focus restores the previous nonfocused layout and keeps the inspection tab, without replacing the draft. Choosing another editing section while focused reveals that editor and retains the dock. The panel initially uses the sidebar. Switching Preview, Draft diff, or Run diff changes only its content and preserves the current width and focus state; focused reading is entered explicitly. Narrow windows stack work areas instead of squeezing four columns; focused reading hides the editor until you return or choose an editing section. Draft diff compares draft compilation with the saved definition; Run diff compares captured provider-turn snapshots. Inspection itself does not send a model request or establish cache hits.
 
-Profile editing groups Provider/Model and Thinking/Preset together; immutable identity appears in the heading. Profile and Capability creation still explicitly choose ID and scope. The Advanced Preset tab places editable parameters before the collapsed extension reference catalog. Preview tool details are expandable; section statistics remain available on section-title tooltips.
+Profile editing groups Provider/Model and Thinking/Preset together; immutable identity appears in the heading. Profile and Capability creation still explicitly choose ID and scope. The Advanced Preset tab places editable parameters before the collapsed extension reference catalog. Preview tool details are expandable; section statistics remain available under **Source**.
 
 Contributed **Settings** pages auto-save and show pending/saving/saved/error feedback. Failed edits remain in the form. Presets, Capabilities, and Profiles retain their explicit save controls.
 
+### Reading Preview and tool results
+
+Preview and Current session use readable excerpts with teal user / blue assistant roles. **Tools** groups start expanded; individual calls and results start as single lines. Fold a group to keep just its call/result counts and explicit failures. Groups cover only uninterrupted tools belonging to one assistant message; intervening messages or instructions stay visible. Missing, conflicting or ambiguous call IDs are not guessed. A uniquely matched file result can show the filename from its actual call arguments.
+
+**Results → Original order** is the default. **Pair with calls** places uniquely associated returns beside their calls only within a safe continuous tool interval. Cross-message results and unassociated-result barriers remain in place. This is display pairing, not a timeline or claim about parallel execution; the position markers always refer to the original projection. These view controls do not modify the Preset, provider context or executable tools. Choices are local to the open inspector, not persisted resource settings.
+
+Search examines complete message text, roles, source labels, tool names/call IDs, named System section keys and historical declaration JSON. Matching groups, text and declarations open temporarily; clearing search restores prior disclosure choices and reading positions. **Full text** expands the inspection text; **Source** exposes provenance and existing text estimates. Named System sections distinguish setting, setting empty, and removal; historical tool declarations remain separate from currently selected tools. The existing estimates still describe the compiler's text projection, not full tool schemas, structured arguments or media.
+
+**Historical transcript tool declarations** keep each added tool collapsed to one line: name, an excerpt of its real description, and a count when the schema explicitly lists top-level properties. This is a declared-property count, not inferred arity through references/composites; an unknown schema does not mean zero arguments. Open a tool to inspect or copy its complete Preview declaration JSON (name, description and parameters when present). Removed declarations retain their names only; no missing schema is reconstructed. These historical records do not select executable tools.
+
+Editing within the same Preset keeps inspection choices and unchanged tool reading positions. While the new draft compiles, the previous preview is explicitly marked pending and its inspection controls are paused. A real resource switch still resets local inspection state. On short narrow screens the Preset shell scrolls as needed so headers cannot squeeze the editor/inspection dock to zero height.
+
+**Copy report** retains the compiler text report. Copy a tool row for its complete displayed parameters/output. Structured argument JSON is a representation of the compiled object, not raw provider-wire bytes; images and unsupported content parts have explicit placeholders. Text copying is not a complete multimodal export. Folding, pairing and excerpts do not reduce model context, token usage, or establish cache savings. Draft/Run diff and request invalidation retain their existing meanings.
+
 ### Inspecting a Capability's context impact
 
 The **Current session** workspace places capability controls and tools on the left, and the session projection on the right (stacked on narrow screens). It shows current effective tools and a short excerpt of each active instruction snapshot. A successful Enable/Disable/Reset in this browser also shows the observed tool additions/removals; this is not a persistent history. A Capability's configured tool adjustments are labeled separately: overlapping Capabilities can produce no net tool change.
 
 **Locate in context** keeps the controls visible and highlights related projected update blocks, scrolling to the latest match. Normal updates do not steal the reading position. The workspace inspects the **active saved Preset + current session capabilities**, not whichever Preset is being edited. The Preset editor still supports simultaneous editing and **Preview / Draft diff / Run diff**; switching workspaces preserves its draft, selection, inspection tab and width/focus.
 
+**After switching Presets:** if a turn ran under A and you then activate saved Preset B, this projection updates to B with the existing branch history and current capabilities, without sending a model request. Merely selecting/editing B leaves A active. Earlier A messages and historical declarations can still appear as history; that does not mean B failed to activate. This is a current composition preview, not the last sent request or an exact prediction of the next provider payload. Run diff retains captured requests; Payload shows the capture that was armed, not arbitrary past turns. Capture is at the provider hook and can precede later plugin shaping.
+
 Background status checks are quiet and do not reload the capabilities catalog or disable otherwise usable controls on each poll. Catalog discovery occurs on workspace entry, explicit refresh and relevant mutation follow-up. Returning invalidates late reads from a previous visit without discarding in-flight mutation receipts. Projection reads follow semantic state changes, rather than a second polling loop. During same-branch refresh a labeled previous projection remains visible; stale/untrusted or changed session/branch data is invalidated.
 
 Block numbers apply only to that preview. Native System sections and attributed user-fallback updates retain their actual roles; stopping a Capability does not erase its earlier updates. If no reliable match is visible, the inspector says so rather than guessing. This first iteration requires a trusted session and an active Preset; full event-history browsing is not included.
@@ -117,7 +133,7 @@ Saves, imports, forks, and deletes reload Preset state into the current Pi sessi
 
 ### Compatibility
 
-Presets configured with `tools.initial` require updated Forge. Older Forge versions may ignore `tools.initial` and revert to legacy selection behavior (selective allow selects catalog matches; unrestricted/deny retains or filters the session baseline) (not downgrade-compatible). These changes require Forge 0.5.5; the host requirement remains Pi `>=0.87.0 <0.88.0`.
+Presets configured with `tools.initial` require updated Forge. Older Forge versions may ignore `tools.initial` and revert to legacy selection behavior (selective allow selects catalog matches; unrestricted/deny retains or filters the session baseline) (not downgrade-compatible). These changes require Forge 0.5.5; the minimum host requirement remains Pi 0.87.0 (published 0.5.7 peer range was `>=0.87.0 <0.88.0`; unreleased source compatibility supports `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.1.0`; see [Pi 1.0 compatibility guide](pi-1-compatibility.md)).
 
 ## Agent-profile workspace
 

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:** Pi `>=0.87.0 <0.88.0` (repository dev SDK pinned to `0.87.0`, peer range `>=0.87.0 <0.88.0`; min SDK 0.87 unchanged; no dual 0.86 runtime support claim). Capabilities require Forge 0.5.5.
+- **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).
 - **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 0.87 required:** Upstream Pi `>=0.87.0 <0.88.0` is required. 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.
+- **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).
 - **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.
@@ -253,7 +253,7 @@ The 0.5.5 core functional implementation is delivered in source across all plann
 - Parent safeguards: raw source/revision coherence, external new bindings stale-save detection, and lifecycle/re-entry fences.
 - Tool patch schema supports `add` and `remove` only; candidate `only`/allowlist is not implemented.
 - Conservative provider-managed prompt cache warnings; compatible Codex additional-tool delivery can preserve prefixes for new names when retained history has no removals/redeclarations; tool removal/redeclaration falls back to the current full tool list (not guaranteed cache hits); no automatic legacy migration or old summary rewrites; no Pi split patch; no claims of forced prompt, warming, auto overflow, or remote acceptance.
-- Local build and full Node/browser/package verification passed at the 2026-09-24 UI closeout (commit `89c6ba2`); this is a dated local result, not current CI evidence, remote-provider acceptance, or npm publication. Pi `>=0.87.0 <0.88.0` remains required; optional runtime/subagent integration and its producer work are independently tested and released.
+- Local build and full Node/browser/package verification passed at the 2026-09-24 UI closeout (commit `89c6ba2`); this is a dated local result, not current CI evidence, remote-provider acceptance, or npm publication. That historical check used Pi `>=0.87.0 <0.88.0`; current source host policy is in the [compatibility guide](../guides/pi-1-compatibility.md). Optional runtime/subagent integration and its producer work are independently tested and released.
 
 
 Filesystem safety checks reject symlinks present when checked. They are not isolation against another local process racing directory replacement; revision checks likewise are not cross-process locking. Do not use resource mutation against an adversarial shared filesystem.

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+. The four Pi SDK packages are host-provided optional peers at `>=0.87.0 <0.88.0`; `typebox` is an optional wildcard peer. Exact repository versions are reproducible development/test fixtures rather than runtime constraints.
+- 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).
 - 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: Pi `>=0.87.0 <0.88.0` (repository dev SDK pinned to `0.87.0`, peer range `>=0.87.0 <0.88.0`; no dual 0.86 runtime support claim).
+- 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).
 - 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

@@ -23,7 +23,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`, at least one initial tool, and no same-name redefinition: initial tools stay first, later tools are appended with `defer_loading`, and changes are `tool_addition` / `tool_removal` blocks. The request-level list only grows. Otherwise: the current list at request level. |
+| `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-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. |

package/docs/reference/stack-schema.md

@@ -127,7 +127,7 @@ The `tools` policy optionally accepts an `initial` list:
 - **Ceiling enforcement:** The `allow`/`deny` ceiling remains authoritative and exclusive. Initial tools must fall within permitted bounds: listing a tool that is blocked by allow/deny produces a validation error.
 - **Extension and mod tools:** Dynamically registered extension tools are allowed by default if they satisfy the allow/deny policy, but when `initial` is specified, they remain registered and inactive until explicitly added by `initial`, by an active capability, or through runtime tooling.
 - **Preset baseline behavior:** Configured initial tools serve as the active base for as long as the preset remains active—not a one-time reset per turn. Calling `/capability disable` or `/capability reset` returns the session to the preset defaults (plus any remaining active capabilities). Disabling restores the reconciled session baseline; switching recomputes under the new Preset and remaining unbound capabilities.
-- **Compatibility:** Stacks declaring `tools.initial` require Forge 0.5.5 or newer. Older Forge versions may ignore `tools.initial` and revert to legacy selection behavior (selective allow selects catalog matches; unrestricted/deny retains or filters the session baseline), so the field is not downgrade-compatible. The host requirement remains Pi `>=0.87.0 <0.88.0`.
+- **Compatibility:** Stacks declaring `tools.initial` require Forge 0.5.5 or newer. Older Forge versions may ignore `tools.initial` and revert to legacy selection behavior (selective allow selects catalog matches; unrestricted/deny retains or filters the session baseline), so the field is not downgrade-compatible. The minimum host requirement remains Pi 0.87.0 (published 0.5.7 peer range was `>=0.87.0 <0.88.0`; unreleased source compatibility supports `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.1.0`; see [Pi 1.0 compatibility guide](../guides/pi-1-compatibility.md)).
 
 Tool policy changes Pi's active tool list, is reasserted before input/turns, and has a tool-call guard. It preserves external additions in the restorable baseline and restores that baseline when policy no longer applies or the extension shuts down.
 

package/docs/zh-CN/README.md

@@ -12,6 +12,7 @@
 
 - [Web 编辑器](guides/web-editor.md)
 - [迁移到 0.5](guides/migrating-to-0.5.md)
+- [Pi 1.0 兼容指南](guides/pi-1-compatibility.md)
 - [实验性前台 delegation](guides/delegation.md)：启用前请先阅读安全边界。
 - [预设使用场景（英文）](../guides/use-cases.md)
 

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

@@ -0,0 +1,72 @@
+# Pi 1.0 兼容说明
+
+[中文文档](../README.md) · [English](../../guides/pi-1-compatibility.md)
+
+## Forge 0.5.8 与旧版本
+
+本指南介绍 **Forge 0.5.8** 兼容补丁。安装旧版 `@zihanw/pi-forge@0.5.7` 不会获得这些改动；该 artifact 的 Pi peer 范围仍为 `>=0.87.0 <0.88.0`。
+
+Forge 0.5.8 为四个 Pi SDK 包声明的 peer 策略为：
+
+```text
+>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.1.0
+```
+
+最低 Pi 保持 0.87.0。开发依赖固定为 Pi 1.0.2 和 `typebox@1.3.27`。SDK 和 TypeBox 仍为宿主提供的可选 peer，不私装运行时副本；`>=1.0.0 <1.1.0` 覆盖 Pi 1.0 的补丁版本；本次发布实测 1.0.0、1.0.1、1.0.2，CI 定时任务会测试最新 Pi。不自动承诺其他 0.x 中间版本或 Pi 1.1 及以后版本。
+
+本补丁只调整依赖、测试覆盖与文档，**不改变**工具授权、Capability 所有权、用量汇总或个人配置。
+
+## Native MCP：逐项确认精确名称迁移
+
+Pi 0.99.2+ 规范化 native MCP 名称，例如 `mcp__demo-server__ping` 改为 `mcp__demo_server__ping`。同一服务器内 `a-b` 与 `a_b` 等工具名冲突会添加 hash 后缀；服务器名规范化冲突会被拒绝。
+
+请检查 allow/deny、initial、Capability add/remove、脚本和已保存 loadout 中的精确名称：
+
+- 未注册的 Capability **add** 会被拒绝。旧 initial 名称可能被省略，旧精确 allow 项不会放行新名称。
+- **旧的精确 deny/remove 名称可能只是匹配不到更名后的工具。** 不能把所有旧名称都当成 fail-closed；限制项和添加项一样需要检查。
+- 等服务器连接后，查看 Web 编辑器刷新后的工具选择器，或扩展 API `pi.getAllTools()` 返回的注册目录。仅查看 active 列表会漏掉 inactive/deferred 工具。
+- 人工确认每个 old→new 映射，包括碰撞 hash，再更新配置。Forge 不猜测别名，也不全局替换连字符。
+
+这些规则针对 **native MCP**，不是 `pi-mcp-adapter` 2.x 等第三方 adapter。本补丁不迁移 adapter 配置或改写现有资源。
+
+## Discovery 与延迟注册
+
+默认 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 测试冒充。
+
+Forge 保留 `mcp_servers` 等外来 System section，包括更新和删除。上游 section 更新可能改变后续 prompt，不保证 cache 命中。
+
+## Pi 1.0.1 起的 Anthropic 工具变化
+
+在支持原生中途改工具的 Anthropic 模型上，Pi 1.0.1 起请求级工具列表固定为初始工具加一个保留占位工具，之后的每个工具都直接以完整定义写在 `tool_addition` 块里。因此启用或停用 Capability 不再改写请求级工具列表，同名重定义也不再强制发送完整列表。原生路径仍需要至少一个初始工具：会话开始时没有任何活动工具（例如 `tools.initial: []` 的预设）时，每次工具变化都会在请求级别发送当前完整列表。Forge 不改变这一行为，也没有针对 1.0.1 起重新做真实缓存实测。详见 [Provider 支持](../reference/provider-support.md)。
+
+## Codemode 边界保持原样
+
+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 自动按授权过滤。
+
+`models.generateImages()`（1.0 新增）和 `models.classify()`（0.99 已有）直接调用会话 model registry，不经过 `ctx.executeTool()` / `tool_call`。关闭生图工具**不等于**关闭模型 API。Pi settings 没有 `models: false` 开关；SDK factory `createCodemodeExtension({ models: false })` 需要明确的编程式插件装配。
+
+Pi 会将 codemode 模型返回的用量计入总账。Forge cache 面板仍分别展示 assistant 用量与显式 `details.forgeNestedUsage`，没有新增任意 native tool/model usage 汇总；不能把两份回执直接重复加总。
+
+## TUI 与配套包
+
+Pi 1.0 默认 fullscreen。要保留普通终端 scrollback，可在 Pi settings 中设置 `"tuiMode": "regular"`，或运行 `pi --tui-mode regular`。这不改变 Forge WebUI。
+
+agent-core 实验 harness 的移除，不等于我们配套 runtime 使用的 coding-agent `AgentSession` 被移除。`pi-durable` 仍明确标为实验性；本补丁不接入它，也不新增跨重启 continue。
+
+已发布的 subagents 0.5.3 不支持 `tools.initial`。尚未发布的新功能版本可以合入 Pi 1.0 适配，但仍需独立完成 runtime artifact/floor、TypeBox peer 整理、bwrap `/tmp` 启动器修复、packed 验收与发布授权。主 Forge 独立发布；main+optional 的 import smoke 不等于待发布 continue/background 功能已验收。见 [host-port 兼容说明](../../reference/subagent-host-port.md#tool-selection-compatibility)。
+
+## 验证
+
+```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
+```
+
+不指定时，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 验收。

package/docs/zh-CN/guides/web-editor.md

@@ -48,16 +48,32 @@
 - **策略：** 许可上限与默认工具分成两张卡；字面量／通配符输入收在高级区，技能列表可见性另列，不能当作执行沙箱。
 - **预览／草稿差异／运行差异：** 预览是独立工作区开关，开关或切换编辑页签都保留当前编辑页。边界尖角把侧栏加宽；加宽时分别提供“收窄”和“专注”两个按钮，退出专注恢复之前的非专注布局并保留检查页签，不替换草稿。专注时点击其他编辑页签会露出编辑区并保留预览。面板首次默认侧栏。切换预览、草稿差异或运行差异时只切换内容，保留当前宽度和专注状态；专注阅读需手动进入。窄窗口改为上下布局，避免硬挤四列；专注阅读时暂时隐藏编辑区，返回或选择编辑页签后恢复。草稿差异比较草稿编译结果与已保存定义；运行差异比较捕获的提供商轮次快照。查看本身不请求模型，也不证明缓存命中。
 
-Profile 编辑按 Provider／Model、Thinking／Preset 分组，不可变身份在标题处显示；Profile 与 Capability 创建时仍明确选择 ID 与作用域。预设高级页把可编辑参数放在折叠的扩展参考目录之前。预览工具详情按需展开，段落统计可在标题提示中查看。
+Profile 编辑按 Provider／Model、Thinking／Preset 分组，不可变身份在标题处显示；Profile 与 Capability 创建时仍明确选择 ID 与作用域。预设高级页把可编辑参数放在折叠的扩展参考目录之前。预览工具详情按需展开，段落统计可在**来源**中查看。
 
 插件贡献的**设置**页自动保存，并反馈待保存／保存中／已保存／失败；保存失败的编辑会留在表单。预设、能力与 Profile 仍使用显式保存。
 
+### 阅读 Preview 与工具返回
+
+预览和当前会话使用可读正文摘录，user 青色、assistant 蓝色。琥珀色 **Tools** 组默认展开，组内调用／返回默认单行。收起整组后仍显示调用、返回与明确失败的数量。工具组只覆盖同一助手消息所属的连续工具区间，不隐藏中间的用户消息或指令；缺失、冲突或不唯一的 call ID 不会被猜测配对。唯一匹配的文件返回可显示真实调用参数里的文件名。
+
+**工具返回 → 原始顺序**是默认选项；**按调用配对**仅在安全的连续工具区间内，将唯一关联的返回放到调用旁边，不跨消息或无关联返回的屏障移动。这是展示方式，不是时间线，也不声称工具并行执行；位置编号始终来自原始投影。切换不改预设、提供商上下文或可执行工具，选择仅属于当前打开的检查区，不写入资源配置。
+
+搜索检查完整消息正文、角色、来源标签、工具名／call ID、命名 System 分段的键以及历史声明 JSON；临时展开匹配组、正文与声明，清空后恢复原折叠选择和阅读位置。**全文**展开检查文本，**来源**显示归属及既有文本估算。System 的设置、设空、删除仍明确区分，历史工具声明不混同当前生效工具。现有估算仍针对编译器文本投影，不含完整工具 schema、结构化参数或媒体。
+
+**历史转录工具声明**中，每个新增工具默认折叠成一行：工具名、真实描述摘录，以及 schema 明确列出顶层 properties 时的已声明参数数。它不推断引用／组合 schema 的总参数量；未知不等于零。点开后查看或复制完整预览声明 JSON（有值时包含 name、description、parameters）。移除声明仍只显示已知工具名，不重建不存在的 schema；历史记录不决定当前可执行工具。
+
+同一预设内编辑时，检查选项和未改变的工具阅读位置会保留。新草稿编译期间，上次预览会明确标为待更新，并暂停其检查控件；真正切换资源仍重置局部检查状态。矮窄屏幕下预设工作区可内部滚动，不让标头把编辑／检查区域挤成零高。
+
+**复制报告**保留编译器文本报告；完整显示的工具参数／输出请复制对应工具行。参数 JSON 表示已编译的结构化对象，不是提供商 wire 原始字节；图片及不支持的内容块显示明确占位符，文本复制不等于完整多模态导出。折叠、配对、摘录不会减少模型上下文或 token，也不证明缓存节省；草稿／运行差异与请求失效机制保持原有含义。
+
 ### 检查能力对上下文的影响
 
 **当前会话**工作区左侧是能力与工具控制，右侧是会话投影，窄屏上下排列。当前生效工具和活动指令摘要直接可见。在本页面成功启用、停用或重置后，还显示操作前后实际观测到的工具增减；这不是持久历史。能力**配置的工具调整**另行标注：多个能力重叠作用时，实际工具可能完全不变。
 
 点击**在上下文中定位**，控制区保持可见，右侧高亮关联更新并滚到最近匹配；普通更新不抢阅读位置。这里检查的是**已启用的已保存预设＋当前会话能力**，不是编辑器选中的任意预设。原预设编辑页仍能一边编辑，一边查看**预览／草稿差异／运行差异**；跨工作区保留草稿、选择、检查页签及宽度／专注状态。
 
+**一轮结束后切换预设：**如果这一轮用 A，随后真正启用已保存预设 B，投影会更新为 B 加既有分支历史与当前能力，不必先发一次模型请求；只选中／编辑 B 则仍使用 A。历史里保留 A 的旧消息／工具声明，不代表 B 未生效。这里是当前组成预览，不是上一回已发送请求，也不保证逐字等于下一回 provider payload。运行差异保留已捕获请求；Payload 展示此前已开启捕获的那次，不会追溯任意过去轮次。捕获发生在 provider hook，后续插件仍可能修改最终发送内容。
+
 后台状态检查静默进行，不再每轮读取能力目录或让可用控件闪成禁用态。目录在进入工作区、主动刷新及相关操作后读取；返回时废弃上一轮迟到读取，但不丢弃正在进行的写操作回执。投影由状态的实际变化驱动，不另开轮询；同分支刷新暂保留并明确标注上次投影，过期／不可信或会话／分支切换时使旧结果失效。
 
 块序号只对该次预览有效。原生 System 分段与归属明确的 user fallback 保留实际角色；停用不会抹去此前的更新。没有可靠匹配时会明确提示，不猜测位置。第一版要求可信会话与已启用预设，尚不提供完整的启停事件历史浏览。
@@ -103,7 +119,7 @@ Profile 编辑按 Provider／Model、Thinking／Preset 分组，不可变身份
 
 ### 兼容性说明
 
-使用 `tools.initial` 的预设需要新版 Forge 支持。旧版 Forge 可能忽略 `tools.initial` 并恢复旧选择逻辑（选择性 allow 匹配目录，不限/deny 保留或过滤会话基线）（不支持向下降级兼容）。这些变化需要 Forge 0.5.5；宿主要求保持 Pi `>=0.87.0 <0.88.0` 不变。
+使用 `tools.initial` 的预设需要新版 Forge 支持。旧版 Forge 可能忽略 `tools.initial` 并恢复旧选择逻辑（选择性 allow 匹配目录，不限/deny 保留或过滤会话基线）（不支持向下降级兼容）。这些变化需要 Forge 0.5.5；最低宿主要求保持 Pi 0.87.0 不变（已发布 0.5.7 的 peer 范围为 `>=0.87.0 <0.88.0`；未发布的源码兼容补丁支持 `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.1.0`；详见 [Pi 1.0 兼容指南](pi-1-compatibility.md)）。
 
 ## Agent profile 工作区
 

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

@@ -6,7 +6,7 @@ Pi-forge 引入了能力（Capabilities）：会话级动态提示词指令与
 
 ## 环境要求与安装
 
-- **宿主版本：** Pi `>=0.87.0 <0.88.0`（仓库开发 SDK 固定为 `0.87.0`，peer 范围为 `>=0.87.0 <0.88.0`；最低 SDK 0.87 保持不变；不声称对 0.86 的双重运行时支持）。能力功能需要 Forge 0.5.5。
+- **宿主版本：** 最低支持 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)。
 - **项目信任：** 激活能力、预设绑定或添加手动指令需要项目处于受信任状态（`isProjectTrusted()`）。
 - **兼容性限制：** 包含 `tools.initial` 的配置需要新版 Forge 支持；旧版 Forge 会忽略 `initial`，因而配置不具备向下降级兼容性。
 
@@ -230,7 +230,7 @@ Forge 在每次发起模型请求时通过两阶段拼装动态投影能力增
 
 ## 兼容性与安全边界
 
-- **要求上游 Pi 0.87：** 必须使用上游 Pi `>=0.87.0 <0.88.0`。不提供对 0.86 的双重运行时支持。之前在 `context` hook 中操作或读取完整 System 消息的第三方扩展必须迁移到 `context_with_system` 完整 hook。
+- **要求上游 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)。
 - **`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）。
@@ -253,7 +253,7 @@ Forge 在每次发起模型请求时通过两阶段拼装动态投影能力增
 - Parent 核心防护：源版本一致性保障、外部新增绑定防脏写检测、生命周期与重入安全围栏。
 - 工具补丁仅支持 `add` 与 `remove`；候选的 `only`/allowlist 未实现。
 - 提供保守的 Provider 托管与缓存预警；兼容的 Codex 传输在保留历史没有移除/重复声明时可追加全新工具以保留前缀（不保证缓存命中）；移除/同名重加回退全量当前工具表；不进行自动旧数据迁移，不重写历史摘要；无 Pi split patch；不声称 forceprompt、warming、autooverflow 或远程模型验收保证。
-- 2026-09-24 UI 收口时（提交 `89c6ba2`）本地构建、完整 Node／浏览器／打包验证已通过；这是有日期的本地结果，不是当前 CI 证据、远端提供商验收或 npm 已发布的证明。宿主仍要求 Pi `>=0.87.0 <0.88.0`；可选 runtime／subagent 集成及其生成者接入工作独立测试和发布。
+- 2026-09-24 UI 收口时（提交 `89c6ba2`）本地构建、完整 Node／浏览器／打包验证已通过；这是有日期的本地结果，不是当前 CI 证据、远端提供商验收或 npm 已发布的证明。该历史验收使用 Pi `>=0.87.0 <0.88.0`；当前源码宿主策略见[兼容说明](../guides/pi-1-compatibility.md)。可选 runtime／subagent 集成及其生成者接入工作独立测试和发布。
 
 
 文件路径校验会拒绝检查时已存在的符号链接，但不能隔离另一个本地进程并发替换目录的攻击；源版本比较也不是跨进程锁。不要把资源编辑用于不可信进程可竞争修改的共享目录。

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

@@ -23,7 +23,7 @@ Pi 和 Forge 在每次请求时都读取当前模型的 `compat` 标记：
 
 | API | 指令正文 | 工具变化 |
 |---|---|---|
-| `anthropic-messages` | 有标记时为 `role: "system"` 消息。Pi 会把它留到下一条 assistant 消息之前再发，因此不会插在 `tool_use` 和对应的 `tool_result` 之间；记录在用户消息之前的更新，实际会发在该用户消息之后。 | 有 `supportsMidConvoToolChanges`、至少一个初始工具且没有同名重定义时：初始工具保持在最前，之后的工具带 `defer_loading` 追加，变化以 `tool_addition` / `tool_removal` 块表示，请求级工具列表只增不减。否则在请求级别发送当前列表。 |
+| `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-completions` | 有标记时，在原位置发送 `developer` 或 `system` 消息。 | 有 `supportsMidConvoToolAdditions` 时新增在原位置加载；移除和重声明改为发送完整的当前列表。 |
 | `mistral-conversations` | 有标记时，在原位置发送 `system` 消息。 | 始终在请求级别发送完整的当前列表。 |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zihanw/pi-forge",
-	"version": "0.5.6",
+	"version": "0.5.8",
 	"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",
-		"@earendil-works/pi-ai": ">=0.87.0 <0.88.0",
-		"@earendil-works/pi-coding-agent": ">=0.87.0 <0.88.0",
-		"@earendil-works/pi-tui": ">=0.87.0 <0.88.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.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",
 		"typebox": "*"
 	},
 	"peerDependenciesMeta": {
@@ -69,14 +69,14 @@
 		}
 	},
 	"devDependencies": {
-		"@earendil-works/pi-agent-core": "0.87.0",
-		"@earendil-works/pi-ai": "0.87.0",
-		"@earendil-works/pi-coding-agent": "0.87.0",
-		"@earendil-works/pi-tui": "0.87.0",
+		"@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",
 		"@types/node": "22.20.1",
 		"@vitejs/plugin-vue": "6.0.8",
 		"playwright-core": "1.61.1",
-		"typebox": "1.3.7",
+		"typebox": "1.3.27",
 		"typescript": "6.0.3",
 		"vite": "8.1.5",
 		"vue": "3.5.40",
@@ -89,7 +89,7 @@
 		"check:docs": "node scripts/check-docs.mjs",
 		"check:dist": "node scripts/check-dist.mjs",
 		"check:package": "node scripts/check-package.mjs",
-		"prepack": "npm run build",
+		"prepack": "npm run build && npm run check:package",
 		"typecheck": "tsc --noEmit && vue-tsc --noEmit -p tsconfig.web.json",
 		"test": "node --test tests/*.test.ts",
 		"test:browser": "node --test --test-concurrency=1 tests-browser/*.test.ts",
@@ -97,11 +97,12 @@
 		"check:packed": "node scripts/check-packed-install.mjs"
 	},
 	"files": [
-		"dist/",
-		"docs/",
-		"examples/",
-		"assets/readme/",
-		"assets/pi-forge-header-concept-1.png",
+		"dist/**/*.js",
+		"dist/**/*.d.ts",
+		"dist/**/*.map",
+		"docs/**/*.md",
+		"examples/**/*.json",
+		"examples/**/*.ts",
 		"README.md",
 		"README.zh-CN.md",
 		"CHANGELOG.md",