Magent 前端边界

agent-shell integration 是完整的会话接口。Magent 不再维护并行的 workspace、compose buffer、command menu 或自定义 output-buffer frontend。新的会话行为放在 agent-shell 或 ACP adapter，共享 runtime 行为放在 runtime API；显式 command registration 和 invocation 则属于 magent-action.el 。

• magent-agent-shell.el 提供 Magent agent-shell 配置、兼容入口 ~magent-start~，以及 隔离的 context compatibility block；交互 buffer 和 prompt 行为仍由 agent-shell 负责。
• magent-acp.el 实现进程内 ACP request、notification、response、permission 和 session/update adapter。
• magent-action.el 负责 registered slash/interactive command discovery 和 invocation lifecycle； magent-action-session.el 提供 isolated durable persistence，但不构成 frontend。
• magent-runtime-api.el 是 frontend-neutral runtime/session API。
• magent-runtime-queue.el 负责会话内 FIFO、会话间并发和 session-scoped cancellation。

1. 使用 M-x magent-start 启动 Magent；也可以先调用 magent-agent-shell-ensure-config 注册配置，再从 M-x agent-shell 中选择 Magent。
2. agent-shell 调用 magent-acp.el 中的进程内 ACP client。
3. ACP 分别规范化 text 和 resource blocks。本地 file:// resource 会提供 scoped request path；history 重建时 resource body 始终保持 user-role context。
4. ACP 按 runtime session 的精确 scope 解析 registered slash input，并通过 magent-action.el 调用；普通 prompt 直接进入 magent-runtime-api.el 。Command 拥有的 turn 和 workflow step 同样使用该 API；direct handler 可以不进入通用 agent turn 而直接完成。
5. runtime API 在排队前一次创建并冻结带 :ui-visibility 'none 的 magent-request-context~；queue 每次只启动一个 active turn，并把该 context 原样交给 ~magent-agent-run-turn 。
6. agent loop 发出 Magent-native observer events； magent-acp.el 将其转换成发给 agent-shell 的 ACP session/update 消息。
7. ACP prompt request 会保持 pending，直到对应的普通 turn 或 command invocation completed、failed 或 cancelled。

• magent-agent-shell-session-strategy 用于选择受支持前端的 new、latest 或 prompt session 流程；无论使用 Magent 兼容入口还是从通用 agent-shell 选择器中选择 Magent， 该设置都会生效。默认值是 ~prompt~，会列出当前 scope 中的新 session 和已保存 session。
• ACP 暴露一个原生 model session option，包含 gptel 已注册的所有 backend 和 model。显示名使用 provider:model~；opaque id 能区分不同 provider 下的同名 model。选择模型只会保存 session-local route，不会修改 gptel 的全局 backend 或 model 变量。~Auto 会清除该 route，并显示当前由 agent/default 解析出的模型。

Model route 会在 runtime submission 创建时完成解析并冻结。用户可见 turn 的优先级为 session route、agent 显式模型、gptel 默认值；child agent 则优先使用自身显式模型， 否则继承冻结的 parent route。route object 还保留 agent profile 与 phase 字段，作为 未来 per-agent/per-phase policy 的 API 接口；当前 runtime 并未实现 phase router。 切换 session 模型只影响后续 submission，不影响 active work、已经 queued 的 work， 也不影响 provider-native tool continuation。

Magent 实现 ACP session/new~、~session/list~、~session/load~、~session/resume 和 session/fork~。~agent-shell-fork 会创建新的 durable session，以 source conversation 作为初始历史，同时使用完全独立的 ledger。source 与 fork 拥有不同 id，并从创建点起 独立演进。

Fork 按精确 scope fail closed：请求 cwd 必须解析到 source session 的 scope，source 也不能拥有 active 或 queued work。selected agent、model route、effort、thinking mode 和 automatic capability 设置等稳定 frontend option 会被继承；session approval override、 child-agent job 和 one-shot skill 会被显式重置。历史中引用的 spilled tool output 会复制到 fork 自己的私有 session storage。

Frontend-neutral 行为放在 magent-runtime-api.el~，ACP conversion 放在 ~magent-acp.el~，交互 frontend 行为留在 agent-shell。~magent-agent-shell.el 只保留 Magent config 与显式分组的 context compatibility advice。不要在 core runtime 内 引入第二套交互 frontend。

Skill discovery 同样保持 frontend-neutral。 magent-skills-list-descriptors 和 magent-skills-resolve-descriptor 会针对精确 session scope 返回 metadata，但不暴露 prompt body 或 executable handler。因为 agent-shell 只有一套 slash menu，ACP 会把 instruction skill 展平为 $name~，再把 ~/$name 作为普通 magent-runtime-submit :skills turn 分派。未来 frontend 可以把 registered Action command projections 与 skill descriptors 展示为两个独立入口； 它不应从 Action registry 反推 skills。

• 受支持的 frontend 硬依赖 agent-shell 和 acp 。
• Magent 目前仍需为通用 agent-shell picker 显式注册 config，并临时 advice 四个私有 context function，以处理 remote-safe 与空行 context。
• runtime execution 在同一会话内按 FIFO 串行执行，不同会话（包括同一项目）可并发。完成和取消均指向精确 submission；忙碌或等待批准的会话不会阻塞其他会话。
• cancellation 是 session-scoped：取消一个 ACP session 会取消该 session 的 active 和 queued submissions，但不会移除其他 session 的 queued work。
• 受支持的 frontend 已支持 per-request instruction skill overrides、scope-aware /$skill projection 和 Elisp-native Action command projections；目前不暴露 per-request agent overrides。
• ACP session config 暴露 Automatic capabilities ；关闭后，该 session 后续 turn 不再 自动解析 contextual capabilities，但显式选择的 instruction skills 仍然生效。
• Model route 当前只保存在 session 内存中；尚未实现跨 Emacs 持久化。加载已保存的 session 后会回到 ~Auto~。
• 不支持在 active turn 执行期间 fork，也不支持跨 project scope fork。

Assistant message item 按顺序保留进度、工具和最终答复边界，reasoning 显示设置 不影响可见的进度说明。Runtime 的 plan-update 事件携带 entries，由 magent-acp 转换为原生 plan update；保存的 plan item 使用同一路径恢复，由 agent-shell 负责显示。取消或失败的工具在恢复时显示失败；普通 turn 没有最终答复时，pending prompt 返回明确错误，不再隐藏地请求模型补写总结。