@zihanw/pi-forge 0.4.1 → 0.5.0

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.

package/docs/reference/macros-and-slots.md

@@ -1,56 +1,59 @@
-# Macros and runtime slots
+# Forge-v1 templates and runtime slots
 
 [Documentation](../README.md)
 
-## Value macros
+Prompt text is compiled with the `forge-v1` engine: one closed grammar with no
+includes, loops, function calls, or arbitrary expressions. Preview, runtime,
+and subagent preparation use the same engine entry.
 
-| Macro | Value |
-|---|---|
-| `{{lastUserMessage}}` | Latest user message |
-| `{{date}}` | Current date as `YYYY-MM-DD` |
-| `{{time}}` | Current time as `HH:MM:SS` |
-| `{{cwd}}` | Current working directory |
-| `{{tools}}` | Comma-separated selected tool names |
-| `{{selectedTools}}` | Alias of `{{tools}}` |
-| `{{activeModel}}` | Current `provider/model` |
-| `{{name}}` | Turn, session, then static variable lookup |
-| `{{var::name}}` / `{{getvar::name}}` | Explicit scoped-fallback variable lookup |
-| `{{getturnvar::name}}` | Turn-only lookup |
-| `{{getsessionvar::name}}` | Session-only lookup |
-
-## Variable mutation
+## Template interpolation
 
-```text
-{{setvar::name::value}}             set a turn variable
-{{setturnvar::name::value}}         set a turn variable
-{{setsessionvar::name::value}}      set a session variable
-{{setvar::session::name::value}}    set a session variable
-{{clearvar::name}}                  clear using normal scope behavior
-{{clearturnvar::name}}              clear a turn variable
-{{clearsessionvar::name}}           clear a session variable
-```
+| Syntax | Value |
+|---|---|
+| `{{ runtime.cwd }}` | Current working directory |
+| `{{ runtime.date }}` | Current date as `YYYY-MM-DD` |
+| `{{ runtime.time }}` | Current time as `HH:MM:SS` |
+| `{{ runtime.lastUserMessage }}` | Latest user message |
+| `{{ runtime.selectedToolsText }}` | Comma-separated effective tool names |
+| `{{ runtime.activeModel }}` | Current `provider/model` |
+| `{{ parameters.<name> }}` | Static stack parameter |
+| `{{ extensions.<name> }}` | Registered custom macro value |
 
-Turn variables reset for each message. Session variables follow Pi's active session-tree branch. Static variables come from top-level `stack.variables`. Non-string JSON-compatible values stringify as JSON during substitution.
+Legacy v1 stacks keep a compatibility fallback: bare `{{name}}` resolves to a
+static parameter, `{{lastUserMessage}}`/`{{date}}`/`{{time}}`/`{{cwd}}` resolve
+to the matching `runtime.*` value, and registered custom macros resolve by
+name. New v2 stacks use the explicit `parameters.*` / `runtime.*` paths.
 
-## Filters and conditionals
+## Filters
 
-Nested macros are supported. `::` separators are parsed only at the current macro depth.
+Nested pipelines are supported; filters are pure and versioned.
 
-| Macro | Result |
+| Filter | Result |
 |---|---|
-| `{{trim::value}}` | Trim surrounding whitespace |
-| `{{upper::value}}` | Uppercase value |
-| `{{lower::value}}` | Lowercase value |
-| `{{json::value}}` | JSON string literal |
-| `{{xml::value}}` | XML-escaped value |
-| `{{ifvar::name::then::else}}` | Select by variable existence |
-| `{{ifeq::name::expected::then::else}}` | Select by equality |
-| `{{iftools::tool::then::else}}` | Select by effective tool name |
-| `{{ifslot::slot::then::else}}` | Select by enabled slot name |
+| `{{ value \| trim }}` | Trim surrounding whitespace |
+| `{{ value \| upper }}` | Uppercase |
+| `{{ value \| lower }}` | Lowercase |
+| `{{ value \| json }}` | JSON string literal |
+| `{{ value \| xml }}` | XML-escaped |
+
+## Conditionals
+
+```text
+{% if runtime.tool.read %}read is available{% else %}read is unavailable{% endif %}
+{% if parameters.mode == "image-reader" %}image reader{% endif %}
+{% if runtime.tool.bash != null %}bash visible{% endif %}
+```
 
-The final `else` is optional. Branches are lazy: skipped branches are not expanded and cannot mutate variables.
+- `{% if path %}` selects the branch when the path exists and is truthy.
+- `==` / `!=` compare against a quoted string, including empty strings.
+- Nested `{% if %}` blocks are supported.
+- An undefined output path is a strict compile error (no raw fallback); the
+  legacy `defaults.unresolvedMacroPolicy` is ignored.
+- `runtime.tool.<name>` and `runtime.slot.<name>` booleans power tool/slot
+  conditionals without function calls.
 
-Unknown macro behavior is controlled by stack `defaults.unknownMacro`: keep, warn, or error according to schema validation.
+When a block fails to parse, analyze, or render, pi-forge emits an error
+diagnostic and omits that block rather than re-injecting raw template text.
 
 ## Built-in slots
 
@@ -62,21 +65,39 @@ Unknown macro behavior is controlled by stack `defaults.unknownMacro`: keep, war
 | `skills` | Model-visible loaded Pi skills |
 | `project-context` | Trusted project instructions/context |
 | `append-system-prompt` | Pi's appended system prompt text |
-| `variables` | Static/session/turn values |
 | `date` | Current date, optionally time |
 | `cwd` | Working directory |
 | `date-cwd` | Date and working directory, optionally time |
 | `active-model` | Selected provider/model |
 | `pi-docs` | Pi documentation guidance |
 
-Structured slots (`tools`, `tool-guidelines`, `skills`, `project-context`, `variables`) default to XML-style wrappers and support `"format": "plain"`.
-
-Notable Pi-mirror options include `tools.onlyWithSnippets`, `tool-guidelines.heading`, `tool-guidelines.includePiDefaultGuidelines`, `tool-guidelines.piStyle`, and `skills.requireReadTool`. `date` and `date-cwd` support `includeTime: true`.
+Structured slots (`tools`, `tool-guidelines`, `skills`, `project-context`)
+default to XML-style wrappers and support `"format": "plain"`.
 
-`variables` supports `includeStatic`, `includeSession`, `includeTurn`, and `format`.
+## Trusted custom definitions
 
-The complete `chat-history` option set is documented in [stack schema](stack-schema.md#chat-history-options).
+Trusted global/project modules register macros (addressed as
+`{{ extensions.<name> }}`) and slots through the pure extension port:
+
+```ts
+api.registerMacro({
+  name: "ticketId",
+  description: "Current ticket id.",
+  dependencies: ["parameters.ticket.id"],
+  render: ({ env, helpers }) => String(env.parameters["ticket.id"]),
+});
+
+api.registerSlot({
+  name: "ticket-context",
+  description: "Render ticket context.",
+  dependencies: ["parameters.ticket.id"],
+  options: { heading: { type: "string", default: "Ticket context" } },
+  render: ({ item, options, env, helpers }) => "...",
+});
+```
 
-## Trusted custom definitions
+Custom slots receive the same pure `{ item, options, env, helpers }` context and
+declared-dependency resolution as macros, and their output is held to the same
+16,384-character extension limit.
 
-Trusted global/project modules and reusable Pi packages can register additional macro and slot names. The runtime exposes the active definitions through `getRegisteredMacros()` and `getRegisteredSlots()`. See [custom macros and slots](../guides/custom-macros-and-slots.md).
+See [custom macros and slots](../guides/custom-macros-and-slots.md).

package/docs/reference/public-api.md

@@ -1,28 +1,75 @@
 # Public API policy
 
-pi-forge is pre-1.0. This document separates supported integration surfaces from experimental 0.4 work and compatibility paths that should not become permanent dependencies.
+[Documentation](../README.md)
 
-## Stable
+pi-forge is pre-1.0. This document defines the intentional integration surfaces of the 0.5.0 line.
 
-- The package default export is the Pi extension entry point declared by `pi.extensions`.
-- Package-root macro and slot registration APIs (`registerMacro`, `registerSlot`, their registry readers, render contexts, and declarative definition types) are supported for trusted reusable extensions.
-- `ForgeExtensionApi` and related registration types are supported for trusted project-local forge extensions.
+## The three intentional entry points
 
-Stable means changes should preserve source compatibility within the documented supported release range unless a changelog entry explicitly announces a breaking release.
+`check-package` enforces this allowlist; nothing else is importable from the package.
 
-## Experimental
+### 1. Package root: extension factory
 
-- Agent-profile repository, resolution, application, preview, provenance, and drift APIs are 0.4 experimental surfaces.
-- The runner-neutral subagent contract and host-resolution helpers are 0.4 experimental surfaces. Backend registration, sealing, lifecycle, and the fresh-process backends moved to `@zihanw/pi-subagent-runtime`; Forge consumes them through its public runtime API.
-- New subagent integrations should import from `@zihanw/pi-forge/subagent`. The package root continues to re-export the current subagent names through 0.4 for compatibility.
+```ts
+import piForge from "@zihanw/pi-forge";
+```
 
-Experimental APIs are typed, tested, and documented, but may change in later releases as adapter and parent-integration experience exposes missing semantics. Changes should still be deliberate and recorded.
+The default export is the Pi extension entry point declared by `pi.extensions`. Most users install the package and never import it directly.
 
-## Internal compatibility paths
+### 2. Package root: trusted extension API
 
-- `@zihanw/pi-forge/src/*` subpath exports exist for compatibility with earlier source-shaped imports. They resolve to compiled `dist` modules and are not a promise that every implementation module is a permanent public API.
-- Browser-only `@zihanw/pi-forge/src/web-editor/client/*` implementation paths are explicitly blocked. The editor is distributed only through its generated embedded assets; these authored modules have never been a runtime integration surface.
-- The package root re-exports `@zihanw/pi-forge/subagent` contract names directly from the focused contract modules. The former `src/subagent-contract.ts` compatibility barrel and the `scripts/subagent-sdk-spike*` diagnostic harness were removed in the 0.4 cleanup.
-- Physical `src/` files are not included in the npm tarball. Runtime installation and legacy `@zihanw/pi-forge/src/*` aliases use compiled `dist` modules; source inspection or modification requires a repository clone.
+```ts
+import { registerMacro, registerSlot } from "@zihanw/pi-forge";
+import type {
+  ForgeExtensionApi,
+  ForgeExtensionRegister,
+  PromptEnvironment,
+  PromptEnvironmentValue,
+  PromptExtensionArgumentDefinition,
+  PromptExtensionOptionDefinition,
+  PromptExtensionOptionsSchema,
+  PromptExtensionOptionType,
+  PromptMacroDefinition,
+  PromptMacroRenderContext,
+  PromptMacroRenderer,
+  PromptRegistryEntry,
+  PromptRenderHelpers,
+  PromptSlotDefinition,
+  PromptSlotRenderContext,
+  PromptSlotRenderer,
+} from "@zihanw/pi-forge";
+```
 
-Before removing the compatibility subpaths, check known consumers, announce the change, and provide supported package entry points for legitimate integrations.
+Supported for trusted reusable and project-local extensions. The contract (pure renderers, declared dependencies, immutable `PromptEnvironment`, bounded output) is specified in the [0.5.0 architecture plan](../design/architecture-0.5.md#extension-port-contract-050) and the [custom macros and slots guide](../guides/custom-macros-and-slots.md).
+
+### 3. `@zihanw/pi-forge/subagent`: versioned host port
+
+```ts
+import {
+  ForgeHost, ForgeHostClient, ForgeHostPortError,
+  FORGE_HOST_CHANNEL, FORGE_HOST_PORT_VERSION, FORGE_HOST_PORT_OPERATIONS,
+  validateListProfilesRequest, validateListProfilesResponse,
+  validateResolveProfileRequest, validateResolveProfileResponse,
+  validatePrepareRequest, validatePrepareResponse,
+  canonicalSubagentJson, subagentFingerprint,
+  subagentSourceProfileFingerprint, subagentPromptStackFingerprint,
+} from "@zihanw/pi-forge/subagent";
+```
+
+The experimental host port over the Pi event bus: discovery, profile listing/snapshot, and host-owned prompt preparation with mandatory lifecycle semantics (correlation IDs, payload validation, bounded timeouts, host generation, duplicate-host failure, disposal/`unavailable`, listener cleanup). The wire DTOs and validators are self-contained Forge data contracts; the main package has no dependency on `@zihanw/pi-subagent-runtime`. The canonical `sha256:v1` fingerprint helpers are Forge-owned and byte-compatible with the runtime's canonical JSON.
+
+The optional `@zihanw/pi-forge-subagents` package consumes this port and owns subagent execution and configuration.
+
+## Compatibility policy
+
+- **Stable** surfaces (root factory, macro/slot registration) preserve source compatibility within the documented release range unless a changelog entry announces a breaking release.
+- **Experimental** surfaces (the `/subagent` host port) are typed, tested, and documented, but may change deliberately as integration experience exposes missing semantics.
+- Everything not listed above is internal and may change without notice. In particular: no `src/*` subpath aliases exist, `./examples/*` is not an import surface (examples ship as browsable files), and removed 0.4 surfaces (the execution contract re-exports, loader/profile/catalog helpers) now live either nowhere or in `@zihanw/pi-forge-subagents`.
+
+## Removed in 0.5.0
+
+- All `@zihanw/pi-forge/src/*` compatibility aliases and the `./examples/*` subpath export.
+- Root re-exports of loader, agent-profile, profile-service, catalog, resource-identity, render-helper values, the `forge-v1` engine, and registry readers.
+- Root and `/subagent` re-exports of the 0.4 execution contract (`AgentRequest`, `createAgentExecutionPlan`, `validateAgentRequest`, `negotiateSubagentTools`, `resolveSubagentHostProfile`, `prepareSubagentHostPlan`, and friends). The execution contract now belongs to `@zihanw/pi-forge-subagents`.
+
+See the [0.5 migration guide](../guides/migrating-to-0.5.md) for the complete breaking-change list.

package/docs/reference/stack-schema.md

@@ -6,7 +6,7 @@ Use [the default Pi mirror](../../examples/default-prompt-stack.json) as the com
 
 ## Top-level shape
 
-A stack has a unique `id`, schema/type identity, optional display metadata and auto-activation, a system `mode`, ordered `items`, and optional defaults, variables, context, resource policy, regex, and source metadata.
+A stack has a unique `id`, schema/type identity, optional display metadata and auto-activation, a system `mode`, ordered `items`, and optional defaults, parameters (schema v2) or legacy variables, context, resource policy, regex, and source metadata.
 
 Unknown/advanced metadata is preserved by raw editing, but behavior-changing fields are shape-checked and invalid values are not silently normalized into active behavior.
 
@@ -21,7 +21,7 @@ Block:
   "name": "Readable label",
   "enabled": true,
   "role": "system",
-  "content": "Your text here. Use {{macros}} for dynamic content."
+  "content": "Your text here. Use {{ parameters.role }} / {{ runtime.lastUserMessage }} for dynamic content."
 }
 ```
 
@@ -65,7 +65,7 @@ Item IDs must be unique. Unsupported slots and missing required custom registrat
 }
 ```
 
-- Set `includeLastUserMessage: false` when a later block reinserts `{{lastUserMessage}}`.
+- Set `includeLastUserMessage: false` when a later block reinserts `{{ runtime.lastUserMessage }}`.
 - `stripAssistantThinking` removes prior thinking blocks but preserves visible assistant text, tool calls, and results. It does not change the live loop or stored transcript.
 - `includeSummaries: false` excludes branch/compaction summaries.
 - `roles` keeps only selected roles.
@@ -76,7 +76,7 @@ When filtering would separate a tool call from its result, pi-forge removes dang
 
 ## Structured slots
 
-`tools`, `tool-guidelines`, `skills`, `project-context`, and `variables` support `"format": "plain"`; the default is XML-style structure. Date slots support `includeTime: true`.
+`tools`, `tool-guidelines`, `skills`, and `project-context` support `"format": "plain"`; the default is XML-style structure. Date slots support `includeTime: true`.
 
 See [macros and slots](macros-and-slots.md) for names and options.
 
@@ -101,13 +101,14 @@ Tool policy changes Pi's active tool list, is reasserted before input/turns, and
 
 Skill policy filters only pi-forge-rendered skill slots. It does not disable explicit invocation and is not a capability boundary. `append`/`prepend` may retain Pi's unfiltered base skill text, so validation warns.
 
-## Variables
+## Parameters and schema v2
 
-Top-level static variables are JSON values:
+Schema v2 stacks store immutable static values in `parameters` (JSON-compatible):
 
 ```json
 {
-  "variables": {
+  "schemaVersion": 2,
+  "parameters": {
     "char": "Konata",
     "user": "User",
     "style": { "tone": "concise" }
@@ -115,7 +116,11 @@ Top-level static variables are JSON values:
 }
 ```
 
-Turn and session values are changed through macros. See [macro reference](macros-and-slots.md).
+Parameters resolve through `{{ parameters.<name> }}` templates and are available
+to trusted custom macros/slots. Unversioned and v1 stacks continue to read the
+legacy `variables` field (string values) and support bare `{{name}}` fallback.
+A stack must not mix `parameters` and `variables` across schema versions. See
+[macro reference](macros-and-slots.md).
 
 ## Regex transforms
 
@@ -164,4 +169,4 @@ Outgoing rules change future model input. To destructively change a completed as
 
 > `finalize` runs at `message_end`, after raw output may have streamed. It replaces the stored assistant message, so the original output is not preserved.
 
-`effect: "display"` and `"both"` validate with warnings but are ignored until true display transforms exist. Runtime diagnostics report match and changed-segment counts.
+`effect: "outgoing"` and `"finalize"` are the only valid effects; `"display"` and `"both"` are rejected during validation. Runtime diagnostics report match and changed-segment counts.

package/docs/reference/subagent-host-port.md

@@ -0,0 +1,49 @@
+# Subagent host port contract
+
+[Documentation](../README.md)
+
+Status: experimental, versioned (`FORGE_HOST_PORT_VERSION = 1`). The `/subagent` entry point is the main package's only subagent surface: a transport-neutral host port over data-only messages. Subagent execution, approval, and configuration live in the optional [`@zihanw/pi-forge-subagents`](https://github.com/MacroSony/pi-forge-subagents) package, which consumes this port and never imports main-package internals.
+
+## Ownership boundary
+
+- **Main package owns:** prompt-stack/agent-profile storage and validation (repositories + codecs), the immutable `ForgeWorkspace` snapshot, profile/stack resolution, host-owned prompt compilation, and tool filtering through stack policy.
+- **Optional package owns:** delegation authorization (`subagents.json`), the execution contract (request, preflight, plan, response, validators), backend preflight and sealing via `@zihanw/pi-subagent-runtime`, approval UX, and execution.
+- **Never crosses the port:** live contexts, internal registries, execution/runtime material (access workspace model, limits, `resultProjection`, `parent`, `remoteEgressConsent`, a base system prompt). The client sends only a profile selector, the task, prompt-compilation access facts (`level`/`network`/`allowProcess`), and backend facts (model, thinking level, tool catalog).
+
+## Transport and lifecycle
+
+`ForgeHostTransport` is a minimal `{ emit(channel, data), on(channel, handler) }` interface; the production wiring is `pi.events`. Wire messages are plain JSON-compatible data validated recursively (exact nested fields, typed enums, plain objects only, unknown fields rejected) at both boundaries.
+
+Mandatory lifecycle rules:
+
+1. Clients subscribe before announcing or discovering, and use bounded timeouts.
+2. A duplicate live host fails explicitly (`host.duplicate`).
+3. `request`/`reply` messages carry `hostId` + `generation`; stale-generation and wrong-host requests are rejected server-side, mismatched replies ignored client-side.
+4. Disposal sends `unavailable` and invalidates connections; all transient and persistent listeners are cleaned up.
+5. The host can only start after the first workspace snapshot exists, so an advertised host implies a loaded workspace. Reload honors project trust: untrusted workspaces expose global resources only.
+
+## Operations
+
+### Discovery
+
+`ForgeHostClient.discover()` / `ForgeHostSession` in the optional package announce on `FORGE_HOST_CHANNEL` and wait for `available` with capabilities.
+
+### `listProfiles`
+
+Request: `{}`. Response: `{ profiles: ForgeProfileSummary[] }` — each with `profileId`, `scope`, optional `name`/`description`/`autoActivate`, `model`, `thinkingLevel`, `promptStack`, `usable`, and load diagnostics. Read-only; no resolution side effects.
+
+### `resolveProfile`
+
+Request: `{ profile: string }` — a scoped selector (`reviewer`, `project:reviewer`, `global:reviewer`). Response: `{ snapshot }` — the immutable host-owned profile snapshot artifact: resolved profile and prompt stack JSON, prompt dependency list, and `sha256:v1` content fingerprints (`profileFingerprint`, `promptStackFingerprint`) computed with Forge-owned canonical helpers byte-compatible with the runtime's canonical JSON. The optional package re-validates and re-fingerprints the snapshot before binding it into execution plans.
+
+### `prepare`
+
+Request: `{ profile, task: { text }, access: ForgePromptAccessFacts, backend: ForgeBackendFacts }`. The workspace resolves the profile and stack from its snapshot, filters the client tool catalog through stack tool policy and the access facts, and compiles through the same compilation context as runtime and preview. Response: `{ profileId, model, thinkingLevel, systemPrompt, messages, effectiveToolIds, effectiveToolNames, diagnostics, profileSnapshot, preparedAt }`. `messages` ends with the protected delegated task (`protectedTask: true`, `source: "delegated-task"`); stack-compiled messages carry `source: "prompt-stack"`. The base system prompt is host-owned and intentionally empty for delegated subagents — the prompt stack composes the system prompt.
+
+## Fingerprints
+
+`canonicalSubagentJson`, `subagentFingerprint`, `subagentSourceProfileFingerprint`, `subagentPromptStackFingerprint`, and `SUBAGENT_FINGERPRINT_PREFIX` are Forge-owned and vendored in the main package; golden vectors pin byte compatibility with the runtime's canonical serialization. Conversation and execution fingerprints are never host-computed — they are issued by `@zihanw/pi-subagent-runtime` during plan sealing in the optional package.
+
+## Errors
+
+`ForgeHostPortError` carries `code: "timeout" | "duplicate" | "unavailable" | "protocol" | "invalid"`. Operation-level failures return `{ ok: false, error }` results rather than throwing across the bus.