@zihanw/pi-forge 0.4.1 → 0.5.0

package/docs/zh-CN/README.md

@@ -11,12 +11,12 @@
 ## 指南
 
 - [Web 编辑器](guides/web-editor.md)
+- [迁移到 0.5](guides/migrating-to-0.5.md)
 - [实验性前台 delegation](guides/delegation.md)：启用前请先阅读安全边界。
 - [Prompt stack 使用场景（英文）](../guides/use-cases.md)
 
-SillyTavern 导入、自定义 macros/slots 和调试的完整说明目前以英文版为准：
+自定义 macros/slots 和调试的完整说明目前以英文版为准：
 
-- [SillyTavern import](../guides/sillytavern-import.md)
 - [Custom macros and slots](../guides/custom-macros-and-slots.md)
 - [Prompt and payload debugging](../guides/debugging.md)
 
@@ -27,7 +27,7 @@ SillyTavern 导入、自定义 macros/slots 和调试的完整说明目前以英
 - [Macros 与 slots（英文）](../reference/macros-and-slots.md)
 - [配置（英文）](../reference/configuration.md)
 - [Public API（英文）](../reference/public-api.md)
-- [实验性 subagent adapter（英文）](../reference/subagent-adapter.md)
+- [实验性 subagent host port（英文）](../reference/subagent-host-port.md)
 
 ## 开发与设计
 

package/docs/zh-CN/concepts/agent-profiles.md

@@ -43,4 +43,4 @@ Agent profile 是项目级或用户全局、带 schema version 的预设，只
 
 `/profile status` 会把 profile 源定义变化和当前模型/思考等级/stack drift 分开显示。Provenance 只用于 branch 状态报告；reload、resume、tree navigation 和 compaction 不会重新应用 profile。
 
-普通 profile 默认不能委派。Delegation 授权跟随 profile scope：可信项目 `.pi/forge/config.json` 的 `subagents.profiles.<id>` 只授权 `project:<id>`，用户全局 `~/.pi/forge/config.json` 的 `subagents.profiles.<id>` 只授权 `global:<id>`；同 ID 的全局和项目 profile 永不互相继承授权。删除 profile 会清除同 scope 的授权，防止以后同 ID profile 继承权限。启用前见[前台 delegation](../guides/delegation.md)。
+普通 profile 默认不能委派。Delegation 授权由可选包 `@zihanw/pi-forge-subagents` 通过专用文件持有：可信项目 `.pi/forge/subagents.json` 只授权 `project:<id>`，用户全局 `~/.pi/forge/subagents.json` 只授权 `global:<id>`，并可按 profile 覆盖 backend/timeout；同 ID 的全局和项目 profile 永不互相继承授权。主包不读取任何 subagent 配置，删除 profile 也不会改动 `subagents.json`。启用前见[前台 delegation](../guides/delegation.md)。

package/docs/zh-CN/concepts/prompt-stacks.md

@@ -11,7 +11,7 @@ Prompt stack 是一份有序、声明式的 prompt 与策略描述，由固定 *
 1. 按 JSON 顺序排列启用的 block/slot。
 2. 构建 system 内容，并使用 `replace`、`append` 或 `prepend` 模式。
 3. 在可移动 `chat-history` 周围插入 user/assistant 消息。
-4. 展开内置、变量和可信自定义宏。
+4. 用 forge-v1 编译 `runtime.*` / `parameters.*` / `extensions.*` 模板。
 5. 对 Pi 执行工具策略，并过滤 pi-forge 渲染的 skills。
 6. 应用 history/compiled outgoing regex。
 7. 可选地在消息完成后应用破坏性的 finalize regex。
@@ -21,7 +21,7 @@ Prompt stack 是一份有序、声明式的 prompt 与策略描述，由固定 *
 1. 长期 system 规则。
 2. 工具和项目上下文。
 3. `includeLastUserMessage: false` 的 `chat-history`。
-4. 包含 `{{lastUserMessage}}` 的最终 user block。
+4. 包含 `{{ runtime.lastUserMessage }}` 的最终 user block。
 
 这样既保留旧上下文，又只在最后明确出现一次当前请求。History 还可以过滤 summary/role、去掉旧工具消息、移除 assistant thinking，并限制消息数或字符数。
 
@@ -35,8 +35,8 @@ Prompt stack 是一份有序、声明式的 prompt 与策略描述，由固定 *
 - 项目 stack 优先于全局 stack；项目 scope 存在候选时，即使项目候选无效或冲突也会 fail closed，不会回退到全局 stack。
 - 同 ID 项目 stack 会遮蔽全局 stack，包括无效 shadow 或显式 opt-out。
 - `/preset use none` 会记录 session branch 的 opt-out。
-- Active stack 和 session variables 会跟随 Pi session tree branch。
+- Active stack 选择会跟随 Pi session tree branch。
 - 恢复的 branch 状态优先于新 session 自动启用。
 - 自动启用的 agent profile 优先于独立 stack autoload。
 
-完整字段见英文 [stack schema](../../reference/stack-schema.md)，macro/slot 见[参考](../../reference/macros-and-slots.md)。
+完整字段见英文 [stack schema](../../reference/stack-schema.md)（schema v2 使用 `parameters`），模板语法见[参考](../../reference/macros-and-slots.md)。

package/docs/zh-CN/getting-started.md

@@ -64,11 +64,12 @@ Profile 默认保存在 `.pi/forge/agent-profiles/*.json`。`/profile save globa
 |---|---|
 | `.pi/forge/prompt-stacks/` | 项目 prompt stacks |
 | `.pi/forge/agent-profiles/` | 项目 agent profiles |
-| `.pi/forge/config.json` | 项目配置和 `project:<id>` delegation 授权 |
+| `.pi/forge/config.json` | 项目配置（`webEditor.*`） |
 | `.pi/forge/extensions/` | 可信项目 macro/slot 代码 |
 | `~/.pi/forge/prompt-stacks/` | 用户全局 prompt stacks |
 | `~/.pi/forge/agent-profiles/` | 用户全局 agent profiles |
-| `~/.pi/forge/config.json` | 用户默认配置和 `global:<id>` delegation 授权 |
+| `~/.pi/forge/config.json` | 用户默认配置（`webEditor.*`） |
+| `.pi/forge/subagents.json` / `~/.pi/forge/subagents.json` | 由可选包 `@zihanw/pi-forge-subagents` 持有的 delegation 授权配置 |
 | `~/.pi/forge/extensions/` | 可信用户 macro/slot 代码 |
 
 旧的 `.pi/prompt-stacks/*.json` 仍可读取；命令创建的 stack 会写到 `.pi/forge/prompt-stacks`，使用 Web 编辑器的 `global` scope 下拉可创建到用户全局 `~/.pi/forge/prompt-stacks`。安全迁移方式：

package/docs/zh-CN/guides/delegation.md

@@ -4,28 +4,26 @@
 
 > **实验性：** 此 API 和 backend 可能独立于稳定的 prompt stack/profile 功能发生变化。
 
-pi-forge 可以把明确授权的 agent profile 作为独立、干净、一次性的 Pi 进程执行。它在前台运行，并向父对话返回有界报告。
+可选包 `@zihanw/pi-forge-subagents` 可以把明确授权的 agent profile 作为独立、干净、一次性的 Pi 进程执行。它在前台运行，并向父对话返回有界报告。
 
 ## 启用 profile
 
-Profile 默认不能委派。请在可信项目的 `.pi/forge/config.json` 中逐个启用项目 profile，在用户全局 `~/.pi/forge/config.json` 中逐个启用全局 profile；也可以使用 `/preset ui` 的 delegation 卡片：
+Profile 默认不能委派。请在可信项目的 `.pi/forge/subagents.json` 中逐个启用项目 profile，在用户全局 `~/.pi/forge/subagents.json` 中逐个启用全局 profile；`.pi/forge/config.json.subagents` 仅作为只读兼容来源：
 
 ```json
 {
-  "subagents": {
-    "backend": "pi-subprocess-readonly",
-    "timeoutMs": 60000,
-    "profiles": {
-      "reviewer": {
-        "enabled": true,
-        "timeoutMs": 300000
-      }
+  "backend": "pi-subprocess-readonly",
+  "timeoutMs": 60000,
+  "profiles": {
+    "reviewer": {
+      "enabled": true,
+      "timeoutMs": 300000
     }
   }
 }
 ```
 
-授权跟随 profile scope：项目 config 的 `subagents.profiles.<id>` 只授权 `project:<id>`，全局 config 的 `subagents.profiles.<id>` 只授权 `global:<id>`。同 ID 的全局和项目 profile 不会互相继承 enable/backend/timeout。未启用或未列出的 ID 不会被 discovery 返回，即使猜中 ID 也会被拒绝。
+授权跟随 profile scope：项目 `subagents.json` 的 `profiles.<id>` 只授权 `project:<id>`，全局 `subagents.json` 的 `profiles.<id>` 只授权 `global:<id>`。同 ID 的全局和项目 profile 不会互相继承 enable/backend/timeout。未启用或未列出的 ID 不会被 discovery 返回，即使猜中 ID 也会被拒绝。
 
 ## Plan 与运行
 
@@ -55,7 +53,7 @@ Profile 默认不能委派。请在可信项目的 `.pi/forge/config.json` 中
 }
 ```
 
-它只影响 `forge_subagent`；`/forge-agent run` 仍需要交互审批。格式错误或不可信项目会 fail closed。请把此 config 当作授权文件：除非所有可调用父 agent 都可以无需再次询问就把编译 prompt 和可读文件发给 provider，否则不要启用或提交此设置。
+它只影响 `forge_subagent`；`/forge-agent run` 仍需要交互审批。格式错误或不可信项目会 fail closed。请把此 `subagents.json` 当作授权文件：除非所有可调用父 agent 都可以无需再次询问就把编译 prompt 和可读文件发给 provider，否则不要启用或提交此设置。
 
 ## Child 边界
 

package/docs/zh-CN/guides/migrating-to-0.5.md

@@ -0,0 +1,92 @@
+# 迁移到 pi-forge 0.5
+
+[中文文档](../README.md) · [English](../../guides/migrating-to-0.5.md)
+
+0.5.0 是一个破坏性的清理版本。本页是全部变更的迁移说明。
+
+## 被移除的内容
+
+- SillyTavern 导入器（`/preset import-silly`）及其报告、指南、示例和测试。升级前请先用 pi-forge 0.4 转换 SillyTavern preset。
+- 可变 turn/session 变量、变量修改 macro、`pi-forge-variable-state` session 条目和 `variables` slot。
+- 正则的 `display` 与 `both` 效果；保留 `outgoing` 和 `finalize`。
+- 主包中的 subagent 执行功能（移至可选包，见下文 Lane 3/4）。
+
+## 模板语法变更
+
+Prompt 文本现在使用封闭的 `forge-v1` 语法编译。
+
+| 0.4 写法 | 0.5 forge-v1 |
+|---|---|
+| `{{name}}`（静态） | `{{ parameters.name }}` |
+| `{{lastUserMessage}}` | `{{ runtime.lastUserMessage }}` |
+| `{{date}}` / `{{time}}` / `{{cwd}}` | `{{ runtime.date }}` / `{{ runtime.time }}` / `{{ runtime.cwd }}` |
+| `{{tools}}` | `{{ runtime.selectedToolsText }}` |
+| `{{upper::x}}` | `{{ x \| upper }}` |
+| `{{iftools::bash::A::B}}` | `{% if runtime.tool.bash %}A{% else %}B{% endif %}` |
+| 自定义 `{{myMacro}}` | `{{ extensions.myMacro }}` |
+
+未知路径、未知 filter、解析错误、循环和输出超限都是编译错误；失败的块会被省略，而不是把原始模板文本重新注入。
+
+## Schema v2
+
+Schema v2 的 stack 把不可变静态值存入 `parameters`（JSON 兼容），取代旧的纯字符串 `variables` 字段：
+
+```json
+{
+  "schemaVersion": 2,
+  "parameters": { "char": "Konata" }
+}
+```
+
+未标注版本 / v1 的 stack 仍通过旧的 `variables` 读取器加载。
+
+## 运行迁移工具
+
+一个以诊断为先的机械脚本可转换已保存的 stack 文件：
+
+```bash
+node scripts/migrate-stack-v2.mjs .pi/forge/prompt-stacks/default.json --dry-run
+node scripts/migrate-stack-v2.mjs .pi/forge/prompt-stacks/default.json --write
+```
+
+它会把 `variables` 改名为 `parameters`、映射 runtime/parameter 路径并转换简单的 filter 管道。无法机械转换的写法会被报告；只有不存在这类写法时才会写入文件。仍含旧 `variables` 字段的 schema v2 文件不会被改动，仅给出警告。
+
+## Lane 2：带 scope 的全局 profile 与 prompt stack
+
+- 用户全局资源现在位于 `~/.pi/forge/prompt-stacks` 和 `~/.pi/forge/agent-profiles`，与项目存储并存。Profile 和 stack 选择器支持显式 scope：`project:<id>`、`global:<id>`，裸 ID 优先解析项目资源。
+- 同 ID 的项目资源会遮蔽对应的全局资源；全局 stack 不能引用项目资源（反之亦然）——引用在被引用资源的 scope 内解析。
+- 未信任的项目一律拒绝：只加载全局资源，所有变更路由被拒绝，并且当 session 可能仍活跃时 `session_shutdown` 不再销毁已信任的工作区（空闲工作区一小时后被清扫；host 独立停止）。
+- Web 编辑器新增 scope 下拉，可向任一存储创建 stack/profile，并通过显式 `global:<id>` 路由执行全局变更。
+
+## Lane 3：subagent 包拆分
+
+Subagent 执行功能从主包移入可选包 `@zihanw/pi-forge-subagents`（要求 `@zihanw/pi-forge@^0.5.0`）。如需保留前台 delegation，请单独安装该包。
+
+- **命令：** `/subagents` 和 `/subagent-run` 已从主包移除。可选包注册 `/forge-agent backends|plan|run`。
+- **模型工具：** `forge_subagent_profiles` 和 `forge_subagent` 由可选包注册。
+- **配置：** `subagents.*` 从 `.pi/forge/config.json` 移入专用的 `.pi/forge/subagents.json`（可信项目）和 `~/.pi/forge/subagents.json`（用户默认）。可选包会把旧的 `config.json.subagents` 段落作为只读回退读取并发出警告；它永远不会写入旧位置。把配置值复制到 `subagents.json` 即可消除警告。
+- **Web 编辑器：** delegation 卡片已从主编辑器移除；请直接编辑 `subagents.json`。
+- **架构：** 主包的 prompt 编译器不再携带 subagent 假设，`ForgeWorkspace` 是资源状态和编译上下文的唯一持有者。
+
+## Lane 4：Forge 原生 host 契约与公开 surface
+
+- 主包不再依赖 `@zihanw/pi-subagent-runtime`，也不再导出 0.4 执行契约。该契约（`AgentRequest`、`createAgentExecutionPlan`、`validateAgentRequest`、`negotiateSubagentTools`、preflight/plan/response 校验器等）现在位于 `@zihanw/pi-forge-subagents` 内部，供其自身 runtime 接线使用；两个包都不把它作为第三方可用的公开 surface。
+- `@zihanw/pi-forge/subagent` 现在只导出带版本的 host port：wire DTO 与校验器、`ForgeHostTransport`、`ForgeHost`/`ForgeHostClient`、生命周期常量，以及 Forge 持有的规范指纹辅助函数。`resolveSubagentHostProfile` / `prepareSubagentHostPlan` 已被 host port 的 `resolveProfile` 和 `prepare` 操作取代。
+- 包根只导出默认扩展工厂、`registerMacro`/`registerSlot` 及其契约类型。其余根导出（loader、agent-profile、profile-service、catalog、resource-identity、render-helper 值、`forge-v1` 引擎、registry 读取器）已全部移除。
+- 所有 `@zihanw/pi-forge/src/*` 子路径别名和 `./examples/*` 导出均已移除；`check-package` 会拒绝它们。
+
+### 导入迁移表
+
+| 0.4 导入 | 0.5 替代 |
+|---|---|
+| `@zihanw/pi-forge`（默认导出、`registerMacro`、`registerSlot`） | 不变 |
+| `@zihanw/pi-forge/subagent` host-port 名称（`ForgeHost*`、校验器、指纹） | 不变 |
+| `@zihanw/pi-forge/subagent` 执行契约（`AgentRequest`、`createAgentExecutionPlan` 等） | 已内置于 `@zihanw/pi-forge-subagents`；无公开替代 |
+| `@zihanw/pi-forge/subagent` 的 `resolveSubagentHostProfile` / `prepareSubagentHostPlan` | 通过 `ForgeHostClient` 使用 host-port 操作 |
+| `@zihanw/pi-forge/src/*` 别名 | 已移除；无替代（内部实现） |
+| 根部的 loader/profile/catalog/engine 再导出 | 已移除；无替代（内部实现） |
+
+## 兼容性说明
+
+- Host port 的 wire 结构在 `FORGE_HOST_PORT_VERSION = 1` 内只做增量扩展；未知操作会以普通的 `{ ok: false, error }` 结果拒绝（`"Unknown Forge host operation: …"`），而不是抛出异常。可选包必须把任何操作失败视为该请求的终态。
+- 主包内置的指纹辅助函数由黄金向量锁定，与 `@zihanw/pi-subagent-runtime` 的规范序列化保持字节兼容；计划封存（plan sealing）仍只发生在可选包中。

package/docs/zh-CN/guides/web-editor.md

@@ -29,17 +29,17 @@
 - 拖拽排序、启用/禁用、校验和完整编译预览；
 - 工具/skill 搜索、精确名称 chips 和通配符策略；
 - variables、context 和 regex 规则；
-- 原生 pi-forge 与 SillyTavern JSON 导入；
+- 原生 pi-forge JSON 导入；
 - 导出、fork、删除和 payload 捕获。
 
 已有 ID 在编辑时不可修改；需要新 ID 时使用 **Fork**，避免破坏 profile 引用和当前选择。工具栏的 scope 下拉（默认 `project`）决定新建、导入和 fork 的写入位置：选择 `global` 写入用户全局 `~/.pi/forge/prompt-stacks`，选择 `project` 写入项目 `.pi/forge/prompt-stacks`。列表会为全局 stack 显示 `global` badge；保存和删除通过 `global:<id>` 路由精确作用于全局文件。保存、导入、fork 和删除后会重新加载当前 Pi session。
 
 ## Agent profile 工作区
 
-列表显示 profile ID、名称、模型、思考等级、stack、校验状态、auto-activation、last-applied provenance 和 delegation 状态。每个 profile 都带 `project` / `global` scope badge；同 ID 的 shadow 对会显示 `shadows global:<id>` 或 `shadowed by project:<id>`。
+列表显示 profile ID、名称、模型、思考等级、stack、校验状态、auto-activation 和 last-applied provenance。每个 profile 都带 `project` / `global` scope badge；同 ID 的 shadow 对会显示 `shadows global:<id>` 或 `shadowed by project:<id>`。
 
 可信项目通过 **New profile** 旁的 scope 下拉（默认 `project`）选择目标 scope：选择 `global` 写入用户全局 `~/.pi/forge/agent-profiles`，选择 `project` 写入项目 `.pi/forge/agent-profiles`。全局 profile 可通过显式 `global:<id>` 路由编辑、校验、保存、一次性应用和删除；未限定路由始终只作用于项目资源。编辑全局 profile 时，stack 下拉只显示全局 stack。Model 选项来自 Pi registry，thinking 选项反映模型支持，stack 选项来自同一个 repository。编辑器会拒绝同 scope 内第二个 auto-activation profile。
 
-Delegation 卡片按 profile 的 scope 修改 `subagents.profiles.<id>` 的 enable/backend/timeout：项目 profile 写入项目 config，全局 profile 写入用户全局 config。切换 profile、刷新、删除或离开页面时，未保存的 delegation 字段会得到保护。通用默认值和 `allowAgentInvocationWithoutApproval` 只能在 config 文件中设置。
+## Delegation
 
-启用前请阅读[前台 delegation](delegation.md)。
+Delegation 配置不在主编辑器中。可选包 `@zihanw/pi-forge-subagents` 持有专用的 `.pi/forge/subagents.json` 和 `~/.pi/forge/subagents.json` 文件。启用 profile 前请阅读[前台 delegation](delegation.md)。

package/docs/zh-CN/reference/commands.md

@@ -23,7 +23,6 @@
 | 命令 | 行为 |
 |---|---|
 | `/preset migrate-stacks [--dry-run] [--overwrite] [--delete-legacy]` | 把旧 stack 复制到 `.pi/forge/prompt-stacks` |
-| `/preset import-silly <path> [character_id] [--dry-run] [--overwrite]` | 转换 SillyTavern preset 并生成报告 |
 
 覆盖或删除之前请先使用 `--dry-run`。
 
@@ -42,13 +41,15 @@
 
 ## 实验性 delegation
 
+以下命令由可选包 `@zihanw/pi-forge-subagents` 提供。
+
 | 命令 | 行为 |
 |---|---|
 | `/forge-agent backends` | 列出 backend、capabilities 和默认值 |
 | `/forge-agent plan <profile> [--backend <id>] <task>` | 准备、显示并丢弃计划，不联系 provider |
 | `/forge-agent run <profile> [--backend <id>] <task>` | 审批并执行前台只读任务 |
 
-只接受匹配 scope 明确授权的 profile：项目 config 授权 `project:<id>`，全局 config 授权 `global:<id>`。模型工具为 `forge_subagent_profiles` 和 `forge_subagent`。见[安全说明](../guides/delegation.md)。
+只接受匹配 scope 明确授权的 profile：项目 `subagents.json` 授权 `project:<id>`，全局 `subagents.json` 授权 `global:<id>`；也可使用 `.pi/forge/config.json.subagents` 作为只读兼容来源。模型工具为 `forge_subagent_profiles` 和 `forge_subagent`。见[安全说明](../guides/delegation.md)。
 
 ## Payload
 

package/examples/custom-system-status-extension/README.md

@@ -4,7 +4,7 @@ This example shows how trusted pi-forge extension modules can register a custom
 
 It registers:
 
-- `{{cpuLoad}}` macro: one-line CPU load summary.
+- `{{ extensions.cpuLoad }}` macro: one-line CPU load summary.
 - `machine-status` slot: CPU load, OS load average, memory, and uptime snapshot.
 
 The renderers are synchronous, so this example uses Node's OS load average and memory APIs. It is a rough machine-load signal, not an async sampled CPU-utilization profiler.
@@ -53,12 +53,12 @@ Each module exports a default function or named `register` function:
 
 ```ts
 export default function register(api) {
-  api.registerMacro({ name: "cpuLoad", render: () => "..." });
+  api.registerMacro({ name: "cpuLoad", dependencies: [], render: ({ env, helpers }) => "..." });
   api.registerSlot({ name: "machine-status", render: () => "..." });
 }
 ```
 
-pi-forge passes the registration API into the function, tracks unregister callbacks, and unregisters previous definitions before reloading the folder. If the extension is not loaded, the stack can still be read, but `machine-status` will validate as an unsupported slot and `{{cpuLoad}}` will remain an unresolved macro.
+pi-forge passes the registration API into the function, tracks unregister callbacks, and unregisters previous definitions before reloading the folder. If the extension is not loaded, the stack can still be read, but `machine-status` will validate as an unsupported slot and `{{ extensions.cpuLoad }}` will remain an unresolved extension path.
 
 Only use this folder for trusted code. These modules execute with normal local code permissions after the project is trusted.
 

package/examples/custom-system-status-extension/index.ts

@@ -5,7 +5,8 @@ interface ForgeRegistrationApi {
 		name: string;
 		source?: string;
 		description?: string;
-		render: () => string;
+		dependencies?: string[];
+		render: (ctx: { env: Record<string, unknown>; helpers: unknown }) => string;
 	}): () => void;
 	registerSlot(definition: {
 		name: string;

package/examples/custom-system-status-extension/prompt-stack.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "type": "pi-forge.prompt-stack",
   "id": "custom-system-status",
   "name": "Custom System Status",
@@ -12,7 +12,7 @@
       "name": "CPU Load Macro",
       "enabled": true,
       "role": "system",
-      "content": "Current rough CPU load: {{cpuLoad}}"
+      "content": "Current rough CPU load: {{ extensions.cpuLoad }}"
     },
     {
       "kind": "slot",
@@ -35,5 +35,6 @@
       "enabled": true,
       "slot": "chat-history"
     }
-  ]
+  ],
+  "parameters": {}
 }

package/examples/default-prompt-stack.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "type": "pi-forge.prompt-stack",
   "id": "default",
   "name": "Default Pi Prompt Mirror",
@@ -14,10 +14,14 @@
     "allowDuplicateChatHistory": false
   },
   "tools": {
-    "allow": ["*"]
+    "allow": [
+      "*"
+    ]
   },
   "skills": {
-    "allow": ["*"]
+    "allow": [
+      "*"
+    ]
   },
   "items": [
     {
@@ -116,5 +120,6 @@
       "enabled": true,
       "slot": "chat-history"
     }
-  ]
+  ],
+  "parameters": {}
 }

package/examples/image-reader-prompt-stack.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "type": "pi-forge.prompt-stack",
   "id": "image-reader",
   "name": "Image Reader Subagent",
@@ -14,13 +14,11 @@
     "allowDuplicateChatHistory": false
   },
   "tools": {
-    "deny": ["bash", "edit", "write"]
-  },
-  "variables": {
-    "audience": "main agent",
-    "report_mode": "image-reader",
-    "detail_level": "exhaustive factual visual inventory",
-    "safety_scope": "include safety-relevant visual content neutrally without giving instructions for harmful acts"
+    "deny": [
+      "bash",
+      "edit",
+      "write"
+    ]
   },
   "items": [
     {
@@ -29,7 +27,7 @@
       "name": "Image Reader Role",
       "enabled": true,
       "role": "system",
-      "content": "{{setturnvar::active_preset::image-reader}}You are an image reader subagent. Your job is to inspect image inputs directly and produce a faithful visual report for the {{audience}}.\n\nUse this stack only when you can actually inspect the image. If no image is present, the image is inaccessible, or the current model cannot view images, say that directly and do not guess.\n\nPrimary objective: describe exactly what is visible in the image in detail. Treat the report as sensory evidence for another agent, not as advice, judgment, or creative writing."
+      "content": "You are an image reader subagent. Your job is to inspect image inputs directly and produce a faithful visual report for the {{ parameters.audience }}.\n\nUse this stack only when you can actually inspect the image. If no image is present, the image is inaccessible, or the current model cannot view images, say that directly and do not guess.\n\nPrimary objective: describe exactly what is visible in the image in detail. Treat the report as sensory evidence for another agent, not as advice, judgment, or creative writing."
     },
     {
       "kind": "block",
@@ -45,21 +43,7 @@
       "name": "Macro Context",
       "enabled": true,
       "role": "system",
-      "content": "{{ifeq::report_mode::image-reader::Report mode is active: {{upper::{{report_mode}}}}.::Report mode is not image-reader; state this mismatch before proceeding.}}\n{{ifvar::safety_scope::Safety scope: {{safety_scope}}.}}\n{{iftools::read::If the user references an image file path and direct vision input is unavailable, you may inspect only file metadata or surrounding text with read tools; do not pretend metadata is image vision.}}\n{{ifslot::variables::Runtime variables are available below for auditability.}}"
-    },
-    {
-      "kind": "slot",
-      "id": "variables",
-      "name": "Image Reader Variables",
-      "enabled": true,
-      "role": "system",
-      "slot": "variables",
-      "options": {
-        "includeStatic": true,
-        "includeSession": true,
-        "includeTurn": true,
-        "format": "plain"
-      }
+      "content": "Report mode is active: {{ parameters.report_mode | upper }}.\nSafety scope: {{ parameters.safety_scope }}.\n{% if runtime.tool.read %}If the user references an image file path and direct vision input is unavailable, you may inspect only file metadata or surrounding text with read tools; do not pretend metadata is image vision.{% endif %}"
     },
     {
       "kind": "slot",
@@ -118,7 +102,13 @@
       "name": "Current Image Task",
       "enabled": true,
       "role": "user",
-      "content": "<current_image_task>\n{{xml::{{lastUserMessage}}}}\n</current_image_task>\n\nProduce the image report now for the {{audience}}.\n\nRequired output:\n1. Access check: state whether you can directly inspect the image.\n2. One-sentence overview: summarize the scene plainly.\n3. Detailed inventory: list visible subjects, objects, setting, text, colors, layout, and relationships.\n4. Safety-relevant content: list visible hazards, injuries, weapons, explicit content, abuse indicators, hate symbols, or other potentially harmful content. Write \"None visible\" only if none are visible.\n5. Uncertainties: list anything important that is unclear, ambiguous, cropped, blurry, or inferred.\n6. Machine-readable summary: include one compact JSON object with keys \"canInspectImage\", \"overview\", \"visibleText\", \"safetyRelevantContent\", and \"uncertainties\". Use strings or arrays only; do not include markdown inside the JSON.\n\nRequest as JSON string for logging: {{json::{{lastUserMessage}}}}"
+      "content": "<current_image_task>\n{{ runtime.lastUserMessage | xml }}\n</current_image_task>\n\nProduce the image report now for the {{ parameters.audience }}.\n\nRequired output:\n1. Access check: state whether you can directly inspect the image.\n2. One-sentence overview: summarize the scene plainly.\n3. Detailed inventory: list visible subjects, objects, setting, text, colors, layout, and relationships.\n4. Safety-relevant content: list visible hazards, injuries, weapons, explicit content, abuse indicators, hate symbols, or other potentially harmful content. Write \"None visible\" only if none are visible.\n5. Uncertainties: list anything important that is unclear, ambiguous, cropped, blurry, or inferred.\n6. Machine-readable summary: include one compact JSON object with keys \"canInspectImage\", \"overview\", \"visibleText\", \"safetyRelevantContent\", and \"uncertainties\". Use strings or arrays only; do not include markdown inside the JSON.\n\nRequest as JSON string for logging: {{ runtime.lastUserMessage | json }}"
     }
-  ]
+  ],
+  "parameters": {
+    "audience": "main agent",
+    "report_mode": "image-reader",
+    "detail_level": "exhaustive factual visual inventory",
+    "safety_scope": "include safety-relevant visual content neutrally without giving instructions for harmful acts"
+  }
 }

package/examples/reviewer-prompt-stack.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "type": "pi-forge.prompt-stack",
   "id": "reviewer",
   "name": "Focused Code Reviewer",
@@ -14,12 +14,10 @@
     "allowDuplicateChatHistory": false
   },
   "tools": {
-    "deny": ["edit", "write"]
-  },
-  "variables": {
-    "review_focus": "correctness, regressions, security, maintainability, and missing tests",
-    "review_style": "findings first, ordered by severity",
-    "max_findings": "8"
+    "deny": [
+      "edit",
+      "write"
+    ]
   },
   "items": [
     {
@@ -28,7 +26,7 @@
       "name": "Reviewer Role",
       "enabled": true,
       "role": "system",
-      "content": "You are a senior code reviewer operating inside pi. Review the user's target with a skeptical engineering lens. Prioritize {{review_focus}}.\n\nRules:\n- Do not edit files or write patches unless the user explicitly asks for implementation.\n- You may inspect files and run safe read-only commands when needed.\n- Treat previous conversation as context, not as the target unless the latest user message says so.\n- Prefer concrete file/line references when available.\n- If there are no substantive issues, say that clearly and mention residual risks or test gaps."
+      "content": "You are a senior code reviewer operating inside pi. Review the user's target with a skeptical engineering lens. Prioritize {{ parameters.review_focus }}.\n\nRules:\n- Do not edit files or write patches unless the user explicitly asks for implementation.\n- You may inspect files and run safe read-only commands when needed.\n- Treat previous conversation as context, not as the target unless the latest user message says so.\n- Prefer concrete file/line references when available.\n- If there are no substantive issues, say that clearly and mention residual risks or test gaps."
     },
     {
       "kind": "slot",
@@ -58,20 +56,6 @@
       "role": "system",
       "slot": "date-cwd"
     },
-    {
-      "kind": "slot",
-      "id": "variables",
-      "name": "Review Variables",
-      "enabled": true,
-      "role": "system",
-      "slot": "variables",
-      "options": {
-        "includeStatic": true,
-        "includeSession": true,
-        "includeTurn": false,
-        "format": "plain"
-      }
-    },
     {
       "kind": "block",
       "id": "history-open",
@@ -109,7 +93,12 @@
       "name": "Current Review Target",
       "enabled": true,
       "role": "user",
-      "content": "<review_target>\n{{lastUserMessage}}\n</review_target>\n\nReview this target now. Lead with findings, ordered by severity. Limit yourself to the most important {{max_findings}} findings unless the target asks for exhaustive review. Use this format:\n\nFindings:\n- [severity] file:line - issue, impact, and suggested fix.\n\nOpen questions:\n- List only questions that materially affect the review.\n\nIf no findings are present, write \"No blocking findings\" and then summarize remaining test or operational risk."
+      "content": "<review_target>\n{{ runtime.lastUserMessage }}\n</review_target>\n\nReview this target now. Lead with findings, ordered by severity. Limit yourself to the most important {{ parameters.max_findings }} findings unless the target asks for exhaustive review. Use this format:\n\nFindings:\n- [severity] file:line - issue, impact, and suggested fix.\n\nOpen questions:\n- List only questions that materially affect the review.\n\nIf no findings are present, write \"No blocking findings\" and then summarize remaining test or operational risk."
     }
-  ]
+  ],
+  "parameters": {
+    "review_focus": "correctness, regressions, security, maintainability, and missing tests",
+    "review_style": "findings first, ordered by severity",
+    "max_findings": "8"
+  }
 }