---
title: "SubagentStart 只能给孩子注入上下文，continue:false 拦不住启动"
summary: "matcher 对 agent_type。Review / Compact 等内部子代理不跑。真要停，用 SubagentStop。"
category: hooks
level: advanced
surfaces: [cli]
tags: ["hooks", "SubagentStart", "子代理"]
canonical: /tips/subagent-start-hook/
---

# SubagentStart 只能给孩子注入上下文，continue:false 拦不住启动

matcher 对 agent_type。Review / Compact 等内部子代理不跑。真要停，用 SubagentStop。

线程 spawn 出来的子代理**不会**再跑父级 `SessionStart`。启动前那一次是 `SubagentStart`，发生在孩子发出第一轮模型请求之前。

`matcher` 对 `agent_type`，也就是 `spawn_agent` 用的类型；没写类型时落到默认 agent。给审查者注入约定：

```toml
[[hooks.SubagentStart]]
matcher = "reviewer"

[[hooks.SubagentStart.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/subagent_start.py"'
timeout = 10
statusMessage = "Loading reviewer context"
```

stdout 纯文本会变成孩子的额外 developer 上下文。JSON 形状：

```json
{
  "hookSpecificOutput": {
    "hookEventName": "SubagentStart",
    "additionalContext": "Review the repository test conventions first."
  }
}
```

`continue: false` 只为兼容而解析，**不会**阻止子代理启动。想在结束时拦住后续续写，用 `SubagentStop`；任意匹配钩子返回 `continue: false` 会压过其它 Stop 钩子的继续决定。

不会跑 `SubagentStart` 的路径：Review、Compact、MemoryConsolidation 这类内部/系统子代理。不要给它们写 matcher。

新钩子先 `/hooks` 信任。自定义 agent 若改了 `model` / `sandbox_mode`，孩子会重建配置；未写入配置层的信任可能被丢掉，钩子静默不跑，子代理本身仍会完成。

## 来源

- [OpenAI · Hooks](https://developers.openai.com/codex/hooks)