Agent 兼容字段与 Hooks

迁移 Claude Code frontmatter，并核对模式映射、回合限制、MCP 和 Hook 作用域。

This page has not been translated into English yet. The original Chinese version is shown below.

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 隔离参数是另一层接口，见后台与工作目录。