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

package/CHANGELOG.md

@@ -0,0 +1,160 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+In 0.x development, breaking changes may occur in minor releases and will be explicitly noted.
+
+## [Unreleased]
+
+## [0.4.0-beta.1] - 2026-07-18
+
+### Added
+
+- **Main-agent profile discovery.** Added the no-egress `forge_subagent_profiles` tool. It returns loaded profile IDs, names, descriptions, declared model/thinking/stack metadata, ready/unavailable resolution diagnostics, and whether parent policy currently exposes `forge_subagent`, without preparing a child prompt or contacting a provider.
+- **Approval-gated foreground subagents.** Added the model-callable `forge_subagent` tool and moved `/forge-agent run` onto the same prepare-review-execute path. Every run prepares an immutable exact plan before provider transport. `/forge-agent run` and the default tool path show a compact task/profile/provider/model/thinking/tool/boundary/fingerprint summary, permit on-demand inspection of the full provider-bound prompt, and require explicit interactive human approval.
+- **Explicit unattended tool authorization.** Trusted projects may set `subagents.allowAgentInvocationWithoutApproval: true` in `.pi/forge/config.json` to let the parent agent invoke only the model-callable `forge_subagent` tool without per-run UI. Profile discovery exposes the active mode, result receipts record `trusted-project-config`, and missing, malformed, or untrusted-project settings fail closed.
+- **Read-only Pi subprocess backend.** Added the experimental `pi-subprocess-readonly` backend as the extension default. It runs one sequential foreground Pi subprocess with a clean conversation and only stack-filtered `read`, `grep`, `find`, and `ls` tools; write, edit, shell, skills, templates, context files, and third-party extensions are disabled.
+- **Inspectable subagent reports.** Foreground progress and bounded output now return through a normal Pi tool call result. Expandable result details retain the approval receipt, plan summary, normalized response, diagnostics, usage, bounded transcript tail, and tool calls/results while the full compiled prompt remains transient unless the user explicitly opens it before approval.
+- **Explicit shared-user execution boundary.** Access receipts can now distinguish isolated execution from a shared-user subprocess. The latter cannot claim mount, symlink, process, or network isolation and documents that read-only model tools do not reduce the child process's operating-system permissions.
+- **Public API classification.** Added a dedicated experimental `@zihanw/pi-forge/subagent` entry point and documented stable, experimental, and internal compatibility surfaces while preserving existing package-root exports.
+- **Optional subagent backend registry.** Added empty-by-default validated backend registration, accepted-preflight binding, exact/backend-assisted preparation dispatch, execution and cancellation arbitration, host-abort timeout handling, failure normalization, and authorization-scoped trace routing. Deterministic fake-backend conformance tests cover the full adapter status and enforcement matrix.
+- **Experimental isolated Pi SDK backend.** Added a pi-forge-owned, text-only `pi-sdk-isolated` adapter backed by an in-memory Pi `AgentSession`. It accepts only access `none`, advertises no agent tools or stored artifacts/traces, blocks provider transport until exact host preparation and immutable-plan validation complete, and cleans up temporary runtime state after execution or discard.
+- **Human subagent test commands.** Added `/forge-agent backends`, `/forge-agent plan <profile> <task>`, and `/forge-agent run <profile> <task>`. Dry planning exercises the complete request pipeline without provider transport; TUI execution requires explicit provider-egress confirmation and returns a compact normalized response.
+
+- **Native one-shot agent profiles.** Project profiles under `.pi/forge/agent-profiles` store an exact model, thinking level, and prompt-stack reference. `/profile use` preflights and applies once, `/profile save` captures the current runtime, and list/status/preview/validate/reload/forget commands cover diagnostics, drift, direct file editing, and branch-scoped provenance without automatic reapplication.
+- **Profile resolution API.** Exported strict profile types, loading, validation, exact model/auth/thinking/stack resolution, fingerprints, provenance guards, and diagnostics for future subagent adapters without adding a runner dependency. Prompt stacks remain the single source of truth for tool policy and model-visible skill filtering.
+- **Fresh-session profile auto-activation.** One profile may opt into `autoActivate: true` to apply its model, thinking level, and prompt stack once for each fresh session. Profile selection takes precedence over standalone stack autoload, restored branch state remains authoritative, and invalid or ambiguous startup profiles fail closed without producing a hybrid configuration.
+- **Browser-level editor smoke coverage.** CI now launches the real localhost editor in headless Chrome and verifies load, metadata editing, validation, policy guidance, save, and browser-console behavior.
+- **Runner-neutral subagent adapter contract.** Exported pure request, host-resolution, backend-preflight, backend-assisted preparation, execution-plan, enforcement-receipt, and discriminated response APIs. The contract includes custom macro/slot dependency receipts, effect-aware tool negotiation, protected task/media assembly, deterministic UTF-8 context budgeting, canonical `sha256:v1` fingerprints, and access/limit/status/artifact/trace validators without registering a backend or adding parent run tools.
+- **Internal Pi SDK adapter spike.** Added an opt-in dry-run/execute harness that validates real profiles, exact lifecycle prompt preparation, in-memory sessions, no-access execution, timeout abort, media transport, and trusted custom registrations against Pi 0.80.6.
+
+### Fixed
+
+- **Terminal subprocess cancellation.** Cancelled and timed-out registry responses now wait for backend execution to drain. The subprocess backend awaits child closure with bounded TERM-to-KILL escalation during cancellation and disposal, terminalizes pre-spawn failures, and removes temporary run data before the foreground result settles.
+- **Bounded retained subagent transcripts.** Retained transcript strings are capped, base64-like text is redacted in addition to canonical image blocks, stderr is bounded, and report messages keep a 512 KiB rolling tail with explicit omission metadata. This prevents pathological textual output from recreating the TUI/session lag caused by the original inline-image transport.
+- **Binary-safe subagent image reports.** The child no longer sends Pi's complete JSON lifecycle stream to the parent, where repeated inline image blocks could exceed the 8 MiB transport limit and make the TUI retain megabytes of base64. A dedicated sanitized report channel preserves images inside the child for vision-provider requests, emits only image metadata to the parent, and defensively sanitizes the retained tool details again.
+- **Pi 0.80.10 subagent authentication.** Subagent preparation now reuses the parent `ModelRuntime` when creating its temporary `AgentSession`, preserving the parent's OAuth/API-key state instead of passing session options that Pi 0.80.10 ignores. An offline regression test covers the extension's real model-registry-only path.
+- **Fail-closed subagent egress consent.** `/forge-agent run` and the default `forge_subagent` path refuse non-UI execution instead of treating the absence of an interactive confirmation surface as approval. Only the explicit trusted-project unattended setting bypasses the tool's per-run UI. Exact preparation remains behind a closed provider gate, and dry planning remains available without provider transport.
+- **Cancellation before backend dispatch.** An external abort that wins before backend execution now discards the prepared backend state without calling `execute()`. Concrete Pi SDK cancellation and host-timeout tests verify `AgentSession` abort and temporary-runtime cleanup.
+- **Web editor lifecycle refresh.** Reused editor servers now bind ordinary lifecycle contexts separately from snapshotted system-prompt options, so resource inventory and preview remain available after startup reload, tree navigation, compaction, and extension reinitialization.
+- **Trusted extension disposal and reload.** Runtime shutdown unregisters owned custom macros and slots before replacement. Every ESM load receives a process-unique cache token, while CommonJS entry caches are cleared, so `.ts`, `.mjs`, CommonJS `.js`, and `.cjs` extension edits reload without duplicate registrations or stale entry code.
+- **Strict prompt-stack input validation.** Behavior-changing booleans, enums, defaults, context fields, variables, and item shapes are diagnosed before recovery normalization. Malformed values can still be displayed for repair but can no longer become an automatically usable stack.
+- **Immutable stack identity on save.** Existing stack IDs are read-only in the web editor, and the save API rejects body/URL ID mismatches without writing files or changing active selection. Fork remains the supported way to create a new ID.
+- **Token-accounting payload visibility.** Provider payload redaction preserves known token limits, usage counters, budgets, and tokenizer metadata while continuing to hide generic and credential-shaped token fields.
+- **Tool policy restoration and enforcement across Pi reload.** pi-forge now restores the pre-policy active tool set during extension shutdown, waits for other extensions to finish their startup tool configuration before recapturing it, and reapplies restrictive policy before input and turns. A tool-call guard blocks disallowed execution even if another extension later calls `setActiveTools()`. This prevents both missing built-ins after `/preset use none` and late-added extension tools bypassing an active stack policy.
+- **Skill-policy semantics.** Validation, documentation, and editor guidance now state that skill policy filters model-visible pi-forge skill listings; it does not disable explicit skill invocation and is not a security boundary.
+
+### Changed
+
+- The npm tarball no longer includes physical `src/` files and uses compiled runtime entries. Legacy `@zihanw/pi-forge/src/*` imports continue to resolve to compiled modules, while development documentation directs source modifications through a repository clone and explicit local TypeScript extension entry.
+- The extension entry point is now a small composition root; prompt-stack state, one-shot profile activation, tool-policy/preview behavior, and shared web-editor lifecycle live in focused runtime modules.
+- The web editor client is authored as strict TypeScript modules for API transport, DOM access, policy editing, regex editing, preview/payload inspection, and orchestration. A build-only esbuild step produces the self-contained script used by the localhost editor, and verification rejects stale generated output.
+- The subagent contract implementation is split into focused type, canonicalization, request, preflight, tool, context, plan, response, and diagnostic modules. Existing package-root and `src/subagent-contract.ts` exports remain compatibility barrels with an exact import-surface test.
+- Backend-assisted preparation now makes the adapter, rather than the caller, provide the complete runtime compiler inputs. The registry fingerprints and validates that runtime, invokes the host compiler exactly once, binds the resulting prompt/messages/tools to execution, routes discard through the owning backend, and rejects adapters or callers that bypass, alter, or refingerprint a substitute host result.
+- Profile commands now consume shared typed repository, application, preview, provenance, and drift-status services, establishing one behavioral core for profile UI and future subagent preparation.
+- Package metadata now declares Node.js 22.19+ and pins the Pi peer/runtime/development packages to exactly 0.80.10. Pi changed session runtime wiring within 0.80.x, so this beta no longer claims compatibility with 0.80.6–0.80.9 or unverified later 0.80.x releases.
+- The roadmap now records the approval-gated foreground subprocess path and moves forward to sandboxing, staged writes, profile UI, and release hardening without adding background orchestration.
+
+## [0.3.2] - 2026-07-07
+
+### Added
+
+- **Global forge extensions.** pi-forge now loads trusted macro/slot registration modules from `~/.pi/forge/extensions` before project-local `.pi/forge/extensions`, so users can keep personal custom macros and slots available across projects without importing `@zihanw/pi-forge`.
+
+### Changed
+
+- `/preset list` now shows both global and project forge extension directories.
+- Documentation and examples now describe global and project-local forge extension placement.
+- No breaking changes.
+
+## [0.3.1] - 2026-07-07
+
+### Added
+
+- **Parser-backed macro expansion.** Macros now support nested `{{...}}` expressions and split `::` arguments only at the current macro depth.
+- **Macro filters and lazy conditionals.** Added `{{trim}}`, `{{upper}}`, `{{lower}}`, `{{json}}`, `{{xml}}`, plus lazy `{{ifvar}}`, `{{ifeq}}`, `{{iftools}}`, and `{{ifslot}}` conditionals. Skipped conditional branches are not expanded, so they cannot mutate variables.
+- **Trusted custom macro and slot APIs.** Added `registerMacro`, `registerSlot`, `getRegisteredMacros`, `getRegisteredSlots`, shared render helpers, and process-global registries so trusted Pi extensions can add custom macros and slots without embedding executable code in stack JSON.
+- **Project-local forge extensions.** Added trusted `.pi/forge/extensions` modules for project-local macro/slot registration. pi-forge loads them before stack validation, reloads them on `/preset reload`, and lists loaded files or load warnings in `/preset diagnostics`.
+- **Example custom extension.** Added `examples/custom-system-status-extension`, which registers a `{{cpuLoad}}` macro and `machine-status` slot from a project-local forge extension module.
+- **Slot registry and date-time option.** Built-in slots now use the public slot registry, and `date` / `date-cwd` slots support `includeTime: true`.
+- **Web editor: new stack workflow.** The browser can create a stack even when no stack files exist yet. New stacks start from the default Pi prompt mirror layout so users can edit a complete working stack instead of a blank skeleton.
+- **Web editor: policy resource picker.** The Policy tab now lists registered tools and loaded skills, marks active tools and hidden skills, hides exact selected names from the available list, supports removable selected-pattern chips, and includes a filter/autocomplete input for adding exact names while keeping wildcard/manual textarea editing.
+- **Web editor shortcuts.** Added browser shortcuts for new stack, save, validate, preview, and closing dialogs/inspectors.
+- **Web editor item actions.** Added direct Add block and Add slot actions.
+- **Read-only web resource inventory API.** Added editor host support for listing known tools and skills for UI policy editing.
+
+### Fixed
+
+- **Package install exports.** Installs now load compiled `dist` JavaScript instead of raw `.ts` files under `node_modules`, so `import { registerMacro, registerSlot } from "@zihanw/pi-forge"` works for reusable trusted extension packages without relying on Node TypeScript stripping. Git installs include the compiled output and do not require TypeScript during Pi's `npm install --omit=dev` step.
+- **Preview policy simulation.** Web preview now compiles with the edited stack's tool policy applied to selected tools, snippets, and tool guidelines. This prevents preview from showing unrelated tool guidelines from the current Pi tool state.
+- **Empty-project web editor UX.** Empty stack directories now show a create/import path instead of leaving the editor in a dead-end state.
+
+### Changed
+
+- Documentation and feature inventory now describe the 0.3.1 web editor workflow.
+- No breaking changes.
+
+## [0.3.0] - 2026-06-30
+
+### Breaking Changes
+
+- **Tool/skill policy no longer allows mixed `allow` and `deny` lists.** Each resource policy (`tools`, `skills`) must use either `allow` **or** `deny`, not both. Stacks with non-empty mixed lists now produce validation errors. Previously, concrete `allow` patterns silently took priority over `deny`. Update your stack JSON to use one list per resource.
+  - Before: `{ "tools": { "allow": ["read", "bash"], "deny": ["*"] } }`
+  - After: `{ "tools": { "allow": ["read", "bash"] } }` or `{ "tools": { "deny": ["write"] } }`
+- `PromptResourcePolicy` type changed from `{ allow?: string[]; deny?: string[] }` to a discriminated union: `{ allow?: string[]; deny?: never } | { allow?: never; deny?: string[] }`.
+
+### Added
+
+- **Regex transforms.** Deterministic JavaScript `RegExp` find/replace on prompt text, ordered as stack-level `regex.rules`.
+	  - `stage: "history"` — transforms messages inserted by the `chat-history` slot, with role filters, depth filters, `maxMessages`, and `maxChars`.
+	  - `stage: "compiled"` — transforms final system prompt and/or message text before provider serialization, with `targets`, role filters, depth filters, `maxMessages`, and `maxChars`.
+	  - `trimStrings` supports deterministic SillyTavern-style Trim Out behavior for expanded replacement matches/captures.
+  - `effect: "finalize"` — destructively rewrites completed assistant messages at `message_end`. Original model output is not preserved.
+  - Supported flags: `g`, `i`, `m`, `s`, `u`. Invalid patterns, duplicate IDs, and unsupported flags are rejected during validation.
+  - Runtime diagnostics report match counts and changed text segments.
+- **Tool and skill policy.** Stack-level `tools.allow`/`tools.deny` and `skills.allow`/`skills.deny` with exact names and `*` wildcards. Tool policy is enforced through `pi.setActiveTools()` and restored when the stack is disabled or switched. Skill policy filters rendered `skills` slots and respects `disableModelInvocation`.
+- **Web editor: Policy tab.** Structured editor for tool and skill policies with mode selector (Unrestricted / Allow / Deny), pattern textarea, duplicate detection, and live policy summaries.
+- **Web editor: Payload inspector.** Arm the next provider request from the UI, display captures with collapsible JSON sections, redaction preserved, char/token estimates, and copy controls. Captures triggered by `/payload next` are also visible in the browser.
+- **Web editor: Full-screen structured preview inspector.** Collapsible system/message sections, char/token estimates, and copy controls for full preview and individual sections.
+- **Web editor: Structured editors** for stack `context` options, `variables`, tool/skill policy, and `regex.rules` with drag-and-drop reordering.
+- **Web editor: Raw JSON recovery path.** View, copy, and apply raw stack JSON for advanced stack-level fields.
+- **Compact prompt slot formats.** Opt-in `format: "plain"` for `tools`, `tool-guidelines`, `skills`, `project-context`, and `variables` slots. XML remains the default.
+- **Chat-history controls.** `chat-history` slots can opt into `stripAssistantThinking: true`, summary omission, role filters, `toolMode: "drop"`, `maxMessages`, and `maxChars`. Filtering/trimming repairs dangling tool calls/results before model-bound history is sent.
+- **Prompt-stack storage migration.** New stacks write to `.pi/forge/prompt-stacks/`; legacy `.pi/prompt-stacks/` remains readable and is shadowed by same-named forge files. `/preset migrate-stacks [--dry-run] [--overwrite] [--delete-legacy]` copies legacy stacks into forge storage.
+- **SillyTavern regex import.** Safe `promptOnly` regex scripts are converted into pi-forge outgoing `history` regex rules during import, including `{{match}}` / `$0` full-match conversion, trim strings, depth fields, clear user/assistant placement mapping, and preserved `source.sillytavern` metadata. Display-only, mixed, JavaScript, DOM/browser, CSS/HTML decoration, and unsupported-placement scripts remain report-only with migration notes.
+- **`/preset ui` server reuse.** Existing same-project editor servers are reclaimed after extension reinitialization from session navigation or new-session flows, preventing orphaned servers.
+- **`/payload next [save=<path>]` command.** Displays and optionally saves the next redacted/truncated provider payload with char/token estimates.
+- **`/preset migrate-stacks` command** with `--dry-run`, `--overwrite`, and `--delete-legacy` options.
+
+### Changed
+
+- **Web editor architecture split.** `src/web-editor.ts` split into `src/web-editor/` module folder (`index.ts`, `types.ts`, `server.ts`, `page.ts`). `src/index.ts` split into `src/web-host.ts` (stack CRUD/web-editor host) and `src/payload-capture.ts` (provider payload redaction/capture).
+- **Prompt state removed before 0.3.0 release.** pi-forge now keeps template variables and SillyTavern-style variable macros, but no longer exposes stack `state.definitions`, `/state`, `/preset vars`, `forge_state_set`, `forge_set_var`, state metadata rendering, or web runtime state editing.
+- **Context rewrite** limited to the first provider request of each user-submitted turn, avoiding repeated injection after tool calls.
+- **`/preset import-silly`** now detects `{{lastUserMessage}}` and configures chat history accordingly. SillyTavern `{{setvar}}`/`{{getvar}}` macros reported as handled instead of migration-needed.
+- **`/preset reload`** preserves explicit disabled selection instead of reactivating `default.json`.
+- SillyTavern import reports now include `extensions.regex_scripts` counts, prompt/display classification, script names, per-script conversion warnings, and migration notes.
+
+### Removed
+
+- Implicit `allow`-takes-priority-over-`deny` behavior in resource policy evaluation.
+- Prompt-state memory layer: `state.definitions`, `/state`, `/preset vars`, `forge_state_set`, `forge_set_var`, metadata/namespace/JSON prompt-state rendering, and web runtime state editing.
+
+## [0.2.0] - 2025-06-13
+
+### Added
+
+- File-backed prompt stacks with `replace`, `append`, and `prepend` system prompt modes.
+- Movable `chat-history` slot with optional omission of latest user message.
+- Runtime slots: `tools`, `tool-guidelines`, `skills`, `project-context`, `append-system-prompt`, `date`, `cwd`, `date-cwd`, `active-model`, `pi-docs`, `variables`.
+- Built-in macros: `{{cwd}}`, `{{date}}`, `{{time}}`, `{{lastUserMessage}}`, `{{selectedTools}}`, `{{tools}}`, `{{activeModel}}`.
+- Turn/session/static variable lookup and mutation macros.
+- Branch-aware macro session variable restoration during session tree navigation.
+- `/preset` commands: `list`, `status`, `use`, `preview`, `validate`, `diagnostics`, `reload`, `vars`, `ui`.
+- `/intercept` command for next provider payload inspection.
+- `/preset import-silly` command for SillyTavern preset import with import reports.
+- `/preset ui` local web editor for prompt-stack management.
+- Node built-in test suite covering compiler, loader, importer, and command/event harness.
+- Chinese README (`README.zh-CN.md`).

package/PUBLIC_API.md

@@ -0,0 +1,28 @@
+# 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.
+
+## Stable
+
+- 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.
+
+Stable means changes should preserve source compatibility within the documented supported release range unless a changelog entry explicitly announces a breaking release.
+
+## Experimental
+
+- Agent-profile repository, resolution, application, preview, provenance, and drift APIs are 0.4 experimental surfaces.
+- The runner-neutral subagent contract, host-resolution helpers, optional empty-by-default backend registry, retained `PiSdkIsolatedBackend`, and default `PiSubprocessBackend` adapter are 0.4 experimental surfaces.
+- New subagent integrations should import from `@zihanw/pi-forge/subagent`. The package root continues to re-export the current subagent names through the 0.4 prereleases for compatibility.
+
+Experimental APIs are typed, tested, and documented, but may be revised before the 0.4 release as real adapter and parent-integration work exposes missing semantics. Changes should still be deliberate and recorded.
+
+## Internal compatibility paths
+
+- `@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.
+- `src/subagent-contract.ts` is a compatibility barrel over the focused contract modules; it does not contain a second implementation.
+- 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.
+- `scripts/subagent-sdk-spike*.ts` are diagnostic development interfaces, not a supported runner API.
+
+Before removing the compatibility subpaths, check known consumers, announce the change, and provide supported package entry points for legitimate integrations.

package/README.md

@@ -4,7 +4,7 @@
 
 ![pi-forge header](https://raw.githubusercontent.com/MacroSony/pi-forge/main/assets/pi-forge-header-concept-1.png)
 
-**pi-forge** lets you customize how Pi thinks and behaves. It gives you prompt stacks — JSON files that can replace, append to, or prepend Pi's default system prompt while controlling the AI's personality, visible tools, conversation history layout, template variables, and prompt transforms.
+**pi-forge** lets you customize how Pi thinks and behaves. It gives you prompt stacks for prompt/tool policy and agent profiles that apply a model, thinking level, and prompt stack as a reusable one-shot preset.
 
 Think of it as a character sheet for your AI agent.
 
@@ -12,6 +12,7 @@ Think of it as a character sheet for your AI agent.
 
 - **Give Pi a personality** — turn it into a creative writer, a roleplay partner, a strict code reviewer, or anything in between.
 - **Switch contexts instantly** — one command to swap between "coding mode", "writing mode", and "translation mode".
+- **Save complete agent presets** — capture the current model, thinking level, and prompt stack, then apply them together later.
 - **Control what the AI sees** — choose which tools, skills, and project context appear in each prompt.
 - **Limit tools and skills per stack** — enforce active tool policy and filter skill visibility for focused modes.
 - **Use template variables** — define static values such as `{{char}}` / `{{user}}`, and use ST-style turn/session variable macros inside prompt text.
@@ -24,9 +25,13 @@ Think of it as a character sheet for your AI agent.
 ### Install
 
 ```bash
-pi install npm:@zihanw/pi-forge
+pi install npm:@zihanw/pi-forge@0.4.0-beta.1
 ```
 
+The beta is published under npm's `next` channel rather than replacing the stable `latest` release. It requires Node.js 22.19 or newer and the exact `@earendil-works/pi-*` 0.80.10 packages used by Pi 0.80.10.
+
+> **Pi version compatibility:** Pi changed session authentication/runtime wiring within the 0.80.x line. This build targets 0.80.10 exactly; 0.80.6–0.80.9 and later unverified 0.80.x releases are not claimed as compatible. After installing or rebuilding pi-forge, restart Pi so the extension and host SDK agree. If the parent agent can use a provider but subagent preparation reports `No API key found`, check for an older pi-forge build before using `/login`: a build using the pre-0.80.10 session API can lose the parent authentication during preparation, and logging in again does not fix that version mismatch.
+
 ### Your first prompt stack
 
 Create `.pi/forge/prompt-stacks/default.json` from [examples/default-prompt-stack.json](examples/default-prompt-stack.json).
@@ -50,11 +55,11 @@ Prefer clicking over typing JSON? pi-forge has a built-in web editor:
 /preset ui
 ```
 
-Drag, drop, create, edit, validate, inspect full previews and captured payloads, manage variables/context/regex rules in tabs, switch dark mode, recover through raw stack JSON, import, export, fork, and delete stacks — all in your browser. New stacks start from the default Pi prompt mirror layout. Stack metadata is collapsible so the active editor stays in view. The policy tab shows registered tools and loaded skills with selected-pattern chips and filtering, so allow/deny rules can be built from exact names while still supporting wildcards.
+Drag, drop, create, edit, validate, inspect full previews and captured payloads, manage variables/context/regex rules in tabs, switch dark mode, recover through raw stack JSON, import, export, fork, and delete stacks — all in your browser. New stacks start from the default Pi prompt mirror layout. Existing stack IDs are immutable; use Fork to create a new ID without risking profile references or active selection. Stack metadata is collapsible so the active editor stays in view. The policy tab shows registered tools and loaded skills with selected-pattern chips and filtering, so allow/deny rules can be built from exact names while still supporting wildcards.
 
 Import accepts native pi-forge stack JSON and SillyTavern preset JSON. SillyTavern presets are converted to prompt stacks automatically; if a preset contains multiple `character_id` configs, the editor asks which one to use.
 
-The editor runs on an available `127.0.0.1` port with a session token, so multiple Pi instances can run editors at the same time. If Pi reinitializes the extension after session navigation or a new session, `/preset ui` reuses the existing editor URL for the same project instead of orphaning the old server. Writes require a trusted project and stay inside prompt-stack storage. New stacks are written to `.pi/forge/prompt-stacks`; existing legacy stacks under `.pi/prompt-stacks` remain readable and editable. Successful save, import, fork, and delete actions reload into the current Pi session. Use `/preset ui restart` or `/preset ui stop` when needed.
+The editor runs on an available `127.0.0.1` port with a session token, so multiple Pi instances can run editors at the same time. If Pi reinitializes the extension after session navigation or a new session, `/preset ui` reuses the existing editor URL for the same project instead of orphaning the old server; resources and preview remain available across lifecycle refreshes. Writes require a trusted project and stay inside prompt-stack storage. New stacks are written to `.pi/forge/prompt-stacks`; existing legacy stacks under `.pi/prompt-stacks` remain readable and editable. Successful save, import, fork, and delete actions reload into the current Pi session. Use `/preset ui restart` or `/preset ui stop` when needed.
 
 To copy old stacks into the new location, run `/preset migrate-stacks`. Add `--dry-run` to preview, `--overwrite` to replace existing target files, and `--delete-legacy` to remove old files after successful copy.
 
@@ -68,6 +73,70 @@ To prefer a specific port, create `.pi/forge/config.json`. If that port is busy,
 }
 ```
 
+### Agent profiles
+
+Agent profiles are project-local JSON files under `.pi/forge/agent-profiles`. The quickest way to create one is to configure Pi normally and capture the current model, thinking level, and prompt-stack selection:
+
+```text
+/profile save reviewer
+/profile use reviewer
+```
+
+Profiles are applied once. They do not continuously own Pi's model or thinking level, so later manual changes are preserved until `/profile use reviewer` is run again. Prompt-stack tool policy remains strict for as long as that stack is active.
+
+A profile can also be written directly:
+
+```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"
+}
+```
+
+`autoActivate: true` applies the complete profile once when Pi starts a fresh session. At most one profile may request auto-activation. An auto-activated profile takes precedence over standalone prompt-stack autoload, including when its `promptStack` is `null`; if no profile requests auto-activation, the existing `default.json`/`autoActivate` stack behavior remains the fallback. Restored branch selections take precedence over both mechanisms.
+
+`promptStack` may be `null`. Tool names and skill lists do not belong in profile v1: the referenced prompt stack is the single source of truth for tool policy and model-visible skill filtering. Profile validation rejects unsupported fields rather than silently retaining inert generation or runner settings.
+
+`/profile preview <id>` resolves the model, authentication, thinking-level support, prompt stack, and effective tools without changing runtime state. `/profile status` reports the last-applied profile and current drift; it deliberately does not describe a profile as active. Provenance follows the session branch for status purposes but never causes automatic reapplication during reload, resume, tree navigation, or compaction. Fresh-session auto-activation is still one-shot, so later manual changes are preserved.
+
+### Experimental foreground subagent
+
+The 0.4 beta can run a stored profile as a separate, clean, one-shot Pi subprocess. The no-egress `forge_subagent_profiles` tool lets the main agent discover the currently loaded profile IDs, names, descriptions, declared model/thinking/stack, current resolution status, and approval mode. It should call that first when the user has not specified a profile, then invoke `forge_subagent`. A restrictive main-agent prompt stack must permit both tool names. The same execution path remains available to a human through commands:
+
+```text
+/forge-agent backends
+/forge-agent plan reviewer Review this API design for correctness.
+/forge-agent run reviewer Review this API design for correctness.
+```
+
+`plan` resolves the profile and stack, compiles the exact provider-bound prompt, validates an immutable execution plan, and then discards it without contacting the provider. `/forge-agent run` and, by default, `forge_subagent` prepare that same exact plan before showing an approval screen. The default screen shows the agent task, profile/stack, provider, model, thinking level, effective tools, working directory, security boundary, payload size, and execution fingerprint. Choose **View full prompt** to inspect the complete system prompt and ordered provider-bound messages before approving; any editor changes are ignored.
+
+To deliberately let the parent agent invoke `forge_subagent` without per-run approval, set the following trusted-project option in `.pi/forge/config.json`:
+
+```json
+{
+  "subagents": {
+    "allowAgentInvocationWithoutApproval": true
+  }
+}
+```
+
+This option affects only the model-callable `forge_subagent` tool; `/forge-agent run` remains interactively approved. The exact preflight and immutable-plan checks still run, and the tool result records `trusted-project-config` as its authorization source, but provider transport begins without showing the prompt to a human. Profile discovery reports the active approval mode. The setting is ignored for untrusted projects and malformed values fail closed. Treat the project config as authorization: do not enable or commit this option in a repository unless every parent agent allowed to use `forge_subagent` should be able to send the compiled prompt and readable file contents to the selected provider without asking again.
+
+The child starts with a clean conversation and receives no parent history automatically. It runs in the foreground with the profile's exact model/thinking level and prompt stack. Its only candidate tools are `read`, `grep`, `find`, and `ls`, further restricted by the stack's tool policy; it receives no write/edit/shell tools, skills, prompt templates, context files, or third-party extensions. The final tool result contains a bounded model-visible report plus expandable human-visible execution details. Retained transcript strings are individually bounded, base64-like text is redacted, and the transcript keeps a 512 KiB rolling tail so the final report remains available without making the TUI retain an unbounded tool history. Inline image data stays inside the child long enough for the selected vision model to use it, but the dedicated report channel replaces binary payloads with MIME type and encoded-size metadata before anything is retained in the parent session.
+
+Important: this first backend is **shared-user**, not an operating-system sandbox. Read-only is a model-tool policy: the subprocess retains the invoking user's OS permissions, and absolute paths readable by that user may be read, sent to the selected provider, and retained as text inside the parent tool-result details. Host timeout and cancellation are best effort. `/tree` removes the invocation and result from the active conversation branch, but abandoned entries can remain in Pi's on-disk session JSONL; deleting sensitive retained text requires deleting the relevant session data. `/tree` also cannot undo provider requests, billing, or external side effects. The default tool set intentionally provides no filesystem mutation path while a bubblewrap-style sandbox and staged write mode remain future work.
+
 ## Use cases
 
 ### 🎭 Roleplay & creative writing
@@ -156,7 +225,7 @@ See exactly what gets sent to the model:
 /payload next save=.pi/forge/payloads/last.json
 ```
 
-Or open `/preset ui`, click **Arm payload**, send the next Pi prompt, and inspect the redacted provider payload in the browser.
+Or open `/preset ui`, click **Arm payload**, send the next Pi prompt, and inspect the redacted provider payload in the browser. Credential-shaped token fields remain hidden, while normal limits and accounting fields such as `max_tokens`, `input_tokens`, and `output_tokens` remain visible.
 
 Or preview your compiled prompt without sending anything:
 
@@ -220,6 +289,29 @@ Items are arranged in order. When the stack is active, pi-forge:
 | `/preset migrate-stacks [--dry-run] [--overwrite] [--delete-legacy]` | Copy legacy `.pi/prompt-stacks` files into `.pi/forge/prompt-stacks` |
 | `/preset ui [stop\|restart]` | Open, stop, or restart the web editor |
 
+### Managing agent profiles
+
+| Command | What it does |
+|---------|-------------|
+| `/profile list` | Show project profiles and resolution diagnostics |
+| `/profile use <id>` | Preflight and apply a profile once |
+| `/profile save <id> [--overwrite]` | Capture the current model, thinking level, and prompt stack |
+| `/profile status` | Show current runtime, last-applied provenance, and drift |
+| `/profile preview <id>` | Preview resolved effects and effective tools without applying |
+| `/profile validate [id]` | Validate one profile, or all profiles when omitted |
+| `/profile reload` | Reload profile files without applying them |
+| `/profile forget` | Forget last-applied provenance without changing runtime state |
+
+### Experimental foreground subagent
+
+| Command | What it does |
+|---------|-------------|
+| `/forge-agent backends` | Show the available experimental backend and its capabilities |
+| `/forge-agent plan <profile> <task>` | Prepare, validate, display, and discard an exact plan without provider transport |
+| `/forge-agent run <profile> <task>` | Review the exact plan and run one foreground read-only text task after approval |
+
+The model-callable tools are `forge_subagent_profiles` for local metadata discovery and `forge_subagent` for execution. Discovery needs no approval and performs no provider request or subagent prompt preparation. Invocation requires the current main-agent tool policy to permit it; execution then requires either an interactive approval UI or the explicit trusted-project unattended option described above.
+
 ### Import & debug
 
 | Command | What it does |
@@ -422,7 +514,7 @@ The default Pi mirror uses a few extra slot options:
 
 ### Tool and skill policy
 
-Prompt stacks can constrain tools and skills with stack-level `allow` or `deny` lists. Patterns are exact by default and support `*` wildcards.
+Prompt stacks can constrain active tools and filter model-visible skills with stack-level `allow` or `deny` lists. Patterns are exact by default and support `*` wildcards.
 
 ```json
 {
@@ -435,11 +527,11 @@ Prompt stacks can constrain tools and skills with stack-level `allow` or `deny`
 }
 ```
 
-Use `allow` when only matching tools or skills should remain active. Use `deny` when everything except matching tools or skills should remain active. A single resource policy cannot contain both non-empty lists; mixed `allow` and `deny` entries are validation errors.
+For tools, use `allow` when only matching active tools should remain and `deny` when matching active tools should be removed. For skills, the same patterns control which skills remain visible in pi-forge's rendered `skills` slots. A single resource policy cannot contain both non-empty lists; mixed `allow` and `deny` entries are validation errors.
 
-Tool policy is enforced through Pi's active tool list while the stack is active. pi-forge remembers the previous active tools and restores them when prompt stacks are disabled or switched to an unrestricted stack.
+Tool policy is enforced through Pi's active tool list while the stack is active. On startup and reload, pi-forge waits for other extensions to finish their `session_start` tool configuration before capturing the baseline and applying the stack policy. It reasserts the policy before user input and turns, and a tool-call guard blocks disallowed model tool execution even if another extension later calls `setActiveTools()`. External tool additions are preserved in the restorable baseline, which is restored when prompt stacks are disabled or switched to an unrestricted stack.
 
-Skill policy filters skills rendered by pi-forge's `skills` slot. If a stack uses `mode: "append"` or `"prepend"`, Pi's base prompt may already contain unfiltered skills; use `mode: "replace"` when skill visibility must be controlled.
+Skill policy filters skills rendered by pi-forge's `skills` slot. It does not disable explicit skill invocation and is not a capability or security boundary. If a stack uses `mode: "append"` or `"prepend"`, Pi's base prompt may already contain unfiltered skills; use `mode: "replace"` when model-visible skill listings must be controlled.
 
 ### Regex transforms
 
@@ -509,20 +601,46 @@ SillyTavern imports convert deterministic prompt-only `{{match}}` / `$0` full-ma
 ## Package setup for development
 
 ```bash
-git clone <repo>
+git clone https://github.com/MacroSony/pi-forge.git
 cd pi-forge
 npm install
 npm run build
-# .pi/settings.json already points at the package root
+# .pi/settings.json loads the package's built dist/index.js
 pi    # start Pi, trust the project, /reload if needed
 ```
 
+The npm package intentionally omits physical `src/` files and loads compiled `dist/` output at runtime. To inspect or modify pi-forge itself, clone or fork the repository instead of editing `node_modules` or generated `dist/` files. A clone preserves your changes in Git and includes the development dependencies, tests, and source-to-dist consistency checks.
+
+For release-like local testing, register the cloned package directory. Its package manifest loads the tracked `dist/index.js`:
+
+```json
+{
+  "packages": ["../pi-forge"]
+}
+```
+
+For live source development, remove that pi-forge package entry and load the TypeScript extension directly from `.pi/settings.json`:
+
+```json
+{
+  "extensions": ["../pi-forge/src/index.ts"]
+}
+```
+
+You can also run `pi -e ../pi-forge/src/index.ts` for a one-off source-level smoke test. Do not load the package and source entry simultaneously or pi-forge will initialize twice. Browser-client source changes additionally require `npm run build:client` because the local editor serves its generated browser bundle.
+
 Run tests:
 
 ```bash
 npm test
 ```
 
+Run the real-browser editor smoke test (set `CHROME_PATH` if Chrome is not in a standard location):
+
+```bash
+npm run test:browser
+```
+
 Typecheck:
 
 ```bash
@@ -535,6 +653,14 @@ Build package output:
 npm run build
 ```
 
+Run the full repository verification, including a clean temporary build that checks tracked `dist/` byte-for-byte against `src/`:
+
+```bash
+npm run verify
+```
+
+The same verification runs in CI. When source changes affect generated output, run `npm run build` and commit the matching `dist/` changes with the source changes.
+
 ## License
 
 MIT