Agent 兼容字段与 Hooks
迁移 Claude Code frontmatter，并核对模式映射、回合限制、MCP 和 Hook 作用域。
Qwen Code 接受一组 Claude Code 兼容字段，但字段能解析不代表所有行为与原产品相同。官方当前列出的兼容基准是 Claude Code 2.1.168；不要据此推断其他版本的全部字段都支持。
可用字段
| 字段 | 作用与优先级 |
|---|---|
permissionMode | 解析为 approvalMode；两者都有时显式 approvalMode 优先 |
maxTurns | 正整数回合上限，运行时进入 runConfig.max_turns；顶层值优先 |
color | 显示颜色；兼容保留旧 auto 值 |
mcpServers | 与会话服务集合合并，同名服务采用 agent 定义 |
hooks | 本次 agent 调用期间生效的 Hook 定义 |
颜色接受 red、blue、green、yellow、purple、orange、pink、cyan。无效的兼容可选字段通常会被丢弃；不要把这种宽松解析推广到原生 approvalMode 等其他字段。MCP 无效条目按键丢弃并警告，不会因此拒绝整个 agent。
permissionMode 的确切映射
| 兼容值 | Qwen approvalMode |
|---|---|
default | default |
plan | plan |
acceptEdits | auto-edit |
auto | auto-edit |
bypassPermissions | yolo |
dontAsk | default |
特别注意兼容字段 permissionMode: auto 映射为 auto-edit，并不是 Qwen 的 Auto 分类器模式。dontAsk 被映射到 default，也不能当作与 Claude Code 的拒绝询问行为完全等价。映射之后仍受父会话模式影响。
带预算的审查角色
---
name: bounded-reviewer
description: Review the requested changes and report evidenced defects.
permissionMode: plan
maxTurns: 30
color: cyan
tools:
- read_file
- grep_search
- glob
---
Prioritize verified defects and explain their trigger and impact.保存时会移除旧的嵌套 runConfig.max_turns，以免保留两份冲突来源。不要仅靠颜色或角色描述判断实际工具限制。
Hook 只观察本次调用
Agent frontmatter Hooks 使用与 settings Hooks 相同的事件和 matcher 结构，注册到调用生命周期，释放时移除。它们不接收父级、兄弟或嵌套子级事件。
生命周期使用 SubagentStart 与 SubagentStop；Stop 不是 SubagentStop 的别名。需要观察整个会话的行为，应使用全局 settings Hooks；会话级 Skill / function Hooks 保留其既有继承规则。
项目 agent 的 Hooks 在不可信工作区会跳过，并在每次事件前重新检查来源工作区信任。迁移时应验证事件确实来自预期角色，而不是仅确认配置可解析。
尚不能按兼容字段承诺的功能
官方该章把 effort、skills、initialPrompt、memory、isolation 列为后续实现内容。本页不把这些 Claude Code frontmatter 字段当作可用承诺；Agent 调用本身的 worktree 隔离参数是另一层接口，见后台与工作目录。