@zihanw/pi-forge 0.4.0-beta.1 → 0.4.1

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.

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

@@ -0,0 +1,274 @@
+# Subagent request/response design
+
+Status: historical design and implementation record for the completed 0.4 path. Execution ownership (backend registry, preflight binding, plan sealing, conversation/execution fingerprints, lifecycle, and the fresh-process `pi-subprocess-readonly`/`pi-rpc-readonly` backends) lives in `@zihanw/pi-subagent-runtime`; the former in-package registry and `pi-sdk-isolated` compatibility backend were removed in that migration. The broader Pi SDK spike is recorded in the [SDK spike findings](sdk-spike-findings.md) (harness since removed), and the concrete exported semantics are documented in the [subagent adapter contract](../../reference/subagent-adapter.md).
+
+## Goals
+
+- Make pi-forge profiles usable by native, subprocess, package-provided, or remote backends without requiring every backend to reproduce the parent Pi runtime.
+- Start every subagent with a clean conversational context while allowing explicit, bounded context seeding.
+- Keep prompt stacks as the profile-level source of prompt layout, visible-tool policy, and model-visible skills.
+- Keep access, limits, cancellation, trace storage, and result reporting outside reusable profiles.
+- Return a compact parent-visible tool result while retaining normalized execution history for authorized inspection.
+- Export the demonstrated request/resolution/preflight/plan/response boundary while keeping a full owned runner, orchestration, and automatic delegation out of the package surface.
+
+## Execution Flow
+
+The portable caller request is not itself executable. Execution has five stages:
+
+```text
+AgentRequest
+    -> host profile/stack/dependency resolution
+    -> backend discovery and preflight
+    -> backend-assisted host plan preparation
+    -> backend execution
+    -> AgentResponse
+```
+
+### 1. AgentRequest
+
+The parent supplies intent: profile selection, task/media, explicit selected context, access requirements, limits, and parent-depth provenance. It does not contain parent runtime model objects, loaded files, credentials, raw session entries, or a compiled prompt.
+
+### 2. Host resolution
+
+pi-forge validates profile syntax, resolves the referenced prompt stack, identifies required custom macro/slot registrations, resolves selected parent-context references, and creates immutable declarative provenance. This stage does not claim that the target backend has the model, credentials, tools, isolation, or limit support needed to execute it.
+
+Current parent-runtime resolution used by `/profile use` remains valid for applying profiles to the parent. Subagent host resolution must be a separate operation rather than reusing parent model/auth diagnostics as backend truth.
+
+### 3. Backend discovery and preflight
+
+Before prompt compilation, the selected backend reports:
+
+- Model availability, authentication, thinking-level support, and media support.
+- A stable tool catalog with backend tool IDs, policy-facing names, prompt snippets, and optional adapter mappings.
+- Prompt-runtime inputs needed for Pi-compatible base prompts, tool guidance, skills, and context resources.
+- Workspace/mount materialization support and granular access enforcement.
+- Supported hard limits, cancellation behavior, trace support, and artifact behavior.
+- Remote data-egress requirements.
+
+The host applies the prompt stack's tool policy to the backend catalog. An allow pattern that matches nothing remains a warning unless separate dependency metadata marks that tool or capability as required.
+
+### 4. Backend-assisted plan preparation and AgentExecutionPlan
+
+The host combines the resolved profile, backend preflight receipt, selected context, and prompt-stack compiler into an immutable execution plan. The plan contains prepared system text/messages, exact model and thinking level, effective backend tool IDs, materialized workspace handles, enforced limits, diagnostics, provenance, and a stable execution fingerprint.
+
+Some backends cannot expose exact prompt-runtime inputs during passive preflight. Pi SDK 0.80.6, for example, exposes its exact base prompt, tool snippets, skills, and context options through `before_agent_start`, immediately before provider execution. Such an adapter may supply those inputs to a trusted host preparation callback after accepting the prompt, provided it blocks provider transport until host compilation, protected-task validation, limit checks, and plan finalization succeed. A partial dry preflight must declare its prompt-runtime fidelity and cannot masquerade as the exact execution plan.
+
+Custom macros and slots execute during plan preparation in the trusted host. Backends receive their rendered result and dependency receipt, not executable registration code. A raw `PromptStack` remains snapshot provenance and is not treated as an executable backend artifact.
+
+For a null stack or append/prepend stack mode, the backend preflight must provide the base-prompt inputs required by the selected adapter. If the host cannot reproduce the intended base prompt, plan preparation fails.
+
+### 5. AgentResponse
+
+The backend returns normalized terminal status, output, enforcement receipts, effective tools/limits, artifacts, usage, and a routed trace handle. A separate projection determines what enters the parent model's context.
+
+## Responsibility Boundaries
+
+Effective permissions are the intersection of:
+
+1. Profile prompt-stack tool selection.
+2. Request access and limit requirements.
+3. Backend-advertised capabilities and enforcement.
+
+A backend must reject a required policy it cannot enforce. Prompt tool filtering is not a filesystem, process, or network sandbox.
+
+pi-forge owns profile/stack resolution, trusted prompt compilation, context selection, plan creation, stable fingerprints, diagnostics, and parent-visible response projection. Backends own target-runtime preflight, execution, cancellation, backend-namespace canonicalization, enforcement receipts, usage collection, artifacts, and normalized traces.
+
+## Context Model and Task Preservation
+
+Subagents inherit no parent conversation automatically. Their prepared context contains:
+
+1. System instructions compiled from the resolved profile and backend prompt inputs.
+2. Optional parent-selected context rendered as quoted background evidence with provenance.
+3. A protected final user task containing all request text and media.
+
+Selected context may contain a provenance-bearing summary, visible user/assistant excerpts, quoted tool-result excerpts, and resource/artifact references. It never automatically contains the parent system prompt, full chat history, hidden reasoning, raw provider payloads, secrets, or environment variables.
+
+Tool-result excerpts are background content, not native tool-result messages, because they do not have matching tool calls in the clean subagent history. Delimiters communicate instruction priority but are not a prompt-injection security boundary.
+
+The delegated task is appended as a protected final user message after unrestricted prompt-stack message layout has been compiled. A backend adapter may combine adjacent user messages for provider compatibility, but it must preserve the delegated-context/task boundary and all structured media parts. Subagent preparation fails if the final normalized plan does not contain the complete task.
+
+Context budgeting uses a required character/byte ceiling in v1. Any optional token estimate records the estimator/tokenizer name and version. Truncation removes optional context before required context and never truncates the final task or required media.
+
+## Contract Artifacts
+
+The TypeScript shapes and pure validators for the following artifacts are exported. Backend registration, explicit backend selection, and execution lifecycle are owned by `@zihanw/pi-subagent-runtime`; the extension composition root registers local `forge_subagent_profiles` discovery and drives the runtime's `pi-subprocess-readonly` (default) and `pi-rpc-readonly` backends for `forge_subagent` and `/forge-agent`.
+
+### AgentRequest
+
+- Schema version and host-generated request ID.
+- Profile ID plus an optional expected source fingerprint for optimistic consistency.
+- Structured text/media input.
+- Optional selected-context summary/items with provenance and a character budget.
+- Access requirements expressed through opaque workspace/resource handles, not backend-specific absolute paths.
+- Hard execution limits and a separate parent-result projection limit.
+- Parent run/session provenance and bounded delegation depth.
+- Explicit remote-egress consent when a backend would transmit local project data.
+
+### AgentProfileSnapshot
+
+- Normalized profile fields and canonical source-profile digest.
+- Normalized prompt-stack definition and canonical stack digest, or null.
+- Required custom macro/slot dependency identities when available.
+- No model-registry object, credential/auth result, loaded file path, diagnostics, session state, or secret.
+
+This snapshot is immutable provenance. It is not sent to a backend as a promise that the profile is executable there.
+
+### BackendPreflightResult
+
+- Accepted/rejected state with structured diagnostics.
+- Resolved target model and thinking level.
+- Stable tool catalog and adapter mappings.
+- Prompt-runtime/base-prompt inputs.
+- Workspace materialization/mount mappings in the backend namespace.
+- Granular enforcement capabilities and accepted hard limits.
+- Media, cancellation, trace, artifact, and remote-egress behavior.
+
+### AgentExecutionPlan
+
+- Host-generated run ID, request ID, and backend ID.
+- Prepared system prompt and normalized initial messages.
+- Exact model, thinking level, effective backend tool IDs, and unmatched policy diagnostics.
+- Materialized workspace handles, relative working directory, network policy, and enforcement requirements.
+- Enforced execution limits and separate result-projection limits.
+- Profile/stack provenance, dependency receipt, and backend preflight receipt.
+- Canonical execution fingerprint covering all behavior-affecting prepared inputs.
+
+The run ID exists before backend execution begins so cancellation and trace correlation do not depend on a remote backend first returning its own ID.
+
+### AgentResponse
+
+Response status is a discriminated union:
+
+- `completed`: no error; output may be empty.
+- `failed`: structured error required; optional partial output must be marked partial.
+- `cancelled`: cancellation reason required; output is absent or explicitly partial.
+- `timed-out`: timeout reason and enforced timeout required; output is absent or explicitly partial.
+- `limit-reached`: the reached hard limit is required; output is absent or explicitly partial.
+
+Every response includes request/run/backend correlation, model/profile/execution fingerprints, backend-produced enforcement receipt, effective tools and limits, duration, and artifact/trace routing metadata. `effectiveAccess` is never a request echo.
+
+Token usage records tokenizer/model provenance when known. Cost uses an amount plus ISO currency code rather than an unqualified number. Artifact/change paths live in a named workspace namespace and include authorization, lifetime, and cleanup metadata.
+
+Opaque backend trace IDs are registered behind host trace handles. Inspection authorizes the caller and routes through the backend/host trace registry. Hidden provider reasoning remains excluded by default.
+
+Hard execution limits are distinct from response projection truncation. A backend that cannot enforce a required timeout, turn, token, output, filesystem, or network constraint rejects preflight.
+
+## Access and Data-Egress Model
+
+Requests identify host resources with opaque workspace/resource handles. Backend preflight maps them into backend-visible mounts or uploaded resources. The execution plan uses mount IDs plus normalized relative paths rather than assuming host absolute paths exist remotely.
+
+- `none` permits no filesystem mounts and no filesystem working directory.
+- `read-only` permits only read-only mounts.
+- `workspace-write` permits explicitly identified read-write mounts; all other mounts remain read-only or absent.
+- An access receipt distinguishes an `isolated` execution boundary from an explicitly unsafe `shared-user` process. At the shared-user boundary, access levels describe the model-visible tool policy rather than the child process's operating-system permissions.
+- A working directory, when present, must be contained within an accepted mount.
+- The backend canonicalizes and checks paths in its own namespace immediately before access and must enforce containment against symlink races.
+- Model/provider transport is distinct from agent-accessible network tools.
+- Sending project content to a remote backend requires an explicit egress decision; project trust alone is insufficient consent.
+
+Capabilities are granular claims such as read-only mount isolation, read-write mount isolation, symlink-safe containment, agent-network isolation, timeout enforcement, turn enforcement, token-budget enforcement, output enforcement, cancellation, media transport, artifact retention, and trace inspection. Broad booleans are insufficient.
+
+## Fingerprints and Compatibility
+
+New portable fingerprints use canonical serialization and a named algorithm/version such as `sha256:v1:<digest>`.
+
+- Source-profile fingerprint: normalized declarative profile.
+- Prompt-stack fingerprint: normalized declarative stack.
+- Execution fingerprint: compiled system/messages, exact model/thinking, effective tool IDs/mappings, relevant prompt-runtime inputs, selected-context/resource digests, dependency receipt, materialized access policy, enforced limits, and adapter/preflight version.
+
+The existing `agentProfileFingerprint()` JSON string remains unchanged for stored branch provenance and drift compatibility. Portable snapshot/execution digests are new fields with separate semantics.
+
+## Parent-Visible Result
+
+The complete response is control-plane data. The main agent receives a bounded tool-result projection containing run ID, terminal status, output, and compact errors/warnings when applicable.
+
+The human can expand the same tool result to inspect the plan summary, approval receipt, diagnostics, usage, normalized response, and complete captured subprocess transcript/tool events. Those details stay out of the normal model-visible projection. The full prepared prompt is shown only on demand before approval and is not persisted in result details by default. `/tree` changes the active conversation branch; it cannot undo provider egress, billing, or external effects. Contract trace inspection, artifacts, and resumable sessions remain separate and deferred.
+
+## Revised Implementation Plan
+
+### Integration checkpoint: require a user-visible walking skeleton
+
+Fake-backend conformance proves contract and registry behavior, while the standalone SDK spike proved broader Pi provider behavior. The shipped walking skeleton sends a human-requested task through the complete profile-resolution, runtime-preflight, prompt-preparation, plan-validation, provider-execution, and response-projection path.
+
+The first concrete integration was a pi-forge-owned `pi-sdk-isolated` adapter plus a human-operated plan/run command. The current integration drives the runtime package's foreground `pi-subprocess-readonly` (default) and `pi-rpc-readonly` backends for the command and model-callable tool. It exposes only stack-filtered read/list/search tools, declares a shared-user boundary rather than filesystem isolation, requires explicit approval of an immutable plan bound to runtime-issued fingerprints, and returns bounded output plus expandable reports.
+
+This integration also exposed a contract seam hidden by the fake backend: backend-assisted preparation cannot require the caller to fabricate the prompt runtime that the backend is responsible for discovering. The backend must supply complete, canonical compiler inputs; the host must compile from them; and the registry must return the exact runtime/preparation pair used for execution-plan construction.
+
+### Iteration 1: Shared profile service
+
+- Extract shared typed profile repository operations for load, capture, save/update, and delete.
+- Extract profile application and rollback from command rendering.
+- Extract typed resolution preview and runtime/provenance drift status.
+- Refactor commands to use the service without changing current CLI behavior.
+- Add service-level tests so profile UI and subagent preparation share one implementation.
+
+### Iteration 2: Internal real-backend spike (completed)
+
+- Prototype one in-memory Pi SDK backend using a fresh `SessionManager`, explicit model/thinking, a controlled tool baseline, cancellation, and compact output.
+- Exercise a real profile, restrictive prompt stack, custom macro/slot dependency, media input, and current local provider.
+- Record actual SDK/runtime requirements and failure points.
+- Keep all spike types internal and expose no run tool.
+
+Implemented as the opt-in `scripts/subagent-sdk-spike.ts` (removed in the 0.4 cleanup after its findings were productized in the runtime's shared preparation gate); results and limitations are recorded in `SUBAGENT_SDK_SPIKE_FINDINGS.md`.
+
+### Iteration 3: Resolve/preflight/plan boundary (completed)
+
+- Split parent application resolution from backend-independent host resolution.
+- Define internal request, backend descriptor/preflight, backend-assisted preparation callback, execution-plan, response, enforcement-receipt, and diagnostic types based on the spike.
+- Implement protected task/context preparation and tool negotiation.
+- Validate null/replace/append/prepend stacks and missing custom dependencies.
+
+Implemented in `src/subagent-host.ts` and focused modules under `src/subagent/`, with `src/subagent-contract.ts` retained as a compatibility barrel. The SDK spike consumes the shared protected-task and host-resolution helpers.
+
+### Iteration 4: Stable validation and fingerprints (completed)
+
+- Add canonical snapshot/stack/execution digests without changing legacy provenance fingerprints.
+- Add pure validators and the full status/error/access/limit matrices.
+- Add deterministic context budgeting and artifact/trace namespace validation.
+- Export only the portions demonstrated by the real spike.
+
+Implemented with canonical `sha256:v1` fingerprints, deterministic UTF-8 context budgeting, access/limit/status matrices, artifact/trace validation, and package-root exports. Legacy profile provenance fingerprints are unchanged.
+
+### Iteration 5: Backend registration and conformance (completed)
+
+- Added an optional backend registry/dispatcher with validated descriptor discovery and granular capability negotiation.
+- Added a deterministic fake backend and reusable conformance fixtures shaped by the real spike.
+- Normalized cancellation races, host-abort timeouts, provider failures, malformed responses, enforcement receipts, and authorization-scoped trace routing.
+- pi-forge remains fully functional with no registered backend; the registry starts empty.
+
+### Iteration 6: Concrete Pi SDK walking skeleton (completed)
+
+- Correct backend-assisted prompt-runtime ownership and add complete compiler-input validation/fingerprints.
+- Extract an access-none, no-tool, in-memory Pi SDK backend from the completed spike.
+- Add human-operated backend discovery, dry plan, and explicit real-run commands through the registry.
+- Cover pre-transport refusal, provider failure, host timeout, cancellation, response normalization, and cleanup without live provider calls in ordinary tests.
+
+Implemented as the exported experimental `PiSdkIsolatedBackend` and `/forge-agent backends|plan|run` command path. Ordinary tests use Pi's faux provider through a real in-memory `AgentSession`, proving provider gating and final context without network traffic.
+
+### Iteration 7: Foreground parent integration (completed)
+
+- Added no-egress `forge_subagent_profiles` discovery so the main agent can select only from profile IDs explicitly enabled by trusted-project delegation policy rather than guessing.
+- Added the sequential `forge_subagent` tool on the shared command/runtime path rather than creating a second runner.
+- Added project-only `subagents.profiles.<id>` policy so ordinary profiles remain portable and independently usable while delegation eligibility, backend, and timeout are resolved per profile; global config remains limited to general defaults until global profile and stack storage have explicit scope semantics.
+- Resolve the profile and prepare the exact immutable plan before asking for interactive approval or permitting provider transport.
+- Show a compact default review, with full prompt inspection on demand, and bind approval to the execution fingerprint.
+- Insert only bounded response text into parent context while retaining complete transcript/tool-event details for expanded human inspection.
+- Keep execution text-only, foreground, clean-context, read-only, and shared-user; cancellation, rejection, provider failure, and missing-UI cases fail closed.
+
+### Iteration 8: Sandbox and staged-write decision
+
+- Evaluate an optional bubblewrap-style backend that can honestly enforce allowed roots, network policy, and subprocess restrictions without changing the portable contract.
+- Design writes as a separately approved staged patch/change set with clear inspection and undo semantics; do not simply add `write`, `edit`, or shell to the shared-user child.
+- Continue deferring resumable agents, retries, queues, chains, pipelines, background work, and concurrency orchestration until concrete demand exists.
+
+Profile UI can proceed independently on the completed Iteration 1 service; it does not need to block parent integration or a concrete adapter decision. Each iteration remains independently reviewable and revertible.
+
+## Deferred Decisions
+
+- Whether the experimental Pi SDK backend remains built in, becomes separately configurable, or moves to an optional integration after 0.4 feedback.
+- Trace/artifact storage location, retention defaults, redaction, and cleanup implementation.
+- Resumable sessions and continuation references.
+- Automatic retries, fallbacks, priorities, queues, and concurrency.
+- Secret/environment injection.
+- Structured JSON-schema output.
+- Automatic parent-context selection beyond explicit summaries and references.

package/docs/design/subagents/sdk-spike-findings.md

@@ -0,0 +1,117 @@
+# Historical Pi SDK subagent spike findings
+
+Status: completed internal spike against `@earendil-works/pi-coding-agent` 0.80.6 on 2026-07-12. Its contract findings are productized in `@zihanw/pi-subagent-runtime`'s shared SDK preparation gate, which both fresh-process backends use. The spike harness (`scripts/subagent-sdk-spike*.ts`) was removed in the 0.4 cleanup; with it went the only live media-transport and trusted-extension preparation diagnostic, to be re-established when delegated media tasks are productized. The 0.80.6 observations and terminology below remain a historical record.
+
+## Deliverable
+
+The spike was available through `npm run spike:subagent -- --cwd /path/to/project --profile PROFILE_ID` before its removal in the 0.4 cleanup.
+
+Dry-run is the default. A provider call requires `--execute`; that explicit flag is also the spike's consent to transmit the supplied task/media to the selected provider. The other spike-only flags are:
+
+- `--task TEXT`
+- `--timeout MILLISECONDS`
+- `--access none|read-only|workspace-write`
+- `--image PATH` (repeatable)
+- `--load-forge-extensions` to execute trusted global/project pi-forge registration code
+
+The command emits a JSON preflight/execution report. It creates an in-memory `SessionManager`, uses an isolated SDK resource directory and working directory for `access=none`, loads only the inline compiler bridge, does not write a Pi session file, and disposes the session and trusted registrations when finished.
+
+Execution currently rejects `read-only` and `workspace-write`. The SDK can filter tools, but this adapter cannot produce an allowed-root, symlink-safe filesystem/process/network isolation receipt. `access=none` is enforceable by setting the active tool set to empty.
+
+## Validated Behavior
+
+### Real profile, model, auth, and stack
+
+The dry and execute paths resolved `/home/bruhw/programming`'s `default` profile to:
+
+- Model: `opencode-go/glm-5.2`
+- Thinking: `high`
+- Stack: `qiqi-assistant`
+- Auth: configured through Pi's real `AuthStorage` and `ModelRegistry`
+
+The SDK session used those exact values, remained in memory, and exposed no session file. A real no-tool turn completed with `SPIKE_OK`.
+
+### Tool discovery and policy
+
+The isolated Pi 0.80.6 SDK session advertised seven built-ins: `read`, `bash`, `edit`, `write`, `grep`, `find`, and `ls`. This confirms that adapter discovery must be dynamic; neither pi-forge nor the contract should hard-code the interactive UI's historical four-tool baseline.
+
+The spike computes:
+
+```text
+backend catalog ∩ prompt-stack policy ∩ request access
+```
+
+It records the backend catalog, stack-selected names, effective names, unmatched allow patterns, and whether the requested access can actually be enforced. Tool selection worked for dry preflight, and `access=none` produced an empty effective set in real execution.
+
+Pi's public `ToolInfo` includes names, descriptions, parameter schemas, prompt guidelines, and source metadata, but not the one-line `toolSnippets` used by the base prompt. Those snippets are available in `before_agent_start.systemPromptOptions`. A dry plan built only from the public catalog is therefore intentionally marked `partial-dry-run`.
+
+### Exact prompt preparation and protected task
+
+The inline SDK extension receives the exact base system prompt and `BuildSystemPromptOptions` in `before_agent_start`, then calls the existing pi-forge compiler. On the first `context` event it:
+
+1. Removes the delegated task from unrestricted history compilation.
+2. Compiles optional history and synthetic prompt-stack messages.
+3. Appends a structured clone of the delegated text and media as the protected final user message.
+
+This preserved the task through `qiqi-assistant` and `image-viewer`, including layouts that add synthetic user messages. Offline tests also cover a `chat-history` slot configured to omit the latest user message and prove that it cannot remove the protected task.
+
+The exact `BuildSystemPromptOptions` are not publicly obtainable during passive SDK preflight. For a Pi SDK adapter, exact plan preparation must therefore be backend-assisted inside the accepted prompt lifecycle, after capability preflight but before the provider request. The adapter must fail the turn before transport if compilation or task-preservation validation fails.
+
+### Trusted custom macros and slots
+
+`--load-forge-extensions` explicitly loads trusted global/project pi-forge registration modules in the host. A dry fixture using `examples/custom-system-status-extension` validated that:
+
+- The extension module was discovered and registered.
+- Prompt stacks were reloaded and revalidated after registration.
+- The `cpuLoad` macro and `machine-status` slot compiled without stale unsupported-slot diagnostics.
+- Registrations were unloaded during cleanup.
+
+This supports keeping executable dependencies in the trusted host. It also confirms that host resolution must load required registrations before final stack validation. Dependency identity and missing-dependency receipts remain future work.
+
+### Media
+
+A real `opencode-go/qwen3.7-plus` turn used the `image-viewer` profile and a 1.6 MB PNG. The model received the image, completed successfully, and identified the visible Pi symbol. The final structured task and image were preserved by the prompt-stack layout.
+
+Preflight rejects image input when the selected model does not advertise `image` support. File paths are converted to SDK `ImageContent` only for explicitly supplied `--image` references.
+
+### Timeout, cancellation, response, and trace
+
+A real `glm-5.2` turn with a 1 ms host deadline called `session.abort()`, settled in roughly 70 ms, reported `timed-out`, and recorded zero provider tokens/cost. A normal run reported completion, output, duration, session statistics, and a compact normalized lifecycle trace.
+
+The SDK does not enforce hard turn, token, or output limits through `createAgentSession`. Its statistics report numeric cost without a currency code. Future response normalization must mark those limits unsupported and treat cost currency as unknown unless the adapter can supply it.
+
+The spike trace includes lifecycle and tool start/end metadata only. It excludes streaming content, provider payloads, credentials, and hidden reasoning.
+
+## Contract Revisions Implemented
+
+1. Split backend work into discovery/preflight, backend-assisted plan preparation, and execution. Preparation may occur inside an adapter-controlled pre-provider hook when the backend cannot expose exact prompt-runtime inputs earlier.
+2. Keep the host responsible for profile/stack resolution, trusted compiler execution, protected-task assembly, diagnostics, and plan validation, even when the adapter supplies runtime inputs through a callback.
+3. Do not require a passive dry preflight to reproduce the exact prompt when the backend cannot expose all inputs. Record prompt-runtime fidelity and reject execution if exact preparation cannot be completed before provider transport.
+4. Make tool discovery dynamic and include a separate prompt-runtime receipt; `ToolInfo` alone is insufficient to recreate Pi's prompt.
+5. Treat tool filtering and access isolation as separate receipts. The current Pi SDK adapter supports only `access=none` honestly.
+6. Distinguish backend-native limits from host best-effort controls. The observed timeout uses host abort and is not proof of process-level hard isolation.
+7. Load trusted macro/slot registrations before final stack validation and later add explicit dependency identities/fingerprints.
+8. Normalize assistant error/aborted stop reasons because `session.prompt()` may settle with a terminal assistant message rather than throw.
+
+## Remaining Concrete-Adapter Gaps
+
+- No allowed-root filesystem, subprocess, or agent-network isolation.
+- No hard turn, token, or output-byte enforcement.
+- The retained SDK adapter exposes an empty tool catalog. The default subprocess adapter adds only stack-filtered `read`, `grep`, `find`, and `ls`, under an explicit shared-user rather than sandboxed boundary.
+- The registry, model-callable foreground tool, and text-only subprocess backend now exist, but there is still no artifact store, contract trace storage, media resolution in the shipped path, sandbox enforcement, or staged write workflow.
+- Custom dependency scanning records macro/slot names and registration sources, but it cannot fingerprint executable registration code.
+- The command/tool is foreground-only and does not expose a separate cancel command; Pi/host abort signals and host timeouts terminate the active SDK session or subprocess on a best-effort basis.
+
+These gaps do not block the approval-gated read-only foreground workflow. They do require the UI and receipts to keep saying shared-user, and they rule out adding direct write/shell tools until stronger sandboxing or a separately approved staged-change design exists.
+
+## Verification Evidence
+
+- Offline suite covers the contract matrix, fake-backend conformance, command consent/dry-plan behavior, and concrete SDK execution through Pi's faux provider and a real in-memory `AgentSession` without network traffic.
+- TypeScript typecheck: passed.
+- Real profile dry preflight: passed.
+- Real `glm-5.2` no-tool completion: passed.
+- Real host-timeout/abort case: passed.
+- Real `qwen3.7-plus` PNG input: passed.
+- Trusted custom macro/slot dry fixture: passed.
+
+The generated reports were inspected during the spike and were not committed because they contain machine-specific paths, run IDs, timing, and provider usage.