@zihanw/pi-forge 0.5.4 → 0.5.6

package/docs/guides/delegation.md

@@ -4,7 +4,10 @@
 
 > **Experimental:** This API and its backends may change independently of stable prompt-stack and profile behavior.
 
-The optional `@zihanw/pi-forge-subagents` package executes an explicitly authorized agent profile as a separate, clean, one-shot Pi process. It runs in the foreground and returns a bounded report to the parent conversation.
+The optional `@zihanw/pi-forge-subagents` package executes an explicitly authorized agent profile through a selected backend. The default read-only backends use a separate, clean, one-shot Pi process; write-capable backends have different boundaries described below. The documented flow runs in the foreground and returns a bounded report to the parent conversation.
+
+> **Default-tool compatibility:** Forge 0.5.5 provides `tools.initial`; the independently published optional subagents 0.5.3 is not compatible with this field. Until the optional package raises its Forge floor to `^0.5.5` and ships its separate fix, use matching local checkouts; see [tool-selection compatibility](../reference/subagent-host-port.md#tool-selection-compatibility). This optional compatibility work is not a main-package release gate.
+
 
 ## Enable a profile
 
@@ -43,7 +46,7 @@ Humans use:
 
 `plan` resolves the profile and stack, compiles and validates the exact immutable provider-bound plan, displays it, and discards it without provider transport.
 
-Profile selectors accept the same grammar everywhere: `reviewer` (project first), `project:reviewer`, or `global:reviewer`. When both scopes expose the same ID, the project profile keeps the concise selector and the global profile remains callable as `global:<id>`.
+Profile selectors use the same grammar everywhere: `reviewer`, `project:reviewer`, or `global:reviewer`. For delegation, a bare ID selects `project:<id>`; use an explicit `global:<id>` selector for a global profile. Same-ID profiles remain separate and do not inherit delegation policy from one another.
 
 The parent model uses `forge_subagent_profiles` to discover enabled profiles and `forge_subagent` to invoke one. A restrictive parent stack must allow both tool names. Discovery is local/no-egress and reports metadata, resolution readiness, effective backend/timeout, approval mode, and whether parent tool policy permits invocation.
 
@@ -51,18 +54,20 @@ Projects with only a few frequently used profiles can set `summaryInToolDescript
 
 ## Parallel invocation
 
-`forge_subagent` is a parallel-execution tool: the parent model may issue several calls in one turn, and they prepare and run concurrently. Interactive approval dialogs are serialized one at a time because Pi's selector/editor UI is a single slot—a second concurrent dialog would clear the first and leave it unresolved—so each call waits its turn for the dialog and then executes immediately, letting approved runs overlap. Unattended invocation needs no dialog and is fully concurrent. Each run is an independent `pi` subprocess and provider request; a burst of parallel calls multiplies provider cost and process load, so keep the parent tool policy conservative until a configurable concurrency cap lands.
+`forge_subagent` is a parallel-execution tool: the parent model may issue several calls in one turn, and they prepare and run concurrently. Interactive approval dialogs are serialized one at a time because Pi's selector/editor UI is a single slot—a second concurrent dialog would clear the first and leave it unresolved—so each call waits its turn for the dialog and then executes immediately, letting approved runs overlap. Unattended invocation needs no dialog and is fully concurrent. Fresh-process backends create an independent child process and provider request; `pi-inprocess` instead runs in the host runtime. A burst of parallel calls multiplies provider cost and process load, so keep the parent tool policy conservative until a configurable concurrency cap lands.
 
 ## Backends and precedence
 
-Two fresh-process backends are registered:
+Matching development versions of the optional subagents package and runtime expose four backend IDs. These notes describe unfinished optional-package source, not a finalized companion release; the main Forge 0.5.5 package does not require them.
 
-- `pi-subprocess-readonly` is the default and uses `pi --mode text --print`.
-- `pi-rpc-readonly` uses `pi --mode rpc`.
+- `pi-subprocess-readonly` is the default and uses `pi --mode text --print`. It exposes the `read`/`grep`/`find`/`ls` allowlist and is shared-user: the allowlist is not an OS sandbox.
+- `pi-rpc-readonly` uses `pi --mode rpc` with the same shared-user read-only policy; only the process protocol differs.
+- `pi-inprocess` runs in the host model runtime with the invoking user's full privileges. It is a workspace-write backend and can expose `read`/`grep`/`find`/`ls`/`edit`/`write`/`bash` when the sealed access level and stack policy allow them; it has no OS sandbox. It is the backend for extension-registered providers that cannot be used in fresh children.
+- `pi-bwrap-write` is an opt-in Linux Bubblewrap backend. It provides an isolated `workspace-write` mount for the selected workspace and can expose `read`/`grep`/`find`/`ls`/`edit`/`write`/`bash` when allowed. Writes go directly to that workspace; they are not staged for a separate approval/apply step. Bubblewrap and, by default, a git workspace are required.
 
-Both execute the same sealed prompt and shared-user read-only policy; only their process protocol differs. There is no fallback if the selected backend is unavailable.
+There is no fallback if the selected backend is unavailable. Fresh-process backends reject extension-registered providers as non-portable; use `pi-inprocess` for those providers. Do not read the development matrix or the `tools.initial` compatibility fix as a claim that the paired companion release is already published.
 
-Interactive backend precedence is: per-run override, project profile override, project default, user default, built-in default. Unattended model invocation is pinned to the effective configured backend and rejects a per-call override. Timeout follows profile, project, user, then the 60-second built-in default; valid values are 1,000–3,600,000 ms. Host timeout is best effort.
+For human runs, backend precedence is: explicit per-run `--backend`, matching profile override, trusted project default, global default, then the built-in `pi-subprocess-readonly`. An interactive model invocation may also supply a per-call backend override; an unattended model invocation is pinned to the effective profile/configured backend and rejects that override. Timeout follows matching profile override, trusted project default, global default, then the 60-second built-in default; valid values are 1,000–3,600,000 ms. Host timeout is best effort.
 
 ## Approval and unattended invocation
 
@@ -76,28 +81,25 @@ To authorize the parent model without per-run approval:
 }
 ```
 
-This affects only `forge_subagent`; `/forge-agent run` remains interactive. It is ignored in untrusted projects and malformed values fail closed. Treat this project `subagents.json` as an authorization file: do not enable or commit it unless every parent agent allowed to call `forge_subagent` may send the compiled prompt and readable file contents to the selected provider without asking again.
+This affects only `forge_subagent`; `/forge-agent run` remains interactive. The flag may come from global defaults or a trusted project file, with the project value taking precedence. With the unreleased companion fix, an absent flag inherits; an explicitly non-boolean value sets that layer to `false` and emits a warning. A valid boolean in a higher-priority layer still overrides normally. If an entire config file is unreadable, malformed, or not a JSON object, that file is ignored with a warning and an earlier valid layer may remain effective. An untrusted project's project settings are ignored, and the execution trust gate blocks delegation runs from that project. Treat `subagents.json` as an authorization file: do not enable or commit unattended invocation unless every permitted parent agent may send the compiled prompt and readable file contents to the selected provider without asking again.
 
 ## Child context and output
 
-The child receives a clean conversation, the exact profile model/thinking/stack, and the delegated task as a protected final user message. It does not automatically receive parent history.
+An ordinary new child starts with a clean conversation, the exact profile model/thinking/stack, and the delegated task as a protected final user message. It does not automatically receive parent history. Explicit retained-child continuation and background execution are separate development features documented in the [companion package](https://github.com/MacroSony/pi-forge-subagents).
 
-Candidate tools are `read`, `grep`, `find`, and `ls`, further restricted by stack tool policy. The child loads no write/edit/shell tools, skills, prompt templates, project context files, or third-party extensions.
+For `pi-subprocess-readonly` and `pi-rpc-readonly`, candidate tools are `read`, `grep`, `find`, and `ls`, further restricted by stack tool policy; these children load no write/edit/shell tools, skills, prompt templates, project context files, or third-party extensions. `pi-inprocess` and `pi-bwrap-write` can receive the write-capable tool surface described above only when their access level and stack policy allow it.
 
 The model-visible result is bounded. Expandable human details retain normalized status, a text transcript, tool events, diagnostics, usage, approval receipt, and execution report. Retained strings are bounded, base64-like text is redacted, and the transcript keeps a 512 KiB rolling tail. Inline image bytes are replaced by MIME/encoded-size metadata before retention in the parent session.
 
 ## Security boundary
 
-The current backends are **shared-user, not operating-system sandboxes**.
+The security boundary is backend-specific:
 
-- “Read-only” is a model-tool policy. The process retains the invoking user's OS permissions.
-- Absolute paths readable by that user may be read and sent to the selected provider.
-- Text may be retained in parent tool-result details and Pi's on-disk session JSONL.
-- Timeout and cancellation are best effort.
-- `/tree` changes the active conversation branch; abandoned entries can remain on disk.
-- `/tree` cannot undo provider requests, billing, or external effects.
-- Removing sensitive retained text requires deleting the relevant Pi session data.
+- The subprocess and RPC read-only backends are **shared-user, not OS sandboxes**. “Read-only” is a model-tool policy; the child retains the invoking user's OS permissions. Absolute paths readable by that user may be read and sent to the selected provider.
+- `pi-inprocess` is also shared-user and runs in the host process with full user privileges. Its allowlist can permit write/edit/`bash`, but it provides no OS isolation.
+- `pi-bwrap-write` is the isolated Linux exception: Bubblewrap exposes the selected workspace as the writable project mount, alongside read-only runtime mounts and temporary sandbox storage. It is not a staged patch/apply workflow, and it does not provide network isolation.
+- Across backends, timeout and cancellation are best effort. Text may be retained in parent tool-result details and Pi's on-disk session JSONL; `/tree` cannot undo provider requests, billing, or external effects, and abandoned entries can remain on disk. Removing sensitive retained text requires deleting the relevant Pi session data.
 
-The default tools intentionally provide no mutation path. Do not add write, edit, or shell access to this shared-user design. OS isolation and separately approved staged writes remain future work.
+Choose a read-only backend when no mutation path is intended. Treat write-capable backends as explicit authorization to modify the selected workspace, not as a promise of separately approved staged changes.
 
 For integration authors, see the [subagent host port contract](../reference/subagent-host-port.md).

package/docs/guides/migrating-to-0.5.md

@@ -101,6 +101,35 @@ Subagent execution moved out of the main package into the optional `@zihanw/pi-f
 | `@zihanw/pi-forge/src/*` aliases | removed; no replacement (internals) |
 | root loader/profile/catalog/engine re-exports | removed; no replacement (internals) |
 
+## Upstream Pi 0.87 migration
+
+Forge 0.5.5 requires upstream Pi `>=0.87.0 <0.88.0`. Dual 0.86 runtime support is not provided (repo dev SDK is pinned to `0.87.0`, peer range `>=0.87.0 <0.88.0`). Main and optional packages release independently.
+
+**Restart Pi after upgrading:** Updating the global installation does not replace the core in already-running processes. If the session predates the upgrade, exit and start Pi again before resuming it; extension-only `/reload` does not upgrade the running core. Use the new `/preset ui` URL; old server tokens are not retained.
+
+### Context hook migration (`context_with_system`)
+
+- **Standard `context` excludes System:** In Pi 0.87, standard `context` lifecycle hooks intentionally exclude System messages. Any prior extension or custom integration that inspected, modified, or relied upon full System context must move to the full `context_with_system` hook.
+- **Unified Forge pipeline:** Forge moves its entire compiler, base prompt replacement, and capability projection pipeline together to `context_with_system`, operating cleanly at the full-transcript boundary without an internal two-phase split.
+- **`before_agent_start` timing:** Any forced System prompt injection via `before_agent_start` continues to execute later in Pi's lifecycle than `context_with_system`.
+
+### Canonical projection and session history
+
+- **`buildSessionProjection` integration:** Runtime execution, the Preview dock, and anchor locator helpers now use Pi 0.87's `buildSessionProjection`. Turn-level `context_edit` omissions, replacements, and `sourceEntry` references are reflected in ephemeral model requests while raw session JSONL history on disk remains untouched.
+- **Leading System message ordering:** The SDK's incoming leading System message always remains first in the request transcript; Forge's own prefix plain metadata anchors are inserted immediately after it, never displacing the request head or user fallback.
+- **Arbitrary preceding rewrites fail closed:** Third-party extensions performing arbitrary message rewrites prior to Forge must maintain unique ordered alignment with the canonical session projection. Ambiguous or destructive preceding rewrites still fail closed.
+
+### Continuations and settlement lifecycle
+
+- **`agent_end` vs. `agent_settled`:** `agent_end` offers an anchor boundary after a low-level run, provided no Forge context failure or incomplete tool batch remains. However, the compile cycle and busy fence reset only on `agent_settled`. This guarantees that `agent_before_settle` continuations preserve compiled Preset inputs and active capabilities across low-level runs without dropping prompt context.
+
+### Guardrails and semantics unchanged
+
+- **Project trust:** Activations and Agent control require an explicitly trusted project (`isProjectTrusted()`); human CLI disable/reset recovery remains available.
+- **`sourceRevision` stale-save guard:** Existing capability updates/deletes and binding-bearing Preset updates must match the loaded source revision; capability creation must not overwrite an existing file. Stale saves fail with `409 Conflict`.
+- **Save ≠ Enable:** Saving a capability library definition updates its file only and does not enable it in the session; saving an active Preset refreshes that Preset's policy immediately (updating live tool and capability authorization policy), without replacing frozen active capability snapshots.
+- **Upstream defect status:** Upstream Pi metadata chunking and semantic-cut defects are NOT patched; compaction checkpoint placement is unchanged. Existing legacy session carriers remain untouched without automatic migration, and Oh My Pi (OMP) is not supported or promised.
+
 ## Compatibility notes
 
 - The wire shape of the host port is additive across `FORGE_HOST_PORT_VERSION = 1`; unknown operations are rejected with a plain `{ ok: false, error }` result (`"Unknown Forge host operation: …"`), not a thrown error, and optional packages must treat any operation failure as terminal for that request.

package/docs/guides/use-cases.md

@@ -36,7 +36,7 @@ Keep independent project files:
   translator.json
 ```
 
-Switch with `/preset use coder`, `/preset use writer`, or `/preset use translator`. Capture a profile when a mode also needs a specific model and thinking level.
+Switch with `/preset use coder`, `/preset use writer`, or `/preset use translator`. Capture a profile when a capability also needs a specific model and thinking level.
 
 ## Read-only scout
 
@@ -44,13 +44,17 @@ Allow only `read`, `grep`, `find`, and `ls`, omit editing tools, and cap chat hi
 
 Tool policy constrains model tool calls but is not an operating-system sandbox. A normal Pi agent may still have other non-tool ways to interact with its host; do not describe a prompt stack alone as process isolation.
 
+## Read first, enable command/edit tools on demand
+
+The [Read-first Worker pair](../reference/capabilities.md#read-first-worker) keeps the minimal-worker shape: one role block and chat history. Defaults are `read` and `ls` plus `forge_capability`; one explicitly authorized binding adds `bash` and `edit`. Follow the paired-file setup and ownership/sandbox caveats before trying it.
+
 ## Surgical patcher
 
 Keep the Pi mirror, require the tools needed for the workflow, strip prior assistant thinking from inserted history, and move project context near the current user turn. This reduces distracting prompt material without removing relevant repository instructions.
 
 ## Payload lab
 
-Include `active-model` and `date-cwd`, then add compiled regex rules for deterministic redaction or formatting. Pair the stack with `/payload next` or the web editor's capture view to audit exactly what changed.
+Include `active-model` and `date-cwd`, then add compiled regex rules for deterministic redaction or formatting. Pair the stack with `/forge payload next` (or bare `/payload`) or the web editor's capture view to audit exactly what changed. Use `save="path with spaces.json"` when saving a capture; existing files require `--overwrite`.
 
 Redaction is limited to the declared patterns and supported text targets. It is useful for known shapes but is not an exhaustive credential scanner or security boundary.
 

package/docs/guides/web-editor.md

@@ -14,7 +14,7 @@ Use `/preset ui restart` to replace its server or `/preset ui stop` to close it.
 
 The editor binds to an available `127.0.0.1` port and uses a session token. Multiple Pi projects can run editors simultaneously. Lifecycle reinitialization reuses the existing editor URL for the same project when possible.
 
-Reads, preview, resources, and payload inspection remain available as appropriate, but writes require Pi to trust the project. Files are constrained to Pi Forge's Preset/Profile storage. Never expose or proxy the editor URL to an untrusted network.
+Reads, preview, resources, and payload inspection remain available as appropriate, but writes require Pi to trust the project. Built-in Web writes are constrained to Pi Forge's Preset/Profile, Capability, and trusted Forge configuration storage. Never expose or proxy the editor URL to an untrusted network.
 
 Choose a preferred port in `.pi/forge/config.json`:
 
@@ -36,9 +36,11 @@ The editor interface is available in English and Chinese. Use the language selec
 
 The Preset workspace provides:
 
-- creation from the default Pi-mirror layout;
+- preset creation with template choices (Default Pi prompt, Empty, Minimal Worker);
 - an ordered **Stack** tab for Block/Slot composition;
-- structured metadata, policy, parameters, context, and Regex editing;
+- a **Policy** tab for tool/skill allow/deny resource policy and custom default tools (`tools.initial`);
+- a peer **Capability bindings** tab for associating capabilities (Preset metadata no longer contains bindings);
+- structured metadata, parameters, context, and **Regex** editing;
 - drag-and-drop item order and enable/disable controls;
 - validation and a full compiled preview;
 - registered-tool and loaded-skill search with exact-name chips and wildcard patterns;
@@ -48,15 +50,82 @@ The Preset workspace provides:
 - payload arming and redacted captured-payload inspection;
 - light and dark themes.
 
-Existing IDs are immutable during edit. Use **More → Fork** to create a different ID without breaking Profile references or the active selection. The compact selector attached to **New preset** (default `Project`) chooses where new Presets, imports, and forks are written: `Global` targets the user-global `~/.pi/forge/prompt-stacks`, `Project` targets `.pi/forge/prompt-stacks`. Those paths keep their pre-0.5.3 names for compatibility. Less-used capture, fork, import, export, and delete actions live under **More** so the Stack and Preview/Diff panes keep the available viewport. Preset rows show a `global` badge, and save/delete routes use `global:<id>` for exact global mutations. Legacy resources remain editable in place.
+### Editing and inspecting
+
+The resource header identifies the Preset being edited separately from whether it is active in the session. The global Session capabilities strip stays available when switching surfaces. Opening **Preset properties**, item properties, rule cards, or binding details does not modify the draft. Preset properties now opens from the resource header without pushing the editor down; its field edits remain in the same Preset draft until Save. Global Session capabilities retains a compact summary and opens the non-modal **Current session** workspace, separate from the edited resource. Effective tools, instruction excerpts, active capabilities and activation controls come first; full instruction bodies, session identity and transport details are expandable. Trust/stale/error and pending/prepared warnings remain visible. Preset status feedback sits in the footer; its Disable action still targets the active Preset, not the selected draft.
+
+- **Stack:** Rows show a name/on-off control and one summary line, such as `user · report` or `slot · chat-history`. Full identity remains available in tooltips and **Properties**, including Copy ID. Role and slot selection sit beside Properties; content follows directly. Rows support Enter/Space selection and dragging. A quiet, direct delete button remains in the item header with confirmation. Slot option forms size to their contents rather than stretching their rows.
+- **Row state and pane widths:** Disabled rows use a neutral background, muted text and gray side markers; a thin selection outline means editing, not enabling. Drag the right edge of the Presets or Stack items pane to resize it. Double-click or press Enter on the separator to restore its default; arrow keys adjust it, and Escape cancels an active drag. Width preferences stay in this browser origin, never in Preset JSON, and do not dirty or save a draft. Smaller windows temporarily constrain widths to leave editing room; narrow screens retain the stacked layout.
+- **Regex:** Scan rule names, enable state, stage/effect, and pattern excerpts before expanding a rule. Pattern/replacement editing stays prominent; frequency, targets, roles, and limits are under the rule's advanced section. A dashed list-end entry adds and focuses a rule. Rule/binding removal is confirmed and remains a draft change; use the Preset's **Save** action to persist changes.
+- **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.
+
+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.
+
+### 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.
+
+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.
+
+Inspection is a local read: it neither prepares/delivers a request nor changes tools or session history. It is not a captured provider payload or evidence of cache reuse; use Run diff/Payload and reported usage for those separate observations.
+
+### Tool selection and default tools editor
+
+The **Policy** tab includes an opt-in default tools editor (`tools.initial?: string[]`):
+
+- **Default tools picker:** A searchable, collapsible grouped tool picker organizes tools by SDK `sourceInfo` (Pi built-in tools, packages, and top-level entry points). Group checkboxes select/deselect the currently filtered group. **Enter tool names manually** preserves literal/offline-name entry, including in the Capability editor.
+- **Exact names:** The picker saves concrete tool names. It does not persist package references or auto-install packages, and newly introduced package tools are not automatically added. Inactive registered tools are visible in the picker; unloaded tools are unavailable in the session, but manual saved references are preserved rather than discarded.
+- **Omission vs. zero defaults:** Omitting custom defaults preserves legacy behavior (selective allow selects catalog matches; unrestricted/deny retains or filters the session baseline); setting an empty list (`[]`) sets zero active tools by default.
+- **Authoritative ceiling:** The advanced literal and wildcard allow/deny policy is retained and acts as an authoritative ceiling; tools blocked by allow/deny cannot be selected as defaults.
+- **Runtime behavior:** Configured defaults serve as the active base while the preset is active (not a one-time reset per turn). Disabling a capability recomputes defaults plus remaining active capabilities; disabling the preset restores the reconciled session baseline, while switching recomputes under the new Preset and remaining unbound capabilities.
+
+### Capability bindings tab
+
+Capability bindings are managed in the peer **Capability bindings** tab:
+
+- Each binding card shows one scoped capability reference and the model-activation authorization toggle. Binding ID belongs to its expandable details, not a permanently visible header field.
+- **Advanced** reveals binding ID and overrides (content replace/append, tool add/remove). The live source-effective preview has its own disclosure.
+- Tool overrides choose **Inherit** or **Custom override**, with integrated tool pickers matching the policy picker. A custom list may be empty: `[]` replaces that source add/remove list with zero entries, while inheritance omits the override. It does not clear every session tool or bypass other permission limits.
+- Binding order is catalog order, not execution priority; the editor no longer offers up/down controls. Direct removal requires confirmation and stays in the Preset draft until Save. Expanded details follow their binding when another row is deleted.
+
+### Save behavior and execution impact
+
+**Activate** uses the saved Preset. It is unavailable while the editor has unsaved changes; save explicitly first. Saving and activating are not a combined transaction.
+
+- **Capabilities surface:** Saving a capability updates its library definition only and does not enable it in the current session.
+- **Presets:** Saving an **inactive** Preset updates its configuration file without selecting or activating it. Crucially, saving the **currently active** Preset refreshes its policy immediately in the active session (synchronizing live tool and capability authorization policy), without replacing frozen active capability snapshots.
+
+Existing IDs are immutable during edit. Use **More → Fork** to create a different ID without breaking Profile references or the active selection. The **New preset**, **Import**, and **Fork** dialogs collect name, ID, and target scope (default `Project`) before writing: `Global` targets the user-global `~/.pi/forge/prompt-stacks`, `Project` targets `.pi/forge/prompt-stacks`. Those paths keep their pre-0.5.3 names for compatibility.
+
+The **New preset** dialog offers three initial templates:
+- **Default Pi prompt:** Preserves Pi's built-in prompt layout with movable slots, tools, guidelines, docs, project context, skills, and chat history.
+- **Empty:** Starts with no preset items or tool/skills policies (`items: []`). This does not mean zero context or tools; Pi automatically retains its base system prompt and history when no composed system prompt is provided.
+- **Minimal Worker:** Mirrors the DeepSeek Harness minimal shape (`examples/minimal-prompt-stack.json`) with a single-line system persona ('You are a helpful software engineer assistant.'), chat history with summaries disabled, and restricted tools (`bash` and `edit` only).
+
+Choosing a template automatically updates the suggested preset name as long as it has not been customized by the user. The **Import** and **Fork** dialogs continue to use the supplied or loaded source preset, not a creation template.
+
+The dashed creation entry sits below the Preset list; **Add content / slot** below the item list lets you choose Block or Slot. Less-used capture, fork, import, export, and delete actions live under **More** so the Stack and Preview/Diff panes keep the available viewport. Preset rows show a `global` badge, and save/delete routes use `global:<id>` for exact global mutations. Legacy resources remain editable in place.
 
 Saves, imports, forks, and deletes reload Preset state into the current Pi session. When another surface changes a referenced Preset, returning to Profiles refreshes Profile resolution.
 
+### 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`.
+
 ## Agent-profile workspace
 
 The Profile list shows each Profile's ID, display metadata, model, thinking level, Preset, resolution state, auto-activation, last-applied provenance, and a `project`/`global` scope badge. Same-ID shadow pairs are marked `shadows global:<id>` or `shadowed by project:<id>`.
 
-Trusted projects can create Profiles in either scope: the scope selector beside **New profile** (default `project`) chooses whether to write the user-global `~/.pi/forge/agent-profiles` or the project `.pi/forge/agent-profiles`. Global Profiles can be edited, validated, saved, applied once, and deleted through explicit `global:<id>` routes; unqualified routes stay project-only. When editing a global Profile, the Preset dropdown offers only global Presets. Model choices come from Pi's model registry, thinking choices reflect model support, and Preset choices come from the shared repository. The editor rejects a second auto-activation Profile within the same scope.
+Profile and Capability libraries place their dashed creation entry below the resource list. Creation editors put name first and choose scope in one place; they keep their full model/content fields and do not write incomplete resources merely to create a list row.
+
+Trusted projects can create Profiles in either scope: the scope field in the creation editor (default `project`) chooses whether to write the user-global `~/.pi/forge/agent-profiles` or the project `.pi/forge/agent-profiles`. Global Profiles can be edited, validated, saved, applied once, and deleted through explicit `global:<id>` routes; unqualified routes stay project-only. When editing a global Profile, the Preset dropdown offers only global Presets. Model choices come from Pi's model registry, thinking choices reflect model support, and Preset choices come from the shared repository. The editor rejects a second auto-activation Profile within the same scope.
 
 The runtime/provenance card separates current runtime state, last-applied snapshot, source-definition changes, and field-level runtime drift.
 

package/docs/reference/active-state.md

@@ -0,0 +1,77 @@
+# Active-state bus contract
+
+[Documentation](../README.md)
+
+Status: neutral, versioned. This is an optional appearance/session metadata seam consumed over the Pi event bus. It is not a package import entry point and has no Pi Pet-specific dependency. Consumers attach to `pi.events` (or `ctx.events`) and must treat every failure cosmetically.
+
+## Channels
+
+- Snapshot/change: `@zihanw/pi-forge/active-state/v1`
+- Snapshot request: `@zihanw/pi-forge/active-state/request/v1`
+
+The production publisher is the main pi-forge extension. It registers the request listener on attach and removes it on disposal/session switch. No unbounded retries or timers are used.
+
+## Request
+
+```json
+{ "schemaVersion": "1", "sessionId": "raw Pi session-manager id" }
+```
+
+`sessionId` is optional. When present, the publisher answers only if it matches the currently bound session; when omitted, it answers the current snapshot. A late subscriber can therefore request the current state after missing an earlier publish. Malformed or oversized requests are ignored.
+
+## Event
+
+```json
+{
+  "schemaVersion": "1",
+  "sessionId": "raw Pi session-manager id",
+  "instanceId": "uuid",
+  "revision": 1,
+  "stackKey": "global:slug",
+  "profileKey": null,
+  "projectKey": "64 lower hex sha256"
+}
+```
+
+| Field | Meaning |
+| --- | --- |
+| `schemaVersion` | Always `"1"`. Unknown versions are rejected. |
+| `sessionId` | Raw Pi session-manager ID for the bound session. |
+| `instanceId` | Fresh bounded publisher instance (`^[A-Za-z0-9_-]{1,128}$`, UUID-compatible) per attach/epoch. A new instance retires the old one. |
+| `revision` | Monotonic safe integer within one instance. |
+| `stackKey` | Effective scoped prompt-stack key, or `null` when disabled/off. |
+| `profileKey` | Compatible applied-profile provenance key, or `null` (see below). |
+| `projectKey` | Opaque SHA-256 project identity, or `null`. Never a raw path. |
+
+No other fields cross the channel. Prompt text, file paths, tokens, credentials, model configuration, tool policy, and character data are never included.
+
+## Identity and scope rules
+
+- Scoped keys use `^(global|project):[A-Za-z0-9][A-Za-z0-9._-]{0,127}$`. Invalid values become `null`; scoped IDs never cause filesystem access.
+- `projectKey = sha256("pi-forge-project-v1\0" + hostname + "\0" + path.resolve(cwd))`, lower hex. Only the digest crosses the bus, so two working directories are isolated without revealing either path.
+- Global resource bindings ignore `projectKey`.
+- Project resource bindings **require** `projectKey`. A project-scoped `stackKey`/`profileKey` with a `null` project key fails closed. When the session `cwd` is empty or unresolvable, the publisher nulls project-scoped `stackKey`/`profileKey` rather than emit a snapshot its own validator rejects.
+- `instanceId` uses the bounded UUID-compatible scalar grammar above; control characters, path separators, dots, and other punctuation are rejected. Real session IDs remain raw bounded strings (1..1024 chars).
+- `profileKey` is derived from `lastAppliedProfile` only while its recorded `snapshot.promptStack` equals the current effective scoped stack (`null` equals disabled). It is cosmetic compatible-provenance identity, not a claim that the current model, thinking level, or tools still match the profile. Manual stack drift clears an unrelated profile binding.
+
+## Publishing lifecycle
+
+The publisher emits on: initial session bind/restore, session start, tree navigation, compaction, explicit preset changes (`enable`, `none`/off), profile apply/update, web-editor updates, and disposal. Workspace changes publish without any provider/model call.
+
+Rules:
+
+1. `instanceId` is per attach. Switching sessions emits a final cleared snapshot for the old session, then a new instance for the new session.
+2. `revision` is monotonic within an instance. At the `Number.MAX_SAFE_INTEGER` boundary the publisher rotates to a fresh instance epoch instead of wrapping the same instance back to `1`. A snapshot request repeats the current revision rather than advancing it.
+3. Disposal emits a cleared snapshot (`stackKey`/`profileKey`/`projectKey` as available, stack/profile `null`) and unregisters the request listener.
+4. Session start/tree/compact suspend publication and request replies across `restoreBranchScopedRuntime`, then bind and publish one latest coherent snapshot. A failed restore detaches/clears instead of leaving the old session bound to the new workspace.
+5. Optional listeners never alter Forge compilation, tool policy, or provider behavior; a throwing reader/listener/transport is isolated. The shutdown path attempts every teardown step even if an optional transport rejects `emit`/`on`/`unsubscribe`.
+6. The same live instance/epoch is retained across a same-session compaction; cosmetic state is not cleared/recreated needlessly.
+
+## Consumer expectations (normative)
+
+- Accept only events whose `sessionId` matches the consumer's current Pi canonical session identity.
+- Reject stale/duplicate revisions and snapshots from retired instances with bounded tracking; never retry unboundedly.
+- Fail closed on malformed or oversized payloads, wrong schema versions, or project-scoped bindings without a `projectKey`.
+- Clear context on an explicit cleared snapshot; do not treat bus traffic as an implicit identity/status/auth/Team change.
+
+See [public API policy](public-api.md) for how this bus contract relates to the package import surfaces.