@zihanw/pi-forge 0.3.2 → 0.4.0

package/docs/concepts/agent-profiles.md

@@ -0,0 +1,60 @@
+# Agent profiles
+
+[Documentation](../README.md) · [中文](../zh-CN/concepts/agent-profiles.md)
+
+An agent profile is a project-local, schema-versioned preset that references one exact model, thinking level, and prompt stack. It is deliberately small and portable.
+
+## Schema
+
+Profiles live in `.pi/forge/agent-profiles/*.json`:
+
+```json
+{
+  "schemaVersion": 1,
+  "type": "pi-forge.agent-profile",
+  "id": "reviewer",
+  "name": "Reviewer",
+  "description": "Reviews code without making changes.",
+  "autoActivate": true,
+  "model": {
+    "provider": "provider-id",
+    "id": "model-id"
+  },
+  "thinkingLevel": "high",
+  "promptStack": "reviewer"
+}
+```
+
+`promptStack` may be `null`. Unsupported fields are errors: generation settings, tools, skills, backend selection, and runner policy are intentionally not profile-v1 data. The referenced prompt stack is the sole source of tool policy and model-visible skill filtering.
+
+## Capture and application
+
+```text
+/profile save reviewer
+/profile preview reviewer
+/profile use reviewer
+```
+
+Save captures the current provider/model, thinking level, and stack without secrets, history, tools, or provenance. `--overwrite` is required to replace an existing file; existing display metadata is preserved.
+
+Application is transactional and one-shot. pi-forge first validates the profile, model, configured authentication, thinking-level support, prompt stack, and tool allow patterns. It changes nothing when preflight fails. If an application step fails, it attempts rollback and does not record successful provenance.
+
+After a successful application, later manual changes are respected. The profile does not continuously own model or thinking state, although the selected prompt stack continues enforcing its policy.
+
+## Auto-activation
+
+At most one profile may set `autoActivate: true`. It applies once when Pi starts a fresh session and takes precedence over standalone prompt-stack autoload, including when `promptStack` is `null`.
+
+Restored branch selections take precedence over auto-activation. Invalid or ambiguous profile auto-activation fails closed: pi-forge will not partially apply it or silently fall back to a stack.
+
+## Provenance and drift
+
+`/profile status` compares the current runtime with the last-applied resolved snapshot. It reports source-definition changes separately from runtime drift in model, thinking level, or stack.
+
+Provenance is branch-scoped status metadata, not ownership. Reload, resume, tree navigation, and compaction never reapply a profile. `/profile forget` removes provenance without changing runtime state.
+
+## Delegation is separate
+
+Ordinary profiles cannot be delegated by default. The trusted project's `.pi/forge/config.json` separately authorizes eligible profile IDs and host-specific backend/timeout choices. Deleting a profile removes its delegation policy so a later same-ID profile cannot inherit authority.
+
+Read the [experimental delegation guide](../guides/delegation.md) before enabling it.

package/docs/concepts/prompt-stacks.md

@@ -0,0 +1,90 @@
+# Prompt stacks
+
+[Documentation](../README.md) · [中文](../zh-CN/concepts/prompt-stacks.md)
+
+A prompt stack is an ordered, declarative description of the prompt and policy Pi should use. It combines static **blocks** with dynamic **slots**.
+
+## Blocks and slots
+
+A block inserts static text with a role:
+
+```json
+{
+  "kind": "block",
+  "id": "review-rules",
+  "name": "Review rules",
+  "enabled": true,
+  "role": "system",
+  "content": "Prioritize correctness, regressions, security, and missing tests."
+}
+```
+
+A slot renders current Pi data at that position:
+
+```json
+{
+  "kind": "slot",
+  "id": "history",
+  "name": "Conversation",
+  "enabled": true,
+  "role": "user",
+  "slot": "chat-history",
+  "options": { "includeLastUserMessage": false }
+}
+```
+
+Slots cover conversation history, tools, tool guidance, skills, project context, appended system text, variables, model, date, and working directory. See [macros and slots](../reference/macros-and-slots.md).
+
+## Compilation order
+
+For each new user turn, pi-forge:
+
+1. Orders enabled blocks and slots exactly as written.
+2. Builds `system` content and applies the stack's `replace`, `append`, or `prepend` mode.
+3. Inserts synthetic user/assistant messages around the movable `chat-history` slot.
+4. Expands built-in, variable, and trusted custom macros.
+5. Applies the stack's tool policy to Pi and filters skills rendered by pi-forge.
+6. Applies outgoing history/compiled regex rules.
+7. Optionally applies destructive finalize rules when an assistant message completes.
+
+The context rewrite happens only on the first provider request for a user-submitted turn. Pi can then continue its normal tool loop without repeatedly rebuilding the same context.
+
+## System modes
+
+- `replace` is the default and gives the stack complete control. An empty replacement falls back to Pi's base prompt.
+- `append` adds stack system content after Pi's base prompt.
+- `prepend` adds stack system content before Pi's base prompt.
+
+Use `replace` when the model-visible skill list must be controlled. With `append` or `prepend`, Pi's base prompt may already contain an unfiltered skill listing.
+
+## History placement
+
+`chat-history` is movable. A useful task-focused layout is:
+
+1. Long-lived system rules.
+2. Runtime tools and project context.
+3. Chat history with `includeLastUserMessage: false`.
+4. A final user block containing `{{lastUserMessage}}`.
+
+This preserves prior context while presenting the current request once, in an explicit final position. History can also filter summaries and roles, drop previous tool traffic, strip assistant thinking, and limit recent messages or characters. pi-forge repairs dangling tool-call/result pairs after filtering.
+
+## Tool and skill policy
+
+Stacks may use either `allow` or `deny` patterns for each resource. Tool policy changes Pi's active tools and is guarded at tool-call time; it remains enforced while the stack is selected. Skill policy only filters skills rendered by pi-forge—it does not prevent explicit skill invocation and is not a security boundary.
+
+External tool additions are preserved in the baseline restored when a restrictive stack is disabled. See the exact behavior in [stack policy reference](../reference/stack-schema.md#tool-and-skill-policy).
+
+## Activation and session behavior
+
+- `default.json` auto-activates unless its metadata opts out.
+- Another stack may set `autoActivate: true`; conflicting auto-activation is invalid.
+- `/preset use none` records an explicit session opt-out.
+- Active stack and session variables follow Pi's session-tree branch.
+- Restored branch state takes precedence over fresh-session auto-activation.
+- An auto-activated agent profile takes precedence over standalone stack autoload.
+
+## Extensions and transforms
+
+Static, turn, and session variables support nested macros and lazy conditionals. Trusted JavaScript/TypeScript registration modules can add macros and slots without putting executable code in stack JSON. Deterministic regex rules can transform model-bound prompt text or, with an explicit warning, replace finalized assistant transcript text.
+
+See [custom macros and slots](../guides/custom-macros-and-slots.md), [macro reference](../reference/macros-and-slots.md), and [regex schema](../reference/stack-schema.md#regex-transforms).

package/docs/design/README.md

@@ -0,0 +1,17 @@
+# Design archive
+
+[Documentation](../README.md)
+
+These documents preserve decisions, reviews, spikes, and implementation history. They are not the authoritative description of current user behavior; use the [guides](../README.md#guides) and [reference](../README.md#reference) for that.
+
+## Subagent design history
+
+- [Request/response design](subagents/interface-design.md) — accepted architecture and completed implementation iterations.
+- [Design review](subagents/design-review.md) — issues that drove preflight, task preservation, policy, fingerprint, and response revisions.
+- [Pi SDK spike findings](subagents/sdk-spike-findings.md) — historical 0.80.6 investigation; its harness was removed after findings were productized.
+
+## Project planning history
+
+- [0.4 roadmap and implementation log](roadmap-0.4-archive.md)
+
+The current exported semantics are in the [subagent adapter contract](../reference/subagent-adapter.md); forward-looking work is in the [roadmap](../development/roadmap.md).

package/docs/design/roadmap-0.4-archive.md

@@ -0,0 +1,216 @@
+# Historical 0.4 roadmap and implementation log
+
+> **Archive:** This document preserves the planning record through the 0.4 development cycle. Completed behavior belongs in the [feature inventory](../reference/features.md); current plans belong in the [roadmap](../development/roadmap.md).
+
+This file was the forward-looking product roadmap during 0.4 development. Completed capability now belongs in the [feature inventory](../reference/features.md), release history in the root [changelog](../../CHANGELOG.md), and current plans in the [roadmap](../development/roadmap.md).
+
+## Documentation Map
+
+- [Root README](../../README.md) and [Chinese README](../../README.zh-CN.md): short project landing pages.
+- [Feature inventory](../reference/features.md): implemented profile, prompt-stack, web-editor, payload, extension, packaging, and experimental subagent behavior.
+- [Changelog](../../CHANGELOG.md): release and unreleased change history.
+- [Subagent interface design](subagents/interface-design.md): accepted request/response architecture, context model, responsibility boundaries, and implementation history.
+- [Subagent adapter contract](../reference/subagent-adapter.md): current exported contract, validation, enforcement receipts, and adapter responsibilities.
+- [SDK spike findings](subagents/sdk-spike-findings.md): historical real Pi SDK findings for model/auth resolution, exact prompt preparation, dynamic tools, media, timeout, and cleanup.
+- [Subagent design review](subagents/design-review.md): issues that drove resolution, preflight, enforcement, task-preservation, fingerprint, and response revisions.
+- [Public API policy](../reference/public-api.md): stable, experimental, and internal compatibility surfaces.
+
+## Current Objective
+
+Harden the completed approval-gated foreground subagent path without turning pi-forge into a general orchestrator. Work should proceed in this order:
+
+1. Dogfood the shared-user read-only path and tighten report, cancellation, and sensitive-path behavior found in real use.
+2. Evaluate an optional bubblewrap-style backend that can enforce allowed roots, subprocess limits, and network policy honestly.
+3. Design any future write access as an inspectable staged patch with a separate approval boundary.
+4. Expose agent profiles in the existing browser editor.
+5. Harden the workflows and prepare the release.
+
+The current tool and commands already share the same request, preflight, host preparation, immutable plan, execution, and response-projection path. Further safety work should strengthen the backend boundary rather than introduce a second runner. Profile UI remains a bounded user-facing iteration independent of sandbox development.
+
+## Recently Completed: Approval-Gated Foreground Subagent
+
+The `pi-subprocess-readonly` and `pi-rpc-readonly` paths send one requested text task through profile eligibility and resolution, backend preflight, exact backend-assisted prompt preparation, immutable plan validation, interactive review by default, a foreground Pi process (text/print or RPC), and normalized response handling without owning a general runner. Backend registration, preflight binding, plan sealing, lifecycle arbitration, and both process backends are owned by `@zihanw/pi-subagent-runtime`; pi-forge keeps profiles, execution policy, compilation, approval, and presentation. Backend and timeout defaults are layered global/project configuration, while explicit `subagents.profiles.<id>` delegation opt-in and per-profile overrides are trusted-project-only; interactive runs may override the backend, there is no fallback, and a trusted-project option can explicitly authorize the model-callable tool without per-run review pinned to the effective configured profile backend. The former in-package `SubagentBackendRegistry`, `PiSubprocessBackend`, and `PiSdkIsolatedBackend` exports were removed in the migration; the SDK spike harness was removed after its findings were productized in the runtime's shared preparation gate.
+
+User test surface:
+
+- Explicitly enable intended delegation profiles under the trusted project's `subagents.profiles`, then ask the main agent to discover them with `forge_subagent_profiles` and execute with `forge_subagent`; restrictive tool policy must permit both names.
+- `/forge-agent backends`
+- `/forge-agent plan <profile> <task>` prepares the exact request behind a provider gate, reports its plan, and discards it without transport.
+- `/forge-agent run <profile> <task>` reviews the same exact prepared plan in the TUI and executes it only after approval.
+
+Current boundary:
+
+- Use Pi's existing model registry, authentication, streaming, and in-memory session primitives.
+- Support one-shot sequential foreground text execution with an existing agent profile and clean context.
+- Expose only stack-filtered `read`, `grep`, `find`, and `ls`; load no write/edit/shell tools, skills, prompt templates, context files, or third-party Pi extensions.
+- Declare `executionBoundary: shared-user`: read-only is model-tool policy, not mount, path, process, or network isolation. The child retains the invoking user's OS permissions.
+- Load trusted pi-forge macro/slot registrations only in the host compiler and preserve the delegated task as the final protected user message.
+- Treat timeout and abort as host best-effort enforcement.
+- Keep provider execution opt-in through interactive approval bound to the exact execution fingerprint or the explicit trusted-project unattended-tool setting. Ordinary automated tests use only an offline faux provider.
+- Let the main agent inspect only delegation-enabled profile IDs/descriptions, effective execution settings, and current resolution status locally without approval, provider transport, or exact prompt preparation.
+- Return bounded model-visible output and expandable human-visible plan, approval, diagnostics, transcript, tool-event, usage, and response details. Advertise no artifact or contract trace storage until those implementations exist.
+
+## 0.4.0 Exit Plan (agreed 2026-07-26)
+
+Decisions and scope for taking 0.4.0 out of beta. This section supersedes older subagent-status prose elsewhere in this file (notably the retained `pi-sdk-isolated` wording, which no longer matches the code); aligning those documents is work item 4 below.
+
+### Decisions
+
+- **Backend selection is configuration, not profile schema.** Agent profiles remain execution-environment-agnostic personas (model, thinking level, prompt stack). Defaults are configured through `subagents.backend` in global `~/.pi/forge/config.json` with a trusted-project override in `.pi/forge/config.json`; trusted-project `subagents.profiles.<id>` entries gate delegation and may override backend/timeout per profile, and interactive runs may override backend with `--backend`. Global profile entries are ignored until global profiles and prompt stacks have explicit source scope. The unattended model-callable tool path pins the effective configured profile backend; the interactive approval dialog always displays the bound backend. There are no fallback chains: the runtime contract forbids silent fallback, and a fallback that downgrades the execution boundary would overstate enforcement.
+- **Depth over orchestration breadth.** pi-forge's delegation niche is policy-bound, reviewable execution: sealed exact prompts, fingerprint-bound approval, and honest enforcement receipts. Background agents, parallel fan-out, chains/pipelines, nested delegation, and inter-agent messaging stay deferred (see Deferred Product Backlog); general orchestration is deliberately left to dedicated packages. The runtime's run-handle model already permits host-composed concurrency, so a future parallel approval UX needs no runtime change.
+- **pi-forge 0.4.0 does not require pi-subagent-runtime 0.1-stable.** Pin an exact runtime version and keep the subagent surface labelled experimental per Milestone 3. The runtime's own stabilization still waits for a second consumer or backend author per its VISION.md.
+
+### Work items, in order
+
+1. **Finish the runtime integration in pi-forge.**
+   - ~~Expose backend selection as decided above~~ **(done 2026-07-29):** global/trusted-project defaults plus explicit trusted-project `subagents.profiles.<id>` delegation eligibility and backend/timeout overrides, `/forge-agent plan|run --backend <id>`, interactive `forge_subagent` `backend` parameter, unattended pinning to the effective configured profile backend, and resolved-setting reporting in `forge_subagent_profiles` and `/forge-agent backends`.
+   - ~~Resolve the fingerprint-semantics contradiction~~ **(done 2026-07-26):** `AgentExecutionPlan` now carries the runtime-issued `conversationFingerprint` and `executionFingerprint` as required inputs to `createAgentExecutionPlan()`; the host never computes either value. `subagentExecutionFingerprint` and the host-side recomputation check in `validateAgentExecutionPlan()` were removed; substitution detection remains the runtime's sealed-plan binding.
+   - ~~Surface the sealed `conversationFingerprint`~~ **(done 2026-07-26):** shown in `/forge-agent plan` output, the approval summary, the full-prompt viewer, and the tool's plan details.
+   - ~~Deduplicate validation toward runtime core~~ **(done 2026-07-26):** `src/subagent/validation.ts` re-exports and adapts the runtime core validators; only host-specific artifacts keep local implementations. The host access-receipt validator intentionally stays richer than the runtime's (mount uniqueness, level consistency, boundary-claim cross-checks); porting those checks into the runtime core is a runtime-side follow-up.
+2. **Land small runtime-side API additions** **(done 2026-07-28):** `compile` receives the validated accepted preflight and `prepare` accepts an `AbortSignal`; pi-forge now consumes both directly without `hostCompilePreflight()` or `prepareWithAbort()`. Media materialization remains deferred unless delegated media tasks enter 0.4 scope.
+3. **Resolve the runtime publish story** **(done 2026-07-28):** published `@zihanw/pi-subagent-runtime@0.1.0-beta.1` and pinned that exact prerelease in pi-forge. The subagent surface remains experimental and does not require runtime 0.1-stable.
+4. **Legacy cleanup and documentation alignment** **(done 2026-07-26):** removed the SDK spike scripts/test, the `src/subagent-contract.ts` compatibility barrel, and the `subagentExecutionFingerprint` host shim; aligned stale `pi-sdk-isolated`/registry claims in `SUBAGENT_INTERFACE_DESIGN.md`, `SUBAGENT_ADAPTER_CONTRACT.md`, `SUBAGENT_SDK_SPIKE_FINDINGS.md`, and `FEATURES.md`; recorded the removed legacy exports as breaking changes in `CHANGELOG.md`. Coverage debt accepted: the removed spike was the only live media-preparation and trusted-extension preparation diagnostic; re-establish that coverage when delegated media tasks are productized (work item 2).
+5. **Milestone 1 step 1 dogfooding** of the subprocess backend against representative providers, cancellation timing, long prompts, large read results, and rejection/full-prompt review flows. The bubblewrap sandbox evaluation and staged-write proposal remain Milestone 1 design work and do not gate 0.4.0; any sandbox backend lands as a separate runtime backend entry point with honest receipts.
+6. **Milestone 2: profile UI** **(done 2026-07-31):** the browser editor now manages profiles end to end — navigation, list/badges, create/edit/validate/save/apply/delete, single auto-activation enforcement, registry-driven model controls, provenance/drift display, and a per-profile delegation card that writes `subagents.profiles` policy with backend/timeout overrides. A viewport-layout regression from the Vue shell migration (clipped content with no scroll path) was repaired with flex `min-height: 0` chains, a collapsible diagnostics panel, narrow-mode layout fixes, and a layout-invariant browser test.
+7. **Milestone 3: release readiness**, plus explicit release-note non-goals: no runner, no background execution, no chains, no profile schema expansion, no macro portability hints, no chat-history lifecycle controls.
+
+## 0.4.1 Candidate: Scoped Global Profiles and Stacks
+
+If cross-project presets are added, introduce global profiles and prompt stacks together rather than treating a project-local profile ID as a global identity. Load them from explicit global directories, retain source scope on every loaded resource, let a same-ID project resource shadow its global counterpart, and apply global/project `subagents.profiles` policy only to profiles from the matching scope. Define discovery, auto-activation, stack-reference, and editor behavior against that scoped identity before implementation.
+
+## Milestone 1: Sandbox and Write-Safety Evaluation
+
+Goal: determine whether stronger isolation and useful write workflows can be added without obscuring the current honest shared-user boundary.
+
+Implementation sequence:
+
+1. Exercise the current subprocess against representative local and remote providers, cancellation timing, long prompts, large read results, and rejection/full-prompt review flows.
+2. Define an optional sandbox-driver interface and prototype bubblewrap on supported Linux hosts with explicit allowed roots, a minimal environment, process restrictions, and configurable network policy.
+3. Keep shared-user as an explicitly unsafe compatibility mode; never report sandbox enforcement when the selected host cannot provide it.
+4. Specify a staged-write result containing proposed patches/change metadata that the human can inspect and approve separately before host application.
+
+Initial scope:
+
+- One foreground text task at a time, with no background execution or automatic retries.
+- Clean context and explicit task only; no automatic parent history.
+- Preserve read-only defaults until a separate staged-write approval/apply path exists.
+- No generic shell merely to obtain file writes; sandbox claims require enforcement tests and receipts.
+
+Done criteria:
+
+- The optional sandbox can demonstrate and test allowed-root, process, symlink, and requested network behavior, or the product continues to label execution shared-user without ambiguity.
+- A proposed write cannot affect the workspace before a second, human-visible approval and has a clear failure/partial-application strategy.
+- User cancellation and host timeout settle once and clean up preparation sessions, child processes, and temporary bridge data.
+- Documentation and receipts remain accurate on unsupported platforms and when falling back to shared-user execution.
+
+## Milestone 2: Profile UI (landed 2026-07-31)
+
+Goal: make profile v1 fully manageable from the existing localhost editor while preserving the exact behavior of the shared profile service and `/profile` commands.
+
+Scope:
+
+- Add clear top-level navigation between prompt stacks and agent profiles.
+- List profiles with ID, name, exact provider/model, thinking level, prompt-stack reference, auto-activation, and validation state.
+- Support create, edit, validate, save, delete, and one-shot apply operations.
+- Populate model/thinking controls from available model-registry data and prompt-stack selection from the shared stack repository.
+- Show resolution diagnostics for missing models, authentication, unsupported thinking levels, invalid stacks, and unmatched tool policy.
+- Distinguish source-definition changes, last-applied provenance, and current runtime drift; never imply that a profile continuously owns runtime state.
+- Retain a raw JSON recovery path for invalid or future fields without silently accepting unsupported profile fields.
+- Reuse the existing profile repository, application, preview, provenance, and drift services rather than duplicating command behavior in web handlers.
+
+Done criteria:
+
+- A user can create, edit, validate, save, apply once, and delete a profile without editing JSON or using `/profile` commands.
+- At most one auto-activation profile is accepted, and profile precedence remains identical to the command/runtime path.
+- Applying a profile performs full preflight and best-effort rollback on failure.
+- The UI does not duplicate prompt-stack item, tool-policy, or skill-policy editing.
+- Browser tests cover token protection, empty and invalid states, model/stack selection, validation, save, apply, drift display, deletion, and lifecycle host refresh.
+
+## Milestone 3: Release Readiness
+
+Goal: make the user-visible profile and experimental delegation surfaces understandable, reproducible, and safe to release.
+
+Scope:
+
+- Update English and Chinese user documentation with profile UI workflows, profile-versus-stack ownership, delegation consent, and concrete backend limitations.
+- Clearly label the subagent API/backend as experimental and keep installation and ordinary non-delegation use independent of backend execution.
+- Run command/event and browser workflows across extension reload, session navigation, fresh sessions, compaction, and editor reuse.
+- Verify npm and Git delivery through compiled `dist` while clone-based development continues to load `src/index.ts` explicitly.
+- Run `npm run verify` before every release candidate and reject stale browser-client or `dist` output.
+
+Done criteria:
+
+- Documentation and UI do not overstate skill filtering, tool filtering, filesystem isolation, timeout enforcement, or profile ownership.
+- Release-like package checks contain no physical `src/` files and both package entry points resolve to compiled output.
+- All core, browser, type, generated-client, `dist`, and package checks pass from a clean checkout.
+
+## Deferred Product Backlog
+
+### Broader or Owned Subagent Runner
+
+Do not build a full runner in 0.4. The current subprocess path should remain fresh-context, profile-backed, foreground, approval-gated, and sequential rather than expanding into chains or pipelines.
+
+Requirements before implementation:
+
+- Project trust behavior for local profiles and agents.
+- Cancellation, timeout, and cleanup semantics.
+- Budget, turn, token, output, and cost limits.
+- Tool/model/profile inheritance and provider fallback rules.
+- Artifact and trace storage, authorization, retention, redaction, pagination, and cleanup.
+- Failure and retry formats, priorities, queues, and concurrency.
+- Secret/environment injection and structured-output policy.
+- Protection against recursive delegation loops.
+
+Build native orchestration only if stored profiles need behavior external runners cannot provide without taking over pi-forge's product surface. Otherwise keep the adapter boundary and let dedicated packages own orchestration.
+
+### Profile Schema Expansion
+
+Keep generation parameters, model fallbacks, tools, skills, global profile storage, secrets, and runner limits out of profile v1. Revisit them only when a concrete consumer can validate and enforce their semantics consistently across supported backends.
+
+### Custom Macro and Slot Portability
+
+- Add optional dependency hints for required slots, macros, or extension package names only after real stack sharing demonstrates portability friction.
+- Surface missing custom dependencies in validation and the editor without allowing executable code in stack JSON.
+- Preserve parser, filter, conditional, slot, and unknown-policy compatibility.
+- Continue deferring general expressions, boolean algebra, loops, arithmetic, regex conditions, and arbitrary stack-authored code.
+
+### SillyTavern Import Fidelity
+
+- Preserve additional useful original metadata under `import` when real presets require it.
+- Add fixtures when real presets reveal unsupported field shapes.
+- Keep macro and regex conversion warnings in their focused importer modules.
+- Preserve existing behavior unless a real fixture demonstrates the need for a change.
+
+### Chat-History and Prompt Lifecycle Controls
+
+Potential history controls include omitting the last N user messages, selecting only the branch after the latest compaction, explicitly including or omitting hidden/synthetic/custom messages, and eventually summarizing old history. Each option needs a concrete use case and dangling tool-call/result repair tests.
+
+Potential lifecycle configuration may include:
+
+```json
+{
+  "lifecycle": {
+    "contextRewrite": "first-provider-request"
+  }
+}
+```
+
+Only add alternatives to the current `first-provider-request` behavior when users demonstrate a need for repeated rewriting, tool-follow-up-aware rewriting, or disabled message-layout rewriting.
+
+### Payload and Regex Expansion
+
+Continue deferring provider-payload rewriting, true display-only regex transforms, and streaming display cleanup. Near-term diagnostics may broaden provider-payload shape coverage and explain precisely what regex changed and where. Add a new stage only for a concrete use case with a stable hook and a non-destructive preview path.
+
+## Product and Engineering Guardrails
+
+- Keep prompt-stack JSON declarative. Trusted executable customization belongs in `~/.pi/forge/extensions`, `.pi/forge/extensions`, or reusable packages.
+- Treat profiles as one-shot presets. Manual use or fresh-session auto-activation configures Pi once; later user changes must not be continuously overwritten.
+- Keep tool names out of profiles. The referenced prompt stack remains the single source of truth for strict active-tool policy.
+- Treat skill policy as model-visible prompt filtering only, not explicit invocation control or a security boundary.
+- Drive new prompt-stack behavior from demonstrated prompt-authoring pain rather than complete SillyTavern compatibility.
+- Avoid expanding browser behavior without browser-level workflow coverage.
+- Keep pi-forge install and ordinary use independent of `pi-subagents`, `@gotgenes/pi-subagents`, Archimedes, or another orchestration package; delegation remains opt-in and additional backends remain optional integrations.
+- Verify any future event-bus adapter against the supported Pi version range before adopting it.
+- Do not expose delegation merely because a dispatcher exists. A concrete adapter must prove its actual isolation, preparation, projection, cleanup, and authorization semantics end to end.
+- Keep Node's built-in test runner for core tests and separate compiler, loader, importer, regex, policy, profile, and subagent-contract tests from integration-style command tests.
+- Extend the command/event harness for command or lifecycle changes, run browser smoke tests for material editor workflows, and run `npm run verify` before commits and releases.

package/docs/design/subagents/design-review.md

@@ -0,0 +1,220 @@
+# Historical subagent design review
+
+Status: historical pre-implementation review. Its blocking findings were resolved by the exported contract, validated backend registry, immutable preparation binding, concrete backends, and approval-gated foreground integration; the text below records the issues that shaped that design.
+
+## Verdict
+
+`NEXT_STEPS.md` is directionally sound and mostly suits pi-forge's current architecture. The profile CLI to shared profile service to profile UI progression is appropriate, and deferring an owned runner is the right call.
+
+`SUBAGENT_INTERFACE_DESIGN.md` is a good requirements draft, but it is not yet an implementable backend-neutral contract. Its status should remain draft rather than accepted until the blocking issues below are resolved.
+
+## Findings
+
+### 1. Blocker: a serialized prompt-stack definition is not an executable snapshot
+
+The proposed `AgentProfileSnapshot` carries only the declarative `PromptStack`. Current compilation also depends on:
+
+- Dynamic `BuildSystemPromptOptions`, the current model, time, variables, and the base system prompt supplied through Pi's lifecycle.
+- Executable custom slot and macro registrations.
+- Pi tool snippets, guidelines, skills, and context files represented by `PromptRuntime`.
+- Pi's default system prompt when the stack is `null`, `append`, or `prepend`.
+
+Two backends receiving the same proposed snapshot can therefore compile different prompts or fail to compile custom slots entirely.
+
+Recommended design: separate two artifacts:
+
+- `AgentProfileSnapshot`: immutable declarative provenance.
+- `AgentExecutionPlan`: a host-prepared system prompt, initial messages, effective tool names, runtime inputs, diagnostics, and an execution fingerprint.
+
+The alternative is to require every backend to run an identical Pi/pi-forge runtime and custom-extension set, but that would not be genuinely backend-neutral.
+
+Relevant code:
+
+- `SUBAGENT_INTERFACE_DESIGN.md:86`
+- `src/lifecycle.ts:86`
+- `src/types.ts:178`
+- `src/slot-renderers.ts:125`
+- `src/macro-engine.ts:122`
+
+### 2. Blocker: profile resolution currently means valid in the parent Pi runtime
+
+The current resolver checks models and authentication against the active Pi model registry. A remote, subprocess, or package backend may have different models and credentials.
+
+Resolution should be split into:
+
+- Host resolution: profile syntax, stack lookup, and trusted extension dependencies.
+- Backend preflight: model availability/authentication, tool availability, media support, policy enforcement, and supported limits.
+
+Without that split, the advertised native/subprocess/remote portability is not achievable.
+
+Relevant code:
+
+- `src/agent-profile.ts:156`
+- `src/agent-profile.ts:172`
+- `src/index.ts:179`
+
+### 3. High: tool negotiation and enforcement are underspecified
+
+`NEXT_STEPS.md` says the runner supplies a baseline and the stack filters it, but the request contains neither the backend's tool catalog nor the resolved effective tools. Current pi-forge filters a dynamic active-tool baseline.
+
+The backend contract needs a discovery or preflight phase that exposes:
+
+- Available tool names or stable capability IDs.
+- The access and limit policies it can enforce.
+- Exact effective tools after stack policy.
+- Required tool patterns that matched nothing.
+- Adapter-specific tool-name mappings, if any.
+
+A stack tool allowlist is selection policy, not filesystem or network isolation.
+
+Relevant code:
+
+- `NEXT_STEPS.md:62`
+- `SUBAGENT_INTERFACE_DESIGN.md:86`
+- `SUBAGENT_INTERFACE_DESIGN.md:167`
+- `src/index.ts:270`
+
+### 4. High: the access contract is not portable or sufficiently enforceable
+
+The contract combines remote backends with host absolute paths in `access.cwd` and `access.roots`, while validation requires host-side canonicalization and symlink checks. Those paths may not exist in a remote or container namespace, and host preflight cannot prevent backend-side symlink races.
+
+The capability booleans are too coarse to determine whether roots, read-only mounts, output limits, token budgets, or turn limits are enforceable.
+
+Recommended changes:
+
+- Define access using backend-visible mounts or opaque workspace handles.
+- Require the backend to canonicalize paths within its own namespace immediately before access.
+- Specify whether `cwd` must be contained in an allowed root.
+- Define the behavior of `level: "none"` when roots are also supplied.
+- Represent granular enforcement support rather than broad booleans.
+- Distinguish model/control-plane network traffic from agent-accessible network tools.
+- Treat remote-backend data egress as a separate trust/consent decision.
+
+Project trust is not, by itself, consent to send project context to a remote backend.
+
+Relevant design sections:
+
+- `SUBAGENT_INTERFACE_DESIGN.md:108`
+- `SUBAGENT_INTERFACE_DESIGN.md:167`
+- `SUBAGENT_INTERFACE_DESIGN.md:216`
+
+### 5. Medium: clean-context assembly conflicts with unrestricted prompt-stack layouts
+
+The design requires the final task to survive truncation, while existing `compileMessages()` behavior permits a stack to remove the latest user message, filter user roles, or omit history. Such a stack can accidentally remove the delegated task.
+
+The contract needs one explicit rule:
+
+- Reject stacks whose compiled delegation layout omits the task; or
+- Reserve a delegation-task insertion point that cannot be filtered; or
+- State that intentional omission is allowed, weakening the guarantee that the actionable task is always preserved.
+
+Additional context concerns:
+
+- "Selected context is data" is an instruction-hierarchy convention, not a security guarantee. Delimiters do not prevent prompt injection.
+- Tool-result excerpts should normally be rendered as quoted background evidence rather than native tool-result messages without matching tool calls.
+- A summary should carry provenance just as other selected context does.
+- `maxTokens` cannot be deterministically portable without defining the tokenizer or estimator. A byte/character bound or recorded estimator/version would be clearer.
+
+Relevant code and design:
+
+- `SUBAGENT_INTERFACE_DESIGN.md:28`
+- `SUBAGENT_INTERFACE_DESIGN.md:41`
+- `SUBAGENT_INTERFACE_DESIGN.md:223`
+- `src/compiler.ts:88`
+- `src/compiler.ts:161`
+
+### 6. Medium: the real adapter spike comes too late
+
+The implementation plan first publishes contract types and builds four slices around fake backends, then validates the design against a real runner in Slice 6. Fake conformance tests can prove internal consistency, but cannot establish that the boundary fits a real backend.
+
+The installed Pi SDK already supports session construction with model, thinking level, tools, custom tools, and resource loaders. A minimal in-memory or subprocess prototype should happen before the contract becomes a public export.
+
+Move the current concrete-adapter decision/spike before contract stabilization. Keep experimental types internal until that spike validates the boundary.
+
+Relevant design and API:
+
+- `SUBAGENT_INTERFACE_DESIGN.md:227`
+- `SUBAGENT_INTERFACE_DESIGN.md:262`
+- `node_modules/@earendil-works/pi-coding-agent/dist/core/sdk.d.ts:11`
+
+### 7. Medium: profile UI needs a shared service extraction first
+
+The profile UI priority is appropriate, but save, status/drift calculation, deletion, and application are not yet presented as one shared typed service. Save and drift rendering are still command-oriented.
+
+Before UI work, extract shared operations for:
+
+- Save/update/delete.
+- Resolution and typed preview.
+- Application.
+- Typed provenance and runtime-drift status.
+
+This prevents the UI from duplicating command behavior and directly supports the stated done criteria.
+
+Relevant code:
+
+- `NEXT_STEPS.md:34`
+- `src/profile-command.ts:258`
+- `src/profile-command.ts:455`
+
+### 8. Medium: fingerprints need explicit stable semantics
+
+Execution-facing fingerprints should use canonical serialization and a named digest algorithm/version, for example `sha256:v1:<digest>`. A raw `JSON.stringify()` value is useful for current provenance comparison but is not an ideal portable fingerprint.
+
+The execution fingerprint should cover all behavior-affecting prepared inputs, not only the source profile and stack. This includes the compiled prompt/messages, effective tools, relevant runtime data, and required custom registrations.
+
+Avoid silently changing the semantics of existing stored provenance fingerprints; introduce a separate execution/snapshot fingerprint format if compatibility matters.
+
+Relevant code:
+
+- `src/agent-profile.ts:243`
+- `SUBAGENT_INTERFACE_DESIGN.md:222`
+
+### 9. Medium: response, trace, and limit semantics need tightening
+
+Before parent integration, clarify:
+
+- Which statuses require or forbid `error`.
+- Whether `output` may be empty for failures and cancellations.
+- Whether `effectiveAccess` is merely echoed or is a backend-produced enforcement receipt.
+- Effective tool and enforced-limit metadata in the response.
+- Currency and units for `usage.cost`.
+- Artifact and change-path namespace, authorization, lifetime, and cleanup.
+- How an opaque trace reference routes back to the correct backend and how inspection is authorized.
+- Cancellation before a remote backend has exposed its `runId`.
+- Whether limits are hard execution limits or only response/projection truncation.
+
+The current capability interface cannot indicate support for `maxTurns`, `maxOutputBytes`, or `tokenBudget`, so the dispatcher cannot reliably apply the rule that unsupported required policies must be rejected.
+
+## Recommended ordering
+
+1. Complete real-provider and real-extension-tool profile CLI compatibility testing.
+2. Extract the shared profile repository/application/status service.
+3. Build profile UI on that service with browser workflow coverage.
+4. Prototype one actual Pi SDK or subprocess backend.
+5. Revise the subagent design around backend preflight plus a host-prepared execution plan.
+6. Add pure validators, stable fingerprints, fake-backend conformance tests, and optional backend registration.
+7. Add parent run/inspect tools only after enforcement and task-preservation semantics are demonstrated.
+8. Continue deferring an owned full runner, resumable agents, chains, pipelines, retries, queues, and concurrency orchestration.
+
+Custom macro/slot portability can remain broadly deferred, but dependency detection cannot. A subagent export must identify required registrations or reject stacks that cannot be reproduced by the chosen backend.
+
+## Parts of the plan worth retaining
+
+- Profiles remain reusable one-shot presets rather than continuously owning runtime state.
+- Prompt stacks remain the profile-level source of tool-selection policy.
+- Per-run access and limits remain outside reusable profiles.
+- Parent context selection is explicit, bounded, and provenance-preserving.
+- Parent-visible results remain compact, with full normalized history behind an inspectable trace.
+- No concrete subagent package is required to install or use pi-forge.
+- A full owned runner remains deferred.
+- Initial runner work avoids chains and pipelines.
+- Browser workflows and public contract behavior receive dedicated tests.
+
+## Validation performed during review
+
+- Core tests: 126 passed.
+- TypeScript typecheck: passed.
+- Real-browser editor smoke test: passed.
+- Tracked `dist/` consistency check: passed.
+
+The review itself did not modify implementation code or either source design document.