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

package/README.zh-CN.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** 让你自定义 Pi 的思考方式和行为。它提供 prompt stack（提示栈）：这些 JSON 文件可以替换、追加到或插入到 Pi 的默认系统提示词之前，并控制 AI 的性格、可见工具、对话历史布局、模板变量和 prompt 转换。
+**pi-forge** 让你自定义 Pi 的思考方式和行为。它提供用于 prompt/工具策略的 prompt stack（提示栈），也提供可一次性应用模型、思考等级和提示栈的 agent profile（agent 配置预设）。
 
 可以把它理解为 AI agent 的角色卡。
 
@@ -12,6 +12,7 @@
 
 - **赋予 Pi 个性** — 把它变成创意写手、角色扮演搭档、严格的代码审查员，或任何你想要的风格。
 - **一键切换模式** — 在"写代码"、"写小说"、"做翻译"之间用一条命令切换。
+- **保存完整 agent 预设** — 捕获当前模型、思考等级和提示栈，以后一条命令一起应用。
 - **控制 AI 看到什么** — 选择每个 prompt 中出现哪些工具、技能和项目上下文。
 - **按栈限制工具和技能** — 为专注模式启用工具策略，并过滤技能可见性。
 - **使用模板变量** — 定义 `{{char}}` / `{{user}}` 这样的静态值，并在 prompt 文本里使用 ST 风格的轮次/会话变量宏。
@@ -24,9 +25,13 @@
 ### 安装
 
 ```bash
-pi install npm:@zihanw/pi-forge
+pi install npm:@zihanw/pi-forge@0.4.0-beta.1
 ```
 
+此 beta 会发布到 npm 的 `next` channel，不会替换稳定版 `latest`。它要求 Node.js 22.19 或更高版本，并且必须使用 Pi 0.80.10 所采用的精确 `@earendil-works/pi-*` 0.80.10 package 版本。
+
+> **Pi 版本兼容性：** Pi 在 0.80.x 系列内部修改了 session 认证/runtime 的接线方式。此 beta 只以 0.80.10 为目标；不声明兼容 0.80.6–0.80.9，也不声明兼容尚未验证的后续 0.80.x 版本。安装或重新 build pi-forge 后请重启 Pi，确保 extension 与 host SDK 使用同一套接口。如果主 agent 可以正常使用 provider，但 subagent preparation 报告 `No API key found`，请先检查是否仍在运行旧的 pi-forge build，不要直接执行 `/login`：使用 0.80.10 之前 session API 的 build 会在 preparation 时丢失主 session 的认证信息，重新登录无法修复这个版本不匹配。
+
 ### 第一个 prompt stack
 
 从 [examples/default-prompt-stack.json](examples/default-prompt-stack.json) 创建 `.pi/forge/prompt-stacks/default.json`。
@@ -50,11 +55,11 @@ $EDITOR .pi/forge/prompt-stacks/default.json
 /preset ui
 ```
 
-拖拽、新建、编辑、校验、查看完整预览和捕获的 payload、用 tabs 管理变量/context/regex 规则、切换深色模式、通过原始 stack JSON 修复高级字段、导入、导出、fork、删除栈 —— 全在浏览器里完成。新栈会从默认 Pi prompt mirror 布局开始。Stack metadata 可以折叠，方便把当前编辑区留在屏幕内。Policy tab 会显示已注册工具和已加载 skills，并提供已选 pattern chips 和过滤输入，方便用精确名称编写 allow/deny 规则，同时保留通配符写法。
+拖拽、新建、编辑、校验、查看完整预览和捕获的 payload、用 tabs 管理变量/context/regex 规则、切换深色模式、通过原始 stack JSON 修复高级字段、导入、导出、fork、删除栈 —— 全在浏览器里完成。新栈会从默认 Pi prompt mirror 布局开始。已有 stack ID 不可在保存时修改；需要新 ID 时请使用 Fork，避免破坏 profile 引用或当前选择。Stack metadata 可以折叠，方便把当前编辑区留在屏幕内。Policy tab 会显示已注册工具和已加载 skills，并提供已选 pattern chips 和过滤输入，方便用精确名称编写 allow/deny 规则，同时保留通配符写法。
 
 导入支持原生 pi-forge stack JSON，也支持 SillyTavern 预设 JSON。SillyTavern 预设会自动转换成 prompt stack；如果一个预设里有多个 `character_id` 配置，编辑器会询问要使用哪一个。
 
-编辑器默认运行在一个可用的 `127.0.0.1` 端口，并带有会话 token，所以多个 Pi 实例可以同时打开各自的编辑器。如果 Pi 在 session navigation 或新会话后重新初始化扩展，同一项目中的 `/preset ui` 会复用已有编辑器 URL，不会遗留旧 server 后再开一个新端口。写入需要项目被信任，且只会写入 prompt-stack 存储目录。新建的栈会写入 `.pi/forge/prompt-stacks`；旧的 `.pi/prompt-stacks` 栈仍然可读取和编辑。保存、导入、fork、删除成功后会重新加载到当前 Pi 会话。需要时可以用 `/preset ui restart` 或 `/preset ui stop`。
+编辑器默认运行在一个可用的 `127.0.0.1` 端口，并带有会话 token，所以多个 Pi 实例可以同时打开各自的编辑器。如果 Pi 在 session navigation 或新会话后重新初始化扩展，同一项目中的 `/preset ui` 会复用已有编辑器 URL，不会遗留旧 server 后再开一个新端口；resources 和 preview 在生命周期刷新后仍可使用。写入需要项目被信任，且只会写入 prompt-stack 存储目录。新建的栈会写入 `.pi/forge/prompt-stacks`；旧的 `.pi/prompt-stacks` 栈仍然可读取和编辑。保存、导入、fork、删除成功后会重新加载到当前 Pi 会话。需要时可以用 `/preset ui restart` 或 `/preset ui stop`。
 
 要把旧栈复制到新位置，执行 `/preset migrate-stacks`。加 `--dry-run` 可先预览，加 `--overwrite` 可覆盖目标文件，加 `--delete-legacy` 会在复制成功后删除旧文件。
 
@@ -68,6 +73,70 @@ $EDITOR .pi/forge/prompt-stacks/default.json
 }
 ```
 
+### Agent profile
+
+Agent profile 是保存在 `.pi/forge/agent-profiles` 下的项目级 JSON 文件。先正常配置 Pi，然后捕获当前模型、思考等级和 prompt stack，就能快速创建：
+
+```text
+/profile save reviewer
+/profile use reviewer
+```
+
+Profile 只应用一次，不会持续接管 Pi 的模型或思考等级；之后的手动修改会一直保留，直到再次执行 `/profile use reviewer`。被选中的 prompt stack 仍会在激活期间持续执行严格工具策略。
+
+也可以直接编写 profile：
+
+```json
+{
+  "schemaVersion": 1,
+  "type": "pi-forge.agent-profile",
+  "id": "reviewer",
+  "name": "Reviewer",
+  "description": "只审查代码，不做修改。",
+  "autoActivate": true,
+  "model": {
+    "provider": "provider-id",
+    "id": "model-id"
+  },
+  "thinkingLevel": "high",
+  "promptStack": "reviewer"
+}
+```
+
+`autoActivate: true` 会在 Pi 启动全新 session 时一次性应用整个 profile。最多只能有一个 profile 请求自动应用。自动应用的 profile 优先于独立 prompt stack 的自动加载，即使它的 `promptStack` 为 `null` 也不会回退；如果没有 profile 请求自动应用，则继续使用现有的 `default.json`/`autoActivate` stack 规则。已恢复的 session branch 选择优先于这两种自动加载机制。
+
+`promptStack` 可以为 `null`。Profile v1 不保存工具名或 skill 列表；引用的 prompt stack 是工具策略和模型可见 skill 过滤的唯一来源。校验会拒绝不支持的字段，避免悄悄保留无效的生成参数或 runner 配置。
+
+`/profile preview <id>` 会解析模型、认证、思考等级支持、prompt stack 和最终工具集，但不会改变运行时。`/profile status` 显示上次应用的 profile 和当前 drift；profile provenance 会跟随 session branch 恢复用于状态显示，但 reload、resume、tree navigation 或 compaction 绝不会自动重新应用 profile。全新 session 的自动应用仍然是一次性的，因此之后的手动修改会被保留。
+
+### 实验性前台 subagent
+
+0.4 beta 可以把已有 profile 作为独立、干净、一次性的 Pi 子进程运行。无数据外发的 `forge_subagent_profiles` 工具让主 agent 查看当前已加载 profile 的 ID、名称、描述、声明的模型/思考等级/stack、当前解析状态和审批模式。用户没有指定 profile 时，主 agent 应先调用该工具，再调用 `forge_subagent`。限制严格的主 agent prompt stack 必须同时允许这两个工具名。用户也可以继续使用同一执行路径的命令：
+
+```text
+/forge-agent backends
+/forge-agent plan reviewer 检查这个 API 设计是否正确。
+/forge-agent run reviewer 检查这个 API 设计是否正确。
+```
+
+`plan` 会解析 profile 和 stack、编译实际将发送给 provider 的 prompt、校验不可变执行计划，然后丢弃它，不会联系 provider。`/forge-agent run` 和默认配置下的 `forge_subagent` 会先准备完全相同的精确计划，再显示审批界面。默认界面显示 agent 任务、profile/stack、provider、模型、思考等级、最终工具、工作目录、安全边界、payload 大小和执行 fingerprint。选择 **View full prompt** 可以在批准前查看完整 system prompt 和按顺序排列的 provider-bound messages；在查看器中的编辑不会生效。
+
+如果要明确允许父 agent 无需逐次审批即可调用 `forge_subagent`，可以在受信任项目的 `.pi/forge/config.json` 中设置：
+
+```json
+{
+  "subagents": {
+    "allowAgentInvocationWithoutApproval": true
+  }
+}
+```
+
+此选项只影响模型可调用的 `forge_subagent` 工具；`/forge-agent run` 仍然需要交互审批。精确 preflight 和不可变计划校验仍会执行，tool result 也会记录 `trusted-project-config` 授权来源，但 provider transport 会在不向人类显示 prompt 的情况下开始。Profile discovery 会报告当前审批模式。未受信任项目会忽略该设置，格式错误的值会 fail closed。请把项目 config 当作授权文件：除非允许所有能调用 `forge_subagent` 的父 agent 无需再次询问就把编译后的 prompt 和可读文件内容发送给指定 provider，否则不要启用或提交此选项。
+
+子 agent 从干净对话开始，不会自动继承主 agent 历史。它在前台运行，并使用 profile 指定的精确模型、思考等级和 prompt stack。候选工具只有 `read`、`grep`、`find` 和 `ls`，还会继续受到 stack 工具策略限制；不会加载 write/edit/shell 工具、skills、prompt templates、context files 或第三方 extensions。最终工具结果包含有界的模型可见报告和可展开的人类可见执行详情。保留的 transcript 会限制每个字符串的大小、删去类似 base64 的文本，并只保留 512 KiB 的滚动尾部，以便保留最终报告而不让 TUI 持有无界工具历史。内联图片数据会留在 child 内供所选视觉模型使用，但专用 report channel 会在任何内容进入主 session 前，把二进制 payload 替换成 MIME type 和编码体积元数据。
+
+重要：首个 backend 是 **shared-user**，不是操作系统沙箱。只读是模型工具策略；子进程仍然拥有启动它的用户权限，因此可以读取该用户可读的绝对路径，把内容发送给所选 provider，并把文本保留在父级 tool-result details 中。Host timeout 和取消仅为 best effort。`/tree` 会从当前对话分支移除调用和结果，但被放弃的 entry 仍可能留在 Pi 的磁盘 session JSONL 中；要删除敏感的保留文本，需要删除相应 session 数据。`/tree` 也不能撤销 provider 请求、计费或外部副作用。默认工具集刻意不提供文件系统写入路径；bubblewrap 类沙箱和 staged write mode 留待后续实现。
+
 ## 使用场景
 
 ### 🎭 角色扮演 & 创意写作
@@ -154,7 +223,7 @@ pi-forge 会把预设转换为 prompt stack，并生成迁移报告，标明哪
 /payload next save=.pi/forge/payloads/last.json
 ```
 
-或者打开 `/preset ui`，点击 **Arm payload**，发送下一条 Pi prompt，然后在浏览器里查看脱敏后的 provider payload。
+或者打开 `/preset ui`，点击 **Arm payload**，发送下一条 Pi prompt，然后在浏览器里查看脱敏后的 provider payload。凭据形式的 token 字段仍会隐藏，而 `max_tokens`、`input_tokens`、`output_tokens` 等正常限制和计数字段会保留显示。
 
 或者不发送只预览编译结果：
 
@@ -218,6 +287,29 @@ pi-forge 会把预设转换为 prompt stack，并生成迁移报告，标明哪
 | `/preset migrate-stacks [--dry-run] [--overwrite] [--delete-legacy]` | 将旧 `.pi/prompt-stacks` 文件复制到 `.pi/forge/prompt-stacks` |
 | `/preset ui [stop\|restart]` | 打开、停止或重启 Web 编辑器 |
 
+### 管理 agent profile
+
+| 命令 | 作用 |
+|------|------|
+| `/profile list` | 显示项目 profile 和解析诊断 |
+| `/profile use <id>` | 预检并一次性应用 profile |
+| `/profile save <id> [--overwrite]` | 捕获当前模型、思考等级和 prompt stack |
+| `/profile status` | 显示当前运行时、上次应用来源和 drift |
+| `/profile preview <id>` | 不应用，只预览解析结果和最终工具 |
+| `/profile validate [id]` | 校验一个 profile；省略 id 时校验全部 |
+| `/profile reload` | 从磁盘重新加载 profile，但不应用 |
+| `/profile forget` | 忘记上次应用来源，不改变运行时 |
+
+### 实验性前台 subagent
+
+| 命令 | 作用 |
+|------|------|
+| `/forge-agent backends` | 显示实验性 backend 及其能力 |
+| `/forge-agent plan <profile> <task>` | 不进行 provider transport，准备、校验、显示并丢弃精确执行计划 |
+| `/forge-agent run <profile> <task>` | 审查精确计划并在批准后运行一个前台只读文本任务 |
+
+模型可调用的工具包括用于本地元数据发现的 `forge_subagent_profiles`，以及用于执行的 `forge_subagent`。发现工具不需要审批，也不会请求 provider 或准备 subagent prompt。当前主 agent 工具策略必须允许执行工具；之后还必须存在交互式审批 UI，或者启用上文明确说明的受信任项目免审批选项，subagent 才可运行。
+
 ### 导入 & 调试
 
 | 命令 | 作用 |
@@ -405,7 +497,7 @@ API 包含 `cwd`、`forgeDir`、`extensionPath`、`helpers`、`registerMacro`、
 
 ### 工具和技能策略
 
-Prompt stack 可以用栈级 `allow` 或 `deny` 列表限制工具和技能。模式默认精确匹配，也支持 `*` 通配符。
+Prompt stack 可以用栈级 `allow` 或 `deny` 列表限制 active tools，并过滤模型可见的技能。模式默认精确匹配，也支持 `*` 通配符。
 
 ```json
 {
@@ -418,11 +510,11 @@ Prompt stack 可以用栈级 `allow` 或 `deny` 列表限制工具和技能。
 }
 ```
 
-使用 `allow` 时，只有匹配的工具或技能保持启用。使用 `deny` 时，除匹配项以外的工具或技能保持启用。同一个资源策略不能同时包含非空 `allow` 和 `deny` 列表；混用会产生 validation error。
+对于工具，`allow` 只保留匹配的 active tools，`deny` 移除匹配的 active tools。对于技能，同样的 pattern 控制哪些技能保留在 pi-forge 渲染的 `skills` slot 中。同一个资源策略不能同时包含非空 `allow` 和 `deny` 列表；混用会产生 validation error。
 
-工具策略会在栈激活期间通过 Pi 的 active tool list 强制执行。pi-forge 会记住之前的 active tools，并在禁用 prompt stack 或切换到没有工具策略的 stack 时恢复。
+工具策略会在栈激活期间通过 Pi 的 active tool list 强制执行。启动和 reload 时，pi-forge 会等其它扩展完成 `session_start` 工具配置，再记录 baseline 并应用 stack 策略；之后还会在用户输入和 turn 开始前重新应用策略。即使其它扩展稍后调用 `setActiveTools()`，tool-call guard 也会阻止模型执行策略之外的工具。外部扩展新增的工具会保留在可恢复 baseline 中，并在禁用 prompt stack 或切换到没有工具策略的 stack 时恢复。
 
-技能策略会过滤 pi-forge `skills` slot 渲染出的技能。如果 stack 使用 `mode: "append"` 或 `"prepend"`，Pi base prompt 里可能已经包含未过滤的技能；需要控制技能可见性时请使用 `mode: "replace"`。
+技能策略会过滤 pi-forge `skills` slot 渲染出的技能。它不会禁用显式技能调用，也不是 capability 或安全边界。如果 stack 使用 `mode: "append"` 或 `"prepend"`，Pi base prompt 里可能已经包含未过滤的技能；需要控制模型可见的技能列表时请使用 `mode: "replace"`。
 
 ### Regex 转换
 
@@ -492,20 +584,46 @@ SillyTavern 导入会把确定性的 prompt-only `{{match}}` / `$0` full-match r
 ## 开发环境搭建
 
 ```bash
-git clone <repo>
+git clone https://github.com/MacroSony/pi-forge.git
 cd pi-forge
 npm install
 npm run build
-# .pi/settings.json 已指向包根目录
+# .pi/settings.json 会加载 package 构建后的 dist/index.js
 pi    # 启动 Pi，信任项目，必要时 /reload
 ```
 
+npm package 会有意省略实际的 `src/` 文件，并在运行时加载编译后的 `dist/`。需要查看或修改 pi-forge 本身时，请 clone 或 fork 仓库，不要直接修改 `node_modules` 或生成的 `dist/`。仓库 clone 可以用 Git 保留改动，并包含开发依赖、测试以及 source-to-dist 一致性检查。
+
+进行接近 release 的本地测试时，在 `.pi/settings.json` 中注册 clone 后的 package 目录；package manifest 会加载已跟踪的 `dist/index.js`：
+
+```json
+{
+  "packages": ["../pi-forge"]
+}
+```
+
+进行实时源码开发时，请移除上面的 pi-forge package entry，再通过 `.pi/settings.json` 直接加载 TypeScript extension：
+
+```json
+{
+  "extensions": ["../pi-forge/src/index.ts"]
+}
+```
+
+也可以用 `pi -e ../pi-forge/src/index.ts` 做一次性的源码级 smoke test。不要同时加载 package 和 source entry，否则 pi-forge 会初始化两次。修改 browser client 源码后还需要执行 `npm run build:client`，因为本地编辑器提供的是生成后的 browser bundle。
+
 运行测试：
 
 ```bash
 npm test
 ```
 
+运行真实浏览器中的编辑器 smoke test（如果 Chrome 不在标准路径，请设置 `CHROME_PATH`）：
+
+```bash
+npm run test:browser
+```
+
 类型检查：
 
 ```bash
@@ -518,6 +636,14 @@ npm run typecheck
 npm run build
 ```
 
+运行完整仓库验证，包括在临时目录中执行干净构建，并逐字节检查已跟踪的 `dist/` 是否与 `src/` 一致：
+
+```bash
+npm run verify
+```
+
+CI 会运行同一套验证。源代码变更影响生成输出时，请运行 `npm run build`，并将对应的 `dist/` 变更与源代码一起提交。
+
 ## License
 
 MIT

package/SUBAGENT_ADAPTER_CONTRACT.md

@@ -0,0 +1,199 @@
+# Subagent Adapter Contract
+
+Status: exported pure contract, host-preparation utilities, optional backend registry, retained `pi-sdk-isolated` compatibility adapter, and a default-approval `pi-subprocess-readonly` foreground path for the 0.4 beta. This is a narrow one-shot delegation boundary, not a background orchestration runner or an OS sandbox.
+
+## Public Surface
+
+New integrations should import this experimental 0.4 surface from `@zihanw/pi-forge/subagent`. The package root retains the same exports through the 0.4 prereleases for compatibility. Stability classifications and compatibility-path policy are recorded in [`PUBLIC_API.md`](PUBLIC_API.md).
+
+The package root exports:
+
+- `AgentRequest`, `AgentProfileSnapshot`, `BackendPreflightResult`, `AgentExecutionPlan`, and `AgentResponse`.
+- Granular access, limit, tool, media, context, artifact, trace, usage, and diagnostic types.
+- Host resolution through `resolveSubagentHostProfile()`.
+- Tool negotiation through `negotiateSubagentTools()`.
+- Deterministic context preparation through `budgetSubagentContext()`, `renderSubagentSelectedContext()`, and `prepareSubagentInitialMessages()`.
+- Protected Pi-message helpers used by the SDK spike.
+- Plan construction through `createAgentExecutionPlan()`.
+- Pure request, snapshot, preflight, plan, response, artifact, and trace validators.
+- Canonical `sha256:v1` profile, stack, and execution fingerprints.
+- Optional backend registration, validated dispatch, cancellation/timeout arbitration, response normalization, and authorization-scoped trace routing through `SubagentBackendRegistry`.
+- Experimental `PiSdkIsolatedBackend` compatibility adapter and the default `PiSubprocessBackend`, including their descriptors/IDs, report types, and host preparation through `prepareSubagentHostPlan()`.
+
+The existing `agentProfileFingerprint()` remains unchanged. It is still the legacy JSON provenance value used for branch drift. New portable fingerprints use separately named functions and semantics.
+
+## Required Flow
+
+```text
+AgentRequest
+    -> resolveSubagentHostProfile
+    -> SubagentBackendRegistry discovery/preflight
+    -> registry-mediated exact or backend-assisted preparation
+    -> createAgentExecutionPlan
+    -> registry-validated backend execution
+    -> validateAgentResponse
+```
+
+No stage may substitute parent-runtime model objects, credentials, source file paths, or raw session history for the portable artifacts.
+
+### 1. Request validation
+
+`validateAgentRequest()` checks:
+
+- Schema, IDs, task text/media references, and media digests.
+- Explicit selected-context byte budgets and provenance.
+- Delegation depth.
+- Access-level/workspace/working-directory/network/process combinations.
+- Required versus best-effort hard limits.
+- Result-projection bounds and remote-egress consent.
+
+Media references are opaque host resources with content digests. The contract does not place local absolute paths or media bytes in the portable request.
+
+### 2. Host resolution
+
+`resolveSubagentHostProfile()` performs only backend-independent work:
+
+- Validates the loaded profile and exact prompt-stack reference.
+- Accepts null, default/replace, append, and prepend stack modes.
+- Scans prompt-stack items for custom macro and slot dependencies.
+- Requires those registrations to be loaded before final resolution.
+- Produces a path-free immutable profile snapshot and portable fingerprints.
+
+It deliberately does not inspect a model registry, authentication, backend tools, mounts, or limits. Parent `/profile use` resolution remains separate.
+
+Unknown macro commands and custom slots are treated as missing subagent dependencies. Static stack variables and built-in macros/slots are excluded. Custom registrations without a `source` still resolve but produce a warning because their dependency identity is anonymous.
+
+### 3. Backend preflight
+
+An accepted `BackendPreflightResult` must identify the exact model/thinking level, dynamic tool catalog, granular capabilities, effective access receipt, and accepted limit receipt.
+
+`validateBackendPreflight()` enforces:
+
+- Exact profile model and thinking-level agreement.
+- Explicit consent for remote provider transport.
+- Requested media MIME support.
+- No missing, extra, upgraded, or mode-mismatched mounts.
+- Working-directory containment through backend mount IDs.
+- Read/write, symlink, process, and denied-network enforcement claims.
+- Every required limit uses `backend-hard` enforcement.
+- Best-effort limits are reported honestly, such as Pi SDK host-abort timeouts.
+- Rejected preflight results contain at least one error diagnostic.
+
+Prompt tool filtering is not accepted as an access receipt.
+
+### 4. Tool negotiation
+
+Each backend tool declares a stable backend ID, policy-facing name, and effects:
+
+- `filesystem-read`
+- `filesystem-write`
+- `process`
+- `network`
+
+`negotiateSubagentTools()` applies prompt-stack policy to names, then removes tools whose declared effects exceed request access. Effect-free tools may remain under filesystem access `none`; network and process are independently controlled. Unmatched allow patterns remain warnings.
+
+Adapters must classify tool effects conservatively. A tool with undeclared effects invalidates the backend's enforcement claim even if name filtering succeeds.
+
+### 5. Context and exact preparation
+
+`budgetSubagentContext()` measures the exact UTF-8 bytes of the rendered selected-context envelope. Required items are retained first. Optional items are considered newest-to-oldest without partial item truncation, and returned in original order. Required overflow fails preparation.
+
+`prepareSubagentInitialMessages()` creates:
+
+1. One quoted selected-context message when the budget retains context.
+2. Host-prepared prompt-stack messages.
+3. The complete protected task/media message as the final user message.
+
+Prompt-stack messages cannot claim reserved selected-context or delegated-task markers.
+
+Backends such as Pi SDK may expose exact base-prompt runtime inputs only in a pre-provider hook. They may call the host preparer there, but provider transport must remain blocked until `createAgentExecutionPlan()` succeeds. A `partial` prompt-runtime preflight cannot produce an execution plan.
+
+### 6. Plan and fingerprints
+
+`createAgentExecutionPlan()` revalidates the request, snapshot, preflight, deterministic context receipt, tool negotiation, runtime fidelity, and protected final task. It creates the run ID correlation and execution fingerprint before provider transport.
+
+The execution fingerprint covers all serialized plan fields except itself, including compiled system/messages, profile/stack/dependency provenance, the complete preflight receipt and adapter version, exact model/thinking, effective backend tool IDs, access and limit receipts, prompt-runtime fingerprint, context receipt, and result-projection bound.
+
+Canonical serialization sorts object keys, omits undefined object fields, rejects cycles/non-finite numbers/non-JSON values, preserves array order, and normalizes negative zero.
+
+### 7. Response validation
+
+`validateAgentResponse()` enforces the terminal status matrix:
+
+| Status | Required terminal field | Output rule |
+|---|---|---|
+| `completed` | none | absent or `partial: false` |
+| `failed` | structured `error` | absent or `partial: true` |
+| `cancelled` | `reason` | absent or `partial: true` |
+| `timed-out` | `reason`, `enforcedTimeoutMs` | absent or `partial: true` |
+| `limit-reached` | `reachedLimit` | absent or `partial: true` |
+
+It also validates request/run/backend correlation, model and fingerprints, effective backend tool IDs, backend-produced enforcement receipts, duration, token/cost units, artifact namespaces, relative paths, cleanup ownership, and authorized trace handles. Cost requires an ISO 4217 currency code.
+
+### 8. Optional backend registry
+
+`SubagentBackendRegistry` starts empty and never installs a default backend. It:
+
+- Validates backend descriptors and rejects duplicate identities.
+- Binds accepted preflight IDs to the exact backend, request, and profile fingerprint used during discovery.
+- Routes exact-preflight preparation directly to the host preparer and requires backend-assisted adapters to invoke the same host boundary.
+- Binds the exact runtime fingerprint, compiled system/messages, effective tools, and context receipt returned by host preparation; recomputing an execution fingerprint cannot substitute a different plan.
+- Routes dry-plan discard through the owning backend before forgetting the preflight binding.
+- Rejects malformed, tampered, foreign, or unbound execution plans before transport.
+- Arbitrates backend completion, explicit user cancellation, external abort signals, and declared host-abort timeouts through one terminal result.
+- Discards prepared backend state without invoking execution when cancellation wins before backend dispatch.
+- Normalizes thrown provider failures and malformed backend responses into contract-valid failed responses.
+- Replaces backend-reported duration with host-observed duration.
+- Keeps opaque backend trace IDs behind host-generated handles and enforces authorization scope, backend routing, expiry, and explicit forgetting during inspection.
+- Refuses backend unregistration while an execution remains active or is draining after cancellation.
+
+The registry validates receipts but does not manufacture filesystem, process, network, token, turn, or output isolation. Those remain adapter responsibilities.
+
+Access receipts may explicitly declare `executionBoundary: "shared-user"`. This boundary means the subprocess retains the invoking user's operating-system permissions and its effective access is constrained only by the tools exposed to the model. A shared-user receipt cannot claim mount, symlink, process, or network isolation. Omitting the field preserves the legacy `isolated` interpretation.
+
+### 9. Experimental foreground subprocess and approval path
+
+`PiSubprocessBackend` is the extension's deliberately narrow default adapter:
+
+- It resolves the exact profile model through Pi's existing `ModelRegistry`, reuses the parent Pi 0.80.10 `ModelRuntime` so preparation sees the same authentication, and prepares the exact prompt inside an in-process Pi session held behind a provider gate.
+- After approval, it disposes the preparation session and launches a fresh foreground Pi subprocess with the approved model, thinking level, system prompt, messages, and tool IDs. Pi's ordinary text stdout is drained separately from a dedicated newline-delimited report channel.
+- Its bridge preserves the exact prepared messages and rejects tools outside the approved allowlist. Candidate tools are limited to `read`, `grep`, `find`, and `ls`, then intersected with prompt-stack policy.
+- It loads no write/edit/shell tools, skills, prompt templates, context files, themes, or third-party Pi extensions and writes no child session file.
+- It accepts text-only, one-shot, sequential `read-only` requests rooted at the project working directory, with no process tool and optional host-abort timeout. It advertises no artifact retention or contract trace inspection.
+- It records a bounded foreground execution report containing sanitized transcript events, tool calls/results, usage, stderr, status, and execution identity. Inline images remain available to the child model but cross the report boundary only as MIME/encoded-size metadata. Base64-like text is redacted, individual strings are capped, and retained messages form a 512 KiB rolling tail so large tool histories cannot make the parent TUI/session retain unbounded data. Temporary bridge inputs are mode `0600` and removed during cleanup.
+- Retained textual tool results are ordinary parent-session tool details. `/tree` can move the active branch away from them but does not erase abandoned entries from Pi's on-disk session JSONL; callers handling sensitive files must treat session-data deletion as a separate operation.
+
+This backend declares `executionBoundary: "shared-user"`. It does not create allowed-root mount containment, symlink-safe path containment, process isolation, or agent-network isolation. The subprocess retains the invoking user's OS permissions; `read-only` describes the tools exposed to the model, not a security sandbox. Network is therefore honestly recorded as allowed even though no dedicated network or shell tool is exposed.
+
+The model-callable `forge_subagent_profiles` tool reads the already-loaded host profile catalog without preparing a prompt or contacting a provider. It exposes IDs, names, descriptions, declared model/thinking/stack metadata, ready/unavailable resolution diagnostics, and whether parent policy currently exposes the invocation tool. A restrictive parent stack must allow both `forge_subagent_profiles` and `forge_subagent` for discovery followed by delegation.
+
+The model-callable `forge_subagent` tool and `/forge-agent run` use the same registry path. Both prepare an exact immutable plan while provider transport remains closed. `/forge-agent run` always shows a compact approval summary, allows inspection of the complete prompt, and requires interactive approval bound to the execution fingerprint. The tool does the same by default, but a trusted project may set `subagents.allowAgentInvocationWithoutApproval: true` in `.pi/forge/config.json`; this permits non-UI model invocation and records `trusted-project-config` in the result receipt without weakening preflight or plan binding. Missing, malformed, and untrusted-project settings fail closed. The tool returns bounded content to the parent model and expandable execution details to the human. `/forge-agent plan` still prepares and discards without provider transport; `/forge-agent backends` shows capabilities. The older access-none `PiSdkIsolatedBackend` remains exported and tested for compatibility but is not the extension default.
+
+## Adapter-Enforced Responsibilities
+
+The exported validators cannot create isolation. Every adapter remains responsible for:
+
+- Credential and model availability in its own runtime.
+- Backend-side mount materialization and path canonicalization immediately before access.
+- Symlink-race-safe containment.
+- Process and agent-network isolation.
+- Accurate tool effects and stable tool mappings.
+- Required hard timeout, turn, token, and output limits.
+- Cancellation settlement and cleanup.
+- Media transport and remote-egress behavior.
+- Artifact authorization, retention, and cleanup.
+- Trace storage, authorization, redaction, pagination, and expiry.
+- Returning actual enforcement receipts rather than echoing request fields.
+
+An adapter must reject preflight when it cannot enforce a required field. The retained Pi SDK adapter can execute only access `none`; the subprocess adapter accepts shared-user read-only access and network allow. Both use best-effort host abort rather than a backend-hard timeout. Provider transport is always a separate, explicitly approved egress path.
+
+## Deliberately Not Included
+
+- Filesystem writes, process/shell tools, media input, background runs, or general backend selection/configuration in the shipped path.
+- OS-level filesystem, process, or network sandboxing for the shared-user subprocess.
+- Automatic parent-history/context selection; the delegated task is explicit and starts a clean conversation.
+- Session resume, retries, queues, chains, or pipelines.
+- Artifact/trace storage implementations.
+- Automatic provider fallback.
+
+Those belong to later iterations and cannot be inferred from these pure types alone.

package/dist/agent-profile.d.ts

@@ -0,0 +1,71 @@
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import { type Model } from "@earendil-works/pi-ai";
+import type { LoadedPromptStack } from "./types.ts";
+export declare const AGENT_PROFILE_TYPE: "pi-forge.agent-profile";
+export declare const AGENT_PROFILE_THINKING_LEVELS: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+export interface AgentProfileModelReference {
+    provider: string;
+    id: string;
+}
+export interface AgentProfile {
+    schemaVersion: 1;
+    type: typeof AGENT_PROFILE_TYPE;
+    id: string;
+    name?: string;
+    description?: string;
+    autoActivate?: boolean;
+    model: AgentProfileModelReference;
+    thinkingLevel: ThinkingLevel;
+    promptStack: string | null;
+}
+export type AgentProfileDiagnosticLevel = "error" | "warning" | "info";
+export interface AgentProfileDiagnostic {
+    level: AgentProfileDiagnosticLevel;
+    message: string;
+    field?: string;
+}
+export interface LoadedAgentProfile {
+    profile: AgentProfile;
+    filePath: string;
+    diagnostics: AgentProfileDiagnostic[];
+}
+export interface AgentProfileResolutionResources {
+    models: readonly Model<any>[];
+    availableModels?: readonly Model<any>[];
+    promptStacks: readonly LoadedPromptStack[];
+    toolNames?: readonly string[];
+}
+export interface ResolvedAgentProfile {
+    loaded: LoadedAgentProfile;
+    model?: Model<any>;
+    promptStack?: LoadedPromptStack;
+    effectiveThinkingLevel: ThinkingLevel;
+    diagnostics: AgentProfileDiagnostic[];
+}
+export interface AgentProfileRuntimeSnapshot {
+    model: AgentProfileModelReference;
+    thinkingLevel: ThinkingLevel;
+    promptStack: string | null;
+}
+export interface AgentProfileProvenance {
+    profileId: string;
+    sourcePath: string;
+    sourceFingerprint: string;
+    appliedAt: string;
+    snapshot: AgentProfileRuntimeSnapshot;
+}
+export { agentProfilePath, agentProfilesDir } from "./storage.ts";
+export declare function isValidAgentProfileId(id: string): boolean;
+export declare function loadAgentProfiles(cwd: string): LoadedAgentProfile[];
+export declare function chooseAutoActivateAgentProfile(profiles: readonly LoadedAgentProfile[]): LoadedAgentProfile | undefined;
+export declare function hasAutoActivateAgentProfile(profiles: readonly LoadedAgentProfile[]): boolean;
+export declare function loadAgentProfileFile(filePath: string): LoadedAgentProfile;
+export declare function validateAgentProfile(profile: AgentProfile): AgentProfileDiagnostic[];
+export declare function resolveAgentProfile(loaded: LoadedAgentProfile, resources: AgentProfileResolutionResources): ResolvedAgentProfile;
+export declare function isUsableAgentProfile(loaded: LoadedAgentProfile): boolean;
+export declare function isResolvedAgentProfileUsable(resolved: ResolvedAgentProfile): boolean;
+export declare function hasAgentProfileErrors(diagnostics: readonly AgentProfileDiagnostic[]): boolean;
+export declare function renderAgentProfileDiagnostics(diagnostics: readonly AgentProfileDiagnostic[]): string;
+export declare function agentProfileFingerprint(profile: AgentProfile): string;
+export declare function isAgentProfileProvenance(value: unknown): value is AgentProfileProvenance;
+//# sourceMappingURL=agent-profile.d.ts.map

package/dist/agent-profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-profile.d.ts","sourceRoot":"","sources":["../src/agent-profile.ts"],"names":[],"mappings":"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"}