Child-Agent Jobs

公开的 child-agent 工具面如下：

工具	作用
spawn_agent	启动一个 child-agent job，并返回稳定 job id。
send_agent_message	向已有 child job 发送 follow-up 输入。
wait_agent	等待一个或多个 job，并返回状态/结果。
list_agents	列出当前 parent session 下的 child jobs。
close_agent	关闭 job，并在存在 live request 时 abort。

这些工具共用 agent permission key。旧的 delegate 工具不保留 compatibility wrapper。

magent-agent-job.el 定义 magent-agent-job ，这是 child job 的 durable record。每个 job 保存：

• id
• parent-session-id
• agent-name
• task-name
• status
• prompt
• created-at
• updated-at
• transcript
• result
• error
• metadata

合法状态包括 queued 、 running 、 waiting 、 completed 、 failed 、 closed 和 cancelled 。

Parent magent-session 会在 agent-jobs slot 中持久化 child jobs。active loop 的 runtime-only state 存在 magent-agent-job--runtimes ，以 job id 为 key。这样 parent session JSON 足够恢复和检查 job 元数据，同时不会尝试序列化 live request handle。

magent-agent-job.el 同时拥有 status observers。~wait_agent~ 订阅状态转换并只使用 一个 deadline timer，不做轮询。Child 状态变化通过 session deferred-save queue 调度 parent-session 持久化，因此 tool callback 不会同步重写 session JSON。

1. spawn_agent 在 parent session 中创建 magent-agent-job 。
2. child request 通过 magent-agent-loop.el 中的 Magent-owned loop 启动。
3. child 使用 summary-only UI，不把完整 transcript 写进 parent conversation body。
4. completion、failure 和 close transition 会通知 wait observer，并更新 durable job record。
5. tool result 向 root agent 返回 model-visible JSON summary。

成功的 spawn_agent result 会包含机器可读的 next_action~，使用返回的 job id 调用 ~wait_agent~。它不会固化 timeout，因此宿主策略仍是权威来源。 ~wait_agent 省略 timeout 时使用正数 ~magent-request-timeout~；该设置被禁用时使用有限的 300 秒 fallback。单次 wait 超时不会取消或关闭 child job。

Provider 边界仍然是 magent-sampling-gptel.el 里的 gptel-request 。Magent 自己负责 orchestration、tool dispatch、persistence、abort 和 child-job coordination。

Child jobs 会在合理范围内继承 parent request context：

• project root 和 session scope
• backend/model names
• temperature、top-p、reasoning effort 和 thinking mode
• active skill names 和 capability context
• 受 parent 与 child agent 双方约束后的 effective permission profile
• request depth，用于递归 spawn guard

magent-child-agent-max-depth 控制递归 spawn。默认允许 root 创建直接 children，但阻止 child 再继续创建 child。

受支持的 agent-shell frontend 会渲染紧凑的 child-agent 生命周期更新。完整 child prompt、metadata、result/error 和 transcript 会持久化在 parent session 的 agent-jobs 数据中。

Agent-shell 恢复持久化 parent session 时，也会恢复其中的 agent-jobs 数据。Emacs 重启后不会恢复 active request handle，但保存的 job metadata、result/error 和 transcripts 仍会保留。

这个生命周期刻意保留 Magent 的 Emacs-native 工作流：

• live Emacs buffers
• 隔离的 emacs_eval~、受信任的 ~emacs_read 和显式 emacs_eval_live
• agent-shell UI
• project-scoped sessions
• gptel transport

Codex sandbox、seatbelt、bubblewrap 和 shell-isolation parity 不在范围内。