> ## 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.1

> 2026-05-06

修 Codex `SessionStart` 注入引发的子代理递归（[#234](https://github.com/mindfold-ai/Trellis/issues/234)）和 Cursor agent `description` 字段不显示。无新增 migration。

## Bug Fixes

### Codex `multi_agent_v2`：修复 `SessionStart` 的 dispatch 的 hook 误导 sub-agent 的问题

`packages/cli/src/templates/codex/hooks/session-start.py` 在任务 READY 状态时会注入"主会话应当 dispatch `trellis-implement`"的指引。`multi_agent_v2` 模式下 Codex 在每个被 spawn 的会话里都跑一次 `SessionStart`，这句指引也被注入到了刚派出去的 `trellis-implement` 子代理。子代理照执行又派了一个 `trellis-implement`，外层 sub-agent 一直 `running`，主会话 `wait_agent` 超时。

Codex `SessionStart` 的 stdin 当前没有 agent identity 字段（[`openai/codex#16226`](https://github.com/openai/codex/issues/16226)），hook 没法直接过滤 sub-agent 会话。这版改在 prompt 层兜：

| 文件                                                         | 改动                                                                                    |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `codex/agents/trellis-implement.toml`、`trellis-check.toml` | `developer_instructions` 开头加一句"不要 dispatch `trellis-implement` / `trellis-check`"     |
| `codex/hooks/session-start.py`                             | dispatch 话术后加一句"如果你是 sub-agent 在读这段，忽略"，READY-state block 和 `<guidelines>` block 各加一处 |

### `shared-hooks/session-start.py`：同上

`packages/cli/src/templates/shared-hooks/session-start.py` 里有相同的 dispatch 话术，被 Claude Code / Cursor / Gemini CLI / Qoder / CodeBuddy / Factory Droid / Kiro 复用。这些平台还没人报递归现象，但触发条件和 Codex 完全一样，跟 Codex 同类型处理。

### Cursor：agent frontmatter `description` 改成单行字面量

`packages/cli/src/templates/cursor/agents/trellis-{research,implement,check}.md` 之前用 YAML 块标量：

```yaml theme={null}
description: |
  Trellis research agent. Use this exact agent ...
```

Cursor 的 agent 解析器只读单行 `description: ...`，块标量会被静默丢弃，UI 上 Description 字段是空的。改成单行字面量，正文不动。

## Upgrade

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