@zihanw/pi-forge 0.5.4 → 0.5.5

package/docs/design/pi-forge-system-update-design-notes.md

@@ -1,229 +1,157 @@
-# pi-forge `system_update` Design Notes
-
-**Status:** Current plan (revised 2026-09-12). Supersedes the 2026-09-10
-exploration draft, which assumed pi-forge would implement the full
-persistence/projection/transport stack itself. Upstream Pi has since started
-building the primitive natively, so pi-forge's scope shrinks to the
-workflow layer.
-
-**Target:** 0.5.5+, blocked on an upstream Pi redo (see §2).
-
----
-
-## 1. TL;DR — Current Plan
-
-`system_update` is a **session-timeline event**, not a mutation of the
-top-level system prompt. That core decision from the original draft survives.
-What changed is who builds what:
-
-- **Upstream Pi is building the primitive**: a first-class `SystemMessage`
-  (`role: "system"`) appended to the transcript, rendered natively on models
-  that support mid-conversation system messages and as a tagged user turn
-  elsewhere. Persistence, resume, compaction, and provider rendering are all
-  owned by the harness.
-- **pi-forge builds only the workflow layer**: an append-only event log, a
-  reducer over it, the `/system-update` command family, preset-declared
-  dormant instruction blocks, and a permission-gated agent tool.
-- **Integration is declarative**: pi-forge renders its active update set into
-  `systemPromptOptions.sections` and lets the harness diff engine emit the
-  deltas. pi-forge no longer returns a fully-compiled replacement string for
-  this path.
-
-Discarded from the original draft: the custom-entry + self-written projector
-design, the `custom_message` transport, the provider transport matrix, and
-the six-phase rollout. See §5 for why.
-
----
-
-## 2. Upstream Landscape (snapshot 2026-09-12)
-
-### 2.1 The PRs
-
-- **PR #9116** (`system-role` branch, pi-ai layer): adds `SystemMessage` to
-  the `Message` union. Appended to the transcript, never folded into
-  `Context.systemPrompt`. Persisted as ordinary message entries; compaction
-  cut points and summaries understand them (rendered as `[System]:` in
-  summaries); interactive mode hides them.
-- **PR #9117** (`system-tool-deltas` branch, stacked, coding-agent layer):
-  the first rendered prompt of a session becomes a stored **baseline**;
-  anything that changes afterwards is appended as a provider-neutral system
-  message delta. On resume/tree navigation the stored baseline is reinstated
-  so a resumed session sends byte-identical cached prefixes. After
-  compaction, the effective prompt folds into a fresh baseline at no extra
-  cost.
-
-**Both PRs were closed by the author on 2026-09-11 with "I will redo this."**
-Direction is alive; implementation is being redone; timeline unknown.
-Community testing (13-scenario harness, all green) flagged two design
-issues likely motivating the redo: ~10 KB per-prompt-entry session bloat
-from storing rendered baselines, and silent tool disappearance on
-non-supporting models across resume.
-
-### 2.2 Verified behavior of the PR branch (local clone: `~/programming/pi-pr9117`)
-
-Measured against the actual `system-tool-deltas` build:
-
-- `sections: Record<string, string>` on `systemPromptOptions` renders as
-  XML-wrapped blocks (`<name>\n...\n</name>`), diff-keyed as `section:name`.
-- `diffSystemPrompts` behavior matrix:
-  - identical pieces → `unchanged` (no cost)
-  - section added → update delta: "The following `<name>` system guidance
-    now applies: ..."
-  - section removed → retraction: "The previous `<name>` system guidance no
-    longer applies."
-  - section content changed → "The `<name>` system guidance has changed. The
-    following supersedes..."
-  - literals changed or `forceSystemPrompt` changed → `replace`
-    (deliberate full cache miss)
-- **`forceSystemPrompt` short-circuits everything**: when set, pieces are
-  only the forced prompt; sections are not rendered at all. Any extension
-  returning a full replacement string from `before_agent_start` gets this
-  path, and every content change is a full prefix miss.
-- **`customPrompt` is a value piece** (keyed `customPrompt`, diff-friendly)
-  and does NOT short-circuit sections. This is pi-forge's integration point
-  for `mode = replace` stacks.
-- Mid-run timing: the diff runs before every LLM request
-  (`agent-loop.ts`), including mid-tool-loop, so an agent tool that mutates
-  sections gets its delta delivered after the tool batch and before the next
-  inference. The tool-call adjacency problem from the original draft is
-  handled by the harness.
-- Fallback rendering for unsupported providers:
-  `<system_update>\n{text}\n</system_update>` as a user-role message
-  (`pi-ai/utils/system-messages.ts`); Gemini confirmed user-role.
-- Native support matrix (upstream compat flags): Anthropic Opus 4.8/5,
-  Fable 5/5.1, Mythos 5/5.1 get real system messages (Anthropic requires a
-  system message to directly precede an assistant turn; pending messages are
-  held). OpenAI transports get `developer`/`system` items. Everything else
-  gets the tagged user turn.
-- `BeforeAgentStartEventResult.message` only accepts `CustomMessage`
-  (customType/content/display/details) — there is **no imperative
-  append-SystemMessage extension API** in the PR as written. The declarative
-  sections path is the intended extension surface.
-- The PR branch itself had two TypeScript errors (`openrouter.ts`,
-  `xai.ts`) when we built it; dist artifacts were still produced.
-
-### 2.3 Trigger to resume this work
-
-When the redone PR appears: verify the sections/diff semantics survived the
-redo (re-run the §2.2 matrix), then wire pi-forge's workflow layer to it.
-If the redo removes the declarative sections surface, reassess; the escape
-hatch is splicing `SystemMessage` in the context hook (see §5).
-
----
-
-## 3. pi-forge Design (workflow layer)
-
-These decisions survive from the original draft and remain the plan.
-
-### 3.1 Event model
-
-- Updates are **append-only custom session entries**
-  (`pi-forge-system-update`, schemaVersion 1), written via the existing
-  `session-adapter.ts` pattern (`pi.appendEntry` / `getCurrentBranchEntries`).
-  Branch semantics come for free.
-- Entry payload: `{ updateId, op: "apply" | "revoke" | "reset", source,
-  presetId?, contentSnapshot, createdAt }`.
-- **Snapshot content, not file paths**: file-backed presets are rendered at
-  activation time and the rendered text is persisted. Editing a preset file
-  tomorrow must not alter yesterday's session.
-- Logical state is a **reducer view** over the branch's events, never
-  canonical mutable state. Powers `/system-update status`, badges, and
-  section rendering.
-- Revoke/reset are new events, never history rewrites. In practice the
-  harness retraction wording ("no longer applies") is generated for us once
-  the section disappears; the event log only records intent.
-
-### 3.2 Rendering (the declarative bridge)
-
-- The reducer's active set is rendered into
-  `systemPromptOptions.sections["pi-forge-update-<id>"]` during
-  `before_agent_start` (and picked up mid-run by the harness's per-request
-  diff).
-- pi-forge's stack compilation moves off the legacy "return one big string"
-  path: `mode = replace` stacks go into `systemPromptOptions.customPrompt`,
-  additive content into keyed `sections`. This is a prerequisite refactor,
-  and it upgrades cache behavior for the whole stack system, not just
-  updates.
-- Transport is not pi-forge's concern: native vs fallback rendering is the
-  harness's compatibility layer.
-
-### 3.3 Commands
-
-- `/system-update <text>` — apply a freeform update (auto-id `update-N`).
-- `/system-update status` — reducer view of active updates.
-- `/system-update reset` — deactivate all (new event, append-only).
-- 0.5.5+ with presets: `/system-update list|use <id>|off <id>`.
-- No command deletes history. None of these trigger an agent turn.
-
-### 3.4 Presets and the agent tool
-
-- Presets declare dormant runtime blocks:
-  `{ "systemUpdates": [{ "id", "name", "description", "modelCallable",
-  "content" | "file" }] }`.
-- The base system prompt carries only a compact inventory; full blocks load
-  on activation (lazy privileged prompt loading).
-- Agent-facing tool `forge_system_update({action, id})` references declared
-  preset IDs only. **No arbitrary file elevation, no arbitrary agent-provided
-  privileged text.** Repository content is untrusted; elevation requires an
-  explicit preset declaration.
-- Source-aware deactivation: the agent may only deactivate agent-activated
-  modes; the user may deactivate anything.
-- Mid-turn activation rides the harness's per-request diff — no
-  pending-commit machinery on our side.
-
-### 3.5 Compaction, resume, branching
-
-All owned by the harness under the new architecture: update sections are part
-of the effective prompt, folded into the post-compaction baseline; stored
-baseline is reinstated on resume; events live on the branch. pi-forge's only
-job is to re-derive the active set from the branch's event log on session
-start/branch switch (same restore pattern as the active-stack state today).
-
----
-
-## 4. Version Plan
-
-- **0.5.4 (done, pushed):** web editor fixes and visual work; prompt-cache
-  features — cache-impact warning on `/preset use` / `/profile use`
-  (common-prefix estimate + last-request cacheRead), and compile-time
-  diagnostics for cache-sensitive content (`{{time}}`, date slots with
-  `includeTime`, `{{date}}` info).
-- **0.5.5:** system update workflow layer per §3, gated on the upstream redo
-  landing in a released Pi. Build the upstream-touching code behind a small
-  isolated module so a redo API change rewrites one file, not the feature.
-
----
-
-## 5. Discarded Designs (recorded so we don't re-litigate)
-
-- **Custom entry + self-written projector** (original draft's main design):
-  required replicating Pi's session-entry→context translation rules
-  (compaction truncation, deferred-message filtering) to compute splice
-  positions, plus a compaction checkpoint synthesizer. Real maintenance
-  coupling to Pi internals. Killed by the upstream `SystemMessage`.
-- **`pi.sendMessage` custom_message transport**: zero projection code, but
-  `custom_message` entries evaporate at compaction (the compaction path
-  doesn't recognize them) and render only as user-role. Viable fallback if
-  the upstream redo dies entirely; otherwise obsolete.
-- **Provider transport matrix / native lowering in pi-forge**: the wire role
-  is the harness's compatibility layer. pi-forge stores semantics
-  (`op`, `presetId`) so a future transport change needs no data migration.
-- **Context-hook SystemMessage splicing**: possible once upstream keeps
-  `role: "system"` messages, but brings back per-request projection, position
-  mapping, and Anthropic placement-rule handling. Escape hatch only.
-
----
-
-## 6. Open Questions for the Redo
-
-1. Did sections survive the redo, and did their diff semantics change?
-2. Is there an imperative append path for extensions after all, or is
-   declarative sections still the only surface?
-3. How does the redo store baselines (the session-bloat feedback)?
-4. Does `customPrompt` remain a non-short-circuiting value piece?
-5. Timing: which Pi release carries it, and what's our minimum-version
-   dependency story for the feature?
-
-Community posture: when the redo PR opens, comment as a downstream consumer
-with the runtime-instruction-modes use case (do not file a new issue;
-feature-request issues get auto-closed while a PR is in flight).
+# Capabilities — accepted 0.5.5 design
+
+[Documentation](../README.md) · [Lean architecture](architecture-0.5.md) · [Roadmap](../development/roadmap.md)
+
+**Status:** implementation authorized, 2026-09-20; accepted 9/21 amendment incorporated. Functional source is delivered across all planned lanes: foundation codecs, human CLI core (`/capability`), plain metadata anchor projection, Web Session capabilities activity panel, live Preset bindings (`capabilities`) in dedicated peer Capability bindings tab with finite overrides and opt-in `modelCallable: true`, restricted model-callable Agent control (`forge_capability`), Web Capabilities surface CRUD with SDK-grouped tool picker and `sourceRevision` stale-save protection, custom default tools policy (`tools.initial`), guarded human Web activation picker (`GET /api/capability-state/available`, `POST /api/capability-state/enable`), and Pi 0.87 transcript/projection migration. Parent safeguards enforce raw source/revision coherence, external new-bindings stale-save protection, and lifecycle/re-entry fences (`disposed`, `lifecycleRevision`, `sameContext`). [Current reference](../reference/capabilities.md) states operational boundaries. Capabilities support `add`/`remove` only; candidate `only`/allowlist is not implemented. Parent build and full verification passed on Pi 0.87.0 (773 Node / 37 browser); development package version remains 0.5.4; release version bump decision pending between 0.5.5 or 0.6; repo dev SDK is pinned to `0.87.0` with peer range `>=0.87.0 <0.88.0` (no dual 0.86 support claim).
+
+This supersedes the [September 12 upstream-blocked proposal](archive/2026-09-12-system-update-design.md). Historical spike notes below reflect dated 0.86 exploration; current production architecture builds directly on Pi 0.87 APIs.
+
+## Ownership and bounded scope
+
+**Definitions are reusable; authorization belongs to Presets; active state belongs to Sessions.** Capabilities contain continuing collaboration/output guidance and optional tool selection changes. Skills remain the place for procedures, scripts and reference material.
+
+- Forge owns semantic events, activation snapshots, derived delivery anchors and request-only capability projection.
+- Pi owns ordinary transcript storage/branching, message protocols, provider encoding and actual tool execution. No fork or private `AgentSession` patches.
+- `ForgeWorkspace` remains the single resource-state owner. Existing codecs/repositories/catalogs are reused. The capability reducer is a pure view, not a second mutable workspace.
+- `tool-policy-runtime` remains the only Forge owner of executable tool selection. Text saying a tool is disabled is not enforcement.
+- CLI, restricted Agent tool and Web UI share one application service. No dynamic control-tool schema, new registry/framework/package entry point, arbitrary JSON Patch, inheritance chain, capability dependencies, automatic resource bundling, or general undo/redo.
+
+## Evidence behind the architecture
+
+An isolated Pi 0.86 `AgentSession`/extension-runner spike used fake models/tools and intercepted adapter payload assembly; no provider HTTP was sent by that harness. Nineteen assertions and a separate smoke passed, including assertions that intentionally reproduce integration failures. They are not nineteen production features passing.
+
+1. Keeping and mutating `before_agent_start.systemPromptOptions.sections` across a tool loop did not reliably synchronize later changes: the expected text sequence off/on/off became off/on/on while tools restored correctly. The command options getter was not a live-run setter.
+2. Returning Forge's current full `systemPrompt` invokes Pi's forced request projection after context hooks; it suppresses later native system updates. `customPrompt` is not an exact replacement because the cwd contribution remains.
+3. A Forge-owned marker/context projector worked in the sampled repeated toggle, native/user/native switch, branch/JSON reconstruction and manual-compaction scenarios. Those samples do not establish production crash recovery, automatic compaction, concurrency, old-Preset compatibility or tool-baseline recovery.
+4. `systemPromptOptions.sections` is a prompt-building input; `SystemMessage.sections` is still useful as a native request representation. Failure of the tested thin bridge does not prove every upstream integration impossible.
+5. `sendMessage` steering with explicit `triggerTurn:false` did not enter the next request in the tested live loop. Omitting it worked while streaming and did not start inference in the tested idle command. Context-hook exceptions alone are swallowed; explicit abort behavior must be accounted for.
+
+The implemented request-base bridge preserves compiled replacement strings while retaining foreign named sections and tool declarations. Built-in base text and selected-tool macros refresh when the executable set changes.
+
+**Production architecture:** management completely avoids transcript `sendMessage` and `custom_message` carriers, preventing dialogue contamination and spurious model turns. Under Pi 0.87, standard `context` hooks intentionally exclude System messages; Forge moves the entire compiler, base prompt replacement, and capability projection pipeline to `context_with_system` without an internal two-phase split. Delivery is anchored using plain `custom` session entries under the same delivery type (`pi-forge-capability-delivery`) carrying strictly cursor-only metadata (`{ schemaVersion: 1, throughEventId: string }`).
+
+- **Anchor persistence points:**
+  - **Idle:** persisted immediately upon `/capability` execution or synchronization.
+  - **Running session:** safely deferred while a tool loop is busy; anchors are never inserted between an in-flight tool call and its matching result.
+  - **On `agent_end`:** uncommitted pending anchors are committed after the assistant's final response when no Forge context failure or incomplete batch remains, before the next user turn.
+  - **Cycle reset on `agent_settled`:** while `agent_end` commits anchors, compile cycles and the busy fence reset only on `agent_settled`. This ensures `agent_before_settle` continuations preserve compiled Preset inputs and active capabilities across low-level runs.
+- **Context assembly via canonical projection:**
+  - Runtime, Preview, and anchor helpers build against Pi 0.87's `buildSessionProjection` (handling `context_edit` omissions, replacements, and `sourceEntry`). Raw session history on disk is never modified.
+  - `prepareCapabilityMessages` materializes before Preset compilation plain metadata anchors into ephemeral in-memory markers at their exact ordinal positions, verifying a unique ordered alignment against the canonical session projection.
+  - Incoming SDK leading System prompts always remain first; Forge's own prefix plain metadata anchors are inserted after it.
+  - `projectCapabilityMessages` then projects active capability deltas into native request-only `SystemMessage.sections` or fallback attributed timeline user messages.
+- **Decoupled UI notification:** UI status notifications (`ctx.ui.setStatus` and Web activity panel) are completely independent and never enqueue turns to the model.
+
+Preceding extension message rewrites (modifying messages in context hooks) are a legal and valid Pi SDK capability. However, Forge's anchor materialization requires a unique ordered alignment with canonical session entries. Content/protocol rewrites, inserted messages, non-custom omissions and ambiguous custom-message omissions fail closed. Prior full-System context extensions must move to `context_with_system`; `before_agent_start` forced System prompt injection continues to execute later in Pi's lifecycle; and final request arbitrary preceding rewrites still fail closed. Users may adjust conflicting extension order or extension behavior, but this is an operational suggestion only; Forge does not guarantee post-extension rewrite safety, nor can it guarantee generic plugin compatibility, prompt cache retention, warming, or automatic overflow handling. Upstream Pi metadata chunking and semantic-cut defects are NOT patched and remain unfixed upstream; legacy session carriers remain untouched, and Oh My Pi (OMP) is not supported or promised.
+
+The SDK queue exception is explicit: persisted custom messages can be absent from the current tool follow-up and have different live/persisted envelope timestamps. Compare full content/protocol fields, ignore only the regenerated custom timestamp, and permit custom-message omissions only when earliest/latest ordered alignments agree. Identical ambiguous omissions fail closed. Never rebuild/overwrite incoming context or reinsert omitted peer messages.
+
+## Resource and binding contract
+
+Discovered directories:
+
+- `.pi/forge/capabilities/*.json`
+- `~/.pi/forge/capabilities/*.json`
+
+```json
+{
+  "schemaVersion": 1,
+  "type": "pi-forge.capability",
+  "id": "review",
+  "name": "Review",
+  "description": "Report findings and evidence before editing.",
+  "content": "List findings, evidence and risks. Do not directly edit files.",
+  "tools": {
+    "add": ["grep", "find", "ls"],
+    "remove": ["bash", "powershell", "write", "edit"]
+  }
+}
+```
+
+The definition has no Agent authorization. Content is literal text, not an executable template or file path. `name`/`description` are optional; omitted tool arrays normalize to empty arrays. At least non-whitespace text or one tool effect is required. Content is bounded to 100,000 characters, name to 1,000, each tool array to 256 names and each exact tool name to 128 characters. Tool names cannot contain whitespace, controls, `*` or `?`. Capabilities support `add` and `remove` only; candidate `only` or capability-level allowlists are not implemented. Unknown and malformed fields fail closed.
+
+Preset binding field:
+
+```json
+{
+  "capabilities": [{
+    "ref": "global:review",
+    "id": "review",
+    "modelCallable": true,
+    "overrides": {
+      "appendContent": "Also inspect backwards compatibility.",
+      "tools": { "add": ["grep", "find"] }
+    }
+  }]
+}
+```
+
+The `capabilities` field is live in the Preset schema and validated by codecs and editors.
+
+### Accepted 9/21 amendment: Tool selection and UX refinements
+
+- **Preset initial tools (`tools.initial?: string[]`):** Configures initial active tools for a preset using concrete valid tool names (no wildcards allowed). When omitted, legacy behavior is preserved (selective allow selects matching registered tools; unrestricted/deny retains or filters the session baseline). When set to `[]`, zero tools are active initially. The `allow`/`deny` ceiling remains authoritative and exclusive; tools blocked by policy produce validation errors. Extensions and mods register allowed inactive tools: if `initial` is set, dynamically registered tools remain inactive unless listed or added by an active capability. Configured defaults serve as the active base throughout preset activation (not a one-time reset per turn): disabling a capability or calling disable/reset restores these defaults plus remaining capabilities; disabling the preset restores the reconciled session baseline (including preserved external changes).
+- **Capability grouped picker:** The tool picker organizes tools using SDK `sourceInfo` (Pi built-in tools, packages, or top-level entry points). It saves exact concrete tool names: no package references are persisted, no packages are auto-installed, and newly added package tools are not auto-added. Inactive registered tools are visible in the picker; unloaded tools are unavailable in the session, but manual saved references are preserved.
+- **Preset bindings tab:** Preset bindings are relocated from Preset metadata to a dedicated peer **Capability bindings** tab (`bindings`). Overrides (content, tools add/remove) and source-effective preview are collapsed under an advanced toggle (`showAdvanced` / `hideAdvanced`).
+- **Default tools editor:** An opt-in, searchable, collapsible grouped picker in the Policy tab allows choosing default tools, while retaining advanced literal and wildcard allow/deny policy.
+- **Save execution behavior:** Saving a Capability in the Capabilities surface updates its library definition only and never activates it. Saving an inactive Preset updates disk bytes without selecting or activating it. Crucially, saving the currently active Preset reloads and syncs its live tool and capability authorization policy immediately in the session without replacing frozen active capability snapshots (UI docs accurately reflect this; never promise that all saves leave execution untouched).
+- **Compatibility and versioning:** Stacks using `tools.initial` require new Forge (older Forge ignores `initial`, not downgrade-compatible). Development remains in the 0.5.4 tree with release version bump pending (0.5.5 or maybe 0.6); host requirement remains Pi `>=0.87.0 <0.88.0` unchanged.
+- **Prompt caching:** On compatible Codex transports, first-time additions can preserve request prefixes if retained history contains no removals/redeclarations; this is not a cache-hit guarantee. Removals/re-additions use the full-current-tool fallback. No permission bypass or caching guarantees.
+
+- Direct library selection of a bare ID uses project-over-global. Invalid or duplicate local definitions do not fall back to global.
+- A bare Preset reference resolves in its owner's scope. A project Preset must explicitly write `global:<id>` to use a global capability; a global Preset cannot use project capabilities.
+- UI writes qualified references. Binding ID defaults to the referenced ID; duplicate effective binding IDs are rejected, including same-name cross-scope references unless explicitly disambiguated. At most 256 bindings per Preset.
+- Only `modelCallable: true` grants eligibility for the Agent control path; omission defaults to `false`. Current tool policy and registration still apply on every call.
+- Overrides allow `content` (replace) **or** `appendContent` (paragraph append with two newlines), never both. Each specified `tools.add`/`tools.remove` array replaces that entire field; the other field is preserved. Identity, name, authorization, and arbitrary fields cannot be overridden.
+- Base resources must validate before applying overrides; an override cannot repair an invalid source silently. Effective results are defensive snapshots.
+
+## Semantic events and snapshots
+
+The internal schema is persisted through existing `session-adapter`/Pi custom entries, not a new persistence backend. Semantic entries carry validated snapshots; delivery messages carry only a versioned event cursor. Baseline records belong to the existing tool-policy owner.
+
+Common event fields: `schemaVersion: 1`, `eventId`, `op`, `actor`, `createdAt` (finite nonnegative milliseconds). Branch order, not timestamps, determines reduction. Opaque event/activation IDs are at most 128 characters. Resource/Preset/binding IDs keep the existing grammar.
+
+- **activate:** actor `user` or `agent`, with an immutable `snapshot` containing `activationId`, `source`, optional name, content, normalized tool patch, and content fingerprint.
+- **deactivate:** targets an `activationId`; actor `user`, `agent` or `lifecycle`.
+- **reset:** user only. Clears current activity, not historical events.
+- Source is `{ kind: "manual" }` or `{ kind: "capability", key: { scope, id }, binding?: { preset: { scope, id }, id } }`.
+- Agent activation requires an authorized bound capability (`modelCallable: true`). Agent deactivation cannot close user-owned activations. Lifecycle deactivation is restricted to bound capabilities; it cannot clear manual or unbound user rules.
+- Unknown/repeated off is a no-op. Activation IDs cannot be reused within one branch even after reset/off. Repeated identical event IDs are no-ops without moving the latest event marker backwards; conflicting reuse fails closed.
+- Repeated `enable` is deduplicated and idempotent; it never performs an automatic owner takeover between user and agent. Takeover requires explicit deactivation and reactivation.
+- Malformed owned event data fails reduction with an index/error, never a partially restored active set. Unrelated Pi entries are filtered by the adapter, not fed as fake capability events.
+- Fingerprints use Forge's canonical `sha256:v1` algorithm. The payload is domain-tagged effective source/name/content/tools, excluding activation ID. It represents content identity, not a cryptographic signature.
+
+Snapshot content never drifts with source edits. Switching Presets appends deactivations for old bound activations while retaining manual and unbound user rules; reloading the same Preset retains immutable active snapshots. Revoked authorization does not retroactively erase active snapshots; human recovery via CLI or Web disable/reset is the recovery path.
+
+## Delivery, recovery, tools, and parent safeguards
+
+Derived plain `custom` metadata entries anchor delivery; they do not independently own active state, duplicate authoritative snapshot payloads, or pollute conversation dialogue. One semantic history supports both presentations:
+
+- Native: request-only `SystemMessage.sections` keyed by activation identity; off uses a null patch and Pi's existing removal wording, without an extra duplicate user notice.
+- Unsupported models: an attributed timeline user update/stop notice. Do not silently fold Forge capability updates into the leading prompt. Genuine user/tool content is never promoted to system authority.
+- Transform only clearly owned Forge rule content, never an entire mixed system message. Preserve unrelated content/sections and `toolsAdded`/`toolsRemoved` for Pi's adapters.
+- Compaction requires an owned current-state checkpoint derived from semantic events; suppress pre-checkpoint anchors, including retained-tail copies, then replay later deltas. Request-only sections are not automatically saved by Pi's raw transcript checkpoint. Checkpoint placement remains unchanged (precedes summary, follows leading system prompt); the upstream Pi metadata chunking bug is an independent issue and remains unfixed.
+- Compaction input characterization: in real SDK compaction, summarizers receive no metadata anchors and no Forge rule bodies (projection is request-only), while user, assistant, and peer dialogue are preserved. Simulated responses in test harnesses characterize request plumbing and harness shape, not remote LLM semantic compaction fidelity or summarizer compliance.
+- **Breaking pre-release rename boundary:** no legacy aliases or readers are provided for the former instruction-mode schema, directories, or capability state. Existing development configuration must be converted and continuing old sessions are unsupported; Forge does not rewrite old JSONL or historical summaries, so converted configurations require a new session.
+- Immediate tool synchronization vs. next-request prompt projection: admission validates text/reference/authorization/tool effects before commit. Executable tool policy synchronizes *immediately* (`sync()` / `setActiveTools()`), whereas prompt text and native sections or user updates take effect at the *next model request* boundary. Running tool batches are not interrupted.
+- Tool policy calculation: tools are computed from a recoverable baseline plus all remaining additions minus all remaining removals, subject to top-level Preset deny policy; removal wins globally across active capabilities. Additions must be registered and permitted by the active Preset.
+- Read-only resource discovery and Preview: inspecting capabilities, calling `GET /api/capability-state/available`, or inspecting the Preview dock never mutates tool policies, commits session events, or marks pending capabilities prepared.
+- Parent safeguards:
+  - Raw source and revision coherence: GET operations couple editable data and `sourceRevision` from the same raw file bytes.
+  - External new bindings stale save detection: Preset saves enforce `sourceRevision` checks whenever bindings are present or modified, rejecting stale overwrites (409 Conflict) if the file changed on disk (including externally added bindings).
+  - Lifecycle and re-entry fences: explicit `disposed` flag, `lifecycleRevision` increment, and `sameContext` verification prevent cross-session pollution or operations after session disposal.
+- Provider-managed cache warning: prompt caching, tool transport, and KV cache hits are downstream provider-managed. Stable prefixes may help caching, but schema changes, removals, fallback, base recompilation, model switches, and compaction alter cache boundaries; pi-forge provides no guarantees of zero KV invalidation or exact cache hits.
+- Human recovery: human CLI (`/capability disable`, `/capability reset`) and Web panel controls remain available; an Agent-owned capability cannot disable its own control path without a safe recovery policy.
+
+## Staged implementation and release gates
+
+1. **Foundation (verified):** JSON codec, finite overrides, scoped resolution, immutable snapshots, and strict event reduction.
+2. **Human CLI core and metadata anchor projection (implemented):** Pi 0.87 dependency upgrade, `context_with_system` full pipeline, `buildSessionProjection` canonical alignment, request-base bridge, scoped discovery, session event persistence, plain `custom` cursor-only metadata anchors (replacing transcript carriers), ordinal materialization, compaction checkpoints, and executable tool-policy coordination. Real SDK tests cover same-run toggles, native/fallback switches, fake tool execution, disk reopens, branches, crash-window baseline recovery, and legitimate preceding extension rewrite fail-closed safety.
+3. **Session activity UI and compaction characterization (implemented):** read/control view derived from the existing runtime, never a second state owner. Human disable/reset carries an exact session/leaf/revision guard with runtime-instance fencing; Web requires trust, pure reads never synchronize or infer, and stale pages cannot retry writes automatically. Real-SDK compaction-input characterization confirms Forge metadata and request-only rules are absent from summarizer history while user, assistant, and peer dialogue remain intact; fake test responses are plumbing characterization, not remote semantic validation.
+4. **Preset authorization and restricted Agent control (implemented):** live Preset binding schema (`capabilities`), opt-in `modelCallable: true`, and restricted fixed-schema `forge_capability` (list, status, enable, disable, ID ≤ 128 chars). Per-call trust, binding identity, authorization, and tool policy checks prevent privilege escalation. CLI additions `/capability bindings` and `/capability enable-bound <id>` provide human parity. Management operations do not initiate paid inference.
+5. **Capabilities library CRUD, 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; Preset metadata 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/leaf/revision plus content fingerprint validation. Parent safeguards enforce raw source/revision coherence, external new bindings stale-save detection, and lifecycle/re-entry fences.
+6. **Release closeout (pending release review and user authorization):** Pi 0.87 migration and accepted tool-selection/UX amendment passed parent build and full verification (773 Node / 37 browser). Development package version remains 0.5.4; release version bump decision pending between 0.5.5 or 0.6; repo dev SDK is pinned to `0.87.0` with peer range `>=0.87.0 <0.88.0` (no dual 0.86 support claim); release, git push, and host reload (`/reload`) are separate user-authorized actions.
+
+Acceptance includes old Presets, regex/history filtering, repeated same-run toggles, native/user/native transitions, request abort/retry/concurrency, explicit and automatic compaction, disk resume/branches/crash boundaries, baseline recovery, real tool-call rejection, external tool changes, warming, and payload/usage association.
+
+No universal native support, obedience, zero-KV-invalidation, or guaranteed cache-hit claims. No automatic legacy migration, no old summary rewrites, and no Pi split patch. Publishing, host upgrades, reloads, and deployment remain separate user-authorized actions.

package/docs/development/release.md

@@ -2,36 +2,36 @@
 
 [Documentation](../README.md)
 
-## Before release
-
-1. Confirm the changelog and user documentation describe the intended version and experimental surfaces accurately.
-2. Publish and smoke-test any required `@zihanw/pi-subagent-runtime` version first.
-3. Install dependencies from the lockfile and run `npm run verify`; require the
-   Ubuntu, macOS, and Windows GitHub Actions jobs to pass for the release commit.
-4. Test a packed installation against the documented minimum and current Pi versions.
-5. Exercise ordinary stack/profile use independently of delegation.
-6. Exercise both configured foreground backends and confirm unsupported host capabilities fail closed before provider transport.
-7. Inspect `npm pack --dry-run` for package size and unexpected or missing files.
-
-The macOS and Windows jobs run the same complete verification surface as Linux,
-including the real-browser editor suite against the hosted runner's system
-Chrome. Compatibility-version and scheduled latest-Pi probes remain Linux-only;
-they test dependency drift rather than operating-system behavior.
+## Independent packages
+
+The main `@zihanw/pi-forge` package has **no** dependency on `@zihanw/pi-forge-subagents` or `@zihanw/pi-subagent-runtime`. It can release independently; unfinished optional features do not block ordinary Forge use or a main-package release.
+
+The optional package is tested against the released Forge host before its own publication. Any required runtime version must be published and smoke-tested before publishing the optional package that depends on it. Backend, continuation, background-task, and nested-usage producer acceptance belong to that companion release, not to the main package.
+
+## Before main-package release
+
+1. Confirm the intended version in the manifest, lockfile, changelog, and current user documentation. Preserve historical release records and document breaking configuration/session boundaries.
+2. Install dependencies from the lockfile with `npm ci`, build, and run the complete `npm run verify` chain: Node tests, browser tests, types, generated client, docs, distribution, package contents, and packed installation.
+3. Require the Ubuntu, macOS, Windows, and configured Pi compatibility GitHub Actions jobs to pass for the **exact release commit**, not an earlier source revision.
+4. Test a packed main-package installation against both the documented minimum and current tested Pi versions; exercise ordinary Preset/Profile/Capability behavior independently of optional delegation.
+5. Inspect `npm pack --dry-run` for package size and unexpected or missing files. Publish the verified artifact, not an unreviewed working tree.
+
+The macOS and Windows jobs run the same complete verification surface as Linux, including the real-browser editor suite. Compatibility-version and scheduled latest-Pi probes remain Linux-only; they test dependency drift rather than operating-system behavior.
 
 ## Dependency policy
 
-Published manifests use wildcard peer dependencies for Pi-host-provided SDK packages. Exact versions belong in development dependencies and the lockfile so tests are reproducible without restricting compatible host releases.
+The four Pi SDK packages remain host-provided optional peers, never private runtime dependencies. Forge 0.5.5 requires Pi `>=0.87.0 <0.88.0`, with development fixtures pinned to `0.87.0`; `typebox` remains a wildcard optional peer. Pi 0.86 and future minor versions are not implicitly supported. Exact tested versions belong in development dependencies and the lockfile, not exact host-version requirements.
 
-`pi-subagent-runtime` remains a normal exact dependency until its compatibility policy says otherwise. Its own host-facing Pi dependencies must follow the same host-provided peer model.
+Published `@zihanw/pi-forge-subagents` 0.5.3 does not understand `tools.initial`. The upcoming optional package needs the matching fix and a Forge dependency floor of `^0.5.5` for the new command-contribution entry. This is a companion compatibility gate, not a requirement to publish the packages simultaneously. See the [host-port compatibility note](../reference/subagent-host-port.md#tool-selection-compatibility).
 
 ## Package contents
 
-The tarball must include compiled `dist/`, examples, the English and Chinese landing pages, changelog, license, and user/reference documentation. It must not include physical `src/` files. Both the default extension entry and experimental subagent entry must resolve to compiled output.
+The tarball must include compiled `dist/`, examples, the English and Chinese landing pages, changelog, license, and user/reference documentation. It must not include physical `src/` files. The root, `/subagent`, `/ui-contribution`, and `/command-contribution` entries must resolve to compiled output.
 
 The root `PUBLIC_API.md` and `SUBAGENT_ADAPTER_CONTRACT.md` files are compatibility pointers; authoritative content lives under `docs/reference/`.
 
 ## Publish and verify
 
-Publish the intended version/tag, then install it through Pi in a clean project. Verify `/preset`, `/profile`, `/preset ui`, and—when deliberately enabled—delegation. Restart Pi after installation to avoid testing a stale extension instance.
+With release authorization, publish the intended version using the intended tag (`latest` for a stable main-package release). Verify registry version, tag, and tarball integrity, then install the published package through Pi in a clean project and smoke-test the main commands and resource workflow without model inference.
 
-For a stable release, ensure npm `latest` points to the new version and any prerelease channel no longer leaves users on an incompatible older build.
+Do not silently move unrelated legacy or prerelease tags. Publishing is not a host upgrade: restart or reload a user's existing host only with that user's authorization, and start a new session when the release's migration notes require it. Keep release evidence separate from static documentation; a version bump or changelog entry alone is not proof of successful publication.

package/docs/development/roadmap.md

@@ -4,7 +4,22 @@
 
 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).
 
-## 0.5.0 breaking cleanup (lean)
+## Active 0.5.5: session capabilities
+
+Implementation is authorized under the [accepted capability design](../design/pi-forge-system-update-design-notes.md) and [lean-plan amendment](../design/architecture-0.5.md#accepted-055-amendment-session-capabilities). Pi 0.86 is released; the old upstream-blocked thin-sections proposal is superseded.
+
+One active lane at a time:
+
+1. **Foundation (verified):** strict capability/override codec, scoped binding resolution, immutable snapshots, and branch event reducer.
+2. **Human CLI core & metadata anchor projection (implemented):** Pi 0.87 dependency upgrade, request-base replacement, `context_with_system` full pipeline, `buildSessionProjection` canonical alignment, native/user projection, semantic events and plain `custom` cursor-only metadata anchors, durable tool baselines, repositories/ForgeWorkspace discovery, and `/capability` add/list/bindings/enable/enable-bound/disable/status/reset. See [current reference](../reference/capabilities.md).
+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 is versioned 0.5.5; publication requires 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).
+
+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.
+
+## 0.5.0 breaking cleanup (lean history)
 
 0.5.0 is a deliberately breaking cleanup release plus the minimum foundation for 0.5.x. Net-new feature work is frozen.
 
@@ -78,7 +93,7 @@ Candidate history controls need concrete use cases and dangling tool-pair tests.
 - Skill filtering is model-visible prompt filtering, not an invocation or security boundary.
 - Delegation remains opt-in, foreground, clean-context, and fail-closed on missing capabilities, and lives in the optional package.
 - Do not report shared-user read-only policy as an OS sandbox.
-- New editor product workflows are frozen; migration changes retain real-browser coverage.
+- New editor workflows remain frozen except the explicitly accepted capability surfaces above; migration and new workflows retain real-browser coverage.
 - Run the full verification and package checks before release.
 
 The detailed completed 0.4 plan is retained in the [historical roadmap](../design/roadmap-0.4-archive.md).

package/docs/development/scoped-global-profiles-stacks.md

@@ -158,7 +158,7 @@ For compatibility:
 
 - Read legacy branch entries containing only `activeStackId` using effective lookup.
 - Write new entries with a scoped active-stack reference.
-- Preserve the explicit `none`/`off` selection as a scope-independent opt-out.
+- Preserve the explicit `none`/`disable` selection as a scope-independent opt-out.
 - Profile provenance should add the profile scope/key while continuing to accept older provenance that has only `profileId` and `sourcePath`.
 - Drift snapshots should store the resolved scoped stack reference so status can distinguish definition changes from a scope change.
 

package/docs/development/setup.md

@@ -55,7 +55,7 @@ Set `CHROME_PATH` when Chrome/Chromium is outside a standard location. CI runs t
 
 ## Pi compatibility
 
-Published pi-forge treats Pi-owned SDK packages (`pi-agent-core`, `pi-ai`, `pi-coding-agent`, `pi-tui`, and `typebox`) as host-provided wildcard peers. The running Pi host supplies one coherent SDK instance, avoiding duplicate packages and avoiding an install-time lock to Pi's frequent release cadence.
+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.
 
 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.
 

package/docs/getting-started.md

@@ -25,7 +25,7 @@ mkdir -p .pi/forge/prompt-stacks
 cp examples/default-prompt-stack.json .pi/forge/prompt-stacks/default.json
 ```
 
-When installed from npm, open `/preset ui` and create a stack; new stacks start from the same mirror layout.
+Open `/forge ui` to create a preset without copying a file. In Forge 0.5.5, you can choose the default Pi mirror layout, an empty preset (where Pi retains its base prompt and history), or a minimal worker template (`bash` and `edit` only).
 
 Reload and activate it: