SendMessage 是 Claude Code 子代理（subagent）系统中用于消息传递的核心机制。它允许主代理（parent agent）向指定的子代理发送消息，也支持子代理之间进行通信。理解 SendMessage 是掌握子代理协作模式的基础。
to 参数用于指定消息的接收者。它可以是一个具体的子代理名称（如 "code_reviewer"），也可以是一个特殊标识符。当主代理需要向特定子代理分配任务时，通过 to 参数精确指定目标。如果 to 参数指向一个不存在的子代理，系统会返回投递失败的错误信息。在实际应用中，子代理名称通常在系统架构中预先定义，主代理根据任务类型选择对应的子代理进行通信。
summary 参数提供消息的简短预览，主要用于用户界面显示。当主代理向子代理发送消息时，summary 内容会展示在 UI 的消息列表中，让用户可以快速了解消息的主题和用途，而无需查看完整的消息内容。summary 应该保持简洁明了，通常不超过一句话，准确概括消息的核心意图。例如 "请求代码审查：处理 login 模块" 或 "通知：数据采集任务已完成"。
message 参数是消息的实际内容，可以包含文本字符串或者结构化的 JSON 数据。文本消息适合传递简单的指令或信息；JSON 消息则适用于需要结构化数据的场景，协议消息通常使用 JSON 格式，其中 type 字段标识消息类型。消息内容的大小在实际系统中有一定限制，过大的消息需要分片发送或通过引用传递。
主代理调用 SendMessage 方法，传入 to（目标子代理名称）、summary（消息预览）和 message（消息内容）。消息进入投递队列，系统根据 to 参数查找目标子代理。消息在目标子代理的下一个处理轮次中被投递。子代理处理消息并可选地通过 SendMessage 回复。主代理收到回复后继续进行后续流程。整个过程是异步进行的，主代理和子代理各自独立运行在自己的执行上下文中。
SendMessage 支持多种消息类型，不同类型的消息适用于不同的通信场景。理解消息类型的分类和用途，有助于设计合理的子代理通信架构。
文本消息是最基础的消息类型，message 参数直接包含文本字符串。文本消息适用于传递简单的指令、问题或信息。接收方子代理需要对文本进行解析，理解其中的含义并做出响应。文本消息的优势在于简单直观，易于调试；缺点是没有固定的结构，解析依赖于双方约定的格式。在简单的协作场景中，文本消息足够满足需求。
JSON 协议消息使用结构化的 JSON 格式作为消息内容。相比文本消息，JSON 消息具有明确的数据结构，便于程序解析和处理。JSON 消息通常包含 type 字段用于标识消息类型，以及其他字段携带具体数据。协议消息要求双方严格遵守约定的数据格式，这种约束虽然增加了定义成本，但大幅提高了通信的可靠性和可维护性。
shutdown_request 是一种特殊的协议消息，主代理通过它请求子代理进行关闭。当系统需要回收资源、任务完成或者出现异常时，主代理发送 shutdown_request 消息给指定的子代理。消息中可以包含关闭原因和清理指示。子代理收到 shutdown_request 后，会执行相应的清理操作（如释放资源、保存状态、关闭连接等），然后回复 shutdown_response 确认关闭。
shutdown_response 是子代理对 shutdown_request 的回复消息。子代理在完成清理工作后，发送 shutdown_response 告知主代理关闭操作已完成。shutdown_response 可以包含清理结果的状态信息（成功或失败）以及任何需要汇报的清理细节。主代理收到 shutdown_response 后，确认子代理已经安全关闭，然后进行后续的资源回收操作。
plan_approval_response 是子代理请求主代理审批计划时使用的协议消息。当子代理需要执行重要操作或需要主代理确认决策时，它先发送一个 plan_approval_request 给主代理。主代理审阅计划后，通过 plan_approval_response 回复批准（approved）或拒绝（rejected）的决定。这种机制确保了关键决策始终由上级代理控制，避免子代理越权执行重要操作。
| 消息类型 | 发送者 | 接收者 | 用途 |
|---|---|---|---|
| 文本消息 | 主代理/子代理 | 子代理/主代理 | 传递简单指令和信息 |
| JSON协议消息 | 主代理/子代理 | 子代理/主代理 | 结构化数据传输 |
| shutdown_request | 主代理 | 子代理 | 请求子代理关闭 |
| shutdown_response | 子代理 | 主代理 | 确认子代理已关闭 |
| plan_approval_response | 主代理 | 子代理 | 审批子代理的计划请求 |
一对一通信是子代理系统中最常见的通信模式，涵盖主代理与子代理之间以及子代理与子代理之间的直接通信。这种模式保证了消息的精确投递和信息的定向传递。
主代理通过 to 参数指定特定的子代理名称，将任务直接发送给该子代理。这是最基本的工作分配方式。主代理维护着一个子代理注册表，其中包含每个子代理的名称、能力和状态信息。当主代理需要执行某个任务时，它根据任务类型选择合适的子代理，并通过 SendMessage 将任务委托出去。子代理独立完成任务后，将结果返回给主代理。这种模式实现了任务的解耦和并行处理。
子代理在完成任务后，通过 SendMessage 向主代理汇报结果。汇报内容通常包括任务执行状态（成功/失败）、输出数据、遇到的错误以及后续建议。主代理收到子代理的汇报后，根据结果决定下一步行动：如果任务成功则继续后续流程；如果失败则可能重新分配任务或采取补救措施。子代理汇报结果时，to 参数通常设置为父代理的标识或直接使用预设的通信渠道。
子代理之间也可以进行直接通信，实现同级协作。例如，一个数据采集子代理完成数据抓取后，可以直接将数据发送给数据分析子代理进行处理，而无需经过主代理中转。这种同级通信方式可以减少主代理的通信负担，提高系统效率。同级通信同样遵循消息队列和投递的规则，发送方子代理和接收方子代理必须存在于同一个子代理系统中，并且名称可被路由解析。
消息投递保证机制确保 SendMessage 发送的消息能够可靠地到达目标。系统采用至少一次投递（at-least-once delivery）策略，即消息会被反复尝试直到成功投递或被明确标记为失败。投递失败时，发送方会收到错误通知，可以根据错误类型决定重试策略。对于关键消息，系统还支持消息确认（acknowledgment）机制，接收方处理完消息后发送确认，发送方只有在收到确认后才认为消息处理完毕。
消息路由是 SendMessage 机制中的核心环节，负责将消息从发送方准确地传递到目标子代理。路由系统基于子代理的名称和注册信息进行消息转发。
当 SendMessage 被调用时，消息路由系统首先解析 to 参数，在子代理注册表中查找匹配的子代理。如果找到唯一的匹配项，消息被放入该子代理的消息队列中。如果找不到匹配项或存在多个匹配项，系统会返回路由错误。路由解析支持通配符和模式匹配，在某些实现中可以匹配一组符合特定命名规则的子代理。
每个子代理都有一个消息队列，进入队列的消息将在子代理的下一个处理轮次中被自动投递。子代理的运行循环（event loop）会检查消息队列，按顺序取出消息进行处理。这种机制保证了子代理在处理完当前任务后能够及时收到新的消息，同时也避免了消息处理的中断和竞争条件。
消息队列为每个子代理维护一个 FIFO（先进先出）的消息列表。同一发送方发往同一接收方的消息按照发送顺序被处理，这保证了消息的有序性。但不同发送方发往同一接收方的消息，其顺序取决于消息到达队列的时间。对于需要严格顺序保证的场景，发送方可以使用序列号或依赖关系标记来控制消息的执行顺序。
当消息发送失败时，系统会生成包含错误信息的响应。常见错误场景包括：目标子代理不存在或已关闭、消息队列已满、网络通信故障等。发送方可以根据错误类型采取不同的应对策略：对于临时性错误（如队列满），可以等待后重试；对于永久性错误（如目标不存在），则需要向用户报告或调整发送逻辑。系统通常内置自动重试机制，对于可恢复的错误会在一定时间间隔内自动重试数次。
协议消息是子代理通信中用于系统控制和管理的一类特殊消息，它们遵循固定的处理流程，确保系统的稳定运行和状态一致性。
shutdown_request 的处理流程包含以下步骤：主代理检测到需要关闭子代理（任务完成、系统关机或异常情况）。主代理构造 shutdown_request 消息（包含关闭原因和清理指示），并通过 SendMessage 发送给目标子代理。子代理接收 shutdown_request，解析关闭原因。子代理执行清理操作：保存当前状态、关闭打开的资源（文件句柄、网络连接等）、中止正在进行的任务。子代理构造 shutdown_response 消息（包含清理状态和结果详情），发送给主代理。子代理进入终止状态。主代理收到 shutdown_response，确认子代理已安全关闭。主代理回收子代理占用的系统资源。整个流程确保了子代理的优雅关闭，避免了资源泄漏和数据丢失。
plan_approval_response 的处理流程涉及子代理和主代理之间的双向协商。子代理在执行过程中遇到需要主代理决策的关键节点。子代理构造 plan_approval_request 消息，包含计划详情、备选方案和推荐意见，发送给主代理。主代理收到请求后，审阅计划内容，评估风险和收益。主代理构造 plan_approval_response 消息，包含审批决定（approved/rejected）和审批意见，发送回子代理。如果计划被批准，子代理按照计划继续执行。如果计划被拒绝，子代理根据审批意见调整计划或上报更高级别的处理者。这种机制实现了对子代理行为的分级控制，既保留了子代理的自主执行能力，又确保了关键决策始终在可控范围内。
核心要点总结：SendMessage 是子代理通信的基础设施，支持文本和 JSON 两种消息格式，覆盖一对一和一对多通信模式。通过 to 参数实现精确路由，借助消息队列保证投递可靠性和顺序性。协议消息（shutdown_request/shutdown_response/plan_approval_response）为系统提供了优雅的关闭和分级审批机制，是构建安全可靠的子代理系统的关键组件。理解 SendMessage 的工作原理对于设计复杂的子代理协作架构至关重要。