结构化能力：Plan / Goal / Todo / Workflow / Subagent

四者定位对比

能力	性质	持久化	驱动者	定位
Todo	模型自维护的任务清单	log-only 全量快照（`todo/write`）	模型自己	轻量、无 id、全量替换
Plan mode	协作状态（只读规划阶段）	log-only `plan/mode` 事件	用户/模型经 `exit_plan_mode`	软引导，不强制
Goal	同会话长程目标 + 自动续行	durable `goal/change` 事件	driver 在 idle 时自动开 round	跨多 turn 自主续行
Workflow	模型写的编排脚本	父 session 的 `tool-workflow/*` 记录	worker thread 引擎	结构化并发派生子 agent

共性设计：可重放转录消费 session/event（log-only 事件不入模型历史但可 fold 恢复）；agent/* 只做活协调。

Todo

TodoItem = { content, status: pending|in_progress|completed }，刻意最小化（无 id/优先级）；每次 todo_write(todos) 全量替换、last-write-wins；列表只属于调用工具的那一个 agent session。allowParallelInProgress 是部署选择。

Plan mode

激活时每个请求附带部署提供的 plan:policy prompt section（order 50）。软引导——sandbox/approval 独立强制，不读写 plan 状态。
状态 log-only、whole-value-replace；选择经 pending selection 机制（set() 返回 committed|queued|cancelled|noop）；唯一 append 点是前置的 agent/pre-step listener（且仅在请求 header 状态变化时追加一条 user/message 通知）。
exit_plan_mode 工具：始终注册、非 plan 态执行失败；要求 # 开头的完整 markdown plan，经 user-questions seam 人工审核。另有 /plan [off|message] 命令。

Goal（same-session goals）

GoalRef { id, revision } compare-and-set；GoalPhase = active|paused|blocked|complete。activation（armed/disarmed）是进程内的，与 durable phase 分离且刻意不持久化——resume/fork 后自动工作必须先人工授权（安全设计，见 architecture）。
每次变更是一条 durable goal/change session 事件（完整 snapshot 或 clear tombstone）；续行消息带 GoalMessageSource { kind:'goal', goalId, revision, round }。
goal-round-driver：agent idle 且 goal active+armed+有容量时，先 checkpoint（ctx.sessions.flush）→ 预留 roundsStarted+1 → 排一条 <goal_round> prompt；pre-step 前后双重校验，只有真正进入的 user/message 才推进计数；人类消息不占 cap；取消会把有已准入尝试的 goal pause 掉防自动重启。
goal 是状态而非调度器，session log 是其唯一真相源。

Workflow（+ Ralph）

模型写 plain-JS 编排脚本（top-level await、以 return <json> 结束），由 dsh-workflow-worker-thread 执行（每 run 一个 worker_threads worker + vm context；无 fs/网络/Node API）。
WorkflowStartRequest { script, meta, args?, subagentProvider?, maxTotalAgents?, parent(必填), signal? }；meta（name/description/whenToUse/phases）纯 JSON 先校验再跑。
脚本内 hooks：agent() 派生 subagent、phase(title)、log(msg)、parallel()/pipeline()。结果 { value, stopReason: completed|cancelled|error, agentsStarted }；result 永不 reject，取消有 bounded grace 强结算；WorkflowError.fatal 被 parallel/pipeline 重 throw 而非映射 null。
observe-only 事件对：workflow/start|phase|log|agent-start|agent-end|end；父 session 写 tool-workflow/run-start|run-end durable 展示记录。
Ralph loop（dsh-tool-ralph）：面向不可变目标的前台 fresh-agent workflow run——每轮（Ralph round）一个全新 child session，不继承父/前轮对话种子，靠共享 workspace 与 handoff（规范化有界报告：status/summary/evidence/next steps/blocker）传状态。是组合自 workflow 与 subagent 原语的模型侧策略。

Subagent 机制

capability seam，与 bash 等单 provider seam 不同：多 provider 按名共存（registry 形态仿 LLM adapter registry）。

Providers（6）：spawn-in-process、fork-in-process、acp、codex、claude-code、dsh-sdk——即可以把 Claude Code / Codex / ACP 外部 agent 当子代理驱动。
Consumers：tool-subagent（per-provider 委托）、tool-subagent-control（send_message/interrupt_agent/list_agents）、tool-subagent-report（子向父 report 回传）。
能力发现：一次性 run 看静态 SubagentCapabilities { outputSchema, depthLimit, toolFilter, persona }（缺失大声拒绝 UNSUPPORTED_CAPABILITY）；continuable 看可选方法 prepareContinuable（方法存在即能力）。

One-shot：start(name, req) → SubagentRun { id, localAgent, result, dispose() }。本地 provider 必须在 start() 完成前发布子 agent/session；子 header 记 parentSession；首请求前 append subagent/descriptor（log-only durable 身份）。SubagentStopReasonMap = completed|aborted|error|max-tokens|refusal。子失败 resolve 为非 completed stopReason，只有基础设施故障才 reject。

Continuable：一个 durable 子 Session + 至多一个进程内 Activation（重建的子 Agent 驻留期）。层级：persisted Session → optional Activation → one AgentHandle → Agent inbox 是唯一 turn FIFO → owned child Activations。Activation 状态从静默与 owned-child 集合导出：running / waiting / settled。followup() 按驻留性路由（同 Activation 排队 / 唤醒 / cold-resume）；follow-up 权限 = 精确活 Agent 且是 durable 直接父。interrupt() = Agent.cancel(cause, {keepInbox:true})，保留未认领 inbox 与后代。

Report/Settled：reportFrom(child, content, { delivery: 'quiet'|'wakeup' })——quiet 用 agent.inject()、wakeup 用 agent.followup()。Activation settle 时无条件向直接父递送 subagent-settled 通知（runtime 自己的陈述，刻意与子 report 不同 kind，避免转录把 runtime 的话记成孩子写的）。

深度与种子：delegation depth = durable SessionHeader.delegationDepth 与 AgentOptions.subagentDepth 取大，子持久化 parent+1，maxDepth 上限校验；fork 种子 = 父 log 的平衡已完成-turn 前缀。

Wiki AI

目录