@tea-agent/loop-agent 0.25.6 → 0.26.0

package/skills/loop-agent/references/long-running-loop.md

@@ -1,57 +1,57 @@
-# Long-Running Loop 详细规则
-
-需要跨多轮记录目标、压缩记忆、round facts 引用，或使用 `loop init|status|run|record-round|add-signal|closeout` 时使用本文。`loop` 是 experimental outer workflow state：它不替代 Agent DAG，也不等同于已移除的顺序式 `run loop`。共享 policy 摘要见 `harness-policy.md` 的 "Long-running loop policy" 一节。
-
-## 最小入口
-
-```bash
-loop-agent loop init <task-id>
-loop-agent loop status <task-id>
-loop-agent loop run <task-id> --action shell-verify --command "bash scripts/check-repo.sh"
-loop-agent loop run <task-id> --action pi-review
-loop-agent loop run <task-id> --action dag
-loop-agent loop run <task-id> --action dag --execute
-loop-agent loop run <task-id> --auto --max-rounds 3
-loop-agent loop run <task-id> --auto --max-rounds 3
-loop-agent loop add-signal <task-id> --type human_followup --message "review this boundary before closeout"
-loop-agent loop closeout <task-id>
-loop-agent loop record-round <task-id> \
-  --action manual \
-  --result "summary" \
-  --lesson "what to carry forward" \
-  --next "next bounded action" \
-  --decision continue \
-  --ref ".harness/runs/completed/<run-id>/result.json"
-```
-
-## 状态源与记忆规则
-
-- `loop/objective.md` 与 `loop/context.md` 是运行态投影；exec plan / task source 仍是需求状态源。
-- `rounds.jsonl` 只引用 canonical facts，不复制完整 executor 日志。
-- `context.md` 每轮重写为压缩记忆，不无限 append。
-- `events.jsonl` 只用于 observability，覆盖 loop_start、round_start、action_start、action_finish、context_rewrite、decision、loop_finish；不要把 events 当状态源。
-
-## Action 规则
-
-- `loop run --action shell-verify` 是 deterministic action；命令 exit code 决定 verification result，输出摘要写入 `loop/verification/round-N.json`。
-- `loop run --action pi-review` 必须保持 read-only；工具 allowlist 固定为 `read,grep,find,ls`，输出必须包含 `findingSummary`、`failureCategory`、`nextHypothesis`、`recommendedAction`、`fixScope`、`rootCause`，其中 `recommendedAction` 只能是 `implement_fix|replan|pause|done`。
-- 自动写入只能通过 `loop run --action dag --execute` / auto DAG execute；须读取 task `allowedPaths` / `forbiddenPaths` 并审查 writer writeSet。
-- `loop run --action dag` 默认是 review mode：调用 `dag run-task <task-id> --profile auto --strict-models` 生成 DAG，再用 `dag validate --strict-models --strict-governance` 校验，并记录 review packet。
-- `loop run --action dag --execute` 才会调用 `run-dag`，随后读取 `dag report --json` 作为 round result；paused DAG 会让 loop 进入 `paused`。
-
-## Auto mode 与写入边界
-
-- `loop run --auto --max-rounds N` 使用 deterministic policy 选择下一轮 action；默认只会自动选择 shell-verify、pi-review、dag review 或 policy pause/block。
-- 自动 DAG execute 必须显式 opt-in：`task.json.loopAutoExecutionPolicy="enabled"`，或 `approval-required` 加 pending approval；旧 `loopAutoWritePolicy` fail-fast。
-- auto mode 遇到同类 failure streak 达阈值会 blocked，避免无限重试。
-
-## Signals
-
-- `loop add-signal` 写入 durable `signals.jsonl`，支持 `human_followup|approval|scope_changed|review_feedback`；urgent/scope_changed 会 pause，review feedback / human follow-up 先走 read-only Pi review，approval 触发下一轮 DAG review packet。
-- Signals 不直接覆盖 `objective.md`；DAG decision envelope / approve / reject / resume 仍由 DAG action 机制管理，loop 只记录 refs。
-
-## Closeout
-
-- `loop closeout` 从 loop state、objective/context、rounds 和 signals 派生 `loop/closeout.md` draft；draft 会标出 workflow path（`dag` / `explicit-fallback` / `missing-dag-evidence` / `micro-or-small`）与 fallback reason。
-- 非 complete 状态必须标 partial/paused/blocked，不能修改 completed facts；medium/large loop 若缺少 DAG round 且没有 `dagFallbackReason`，必须把缺失 DAG 证据列为 remaining risk。
-- 完成声明仍必须由 shell verification、review verdict 和 success criteria coverage 证明。
+# Long-Running Loop 详细规则
+
+需要跨多轮记录目标、压缩记忆、round facts 引用，或使用 `loop init|status|run|record-round|add-signal|closeout` 时使用本文。`loop` 是 experimental outer workflow state：它不替代 Agent DAG，也不等同于已移除的顺序式 `run loop`。共享 policy 摘要见 `harness-policy.md` 的 "Long-running loop policy" 一节。
+
+## 最小入口
+
+```bash
+loop-agent loop init <task-id>
+loop-agent loop status <task-id>
+loop-agent loop run <task-id> --action shell-verify --command "bash scripts/check-repo.sh"
+loop-agent loop run <task-id> --action pi-review
+loop-agent loop run <task-id> --action dag
+loop-agent loop run <task-id> --action dag --execute
+loop-agent loop run <task-id> --auto --max-rounds 3
+loop-agent loop run <task-id> --auto --max-rounds 3
+loop-agent loop add-signal <task-id> --type human_followup --message "review this boundary before closeout"
+loop-agent loop closeout <task-id>
+loop-agent loop record-round <task-id> \
+  --action manual \
+  --result "summary" \
+  --lesson "what to carry forward" \
+  --next "next bounded action" \
+  --decision continue \
+  --ref ".harness/runs/completed/<run-id>/result.json"
+```
+
+## 状态源与记忆规则
+
+- `loop/objective.md` 与 `loop/context.md` 是运行态投影；exec plan / task source 仍是需求状态源。
+- `rounds.jsonl` 只引用 canonical facts，不复制完整 executor 日志。
+- `context.md` 每轮重写为压缩记忆，不无限 append。
+- `events.jsonl` 只用于 observability，覆盖 loop_start、round_start、action_start、action_finish、context_rewrite、decision、loop_finish；不要把 events 当状态源。
+
+## Action 规则
+
+- `loop run --action shell-verify` 是 deterministic action；命令 exit code 决定 verification result，输出摘要写入 `loop/verification/round-N.json`。
+- `loop run --action pi-review` 必须保持 read-only；工具 allowlist 固定为 `read,grep,find,ls`，输出必须包含 `findingSummary`、`failureCategory`、`nextHypothesis`、`recommendedAction`、`fixScope`、`rootCause`，其中 `recommendedAction` 只能是 `implement_fix|replan|pause|done`。
+- 自动写入只能通过 `loop run --action dag --execute` / auto DAG execute；须读取 task `allowedPaths` / `forbiddenPaths` 并审查 writer writeSet。
+- `loop run --action dag` 默认是 review mode：调用 `dag run-task <task-id> --profile auto --strict-models` 生成 DAG，再用 `dag validate --strict-models --strict-governance` 校验，并记录 review packet。
+- `loop run --action dag --execute` 才会调用 `run-dag`，随后读取 `dag report --json` 作为 round result；paused DAG 会让 loop 进入 `paused`。
+
+## Auto mode 与写入边界
+
+- `loop run --auto --max-rounds N` 使用 deterministic policy 选择下一轮 action；默认只会自动选择 shell-verify、pi-review、dag review 或 policy pause/block。
+- 自动 DAG execute 必须显式 opt-in：`task.json.loopAutoExecutionPolicy="enabled"`，或 `approval-required` 加 pending approval；旧 `loopAutoWritePolicy` fail-fast。
+- auto mode 遇到同类 failure streak 达阈值会 blocked，避免无限重试。
+
+## Signals
+
+- `loop add-signal` 写入 durable `signals.jsonl`，支持 `human_followup|approval|scope_changed|review_feedback`；urgent/scope_changed 会 pause，review feedback / human follow-up 先走 read-only Pi review，approval 触发下一轮 DAG review packet。
+- Signals 不直接覆盖 `objective.md`；DAG decision envelope / approve / reject / resume 仍由 DAG action 机制管理，loop 只记录 refs。
+
+## Closeout
+
+- `loop closeout` 从 loop state、objective/context、rounds 和 signals 派生 `loop/closeout.md` draft；draft 会标出 workflow path（`dag` / `explicit-fallback` / `missing-dag-evidence` / `micro-or-small`）与 fallback reason。
+- 非 complete 状态必须标 partial/paused/blocked，不能修改 completed facts；medium/large loop 若缺少 DAG round 且没有 `dagFallbackReason`，必须把缺失 DAG 证据列为 remaining risk。
+- 完成声明仍必须由 shell verification、review verdict 和 success criteria coverage 证明。

package/skills/loop-agent/references/model-routing.md

@@ -17,6 +17,8 @@
 
 Agent DAG node 的模型来自 DAG JSON 中的 `executorModels`，并由 `dag validate --strict-models` 检查 canonical matrix 漂移。若变更模型配置，须同步更新 `harness.json`、相关测试、repo docs 与本 skill。
 
+`executorModels.pi` 的每档值支持两种形式：裸模型名继续走内置映射或默认 `wizard-local`；`provider/model` 限定引用则显式选择 Pi provider，只在第一个 `/` 处分割并保留模型 ID 的剩余部分。provider 定义与凭证仍归 Pi 的 `~/.pi/agent/models.json` 和环境配置所有。例如不同档可分别写 `wizard-local/glm-5.2` 与 `deepseek/deepseek-v4-flash`。
+
 `pi-prompt` 是独立 one-shot helper，不使用 `harness.json.models` 或 DAG `executorModels`。当前默认是 `wizard-local/glm-5.2`；高复杂度 one-shot 显式传 `--model gpt-5.5`。Agent DAG `pi` executor 的 canonical matrix 保持；读写 profile 共用同一矩阵：
 
 ```json

package/skills/loop-agent/references/one-shot-runs.md

@@ -1,85 +1,85 @@
-# One-shot Run Evidence（`.harness/runs/`）
-
-当你使用 `cursor-prompt`、Pi `cursor` tool、`promote-run`，或在治理检查中看到 `.harness/runs/active` warning 时，读本文。
-
-## 目录职责
-
-`.harness/runs/` 保存一次性工具调用的运行证据。它不是 task 状态源，也不是 Agent DAG run 目录。
-
-```text
-.harness/runs/active/<run-id>/      # 正在执行或异常残留的 one-shot tool run
-.harness/runs/completed/<run-id>/   # 成功完成的 one-shot run evidence
-.harness/runs/failed/<run-id>/      # 失败的 one-shot run evidence
-```
-
-每个 run directory 通常包含：
-
-```text
-run.md
-meta.json
-artifacts/
-```
-
-`run.md` 是人类可读摘要；`meta.json` 是机器可读 run metadata；`artifacts/` 是该次 one-shot 的交付物目录。
-
-## 什么时候创建
-
-会创建 `.harness/runs/` 的常见入口：
-
-- `loop-agent cursor-prompt ...`
-- Pi `cursor` tool / loop-agent cursor tool 的 one-shot Cursor 调用
-- 内部 two-phase one-shot logging：先 `createActiveCursorRun()`，再 `finalizeCursorRunLog()`
-
-创建条件：
-
-- 调用的 `cwd` 必须是含 `.harness/` 的 harness repo。
-- `cursor-prompt` 会先创建 `.harness/runs/active/<run-id>/`，再把结果归档。
-- 成功时整个目录移动到 `.harness/runs/completed/<run-id>/`。
-- 失败、timeout 或 cancel 时整个目录移动到 `.harness/runs/failed/<run-id>/`。
-
-当前 `pi-prompt` 不创建 `.harness/runs/`。它是 one-shot helper，但不维护 run evidence、task state、verification 或 handoff artifact。
-
-## 与 task / DAG 的关系
-
-| 目录 | 含义 | 是否代表 task 完成 |
-|---|---|---|
-| `.harness/tasks/<task-id>/` | task 运行态状态源 | 是 task 状态源 |
-| `.harness/runs/<state>/<run-id>/` | one-shot tool run evidence | 否，只是一次执行证据 |
-| `.harness/dag-runs/<state>/<run-id>/` | Agent DAG run facts | 否，只是 DAG run facts |
-
-completed one-shot evidence 若要进入 task artifacts，使用：
-
-```bash
-loop-agent promote-run <task-id> --run-id <run-id>
-loop-agent closeout task <task-id>
-```
-
-`promote-run` 只读 `.harness/runs/completed/**`，生成或更新 task `artifacts/修改记录.md` / `artifacts/验证结果.md`，不修改 completed run facts。
-
-## Active 目录清理
-
-`.harness/runs/active/` 只应存在 live one-shot run。治理检查发现 active 内容时会 warning：
-
-```text
-[HARNESS RUNTIME WARNING] .harness/runs/active contains runtime entries
-```
-
-处理规则：
-
-- 如果确有 one-shot 正在执行，可以保留；必要时用 `HARNESS_ALLOW_ACTIVE_TOOL_RUNS=1` 跑治理检查。
-- 如果是已完成、失败或中断残留，应移动到 `completed/` / `failed/`，或在确认无价值后删除。
-- 如果是 `.DS_Store` 等系统垃圾文件，直接删除；它不是合法 run evidence。
-- 不要把 active 残留当作 task 完成证据。
-
-严格检查可用：
-
-```bash
-HARNESS_STRICT_ACTIVE_TOOL_RUNS=1 bash scripts/check-harness-runtime-clean.sh
-```
-
-## 不要做什么
-
-- 不要提交 `.harness/runs/**` 运行态内容。
-- 不要手动改写 `.harness/runs/completed/**` 或 `.harness/runs/failed/**` 事实。
-- 不要把 `.harness/runs/active/**` 当作长期记录。
-- 不要把 one-shot evidence 直接等同于 task artifacts；需要汇总时用 `promote-run`。
+# One-shot Run Evidence（`.harness/runs/`）
+
+当你使用 `cursor-prompt`、Pi `cursor` tool、`promote-run`，或在治理检查中看到 `.harness/runs/active` warning 时，读本文。
+
+## 目录职责
+
+`.harness/runs/` 保存一次性工具调用的运行证据。它不是 task 状态源，也不是 Agent DAG run 目录。
+
+```text
+.harness/runs/active/<run-id>/      # 正在执行或异常残留的 one-shot tool run
+.harness/runs/completed/<run-id>/   # 成功完成的 one-shot run evidence
+.harness/runs/failed/<run-id>/      # 失败的 one-shot run evidence
+```
+
+每个 run directory 通常包含：
+
+```text
+run.md
+meta.json
+artifacts/
+```
+
+`run.md` 是人类可读摘要；`meta.json` 是机器可读 run metadata；`artifacts/` 是该次 one-shot 的交付物目录。
+
+## 什么时候创建
+
+会创建 `.harness/runs/` 的常见入口：
+
+- `loop-agent cursor-prompt ...`
+- Pi `cursor` tool / loop-agent cursor tool 的 one-shot Cursor 调用
+- 内部 two-phase one-shot logging：先 `createActiveCursorRun()`，再 `finalizeCursorRunLog()`
+
+创建条件：
+
+- 调用的 `cwd` 必须是含 `.harness/` 的 harness repo。
+- `cursor-prompt` 会先创建 `.harness/runs/active/<run-id>/`，再把结果归档。
+- 成功时整个目录移动到 `.harness/runs/completed/<run-id>/`。
+- 失败、timeout 或 cancel 时整个目录移动到 `.harness/runs/failed/<run-id>/`。
+
+当前 `pi-prompt` 不创建 `.harness/runs/`。它是 one-shot helper，但不维护 run evidence、task state、verification 或 handoff artifact。
+
+## 与 task / DAG 的关系
+
+| 目录 | 含义 | 是否代表 task 完成 |
+|---|---|---|
+| `.harness/tasks/<task-id>/` | task 运行态状态源 | 是 task 状态源 |
+| `.harness/runs/<state>/<run-id>/` | one-shot tool run evidence | 否，只是一次执行证据 |
+| `.harness/dag-runs/<state>/<run-id>/` | Agent DAG run facts | 否，只是 DAG run facts |
+
+completed one-shot evidence 若要进入 task artifacts，使用：
+
+```bash
+loop-agent promote-run <task-id> --run-id <run-id>
+loop-agent closeout task <task-id>
+```
+
+`promote-run` 只读 `.harness/runs/completed/**`，生成或更新 task `artifacts/修改记录.md` / `artifacts/验证结果.md`，不修改 completed run facts。
+
+## Active 目录清理
+
+`.harness/runs/active/` 只应存在 live one-shot run。治理检查发现 active 内容时会 warning：
+
+```text
+[HARNESS RUNTIME WARNING] .harness/runs/active contains runtime entries
+```
+
+处理规则：
+
+- 如果确有 one-shot 正在执行，可以保留；必要时用 `HARNESS_ALLOW_ACTIVE_TOOL_RUNS=1` 跑治理检查。
+- 如果是已完成、失败或中断残留，应移动到 `completed/` / `failed/`，或在确认无价值后删除。
+- 如果是 `.DS_Store` 等系统垃圾文件，直接删除；它不是合法 run evidence。
+- 不要把 active 残留当作 task 完成证据。
+
+严格检查可用：
+
+```bash
+HARNESS_STRICT_ACTIVE_TOOL_RUNS=1 bash scripts/check-harness-runtime-clean.sh
+```
+
+## 不要做什么
+
+- 不要提交 `.harness/runs/**` 运行态内容。
+- 不要手动改写 `.harness/runs/completed/**` 或 `.harness/runs/failed/**` 事实。
+- 不要把 `.harness/runs/active/**` 当作长期记录。
+- 不要把 one-shot evidence 直接等同于 task artifacts；需要汇总时用 `promote-run`。

package/skills/loop-agent/references/pi-prompt.md

@@ -1,23 +1,23 @@
-# One-shot Pi SDK Prompt Helper（`pi-prompt`）
-
-短时 Pi SDK task、不需要完整 `.harness/tasks/<id>` workflow 时使用本文。替代 ad-hoc 临时代码脚本导入 `executeSingleSdkAttempt` 的做法。
-
-### One-shot Pi SDK prompt helper
-
-短时 Pi SDK task、不需要完整 `.harness/tasks/<id>` workflow 时，用 `loop-agent pi-prompt`，勿创建 ad-hoc 临时代码脚本导入 `executeSingleSdkAttempt`。`pi-prompt` 是一次性 full-capability helper；是否只读由本次调用的 prompt 与 `--tools` 决定。
-
-```bash
-loop-agent pi-prompt "Reply with exactly OK."
-loop-agent pi-prompt --stdin < <temp-dir>/task.md
-loop-agent pi-prompt --file <temp-dir>/task.md
-loop-agent pi-prompt --cwd ~/go/src/loop-agent --tools read,grep,find,ls "Review the current diff. Do not edit files."
-loop-agent pi-prompt --cwd ~/go/src/loop-agent --tools subagent,read --timeout 2400000 "Use subagent exactly once ..."
-loop-agent pi-prompt --model gpt-5.5 --cwd ~/go/src/loop-agent "Deeply diagnose this failure."
-loop-agent pi-prompt "Reply with exactly OK."
-```
-
-`<temp-dir>` 表示平台原生临时目录；实际命令中使用本机路径。
-
-默认：`--provider wizard-local --model glm-5.2`；高复杂度 one-shot 可显式 `--model gpt-5.5`。按需用 `--provider`、`--model`、`--thinking`、`--tools`、`--timeout` 覆盖。
-
-`pi-prompt` 仅用于 quick one-shot SDK call。**不**创建 `.harness/tasks/`、不跑 verification、不写 handoff artifact、不保留 workflow state。须可恢复、可验证的 implementation work 用 DAG 路径；需要隔离写入时使用 bounded Cursor 或 `delegate`。
+# One-shot Pi SDK Prompt Helper（`pi-prompt`）
+
+短时 Pi SDK task、不需要完整 `.harness/tasks/<id>` workflow 时使用本文。替代 ad-hoc 临时代码脚本导入 `executeSingleSdkAttempt` 的做法。
+
+### One-shot Pi SDK prompt helper
+
+短时 Pi SDK task、不需要完整 `.harness/tasks/<id>` workflow 时，用 `loop-agent pi-prompt`，勿创建 ad-hoc 临时代码脚本导入 `executeSingleSdkAttempt`。`pi-prompt` 是一次性 full-capability helper；是否只读由本次调用的 prompt 与 `--tools` 决定。
+
+```bash
+loop-agent pi-prompt "Reply with exactly OK."
+loop-agent pi-prompt --stdin < <temp-dir>/task.md
+loop-agent pi-prompt --file <temp-dir>/task.md
+loop-agent pi-prompt --cwd ~/go/src/loop-agent --tools read,grep,find,ls "Review the current diff. Do not edit files."
+loop-agent pi-prompt --cwd ~/go/src/loop-agent --tools subagent,read --timeout 2400000 "Use subagent exactly once ..."
+loop-agent pi-prompt --model gpt-5.5 --cwd ~/go/src/loop-agent "Deeply diagnose this failure."
+loop-agent pi-prompt "Reply with exactly OK."
+```
+
+`<temp-dir>` 表示平台原生临时目录；实际命令中使用本机路径。
+
+默认：`--provider wizard-local --model glm-5.2`；高复杂度 one-shot 可显式 `--model gpt-5.5`。按需用 `--provider`、`--model`、`--thinking`、`--tools`、`--timeout` 覆盖。
+
+`pi-prompt` 仅用于 quick one-shot SDK call。**不**创建 `.harness/tasks/`、不跑 verification、不写 handoff artifact、不保留 workflow state。须可恢复、可验证的 implementation work 用 DAG 路径；需要隔离写入时使用 bounded Cursor 或 `delegate`。

package/skills/loop-agent/references/pi-subagent-assisted-mode.md

@@ -1,84 +1,84 @@
-# Pi Subagent Assisted Mode
-
-loop-agent task 启用 `piSubagentMode`、在 analyze/plan/spec/retrospective 内需要 read-only scout/planner/reviewer subagents，或配置 project-local agents/prompts 时使用本文。
-
-`task.json` 支持可选字段 `piSubagentMode`，用于 step 级 `subagent` tool delegation：
-
-| Mode | analyze | plan | spec | implement | retrospective | verify |
-|------|---------|------|------|-----------|----------------|--------|
-| `off`（默认） | read only | read only | read only | +write/edit/bash | read only | read only |
-| `analyze-plan` | **+subagent** | **+subagent** | **+subagent** | 同 off | 同 off | 同 off |
-| `full` | **+subagent** | **+subagent** | **+subagent** | 同 off | **+subagent** | 同 off |
-
-### 何时启用
-
-在 `task.json` 设 `piSubagentMode: "analyze-plan"` 或 `piSubagentMode: "full"` 当：
-- task 涉及大规模 codebase 阅读，适合 parallel scout agents
-- analysis 或 planning 需多角度调查（如跨模块比较实现）
-- retrospective review 适合独立 reviewer subagent（`full` mode）
-
-### step 内使用 `subagent` 的指引
-
-subagent 可用时，**仅用于 read-only task**：
-- **Parallel scout**：dispatch 多个 subagent 同时搜索/阅读不同区域
-- **Chain**：一个 subagent scout，另一个基于发现 planning
-- **Reviewer**：用 subagent 在定稿前 review analysis/plan
-
-**不要**用 subagent 做 writing、editing 或执行命令。subagent 输出仅 advisory；务必 verify 并将发现并入自己的输出。**不要**把 subagent 结果当作权威 state 或 artifact source。
-
-### 前置条件
-
-- Pi runtime 环境须有 `subagent` tool（经 Pi subagent extension 加载）
-- 推荐用 Pi 自带 example 文件安装：
-
-```bash
-mkdir -p ~/.pi/agent/extensions/subagent ~/.pi/agent/agents ~/.pi/agent/prompts
-
-ln -sf /usr/local/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions/subagent/index.ts ~/.pi/agent/extensions/subagent/index.ts
-ln -sf /usr/local/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions/subagent/agents.ts ~/.pi/agent/extensions/subagent/agents.ts
-
-for f in /usr/local/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions/subagent/agents/*.md; do
-  ln -sf "$f" ~/.pi/agent/agents/$(basename "$f")
-done
-
-for f in /usr/local/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions/subagent/prompts/*.md; do
-  ln -sf "$f" ~/.pi/agent/prompts/$(basename "$f")
-done
-```
-
-- 最小 smoke check：
-
-```bash
-pi -p --no-session --no-context-files --no-skills --tools subagent "Reply with exactly OK."
-```
-
-  预期输出：`OK`
-- mode 按 task opt-in；默认 `off` 保持向后兼容
-- 任何 mode 下 `implement` 都不给 `subagent`（防止 nested multi-writer）
-
-### 内置 Project-Local Agents 与 Prompts
-
-本 repo 提供 `.pi/agents/` 与 `.pi/prompts/` 模板，供 `piSubagentMode` 使用：
-
-**Agents**（`.pi/agents/`）
-
-| Agent | Role | 对应阶段 |
-|-------|------|----------|
-| `loop-agent-scout` | 只读侦察：code、tests、docs、governance | Scout |
-| `loop-agent-planner` | 最小可执行计划；强调验证与回退 | Plan |
-| `loop-agent-reviewer` | 严格审查：范围漂移、验证缺口、契约破坏 | Verify / Review |
-| `loop-agent-worker` | 有界实现与修补 | Implement |
-
-另有通用 agents：`scout` / `planner` / `worker` / `reviewer`（中文提示，可被通用 prompt 模板调用）。模型以各 agent frontmatter 为准（当前仓库默认对齐 `harness.json` 的 Pi executor）。
-
-**Prompt Templates**（`.pi/prompts/`）：输入 `/loop-agent-*` 或通用模板名调用
-
-| Template | Flow |
-|----------|------|
-| `loop-agent-scout-and-plan` | parallel scout → planner |
-| `loop-agent-analyze-wide` | 3 parallel scouts → 结构化分析 |
-| `loop-agent-review-only` | 独立审查计划/实现/验证 |
-| `loop-agent-implement-and-review` | worker → reviewer → worker |
-| `scout-and-plan` / `implement` / `implement-and-review` | 通用 chain（调用 `scout`/`planner`/`worker`/`reviewer`） |
-
-传 `agentScope: "both"` + `confirmProjectAgents: false` 以访问 repo-local agents。
+# Pi Subagent Assisted Mode
+
+loop-agent task 启用 `piSubagentMode`、在 analyze/plan/spec/retrospective 内需要 read-only scout/planner/reviewer subagents，或配置 project-local agents/prompts 时使用本文。
+
+`task.json` 支持可选字段 `piSubagentMode`，用于 step 级 `subagent` tool delegation：
+
+| Mode | analyze | plan | spec | implement | retrospective | verify |
+|------|---------|------|------|-----------|----------------|--------|
+| `off`（默认） | read only | read only | read only | +write/edit/bash | read only | read only |
+| `analyze-plan` | **+subagent** | **+subagent** | **+subagent** | 同 off | 同 off | 同 off |
+| `full` | **+subagent** | **+subagent** | **+subagent** | 同 off | **+subagent** | 同 off |
+
+### 何时启用
+
+在 `task.json` 设 `piSubagentMode: "analyze-plan"` 或 `piSubagentMode: "full"` 当：
+- task 涉及大规模 codebase 阅读，适合 parallel scout agents
+- analysis 或 planning 需多角度调查（如跨模块比较实现）
+- retrospective review 适合独立 reviewer subagent（`full` mode）
+
+### step 内使用 `subagent` 的指引
+
+subagent 可用时，**仅用于 read-only task**：
+- **Parallel scout**：dispatch 多个 subagent 同时搜索/阅读不同区域
+- **Chain**：一个 subagent scout，另一个基于发现 planning
+- **Reviewer**：用 subagent 在定稿前 review analysis/plan
+
+**不要**用 subagent 做 writing、editing 或执行命令。subagent 输出仅 advisory；务必 verify 并将发现并入自己的输出。**不要**把 subagent 结果当作权威 state 或 artifact source。
+
+### 前置条件
+
+- Pi runtime 环境须有 `subagent` tool（经 Pi subagent extension 加载）
+- 推荐用 Pi 自带 example 文件安装：
+
+```bash
+mkdir -p ~/.pi/agent/extensions/subagent ~/.pi/agent/agents ~/.pi/agent/prompts
+
+ln -sf /usr/local/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions/subagent/index.ts ~/.pi/agent/extensions/subagent/index.ts
+ln -sf /usr/local/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions/subagent/agents.ts ~/.pi/agent/extensions/subagent/agents.ts
+
+for f in /usr/local/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions/subagent/agents/*.md; do
+  ln -sf "$f" ~/.pi/agent/agents/$(basename "$f")
+done
+
+for f in /usr/local/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions/subagent/prompts/*.md; do
+  ln -sf "$f" ~/.pi/agent/prompts/$(basename "$f")
+done
+```
+
+- 最小 smoke check：
+
+```bash
+pi -p --no-session --no-context-files --no-skills --tools subagent "Reply with exactly OK."
+```
+
+  预期输出：`OK`
+- mode 按 task opt-in；默认 `off` 保持向后兼容
+- 任何 mode 下 `implement` 都不给 `subagent`（防止 nested multi-writer）
+
+### 内置 Project-Local Agents 与 Prompts
+
+本 repo 提供 `.pi/agents/` 与 `.pi/prompts/` 模板，供 `piSubagentMode` 使用：
+
+**Agents**（`.pi/agents/`）
+
+| Agent | Role | 对应阶段 |
+|-------|------|----------|
+| `loop-agent-scout` | 只读侦察：code、tests、docs、governance | Scout |
+| `loop-agent-planner` | 最小可执行计划；强调验证与回退 | Plan |
+| `loop-agent-reviewer` | 严格审查：范围漂移、验证缺口、契约破坏 | Verify / Review |
+| `loop-agent-worker` | 有界实现与修补 | Implement |
+
+另有通用 agents：`scout` / `planner` / `worker` / `reviewer`（中文提示，可被通用 prompt 模板调用）。模型以各 agent frontmatter 为准（当前仓库默认对齐 `harness.json` 的 Pi executor）。
+
+**Prompt Templates**（`.pi/prompts/`）：输入 `/loop-agent-*` 或通用模板名调用
+
+| Template | Flow |
+|----------|------|
+| `loop-agent-scout-and-plan` | parallel scout → planner |
+| `loop-agent-analyze-wide` | 3 parallel scouts → 结构化分析 |
+| `loop-agent-review-only` | 独立审查计划/实现/验证 |
+| `loop-agent-implement-and-review` | worker → reviewer → worker |
+| `scout-and-plan` / `implement` / `implement-and-review` | 通用 chain（调用 `scout`/`planner`/`worker`/`reviewer`） |
+
+传 `agentScope: "both"` + `confirmProjectAgents: false` 以访问 repo-local agents。