本页为 pi-subagents 官方文档的非官方中文翻译，请以官方英文文档为准。 原文 · 许可证

pi-subagents 从 ~/.pi/agent/extensions/subagent/config.json 读取可选的 JSON 配置。本页列出每一个键，以及影响配置解析的环境变量和设置文件中的键。

设置级键（subagents.defaultModel、defaultProvider、defaultThinking、defaultExtensions、agentOverrides、machines、agentScanDirs、agentExcludeDirs、modelScope、disableThinking、disableBuiltins、看门狗设置等）位于 Pi 的设置文件，而非本配置文件。modelScope.agents.<name> 增加按智能体的限制，而 allow: ["inherit"] 允许使用当前的父会话模型。见 models.md、agents.md 与 watchdog.md。

项目根目录解析（设置）

默认情况下，项目设置从最近的、包含 .pi 或 .agents 的父目录解析，从而保留既有的嵌套项目行为。在 monorepo 或 Git 工作树中，若一个偶然出现的嵌套 .pi 目录不应遮蔽仓库级配置，请在仓库根目录的 .pi/settings.json 中设置：

{
  "subagents": {
    "projectRootResolution": "git-root"
  }
}

"git-root" 会使包发现、项目智能体、链式调用以及 agentOverrides 锚定到该 Git 工作树根目录（当该根目录也存在 Pi 项目配置时）。嵌套项目仍可通过在其自身的 .pi/settings.json 中设置 "projectRootResolution": "nearest" 来重新选择就近根目录行为。

额外的智能体扫描目录（设置）

通过 Pi 设置中的 subagents.agentScanDirs 添加递归的用户或项目智能体根目录：

{
  "subagents": {
    "agentScanDirs": ["~/.pi/flows/*/agents"]
  }
}

条目支持 ~ 展开。单个 * 路径段会展开一个目录层级，因此类包目录中的每一个都可以暴露一个 agents/ 目录。缺失的目录会被忽略。固定的用户/项目智能体目录优先级仍高于来自扫描根目录的同名智能体。

排除的智能体目录（设置）

通过 subagents.agentExcludeDirs 在递归智能体定义发现中裁剪目录子树：

{
  "subagents": {
    "agentExcludeDirs": ["~/.agents/plugins", "../.agents/plugins"]
  }
}

条目是字面意义上的目录路径（不支持通配），支持 ~ 与绝对路径。相对路径相对于其设置文件所在目录解析：用户设置相对于用户智能体配置目录，项目设置相对于项目配置目录（通常为 .pi/）。因此项目 .pi/settings.json 中的 ../.agents/plugins 会排除项目的旧版插件子树，而不会排除普通的 .agents/*.md 智能体。

用户与就近项目的排除项会在所有发现作用域中合并，包括全源诊断。它们在遍历与定义读取之前生效；显式的扫描根目录、环境根目录与已安装的包无法重新纳入被排除的子树。规范化与真实路径包含同时会排除符号链接别名，而不会匹配同级目录前缀。设置的修改会使已缓存的发现失效。被排除的智能体树不会被建立指纹；当链式发现共用一个目录时，它会保留自己未变更的监听。技能、链式调用以及扩展自带的内置快照不在本设置的作用范围内。

modelResponseAliases

位于 ~/.pi/agent/extensions/subagent/config.json（顶层，不在 subagents 下）：

{
  "modelResponseAliases": {
    "databricks-bedrock/ias-claude-opus-5": ["claude-opus-5"]
  }
}

可选地为某个提供方限定的精确启动候选接受精确的响应模型 ID。键使用已解析的 provider/model ID，不含其思考后缀，也包括回退尝试中的；值是非空响应 ID 字符串的数组。别名匹配是精确且大小写敏感的，不进行模糊或后缀匹配。空数组不增加任何被接受的 ID；格式错误的声明会导致配置加载失败。

这是你显式声明的"被声明的响应 ID 标识所请求的模型"的断言，而非来自模型输出的证明。它不会重写出站模型或提供方路由，不会授权回退模型，也不会绕过其他路由的验证。前台与后台运行都会在启动时捕获该声明，并在恢复时保留它，即使没有声明任何别名。更改配置会影响新的独立运行，而非保留的声明。在没有匹配声明的情况下，既有的严格验证保持不变。

对于原生 Pi 出现 model_verification_failed 且你的代理接受 claude-haiku-4-5 但回报 anthropic.claude-haiku-4-5-20251001-v1:0 的情况，请独立确认你的代理映射，然后配置：

{
  "modelResponseAliases": {
    "YOUR_PROVIDER/claude-haiku-4-5": ["anthropic.claude-haiku-4-5-20251001-v1:0"]
  }
}

请将 YOUR_PROVIDER 替换为已解析的 Pi 提供方 ID。保持出站模型别名不变。该原生补救在 v0.65.1 中已经存在；它不会从提供方前缀或日期推断等价性。内置的外部 claude-code 适配器不会调用此验证器，也不使用此设置。若外部运行显示该诊断，请在应用原生补救前先确认已安装的版本、已解析的运行器种类/适配器，以及错误位置。感谢 sixtus 在 #1922 中给出的具体请求 ID/响应 ID 示例。

modelExclusions

{
  "modelExclusions": {
    "defaultTtlMs": 300000
  }
}

控制模型排除的持续时间（毫秒）。默认为 86400000（24 小时），最大为 8000000000000000，以保证生成的过期时间戳仍是合法的 JavaScript 日期。扩展会在启动或重载时应用该值。较低的配置值会从原始的 recordedAt 起缩短活跃缓存的排除；它永远不会延长既有的过期时间。若 Pi 的 auth.json 在该排除被记录后被修改，则身份验证相关的排除会被忽略；其他类型的排除不受影响。启动时还会就候选被跳过的情况发出警告，包括缓存原因和过期时间。PI_MODEL_EXCLUSIONS_PATH 更改排除存储的路径，但不更改此 TTL。

toolDescriptionMode

{ "toolDescriptionMode": "compact" }

控制在启动时注册的、面向父会话的 subagent 工具描述。默认注册紧凑的执行/安全描述，外加独立的 promptSnippet 与 promptGuidelines。显式的 "compact" 使用相同的描述，但不附带那些额外元数据；"full" 添加工作流与管理细节，同样不附带拆分元数据。所有模式都保留相同的扁平参数模式。扩展的示例和配方可按需通过 action:"guide" 与自带的 pi-subagents 技能获取；full 模式并不是详尽的手册。在比较提示词占用空间时，请同时计入独立的默认元数据与工具定义本身。

custom 会先从项目配置目录读取 subagent-tool-description.md，再从 ~/.pi/agent/subagent-tool-description.md 读取。缺失、空、不可读或过大的自定义文件会回退到 full 描述。自定义模板可使用 、、、 与 ；安全指引始终存在，因此自定义文本不能移除运行时护栏。修改模式或自定义文件后，请重启 Pi。

inlineToolDisplay

{ "inlineToolDisplay": "summary" }

控制在聊天中内联显示的 subagent 工具结果。默认值 "rich" 会显示实时子智能体活动，并可展开为详细输出。"summary" 使运行中、已完成、失败、已停止与暂停的运行的内联结果保持为同一稳定的行；它不会播放动画、不显示已用时间、不预览子智能体输出，也不会在按下 Pi 的展开键时改变行为。舰队视图仍可用于查看实时进度和详细信息。

这是每次工具调用一个结果行，而非每次运行一个面板；调用标题保持不变。对同一运行独立的 status 调用仍是独立的历史对话记录。summary 模式既不合并这些调用，也不会改变跨扩展的顺序。如需"紧凑聊天加一个实时编辑器界面"，请参阅减少状态显示噪音。

mainWindowRenderer

{
  "mainWindowRenderer": {
    "horizontalSpacing": 0,
    "compactResultMaxLines": 4
  }
}

仅控制主聊天中的 subagent 调用/结果渲染器。它不改变子智能体执行、编排、舰队视图、产物、对话记录或面向模型的内容。

horizontalSpacing 是 0 到 4 之间的整数。默认保留当前间距。将其设为 0 可移除紧凑结果详情前以及调用行各部分之间的额外空格。

compactResultMaxLines 是正整数。它仅限制折叠后的富结果行，并在行被隐藏时添加展开提示。展开后的输出不受限制。

在 "summary" 模式下，工具结果形如：

✓ reviewer · completed

foregroundDetachShortcut

{ "foregroundDetachShortcut": "ctrl+b" }

可选地绑定一个快捷键，用于分离当前前台单子智能体运行而不终止它。运行中的前台卡片会在其实时详情提示旁显示所配置的快捷键。默认未设置，因此 pi-subagents 不会保留一个全局键。

Pi 默认将 Ctrl+B 绑定到编辑器光标左移。扩展的快捷键优先，Pi 会在启动时报告该冲突。若要在不出现警告的情况下保留该键，请在 ~/.pi/agent/keybindings.json 中覆盖编辑器动作：

{
  "tui.editor.cursorLeft": "left"
}

orcaProgressTabs（实验性）

{
  "orcaProgressTabs": {
    "enabled": true
  }
}

选择启用尽力而为的 Orca 观察者：为每个顶层子智能体调用创建一个 Orca 终端标签页，并镜像该运行的实时工具与助手进度。并行与链式的子智能体共享这一个标签页，在镜像日志中带有子智能体的段落标题。标签页标题使用持久的工作树本地序号（subagents · <run-label> · 1、... · 2，以此类推），因此不同的顶层调用不会重用相同的序号。对于同一工作树，orca terminal create 按该序号依次运行，使观察者标签页从左到右依次为 1、2、3。这不会取代 Pi 作为运行器：原生 Pi 子智能体仍保留相同的生命周期、状态、控制、产物与结果路径。外部 CLI 配置档也保留其现有运行器，并可镜像其 stdout/stderr。

该集成默认关闭，支持 macOS 与 Linux，在 Windows 上被禁用。启用后，pi-subagents 会在 PATH 上查找可执行的 orca，或使用 PI_SUBAGENT_ORCA_BINARY 中的可执行文件路径。若没有可执行文件、Orca 未运行、cwd 不是 Orca 管理的工作树，或 terminal create 失败，权威的子智能体仍正常运行。标签页创建被刻意做成尽力而为的，永远不会改变子智能体的结果。当可能时，被动的观察者清单也会写入 <worktree>/.pi/subagents/views/orca/ 下，以便未来的视图界面可以发现该 Orca 标签页，而无需让 Orca 成为权威。

将 enabled 设为 false（或移除该块）即可彻底关闭。在该状态下，pi-subagents 不会调用 orca，也不会创建任何 Orca 标签页。临时的镜像文件包含子智能体输出，在受支持的地方使用私有文件权限，并在运行结束后不久被移除。每个镜像文件上限为 1 MiB。当达到上限或流背压时，观察者停止接受进度并附加截断通知。查看器使用跨文件读取保持状态的解析器移除终端控制序列。完成时，查看器退出回到 Orca 终端的 shell 提示符；标签页及其终端滚动历史保持开启，直到用户关闭该标签页。一次成功完成且有已记录会话的原生 Pi 运行为 rm -- <exact-session-path> 输出一条安全引用的命令；失败、停止、超时以及无会话的运行不会显示该移除命令。

asyncByDefault

{ "asyncByDefault": false }

当请求省略 async 时，WorkflowScript 调用使用后台执行。将 asyncByDefault 设为 false 可恢复仍使用内部单次运行原语的工具启动的"默认前台"行为。除非启用了 forceTopLevelAsync，否则调用方仍可通过 async: false 强制前台。

defaultSubagentContext

{ "defaultSubagentContext": "fresh" }

为每个省略了 context 的子智能体启动设置 fresh 或 fork。该全局偏好会覆盖每个智能体级的 defaultContext。显式的 context: "fresh" 或 context: "fork" 仍优先。

对于 "fork"，该设置使用既有的隐式 fork 行为。当父会话文件或当前叶子节点不可用时，启动会以全新上下文开始。"fresh" 即使在所选智能体默认为 fork 时也会以全新上下文开始。已调度的运行仍会显式设置全新上下文。不支持 fork 上下文的运行器或提供方保留其既有的拒绝行为。

forkContext

{
  "forkContext": {
    "mode": "pruned",
    "model": "openai-codex/gpt-5.6-luna:max"
  }
}

控制已解析的 fork 启动如何准备继承的会话。默认 "full" 模式保留完整的 fork。"pruned" 模式在继承上下文能容纳本扩展所有的 64 KiB 会话预算时予以精确保留。溢出时，必需的 model 返回按稳定 item id 索引的简短 JSON 摘要。工具结果先溢出，然后是更旧的助手与工具上下文，仅在必要时才溢出用户文本。它适用于显式的 context: "fork"、全局与智能体的 fork 默认，以及当所选 profile 解析为 fork 时的 context: "profile"。

子智能体可见的溢出条目仅包含模型摘要与一个稳定的 { batchId, itemId } 恢复引用。原始正文及其摘要、源条目 id、标签、大小与工具元数据都会进入与之相邻的 0600 权限私有 sidecar 文件。本次发布不增加恢复命令，也不向子模型暴露该负载。

经过剪裁的 fork 保留常规的 parentSession 链接、子 cwd 对齐，以及 fork 思考块的清理（已签名的 Anthropic 思考块会被剥离；子智能体保留其请求的思考级别）。缺失模型或身份验证、摘要 JSON 不合法或不完整、预算溢出、恢复校验失败以及原始溢出泄漏都会在子派生之前终止启动。在剪裁失败后，扩展绝不会回退到完整 fork 或仅引用的上下文。

fleetView

{ "fleetView": false }

控制持久化、可导航的舰队视图。默认为 true。将其设为 false 可隐藏舰队视图，但不会禁用状态跟踪、完成通知、/subagents-fleet 或生命周期事件。

fleetViewPlacement

{ "fleetViewPlacement": "aboveEditor" }

将持久化的舰队视图放在 "belowEditor" 或 "aboveEditor"。默认为 belowEditor；非法值回退到 belowEditor。

fleetKeybindings

{
  "fleetKeybindings": {
    "pageUp": ["u"],
    "pageDown": ["d"],
    "selectFirst": ["g"],
    "selectLast": ["G"]
  }
}

仅自定义 /subagents-fleet 或舰队视图检查打开的完整舰队检查器。它不改变 Pi 的全局键绑定，也不影响紧凑的持久舰队视图。

每个动作接受一个非空键字符串数组。已配置的动作会替换其默认值。未设置的动作保留默认值：selectUp 为 up/k、selectDown 为 down/j、scrollUp 为 K、scrollDown 为 J、pageUp 为 pageUp、pageDown 为 pageDown、selectFirst 为 home、selectLast 为 end、toggleTools 为 x/X/ctrl+o、refresh 为 r/R、steer 为 s、stop 为 D、inspect 为 H、close 为 escape/ctrl+c/q。

提示模式保留其固定键。例如，即使舰队级关闭绑定被修改，Esc 仍会取消 steer 文本或 stop 确认。

asyncWidget

{ "asyncWidget": true }

控制活动后台运行的编辑器下方小部件。默认 true，即使启用了舰队视图也如此，因此重新加载后活动工作仍可见。将其设为 false 可隐藏该小部件，同时保留舰队视图。

waitTool

{ "waitTool": { "enabled": true, "defaultTimeoutMs": 120000 } }

defaultTimeoutMs 设置 bg_wait 调用省略 timeoutMs 时使用的阻塞窗口；显式的调用值优先，然后是此设置，再后是 30 分钟的兜底值。bg_wait 是唯一注册的等待工具。当窗口结束时，工具会返回一条非错误的 window_elapsed 结果，包含仍处于活动状态的工作标识，而该工作继续运行。将 enabled 设为 false 可让直接调用立即返回而不阻塞。默认为启用。你也可以设置 "waitTool": false；将 PI_SUBAGENT_WAIT_TOOL_ENABLED=false（或 0、off、disabled）覆盖一次进程的配置。实际生效的 enabled 和默认超时值会被显式传递给子运行时。无头的 agent_end 自动排空保留其自身的严格截止时间，若仍有未解决的工作则失败。非法配置或环境值会失败，而不会强制转换。

阻塞的 bg_wait({ id: "..." }) 会保持当前工具调用开启，直到该运行状态发生变化。默认情况下，它会在运行需要关注时返回。仅当等待至完成的流程需要穿越空闲或长时间思考的关注点时，使用 bg_wait({ stopOnAttention: false })；监督者/联系请求仍会停止等待。在长生命周期的交互式父会话中，bg_wait({ id: "...", nonBlocking: true }) 会先解析前缀一次，持久化精确的运行标识，立即返回一个订阅令牌，并在完成、失败、需要关注、对账失败或超时发生时唤醒该会话。对于没有原生完成通知的提供方、分离或其他后台工作，请使用它；普通的异步子智能体运行会以原生方式通知父会话，不需要等待订阅。已武装的订阅会出现在普通的 subagent({ action: "status" }) 输出中，且不计入活动的子智能体工作。

这与 waitTool.enabled=false 不同——后者会立即返回且不注册任何未来的唤醒。提供方条目仅对阻塞的舰队级等待可用；非阻塞订阅需要一个异步或已记忆的分离前台运行 id。

resultScanLogging

{ "resultScanLogging": "activity" }

控制慢速结果索引扫描的日志记录方式。默认 "activity"；有效值为 "all"、"activity" 和 "off"。

每当结果索引扫描超过慢速阈值（500ms）时，监视器会通过 console.error 记录 Subagent result scan inspected … scheduled …。在 "activity"（默认）下，它仅记录那些实际检查或调度了工作的扫描。使用 "all" 可记录每一次慢速扫描，包括在无挂起异步运行时检查零个文件的周期性健康重扫；或使用 "off" 完全静默慢速扫描日志。"off" 不会禁用结果交付或监视器本身，只会禁用其慢速扫描日志行。

forceTopLevelAsync

{ "forceTopLevelAsync": true }

将深度 0 的内部 single、parallel 与 chain 运行强制为后台模式，并通过强制 clarify: false 绕过启动 UI。嵌套调用保留各自继承的设置。

timeoutMs

{ "timeoutMs": 3600000 }

子智能体运行的全局默认运行时截止时间（毫秒）。在没有任何调用级 timeoutMs/maxRuntimeMs 时，它会取代前台启动（single、parallel、chain 与 workflowScript）以及纯单智能体异步运行的内置 30 分钟兜底。对于单智能体启动，所选智能体 frontmatter 的 timeoutMs 仍优先。这只会改变默认值。到期该运行级截止时间是终态，不会触发 fallbackModels；只有在截止时间之前报告的提供方/模型失败才能回退。

当前台编排或纯异步单智能体运行需要比 30 分钟更长的默认值时使用它。它不会设置异步复合顶层截止时间，也不会替代异步扇出子截止时间。

复合异步运行（异步链、并行任务与脚本化工作流）按设计在顶层保持无界。其运行器子节点各自受其智能体或运行器默认值约束，因此该值不会为它们设定上限。必须是正整数且不大于 2147483647（Node.js 计时器所能处理的最大延迟，约为 24.8 天）；非法或超出范围的值会被忽略，并应用内置默认值。

toolTimeoutMs

{ "toolTimeoutMs": 600000 }

可选的硬性单次工具调用截止时间（毫秒）。配置后，发出 tool_execution_start 但未发出 tool_execution_end 的子智能体会以 timedOut: true 和工具特定的错误终止。实际生效的值按子智能体分别解析：显式 subagent 调用值，然后是智能体 frontmatter，再后是此配置值，最后是 PI_SUBAGENT_TOOL_TIMEOUT_MS。

在没有配置值的情况下，Pi 仍会对已知快速的内置工具应用 5 分钟硬超时：read、grep、find、ls、edit、write 与 structured_output。长时间运行的工具（如 bash、自定义工具与 MCP 工具）没有硬性默认值。它们在 activeNoticeAfterMs 后收到常规的开启工具关注通知，并仍受运行级截止时间约束。

工具计时器按活动分别记录每个 toolCallId，永不延长运行级截止时间：当剩余的运行预算更短时，常规的运行级超时优先。contact_supervisor、intercom 与 bg_wait 被豁免，因为它们存在的合法目的可能就是等待人工、监督者或后台运行。仅在防止死锁时使用硬性工具超时；超时到期并不是"安全变更"的边界。配置值必须为不大于 2147483647 的正整数；非法或超出范围的值会以可见错误拒绝，而不是被静默忽略。

checkpointBeforeDeadlineMs

{ "checkpointBeforeDeadlineMs": 300000 }

异步单智能体 checkpointBeforeDeadlineMs 启动选项的全局默认值。当异步单智能体运行存在运行级截止时间时，运行器会在该截止时间前该毫秒数向子智能体发起尽力而为的"检查点并停止"引导：完成当前工具调用，报告变更的文件、构建/测试状态、剩余工作以及提交/PR 状态，并不再开启新工作。该引导使用子智能体下一个工具边界处的常规引导生命周期，因此其接收（请求、路由、已送达）在运行状态和事件中可见，并且若子智能体未停止，常规的 timeoutMs 终止仍适用。

显式 subagent 调用值优先于此默认值。请选择一个不少于子智能体最长预期工具调用时长的值；引导无法落在其内部。当截止时间前剩下不到 1 秒的运行时间时，检查点会被解除，并表现得如同该选项不存在。全局配置值必须是不大于 2147483647 的正整数；非法值会让配置加载失败，而不是悄悄禁用检查点。

globalConcurrencyLimit

{ "globalConcurrencyLimit": 20 }

限制一次运行内同时活动的子智能体数量，包括持久的旧版多子智能体运行以及通过 runs.run/runs.all 启动的 workflowScript。排队的工作流子节点保留其稳定键，并在某个运行的兄弟节点释放容量后开始。默认为 20。

内联或文件支持的顶层工作流调用可设置一个正的安全整数 globalConcurrencyLimit，以在该工作流中覆盖此值。该覆盖仅作用于工作流自身，不会转发到子调用。

maxSubagentSpawnsPerSession

{ "maxSubagentSpawnsPerSession": 100 }

可选地限制一个父会话中子智能体启动的总数，包括已完成和失败的子智能体、并行任务计数、静态链式步骤以及有界的动态扇出子节点。默认无限制。将该值设为 0 可禁用已配置的限额。PI_SUBAGENT_MAX_SPAWNS_PER_SESSION 为该进程覆盖配置，并遵循相同的"正数限额/零为无限制"语义。

subagent({ action: "status" })、舰队状态与 subagent({ action: "doctor" }) 会暴露已使用、实际限额、剩余容量、授权及该预算的剩余授权额度。用户可在所有子节点安定后在原生根交互式父会话中显式调用 subagent({ action: "grant-spawn-budget", additional: 10 }) 并确认原生提示。授权是叠加的：它们永不抹除累计用量，对于无限制会话及子/无头调用方会被拒绝，且授权总容量不能超过原始配置限额。压缩仍是同一逻辑父会话的一部分，不会重置用量或授权；启动一个新的父会话则会。

maxSubagentSpawnsPerRun

{ "maxSubagentSpawnsPerRun": 64 }

限制一个顶层运行树中的累计逻辑子智能体接纳数。默认为 64。当 PI_SUBAGENT_MAX_SPAWNS_PER_RUN 为正整数时，会覆盖配置。非法、零或缺失的值会回退到已配置的正数值或 64。

内联或文件支持的顶层工作流调用可设置一个正的安全整数 maxSubagentSpawnsPerRun；它会在该工作流中覆盖环境变量和配置。继承的嵌套预算仍为权威，且覆盖不会转发到子调用。

预算统计：单次启动、展开后的 tasks/count、静态链式步骤与并行组、实际动态 expand 条目、追加的链式步骤、工作流子节点以及嵌套子调用。静态和已物化的动态组以原子方式接纳。启动重试、模型回退以及保留子节点的恢复复用原有的逻辑子智能体声明。声明永不释放或退还。该限额独立于会话级累计派生预算与 globalConcurrencyLimit。

maxActiveAsyncRunsPerSession

{ "maxActiveAsyncRunsPerSession": 4 }

可选地限制一个父会话所拥有的、同时活动的顶层异步运行。未设置或 0 保留现有的无限制行为。正整数会在异步 single、parallel、chain 或 workflow 创建运行产物或启动子节点之前预留一个槽位。前台运行与嵌套/工作流子节点不预留其他槽位。

排队、运行中、暂停和需要关注的运行保留容量。由运行器支持的槽位仅在终态逻辑状态以及来自 #1030 的匹配观察进程终止证明之后释放。缺失、格式错误或未知的清理证明会保留该槽位。终态异步工作流在其控制器消失且每个已启动子节点都被记账后释放：已等待的前台子节点由工作流结算覆盖，而真正的后台子节点仍需观察进程终止证明。恢复会转移源槽位，无需再次扣费。解散与历史清理不会释放容量。

当运行器已消失但进程清理证明仍未知时，请在 capacity.abandonedSlotReleaseAfterMs 下配置一个有界的策略回收：

{ "maxActiveAsyncRunsPerSession": 4, "capacity": { "abandonedSlotReleaseAfterMs": 1200000 } }

默认为 1200000 毫秒（20 分钟）。该策略仅释放那些运行器 PID 已死亡且最后活动时间早于该阈值的失败终态运行。存活或未知的 PID、非失败的终态、最近的运行或缺失的活动时间戳都会保留该槽位。将该值设为 false 可保持严格保留。合法的配置时长范围为 5 分钟至 24 小时。策略释放会报告为 abandoned-timeout，且 processProof: unknown；它不是观察到的进程终止证明，因此可能在孤立子节点仍然存在时回收容量。

该限额约束当前顶层异步负载。它与累计的 maxSubagentSpawnsPerSession、maxSubagentSpawnsPerRun 以及 globalConcurrencyLimit 相互独立。

subagent({ action: "status" })、舰队状态与 subagent({ action: "doctor" }) 会暴露已使用、实际限额与剩余活动容量。当静态链与并行调用所声明的容量无法容纳时，它们会在创建运行产物或启动部分工作之前失败。后续的重试或无界动态工作并不由该预检保证。

scheduledRuns

{ "scheduledRuns": { "enabled": false, "maxPending": 20 } }

持久化的调度默认启用，并按项目存储在 .pi/subagents/schedules/<id>/ 下。用法见 missions.md。

设置 storeRoot 可将持久化调度保存在项目仓库之外。它必须是绝对路径或 ~/ 路径，会从用户主目录展开。每个项目都按其已解析工作目录的哈希存储，因此项目之间不共享调度。

{ "scheduledRuns": { "storeRoot": "~/.local/share/pi-subagents/schedules" } }

省略 storeRoot 时，调度保留在 <cwd>/.pi/subagents/schedules。

parallel

{
  "parallel": {
    "maxTasks": 12,
    "concurrency": 6
  }
}

maxTasks 默认为 8；concurrency 默认为 4。每次调用的 concurrency 优先。

defaultSessionDir

{ "defaultSessionDir": "~/.pi/agent/sessions/subagent/" }

会话目录优先级为：params.sessionDir，然后是 config.defaultSessionDir，再后是从父会话派生的目录。会话始终启用。

singleRunOutputBaseDir

{ "singleRunOutputBaseDir": "~/.pi/subagent-outputs" }

将单智能体 /run 调用的相对 output 路径路由到该目录下。每次调用或智能体的绝对输出路径仍按原样使用。未设置时，相对单次运行输出会进入该运行的产物输出目录，而非项目根目录。

maxSubagentDepth

{ "maxSubagentDepth": 1 }

在启动子节点的运行时配置未继承更严格限制时，控制嵌套委派。每个智能体的 maxSubagentDepth 可收紧其子运行的限制，但不能放宽已继承的更严格限制。这同样适用于显式声明 tools: subagent 或 allowNestedSubagents: true 的子智能体；达到上限时，执行扇出会被阻止，而非悄悄隐藏嵌套工作。

PI_SUBAGENT_PI_BINARY

export PI_SUBAGENT_PI_BINARY=/path/to/pi-or-wrapper

覆盖 pi-subagents 为项目面板和配置档模型探测派生的 pi 命令。在受支持的 Bun 编译的 Pi 宿主页上，它也会选择分离的后台宿主可执行文件。该可执行文件必须接受 Pi 的 bootstrap 参数，并提供其兼容的嵌入式 SDK 与相邻的发布资源；裸的 Bun 不能替代它。空值或仅空白字符的值会被忽略。启动失败时不会用另一个运行时重试。

前台子智能体仍是父进程内部的会话。Npm 后台子智能体保留其 Node 运行器与宿主页包的 peer 别名；该变量不会将 npm Pi 变成二进制支持的运行器。官方测试目标见独立后台执行。

intercomBridge

{
  "intercomBridge": {
    "mode": "always",
    "instructionFile": "./intercom-bridge.md",
    "resultDelivery": true
  }
}

控制子智能体是否接收运行时协调指令，以及是否在需要时将 contact_supervisor 自动加入其工具白名单。

字段：

• mode：默认 always；使用 fork-only 仅向 fork 的运行注入；或使用 off 禁用桥接。
• instructionFile：可选的 Markdown 模板，替换默认桥接指令。{orchestratorTarget} 会被父会话目标插值。相对路径相对于 ~/.pi/agent/extensions/subagent/ 解析。默认模板不命名会话，因为 contact_supervisor 会从子运行时配置解析它；命名会话的模板会将 launchContractDigest 绑定到父会话，启动契约预检需要 orchestratorTarget 匹配。
• resultDelivery：默认 false；仅在外部监听器消费 subagent:result-intercom 并确认分组的完成负载时设为 true。这是可选的外部结果交付，而非原生监督者消息。启用的交付会等待确认并报告确认失败。它不改变监督者询问或进度更新。

桥接激活需要一个可寻目标的当前父会话 id，pi-subagents 会自动将其传递给子智能体。原生监督者消息不需要外部 pi-intercom 安装或每智能体扩展白名单：子智能体使用 contact_supervisor，父智能体使用 subagent_supervisor 进行检查或回复。当智能体显式请求提供该工具的提供方时，仍可使用外部 intercom 工具。

默认注入的指引告诉子智能体在阻塞或需要决策时使用 reason: "need_decision" 调用 contact_supervisor；仅在有意义的阻塞/进度更新时使用 reason: "progress_update"；避免常规的完成交接。

worktreeBaseDir

{ "worktreeBaseDir": "/Users/matt/code/.worktrees/pi-subagents" }

为 worktree: true 运行设置原生专用根目录。相对路径相对于仓库根目录解析，~/... 展开为主目录；在使用原生分配且两者都未设置时，专用根目录默认为 {dirname(repoRoot)}/worktrees，即仓库检出旁边的 worktrees 目录。

每个原生工作树叶子为 {dedicatedRoot}/{projectName}/pi-worktree-{runId}-{index}，其中 {projectName} 是仓库目录名（basename(repoRoot)），{runId} 标识运行，{index} 计算该运行内的子节点数。worktreeBaseDir 与 PI_SUBAGENTS_WORKTREE_DIR 仅覆盖专用根目录；其下的 {projectName}/pi-worktree-{runId}-{index} 嵌套在原生分配时始终生效。不安全的位置会被拒绝而不会创建：当专用根目录位于仓库检出或 Pi 扩展目录内部，或工作树将直接落在仓库父目录下时，设置会失败。

worktreeProvider

{ "worktreeProvider": "auto", "worktreeBranchPrefix": "pi-subagents/" }

选择托管的工作树分配器：auto（默认）在 Worktrunk 的机器可读接口可用时使用它，否则回退到 Pi 的原生 Git 工作树；native 始终使用 Pi 的 Git 实现；worktrunk 在 Worktrunk 不可用或不兼容时失败闭合。在 Windows 上，pi-subagents 通过 git wt 调用 Worktrunk，以避免与 Windows Terminal 的冲突别名 wt.exe。已配置的 worktreeBaseDir（或 PI_SUBAGENTS_WORKTREE_DIR）会选择原生分配，且不能与显式的 worktrunk 组合。

worktreeBranchPrefix 会被规范化为 Git ref 命名空间，默认为 pi-subagents/。分支名包含可读的任务/泳道标识以及运行与扇出索引。Pi 继续负责设置钩子、启动、交接/差异证据、恢复与清理；Worktrunk 仅用于分配和回报工作树路径。

将 worktree 设为 true 可让托管工作树隔离成为省略逐调用 worktree 标志的启动的默认值。每次调用的值仍优先。

worktreeSetupHook

{
  "worktreeSetupHook": "./scripts/setup-worktree.mjs",
  "worktreeSetupHookTimeoutMs": 45000
}

钩子为每个创建的工作树运行一次。路径必须是绝对路径、~/... 或仓库相对路径；裸的命令名会被拒绝。

设置命令的等待是非阻塞的，可通过现有的运行控制取消。现有的运行截止时间与钩子超时仍然适用；没有新的设置超时或配置。

设置命令（包括 Git 钩子）必须有限，且在报告成功前等待所有子进程；不要启动后台服务。退出 0、自然管道关闭、完整的有界输出以及合法的 JSON/路径元数据是启动与清理的可信完成，而非观察到的进程树证明。违反上述要求不受支持：不能保证防止在存在未公开的活动子进程时删除工作树。不提供额外的 Windows 隔离保证。

stdin 是一个 JSON 对象，包含 repoRoot、worktreePath、agentCwd、branch、index、runId 与 baseCommit。stdout 必须是一个 JSON 对象，例如：

{ "syntheticPaths": [".venv", ".env.local"] }

syntheticPaths 必须相对于工作树根目录。它们会在差异捕获前被移除，以免辅助文件污染补丁。受版本控制的文件永远不会被排除；将受版本控制的路径标记为合成会导致设置失败。默认超时为 30000 毫秒。

missions

{
  "missions": {
    "enabled": true,
    "globalIndex": true,
    "retainTerminal": 200
  }
}

对于带任务的普通启动，自动任务记录默认启用。对于有意的临时工作，请使用逐启动的 mission: false，或将 enabled 设为 false 全局禁用自动创建；显式的任务记录动作与 missionId/mission 启动字段仍然有效。

• 任务记录默认存放在 Pi 智能体目录下按项目键控的子目录（~/.pi/agent/missions/projects/<project-hash>/）。这能保持项目工作树整洁。
• directory 可以是绝对路径、~/...，或项目相对路径。将其设为 .pi/subagents/missions 以选择项目作用域记录。
• retainTerminal 是正整数计数（默认 200）；剪枝只会移除最旧的已完成、失败或已取消的记录及其指针，永远不会移除计划的、活动的、等待的、需要决策的或损坏的记录。
• 用户全局索引仅包含指针；在全局列出时，缺失记录的指针会自我修复。将 globalIndex 设为 false 可禁用写入，或设置 globalIndexDir 以重定向它。

authorityPolicy

{
  "authorityPolicy": {
    "discardWorktree": "confirm",
    "destructiveCleanup": "confirm",
    "spawnBudgetGrant": "confirm",
    "scheduleCreate": "auto",
    "stopRun": "auto",
    "steerRun": "auto"
  }
}

每个固定动作解析为 "auto"、"confirm" 或 "forbid"。这有意是一个小巧的动作映射，而非通用策略语言。需要确认的控制动作在无交互 UI 时会失败闭合。

artifactDir

{ "artifactDir": "session" }

控制子智能体产物文件（输入、输出、对话记录、元数据）的存放位置：

• "project"：写入 <cwd>/.pi/subagents/artifacts/。
• "session"（默认）：将产物存储在 Pi 的会话目录下（~/.pi/agent/sessions/<session>/subagent-artifacts/），保持工作目录整洁。当不存在会话文件时，回退到操作系统临时目录。
• "temp"：使用操作系统临时目录。

此偏好还控制脚本化链式调用使用的默认工作流产物目录。"project" 使用 <cwd>/.pi/subagents/chain-runs/；该目录保留其旧版名称以保证兼容性。默认的 "session" 和 "temp" 使用用户作用域的临时工作流产物目录。

"session" 选项使用与 cleanupAllArtifactDirs 已按年龄扫描清理的同一目录，因此产物仍会被自动清理。临时工作流产物目录在 24 小时后单独清理。

当项目作用域的启动从 npm 包目录运行时，若包设置可能将 .pi/subagents/ 包含在已发布的包中，pi-subagents 会发出警告。请将 .pi/subagents/ 添加到 .npmignore（或在不存在 .npmignore 时添加到 .gitignore），使用不包含 .pi/subagents/ 的 files 白名单，或选择 "session" 或 "temp"。

completionBatch

{
  "completionBatch": {
    "enabled": true,
    "debounceMs": 150,
    "maxWaitMs": 1000,
    "stragglerDebounceMs": 75,
    "stragglerMaxWaitMs": 400,
    "stragglerWindowMs": 2000
  }
}

控制异步完成通知的智能批处理。当多个后台子智能体在短时间内完成时，它们的成功完成会被短暂保留，并以一条安静的分组完成一次性送达，而不是各自分别完成。

• 一个硬性的 maxWaitMs 上限（从该组中第一次完成起算）保证不会被无限保留。
• 在分组的 stragglerWindowMs 之内到达的后完成兄弟节点会加入一个更短的、由 stragglerDebounceMs 和 stragglerMaxWaitMs 控制的落后组。
• 失败和暂停的完成会绕过批处理并立即触发，先刷新任何已保留的成功，因此失败与需要关注的信号永远不会被延迟。
• 将 enabled 设为 false 可恢复原来"一次完成一条通知"的行为。更改会在下次会话开始时生效。

permissions

原生子智能体工具权限规则。见 watchdog.md。

PI_SUBAGENT_FS_RETRY_MAX_TOTAL_MS

限制一次重试的文件系统操作可能休眠的总时间（毫秒）。仅环境变量；没有配置键。

原子化的状态和结果写入会在 EACCES、EBUSY 与 EPERM 上重试，在 Windows 上这些通常是扫描器或某个同级进程暂时持有 rename 的目标。重试阶梯总共休眠约 7.9 秒，并且是同步休眠——Atomics.wait 会将调用线程停顿而不是自旋。

对于 CLI 而言，这是一种正确的取舍。但对于把 pi-subagents 进程内加载并在其事件循环上运行这些写入器的长生命周期进程来说，它是一种错误的取舍：一次争用的 rename 会让其所服务的所有东西停顿整整一个阶梯时长，而且由于线程是被停顿而非忙碌的，表现为一个看起来无响应且 CPU 占用 0% 的进程。宽扇出会使单个 status.json 上的争用变得很可能。

请设置此项以约束该停顿。阶梯保留其尝试次数，仅缩短休眠，因为 run-fanout-budget 和任务记录状态锁定使用阶梯长度作为其尝试预算：

PI_SUBAGENT_FS_RETRY_MAX_TOTAL_MS=1000

默认未设置，因此除非主动启用，否则行为保持不变。主动启用会以"对锁等待的容忍度"换取"响应性"：被裁剪到 0 的条目会立即返回，因此以前会被等待掉的争用会更快地暴露为错误。非法或非负整数之外的值会失败，而不是被强制转换。