agent-delegator

把编码工作从 Claude Code / Codex 交给独立进程、独立 session 的 pi agent，只回收一份约 30 行的结构化摘要，而不是整段 transcript。

delegate start "把 session store 换成 Redis 后端，补边界测试" --verify "npm test"
# ... 去做别的事 ...
delegate wait d20260822-0830-a1b2c3  # 阻塞到结束，一次调用覆盖整个任务

task d20260822-0830-a1b2c3   status completed   4m12s   $0.0312
cwd  /path/to/repo (branch main)
agent pi 0.84.2 gpt-5.6-sol thinking=high   tools 18 calls

changed 3 files  +84 -12
  M src/auth/session.ts   +61 -9
  M src/auth/index.ts     +18 -3
  A test/session.test.ts  +5 -0

verify `npm test` -> exit 0

outcome   done
what      换掉内存 session store，改 Redis 后端，补边界测试
decisions 用 SETEX 而非独立 TTL 扫描，避免多实例竞态
followups REDIS_URL 需要进部署配置

tokens 41203 (in 38160 / out 3043)
artifacts /Users/you/.delegate/tasks/d20260822-0830-a1b2c3
follow    delegate follow d20260822-0830-a1b2c3 "<msg>"

安装

需要 Node >= 20.10，以及已安装并完成鉴权的 pi。如果要启用质量监督，另行全局安装 agent-overseers；它是可选组件，不影响普通 delegation。

npm install --global agent-delegator
# 可选：只有使用 --oversee 时才需要
npm install --global agent-overseers
delegate install
delegate doctor

agent-delegator CLI 全局安装；Claude Code 和 Codex 的配置仍只落在当前项目：

your-project/
├── .claude/skills/delegate/SKILL.md       # Claude Code 项目级 skill
└── .agents/skills/delegate/SKILL.md       # Codex 项目级 skill

delegate install 不会写 ~/.claude、~/.agents、~/.codex，也不会改已有的 CLAUDE.md 或 AGENTS.md。建议把两份 SKILL.md 一起提交；团队成员全局安装 CLI 后即可获得相同接入。

安装命令默认同时配置 Claude Code 和 Codex；也可以只选一端，或指定另一个工作区：

delegate install --claude
delegate install --codex
delegate install --cwd /path/to/project

重复执行是安全的：生成内容未变化时会报告 up to date；已有同名但内容不同的 skill 时会拒绝覆盖，确认后可加 --force。如果当前会话没有发现新建的顶层 skill 目录，重启对应的 Claude Code/Codex 会话。

接入后，Claude Code 可显式使用 /delegate，Codex 可显式使用 $delegate；两端也会根据 skill 描述自动触发。skill 直接调用全局 PATH 中的 delegate，不会通过 npx 临时下载或解析项目依赖。

命令

| 命令 | 说明 | |---|---| | delegate start "<task>" | 起一个新任务，秒级返回 taskId，不阻塞 | | delegate wait <taskId> | 阻塞到终态，打印摘要；这是获知“完成了”的方式 | | delegate status <taskId> | 单次快照：phase / 工具计数 / token / context 水位；运行中也可用 | | delegate guide <taskId> "<msg>" | 中途纠偏：当前工具调用后、下次模型调用前送达 | | delegate stop <taskId> | 取消运行中的任务（不回滚已写入的文件） | | delegate run "<task>" | start + wait 合一；短任务或无法后台等待时用 | | delegate follow <taskId> "<msg>" | 对已终态任务复用同一 pi session 续跑 | | delegate daemon status \| stop | 查看 / 停止 daemon | | delegate log <taskId> [--tools] | 有界读事件日志；--full 打印全量 | | delegate list | 最近任务 | | delegate cleanup <taskId> [--yes] | 删 worktree、分支与 artifacts；不加 --yes 只预演 | | delegate doctor | 环境自检 | | delegate install [--claude] [--codex] [--cwd DIR] [--force] | 把 skill 安装到工作区；默认同时配置两端 |

start / run 的选项：

| 选项 | 说明 | |---|---| | --cwd DIR | 工作目录，默认当前目录 | | --worktree | 在 git worktree + 分支 delegate/<taskId> 中隔离执行 | | --verify CMD | agent 结束后执行，真实退出码进摘要 | | --timeout SEC | 默认 1800 | | --provider / --model / --thinking | 透传给 pi，默认沿用 pi 自身配置 | | --readonly | policy 拒绝 edit/write/bash，仅供调研 | | --allow-root DIR | 追加可写根，可重复 | | --oversee PROFILE | 显式启用一个具名 Overseer profile | | --json | 输出 JSON 报告 |

显式质量监督

主 Agent（Codex / Claude Code）在发起任务时自行判断是否需要监督，并通过具名 profile 显式选择：

overseer profiles --cwd /path/to/project
delegate start "重构鉴权边界并补回归测试" --cwd /path/to/project --oversee quality

退出码

调用方无需解析文本即可分流：

| 码 | 含义 | |---|---| | 0 | 完成，verify 通过（或未要求 verify）；或有界 wait 超时但状态未变 | | 10 | 完成，但 verify 失败 | | 20 | agent 自报 partial/blocked，或 terminal review 阻止完成 | | 30 | 超时 | | 40 | pi/协议/policy/daemon 错误，或必需终审不完整、sidecar 整体失联 | | 1 | 用法错误 |

常驻控制面

运行中的任务由一个 daemon 持有，按需启动，空闲 15 分钟自动退出。并发 start 用 lockfile + 原子 bind 保证只拉起一个。socket 权限 0600。

为什么不轮询：wait 阻塞在事件上——daemon 内部每次有意义的变更都会推进一个 revision 计数器并唤醒等待者，所以一次 wait 能覆盖任意时长的任务，且不会漏掉两次调用之间发生的更新。参考项目（coder-mcp-bridge）的 agent-wait 卡在 60 秒上限，因为 MCP 工具调用不能无限阻塞；CLI 没这个约束，一个 30 分钟任务在参考项目里约需 30 次调用，这里只需 1 次。--timeout SEC 可做有界等待，超时返回当前快照并标 changed: false，不是失败。

任务不随调用方退出：start 之后 CLI 进程就结束了，任务归 daemon。打断 run / wait 只是停止等待，不会停止工作。想把“完成”变成主动通知？把 wait 放进后台命令即可——这是调用方的用法，不是本工具的功能。

摘要为什么可信

摘要由两部分合成，来源不同：

机械事实由 delegate 自己计算，不采信 agent 自述。run 前先记录 HEAD、git status 以及已脏文件的内容哈希；run 后重新比对，只有内容真的变了才计入。不能只比 status 字母：未跟踪文件在编辑前后都是 ??，而这正是 follow 的常态（它总是叠在上一轮留下的改动之上）。verify 是真实退出码。

叙述部分来自 pi：通过 --append-system-prompt 要求它在末尾输出定界块，再解析 outcome / what / decisions / blockers / followups。缺块时回退截断末条消息，并在摘要标注 summary block missing。

两者冲突时以 diff 为准。这正是让上层能安全信任摘要的关键：agent 声称改了什么并不重要，仓库里实际变成什么样才重要。

落盘

默认 ~/.delegate，可用 DELEGATE_HOME 覆盖。

~/.delegate/
  daemon.sock                  daemon 的 unix socket(0600)
  sessions/                    pi session 文件
  worktrees/<taskId>/          --worktree 建立的工作树
  tasks/<taskId>/
    meta.json                  taskId / sessionId / cwd / 模型 / 状态 / 退出码
    progress.json              运行中的活状态：phase / revision / 工具计数 / token / context 水位 / 待送达 steer
    report.json                完整报告，status 据此重印
    events.jsonl               全量原始事件流
    summary.md                 agent 末条消息（已剥离定界块）
    diff.patch                 完整 patch，含新建文件
    verify.log                 verify 全量输出
    oversight/
      snapshot.json            解析后冻结的具名 profile/role 配置
      events.jsonl             sidecar 协议事件与生命周期诊断
      findings.jsonl           finding 的 revision、来源与内部 steer 投递结果
      diagnostics.jsonl        过期/重复 finding、普通 Role 超时等监督诊断
      summary.json             最近 attempt 的监督状态、finding、修正次数、Role usage 与终审备注
      attempts/<attempt>/
        summary.json           该 attempt 的不可覆盖最终监督摘要
        cycles/<cycle>/
          diff-summary.json    该终审周期观察到的机械 diff 摘要
          verify.log           该终审周期的完整验证输出
          verify-summary.json  该终审周期的验证退出状态与有界 tail
          decision.json        与 request/revision/cycle 严格配对的终审决策

follow 依赖 meta.json 里的 cwd：pi 的 session 恢复键是 （session-dir, cwd, id） 三元组，cwd 变了就是另一个 session。

安全边界

• read/edit/write/grep/find/ls 由 policy 扩展做路径约束，越界拒绝；--readonly 下额外拒绝 edit/write/bash。
• bash 是 advisory 边界，不是沙箱。 无法靠检查参数可靠约束 shell。需要强隔离时请用容器、VM 或 OS sandbox。
• policy 扩展加载失败时 pi 会完全不执行权限检查且不再逐次报错，因此 delegate 检测到这种情况会直接中止整个 run 并以 40 退出，不降级为警告。
• --verify 经 shell 执行是设计意图（等同你自己敲那条命令）；agent 的输出永不插值进该命令。
• API key 通过环境变量或 pi 自身的凭据存储提供，不要写进仓库。

开发

npm test    # build + 全量测试；全部走 fake-pi，不产生 API 费用
npm pack --dry-run   # 检查 npm 发布文件清单

发布前先登录 npm，并确认 npm test 与 npm pack --dry-run 都通过，再执行：

npm publish

License

MIT