@tintinweb/pi-subagents：后台代理与 Worktree 隔离

概览

该扩展向 Pi 添加 Agent、get_subagent_result、steer_subagent，默认后台运行，并可通过 /agents 在 TUI 中查看。

Worktree 隔离需要明确选择，不是每个子代理的默认行为。仅有独立对话无法防止两个代理修改同一份文件。

会话与并发模型

普通子代理是宿主进程内的 SDK 会话。后台调用返回 ID，容量占满时排队，完成后通知父会话；前台调用等待结果。

maxConcurrent 默认允许 10 个后台代理。maxConcurrentForeground 默认 0，表示前台不限，且与后台分别计算。实时组件展示活动和 Token，界面功能依赖交互式 Pi 宿主。SubagentWorkflow 脚本使用 worker 线程，因此也不能概括为全部单线程执行。

Worktree 隔离保证什么

在 Agent 调用或代理 frontmatter 中添加 isolation: "worktree"。子代理在已提交历史创建的临时工作区执行，需要 Git 和初始提交；创建失败会使调用失败，不会改在父目录执行。

父工作区的暂存及未提交修改不会被带入；审查这些 diff 应使用共享工作区。Worktree 分离了工作文件，但拥有 shell 的子代理仍可离开该目录，因此不是安全沙箱。

任务完成后，未修改的 worktree 直接移除；有修改则提交或保留到本地 pi-agent-<id> 分支，临时目录移除。应审查结果中给出的分支并运行项目检查再合并，扩展不会自动合入父分支。

尝试一个范围明确的任务

使用下方命令安装，确认 Pi ≥ 0.84.0 后重启。先运行不带隔离的 Explore，验证工具、模型授权和完成通知。写入任务再明确要求 worktree，并限定一个可独立验证的修改。

下面示例创建隔离的写入代理。完成后检查 get_subagent_result 给出的分支，与原始基点对比。本示例是使用方法，此次源码核验没有执行模型任务。

Agent({
  subagent_type: "general-purpose",
  prompt: "Fix the documented failing test. Run the relevant tests and report the changed files.",
  description: "Fix one failing test",
  isolation: "worktree",
  run_in_background: true
})

控制上下文与开销

inherit_context 默认 false，但 general-purpose 仍接收父系统提示词。代理 frontmatter 可锁定上下文继承、模型与隔离设置，优先于调用参数；请求的选项似乎未生效时，先查看 /agents 中的代理配置。

每个子代理单独产生模型用量；向多个代理复制长对话会增加输入费用。创建 worktree 增加文件系统工作，不会打折 Token。扩大并行前，先用明确提示词、合适模型和较低并发。

与 pi-subagents 的区别

Nico 的 pi-subagents 也支持 worktree。其前台执行使用进程内 SDK 会话，后台则使用独立 runner，并提供执行产物。区别在编排方式与生命周期，不能简单分成“有/无 worktree”。

根据习惯选择工具接口及结果交接方式，再在实际宿主里运行小型只读任务。同时安装两者可能给模型提供重叠的编排入口。