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

> 2026-05-07

修 Codex sub-agent 套娃派发的结构性 bug（[`#240`](https://github.com/mindfold-ai/Trellis/issues/240)、[`#242`](https://github.com/mindfold-ai/Trellis/issues/242)）。直接移除 Codex 的 `SessionStart` 钩子，改由 `UserPromptSubmit` 在首轮 `no_task` 时引导 AI 调一次 `trellis-start` skill 加载工作流上下文。无新增 migration。

## Bug Fixes

### Codex sub-agent 套娃派发

Codex 给每个 spawn 出来的 sub-agent session 都触发一次 `SessionStart`，且 hook 输入里**没有** `agent_id` / `agent_type` 字段（参考 [`openai/codex#16226`](https://github.com/openai/codex/issues/16226)）。所以 `packages/cli/src/templates/codex/hooks/session-start.py` 里的 dispatch 指令也被注入到 sub-agent 的 session-start payload，sub-agent 看到 "Next required action: dispatch `trellis-implement`"，误以为自己是主会话，又派了一个 `trellis-implement` 出去。然后那个 sub-agent 接着干一样的事。

0.5.4 的补丁（[`#237`](https://github.com/mindfold-ai/Trellis/issues/237)）在同一段 prompt 里加了 `Sub-agent self-exemption:` 豁免说明，但它跟 dispatch 指令并排在同一段。LLM 持续优先选择命令式指令，忽略条件豁免。

结构性修法：

* 从 `packages/cli/src/templates/codex/hooks.json` 删除 `SessionStart` 条目 —— 沉重的 session-start payload 不再到达任何 session，sub-agent 和主会话都不会。
* `packages/cli/src/templates/shared-hooks/inject-workflow-state.py`（`UserPromptSubmit`）在 `no_task` 状态下新增 `<trellis-bootstrap>` 注入，告诉 AI 调一次 `$trellis-start`。notice 里带有显式的 sub-agent 豁免说明（sub-agent 先读到既有的 `<sub-agent-notice>`，就会忽略下方所有内容）。
* `packages/cli/src/configurators/codex.ts` 给 Codex 写 `.agents/skills/trellis-start/SKILL.md`。skill 内容直接复用现有的 `common/commands/start.md` 模板，加 skill 前缀 frontmatter。

Sub-agent session 现在只会看到 per-turn 面包屑里的 `<sub-agent-notice>`。新注入里**任何位置**都没有命令式 "必须 dispatch" 文本，递归路径从源头消失。

其他 agent-capable 平台（Claude Code、Cursor、OpenCode、Kiro 等）的 `SessionStart` 钩子保持不变 —— 只有 Codex 受 `openai/codex#16226` 影响。

## Upgrade

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

Codex 用户会拿到新的 `.agents/skills/trellis-start/SKILL.md` 文件，以及一份不含 `SessionStart` wiring 的 `hooks.json`。无需任何 flag。