deep-execution

エージェント強化型の合議実行

並列で動作する Claude アナリストエージェントの Workflow を 1 つ実行し、より深い分析を行います。各アナリストはプロバイダーに問い合わせ、回答の品質を評価し、追加質問を行うこともできます。また、Workflow がスキーマに照らして検証する、構造化された分析を返します。

ステップ 1：プロバイダーを解決し、質問を記述する

1 回のシェル呼び出しで、Workflow に必要な情報、つまり各プロバイダーのモデル、役割、送信する質問ファイルを解決します。標準フローと同じヘルパーを使用します。最終的な質問は heredoc にそのまま貼り付けてください。引用符付きのマーカーを使うと、シェルは中の引用符、バッククォート、$() を解釈しません。 質問は 1 回だけ出力されます。役割を埋め込んだ各プロバイダー用のバリエーションは、再度貼り付けるのではなく、シェル内で作成されます。

source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/providers.sh"
source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/roles.sh"
PROVIDERS=(<the selected providers, space separated>)
ROLES="<the --roles value, or empty>"
RUN=$(date +%s)                                  # names this run's files; Step 6 reuses it
Q="$PWD/.claude/council-cache/.agents-$RUN"
mkdir -p "$PWD/.claude/council-cache"
# Self-ignoring, as cache.sh and run-council.sh keep it: these files carry the
# question and any --file contents, and must never land in a commit.
[[ -f "$PWD/.claude/council-cache/.gitignore" ]] || printf '*\n' > "$PWD/.claude/council-cache/.gitignore"
cat > "$Q.txt" <<'COUNCIL_Q_EOF'
<the question, verbatim>
COUNCIL_Q_EOF
# --file / auto-context: append the context to the question file here, e.g.
#   { printf '\n\nHere is the content of %s:\n\n```\n' "<path>"; cat "<path>"; printf '```\n'; } >> "$Q.txt"
# An unknown role is refused, as the standard flow refuses it; assigning it
# would hand that provider the bare question under a role heading.
[[ -z "$ROLES" ]] || validate_roles "$ROLES" || exit 1
# The model the ANALYST agents run on — distinct from the provider models below,
# which are what actually answer the question. Pinned rather than inherited: an
# omitted model makes every analyst run on whatever model the user's session
# happens to use, so the cost of a mode that already fans out one agent per
# provider varies by a factor of several for no stated reason. Sonnet handles
# the analyst's work — run a query, judge the answer, emit a structured object.
ANALYST_MODEL="${COUNCIL_AGENT_MODEL:-sonnet}"
case "$ANALYST_MODEL" in
    sonnet|opus|haiku|fable) ;;
    *) echo "COUNCIL_AGENT_MODEL must be one of: sonnet, opus, haiku, fable (got '$ANALYST_MODEL')" >&2; exit 1 ;;
esac
echo "analyst model $ANALYST_MODEL"
ASSIGNMENTS=""
[[ -n "$ROLES" ]] && ASSIGNMENTS=$(assign_roles_to_providers "$ROLES" "${PROVIDERS[@]}")
echo "run $RUN"
for p in "${PROVIDERS[@]}"; do
    role=""
    [[ -n "$ASSIGNMENTS" ]] && role=$(get_provider_role "$p" "$ASSIGNMENTS")
    qf="$Q.txt"
    if [[ -n "$role" ]]; then
        qf="$Q-$p.txt"
        build_prompt_with_role "$(cat "$Q.txt")" "$role" > "$qf"
    fi
    printf '%s\t%s\t%s\n' "$p" "$(get_model "$p")" "$qf"
done

実行 ID、その後にアナリストのモデル、続いてプロバイダーごとに 1 行ずつ、名前、モデル（ステップ 4 のヘッダーに表示されます）、そのプロバイダーの質問ファイルの絶対パスが出力されます。アナリストのモデルは analystModel として Workflow に渡してください。Workflow スクリプトは環境を直接読み取れません。

ステップ 2：アナリスト Workflow を実行する

エージェントモードは 1 つの Workflow です。プロバイダーごとにアナリストエージェントを 1 つずつ並列で実行し、それぞれがスキーマで検証された構造化出力を通じて分析を返します。ユーザーはエージェントモード（--agents、または ask.md のステップ 1.5 のプロンプトに「はい」と回答）を求めています。これは Workflow ツールで必要なオプトインです。

このセッションで Workflow ツールを利用できない場合は、ここで停止してください。ユーザーに、--agents を実行するには Workflow ツールがある Claude Code が必要であることを伝え、代わりに同じ質問を標準モードで実行することを提案してください。別の方法でエージェントを起動することはしないでください。

Read ツールで ${CLAUDE_PLUGIN_ROOT}/schemas/agent-analysis.schema.json を読み取り、次に以下のスクリプトを script として、そのまま Workflow ツールに渡してください。

export const meta = {
  name: 'council-agents',
  description: 'One analyst per council provider: query it, judge the answer, follow up, return a structured analysis',
  phases: [{ title: 'Analyze', detail: 'one analyst agent per provider, in parallel' }],
}
// The tool's schema validator does not know the draft-2020-12 dialect the
// file declares; without the declaration it validates the same keywords fine.
const schema = { ...args.schema }
delete schema.$schema
const template = `${args.pluginRoot}/skills/deep-execution/agent-prompt-template.md`
// Single stage: there is no later step for a finished analyst to move on to,
// so the barrier costs nothing.
const results = await parallel(args.providers.map(p => () =>
  agent(
    `You are the council analyst for the provider "${p.name}".\n` +
    `Read ${template} and carry out every step in it, with these values:\n` +
    `- {PROVIDER} = ${p.name}\n` +
    `- {PLUGIN_ROOT} = ${args.pluginRoot}\n` +
    `- {QUESTION_FILE} = ${p.questionFile}\n` +
    `Your final answer is the Round 3 analysis object, returned through the structured output tool.`,
    { label: p.name, phase: 'Analyze', schema, agentType: 'general-purpose',
      model: args.analystModel })))
// parallel() keeps a dead or skipped analyst's slot as null, index-aligned with args.providers.
const failed = args.providers.filter((_, i) => !results[i]).map(p => p.name)
if (failed.length) log(`no analysis from: ${failed.join(', ')}`)
return {
  // The label goes last so an analyst that emits its own "provider" key cannot rename itself.
  analyses: results.map((a, i) => a && { ...a, provider: args.providers[i].name }).filter(Boolean),
  failed,
}

さらに、以下の args を渡してください（文字列ではなく、実際の JSON 値です。pluginRoot は ${CLAUDE_PLUGIN_ROOT} の実際のパス、questionFile はステップ 1 で出力されたパスです）。

{
  "pluginRoot": "<CLAUDE_PLUGIN_ROOT>",
  "analystModel": "<the model Step 1 printed>",
  "schema": { "...the parsed schema file..." },
  "providers": [
    { "name": "gemini", "questionFile": "<absolute path from Step 1>" }
  ]
}

Workflow は { analyses, failed } を返します。analyses 内のすべてのオブジェクトはスキーマを満たします。failed には、アナリストが停止した、またはスキップされたプロバイダーが記載されます。エラーを返したプロバイダーは failed には含まれません。そのアナリストは、テンプレートの指示に従い、エラーテキストを full_response とする quality: poor、confidence: low の分析を報告します。ステップ 5 では、どちらも同じもの、つまり回答しなかったプロバイダーとして扱います。

ステップ 3：結果を読む

検証は不要です。各分析のフィールドをステップ 4～5 でそのまま使用し、failed はステップ 5 のプロバイダーの失敗情報に引き継いでください。

ステップ 4：結果を表示する

各分析を、以下の形式で表示してください。{MODEL} はステップ 1 のモデルです。アナリスト内でモデルのフォールバックを再実行しても、このヘッダーは変わりません。モデルの変更は分析テキストにのみ表示されます。

## {EMOJI} {PROVIDER} ({MODEL}) — Agent Analysis

**Quality**: {quality} | **Confidence**: {confidence} | **Retried**: {retried}

### Key Recommendations
{recommendations}

### Unique Perspective
{unique_perspective}

### Blind Spots
{blind_spots}

---

<details>
<summary>Full {PROVIDER} Response</summary>

{full_response}

</details>

プロバイダーの絵文字（必ず絵文字とスペースを使用）：

• 🟦 Gemini
• 🔳 OpenAI
• 🟥 Grok
• 🟩 Perplexity

ステップ 5：強化された統合

事前に分析された回答を使い、標準モードよりも充実した統合結果を生成します。${CLAUDE_PLUGIN_ROOT}/prompts/synthesis.md の調整ルールも適用されます。同ファイルの「エラーを返した」ケースには、failed に記載されたプロバイダーと、プロバイダーのエラーを full_response に含むすべての quality: poor の分析が含まれます。これらのプロバイダーを失敗として挙げ、信頼度フィールドの重み付けにかかわらず、コンセンサスから除外してください。

信頼度で重み付けしたコンセンサス

各プロバイダーの信頼度に応じて、意見の一致に重みを付けます。高い信頼度での一致は、低い信頼度での一致よりも強いシグナルです。ただし、それは推論についてのみであり、前提についてではありません。すべてのプロバイダーは、どれも検証できないシステムの同じ説明を読みました。そのため、全員が高い信頼度で一致していても、質問に誤った内容が記載され、各プロバイダーがそれを前提に正しく推論しただけという可能性も同じようにあります。一致が広範かつ高い信頼度に基づく場合は、その旨を述べたうえで、回答全体の前提となっている内容と、それを確認できる立場にいた人がいたかどうかを明示してください。

ブラインドスポット分析

各プロバイダーのブラインドスポットを、他のプロバイダーの推奨事項と照合します。 どのプロバイダーも考慮していないリスクにフラグを立てます。

相違点の背景

プロバイダー間で意見が異なる場合、異なる前提、最適化の目標、リスク許容度など、相違が生じる理由を説明します。

推奨事項

最も有力なアプローチを統合し、それを支持するプロバイダーと各プロバイダーの確信度を記載します。

Step 6: 出力を保存する

出力全体（すべてのプロバイダーの分析と統合結果）を .claude/council-cache/council-agents-{RUN}.md に保存します。RUN は Step 1 で出力された実行 ID です（Step 1 でディレクトリは作成済みです）。次に、この実行の質問ファイルを削除します。これらのファイルは自動では削除されません。

rm -f .claude/council-cache/.agents-{RUN}*

ユーザーに次のように伝えます。

---

エージェントの分析全体を .claude/council-cache/council-agents-{RUN}.md に保存しました

エラー処理

• プロバイダーのアナリストが失敗した場合（failed に記載されています）は、その旨を伝え、他のプロバイダーの処理を続けます
• すべてのアナリストが失敗した場合は、明確に報告し、標準モードへの切り替えを提案します
• 選択されたプロバイダーが 1 つだけで、そのアナリストが失敗した場合は、--agents を付けずに再試行するよう提案します
• ワークフローが強制終了または中断された場合は、同じ引数と、ツールの結果に含まれる scriptPath および resumeFromRunId を指定して再実行することで再開できます。完了済みのアナリストの結果はキャッシュから返されます