@zihanw/pi-forge 0.4.1 → 0.5.1

package/docs/guides/delegation.md

@@ -4,33 +4,31 @@
 
 > **Experimental:** This API and its backends may change independently of stable prompt-stack and profile behavior.
 
-pi-forge can execute 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 as a separate, clean, one-shot Pi process. It runs in the foreground and returns a bounded report to the parent conversation.
 
 ## Enable a profile
 
-Profiles are not delegatable by default. Enable each eligible ID in the trusted project's `.pi/forge/config.json`, or use the profile's delegation card in `/preset ui`:
+Profiles are not delegatable by default. Enable each eligible ID in the trusted project's `.pi/forge/subagents.json`:
 
 ```json
 {
-  "subagents": {
-    "backend": "pi-subprocess-readonly",
-    "timeoutMs": 60000,
-    "profiles": {
-      "reviewer": {
-        "enabled": true,
-        "timeoutMs": 300000
-      },
-      "rpc-reviewer": {
-        "enabled": true,
-        "backend": "pi-rpc-readonly",
-        "timeoutMs": 180000
-      }
+  "backend": "pi-subprocess-readonly",
+  "timeoutMs": 60000,
+  "profiles": {
+    "project:reviewer": {
+      "enabled": true,
+      "timeoutMs": 300000
+    },
+    "project:rpc-reviewer": {
+      "enabled": true,
+      "backend": "pi-rpc-readonly",
+      "timeoutMs": 180000
     }
   }
 }
 ```
 
-Enablement follows the profile's scope. A global `~/.pi/forge/config.json` may define general `backend` and `timeoutMs` defaults and may authorize `global:<id>` profiles through its own `profiles` map. The trusted project's `.pi/forge/config.json` authorizes `project:<id>` profiles. Same-ID global and project profiles never inherit enablement, backend, or timeout policy from one another. Disabled or unlisted profiles are hidden from discovery and rejected even if guessed.
+Legacy `.pi/forge/config.json.subagents` is accepted as read-only fallback with a warning. Authorization keys should be canonical selectors: `project:<id>` or `global:<id>`. Bare keys remain a compatibility spelling for project profiles only, even inside `~/.pi/forge/subagents.json`; use an explicit key such as `global:reviewer` to authorize a global profile. Same-ID global and project profiles never inherit enablement, backend, or timeout policy from one another. Disabled or unlisted profiles are hidden from discovery and rejected even if guessed.
 
 ## Discover, plan, and run
 
@@ -49,7 +47,7 @@ Profile selectors accept the same grammar everywhere: `reviewer` (project first)
 
 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.
 
-Projects with only a few frequently used profiles can set `subagents.summaryInToolDescription: true` (global or trusted-project config). The `forge_subagent` tool description then carries a compact summary of enabled profiles—id, model, thinking level, stack, backend, and timeout—so the parent model does not need a discovery call to pick a profile. Ready profiles appear first; unavailable enabled profiles remain visible with their first resolution error so the model knows not to invoke them. The summary rides in every request, is capped at 8 profiles and 1,000 characters, and refreshes with profiles, stacks, and configuration; `forge_subagent_profiles` remains the authoritative full-detail surface.
+Projects with only a few frequently used profiles can set `summaryInToolDescription: true` (global or trusted-project `subagents.json`). The `forge_subagent` tool description then carries a compact summary of enabled profiles—id, model, thinking level, stack, backend, and timeout—so the parent model does not need a discovery call to pick a profile. Ready profiles appear first; unavailable enabled profiles remain visible with their first resolution error so the model knows not to invoke them. The summary rides in every request, is capped at 8 profiles and 1,000 characters, and refreshes with profiles, stacks, and configuration; `forge_subagent_profiles` remains the authoritative full-detail surface.
 
 ## Parallel invocation
 
@@ -74,13 +72,11 @@ To authorize the parent model without per-run approval:
 
 ```json
 {
-  "subagents": {
-    "allowAgentInvocationWithoutApproval": true
-  }
+  "allowAgentInvocationWithoutApproval": true
 }
 ```
 
-This affects only `forge_subagent`; `/forge-agent run` remains interactive. It is ignored in untrusted projects and malformed values fail closed. Treat this project config 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. 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.
 
 ## Child context and output
 
@@ -104,4 +100,4 @@ The current backends are **shared-user, not operating-system sandboxes**.
 
 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.
 
-For integration authors, see the [experimental adapter contract](../reference/subagent-adapter.md).
+For integration authors, see the [subagent host port contract](../reference/subagent-host-port.md).

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

@@ -0,0 +1,107 @@
+# Migrating to pi-forge 0.5
+
+[Documentation](../README.md)
+
+0.5.0 is a breaking cleanup release. This page is the migration note for the
+changes landed so far (Lane 1a-1c plus the compiler/extension conformance
+pass in Lane 1d).
+
+## What was removed
+
+- SillyTavern importer (`/preset import-silly`), its reports, guide, example,
+  and tests. Convert SillyTavern presets with pi-forge 0.4 before upgrading.
+- Mutable turn/session variables, variable mutation macros,
+  `pi-forge-variable-state` session entries, and the `variables` slot.
+- Regex `display` and `both` effects; `outgoing` and `finalize` remain.
+
+## Template syntax changes
+
+Prompt text now compiles with the closed `forge-v1` grammar.
+
+| 0.4 construct | 0.5 forge-v1 |
+|---|---|
+| `{{name}}` (static) | `{{ parameters.name }}` |
+| `{{lastUserMessage}}` | `{{ runtime.lastUserMessage }}` |
+| `{{date}}` / `{{time}}` / `{{cwd}}` | `{{ runtime.date }}` / `{{ runtime.time }}` / `{{ runtime.cwd }}` |
+| `{{tools}}` | `{{ runtime.selectedToolsText }}` |
+| `{{upper::x}}` | `{{ x \| upper }}` |
+| `{{iftools::bash::A::B}}` | `{% if runtime.tool.bash %}A{% else %}B{% endif %}` |
+| custom `{{myMacro}}` | `{{ extensions.myMacro }}` |
+
+Unknown paths, unknown filters, parse errors, cycles, and output-limit breaches
+are compile errors; a failing block is omitted instead of re-injecting raw
+template text.
+
+## Schema v2
+
+Schema v2 stacks store immutable static values in `parameters` (JSON-compatible)
+instead of the legacy string-only `variables` field:
+
+```json
+{
+  "schemaVersion": 2,
+  "parameters": { "char": "Konata" }
+}
+```
+
+Unversioned / v1 stacks continue to load through the legacy `variables` reader.
+
+## Running the migration utility
+
+A mechanical, diagnostics-first script converts a saved stack file:
+
+```bash
+node scripts/migrate-stack-v2.mjs .pi/forge/prompt-stacks/default.json --dry-run
+node scripts/migrate-stack-v2.mjs .pi/forge/prompt-stacks/default.json --write
+```
+
+It renames `variables` to `parameters`, maps runtime/parameter paths, and
+converts simple filter pipelines. Non-mechanical constructs are reported and
+the file is only written when they are absent. A schema v2 file that still
+contains a legacy `variables` field is left untouched and only warned about.
+
+## Preview and finalize
+
+Preview never applies `finalize`; it now reports an informational diagnostic.
+`finalize` remains a destructive, lifecycle-owned transform that replaces the
+stored assistant message.
+
+## Lane 2: scoped global profiles and prompt stacks
+
+- User-global resources now live in `~/.pi/forge/prompt-stacks` and `~/.pi/forge/agent-profiles` alongside the project stores. Profile and stack selectors accept explicit scopes: `project:<id>`, `global:<id>`, with bare IDs resolving project-first.
+- Same-ID project resources shadow their global counterparts; global stacks cannot reference project resources (and vice versa) — references resolve within the referenced resource's scope.
+- Untrusted projects fail closed: only global resources load, all mutation routes are rejected, and `session_shutdown` no longer disposes a trusted workspace while sessions may still be active (idle workspaces are swept after an hour; hosts stop independently).
+- The web editor gained scope selectors for creating stacks/profiles into either store and routes global mutations through explicit `global:<id>` selectors.
+
+## Lane 3: subagent package split
+
+Subagent execution moved out of the main package into the optional `@zihanw/pi-forge-subagents` package (requires `@zihanw/pi-forge@^0.5.0`). Install it separately to keep foreground delegation.
+
+- **Commands:** `/subagents` and `/subagent-run` were removed from the main package. The optional package registers `/forge-agent backends|plan|run`.
+- **Model tools:** `forge_subagent_profiles` and `forge_subagent` are registered by the optional package.
+- **Configuration:** `subagents.*` moved out of `.pi/forge/config.json` into dedicated `.pi/forge/subagents.json` (trusted project) and `~/.pi/forge/subagents.json` (user defaults). The optional package reads legacy `config.json.subagents` sections as a read-only fallback with a warning; it never writes them. Copy the values into `subagents.json` to silence the warning.
+- **Web editor:** the delegation card was removed from the main editor; edit `subagents.json` directly.
+- **Architecture:** the main package's prompt compiler is host-neutral (no subagent assumptions), and `ForgeWorkspace` is the single owner of resource state and compilation contexts.
+
+## Lane 4: Forge-native host contract and public surface
+
+- The main package no longer depends on `@zihanw/pi-subagent-runtime` and no longer exports the 0.4 execution contract. That contract (`AgentRequest`, `createAgentExecutionPlan`, `validateAgentRequest`, `negotiateSubagentTools`, preflight/plan/response validators, …) now lives in `@zihanw/pi-forge-subagents` for its own runtime wiring; it is not a public surface of either package for third-party consumers.
+- `@zihanw/pi-forge/subagent` now exports only the versioned host port: wire DTOs and validators, `ForgeHostTransport`, `ForgeHost`/`ForgeHostClient`, lifecycle constants, and the Forge-owned canonical fingerprint helpers. `resolveSubagentHostProfile` / `prepareSubagentHostPlan` were replaced by the host-port operations `resolveProfile` and `prepare`.
+- The package root exports only the default extension factory, `registerMacro`/`registerSlot`, and their contract types. All other root re-exports (loader, agent-profile, profile-service, catalog, resource-identity, render-helper values, the `forge-v1` engine, registry readers) were removed.
+- All `@zihanw/pi-forge/src/*` subpath aliases and the `./examples/*` export were removed; `check-package` rejects them.
+
+### Import migration table
+
+| 0.4 import | 0.5 replacement |
+|---|---|
+| `@zihanw/pi-forge` (default, `registerMacro`, `registerSlot`) | unchanged |
+| `@zihanw/pi-forge/subagent` host-port names (`ForgeHost*`, validators, fingerprints) | unchanged |
+| `@zihanw/pi-forge/subagent` execution contract (`AgentRequest`, `createAgentExecutionPlan`, …) | internal to `@zihanw/pi-forge-subagents`; no public replacement |
+| `@zihanw/pi-forge/subagent` `resolveSubagentHostProfile` / `prepareSubagentHostPlan` | host-port operations via `ForgeHostClient` |
+| `@zihanw/pi-forge/src/*` aliases | removed; no replacement (internals) |
+| root loader/profile/catalog/engine re-exports | removed; no replacement (internals) |
+
+## 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.
+- Vendored fingerprint helpers in the main package are pinned by golden vectors to stay byte-compatible with `@zihanw/pi-subagent-runtime` canonical serialization; plan sealing still happens only in the optional package.

package/docs/guides/use-cases.md

@@ -9,21 +9,21 @@ Use these as starting patterns rather than rigid templates. The [default Pi mirr
 Put long-lived character rules in a system block, runtime context in appropriate slots, and the current user action in an explicit final user block:
 
 1. System character/personality block.
-2. Tools, project context, variables, and other runtime slots.
+2. Tools, project context, and other runtime slots.
 3. `chat-history` with `includeLastUserMessage: false`.
-4. Final user block containing `{{lastUserMessage}}`.
+4. Final user block containing `{{ runtime.lastUserMessage }}`.
 
-This keeps the latest request clear and avoids duplication. Static `{{char}}` / `{{user}}` variables work well for character constants; turn/session macros can track temporary scene state. Durable project memory belongs in project files, not prompt variables.
+This keeps the latest request clear and avoids duplication. Static `{{ parameters.char }}` / `{{ parameters.user }}` values work well for character constants. Durable project memory belongs in project files, not parameters.
 
 ## Focused code review
 
 Start from [the reviewer example](../../examples/reviewer-prompt-stack.json). It denies writing tools, wraps prior history as background, omits the latest user message from history, then reinserts it as the explicit review target.
 
-Use a rule such as “prioritize correctness, regressions, security, and missing tests.” Keep tools, project context, variables, and history when the reviewer must inspect the repository. Use `append` to retain Pi's normal coding prompt, or `replace` when the stack must fully control prompt and skill visibility.
+Use a rule such as “prioritize correctness, regressions, security, and missing tests.” Keep tools, project context, and history when the reviewer must inspect the repository. Use `append` to retain Pi's normal coding prompt, or `replace` when the stack must fully control prompt and skill visibility.
 
 ## Translation mode
 
-Create a small stack with a system block for target language, register/tone, and terminology rules. Retain history and a final `{{lastUserMessage}}`. Separate literal translation, localization review, and bilingual editing into different stacks when their rules conflict.
+Create a small stack with a system block for target language, register/tone, and terminology rules. Retain history and a final `{{ runtime.lastUserMessage }}`. Separate literal translation, localization review, and bilingual editing into different stacks when their rules conflict.
 
 ## Multi-mode switching
 
@@ -48,13 +48,9 @@ Tool policy constrains model tool calls but is not an operating-system sandbox.
 
 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.
 
-## SillyTavern DM writer
-
-[The DM-writer example](../../examples/sillytavern-dm-writer-prompt-stack.json) defines a Dungeon Master through `{{char}}` / `{{user}}`, wraps prior adventure history, reinserts the current action, and uses deterministic regex cleanup for OOC notes, secret-roll markers, dice notation, and `Player:` prefixes.
-
 ## Payload lab
 
-Include `active-model`, `date-cwd`, and `variables`, 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 `/payload next` or the web editor's capture view to audit exactly what changed.
 
 ## Pi-docs expert
 
@@ -62,4 +58,4 @@ Allow read/search tools, include the `pi-docs` and project-context slots, and ke
 
 ## Trusted runtime status
 
-The [custom system-status example](../../examples/custom-system-status-extension/README.md) registers `{{cpuLoad}}` and a `machine-status` slot from trusted project code. Use this pattern for deterministic host data that cannot be represented as static stack JSON.
+The [custom system-status example](../../examples/custom-system-status-extension/README.md) registers `{{ extensions.cpuLoad }}` and a `machine-status` slot from trusted project code. Use this pattern for deterministic host data that cannot be represented as static stack JSON.

package/docs/guides/web-editor.md

@@ -38,30 +38,26 @@ The stack workspace provides:
 - validation and a full compiled preview;
 - registered-tool and loaded-skill search with exact-name chips and wildcard patterns;
 - raw JSON recovery for advanced or unknown fields;
-- native pi-forge and SillyTavern JSON import;
+- native pi-forge JSON import;
 - export, fork, and deletion;
 - payload arming and redacted captured-payload inspection;
 - light and dark themes.
 
-Existing IDs are immutable during edit. Use **Fork** to create a different ID without breaking profile references or the active selection. The toolbar scope selector (default `project`) chooses where new stacks, imports, and forks are written: `global` targets the user-global `~/.pi/forge/prompt-stacks`, `project` targets `.pi/forge/prompt-stacks`. Stack rows show a `global` badge, and save/delete routes use `global:<id>` for exact global mutations. Legacy stacks remain editable in place.
+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 stack** (default `Project`) chooses where new stacks, imports, and forks are written: `Global` targets the user-global `~/.pi/forge/prompt-stacks`, `Project` targets `.pi/forge/prompt-stacks`. Less-used capture, fork, import, export, and delete actions live under **More** so the stack and Preview/Diff panes keep the available viewport. Stack rows show a `global` badge, and save/delete routes use `global:<id>` for exact global mutations. Legacy stacks remain editable in place.
 
-Saves, imports, forks, and deletes reload stack state into the current Pi session. When another surface changes a referenced stack, returning to profiles refreshes profile resolution without discarding unsaved delegation fields.
+Saves, imports, forks, and deletes reload stack state into the current Pi session. When another surface changes a referenced stack, returning to profiles refreshes profile resolution.
 
 ## Agent-profile workspace
 
-The profile list shows each profile's ID, display metadata, model, thinking level, stack, resolution state, auto-activation, last-applied provenance, delegation status, and a `project`/`global` scope badge. Same-ID shadow pairs are marked `shadows global:<id>` or `shadowed by project:<id>`.
+The profile list shows each profile's ID, display metadata, model, thinking level, stack, 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 prompt-stack dropdown offers only global stacks. Model choices come from Pi's model registry, thinking choices reflect model support, and stack 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.
 
-## Delegation card
+## Delegation
 
-The profile delegation card edits the `subagents.profiles.<id>` values for the selected profile's scope: project profiles write to `.pi/forge/config.json`, global profiles write to `~/.pi/forge/config.json`. General defaults and `allowAgentInvocationWithoutApproval` remain config-file-only because they affect broader authorization.
-
-Unsaved delegation changes are guarded when selecting another profile, starting another profile operation, refreshing, deleting, or leaving/reloading the page. The card shows effective values and the source of each inherited or overridden setting.
-
-Read [foreground delegation](delegation.md) before enabling a profile.
+Delegation configuration is not part of the main editor. The optional `@zihanw/pi-forge-subagents` package owns the dedicated `.pi/forge/subagents.json` and `~/.pi/forge/subagents.json` files. Read [foreground delegation](delegation.md) before enabling a profile.
 
 ## Migration
 

package/docs/reference/commands.md

@@ -23,9 +23,8 @@ Arguments in brackets are optional. Commands that write project files require a
 | Command | Behavior |
 |---|---|
 | `/preset migrate-stacks [--dry-run] [--overwrite] [--delete-legacy]` | Copy legacy `.pi/prompt-stacks` files into `.pi/forge/prompt-stacks`. |
-| `/preset import-silly <path> [character_id] [--dry-run] [--overwrite]` | Convert a SillyTavern preset and write a migration report. |
 
-Use migration/import dry runs before overwriting or deleting anything. See [SillyTavern import](../guides/sillytavern-import.md).
+Use migration dry runs before overwriting or deleting anything.
 
 ## Agent profiles
 
@@ -42,13 +41,15 @@ Use migration/import dry runs before overwriting or deleting anything. See [Sill
 
 ## Experimental foreground delegation
 
+The commands below are provided by the optional `@zihanw/pi-forge-subagents` package.
+
 | 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. |
 
-Only project-authorized delegation profiles are accepted. The model-callable equivalents are `forge_subagent_profiles` (local discovery) and `forge_subagent` (execution). See the [delegation safety guide](../guides/delegation.md).
+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).
 
 ## Payload inspection
 

package/docs/reference/configuration.md

@@ -18,31 +18,30 @@ The port is preferred, not guaranteed. The editor binds only to `127.0.0.1` and
 
 ## Experimental subagents
 
-User configuration may set general defaults:
+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:
 
 ```json
 {
-  "subagents": {
-    "backend": "pi-subprocess-readonly",
-    "timeoutMs": 60000
-  }
+  "backend": "pi-subprocess-readonly",
+  "timeoutMs": 60000
 }
 ```
 
-Trusted project configuration may override defaults, authorize individual project profile IDs, and authorize unattended model invocation:
+Trusted project `subagents.json` may override defaults, authorize individual project profile IDs, and authorize unattended model invocation:
 
 ```json
 {
-  "subagents": {
-    "backend": "pi-subprocess-readonly",
-    "timeoutMs": 60000,
-    "allowAgentInvocationWithoutApproval": false,
-    "profiles": {
-      "reviewer": {
-        "enabled": true,
-        "backend": "pi-rpc-readonly",
-        "timeoutMs": 180000
-      }
+  "backend": "pi-subprocess-readonly",
+  "timeoutMs": 60000,
+  "allowAgentInvocationWithoutApproval": false,
+  "summaryInToolDescription": false,
+  "profiles": {
+    "project:reviewer": {
+      "enabled": true,
+      "backend": "pi-rpc-readonly",
+      "timeoutMs": 180000
     }
   }
 }
@@ -50,9 +49,9 @@ Trusted project configuration may override defaults, authorize individual projec
 
 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).
 
-`subagents.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 configuration and applies wherever it is enabled.
+`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.
 
-`profiles` in global configuration authorizes `global:<id>` profiles; the trusted project's `profiles` authorizes `project:<id>` profiles. 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 clears delegation policy only from the matching scope's config.
+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.
 
 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

@@ -1,6 +1,6 @@
 # Implemented feature inventory
 
-This file tracks the currently implemented feature surface for agent profiles, the prompt-stack runtime, template variables, web editor, SillyTavern importer, storage migration, payload inspector, and regex MVP.
+This file tracks the currently implemented feature surface for agent profiles, the prompt-stack runtime, static stack variables, web editor, storage migration, payload inspector, and regex MVP.
 
 ## Package and Runtime
 
@@ -33,31 +33,16 @@ This file tracks the currently implemented feature surface for agent profiles, t
 - Project trust gates profile loading, application, and writes.
 - Shared typed profile services own capture, protected write/update/delete, application/rollback, immutable preview data, provenance changes, and runtime-drift calculation so command, web-editor, and adapter consumers do not duplicate behavior.
 
-## Subagent Adapter Contract
+## Subagent Host Port
 
-- Dedicated experimental `@zihanw/pi-forge/subagent` entry point, with the existing package-root exports retained for 0.4 compatibility.
-- Subagent types, canonicalization, request/preflight validation, tool negotiation, context preparation, plan construction, response validation, and diagnostics live in focused modules behind a compatibility contract barrel.
-- Exported pure v1 `AgentRequest`, profile snapshot, backend preflight, execution-plan, enforcement-receipt, and discriminated response types without registering or shipping a runner.
+- Experimental versioned `@zihanw/pi-forge/subagent` entry point: the minimal Forge DTO host contract (wire messages, recursive exact-field validators, transport-neutral `ForgeHostTransport`, `ForgeHost`/`ForgeHostClient` lifecycle) plus Forge-owned canonical `sha256:v1` fingerprint helpers byte-compatible with the runtime's canonical JSON.
+- Mandatory lifecycle semantics: bounded discovery timeouts, explicit duplicate-host failure, `hostId`+`generation`-bound request/reply with stale/foreign rejection, disposal with `unavailable` and full listener cleanup. The host starts only after the first workspace snapshot exists, so an advertised host implies a loaded workspace; reload honors project trust (untrusted workspaces expose global resources only).
+- Three minimal operations: `listProfiles` (loaded profile summaries with diagnostics), `resolveProfile` (immutable host-owned profile snapshot artifact with content fingerprints), and `prepare` (host-owned prompt compilation).
+- Host-owned preparation: the client sends only a profile selector, the task text, prompt-compilation access facts (`level`/`network`/`allowProcess`), and backend facts (model, thinking level, tool catalog). The workspace resolves the profile and stack from its snapshot, filters the tool catalog through stack policy and access facts, and compiles through the same compilation context as runtime and preview. Responses return the system prompt, messages ending with the protected delegated task, effective tool IDs/names, diagnostics, the profile snapshot, and `preparedAt`.
+- The port never exposes live contexts, internal registries, or execution/runtime material (access workspace model, limits, `resultProjection`, `parent`, `remoteEgressConsent`, base system prompt). The delegated-task base system prompt is host-owned and intentionally empty; the prompt stack composes the system prompt.
 - Backend-independent host profile resolution produces path-free declarative snapshots and does not consult the parent model registry or authentication state.
 - Host dependency scanning detects custom macro and slot references, records registration source identities, and fails resolution when required registrations are missing.
-- Backend tool negotiation intersects prompt-stack name policy with declared filesystem/process/network effects and per-request access.
-- Optional empty-by-default backend registry validates registration and preflight identity, requires the backend to supply a complete fingerprinted prompt runtime, binds the exact host preparation to execution, routes dry-plan discard, rejects unbound or refingerprinted substitute plans, arbitrates cancellation and host timeouts, normalizes failures, and protects opaque trace routing behind authorization-scoped handles.
-- Experimental `pi-subprocess-readonly` backend reuses the host Pi runtime for authenticated preparation, then runs a clean foreground Pi subprocess with the exact profile model, thinking level, and compiled prompt. Its candidate model tools are limited to `read`, `grep`, `find`, and `ls`, further filtered by prompt-stack policy; it loads no write/shell tools, skills, prompt templates, context files, or third-party extensions. Host-coupled capability mismatches fail closed during preflight.
-- Delegation is an explicit per-profile opt-in under the trusted project's `subagents.profiles`; ordinary profile loading/application remains independent. Global profile entries warn and are ignored so project-local profile IDs cannot silently authorize unrelated projects. Disabled and unlisted profiles are omitted from `forge_subagent_profiles` and rejected before preparation by the command, model-callable tool, and concrete runtime.
-- The no-egress `forge_subagent_profiles` tool gives the main agent a live catalog of enabled profile IDs, names, descriptions, model/thinking/stack metadata, effective backend/timeout and sources, and ready/unavailable resolution status. It also reports whether the parent tool policy currently permits `forge_subagent`.
-- `subagents.summaryInToolDescription` (default `false`) embeds a compact, bounded summary of enabled profiles directly in the `forge_subagent` tool description, so the main agent can pick a frequently used profile without a discovery call. Ready profiles sort first, unavailable enabled profiles include their first resolution error, and the summary is capped at 8 profiles and 1,000 characters. It refreshes whenever profiles, stacks, or configuration change and keeps `forge_subagent_profiles` as the authoritative full-detail surface.
-- The model-callable `forge_subagent` tool and `/forge-agent run` prepare an immutable plan before provider transport. `/forge-agent run` and the default tool path require explicit human approval; a trusted-project `subagents.allowAgentInvocationWithoutApproval` option may authorize only the model-callable tool without a per-run prompt. The default review shows the task, profile/stack, provider/model/thinking level, effective tools, working directory, shared-user boundary, payload size, and fingerprint; the complete provider-bound prompt can be opened on demand.
-- Backend selection is layered configuration rather than profile schema: `subagents.backend` supplies global/project defaults, the trusted project's `subagents.profiles.<id>.backend` supplies a per-profile override, and `/forge-agent plan|run --backend <id>` or the interactive `forge_subagent` `backend` parameter overrides one run. Both the `pi-subprocess-readonly` and `pi-rpc-readonly` backends are registered; there is no fallback when the selected backend is unavailable, and unattended tool invocation is pinned to the effective configured profile backend.
-- Foreground timeout is layered host configuration rather than profile schema: `subagents.timeoutMs` supplies a 60,000-millisecond default and `subagents.profiles.<id>.timeoutMs` can override it per profile; values must be from 1,000 through 3,600,000 milliseconds. Invalid values warn and preserve the preceding valid/default value; discovery, planning, and approval surfaces show the effective best-effort timeout and source.
-- Foreground progress and the bounded final report enter the normal tool-call result. A dedicated child report channel retains the normalized response, complete text transcript, tool calls/results, diagnostics, usage, approval receipt, and execution report without persisting the full prompt or inline image data; omitted images retain MIME and encoded-size metadata.
-- The subprocess backend is explicitly shared-user rather than OS-sandboxed: read-only is a tool policy, host timeout/cancellation are best effort, and `/tree` reverts conversation state rather than provider egress, billing, or external side effects.
-- `/forge-agent backends` and `/forge-agent plan <profile> <task>` expose backend discovery and provider-free exact dry planning to a human.
-- Deterministic fake-backend conformance coverage exercises accepted/rejected preflight, tool effects, access/limit refusal, exact preparation, success/failure, cancellation races, timeout, media, artifacts, and traces. An offline faux-provider test additionally executes the concrete SDK backend through a real Pi `AgentSession` without network traffic.
-- Selected parent context uses explicit provenance and deterministic exact UTF-8 budgeting; required items survive, optional items are selected newest-first, and the complete delegated text/media task remains the protected final user message.
-- Granular validators cover request access/depth/media/limits, backend capabilities and enforcement, prompt-runtime fidelity, plan correlation, all response terminal statuses, usage units, artifact namespaces/paths, and authorized trace handles.
-- Portable profile, prompt-stack, and complete execution fingerprints use canonical `sha256:v1` serialization without changing legacy branch-provenance fingerprints.
-- The opt-in internal Pi SDK spike remains available for broader live diagnostics, including media and trusted custom registrations beyond the shipped text-only walking skeleton.
-- Adapter responsibilities and unsupported runner behavior are documented in the [subagent adapter contract](subagent-adapter.md).
+- Execution ownership (delegation authorization in `subagents.json`, the 0.4 execution contract, backend preflight/plan sealing via `@zihanw/pi-subagent-runtime`, approval UX, `forge_subagent`/`forge_subagent_profiles`, and `/forge-agent`) lives in the optional `@zihanw/pi-forge-subagents` package, which consumes this port and never imports main-package internals. See the [subagent host port contract](subagent-host-port.md).
 
 ## Prompt Stack Loading and Storage
 
@@ -70,7 +55,6 @@ 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.
-- Branch-aware macro session variable restore when navigating the session tree.
 - Persisted `/preset use none` / `off` 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.
@@ -105,7 +89,7 @@ This file tracks the currently implemented feature surface for agent profiles, t
 - `effect: "outgoing"` is active for model-bound prompt text.
 - `effect: "finalize"` is active for completed assistant messages at `stage: "compiled"` / `targets: ["messages"]`.
 - `effect: "finalize"` is destructive: it replaces the finalized assistant message in Pi's stored transcript, so the original model output is not preserved.
-- `effect: "display"` and `"both"` validate with warnings and are ignored until true display transforms are implemented.
+- `effect: "outgoing"` and `"finalize"` are the only valid effects; `"display"` and `"both"` are rejected during validation.
 - Streaming display is not transformed; raw text may be visible until the final message replacement happens.
 - Message transforms support role filters, `maxMessages`, `maxChars`, `minDepth`, `maxDepth`, and `trimStrings`. `$0` is supported as a full-match alias for `$&` in replacements.
 - Compiled-stage transforms support `targets: ["system"]`, `["messages"]`, or both.
@@ -125,7 +109,6 @@ This file tracks the currently implemented feature surface for agent profiles, t
 - `date-cwd`
 - `active-model`
 - `pi-docs`
-- `variables`
 - `date` and `date-cwd` slots can include `Current time: HH:MM:SS` with `includeTime: true`.
 - Runtime slots are registered through the same `registerSlot` definition interface used by trusted custom slots.
 - Trusted `~/.pi/forge/extensions` / `.pi/forge/extensions` modules and reusable Pi packages can register additional runtime slots through `registerSlot`, with declarative option schemas and shared render helpers.
@@ -139,36 +122,29 @@ This file tracks the currently implemented feature surface for agent profiles, t
 - Tool policy is enforced with `pi.setActiveTools()` and restored when prompt stacks are disabled or switched to an unrestricted stack.
 - Tool policy preserves later extension tool additions in the restorable baseline while keeping them filtered from an active restrictive stack.
 - A `tool_call` guard blocks tools outside the active stack policy even if another extension later changes Pi's active tool list.
-- Rendered `tools` slots, tool macros such as `{{tools}}`, and `tool-guidelines` respect stack tool policy.
+- Rendered `tools` slots, template paths such as `{{ runtime.selectedToolsText }}`, and `tool-guidelines` respect stack tool policy.
 - Rendered `skills` slots respect stack skill policy and continue to hide skills marked `disableModelInvocation`.
 - Skill policy controls model-visible skill listings rendered by pi-forge; it does not disable explicit skill invocation and is not a security boundary.
 - Validation warns when skill policy is used with `append` or `prepend` mode because Pi's base prompt may already include unfiltered skills.
 
-## Macros
+## Macros (forge-v1)
 
-- Built-in macros: `{{cwd}}`, `{{date}}`, `{{time}}`, `{{lastUserMessage}}`, `{{selectedTools}}`, `{{tools}}`, `{{activeModel}}`.
-- Built-in macros are registered through the same `registerMacro` definition interface used by trusted custom macros.
-- Parser-backed macro expansion supports nested `{{...}}` expressions and `::` argument splitting at the current macro depth.
-- Filter macros: `{{trim::value}}`, `{{upper::value}}`, `{{lower::value}}`, `{{json::value}}`, and `{{xml::value}}`.
-- Lazy conditional macros: `{{ifvar::name::then::else}}`, `{{ifeq::name::expected::then::else}}`, `{{iftools::tool::then::else}}`, and `{{ifslot::slot::then::else}}`. Only the selected branch is expanded.
-- Trusted `~/.pi/forge/extensions` / `.pi/forge/extensions` modules and reusable Pi packages can register additional macros through `registerMacro`, with argument metadata and shared runtime/variable/helper access.
-- `getRegisteredMacros()` and `getRegisteredSlots()` expose the active macro/slot definitions for implementation references and UI/resource inspection.
-- Static stack variables from `stack.variables`.
-- Turn/session/static lookup through `{{getvar::name}}`, `{{var::name}}`, and bare `{{name}}`.
-- Turn variable mutation through `{{setvar::name::value}}`, `{{setturnvar::name::value}}`, and `{{clearvar::name}}`.
-- Session variable mutation through `{{setsessionvar::name::value}}`, `{{setvar::session::name::value}}`, and `{{clearsessionvar::name}}`.
-- Unknown macro diagnostics with configurable keep/warn/error policy.
-- Non-string variable values stringify as JSON during macro substitution.
+- Prompt text is compiled with the closed `forge-v1` template engine (parse → analyze → render).
+- Runtime facts resolve through `{{ runtime.* }}` (cwd, date, time, lastUserMessage, selectedToolsText, activeModel, tool/slot booleans).
+- Static values resolve through `{{ parameters.* }}`; schema v2 stores them in `parameters` while v1 stacks read legacy `variables`.
+- Custom macros resolve through `{{ extensions.<name> }}` and are registered via the pure `registerMacro` extension port with declared dependencies and bounded output.
+- Filters: `trim`, `upper`, `lower`, `json`, `xml`, composed with `|` pipelines.
+- Conditionals: `{% if path %}...{% else %}...{% endif %}` with `==` / `!=` string comparisons over template paths.
+- Undefined paths, unknown filters, parse errors, cycles, and output-limit breaches are compile errors; a failing block is omitted rather than re-injected.
+- Legacy v1 stacks keep a bare-name compatibility fallback (`{{name}}`, `{{lastUserMessage}}`, `{{date}}`, ...) that maps to the corresponding parameter/runtime path.
+- `getRegisteredMacros()` and `getRegisteredSlots()` expose active definitions for inspection.
 
-## Template Variables
+## Parameters
 
-- Static string variables from `stack.variables`.
-- JSON-compatible session variable values: string, number, boolean, null, arrays, and objects.
-- Session variable snapshots restore from the current session tree branch, so tree navigation rolls macro variables back/forward with history.
-- Valid `<variables>` rendering from the `variables` slot.
-- XML variable entries rendered as `<var name="...">...</var>`.
-- Optional `format: "plain"` variables slot rendering.
-- Scope toggles with `includeStatic`, `includeSession`, and `includeTurn`.
+- Schema v2 stacks store immutable JSON-compatible values in top-level `parameters`.
+- Schema v1 / unversioned stacks read the legacy string-only `variables` field and support bare `{{name}}` fallback.
+- Parameters resolve through `{{ parameters.<name> }}` and are available to trusted custom macros/slots through the frozen environment.
+- Mutable turn/session stores, variable mutation macros, session variable entries, and the `variables` slot are removed in 0.5.0.
 
 ## Commands
 
@@ -180,9 +156,9 @@ This file tracks the currently implemented feature surface for agent profiles, t
 - `/profile validate [id]`
 - `/profile reload`
 - `/profile forget`
-- `/forge-agent backends`
-- `/forge-agent plan <profile> <task>`
-- `/forge-agent run <profile> <task>`
+- `/forge-agent backends` (optional `@zihanw/pi-forge-subagents` package)
+- `/forge-agent plan <profile> <task>` (optional package)
+- `/forge-agent run <profile> <task>` (optional package)
 - `/preset list`
 - `/preset status`
 - `/preset use <id|none>`
@@ -192,29 +168,9 @@ 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]`
-- `/preset import-silly <path> [character_id] [--dry-run] [--overwrite]`
 - `/intercept`
 - `/payload next [save=<path>]`
 
-## SillyTavern Import
-
-- Import SillyTavern preset JSON into `.pi/forge/prompt-stacks/<id>.json`.
-- Generate import reports under `.pi/forge/import-reports/<id>.md`.
-- Select a specific `character_id` when multiple prompt orders exist.
-- Protect existing generated stack/report files from accidental overwrite, with confirmation or `--overwrite`.
-- Preview generated output without writing files via `--dry-run`.
-- Convert prompt order into prompt stack items.
-- Preserve original SillyTavern identifiers in item source metadata.
-- Convert `chatHistory` marker to a movable `chat-history` slot.
-- Skip unsupported SillyTavern marker items and report omissions.
-- Detect `{{lastUserMessage}}` and configure chat history accordingly.
-- Strip SillyTavern comments and `{{trim}}` markers.
-- Report macros that need manual migration, including normalized camelCase SillyTavern macro names.
-- Report supported SillyTavern-style variable macros such as `setvar` and `getvar` as handled by pi-forge.
-- Report SillyTavern `extensions.regex_scripts` counts, prompt/display classification, script names, and migration notes.
-- Convert safe SillyTavern `promptOnly` regex scripts into pi-forge `regex.rules` with `stage: "history"`, `effect: "outgoing"`, JavaScript replacement syntax, trim strings, depth limits, clear placement role mappings, and preserved `source.sillytavern` metadata. History-stage depth is relative to the filtered chat history, matching SillyTavern's chat-relative depth.
-- Leave SillyTavern display-only, mixed prompt/display, DOM/browser, CSS/HTML decoration, JavaScript, unsupported-placement, unsupported-flag, and invalid regex scripts as report-only migration notes.
-
 ## Debugging and Tests
 
 - `/intercept` displays the next provider payload with redaction/truncation for secrets and large data.
@@ -223,10 +179,9 @@ This file tracks the currently implemented feature surface for agent profiles, t
 - The web editor can arm, poll, clear, and inspect the next redacted provider payload in a full-screen collapsible JSON inspector.
 - Runtime compile diagnostics are visible through a footer status and `/preset diagnostics`.
 - `/preset ui` starts a token-protected localhost web editor for stack management.
-- Node built-in tests cover agent-profile resolution/application/provenance, compiler, loader, SillyTavern importer, and the command/event harness.
-- Tests cover variable rendering, XML escaping, macro persistence, and typed macro stringification.
+- Node built-in tests cover agent-profile resolution/application/provenance, compiler, loader, regex, and the command/event harness.
 - Tests cover regex validation, history-stage transforms, compiled-stage transforms, finalize transforms, replacement syntax, trim strings, depth limits, role/message/char limits, and preservation of non-text message parts.
-- Tests cover subagent host resolution, custom dependency detection, all access/required-limit/terminal-status matrices, effect-aware tool negotiation, context budgeting, protected media tasks, canonical fingerprint tamper detection, and malformed external contract values.
+- Tests cover subagent host resolution, custom dependency detection, effect-aware tool negotiation, golden canonical fingerprint vectors, and malformed host-port wire values. Execution-contract matrices (access/required-limit/terminal-status, context budgeting, protected media tasks) moved to the optional package's contract tests.
 - A real headless-Chrome smoke test covers editor load, dirty state, metadata editing, policy and regex editing, validation, save, disk persistence, export, import, and browser-console errors.
 - TypeScript strict typecheck passes.
 - Package dry-run verifies published tarball contents.
@@ -265,16 +220,15 @@ This file tracks the currently implemented feature surface for agent profiles, t
 - Save existing stack JSON and immediately reload pi-forge stack data.
 - Save rejects attempts to change an existing stack ID before writing or changing active selection.
 - Keyboard shortcuts for new stack, save, validate, preview, and closing dialogs/inspectors.
-- Import native stack JSON or SillyTavern preset JSON into `.pi/forge/prompt-stacks`; SillyTavern uploads are converted automatically.
-- Show the SillyTavern import report in the web editor after import, with copy support.
+- Import native pi-forge stack JSON into `.pi/forge/prompt-stacks`.
 - 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.
 - 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, `autoActivate` and last-applied badges, and a `subagent` badge for delegation-enabled profiles.
+- 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.
 - Profile form populates provider/model choices from the model registry and stack choices from the shared stack repository, and shows resolution diagnostics for missing models, authentication, unsupported thinking levels, invalid stacks, and unmatched tool policy.
 - 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.
-- Per-profile delegation card toggles the trusted project's `subagents.profiles.<id>` opt-in with backend and timeout overrides, writing `.pi/forge/config.json` while preserving unrelated keys and removing emptied entries; the card reports the effective backend/timeout and source, warns about unregistered backends, and keeps project defaults and the unattended-invocation setting read-only.
-- Smoke tests cover editor server token checks, bundled page/script markers, save, payload arm/capture/clear, create/fork, SillyTavern JSON import conversion, collision handling, delete, and stop behavior.
+- 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.