@zihanw/pi-forge 0.5.4 → 0.5.6

package/docs/reference/capabilities.md

@@ -0,0 +1,259 @@
+# Capabilities (`/capability`)
+
+[Documentation](../README.md) · [中文](../zh-CN/reference/capabilities.md)
+
+Pi-forge introduces capabilities: session-scoped prompt directives paired with dynamic tool selection. `/capability` is the CLI command. This reference details configuration, CLI usage, Web editing, Agent controls, delivery models, recovery boundaries, and compatibility limits.
+
+## 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.
+- **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.
+
+Capabilities are JSON files stored in:
+
+- **Project scope:** `.pi/forge/capabilities/<id>.json`
+- **Global scope:** `~/.pi/forge/capabilities/<id>.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": [],
+    "remove": ["bash", "powershell", "write", "edit"]
+  }
+}
+```
+
+### Resource rules
+
+- **Literal content:** `content` is literal text (up to 100,000 characters). It is not a file path, script, or macro; template variables are not expanded.
+- **Tool identifiers:** Names in `add` and `remove` arrays must be exact tool names (up to 128 characters, no whitespace, control characters, or wildcards `*`/`?`, max 256 tools per array).
+- **Tool patch constraints:** Capabilities support `add` and `remove` ONLY; candidate `only` or capability-level allowlists are not implemented.
+- **Resolution and shadowing:** Bare selectors use project-over-global shadowing. If a project capability contains invalid JSON, resolution fails closed locally; it does not fall back to global. Exact scopes can be targeted using `project:<id>` or `global:<id>`.
+
+## Ownership scopes and lifecycle
+
+- **Owner scopes:** Definitions (capabilities) are reusable resources stored in project or global libraries. Authorizations and bindings belong to Presets (top-level `capabilities` array in the Preset JSON). Active state and activations belong strictly to Sessions.
+- **Direct vs. bound use:**
+  - Direct activation via CLI (`/capability enable <[scope:]id>`) or Web library activation creates an *unbound* session activation.
+  - Bound activation via CLI (`/capability enable-bound <id>`) or Web preset binding activation creates a *preset-bound* session activation tied to the active Preset.
+- **Immutable snapshot semantics:** Activation captures an immutable snapshot (`content`, `tools`, `fingerprint`). Modifying or deleting capability files on disk does not mutate already active session snapshots.
+- **Same-Preset reload vs. switching:** Reloading the same Preset retains immutable active snapshots. Switching Presets automatically retires (lifecycle-deactivates) old bound activations while retaining manual and unbound user rules. A switch first checks the surviving capabilities against the target tool policy; a conflict rejects the switch without changing the current selection, tools, or activation events. Disable the conflicting capability before retrying. This does not retroactively modify frozen snapshots when their source files change.
+- **Revocation behavior:** Revoking a binding's authorization (`modelCallable: false`) or removing the binding from the Preset does not retroactively erase active snapshots; human CLI (`/capability disable` or `/capability reset`) or Web panel deactivation is the recovery path.
+- **User vs. Agent ownership and deduplication:** Activations record actor attribution (`user` vs `agent`). Repeated `enable` of an already active capability is idempotent and never performs an automatic owner takeover between user and agent. Takeover requires an explicit deactivation and reactivation cycle.
+
+## Preset-authorized Agent controls
+
+Preset `capabilities` bindings support autonomous Agent activation when explicitly authorized:
+
+- **Model-callable tool:** The fixed-schema `forge_capability` tool is registered once. Its visibility follows the normal executable tool selection; registration alone grants no capability authorization. Calls require an active Preset and enable/disable recheck the specific current binding.
+- **Opt-in authorization:** Only bindings with `modelCallable: true` in the active Preset may be activated by the Agent; omission defaults to `false`.
+- **Fixed parameter schema:** Accepts only `{ action: "list" | "status" | "enable" | "disable", id?: string }` (ID ≤ 128 characters).
+  - `list`: lists currently eligible bound capabilities for the active Preset; use `status` to inspect active snapshots.
+  - `status`: returns session active capability count, presentation model, delivery state, and effective tools.
+  - `enable`: requires binding `id`. Activates only authorized preset-bound capabilities with `modelCallable: true`.
+  - `disable`: requires `id` (binding ID or activation UUID). Stops only activations owned by the `agent`.
+- **Safety and ownership fences:**
+  - Rechecks project trust, active Preset, binding identity, `modelCallable: true`, and current tool policy on every call.
+  - The Agent cannot stop human-owned activations.
+  - The Agent cannot invoke `reset` or add arbitrary prompt directives.
+  - The Agent cannot activate a capability that removes `forge_capability`.
+  - Disposed, restoring, or cross-session re-entry requests fail closed immediately.
+
+Agent list/status replies intentionally omit full rule bodies: list returns authored descriptions and effects; status reports activity metadata. This avoids duplicating request-only instructions into ordinary tool history and later summaries. Human CLI/Web inspection still displays the complete frozen content. Genuine dialogue and authored descriptions are not scrubbed.
+
+### Read-first Worker
+
+A minimal main-package example pair: [Preset](../../examples/read-first-worker-prompt-stack.json) and [Write tools capability](../../examples/capabilities/write-tools.json). Use Forge 0.5.5; older published Forge may ignore `tools.initial`. Optional subagent execution remains an independent unfinished release.
+
+1. In a trusted scratch project, copy the Preset to `.pi/forge/prompt-stacks/read-first-worker.json` and the capability to `.pi/forge/capabilities/write-tools.json`. Check for existing files first; do not overwrite your own resources. Importing the Preset alone does not install its referenced capability.
+2. Start a fresh Pi session with Forge loaded, run `/preset reload`, then `/preset use project:read-first-worker`. The example has `autoActivate: false` and uses a **project-scoped** binding; a global copy needs a global capability and an updated `ref`.
+3. With no other active capabilities, defaults are `read`, `ls`, and `forge_capability`. The latter is a capability-management tool, not a file-writing tool. The model can list authorized bindings with `{ "action": "list" }`, enable commands/edits with `{ "action": "enable", "id": "write-tools" }`, then disable its own activation with `{ "action": "disable", "id": "write-tools" }`.
+4. Observe `read, ls, forge_capability` → plus `bash, edit` → defaults again in **Current session** or `/capability status`. Other active capabilities still participate. If a human enabled the capability instead, the model cannot turn that human-owned activation off; stop it from the UI or `/capability disable <activation-id>`.
+
+`allow` is the ceiling; `initial` selects defaults; `modelCallable: true` explicitly authorizes this binding without a new human approval prompt on each use. Change it to `false` if you want human-only activation. Off is requested by the sample prompt, not automatically enforced at task completion. It neither undoes changes nor terminates running tools. **Read-first is not a read-only sandbox:** `bash` can execute arbitrary commands, not just write files; these settings provide no filesystem/process isolation. This deliberately minimal replacement prompt omits Pi's normal project-context, skill and guidance slots; fork the default Pi mirror when you need them.
+
+## Commands
+
+Manage active instructions through the `/capability` command:
+
+| Command | Behavior |
+|---|---|
+| `/capability list` | Explicitly reload the capability library and list available capabilities with validation status. |
+| `/capability bindings` | List capability bindings declared in the active Preset, including human-only bindings. |
+| `/capability enable <[scope:]id>` | Select and activate an unbound library capability (bare ID or qualified selector). |
+| `/capability enable-bound <id>` | Activate a Preset binding by ID as a human; `modelCallable` is not required. |
+| `/capability status` | Show active capability count, presentation model, delivery state, and selected tools. |
+| `/capability disable <activation-or-capability-id>` | Deactivate an active capability by activation UUID or capability ID. |
+| `/capability reset` | Deactivate all active capabilities and manual directives (user only). |
+| `/capability add <text>` | Append a manual literal instruction rule to the active session without tool changes. |
+| `/capability help` | Show command usage and command details. |
+
+Completions use the current session and last published workspace snapshot. They do not perform discovery on every keystroke. Run `/capability list` when an explicit discovery refresh is needed. `/capability enable` completions offer bare IDs when unique, and qualified selectors on same-ID collision or when typing a `:` scope prefix (with labels always qualified by source and name). Human-only bindings remain in `bindings`; `modelCallable: false` prevents Agent control but does not filter the binding from human inspection or activation.
+
+**No inference cost:** All `/capability` commands and Web activity panel actions execute locally. They update internal session state and synchronize tool policies without starting model inference or consuming API tokens for the operation itself. Instruction text consumes input tokens on subsequent model requests when inference occurs.
+
+## Web resource editing
+
+### Capabilities surface (CRUD)
+
+The top-level **Capabilities** navigation surface supports full project and global capability management. Its library API is `GET /api/capabilities`, with selector and effective variants at `/api/capabilities/<selector>` and `/api/capabilities/effective`.
+
+- **Browse and inspect:** View capability ID, display name, description, instruction text, and tool modifications (`+add`, `-remove`), with validation diagnostics.
+- **Create:** Author new capabilities in explicit project (`.pi/forge/capabilities/`) or global (`~/.pi/forge/capabilities/`) scope.
+- **Edit and Save:** Edit display name, description, instruction content, and tool additions/removals. Capability IDs are immutable on save.
+- **Grouped tool picker:** Capability tool selection (`+add` / `-remove`) includes a grouped picker organized by SDK `sourceInfo` (Pi built-in tools, packages, and top-level entry points). The picker saves exact concrete tool names: it does not persist package references or auto-install packages, and newly introduced tools from packages are not automatically added. Inactive registered tools remain visible in the picker; unloaded tools are unavailable in the session, but manually saved references are not discarded.
+- **Delete:** Delete capability JSON files with confirmation.
+- **Stale-save protection (`sourceRevision`):** Save and delete operations require the displayed `sourceRevision` (sha256 of raw source bytes). Stale requests fail with `409 Conflict`, preserving the user's draft in the editor.
+- **Resource safety and save execution impact:** Saving a capability updates its library definition only and never activates it into the active session. Invalid JSON fails closed locally with diagnostics. Symlink targets and directories cannot be mutated.
+
+### Preset Capability bindings tab
+
+In the Preset editor, capability bindings are configured under the dedicated peer **Capability bindings** tab (`bindings`); Preset metadata no longer contains bindings:
+
+- **Qualified capability reference:** Requires a qualified reference (`project:<id>` or `global:<id>`).
+- **Binding ID and metadata:** Unique binding identifier within the Preset; activation controls accept IDs up to 128 characters.
+- **Agent authorization:** Toggle `modelCallable` (defaults to `false`) to permit Agent selection via `forge_capability`.
+- **Collapsed advanced section:** Overrides and source-effective preview are collapsed under an advanced section to keep the primary binding list clear.
+- **Finite overrides:**
+  - **Content override:** Choose between *None (use base content)*, *Replace* (`content`), or *Append* (`appendContent`, separated by two newlines).
+  - **Tool overrides:** Independently choose *Inherit* (omit the field) or *Custom override* (literal list, including explicit `[]` to clear the source list), with the integrated tool picker.
+  - Arbitrary fields, scripts, or inheritance chains cannot be authored.
+- **Source vs. effective preview:** Side-by-side comparison displays source content/tools alongside effective content/tools, resolved through the same server resolver (`resolveCapabilityBindings`) as runtime activation.
+- **Stale-save guard:** Preset saves enforce a `sourceRevision` check against disk bytes whenever bindings are present or modified, rejecting stale overwrites (409 Conflict), including when external edits added bindings.
+- **Preset save execution impact:** Saving an inactive Preset updates its definition and does not select or activate it. Crucially, saving the currently active Preset immediately reloads and synchronizes its live tool and capability authorization policy in the session, without replacing frozen active capability snapshots. If the proposed policy conflicts with those snapshots, saving or overwriting the active Preset is rejected before writing the file; disable the conflicting capability and retry. Editing files outside Forge bypasses this preflight and may require manual recovery after reload.
+
+## Web session capabilities panel
+
+The web editor retains a global **Session capabilities** summary linking to the non-modal **Current session** workspace: capability/tool controls beside the current session projection. The Preset editing workspace retains its own Preview/Draft diff/Run diff dock; navigation preserves unsaved edits and inspection layout.
+
+### State display and active capabilities
+
+- **Active capabilities list:** Lists active capabilities and manual directives for the current session. Each card provides:
+  - **Identity and source:** Activation ID, display name, and resolved source (e.g. `project:review`, `global:review`, or `manual`).
+  - **Actor:** Attribution indicating whether the capability was activated by the `user` or an `agent`.
+  - **Frozen snapshot content:** A visible excerpt plus an expandable view of the exact literal rule text captured upon activation.
+  - **Tool adjustments and effective tools:** Cards label configured patches separately from current effective tools. The latest successful action in this browser shows observed net additions/removals; overlapping Capabilities can leave the effective set unchanged.
+- **Delivery and presentation indicators:**
+  - **Delivery status:** Displays `none` (no capability events recorded yet), `pending` (updates queued for next request), or `prepared` (request context assembled for the current turn). The panel notes that `prepared` indicates prompt context preparation only, not remote model compliance or delivery confirmation.
+  - **Text presentation:** Indicates whether capability instructions are projected as `native` system message sections or attributed `user` timeline updates.
+- **Session controls:**
+  - **Individual deactivation:** Click **Deactivate** to turn off a specific capability by its `activationId`.
+  - **Reset confirmation:** The **Reset all** button initiates a two-step confirmation prompt (**Confirm reset** / **Cancel**) before clearing active capabilities and manual directives.
+- **Prompt cache usage:** When prompt caching statistics exist on the current branch, the panel renders prompt-cache hit rates and request counts for the current turn and session, maintaining visible separation between main assistant requests and nested tool runs. See [Session cache usage](session-cache.md).
+
+### Human activation picker (guarded preview and use)
+
+The panel includes a human activation picker section:
+
+- **Session projection (`GET /api/capability-state/preview`):** Read-only inspection of the active saved Preset and current capability snapshots, with session/leaf/revision and active-Preset fingerprint checks before and after compilation. The Preview sidecar links actual projected update blocks to activation IDs without modifying prompt messages. Requires a trusted session and active Preset; missing/stale context fails explicitly. This does not prepare a request, synchronize tools, or prove provider delivery/cache reuse.
+- **Resource discovery (`GET /api/capability-state/available`):** Pure read-only endpoint returning current session state and available choices categorized into *Library capabilities (unbound)* and *Current preset (bound)*. Read operations never mutate tool policies or session events.
+- **Explicit pre-activation preview:** Selecting a capability in the dropdown renders an immediate pre-activation preview card displaying:
+  - Label, ID, kind badge (`library` or `preset binding`), and short content fingerprint (`#<hash>`).
+  - Tool diff preview (`+add`, `-remove`, or `No tool changes`).
+  - Problem banner if the capability fails tool policy validation.
+  - Full literal instruction content.
+- **Guarded activation (`POST /api/capability-state/enable`):**
+  - Payload sends `{ guard: { sessionId, leafId, revision }, kind, id, fingerprint }`.
+  - Server re-verifies session guard and content fingerprint against disk definitions before applying.
+  - If the session, branch, revision, or source file changed, the server rejects with `409 Conflict`.
+  - Never automatically infers or retries.
+  - Modifying requires project trust (`isProjectTrusted() === true`); untrusted sessions reject with `403 Forbidden`.
+
+### Polling, state guarding, and security
+
+- **Visibility-based polling with zero inference:** The web client quietly polls `GET /api/capability-state` every 3 seconds only while visible (`document.visibilityState === "visible"`), on window focus, or via manual refresh. Catalog reads (`/api/capability-state/available`) happen on workspace entry, explicit refresh and mutation follow-up, not every status poll. Unchanged background checks do not toggle loading/disable controls. The session projection follows semantic state changes and ignores late responses after leaving. All queries are local reads with zero LLM inference cost.
+- **Manual reconciliation on error or conflict:** Errors, stale state, or 409 Conflicts mark the view as stale and require manual review. Mutations do not blindly retry.
+- **Project trust requirement:** Modifying session capabilities requires an explicitly trusted project (`isProjectTrusted() === true`). Untrusted sessions reject mutations with `403 Forbidden`; CLI recovery via `/capability reset` remains available.
+- **State guard and lifecycle protection:** Mutations enforce derived guards (`sessionId`, `leafId`, `revision`). Unmounted or disposed runtimes return `503 Service Unavailable`.
+
+### Local developer testing and host reload
+
+When testing in a local developer harness with local build wiring already configured:
+- Hot reloading the Pi host requires the user to run `/reload` in the Pi console.
+- If a web server was already active prior to `/reload`, run `/preset ui restart` in the host and open the newly returned URL. The pre-existing web server closure retains previous route handlers and will not pick up newly added routes upon host reload alone. Global host switching is not automatic.
+
+## Lifecycle and tool synchronization
+
+- **Unified `context_with_system` pipeline:** In Pi 0.87, standard `context` lifecycle hooks intentionally exclude System messages. Forge moves the complete compiler, base prompt replacement, and capability projection pipeline to `context_with_system` without an internal two-phase split.
+- **Canonical projection with `buildSessionProjection`:** Runtime, Preview, and anchor helpers build against Pi 0.87's canonical `buildSessionProjection` (handling `context_edit` omissions, replacements, and `sourceEntry`), ensuring ephemeral request assembly reflects turn edits while raw session history remains untouched on disk.
+- **Leading System preservation:** SDK incoming leading System prompts remain first; Forge's own prefix plain metadata anchors are inserted immediately after it.
+- **Continuation and settlement lifecycle:** `agent_end` remains an anchor opportunity after a low-level run, provided no Forge context failure or incomplete tool batch remains, but the compile cycle and busy fence reset only on `agent_settled`. This ensures `agent_before_settle` continuations preserve compiled Preset state without dropping active capabilities.
+- **Immediate tool sync vs. next-request prompt projection:**
+  - Executable tool selection synchronizes *immediately* (`pi.setActiveTools()`). Disallowed tools are blocked at execution time.
+  - Prompt text and native System sections or fallback user updates apply at the *next model request* boundary.
+  - Running tool batches mid-flight are never interrupted.
+- **Top-level policy precedence:** Capabilities cannot bypass Preset policies. If an active Preset denies a tool (`tools.deny`), a capability's `add` cannot enable it. Conflicting tool removals win globally across all active capabilities.
+- **Baseline recovery:** Turning off a capability recomputes Preset defaults plus remaining active capabilities. When neither Preset tool selection nor capability overlays apply, Forge restores the reconciled session baseline, including preserved external changes. If a baseline cannot be recovered, Forge does not guess that all registered tools were previously active.
+- **Parent lifecycle and re-entry fences:** Parent safeguards maintain `disposed` flags, `lifecycleRevision` counters, and strict `sameContext` verification, preventing cross-session pollution or operations after session disposal.
+
+## Previewing capability updates
+
+The **Preview** dock evaluates the selected Preset draft against current session capability snapshots:
+
+- Uses the same pure preset/capability projection as the request path: native named system sections or attributed user updates, including stop notices and compaction checkpoints.
+- Delivery markers are pure metadata anchors and do not appear as dialogue messages.
+- System body text, native named sections, and historical tool declarations are kept separate. Text copy contains only body/section values; inspector prose (`Added tool`, `Updated system prompt section`) is not inserted into native text.
+- Historical tool declarations are collapsed and explicitly marked as not the current selection.
+- Preview tool selection uses the evaluated draft policy plus current capability overlays.
+- Text estimates exclude tool schemas and inspector labels; genuinely empty post-projection System cards are hidden.
+- History is grouped only in consecutive runs: intervening capability updates stay in chronological position between surrounding messages.
+- Pure read-only inspection: Preview never mutates tool policies, commits session events, runs inference, or marks pending capabilities prepared. Full preview text is not clipped at layout limits.
+
+## Delivery models: native vs. fallback
+
+Forge projects capability deltas dynamically on each request through a two-stage assembly:
+
+1. **Materialize before compilation:** Session context entries are projected via `buildSessionProjection` and scanned for plain `custom` metadata anchors (`pi-forge-capability-delivery`). At the request context boundary (`prepareCapabilityMessages`), anchors are validated and materialized into ephemeral in-memory markers at their exact ordinal positions matching the canonical projection, without modifying stored dialogue or raw session history.
+2. **Rule projection:** `projectCapabilityMessages` transforms materialized deltas into the appropriate model presentation:
+   - **Native delivery:** When the provider supports mid-conversation system messages (`compat.supportsMidConvoSystemMessages === true`), updates are projected as request-only `SystemMessage.sections` keyed by activation identity (`forge-capability-<id>`). Deactivations send null patches. Native delivery depends strictly on provider capability flags and is not universally guaranteed.
+   - **Fallback delivery:** When native updates are unsupported, updates are projected as attributed timeline user messages (`[pi-forge capability update]`). Forge never folds updates into the leading system prompt; genuine user/tool dialogue is never promoted to system authority.
+   - **Tool-only capabilities:** A capability whose text is empty or whitespace-only sends no text update in either path — no section on activation, no removal notice when it stops, and nothing in compaction checkpoints. Only its tool changes reach the request, and **Current session** offers no Locate action for it.
+   - **Which path applies:** The choice is made on each request from the current model's `compat` entry in Pi's model catalog, which Pi fetches and caches locally and may change with updates. The provider name, authentication method, or an auth extension does not decide it, and models from one provider can differ. For example, the catalog observed on 2026-09-26 with Pi 0.87.1 flagged `anthropic/claude-opus-4-8`, `claude-opus-5`, and `claude-opus-5-5`, but not `anthropic/claude-sonnet-5`. Switching with `/model` changes delivery for later requests. `/capability status` and the Agent `status` action report `native system sections` or `attributed user updates`; check this before testing native updates or cache behavior. See [Provider support](provider-support.md) for the per-API behavior and flagged models recorded for Pi 0.87.1.
+   - **Fallback side effects:** For unflagged models, Pi also folds its own tool-change declarations into the leading system message and top-level tool list, so a tool change rewrites the start of the next request and its cached prefix is not reused. Some models may treat the labeled user update as untrusted text and question it before using the new tools.
+
+## Recovery and offline verification
+
+Active state is derived deterministically from session events and delivery cursors (`throughEventId`):
+
+- **Plain metadata delivery anchors:** Delivery markers are stored as plain `custom` session entries using the same delivery type (`pi-forge-capability-delivery`) with cursor-only metadata payload `{ schemaVersion: 1, throughEventId }`. They are not persisted as `custom_message` dialogue and do not use `sendMessage` steering. Idle updates anchor immediately; in-flight changes safely defer until after all tool results in a running batch complete; and `agent_end` anchors uncommitted deltas after the assistant's final response when no Forge context failure or incomplete batch remains. UI status notifications (`ctx.ui.setStatus`) are decoupled and never enqueue extra model turns.
+- **Offline SDK verification:** State recovery across session reloads, manual compaction checkpoints, and branch tree navigation (`session.navigateTree`) is verified offline using SDK test harnesses. This confirms prompt assembly and tool gating, but does not provide an empirical guarantee of remote model compliance or obedience.
+- **Compaction input and characterization:** Compaction checkpoints remain placed after the leading system prompt (`leadingSystem`) and before the compaction `summary` (placement unchanged; the upstream Pi metadata chunking bug is an independent issue and remains unfixed). Characterization tests verify real SDK summarization request inputs with simulated summaries. In this characterization, the summarizer observes user, assistant, and peer dialogue, but does not automatically receive new control metadata or request-only rule projections. Genuine dialogue quoting rule text is retained. Test-harness simulated responses verify request plumbing and harness shape, not remote LLM semantic compaction fidelity or summarizer compliance.
+- **Breaking pre-release boundary:** This rename has no legacy aliases or readers. Existing development configs using instruction-mode keys, schemas, directories, or tool names must be converted to the new capability names, and sessions that contain the old capability state are unsupported for continuing that state. Forge does not rewrite old JSONL or historical summaries; start a new session after conversion rather than relying on partial restoration.
+- **Session disk flushing:** In fresh sessions where only slash commands execute before the first assistant turn, Pi may not have flushed JSONL entries to disk yet.
+
+## 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.
+- **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.
+- **System prompt getters:** `ctx.getSystemPrompt()` and SDK getters return Pi's raw base prompt, not Forge's compiled request. Inspect compiled requests via `/forge payload` (bare `/payload` remains compatible) or Run context diffs. Forge does not claim to synchronize SDK getters. Extensions returning a full `systemPrompt` in lifecycle hooks cause forced projection conflicts and are unsupported.
+- **Provider-managed tool transport and prompt caching:** Tool transport serialization and prompt prefix cache reuse are downstream provider-managed. Tool policy additions/removals, fallback formatting, and compaction alter prompt boundaries. For compatible Codex transports, clean first-time tool additions can retain request prefixes; removals or same-name redeclarations anywhere in retained history switch to full-current-tool serialization. Anthropic native tool changes and other per-API behavior are summarized in [Provider support](provider-support.md). Provider cache hits are not guaranteed. Pi-forge issues conservative provider-managed cache warnings and makes no permission bypass or caching guarantees (zero KV cache invalidation is not guaranteed).
+- **Sandbox disclaimer:** Capabilities provide no OS-level sandboxing or process isolation. The demo `review.json` removes `bash`, `powershell`, `write`, and `edit`, but does not block external MCP tools or subagents. Configure tool removals matching your specific execution tools.
+
+## Implementation status (0.5.5)
+
+The 0.5.5 core functional implementation is delivered in source across all planned lanes:
+
+- Foundation codecs, scoped discovery, semantic events, and immutable snapshot reducer.
+- Human CLI commands (`/capability` add, list, bindings, enable, enable-bound, disable, status, reset).
+- Formal plain metadata delivery anchor projection with pre-compilation ordinal materialization.
+- Web Session capabilities activity panel and guarded human activation picker (`GET /api/capability-state/available`, `POST /api/capability-state/enable`).
+- Live Preset bindings (`capabilities`) in dedicated peer Capability bindings tab, with finite overrides, collapsed advanced view, and opt-in `modelCallable: true`.
+- Restricted model-callable `forge_capability` agent tool (list, status, enable, disable, ID ≤ 128 chars).
+- Web Capabilities surface (CRUD) with SDK-grouped tool picker and `sourceRevision` stale-save guards.
+- Preset policy custom default tools editor (`tools.initial?: string[]`) with concrete names, zero-default support (`[]`), and legacy fallback on omission.
+- 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.
+
+
+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/commands.md

@@ -2,23 +2,41 @@
 
 [Documentation](../README.md) · [中文](../zh-CN/reference/commands.md)
 
-Arguments in brackets are optional. Commands that write project files require a trusted project.
+Arguments in brackets are optional. Main pi-forge command arguments are strict: unknown flags and extra arguments are rejected. Commands that write project files require a trusted project.
 
-## Prompt stacks
+## Forge commands
+
+`/forge` is the canonical root. With no arguments it opens Forge command help; `/forge help` does the same.
+
+| Command | Behavior |
+|---|---|
+| `/forge ui [stop\|restart]` | Open, stop, or explicitly restart the local web editor. |
+| `/forge payload next [save=<path> [--overwrite]]` | Arm capture of the next provider-hook payload, display it, and optionally save it. Quote paths containing spaces, for example `save="path with spaces.json"`. |
+| `/forge payload status` | Show whether a capture is pending and whether a latest capture exists. |
+| `/forge payload cancel` | Cancel only the pending next-capture request. It does not delete or reset retained captures or context-diff history. |
+| `/forge payload help` | Show payload syntax and capture boundaries. |
+| `/forge subagent plan ...` | Optional execution-plan command supplied by the matching `@zihanw/pi-forge-subagents` package. Duplicate contributors fail closed. |
+
+`/forge payload` and bare `/payload` both arm the next capture. `/intercept` remains a compatibility shortcut for the same arm-without-save operation. A save never overwrites an existing file unless `--overwrite` is present; `--overwrite` is valid only with `save=<path>`; an armed capture does not call a model. Capture is taken at `before_provider_request`, so later plugin shaping may change the final wire body. Saved payloads may contain prompt and conversation text even when credential-shaped fields are redacted.
+
+The legacy `/subagent` command is a separate low-level smoke helper. It is not the actual `/forge subagent plan` execution-plan command.
+
+## Prompt presets
 
 | Command | Behavior |
 |---|---|
-| `/preset list` | List stacks and activation/validation state. |
-| `/preset status` | Show the selected stack and diagnostics summary. |
-| `/preset use <id>` | Validate and select a stack. |
-| `/preset use none` | Disable prompt stacks for this session branch. `off` is accepted as an alias. |
-| `/preset preview [id]` | Compile and display a stack without provider transport. Defaults to the selected stack. |
-| `/preset validate [id]` | Validate one stack or all stacks when omitted. |
+| `/preset list` | List presets and activation/validation state. |
+| `/preset status` | Show the selected preset and diagnostics summary. |
+| `/preset use <id>` | Validate and select a preset. |
+| `/preset use none` | Disable prompt presets for this session branch. `disable` is accepted as an alias. |
+| `/preset preview [id]` | Compile and display a preset without provider transport. Defaults to the selected preset. |
+| `/preset validate [id]` | Validate the selected preset when omitted, or one named preset when supplied. It does not validate every preset by default. |
 | `/preset diagnostics` | Show loader, runtime, policy, regex, and trusted-extension diagnostics. |
-| `/preset reload` | Reload stacks and trusted macro/slot registrations. |
-| `/preset ui [stop\|restart]` | Open, stop, or replace the local web editor. |
+| `/preset reload` | Reload presets and trusted macro/slot registrations. |
+| `/preset ui [stop\|restart]` | Compatibility lifecycle entry for the local web editor; prefer `/forge ui`. |
+| `/preset help` | Show preset command help. |
 
-## Storage migration and import
+## Storage migration
 
 | Command | Behavior |
 |---|---|
@@ -32,30 +50,40 @@ Use migration dry runs before overwriting or deleting anything.
 |---|---|
 | `/profile list` | List project profiles and resolution diagnostics. |
 | `/profile use <id>` | Preflight and apply a profile once. |
-| `/profile save <id> [--overwrite]` | Capture the current model, thinking level, and stack. |
+| `/profile save <id> [--overwrite]` | Capture the current model, thinking level, and preset. |
 | `/profile status` | Compare current runtime with last-applied branch provenance. |
-| `/profile preview <id>` | Resolve model/auth/thinking/stack/tools without applying. |
-| `/profile validate [id]` | Validate one profile or all profiles when omitted. |
+| `/profile preview <id>` | Resolve model/auth/thinking/preset/tools without applying. |
+| `/profile validate [id]` | Validate all loaded profiles when omitted, or one named profile when supplied. |
 | `/profile reload` | Reload definitions without applying them. |
 | `/profile forget` | Remove last-applied provenance without changing runtime state. |
+| `/profile help` | Show profile command help. |
 
-## Experimental foreground delegation
+## Capabilities
 
-The commands below are provided by the optional `@zihanw/pi-forge-subagents` package.
+`/capability` is the command for managing session capabilities.
 
 | Command | Behavior |
 |---|---|
-| `/forge-agent backends` | List registered experimental backends, capabilities, and effective defaults. |
-| `/forge-agent plan <profile> [--backend <id>] <task>` | Prepare, validate, display, and discard an exact plan without provider transport. |
-| `/forge-agent run <profile> [--backend <id>] <task>` | Review and approve an exact foreground read-only run. |
+| `/capability add <text>` | Add a literal manual instruction. |
+| `/capability list` | Explicitly reload and list the capability library. |
+| `/capability bindings` | List bindings on the active preset, including human-only bindings (`modelCallable: false`). |
+| `/capability enable <[scope:]id>` | Enable an unbound library capability. |
+| `/capability enable-bound <id>` | Enable a binding from the active preset. |
+| `/capability disable <activation-id>` | Disable one active capability. |
+| `/capability status` | Show active capabilities and effective tools. |
+| `/capability reset` | Disable all active capabilities and manual directives. |
+| `/capability help` | Show usage and compatibility notes. |
+
+Completions use the current session and last published workspace snapshot. They do not scan resources on every keystroke. Use `/capability list` for an explicit discovery refresh. Human-only bindings remain visible in `bindings`; `modelCallable: false` only prevents Agent control.
 
-Only explicitly scoped profiles are accepted: use `project:<id>` or `global:<id>` keys in `subagents.json`. A bare authorization key always means `project:<id>`, even in the global file; `.pi/forge/config.json.subagents` remains a read-only legacy fallback. The model-callable equivalents are `forge_subagent_profiles` (local discovery) and `forge_subagent` (execution). See the [delegation safety guide](../guides/delegation.md).
+## Optional foreground delegation
 
-## Payload inspection
+The following commands are supplied by the matching optional `@zihanw/pi-forge-subagents` package, not by main pi-forge:
 
 | Command | Behavior |
 |---|---|
-| `/intercept` | Display the next redacted provider payload. |
-| `/payload next [save=<path>]` | Display the next payload, optionally save it, and expose it to the web editor. |
+| `/forge-agent backends` | List registered backends, capabilities, and effective defaults. |
+| `/forge-agent plan <profile> [--backend <id>] <task>` | Prepare, display, and discard an exact plan without provider transport. |
+| `/forge-agent run <profile> [--backend <id>] <task>` | Prepare a foreground run, always ask for human approval, then execute through the selected backend. A backend may write; this is not inherently read-only. |
 
-Saved payloads may include prompt and conversation text even though credential-shaped fields are redacted. Handle them as potentially sensitive.
+Only explicitly scoped profiles are accepted by the optional package: use `project:<id>` or `global:<id>` keys in its `subagents.json`. The model-callable equivalents are `forge_subagent_profiles` (local discovery) and `forge_subagent` (execution). The model-callable `forge_subagent` tool is a separate path. Its unattended behavior is controlled by explicit trusted-project authorization; it is not a way to bypass the approval requirement of `/forge-agent run`. See the [delegation safety guide](../guides/delegation.md).

package/docs/reference/configuration.md

@@ -21,6 +21,8 @@ The port is preferred, not guaranteed. The editor binds only to `127.0.0.1` and
 
 ## Experimental subagents
 
+The explicit non-boolean approval-flag handling described below remains an unreleased companion source fix; published `@zihanw/pi-forge-subagents` 0.5.3 does not contain it. It is optional-package work, not a Forge 0.5.5 main-package feature. Configuration parsing belongs to that optional package, not the Forge host.
+
 Subagent configuration is owned by the optional `@zihanw/pi-forge-subagents` package. Dedicated files are `.pi/forge/subagents.json` for a trusted project and `~/.pi/forge/subagents.json` for user defaults. Legacy `.pi/forge/config.json` / `~/.pi/forge/config.json` `subagents` sections are read-only fallback material and emit a warning.
 
 User defaults may set general settings:
@@ -50,11 +52,11 @@ Trusted project `subagents.json` may override defaults, authorize individual pro
 }
 ```
 
-Valid timeouts are 1,000–3,600,000 ms. Invalid fields warn and fall back to the preceding applicable default. General backend precedence is project then user then built-in; an interactive run and a project profile entry can further override it as described in [delegation](../guides/delegation.md#backends-and-precedence).
+Valid timeouts are 1,000–3,600,000 ms. Invalid timeout fields warn and fall back to the preceding applicable default. General backend precedence is project then user then built-in; a matching profile entry and an interactive per-run override can further override it as described in [delegation](../guides/delegation.md#backends-and-precedence).
 
 `summaryInToolDescription` (default `false`) embeds a compact, bounded summary of enabled subagent profiles directly in the `forge_subagent` tool description so the parent model can pick a profile without a discovery call. Ready profiles appear first, and unavailable enabled profiles include their first resolution error. It may be set in user or trusted-project `subagents.json` and applies wherever it is enabled.
 
-Profile authorization keys should use canonical selectors: `project:<id>` or `global:<id>`. A bare key is a compatibility spelling for `project:<id>` regardless of which config file contains it; it never authorizes a global profile. Therefore a global profile must be written explicitly as `"global:reviewer": { "enabled": true }` in `~/.pi/forge/subagents.json`. Same-ID profiles never inherit enablement, backend, or timeout policy from each other. `allowAgentInvocationWithoutApproval` is project-only, requires trust, and fails closed when malformed. Deleting a profile does not modify `subagents.json`; remove any enabled entry for the deleted profile manually.
+Profile authorization keys should use canonical selectors: `project:<id>` or `global:<id>`. A bare key is a compatibility spelling for `project:<id>` regardless of which config file contains it; it never authorizes a global profile. Therefore a global profile must be written explicitly as `"global:reviewer": { "enabled": true }` in `~/.pi/forge/subagents.json`. Same-ID profiles never inherit enablement, backend, or timeout policy from each other. `allowAgentInvocationWithoutApproval` may be supplied by global defaults or a trusted project file; the project value overrides the global value, and the execution trust gate still blocks delegation from an untrusted project. When that flag is absent at a layer it inherits; an explicitly non-boolean value sets that layer to `false` and emits a warning, while 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 any earlier valid layer remains effective. Deleting a profile does not modify `subagents.json`; remove any enabled entry for the deleted profile manually.
 
 Treat project configuration as an authorization boundary. In particular, do not commit unattended delegation unless every permitted parent agent may transmit compiled prompt and readable project content without another human approval.
 

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+. Published Pi SDK dependencies are host-provided wildcard peers; exact repository versions are reproducible development/test fixtures rather than runtime constraints.
+- 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.
 - Project trust check before loading prompt stacks.
 - Footer status showing the active prompt stack.
 
@@ -55,7 +55,7 @@ This file tracks the currently implemented feature surface for agent profiles, t
 - `/preset migrate-stacks [--dry-run] [--overwrite] [--delete-legacy]` copies legacy stacks into the forge storage location.
 - `default.json` auto-activation unless `autoActivate` is `false`.
 - Branch-aware persisted active stack restore from session entries.
-- Persisted `/preset use none` / `off` opt-out.
+- Persisted `/preset use none` / `disable` opt-out.
 - Invalid stacks with error diagnostics are skipped by automatic selection.
 - Raw stack fields are shape-checked before recovery normalization, including behavior-changing booleans/enums, defaults, context, variables, and item fields.
 - Stack validation for duplicate item IDs, duplicate stack IDs, unsupported slots, missing chat-history slots, and ignored items.
@@ -172,6 +172,15 @@ This file tracks the currently implemented feature surface for agent profiles, t
 - `/preset reload`
 - `/preset ui [stop|restart]`
 - `/preset migrate-stacks [--dry-run] [--overwrite] [--delete-legacy]`
+- `/capability add <text>`
+- `/capability list`
+- `/capability bindings`
+- `/capability enable <[scope:]id>`
+- `/capability enable-bound <id>`
+- `/capability disable <activation-or-capability-id>`
+- `/capability status`
+- `/capability reset`
+- `/capability help`
 - `/intercept`
 - `/payload next [save=<path>]`
 
@@ -199,7 +208,7 @@ This file tracks the currently implemented feature surface for agent profiles, t
 - Resource inventory and preview remain usable when a reclaimed editor host is refreshed from lifecycle contexts that do not expose command-only prompt APIs.
 - Stack list with active/error/warning indicators.
 - Collapsible prompt-stack sidebar.
-- Collapsible stack metadata panel and main-area tabs for Items, Regex, Policy, and Stack JSON/context/variables work.
+- Preset properties from the resource header, with peer Stack, Regex, Policy, Bindings and Advanced editing tabs; the separate Preview/Draft diff/Run diff dock stays alongside the editor.
 - Light/dark theme toggle, button icons, and tooltips for common actions.
 - English/中文 interface switch (`webEditor.locale`: `"en"`, `"zh-CN"`, or `"auto"` following the browser language); contributed settings tabs remain provider-authored and are not translated.
 - Unsaved-change badge in the top bar.
@@ -229,7 +238,7 @@ This file tracks the currently implemented feature surface for agent profiles, t
 - Export the current edited stack JSON from the browser, with clipboard fallback when download is unavailable.
 - Fork the current stack into a new stack file, with optional activation.
 - Delete stack files, disabling prompt-stack replacement if the deleted stack was active.
-- Trust and path guardrails for save/import/fork/delete writes.
+- Built-in Web writes cover Presets, Profiles, Capabilities, and trusted Forge configuration, with trust and path guardrails for save/import/fork/delete operations.
 - Top-level navigation between prompt stacks and project agent profiles; stack drafts, selection, and active state survive surface switches.
 - Profile list shows ID, name, model/thinking/stack targets, validation state, and `autoActivate` and last-applied badges.
 - Profile create, edit, validate, save, one-shot apply, and delete reuse the shared resolver, transactional application service, and guarded repository; save rejects a second auto-activation profile and on-disk conflicts.
@@ -237,3 +246,60 @@ This file tracks the currently implemented feature surface for agent profiles, t
 - A runtime/provenance card distinguishes current runtime, last-applied provenance, source-definition state, and per-field runtime drift after external model, thinking-level, or stack changes.
 - The main web editor no longer ships a delegation card; delegation configuration is owned by the optional `@zihanw/pi-forge-subagents` package through `.pi/forge/subagents.json`.
 - Smoke tests cover editor server token checks, bundled page/script markers, save, payload arm/capture/clear, create/fork, native JSON import, collision handling, delete, and stop behavior.
+
+## 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).
+- 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.
+- Fail-closed project-over-global shadowing for bare IDs; invalid local definitions fail closed with diagnostics and never fall back to global definitions.
+- Scoped selectors (`project:<id>` and `global:<id>`) for targeting exact definitions.
+- Local execution with zero inference cost: `/capability` commands and Web activity panel actions update internal session state and tool policy without invoking model inference or consuming API tokens.
+- Unified `context_with_system` lifecycle: whole compiler, base prompt replacement, and capability projection pipeline moved to `context_with_system` without an internal two-phase split.
+- Canonical session projection via `buildSessionProjection`: runtime, preview, and anchor locator helpers reflect turn-level `context_edit` omissions, replacements, and `sourceEntry` tracking without mutating raw session JSONL history on disk.
+- Leading System prompt preservation: SDK incoming leading System message always remains first; Forge prefix plain metadata delivery anchors are inserted immediately after it.
+- Settlement lifecycle and continuations: `agent_end` acts as an anchor commit boundary after tool batches or turns; compile cycle and busy fence reset only on `agent_settled` so `agent_before_settle` continuations preserve compiled Preset inputs.
+- Immediate executable tool policy synchronization (`setActiveTools`) paired with next-model-request prompt text and section declaration delivery. Running tool batches are not killed mid-flight.
+- Top-level Preset policy precedence: capability additions cannot enable tools denied by the active Preset (`tools.deny`); tool removals win globally across all active capabilities.
+- Tool baseline recovery: restores session tools to a pristine baseline upon capability disable, adopting a conservative baseline when a session has no recorded baseline.
+- Delivery via plain `custom` session entries carrying cursor-only metadata (`pi-forge-capability-delivery` with `{ schemaVersion: 1, throughEventId }`), replacing transcript `sendMessage` steering and `custom_message` carriers.
+- Pre-compilation ordinal materialization into ephemeral in-memory markers at exact session positions matching canonical projection order.
+- Request-only projection to native `SystemMessage.sections` (`forge-capability-<id>`) when supported by the provider, or fallback attributed user timeline updates (`[pi-forge capability update]`).
+- Compaction input characterization: metadata delivery anchors and request-only rule text do not enter summarizer inputs while dialogue history is preserved.
+- Breaking pre-release rename: no legacy aliases or readers are provided for the former instruction-mode schema, directories, or continuing capability state. Convert development configuration and start a new session; old JSONL and summaries are not rewritten.
+- Provider-managed prompt cache warning: prompt caching and tool transport are downstream provider-managed; no guarantee of zero KV cache invalidation or exact cache hits.
+
+## Preset Capability Bindings
+
+- Declarative `capabilities` binding list in the Preset schema.
+- Qualified capability references (`project:<id>`, `global:<id>`), unique binding IDs (≤ 128 characters), and opt-in `modelCallable: boolean` (defaults to `false`).
+- Finite overrides: either content replacement (`content`) or paragraph append (`appendContent` with two newlines), and independent whole-array replacement for `tools.add` and/or `tools.remove`.
+- Source-effective preview via the shared server resolver (`resolveCapabilityBindings`).
+- Stale-save guard using `sourceRevision` checking against raw file bytes, rejecting concurrent or external edits (409 Conflict) whenever bindings are present or modified.
+- Same-Preset reload preserves immutable active snapshots; switching Presets retires old bound activations while retaining manual/unbound rules.
+- Revocation behavior: disabling `modelCallable` does not retroactively erase active snapshots; human CLI or Web deactivation is the recovery path.
+
+## Agent Capability Controls
+
+- Model-callable tool `forge_capability` registered when an active Preset includes bound capabilities.
+- Fixed parameter schema: `{ action: "list" | "status" | "enable" | "disable", id?: string }` (ID ≤ 128 characters).
+- Re-verifies project trust, active Preset existence, binding existence, `modelCallable: true`, and current tool policy on every call.
+- Strict actor ownership: agent can only activate authorized bindings; agent `disable` can only stop its own agent-owned activations; agent cannot stop human rules, reset capabilities, add arbitrary prompt text, or remove `forge_capability`.
+- Repeated use is idempotent and does not take over ownership from user to agent.
+- Fences against disposed runtimes, restoring sessions, and cross-session re-entry.
+
+## Web Editor Capabilities and Session Activity
+
+- Top-level **Capabilities** surface for project and global capability CRUD with validation diagnostics.
+- Capability writes and deletions require `sourceRevision` checking against raw file bytes; 409 Conflict on stale views preserves user drafts.
+- Capability saves never activate definitions into the active session.
+- Dedicated peer **Capability bindings** tab in the Preset editor with binding configuration, `modelCallable` toggle, finite overrides, and live source vs effective preview.
+- Global **Session capabilities** summary opens the non-modal **Current session** workspace, pairing controls with the active saved Preset/session projection and showing active capabilities, actor attribution (`user`/`agent`), collapsible frozen snapshots, tool deltas, effective tools, delivery status (`none`/`pending`/`prepared`), and presentation mode.
+- Human activation picker with available capabilities (`GET /api/capability-state/available`) categorized into Library capabilities (unbound) and Current preset (bound).
+- Explicit pre-activation preview displaying label, ID, badge, fingerprint, tool diff, problem banner, and full literal content.
+- Bodyguard activation (`POST /api/capability-state/enable`) requiring session guard (`sessionId`, `leafId`, `revision`) and source fingerprint validation, rejecting stale or modified sources (409 Conflict) without automatic retry or inference.
+- Read-only resource discovery and Preview never mutate tool policies, commit session events, or mark pending capabilities as prepared.
+- Quiet state polling (every 3 seconds while visible, and on focus) with zero inference; catalog discovery occurs on workspace entry, explicit refresh and mutation follow-up, not each status poll.
+
+The [Read-first Worker example](capabilities.md#read-first-worker) demonstrates default reading tools plus a model-authorized `bash`/`edit` capability. It is a tool-selection pattern, not a sandbox.