Throughline: Instructions file for Claude Code

AGENTS.md

このファイルは AI エージェント（Claude Code、Codex、Grok、Cursor など）がこのリポジトリで作業する際のガイダンスです。

プロジェクト概要

Throughline は Claude Code の hooks プラグインで、会話ターンを 3 層 (L1/L2/L3) に分解して SQLite に保存し、/clear 後も記憶を復元します。加えてマルチセッション対応のトークンモニター CLI も同梱しています。

Throughline は単独で install、設定、状態保存とschema migration、診断、復旧、更新、 release判定まで完結する。dotagentsは工場への配線と統合契約を担当するが、Throughlineの 状態や製品寿命を所有・制御しない。runtime-error collectionはThroughline自身の runtime-errors enable|disable --jsonと製品所有configが管理し、工場側は公開JSON契約だけを使う。 runtime errorを外へ送るのは、利用者がruntime-errors report-enableで明示して有効にした端末だけで、既定では通信しない（ADR 0025）。 Codex固定エラーの最新一回はADR 0025の私有補足を既message_templateへ投影する。旧指紋/件数を変えず、利用者影響unknown/diagnostic_onlyを明示する。

版番号の正本は package.json、公開版はnpm、schemaの正本は src/db.mjs の CURRENT_VERSION とする。Claude Code、Codex、Grok、Cursorをfirst-class hostとして扱う。現行host契約はREADMEとADR 0021／0022／0023、release gateはdocs/04_public_release_plan.mdを正とする。版ごとの変更・公開commit・CI・npm・tag・smoke履歴はCHANGELOG.mdとdocs/archive/, evidence/に置き、この常時読込正本へ複製しない。

設計の核 (v0.4.0 以降 + ADR 0014 二相化、docs/02_clear_auto_handoff_plan.md)

• /clear 後も SQLite はそのまま残る。前任セッションの全レコードを新 session_id に張り替える（記憶張り替え方式）
• 二相ハンドオフ (ADR 0014): Claude Code は同一 project に短時間で複数の SessionStart を発火させることがあり、一部は transcript を生成しない幽霊セッションになる。SessionStart 時点では実体と幽霊を判別できない（本物の transcript も hook より数百 ms 遅れて作られる）ため、SessionStart は pending_handoffs への intent 登録のみを行い、merge + 注入は最初の UserPromptSubmit（= 実体の証明。幽霊はプロンプトを発火しない）で実行する。2026-07-17 に幽霊がバトンを先取りして実セッションが記憶ゼロで始まる incident が同日 2 回発生した（実測・機序は ADR 0014）
• 引き継ぎ発火条件は 2 経路 (baton path 優先):
  1. baton path: 旧セッションで /tl を実行すると UserPromptSubmit hook が handoff_batons テーブルにそのセッションの session_id を書き込み、次の新規セッションが初回プロンプト時に消費して merge。適格性はセッション誕生時刻基準で 0 ≤ (誕生 − baton書込) ≤ TTL 1h。負 age（誕生後に書かれた baton）は消さずに残す＝走行中セッションが横取りしない。source 値関係なく発火する確定指名方法
  2. auto path: baton が無く SessionStart で source='clear' を受け取ったとき、env THROUGHLINE_DISABLE_AUTO_HANDOFF が '1' でなければ findLatestClaudePredecessor（transcript 実在フィルタ付き — 幽霊 twin を前任に選ばない）で前任を SessionStart 時点で解決・凍結し、初回プロンプト時に merge + 注入。組み込み /clear は実測したどのクライアントでも UserPromptSubmit に届かない。VS Code は source='clear' を送るため auto path、Desktop は送らないため /tl を先に使う（経緯と実測は archive docs/12、upstream: anthropics/claude-code#76704）
  3. baton 消費が auto 判定より先発なので両者は構造上同時成立しない
• 注入内容 (ADR 0016, 2026-07-18〜): push は「現在地」だけ — ヘッダ + 現在地アンカー + 案内セクション（無条件表示）+ L2 を新しい順に丸ごと入るターンだけ全文（ターン原子・固定 N なし）。L1 は注入しない。窓 (20 ターン) の残りは throughline recall --l2、それより古い全ターンは recall --l1（要約 or 未要約明示）、一点掘りは throughline detail <時刻> の pull 三段構成。範囲・境界 (ISO ms strict less-than)・件数・session は全部注入時に案内コマンドへ焼き込み、recall 側は窓を再計算しない。memo / thinking は注入しない
• 注入予算 (ADR 0014): hook stdout は約 10k 字超で <persisted-output>（path + 先頭 2KB preview）に file 化されモデル可視が劣化する（実測 9,501 字 inline / 15,286 字 file 化。10k 判定は per context string で multi-hook なら突破可能と実測済みだが構造的想定外として不採用 — ADR 0016）。注入は buildBudgetedResumeContext（上限 9,500 字）で行う
• thinking の L3 保存: assistant の extended thinking ブロックは details テーブルに kind='thinking' で全ターン保存される。throughline detail <時刻> で取り出せるが、注入には含めない
• 各レコードは origin_session_id を保持するため、複数回の引き継ぎでも記憶がチェーン状に蓄積する（ホップ制限なし）
• CLAUDE_AUTOCOMPACT_PCT_OVERRIDE は 使わない（自動コンパクト依存の設計は放棄済み）
• フォールバック / 逃げ道のコードを書かない — docs/04_public_release_plan.md §0 参照。silent try/catch、exit(0) でのエラー隠蔽は禁止