> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trytrellis.app/llms.txt
> Use this file to discover all available pages before exploring further.

# v0.5.6

> 2026-05-07

Codex `multi_agent_v2` 的两个 prompt-layer 补丁。`AGENTS.md` 新增 `spawn_agent` 调用必须传 `fork_turns="none"` 的说明（[`#240`](https://github.com/mindfold-ai/Trellis/issues/240) follow-up），以及收到 `wait` completion 通知后的确定性收口算法（[`#241`](https://github.com/mindfold-ai/Trellis/issues/241)）。无新增 migration。

## Bug Fixes

### `fork_turns="none"` 必填（#240 follow-up）

[v0.5.5](/zh/changelog/v0.5.5) 移除了 `SessionStart` 注入路径。[Marsor707 在 `#240` 下的本地验证评论](https://github.com/mindfold-ai/Trellis/issues/240#issuecomment-4393264022)指出还有第二条路径：

> Without `fork_turns="none"`, the child can see the parent's own `spawn_agent(...)` records and then apply the Trellis/AGENTS "wait for spawned subagents" rule to itself, causing a self-wait such as `wait_agent({"timeout_ms":480000})`.

Codex 默认 `fork_turns="all"`，子代理继承父对话历史，包括之前的 `spawn_agent` 工具调用记录。子代理读到这些记录后，把"等待派发的子代理"这条规则套到**自己**头上，对自己 `wait_agent` —— 自挂 8 分钟。这条路径独立于 SessionStart 注入 bug 存在。

`packages/cli/src/templates/markdown/agents.md` 新增 `### Codex-only — \`spawn\_agent\` parameters`段落，要求主会话调`spawn\_agent`时**必须传**`fork\_turns="none"`。Prompt-layer 修复 —— Trellis 不拦截`spawn\_agent\` 工具本身。

### 多子代理收口算法（[`#241`](https://github.com/mindfold-ai/Trellis/issues/241)）

`AGENTS.md` 原有规则：

> ALWAYS wait for every spawned subagent to reach a terminal status before yielding...

太模糊。复现场景：父代理派发两个 `trellis-research` 子代理，两个都 completed 并写入 `{task_dir}/research/*.md`，父代理收到 `completed` 通知后**仍然继续调 `wait_agent`** 而不是读取产物并关闭。用户侧表现：似乎在卡住。

`packages/cli/src/templates/markdown/agents.md` 新增 `### Codex-only — multi-subagent close-loop` 段落，写明 issue 里建议的确定性算法：

1. 维护 `expected_agents` 集合。
2. 每次 `wait` 返回更新后：调 `list_agents` 核对状态 → 对所有已终态 agent 校验产物 → `close_agent` → 从集合中移除。
3. 仅当 `expected_agents` 还有 running agent 时才继续 `wait`。
4. 永远不要对已 reported `completed` 的 agent 再 `wait`。

两段都是 prompt-layer 修复 —— 没改脚本、钩子、configurator 行为。

## Upgrade

```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```

`AGENTS.md` 在 `## Subagents` 段下新增两个子段。非 Codex 平台看到 `Codex-only` 标签可跳过。