Agent dispatch should default to opus (not inherit the session model) — tracking issue-driven-development#205

[kiki830621]

Tracking primary: PsychQuant/issue-driven-development#205
同型問題：plugin 派 agent 未指定 model → 繼承 session 主迴圈模型,高階模型 session 下 quota 炸裂（實證見 primary）。本 repo 的 agent 派發面需同步預設 opus + 覆蓋機制。

Original text:
「這可能也要連帶改parallel-ai-agent這個plugin」
— Source: 使用者訊息 2026-07-02

---

Current Status

• Phase: closed
• Updated: 2026-07-02
• Complexity: Plan · Conflict Class: A_parallel_safe
• Verify: PASS post-fix（0 blocking；DA 質疑被 12/12 transcript 雙重 live 證據駁倒）
• Implementation: 50fb8f3 on idd/20-agent-dispatch-default-opus（TDD 11/11 ensemble tests、17/17 全套件）
• Scope 擴充: 依賴性裁決已定案（diagnosis）；IDD 側切換 → issue-driven-development#207
• Diagnosis: Agent dispatch should default to opus (not inherit the session model) — tracking issue-driven-development#205 #20 (comment)

[kiki830621]

Decision（scope 擴充 — 依賴性裁決）

Original text:
「等一下，idd不是應該要依賴 parallel-ai-agents嗎？現在是不是沒有完全依賴，而有太多hard-coded的東西。 需要官方就直接依賴」
— Source: 使用者訊息 2026-07-02（/idd-all 呼叫時附帶）

解讀：本 issue 原 scope 是「pai 的派發面同步預設 opus」。使用者追加架構性裁決——若 parallel-ai-agents 是 ensemble 的官方 canonical 實作，issue-driven-development 的 idd-verify 不該維護自己 hard-coded 的複本，應直接依賴。diagnose 需以證據回答：(1) 兩邊 ensemble 實作的重複程度；(2) 直接依賴的可行機制與代價；(3) 落地切分（本 repo vs IDD repo 的工作邊界）。

—— /idd-comment type:decision @ 2026-07-02

[kiki830621]

Diagnosis

對使用者依賴性問題的證據答案

「idd 是不是沒有完全依賴 pai、有太多 hard-coded？」——是，證據如下：

面向	pai workflows/ensemble-workflow.js（513 行）	IDD skills/idd-verify/ensemble-workflow.js（305 行）
血緣	canonical 泛化引擎（header 自述 "mirrors idd-verify design D2"）	窄化 fork（固定 4 lens + DA + codex）
findings schema	severity enum CRITICAL..INFO + lens/title/file/body	同構（重複維護）
fail-closed integrity	有（缺 core lens → HIGH integrity finding）	有（重複實作）
merge/dedup、verdict	有	有（重複實作）
untrusted-content sentinel	dataBlock() PAI_ENSEMBLE markers + stripping + treat-as-DATA guard	同型自製 sentinel（重複實作）
泛化能力	profiles / replicas / include+disable+customLenses / maxAgents / priors / daFocus / codexInstructions	無（hard-coded）
regression tests	test/ensemble-workflow.test.mjs（mock agent、實跑 script）	無
#205 model-default bug	同樣存在（3 站點無 model opt）	已修（#205）

fork 重複的直接代價就是本 issue：同一個 bug 兩邊各要修一次。IDD 需要而 pai 缺的能力＝零（issues 注入可由 consumer sentinel-wrap 後走 contextBlock；4 lens 可用 customLenses/profile:'custom' 表達；diff 走 diffFile）。pai 已以 parallel-ai-agents@parallel-ai-agents 安裝（v2.17.0），依賴解析可走 plugin cache 路徑 + graceful degrade（同 idd-all #28 ralph-loop gate 前例）。

Clarity：唯一歧義「官方＝？」已由使用者裁決錨定（見 decision comment：「idd不是應該要依賴 parallel-ai-agents嗎…需要官方就直接依賴」→ 官方 canonical＝pai）。

Root Cause

（tracking 同型）pai 的 3 個 agent() 站點（reviewPrompt ×replicas / codex / DA，workflows/ensemble-workflow.js:451,465,477）皆未帶 opts.model → 繼承 session 主迴圈模型；高階 session 下 quota 炸裂（實證見 primary issue-driven-development#205：563k–1,092k tokens/輪、DA 死於 session limit）。

Strategy（scope 切分——尊重 repo 邊界）

本 issue（pai repo，本 pipeline 實作）：

• 引擎：args.agentModel（whitelist sonnet|opus|haiku|fable；absent → 'opus'；顯式非法值於派發前 throw——兩層 fail-loud 同 #205 定案）；3 站點 model: AGENT_MODEL；回傳/stats 揭露 dispatchModel
• Consumer 面：5 個 ensemble-* skill 解析 PAI_AGENT_MODEL（pai 自己的 namespace；unset → opus、非法 → abort with usage error）傳入 agentModel
• TDD：test/ensemble-workflow.test.mjs 先加斷言（預設全站點 opus、覆蓋值生效、非法值 throw、dispatchModel 揭露）再改引擎
• 官方化 external-consumer 契約：header/README 明文 args surface 為穩定 API（IDD 依賴的接口）— 全項 done：13/13 ensemble tests + 17/17 全套件；#207 Tier-1 live smoke 以此契約全項實證（run wf_27d7d3dd-c35）
  IDD repo（另立 issue 追蹤，不在本 pipeline 實作）：idd-verify 改為解析已安裝 pai 引擎（plugin cache 版本發現 + graceful degrade → 現有 vendored copy 降級為 fallback-only），lens/DA/codex 組態以 args 表達，IDD_AGENT_MODEL 值直傳 agentModel。

Complexity

Plan（pai repo 無 Spectra 設施；機械修改 + 測試桁架既存 + 契約文件；TDD 可行）

Conflict Class

A_parallel_safe（單 repo；與在飛工作無共享資源）

Residue

• IDD-side 依賴切換為獨立 issue（本 diagnosis Strategy 已定義接口）——實作後 IDD 的 vendored fork 退役為 fallback
• pai 的 [P]-style 其他派發面（skills 內 prose 派發）依 #205 教訓做雙軌掃描，若有未指定站點一併修

[kiki830621]

Verify: #20

Engine

dynamic-workflow backend（idd-verify 2.88.0 引擎，dispatch model: opus——6/6 完整、0 process gap）。本輪本身即為 #205 修復的第二次 self-dogfood：session 為 claude-fable-5[1m]，六個 agent transcript 全記錄 model=claude-opus-4-8。

要求覆蓋率

4/4（引擎 model-default、5 skills consumer 面、契約官方化、TDD）——requirements lens 判定「fully and correctly covered；scope 與 #20/#207 切分吻合、無 creep」。

Findings（合併後 18 筆，triage）

#	Sev	Finding	Action
1/8/11/17	MED+2LOW+INFO	兩條 early-return 的 stats 缺 dispatchModel（vs 官方化 return-shape 契約；DA 補充框架：early-return 本就是縮減子集，屬 polish）	Fixed（兩處補齊 + 測試鎖定）
2/12	MED (DA)+LOW	「agent() 吃不吃 model 完全未證，mock 測試結構性抓不到 silent no-op」	REFUTED（雙重一手證據）：wf_6c1d8ee6-5f3 + wf_d44fa55e-65a（本 verify 輪自身）皆為 fable session + agentModel:'opus' → 12/12 transcript 記錄 claude-opus-4-8。同一 runtime、同一 opts 契約。證據 + request-echo caveat（過舊 runtime 忽略 opts.model 時 dispatchModel 為請求回聲）已記入引擎 header
3/9/14	3×LOW	null / '' 的 absent-vs-invalid 歧義（空字串 hard-throw 違反 (unset = opus) 暗示；PAI_AGENT_MODEL= 空值會炸）	Fixed：null/'' ≡ absent → opus；僅非空非法字串 throw；測試鎖定兩案例
4/7/13	3×LOW	Legacy Backend-B 只有 prose 提醒，具體 Agent 範本沒有 model 欄位 → fallback 路徑可能回歸	Fixed：13 個 YAML 範本 + lecture 的 CRITICAL 行 + compose prose 全部帶具體 model 欄位
5	LOW	CHANGELOG 在 [Unreleased] 但 manifest 已 2.18.0	Fixed（滾版 ## [2.18.0] - 2026-07-02）
6	LOW	不支援 opts.model 的舊 runtime 行為 + error message 插值污染	Fixed：header 註明 degrade 行為；error 改 JSON.stringify（換行/引號逃逸）
15	LOW (DA)	throw 是唯一 out-of-band exit，STABLE 契約未描述（其他 guard 都回 findings-shape）	Fixed：契約 note 明文「invalid agentModel 為文件化的 arg-contract throw，要 soft failure 請先自行驗證」
10	LOW	whitelist 是 runtime enum 的靜態鏡像，無法保證長期同步	Documented（維護點註解；runtime enum 變動時同步——已知限制）
18	INFO (DA)	codex lens 的 model 只 pin Claude wrapper，跨模型推理仍是 gpt-5.5	Documented（header 註記；by design——跨模型 lens 本就刻意不同 family）
16	INFO	STABLE API 只在 JS header + CHANGELOG，無獨立 reference 文件	Noted：正式 reference 文件屬 IDD 依賴落地（issue-driven-development#207）的接口工作一併處理

In-scope fixes

2 commits：50fb8f3（TDD 實作）+ 67459da（verify fixes）。測試 13/13 ensemble（5 個 #20 新案例）、17/17 全套件。

Residue

• issue-driven-development#207 — IDD 依賴切換（vendored fork 退役），本 issue 官方化的契約是其接口
• whitelist ↔ runtime enum 同步為長期維護點（已註解標記）

Result

PASS（verify-gated, post-fix） — 0 blocking。

[kiki830621]

Closing Summary

Problem

pai 的 ensemble 引擎三個 agent() 站點（lens reviewers ×replicas / codex runner / devil's-advocate）皆未帶 opts.model → 繼承 session 主迴圈模型；高階（Fable 級）session 下單輪 ensemble 563k–1,092k tokens、lens agent 曾死於 session limit（primary：issue-driven-development#205）。process 中使用者追加架構裁決：「idd不是應該要依賴 parallel-ai-agents嗎…需要官方就直接依賴」→ 本 issue 同時官方化 external-consumer 契約。

Root Cause

Workflow agent() 語意「省略 model → 繼承主迴圈」，全部派發站點都省略了；且 IDD 與 pai 各養一份 fork，同一 bug 要修兩次——重複維護正是使用者裁決要根除的。

Solution

（squash 8083986，2 commits）

• 引擎：args.agentModel（whitelist；null/''/absent → opus；顯式非法值於任何派發前 throw，error JSON-stringify 防污染）；3 站點 model: AGENT_MODEL；stats.dispatchModel 揭露（含兩條 early-return 路徑）；throw 明文為契約唯一 out-of-band exit
• Consumer 面：5 個 ensemble-* skill 解析 PAI_AGENT_MODEL 傳 agentModel；13 個 legacy Backend-B Agent 範本 + lecture CRITICAL 行帶具體 model 欄位（prose 提醒不夠，可複製範本才會被照抄）
• 契約官方化：header EXTERNAL-CONSUMER CONTRACT（args surface + return shape = STABLE API，破壞性變更需 major bump）+ MODEL-ROUTING CONFIRMED LIVE 證據段
• 2.17.0 → 2.18.0

Verification

TDD 先行（3 個 RED 測試先失敗後通過）+ verify 輪 2 個新增案例 → 13/13 ensemble tests、17/17 全套件。6-AI verify（self-dogfood：verify 自身以 agentModel:'opus' 派發）→ DA「model opt 未證」被雙 live run 駁倒（12/12 transcript 實跑 claude-opus-4-8）。契約以 IDD#207 的 Tier-1 smoke 全項實證（run wf_27d7d3dd-c35：customLenses attribution / contextBlock 送達 / 巢狀 stats.dispatchModel / 5×opus）。Master report：#20 issuecomment-4863436998。

Changes

• PR feat: explicit dispatch model for every ensemble agent — default opus, PAI_AGENT_MODEL override (#20) #21（squash → 8083986）
• 註 1：merge-completeness gate rc=3 為 squash 下 intra-branch supersession 假陽性（67459da 改寫 50fb8f3 的 guard/stats 行）——已機械驗證 main（6 個 model/dispatchModel 站點、2.18.0 manifest）
• 註 2：Diagnosis Residue 兩項處置——(a) IDD 依賴切換：已於 issue-driven-development#207 立案、實作、verified（PR #208）；(b) 其他派發面雙軌掃描：done（TeamCreate fallback 範本全數帶 model）

Distribution Sync

chain 2.18.0：marketplace.json 已隨 merge 進 main（2.18.0），本次同步 marketplace cache + 更新已安裝 plugin——這一步使 IDD#207 的 canonical 路徑點亮（版本閘門 >= 2.18.0 自此通過）。