claude-code-conductor 2.20.0__tar.gz → 2.21.0__tar.gz

{claude_code_conductor-2.20.0 → claude_code_conductor-2.21.0}/.claude/hooks/session_stop.py

@@ -89,6 +89,23 @@ def main() -> int:
     except Exception as e:
         print(f"[session_stop:consolidate_memory] failed: {e}", file=sys.stderr)
 
+    # Phase 3: usage_ingester — セッションログからコスト集計データを ingestion
+    # worktree session では起動しない（stop.run の is_worktree 判定と整合）
+    # 安全側動作: session_utils ロード失敗時や is_worktree 判定失敗時は ingester をスキップする。
+    # worktree 判定不能で誤起動するより skip を優先（except Exception で捕捉 → 早期終了）。
+    try:
+        session_utils_module = _load_module("session_utils")
+        if not session_utils_module.is_worktree(os.getcwd()):
+            session_id = payload.get("session_id")
+            transcript_path = payload.get("transcript_path")
+            if session_id and transcript_path:
+                from pathlib import Path as _Path  # noqa: PLC0415
+                from c3.usage_ingester import ingest_session  # noqa: PLC0415
+                project_dir = _Path(transcript_path).parent
+                ingest_session(session_id=session_id, project_dir=project_dir)
+    except Exception as e:
+        print(f"[session_stop:usage_ingester] failed: {type(e).__name__}", file=sys.stderr)
+
     return 0
 
 

{claude_code_conductor-2.20.0 → claude_code_conductor-2.21.0}/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## [2.21.0] - 2026-05-25
+
+**tier-routing コスト統合（データ収集基盤）**: Claude Code セッションログ（`~/.claude/projects/<slug>/<session>.jsonl` + subagent jsonl）を読み込み、モデル単価で USD 換算して c3.db に蓄積するデータ収集基盤を整備する。将来の cost-aware routing（v2.22.0）の土台。
+
+**スコープ注記**: 本リリースはデータ収集基盤のみ。cost-aware routing と tier_bandit のコスト列は v2.22.0 予定。
+
+### 機能追加
+
+- **`src/c3/pricing.py`（新規）**: Claude API モデルの USD/MTok 単価から token コストを計算する純関数モジュール。
+  `resolve_tier(model)`・`compute_cost_usd(...) -> tuple[float, bool]`・`known_models()` を提供。
+  Opus は世代で単価が 3 倍異なる（4.1/4=$15 系、4.5/4.6/4.7=$5 系）ため、具体パターン優先マッチ → tier 部分一致 fallback の 2 段構成を採用。
+  単価は 2026-05-25 公式取得値（出典 URL を docstring に明記）。
+
+- **`src/c3/migrations/002_agent_cost_runs.sql`（新規）**: `agent_cost_runs` テーブル・`usage_ingest_state` テーブル・インデックスを追加する migration。
+  PK=(session_id, agent_id, model) で「1 エージェント × 1 モデル = 1 行」の集約設計。
+  既存 event-based `agent_runs`（001）は一切変更しない。
+
+- **`src/c3/usage_ingester.py`（新規）**: セッションログ取り込みモジュール。
+  公開 API `ingest_session(*, session_id, project_dir, db_path=None) -> IngestResult`。
+  mainline / subagent jsonl を走査し、model 単位でトークンを合算して `insert_agent_cost_run` で upsert する。
+  session_id UUID validate・パストラバーサル防止・symlink スキップ・例外 type 名のみログ（SR-R-001 準拠）。
+
+- **`.claude/hooks/session_stop.py` Phase 3 追加**: セッション終了時に `ingest_session` を呼ぶ Phase 3 を追加。
+  worktree session では起動しない。例外握りつぶしで exit 0 を維持する。
+
+- **`c3 tier stats` の Agent 別コスト集計セクション追加**: `_collect_snapshot()` に `read_agent_cost_summary()` を追加し、human / JSON 両出力に `agent_cost` セクションを表示する。
+  mainline 行には「（マクロ集計・tier 学習対象外）」を明示。0 件のときは「（コストデータ未収集）」を表示。
+
+### 変更
+
+- **`src/c3/db.py`**: 4 ヘルパー追加（`insert_agent_cost_run` / `read_agent_cost_summary` / `get_ingest_offset` / `set_ingest_offset`）。既存 tier ヘルパー規約（DB 不在で静かに False/0/[]・WAL・busy_timeout）に準拠。
+
+- **`src/c3/__init__.py`**: `__version__` を `"2.20.0"` から `"2.21.0"` に更新。
+
 ## [2.20.0] - 2026-05-25
 
 **SQLite schema migration 枠組み導入**: `.claude/hooks/schema.sql` の「冪等 DDL 一発実行」から、`src/c3/migrations/` の「連番 NNN_xxx.sql migration runner」へ移行する基盤を整備する。

{claude_code_conductor-2.20.0 → claude_code_conductor-2.21.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-code-conductor
-Version: 2.20.0
+Version: 2.21.0
 Summary: Multi-agent orchestration framework for Claude Code with Codex/Cursor adapters (C3)
 Project-URL: Homepage, https://github.com/satoh-y-0323/claude-code-conductor
 Project-URL: Repository, https://github.com/satoh-y-0323/claude-code-conductor

{claude_code_conductor-2.20.0 → claude_code_conductor-2.21.0}/src/c3/__init__.py

@@ -1,3 +1,3 @@
 """Claude Code Conductor (C3) - multi-agent orchestration framework for Claude Code."""
 
-__version__ = "2.20.0"
+__version__ = "2.21.0"

{claude_code_conductor-2.20.0 → claude_code_conductor-2.21.0}/src/c3/cli_tier.py

@@ -89,7 +89,7 @@ def handle_stats(args: argparse.Namespace) -> int:
 
 
 def _collect_snapshot(db_path, recent_limit: int) -> dict[str, Any]:
-    """DB から tier_bandit / tier_recent_outcomes を読み snapshot dict を返す。"""
+    """DB から tier_bandit / tier_recent_outcomes / agent_cost を読み snapshot dict を返す。"""
     bandit_rows: list[dict[str, Any]] = []
     total_trials = 0
 
@@ -114,6 +114,8 @@ def _collect_snapshot(db_path, recent_limit: int) -> dict[str, Any]:
         db_path=db_path,
     )
 
+    agent_cost: list[dict[str, Any]] = c3_db.read_agent_cost_summary(db_path=db_path)
+
     if total_trials < _LEARNING_THRESHOLD:
         mode = "uniform"
     else:
@@ -127,6 +129,7 @@ def _collect_snapshot(db_path, recent_limit: int) -> dict[str, Any]:
         },
         "tier_bandit": bandit_rows,
         "recent_outcomes": recent_outcomes,
+        "agent_cost": agent_cost,
     }
 
 
@@ -166,3 +169,25 @@ def _render_human(snapshot: dict[str, Any]) -> None:
     print("== 学習データ記録チャネル ==")
     print("記録元: dev-workflow フェーズ E の最終承認時のみ（record_tier_outcome.py）")
     print("直接指示作業ではデータが溜まりません（設計通り）")
+    print()
+
+    print("== Agent 別コスト集計（agent_cost_runs） ==")
+    agent_cost = snapshot.get("agent_cost", [])
+    if not agent_cost:
+        print("（コストデータ未収集）")
+    else:
+        print(
+            f"{'agent_type':<16} {'runs':>5}  {'total_usd':>10}  "
+            f"{'in_tok':>9}  {'out_tok':>9}  {'cache_r':>9}  {'cache_w':>9}"
+        )
+        for row in agent_cost:
+            note = "  （マクロ集計・tier 学習対象外）" if row["agent_type"] == "mainline" else ""
+            print(
+                f"{row['agent_type']:<16} {row['runs']:>5}  "
+                f"${row['total_cost_usd']:>9.4f}  "
+                f"{row['input_tokens']:>9}  {row['output_tokens']:>9}  "
+                f"{row['cache_read_tokens']:>9}  {row['cache_create_tokens']:>9}"
+                f"{note}"
+            )
+    print()
+    print("（注: 本リリースはデータ収集基盤のみ。cost-aware routing は v2.22.0 予定）")

{claude_code_conductor-2.20.0 → claude_code_conductor-2.21.0}/src/c3/db.py

@@ -493,3 +493,250 @@ def read_tier_failure_rate(
 
     failures = sum(1 for r in rows if r[0] == 0)
     return failures / sample_count, sample_count
+
+
+# ---------------------------------------------------------------------------
+# usage-ingester: agent_cost_runs / usage_ingest_state ヘルパー（v2.21.0）
+# ---------------------------------------------------------------------------
+
+
+def insert_agent_cost_run(
+    *,
+    session_id: str,
+    agent_id: str,
+    agent_type: str,
+    description: str | None,
+    model: str,
+    attribution_skill: str | None,
+    input_tokens: int,
+    output_tokens: int,
+    cache_read_tokens: int,
+    cache_create_tokens: int,
+    total_cost_usd: float,
+    db_path: Path | None = None,
+) -> bool:
+    """agent_cost_runs に 1 行 upsert する。
+
+    PK=(session_id, agent_id, model) で「1 エージェント × 1 モデル = 1 行」。
+    同一 PK が既に存在する場合は全数値列・total_cost_usd・recorded_at を最新合算値に上書き。
+
+    Args:
+        session_id: セッション UUID。
+        agent_id: 'agent-<id>' または 'mainline'。
+        agent_type: meta.json の agentType / 'mainline'。
+        description: meta.json の description（任意）。
+        model: message.model 文字列。
+        attribution_skill: assistant レコードの attributionSkill（任意）。
+        input_tokens: 入力トークン数（jsonl 内合算値）。
+        output_tokens: 出力トークン数（jsonl 内合算値）。
+        cache_read_tokens: キャッシュ読み込みトークン数（jsonl 内合算値）。
+        cache_create_tokens: キャッシュ書き込みトークン数（jsonl 内合算値）。
+        total_cost_usd: compute_cost_usd が返した USD コスト。
+        db_path: c3.db のパス。省略時は locate_c3_db() で探索。
+
+    Returns:
+        upsert 成功時 True、DB 不在 / sqlite3.Error 時は静かに False。
+    """
+    if db_path is None:
+        db_path = locate_c3_db()
+        if db_path is None:
+            return False
+
+    from datetime import timezone as _tz  # noqa: PLC0415
+    now_iso = datetime.now(_tz.utc).isoformat(timespec="seconds")
+
+    try:
+        conn = sqlite3.connect(str(db_path))
+        try:
+            conn.execute("PRAGMA journal_mode=WAL")
+            _apply_busy_timeout(conn)
+            conn.execute(
+                "INSERT INTO agent_cost_runs "
+                "(session_id, agent_id, agent_type, description, model, "
+                " attribution_skill, input_tokens, output_tokens, "
+                " cache_read_tokens, cache_create_tokens, "
+                " total_cost_usd, recorded_at) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) "
+                "ON CONFLICT(session_id, agent_id, model) DO UPDATE SET "
+                "  agent_type = excluded.agent_type, "
+                "  description = excluded.description, "
+                "  attribution_skill = excluded.attribution_skill, "
+                "  input_tokens = excluded.input_tokens, "
+                "  output_tokens = excluded.output_tokens, "
+                "  cache_read_tokens = excluded.cache_read_tokens, "
+                "  cache_create_tokens = excluded.cache_create_tokens, "
+                "  total_cost_usd = excluded.total_cost_usd, "
+                "  recorded_at = excluded.recorded_at",
+                (
+                    session_id, agent_id, agent_type, description, model,
+                    attribution_skill, input_tokens, output_tokens,
+                    cache_read_tokens, cache_create_tokens,
+                    total_cost_usd, now_iso,
+                ),
+            )
+            conn.commit()
+        finally:
+            conn.close()
+        return True
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("failed to insert_agent_cost_run: %s", type(exc).__name__)
+        return False
+
+
+def read_agent_cost_summary(
+    *,
+    db_path: Path | None = None,
+    limit: int = 50,
+) -> list[dict]:
+    """agent_cost_runs を agent_type 別に集計した結果を返す。
+
+    SELECT agent_type, COUNT(*) runs, SUM(total_cost_usd), SUM(input_tokens),
+    SUM(output_tokens), SUM(cache_read_tokens), SUM(cache_create_tokens)
+    FROM agent_cost_runs GROUP BY agent_type ORDER BY total_cost_usd DESC LIMIT ?
+
+    Args:
+        db_path: c3.db のパス。省略時は locate_c3_db() で探索。
+        limit: 返す最大件数（デフォルト 50）。
+
+    Returns:
+        各行を dict にしたリスト。キー:
+        ``agent_type`` / ``runs`` / ``total_cost_usd`` /
+        ``input_tokens`` / ``output_tokens`` /
+        ``cache_read_tokens`` / ``cache_create_tokens``。
+        DB 不在 / テーブル不在 / エラー時は空リスト。
+    """
+    if db_path is None:
+        db_path = locate_c3_db()
+        if db_path is None:
+            return []
+
+    try:
+        conn = sqlite3.connect(str(db_path))
+        try:
+            # WAL は書き込みヘルパー呼び出し時または migrate 時に設定済みの前提
+            # （既存 read_recent_outcomes 等の read ヘルパーと同方針 / CR-M-001）
+            _apply_busy_timeout(conn)
+            rows = conn.execute(
+                "SELECT agent_type, "
+                "       COUNT(*) AS runs, "
+                "       SUM(total_cost_usd) AS total_cost_usd, "
+                "       SUM(input_tokens) AS input_tokens, "
+                "       SUM(output_tokens) AS output_tokens, "
+                "       SUM(cache_read_tokens) AS cache_read_tokens, "
+                "       SUM(cache_create_tokens) AS cache_create_tokens "
+                "FROM agent_cost_runs "
+                "GROUP BY agent_type "
+                "ORDER BY total_cost_usd DESC "
+                "LIMIT ?",
+                (limit,),
+            ).fetchall()
+        finally:
+            conn.close()
+    except sqlite3.OperationalError as exc:
+        # テーブル不在（no such table）は [] を返す（DB 未初期化でも止めない）
+        logger.debug(
+            "read_agent_cost_summary: table not found or inaccessible: %s",
+            type(exc).__name__,
+        )
+        return []
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("read_agent_cost_summary: unexpected error: %s", type(exc).__name__)
+        return []
+
+    return [
+        {
+            "agent_type": row[0],
+            "runs": row[1],
+            "total_cost_usd": row[2],
+            "input_tokens": row[3],
+            "output_tokens": row[4],
+            "cache_read_tokens": row[5],
+            "cache_create_tokens": row[6],
+        }
+        for row in rows
+    ]
+
+
+def get_ingest_offset(
+    file_key: str,
+    *,
+    db_path: Path | None = None,
+) -> int:
+    """usage_ingest_state から処理済み行数（offset）を返す。
+
+    Args:
+        file_key: '<session>:mainline' / '<session>:agent-<id>'。
+        db_path: c3.db のパス。省略時は locate_c3_db() で探索。
+
+    Returns:
+        処理済み行数。行・テーブル不在・DB 不在は 0 を返す。
+    """
+    if db_path is None:
+        db_path = locate_c3_db()
+        if db_path is None:
+            return 0
+
+    try:
+        conn = sqlite3.connect(str(db_path))
+        try:
+            # WAL は書き込みヘルパー呼び出し時または migrate 時に設定済みの前提
+            # （既存 read_recent_outcomes 等の read ヘルパーと同方針 / CR-M-001）
+            _apply_busy_timeout(conn)
+            row = conn.execute(
+                "SELECT last_offset FROM usage_ingest_state WHERE file_key = ?",
+                (file_key,),
+            ).fetchone()
+        finally:
+            conn.close()
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("get_ingest_offset: %s", type(exc).__name__)
+        return 0
+
+    return row[0] if row is not None else 0
+
+
+def set_ingest_offset(
+    file_key: str,
+    offset: int,
+    *,
+    db_path: Path | None = None,
+) -> bool:
+    """usage_ingest_state に offset を upsert する。
+
+    Args:
+        file_key: '<session>:mainline' / '<session>:agent-<id>'。
+        offset: 処理済み行数（= 次回開始行）。
+        db_path: c3.db のパス。省略時は locate_c3_db() で探索。
+
+    Returns:
+        upsert 成功時 True、DB 不在 / エラー時は静かに False。
+    """
+    if db_path is None:
+        db_path = locate_c3_db()
+        if db_path is None:
+            return False
+
+    from datetime import timezone as _tz  # noqa: PLC0415
+    now_iso = datetime.now(_tz.utc).isoformat(timespec="seconds")
+
+    try:
+        conn = sqlite3.connect(str(db_path))
+        try:
+            conn.execute("PRAGMA journal_mode=WAL")
+            _apply_busy_timeout(conn)
+            conn.execute(
+                "INSERT INTO usage_ingest_state "
+                "(file_key, last_offset, last_processed_at) "
+                "VALUES (?, ?, ?) "
+                "ON CONFLICT(file_key) DO UPDATE SET "
+                "  last_offset = excluded.last_offset, "
+                "  last_processed_at = excluded.last_processed_at",
+                (file_key, offset, now_iso),
+            )
+            conn.commit()
+        finally:
+            conn.close()
+        return True
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("failed to set_ingest_offset: %s", type(exc).__name__)
+        return False

claude_code_conductor-2.21.0/src/c3/migrations/002_agent_cost_runs.sql

@@ -0,0 +1,41 @@
+-- C3 SQLite migration 002: agent_cost_runs / usage_ingest_state テーブル追加
+--
+-- セッションログ（~/.claude/projects/<slug>/<session>.jsonl + subagents/）から
+-- モデル別トークン消費を USD 換算して蓄積するコスト収集基盤テーブルを定義する。
+--
+-- PK=(session_id, agent_id, model) で「1 エージェント × 1 モデル = 1 行」。
+-- jsonl 内の複数 requestId は ingester（usage_ingester.py）が合算 upsert する。
+--
+-- usage_ingest_state は jsonl ごとの処理済み行数 offset を管理する。
+-- file_key = '<session>:mainline' / '<session>:agent-<id>'
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS agent_cost_runs (
+  session_id          TEXT NOT NULL,
+  agent_id            TEXT NOT NULL,              -- 'agent-<id>' / mainline は 'mainline'
+  agent_type          TEXT NOT NULL,              -- meta.json agentType / 'mainline'
+  description         TEXT,
+  model               TEXT NOT NULL,              -- message.model
+  attribution_skill   TEXT,
+  input_tokens        INTEGER NOT NULL DEFAULT 0,
+  output_tokens       INTEGER NOT NULL DEFAULT 0,
+  cache_read_tokens   INTEGER NOT NULL DEFAULT 0,
+  cache_create_tokens INTEGER NOT NULL DEFAULT 0,
+  total_cost_usd      REAL NOT NULL,
+  recorded_at         TEXT NOT NULL,              -- ISO8601 UTC
+  PRIMARY KEY (session_id, agent_id, model)
+);
+
+CREATE INDEX IF NOT EXISTS idx_agent_cost_runs_agent_type
+  ON agent_cost_runs(agent_type, recorded_at);
+
+CREATE TABLE IF NOT EXISTS usage_ingest_state (
+  file_key            TEXT PRIMARY KEY,           -- '<session>:mainline' / '<session>:agent-<id>'
+  last_offset         INTEGER NOT NULL,           -- 処理済み行数
+  last_processed_at   TEXT NOT NULL               -- ISO8601 UTC
+);
+
+INSERT OR IGNORE INTO schema_migrations (version) VALUES ('002');
+
+COMMIT;

claude_code_conductor-2.21.0/src/c3/pricing.py

@@ -0,0 +1,157 @@
+"""Claude API モデルの USD/MTok 単価からトークンコストを計算する純関数モジュール。
+
+出典: https://platform.claude.com/docs/en/about-claude/pricing
+取得日: 2026-05-25
+
+単価は改定されうるため、メンテ時はこの URL を再確認すること。
+（本モジュールの _PRICING dict と docstring の日付を合わせて更新する）
+
+公開 API:
+  - resolve_tier(model) -> str | None
+  - compute_cost_usd(...) -> tuple[float, bool]
+  - known_models() -> tuple[str, ...]
+
+設計判断（plan-report T1 §2):
+  Opus は世代で単価が約 3 倍異なる（4.1/4 = $15 系、4.5/4.6/4.7 = $5 系）ため、
+  単純な "opus" 部分一致では取り違える。
+  「現行世代を列挙マッチ → それ以外の opus は旧世代」の 2 段構成で実装する。
+  具体的には: model に "opus-4-[5-9]" にマッチする場合は現行 ($5 系)、
+  それ以外の opus（"claude-opus-4-YYYYMMDD" 形式の初代 Opus 4 / 4.1 等）は旧世代 ($15 系)。
+  将来 Opus メジャー更新（5.x 等）が出たら本判定と _PRICING の見直しが必要。
+  haiku は "haiku-3" を含む場合は旧世代。
+"""
+
+from __future__ import annotations
+
+import re
+
+# ---------------------------------------------------------------------------
+# 単価表 (USD/MTok)  取得日: 2026-05-25
+# キー = pricing tier 識別子（resolve_pricing_key() が返す文字列）
+# 値 = (input, output, cache_5m_write, cache_read)
+# ---------------------------------------------------------------------------
+# 現行世代（C3 が実際に使うモデル）
+# 旧世代（過去ログ互換・現行 C3 では通常出現しない）
+
+# 現行 Opus 世代（$5 系）: 4.5 / 4.6 / 4.7（将来 4.8/4.9 も同単価想定）
+# それ以外の opus（初代 Opus 4 "claude-opus-4-YYYYMMDD" / 4.1 等）は旧世代 $15 系とする。
+_CURRENT_OPUS_RE = re.compile(r"opus-4-[5-9]")
+
+_PRICING: dict[str, tuple[float, float, float, float]] = {
+    "opus-4-5":   (5.0,   25.0,  6.25, 0.50),   # Opus 4.5 / 4.6 / 4.7 共通
+    "sonnet-4-5": (3.0,   15.0,  3.75, 0.30),   # Sonnet 4.5 / 4.6 共通
+    "haiku-4-5":  (1.0,    5.0,  1.25, 0.10),   # Haiku 4.5
+    "opus-4-1":   (15.0,  75.0, 18.75, 1.50),   # Opus 4.1 / 4（旧世代）
+    "haiku-3-5":  (0.80,   4.0,  1.00, 0.08),   # Haiku 3.5（旧世代）
+}
+
+
+def resolve_tier(model: str) -> str | None:
+    """model 文字列から tier 名を返す（集計・表示用グルーピング）。
+
+    Args:
+        model: message.model 文字列（例: "claude-opus-4-7-20260101"）
+
+    Returns:
+        "opus" / "sonnet" / "haiku" のいずれか。
+        いずれも含まなければ None。
+
+    Note:
+        単価の世代振り分けには使わない。世代判定は _resolve_pricing_key() が担当する。
+    """
+    lower = model.lower()
+    if "opus" in lower:
+        return "opus"
+    if "sonnet" in lower:
+        return "sonnet"
+    if "haiku" in lower:
+        return "haiku"
+    return None
+
+
+def _resolve_pricing_key(model: str) -> str | None:
+    """model 文字列を _PRICING キーに解決する（内部関数）。
+
+    2 段構成で世代を振り分ける:
+    1. 具体パターン優先マッチ: Opus 旧世代 / Haiku 旧世代
+    2. tier 部分一致 fallback: 現行世代
+
+    Args:
+        model: message.model 文字列
+
+    Returns:
+        _PRICING のキー文字列。既知モデルでなければ None。
+    """
+    lower = model.lower()
+
+    # ---- Opus: 世代判定が必要 ----
+    if "opus" in lower:
+        # 現行世代（$5 系: 4.5/4.6/4.7）を列挙マッチ
+        # それ以外（初代 Opus 4 "claude-opus-4-YYYYMMDD" / 4.1 等）は旧世代 ($15 系)
+        if _CURRENT_OPUS_RE.search(lower):
+            return "opus-4-5"   # 現行 $5 系
+        return "opus-4-1"       # 旧世代 $15 系（4.0/4.1/初代 Opus 4 等）
+
+    # ---- Haiku: 世代判定が必要 ----
+    if "haiku" in lower:
+        # "haiku-3" を含めば旧世代 ($0.80 系)
+        if "haiku-3" in lower:
+            return "haiku-3-5"
+        # それ以外（haiku-4-5 等）は現行
+        return "haiku-4-5"
+
+    # ---- Sonnet: 世代で単価不変 ($3 系) ----
+    if "sonnet" in lower:
+        return "sonnet-4-5"
+
+    return None
+
+
+def compute_cost_usd(
+    *,
+    model: str,
+    input_tokens: int,
+    output_tokens: int,
+    cache_read_tokens: int,
+    cache_create_tokens: int,
+) -> tuple[float, bool]:
+    """トークン数から USD コストを計算する純関数。
+
+    Args:
+        model: message.model 文字列（例: "claude-opus-4-7-20260101"）
+        input_tokens: 入力トークン数
+        output_tokens: 出力トークン数
+        cache_read_tokens: キャッシュ読み込みトークン数
+        cache_create_tokens: キャッシュ書き込みトークン数（5 分キャッシュ単価を採用）
+
+    Returns:
+        (cost_usd, known) のタプル。
+        - cost_usd: 計算した USD コスト（不明モデルは 0.0）
+        - known: 単価が解決できた場合 True、不明モデルは False
+
+    Note:
+        不明モデルは (0.0, False) を返す。例外も warning も出さない。
+        換算式: tokens / 1_000_000 * unit_price_per_mtok
+    """
+    key = _resolve_pricing_key(model)
+    if key is None:
+        return (0.0, False)
+
+    inp_price, out_price, cache_write_price, cache_read_price = _PRICING[key]
+
+    cost = (
+        input_tokens        / 1_000_000 * inp_price
+        + output_tokens     / 1_000_000 * out_price
+        + cache_read_tokens / 1_000_000 * cache_read_price
+        + cache_create_tokens / 1_000_000 * cache_write_price
+    )
+    return (cost, True)
+
+
+def known_models() -> tuple[str, ...]:
+    """単価表のキー一覧を返す（テスト・デバッグ用）。
+
+    Returns:
+        _PRICING のキー文字列のタプル（順序は定義順）。
+    """
+    return tuple(_PRICING.keys())