Store a key/value pair in shared memory visible to both Codex and Claude.

Read a value from shared memory by key. Returns empty string if missing.

List all keys currently stored in shared memory.

Append a timestamped note to shared notes (append-only). Use tag like handoff:.

Read shared notes. Optional tag filter.

Create a new task in the task queue. Returns task_id. Optional deliverable (artifact path) and acceptance_criteria (how to verify done) let the next agent check completion without guessing. Optional dependencies (array of task ids) builds; a dependency DAG: the task stays non-claimable until every dependency is terminal. Explicitly new approval-criteria + require_approval: if require_approval=true, the task is a human-approved approval gate — its completion (task_complete by the implementer) lands in awaiting_approval and stays there, blocking any downstream dependent DAG node, until a human calls task_approve. That's the block-until-ack approval gate.

DAG acceptance gate. Act on a task currently in awaiting_approval: decision=approve (…→completed, releases dependents) or decision=reject (→back to running for redo). Rejects a non-awaiting task. Records approver.

List tasks. Filters: status / search(标题+描述+id 模糊) / task_ids(限定集合,批量查询). 排序: sort=priority(按优先级 high>medium>low)|created(创建时间)|status(状态分组). 分页: limit/offset. 批量操作: batch_action=reassign|fail|supersede 配合 task_ids + batch_agent/batch_reason 一次性对多个任务施效(原子). 不带参数=返回全部(兼容旧行为).

自动安全硬拦：对一段文本/产物按 blocklist(默认内建危险模式)预扫描。命中即 blocked → 不可自动放行,清单返回命中模式。用于自动审批前的把关; 小模型/人工兜底据此再判断。blocklist 可选传(字符串或正则)。

把一次多Agent工作流落成阶段依赖链任务 DAG，供面板「当前工作流」按卡片/聚焦图展示。支持四种范式：①线性链模板 'bmad'(需求→架构→实现→评审) 或 args.stages 自定义任意阶段；②竞争式范式 args.paradigm='compete'（同一问题派 ≥2 个视角并行各出方案 → 主控收敛最优，传 args.competitors:[{agent,view}]，可 args.converge_title/args.converge_agent）；③合作式范式 args.paradigm='collaborate'（设计→实施→审核 三段链且实施者与审核者分离，传 args.designer/args.implementer/args.reviewer，默认 claude→codex→claude）；④动态路由范式 args.paradigm='dynamic'（自动分析 goal 选 compete 或 collaborate，路由理由写进工作流 meta + 各 task description「上墙」，参数缺省时用默认 agent 分配：compete=claude/codex/qwen 三视角，collaborate=claude设计/codex实施/qwen审核）。 模板库：template 可选 bmad/bmad-lite/review-only/fix-flow，或 '_list' 返回清单； 并行阶段：args.stages[i].agents=[a,b,c] 或 parallel:true → 该阶段铺 N 个同深度并行任务（共享前置，下一阶段依赖该阶段全部）。args.workflow_id 稳定 id + args.title 让多次调用归并成同一张工作流卡；可选 args.approve_each_phase 每阶段人工门。返回阶段 task_id 链。

任务完成自动沉淀：把一条已完成/已有结果的任务(标题+描述+结果)提炼成知识点写进向量记忆(memory_add)。供后续任务 memory_search 复用。

Claim a pending task by id. Transitions pending→running, records claimant. Rejects if not pending (blackboard auto-claim).

Mark a running task completed with result. Transitions running→completed. Optional agent_name records who completed (useful if handoff mid-task: A claims, B completes).

Mark a task failed with reason (e.g. could not complete).

心跳 worker/主控里程碑汇报：给一个 running 任务刷 last_heartbeat_at + heartbeat_n，并把 note 追加进 progress_log（里程碑）。注意：服务端已对每个 run_* 子进程自动心跳（进程活着就跳，无需调用），本工具供能调 MCP 的主控/worker 在生产阶段主动上报里程碑（如『方案已出，等决策』），或手动续活一个进程仍活着但长期无 stdout 的长任务。需持当前 attempt_id（claim 签发；旧/伪造令牌拒绝），防迟到覆盖。

决策上浮（）worker 遇方案选择/疑问时向队长/用户上浮：把任务转 escalating 态（运行中阻塞，等人类决策），存 question + options。需持当前 attempt_id（claim 签发；交接/伪造令牌拒绝，防迟到）。escalating 是非终态：监控每周期向用户聚合上报（带 raised_at 年龄），用户回答后由队长 task_decide 下发决策、任务回 running。

决策下浮（）队长/用户在任务 escalating 时下发裁决：写 escalation.decision + decider + decided_at，任务回 running（worker 续跑）。仅对 escalating 态生效；幂等——已决策任务再 decide 拒绝。记录 decider 供审计。

Mark a task superseded by another (decision changed: implementer swapped or a step cut). Transitions any non-terminal status→superseded, records superseded_by (task id) + reason. Use this instead of completed/failed when a task didn't finish but was overtaken — keeps the task log honest (no zombie pending tasks).

前置插入核心原语⚠：动态重算任务依赖（覆盖式修改已有任务的 dependencies）。用于前置插入——fork 出补丁分支 S3' 后，把 S3' 的 dependencies 改为指向新插入的前置 S2.5（set=[原依赖…, S2.5]），实现『反向插入硬性前置 + 重算依赖链』。内置【无环校验】——若 set 引入环（目标任务成为自己的直接/间接依赖）则拒绝；已 terminal（completed/superseded）任务不可改（遵守『不破坏已完成段』演进约束）。不改变状态、不派单，纯依赖图调整。

Session 分叉：从 running 任务派生子任务（继承 deliverable/dependencies/acceptance_criteria），原子地把原任务标记 superseded→子任务 id。父任务不 rewrite history。用于探索不同执行路径/决策变更。返回新子任务 id。

【自适应重规划引擎】总入口：封装六个 DAG 演进动作（fork 备选 agent / append 后置追加 / insert 前置插入 / degrade 降级验收 / rollback 阶段回退 / branch 条件分支），并【服务端强制】演进护栏——演进计数 ≤3（超限拒）、演进 ≥2 次强制独立审闸（未过审 gate_required 拒执行）、不破坏已完成段（rollback 是显式豁免：授权推翻已完成段）、留痕统一记进 workflow 元数据。调用方只要给 action+目标任务+理由，护栏/计数/留痕/面板标记引擎代管，不必手动拼 task_fork/task_depend/task_create。

Orchestrator 自动拆解（L1）：给一句话目标, 自动产结构化的多段 DAG 计划。调用拆解器模型把 goal 拆成 stages[]（每段 title/description/criteria/agent/depends_on），做结构自检（数组非空/每段可验收 criteria/agent 已注册/依赖引用合法/无环反向DFS/≤8段），并按复杂度定 L3 人审闸：复杂(段数或跨 agent 并行超阈值)→approval_required=true 交主控审核；小任务→auto-approve 可直接接 workflow_start。不直接建任务, 返回可执行计划供人审/改造。拆解器经 runAgent（继承 429 退避/多模型轮转）。

结果冲突仲裁：多 worker 对同一问题给出不同答案时自动裁决。输入 ≥2 份候选结果，三层裁决：①多数一致优先（结论相同直接过）→ ②专家加权（claude 推理 3 / codex 执行 2 / 其它 1，confidence 可选加权）→ ③仍无胜者时派 LLM 仲裁者（从空闲 worker 池轮询选，排控制主控防自我指涉，全忙回退 qwen）背书。返回 winner + 裁决层 + 各候选权重明细 + 仲裁理由。只裁决不建任务，供 Orchestrator 合并多 worker 并行产出时调用（ 配套）。

Release a pending OR running task back to unclaimed so another agent can take it over. Transitions running→pending (or keeps pending), clears claimant, and revokes the attempt token while sealing it into a handoff generation (stale_attempt_ids + reassigning=true, ≈dsh handoffId): any later complete/fail/approve by the old implementer — with its old token OR even tokenless during the reassignment window — is rejected by staleAttemptRejected. The new owner claims it to start a fresh attempt and clear the handoff state. Use when the current implementer is stuck/lost/gave up and you want an uncontested take-over. Terminal tasks refuse (can't resurrect).

中断一个 running 任务：kill 其 worker 子进程树（Windows 走 taskkill /T /F，Unix 走 SIGTERM→SIGKILL），并把任务置 interrupted 态（保留中断前部分输出 + session_id，供 task_resume 续接）。仅 running 态可中断；终态任务拒绝。适合长任务卡死/跑偏时人工叫停。

恢复一个 interrupted/failed/superseded 任务：复用原任务的描述(prompt)+session_id(若有)+workdir+agent，重新派发给同一 worker 续跑。session_id 复用实现真 resume（claude/codex/qwen 保留上下文）；DSH/opencode 无 resume 则全新跑。复用原 task_id，保留 workflow/dependencies 挂链。可用 args.prompt/session_id/workdir/model 覆盖。终态 completed 不可恢复。

消息总线（兼容保留）: 发一条消息到某 agent 收件箱。持久化落 memory.json mailbox。含【实时唤醒】——若接收端此刻正用 inbox_wait 挂起等待, 立即被唤醒拿到该消息(不等下一轮 poll); 若不在 wait, 消息留存待其下次读。可选 kind/topic/priority/memory(自动沉淀进向量记忆)。返回消息 id。

消息总线【全能力发送】: to/from/body + kind/topic/priority + memory(自动沉淀向量记忆) + 广播(to="*" 唤醒所有广播订阅者)。含实时唤醒——若接收端正 inbox_wait 挂起则即时命中。返回消息 id。

消息总线读(同步, 兼容保留): 列某 agent 未消费(unconsumed)且未被他人租约占用的消息, FIFO 序, 各带 id + 信封(kind/topic/priority)。不消费——读后须 inbox_ack {agent, ids} 确认, 授予/续 60s 租约防并发双处理。实时唤醒用 inbox_wait。

消息总线【实时唤醒读】(异步阻塞, 事件驱动不阻塞服务器): 读某 agent 消息; 有已 pending → 立即返回(授 60s 租约可 ack); 无 → 挂起等待, 当 bus_send/agent_send_message 发来即被【即时唤醒】返回, 或超时(wait_ms 默认30s 上限120s 返回 {items:[], timed_out:true})。可选 kind/topic 过滤订阅。返回 { items:[{id,from,to,kind,topic,priority,body,created_at}], timed_out }。消费用 inbox_ack。

消息总线消费: 把某 agent 的 id(数组)标记 consumed, 释放租约。只有赢得租约的读者可 ack(幂等——ack 已消费/非己有/未过租约期的是 no-op 非错)。消费后不再出现在 inbox_read/inbox_wait。

消息总线【只读信号/消息流回放】: 列某 agent / topic / kind 最近 N 条(含已 consume), 供面板展示/订阅者审计/历史回放。默认 agent 必填; limit≤200。

Acquire an advisory file lock to prevent two agents editing the same file concurrently. Returns ok:true on success, or ok:false with the current holder if already locked. Locks auto-expire (default 30min) so a crashed agent can't hold a lock forever. Path is normalized to absolute.

Release a previously acquired file lock. Returns the holder that was released. Advisory lock — cooperative, not enforced.

List all currently held (non-expired) file locks. For diagnostics.

Search project with ripgrep (fallback grep). Returns file:line:match.

Read file content with line numbers. For letting the other agent inspect a file. Path is confined to BRIDGE_WORK_ROOT (or the caller's workdir) per path isolation — out-of-root paths are rejected.

List directory entries (one level). Path confine to BRIDGE_WORK_ROOT per .

Async call Codex CLI (codex exec) to run a task. For batch codegen/patches. Non-blocking. Auto-tracks task. Pass session_id to resume a prior Codex session (preserves context); the new session id is captured from output and returned for later resumption. Retries automatically on 429/rate-limit/timeout with exponential backoff (default 2 retries, 3 total attempts); set max_retries=0 to disable.

Async call DeepSeek DSH CLI (dsh --profile headless) to run a task. Provider-rotatable across the configurable // backends (same agent loop; pick backend via ~/.dsh settings/patch). Runs with cwd = workdir, which is the workspace-write sandbox boundary: it can REALLY write files and run bash/pwsh inside workdir, non-interactive (no approval stall). Non-blocking. Auto-tracks task. NOTE: no resume (session_id is accepted but starts a fresh run, like opencode). Retries on 429/timeout with exponential backoff (default 2, 3 attempts total); set max_retries=0 to disable. Pass a bounded isolated workdir, never the main repo / a sensitive volume.

Async call Claude CLI (claude -p headless) to run a task. For reasoning/architecture. Injects auth env. Non-blocking. Auto-tracks task. Pass session_id to resume a prior Claude session (preserves context); the new session id is captured from output and returned for later resumption. Retries automatically on 429/rate-limit/timeout with exponential backoff (default 2 retries, 3 total attempts); set max_retries=0 to disable.

Async call Qwen CLI (qwen --auth-type openai, Qwen Code) to run a task. For writing/iterating docs & PPT (complements opencode) and image analysis (complements vision_analyze). Uses the qwen 端点 OpenAI-compatible endpoint via QWEN_ENV. --approval-mode auto-edit lets write_file land to disk (auto). Non-blocking. Auto-tracks task. Pass session_id to resume a prior Qwen session (preserves context — qwen has real resume via --resume, unlike opencode); the new session id is captured from JSON output and returned for later resumption. Retries automatically on 429/rate-limit/timeout with exponential backoff (default 2 retries, 3 total attempts); set max_retries=0 to disable.

List all registered agents (run_* workers) available to agent_invoke. One agent per line: name + (auto: yes) if it honors the auto param (only codex) + [capabilities] + strengths. Use it to pick the right worker for a task. 不自动派单——只备齐选型数据。

Agent 能力评估体系：按 agent 聚合任务记录出 完成率/平均质量分/平均时长/平均重试/满意度 (五等)。只读,供任务路由与选型建议。

识别本地已安装的 worker CLI（claude/codex/qwen/opencode/dsh），检测是否可加入 multi-agent，并把可用性挂载到 registry（AGENTS[name].available）。返回每个 agent 的 available + 缺失引导。bin 类型检测 PATH/绝对路径可执行；qwen 属端点类型，检测 QWEN_BASE_URL/OPENAI_BASE_URL 是否配置。available=false 的 worker 被 run_*/agent_invoke 派发时会被拒绝（提示未安装）。

Invoke any registered agent by name to run a task. Generic path over the Agent Registry — same driver as the run_* tools but name-driven, so new agents (e.g. qwen) need no per-agent tool. Non-blocking. Auto-tracks task. Pass session_id to resume a prior session (the captured id is returned for reuse). auto is honored by agents that support it (codex, qwen); others ignore it. Use agent_list to see available names. Retries automatically on 429/rate-limit/timeout with exponential backoff (default 2 retries, 3 total attempts); set max_retries=0 to disable. 【后台契约】调用可立即返回/被调用方撤回:server 端 Promise 不会因调用方撤回而终止,worker 继续在后台跑到完成,结果落 task.result(及 trace,若 capture_trace);调用方随时可用返回的 task_id 经 task_list 或面板 /api/state 取最终产物,无需阻塞等本次调用返回。给长任务(评估/设计/重构, prompt>2000字)显式传 timeout_sec 600~900 防误杀;传 plan_mode 只读调研不落盘。【默认worker】name 可选：省略 或 指定==控制主控(BRIDGE_CONTROLLER) 时，改从空闲 worker 池轮询派一个（排主控，不压 main；全忙回退主控/或 qwen），返回文案标注实际 worker。【备路】name 明确且该 worker 已忙(agent_live busy/有 running 任务)时自动改派空闲备路 worker(排控制主控,不压 main),返回文案标注改派;same_worker:true 强制精确同名、auto_fallback:false 关备路。

质量门禁：LLM-as-judge 对产物按 criteria 打分(0-100)。低于 threshold(默认80) 判不通过；但在带宽 degrade_band(默认10) 内(score∈[th-band,th)) 判降级放行(pass + degraded 标记 + verify_degraded 留痕)。打分写回任务 quality_score。默认 evaluator=qwen，可换 claude。可作任务下游 gate。

Semantic search over the shared vector memory store (paraphrase-multilingual-MiniLM-L12-v2, 384-dim embeddings + sqlite-vec KNN). Returns top-k memories by cosine similarity. By default filters by scope (current project + guessed platform + global) to avoid cross-project noise — pass scope='global' to search only global knowledge, or pass an explicit category for exact-match filtering. Optional min_length filters out short structural segments (e.g. 40). Lazy-loads the ONNX model + sqlite-vec on first call. Complements keyword search (project_search) for 'have I seen something like this before' recall across agents.

Add a memory to the shared vector store with an embedding (paraphrase-multilingual-MiniLM-L12-v2, 384-dim). Stores content + category + source for later semantic recall via memory_search. Category is auto-constructed as layered '::general' from scope/cwd + content platform hints, unless an explicit category is given. Use to sediment cross-agent knowledge (learnings, gotchas, decisions) that should be findable by meaning, not just keywords.

List memories in the vector store (no embeddings returned, only metadata + content preview). Filter by exact category or category prefix (e.g. 'project::' to list one project's memories); paginate with limit/offset. Returns id + category + source + content preview per row. Use memory_stats for counts/breakdown.

Delete memories from the vector store. Mutually exclusive modes (priority id > category > category_prefix): by id (single row), by exact category (all rows in that category), or by category prefix (batch, e.g. 'test:' to clean test entries, or 'project:oldname:' after migration). Returns count deleted + mode. Idempotent — 0 deleted if no match. Passing no args is a no-op (never full-table delete).

Vector memory store stats: total count, per-category breakdown, embedding dim, model path. For diagnostics and before/after bulk operations. Lazy-loads ONNX+sqlite-vec on first call.

Manually promote a memory to a wider scope (usage-based promotion, manual edition). Changes one memory's category from project:X to platform:Y or global, so future searches find it under the wider scope. Use when an Agent/user judges a project-specific memory is actually cross-project common knowledge. Find the id via memory_list first. Default dry_run=true (preview only, no change) — pass dry_run=false to actually update. to_scope: 'global' | 'platform:' | 'platform:auto' (guess platform from content, fall back to global) | 'project:'. Returns old/new category + whether promoted.

Aggregate runtime stats over the task queue (mem.tasks) — per agent (callee): total calls, success (exit=0), failed, timeout, total retries, avg duration ms. Read-only aggregation of data already in memory.json (run_* / agent_invoke write retries + exit_code + timestamps). For diagnosing rate-limit (429) vs sustained overload: a high failure/timeout rate with many retries signals overload, not a task bug. No args.

Save / list / restore named snapshots of the bridge state (memory.json: task queue + file locks + mailbox; 共享 KV/笔记已外置到 ~/.agents/shared-memory/，不随 checkpoint 回滚). For audit trail and rollback before risky bulk operations. Save: pass name (e.g. 'pre-promotion-batch'). List: pass name='list'. Restore (DANGER: overwrites current state): pass name= + restore=true. Snapshots stored as memory.json.checkpoint. alongside memory.json; do not collide with the live file.

Bare-API vision analysis of an image via vision-LLM (Qwen3-VL-235B-A22B-Instruct on ). For image recognition / scene analysis / reading legible text identifiers. Pass either image_path (local file) or image_data_url (data:...;base64) — not both. Returns a Chinese analysis report. NOTE: this is a scene/text-visibility analyzer, NOT a barcode decoder — high-density barcode VALUES must be decoded by a real decoder (ZXing/Dynamsoft), the VLM cannot. Key read at runtime from opencode.json qwen provider.

Read DeepSeek Harness (DSH) historical sessions. Read-only, delegates to ~/.agents/bin/dsh-read.mjs (zstd-inflate; never mutates DSH data). action='list' lists all sessions (optional keyword filters by title); 'grep ' finds sessions whose title contains keyword; 'get ' prints the session's condensed [user→assistant→tool] dialogue (pass raw=true for original JSONL). Use when asked to recall/show what a DSH chat session did.