throughline 0.4.11 → 0.5.0

package/CHANGELOG.md

@@ -10,6 +10,84 @@ shipped to npm but were not individually tagged on GitHub.
 
 ## [Unreleased]
 
+## [0.5.0] — 2026-05-24
+
+This release closes out the v0.5 transcript-injection investigation and
+locks in **path C** (`resume-context.mjs` v2.1 header + 現在地 anchor) as
+the plugin-scope completion form for Throughline.
+
+### Changed
+
+- Strengthened the Claude `/clear` resume context header with two new
+  short-message handling rules so the cleared-me side stops misreading
+  follow-up shorts as fresh requests:
+  - **短文/相槌の判定**: any user message that is ≤50 chars or built solely
+    out of acknowledgment / agreement / prompt words (はい / うん / 了解 /
+    OK / やって / 進めて / 続き / 次) must be treated as a GO sign on the
+    previous assistant's proposed next move, not a new request, and the
+    cleared-me must not ask back, re-list options, or pivot to other work.
+  - **古い番号リストの再実行禁止**: when the latest user references an
+    older numbered list (e.g. `2 をやれ`) but the most recent assistant turn
+    already executed that item, the cleared-me must respond with a result
+    confirmation / next move, not by re-executing the already-done item.
+    The latest assistant utterance outranks any older numbered list
+    referenced from it.
+
+### Research (no shipped behavior change)
+
+Two alternative injection routes were spiked end-to-end against real
+Claude Code (v2.1.145) and both confirmed dead, locking path C as the
+plugin-scope ceiling.
+
+- **D route — transcript JSONL append** (Phase 0-2 / Phase 0-5): four
+  real-machine runs across `SessionStart` (chain `null` orphan) and
+  `UserPromptSubmit` (chain `b` reachable-from-attachment) timings, with
+  both synthetic and real Claude model names. All four runs produced
+  「ない」when the cleared-me was asked to quote the spike tracer. Root
+  cause: Claude Code decides each new turn's `parentUuid` from its
+  in-process memory state and never re-reads the JSONL, so any text a
+  hook writes to `transcript_path` lives on a parallel chain that the
+  next prompt's parent-walk never reaches.
+- **`hookSpecificOutput.initialUserMessage` route** (Phase 0-6): real
+  Claude Code interactive run on 2026-05-24 13:33 (tracer `9220a79c`,
+  session `0979ad20-…`) returned 「ない」, empirically confirming the
+  openclaude source comment that `initialUserMessage` is consumed only
+  for headless orchestrator sessions, not for the interactive `/clear`
+  scenario this project needs.
+
+Both routes are kept in-tree behind marker files
+(`~/.throughline/spike-inject.flag`,
+`~/.throughline/spike-prompt.flag`,
+`~/.throughline/initial-user-message-test.flag`) as research
+infrastructure for future re-evaluation; they are no-op when the flags
+are absent and have no effect on the shipped path.
+
+### Added
+
+- `docs/THROUGHLINE_TRANSCRIPT_INJECTION_PLAN.md`: full Phase 0 plan and
+  result log for the D / `initialUserMessage` investigation.
+- `docs/RAG/`: third-party spec knowledge base (Claude Code hooks
+  reference, Anthropic Messages API, sessions docs, openclaude
+  `initialUserMessage` source extract) used as the grounding for the
+  no-go calls above.
+
+## [0.4.12] — 2026-05-17
+
+### Changed
+
+- Added a 「現在地 (直前のやりとり)」 anchor at the top of the Claude
+  `/clear` resume context injection. The anchor re-surfaces the latest user
+  directive and the latest assistant turn body (each truncated to 600
+  characters) directly under the header, before the L1 / L2 sections.
+  Observed failure mode: with a long L2 window the model's attention could
+  fixate on the *first* L2 entry (oldest in the window) and mistake an older
+  plan discussion for the current state of the conversation. The anchor pins
+  the latest exchange at the position the model reads first, with the existing
+  L2-tail anchor preserved as reinforcement. The header reading instructions
+  now point to the new anchor as the first bullet.
+
+## [0.4.11] — 2026-05-10
+
 ### Changed
 
 - Disabled Codex automatic current-thread refresh from `UserPromptSubmit`,
@@ -23,6 +101,17 @@ shipped to npm but were not individually tagged on GitHub.
   and opens the selected host. Explicit `throughline trim --execute --host codex`
   remains available as a diagnostic current-thread rollback / inject command.
 
+### Fixed
+
+- Codex hooks registered by `throughline install` now resolve the Node
+  executable through `PATH` (matching `process.execPath` by `realpath`) instead
+  of always hard-coding `process.execPath`. On Homebrew-installed Node on macOS,
+  `process.execPath` points at a Cellar-versioned binary that disappears on the
+  next `brew upgrade`, leaving stale absolute paths in `~/.codex/hooks.json`.
+  The new resolver prefers a stable `PATH` entry (e.g. `/opt/homebrew/bin/node`)
+  and falls back to `process.execPath` only when no PATH entry resolves to the
+  same binary.
+
 ## [0.4.10] — 2026-05-09
 
 ### Fixed

package/README.md

@@ -216,14 +216,21 @@ this fallback. **The env var only affects the fallback**; typed `/clear` and
 
 Both paths inject the **same** curated memory:
 
+- A **"現在地 (latest exchange)"** anchor (added in v0.4.12) re-surfaces the
+  most recent user directive and the most recent assistant turn directly under
+  the header, each truncated to 600 characters
 - L1 summaries (older turns, one-line)
 - L2 verbatim (most recent 20 turns, full text)
-- L3 references (`throughline detail <time>` retrieval commands; bodies stay in SQLite)
+- L3 references (`throughline detail <time>` retrieval commands, attached
+  inline to each L1/L2 row; bodies stay in SQLite)
 
 The injection is reframed as **"resuming an interrupted task"** rather than
 "reading past logs". The L2 verbatim already contains the last assistant
 turn — what Claude was about to do next — so no separate memo or extended
-thinking section is injected.
+thinking section is injected. The current-state anchor exists because, on
+long L2 windows, attention can fixate on the *first* L2 entry (the oldest
+turn in the window) and misread an old plan discussion as the current task;
+pinning the latest exchange at the top of the injection prevents that drift.
 
 Each merged row keeps its `origin_session_id`, so repeated handoffs
 accumulate memory through chains:

package/docs/RAG/INDEX.md

@@ -0,0 +1,160 @@
+# Throughline RAG Index — Context Spec Knowledge Base
+
+Built: 2026-05-24
+
+This directory accumulates third-party specifications relevant to Throughline's mission ("コンテキスト削減しつつ過去の記憶を一切失わない") so design decisions are grounded in actual Claude Code / Anthropic API constraints rather than guesses.
+
+## Folder layout
+
+```text
+docs/RAG/
+├── INDEX.md (this file — synthesized findings, paths forward)
+└── _raw/                       (verbatim spec extracts, kept close to source wording)
+    ├── 01-hooks/
+    │   └── hooks-reference-extract.md      ← Claude Code hooks reference
+    ├── 02-messages-api/
+    │   └── messages-api-extract.md         ← Anthropic Messages API spec
+    ├── 03-settings/
+    │   └── sessions-extract.md             ← /clear, /compact, /resume behavior
+    └── 04-skills/
+        └── initialUserMessage-investigation.md ← deep-dive on the killer field
+```
+
+---
+
+## Question this RAG was built to answer
+
+> Throughline は「コンテキスト削減しつつ過去の記憶を一切失わない」と定義されている。記憶を引き継いでいてもモデルがそれを自分の作業履歴として体感していないなら、その記憶は無意味なコンテキストである。
+>
+> Claude Code の hook 系内で **モデルが「これは自分の過去発話である」と認識する形** で記憶を注入する経路は、本当に存在しないのか?
+
+## Hard findings from spec (verified, not guessed)
+
+### Finding 1: `additionalContext` is a system reminder, not a user message
+
+> "Claude Code wraps the string in a system reminder and inserts it into the conversation at the point where the hook fired. Claude reads the reminder on the next model request, but it **does not appear as a chat message** in the interface."
+> — [Hooks reference](_raw/01-hooks/hooks-reference-extract.md#what-additionalcontext-actually-does-critical)
+
+→ システムリマインダ = ブリーフィング扱い。モデルが「他人事」と感じる構造的原因。
+
+### Finding 2: stdout from `SessionStart` / `UserPromptSubmit` / `UserPromptExpansion` is also a system reminder
+
+> "any non-JSON text written to stdout is added as context"
+> "Claude Code wraps the string in a system reminder"
+> — [Hooks reference](_raw/01-hooks/hooks-reference-extract.md#stdout)
+
+→ 現行 Throughline v0.4.12 の stdout 注入はこの経路。`additionalContext` と同じカテゴリ = 同じ「他人事」問題。
+
+### Finding 3: `initialUserMessage` exists in the schema, but is **HEADLESS-ONLY**
+
+Verified via [openclaude source](_raw/04-skills/initialUserMessage-investigation.md#the-critical-constraint-from-openclaude-source-comment):
+
+```text
+// SessionStart hooks can emit initialUserMessage — the first user turn for
+// headless orchestrator sessions where stdin is empty.
+```
+
+→ Interactive mode (`/clear` シナリオ) では発火しない。我々の問題には使えない。
+
+**2026-05-24 実機確認**: real Claude Code (v2.1.145) で `~/.throughline/initial-user-message-test.flag` を立てて SessionStart hook を JSON 出力モードに切り替え、`hookSpecificOutput.initialUserMessage` に 8 hex tracer 入りメッセージを乗せて `/clear` 後の cleared-me に「過去発話の tracer を message history だけ見て返して」と尋ねた。ラン (2) 13:33 tracer `9220a79c` (session `0979ad20-…`) → モデル応答 **「ない」**。openclaude のソースコメントが real CC でも妥当であることを実機で確認。詳細: [docs/THROUGHLINE_TRANSCRIPT_INJECTION_PLAN.md §6 Phase 0-6](../THROUGHLINE_TRANSCRIPT_INJECTION_PLAN.md#phase-0-6--hookspecificoutputinitialusermessage-経路-spike)
+
+### Finding 4: Messages API treats all messages[] entries equally
+
+> "When creating a new Message, you specify the prior conversational turns with the messages parameter, and the model then generates the next Message in the conversation."
+> — [Messages API](_raw/02-messages-api/messages-api-extract.md#no-differentiation-between-real--synthetic-messages-key)
+
+→ もし messages[] に synthetic な過去 turn を入れられれば、モデルは「本物」と区別できない。問題は CC が messages[] を hook から制御させていないこと。
+
+### Finding 5: `/clear` preserves the JSONL but resets in-memory state
+
+> "/clear: start fresh with an empty context. The previous conversation is saved and resumable"
+> — [Sessions](_raw/03-settings/sessions-extract.md#clear-behavior-key)
+
+→ CC は in-memory state を一次ソースに messages[] を構築。JSONL を外から書き換えても in-memory には反映されない (= Phase 0 / Phase 0-5 で実測確認済み)。
+
+### Finding 6: `/compact` is the documented memory-preservation path
+
+> "/compact [instructions]: replace history with a summary"
+
+→ /compact は同一 session を継続したまま履歴を要約版に置換。**PreCompact / PostCompact hook が発火**。これが Anthropic 公式の「記憶圧縮しつつ継続」経路。
+
+### Finding 7: First-party hook-dev SKILL omits `initialUserMessage`
+
+[anthropics/claude-code/plugins/plugin-dev/skills/hook-development/SKILL.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/hook-development/SKILL.md) は SessionStart hook の `hookSpecificOutput` の `additionalContext` も `initialUserMessage` も触れていない。Plugin 開発者向けの公式チュートリアルですら触れない = どちらも primary 経路として推奨されていない可能性。
+
+---
+
+## Throughline 仮説の見直し
+
+### 当初仮説 (D 経路)
+
+「JSONL に user/assistant 行を append すれば、CC が messages[] 構築時にそれを読む」
+
+**実測 (4 ラン): すべて「ない」 → 反証済み**
+
+JSONL は read 対象ではなく、CC の in-memory state が messages[] のソース。書き込んでも再読込されない。
+
+### 第二仮説 (initialUserMessage)
+
+「`initialUserMessage` で interactive モードでも first user message を注入できる」
+
+**spec 調査 (openclaude source): HEADLESS-ONLY → 反証済み**
+
+### 第三仮説 (PreCompact での再投影)
+
+未検証。`/compact` のタイミングで PreCompact hook が「これを summary に必ず含めろ」と影響を与えられるなら、compaction 後の messages[] は本物の assistant turn として要約を含む可能性。
+
+---
+
+## ここから取れる現実的な道 (3 つ)
+
+### 道 A: スコープを `/compact` に切り替え
+
+- Throughline は `/clear` を諦め、`/compact` への置換を提案
+- PreCompact hook で「直近 N turn を保持し、それ以前を summary に置換」のロジックを差し込む
+- 同一 session 内なので messages[] は real assistant turn として要約を持つ → 本人体感を維持
+- 制約: ユーザーの習慣 ("/clear で切り替える") から外れる; /compact は context full のときに自動発火する別経路でもあるので、頻発させると体感が変わる
+- **`/clear` シナリオには適用できない** (構造的に別物)
+
+### 道 B: Agent SDK / 自前ランタイム (= E)
+
+- Claude Code を捨てて Agent SDK (Python or TypeScript) でラッパーを書く
+- messages[] を完全制御 — synthetic user/assistant turn を自由に prepend
+- /clear に相当する UX は自前で実装、内部的には messages[] を選択的に圧縮
+- 制約: 大改修。Throughline は plugin から product になる
+- これが「本人体感」を達成する唯一の正攻法
+
+### 道 C: 現状受容 + A2.0 文言調整
+
+- 現行 stdout 注入のままで継続
+- 案内文の文言を改善 (現行 A 実装) で「他人事感」を多少緩和
+- 「本人体感」までは届かないが、「『何のこと？』が出ない」レベルは達成済み
+- 制約: Throughline のミッション定義 (「体感」まで含む) を満たさない
+
+---
+
+## 推奨される判断順
+
+1. **Throughline のミッション定義の再確認**:
+   - 「体感まで保証」が必須 → 道 B (E pivot) しかない。CC plugin である限り構造的に不可能。
+   - 「配送までで OK、体感は best-effort」 → 道 C で十分。
+
+2. **`/clear` という UI シグナルへのこだわり**:
+   - 必須 → 道 B または C。/compact は別物。
+   - 妥協可能 → 道 A も視野 (ユーザーに /compact を勧める)
+
+3. **着手コスト**:
+   - 道 C: 小 (文言調整のみ。実装済み)
+   - 道 A: 中 (PreCompact hook + summary 制御)
+   - 道 B: 大 (別プロジェクト相当)
+
+---
+
+## 蓄積予定 (今後 RAG に足すべき調査)
+
+- [ ] PreCompact / PostCompact hook の詳細仕様 (specific output schema)
+- [ ] Agent SDK Python / TypeScript の messages[] 制御 API
+- [ ] `claude --continue` / `--resume` の実 messages[] 構築フロー (JSONL → API call の変換)
+- [ ] CC のバージョンによる hook 挙動差分 (2.1.128 で source='clear' が変わった等)
+- [ ] 他の OSS CC 互換実装 (openclaude 以外) の messages[] 構築コード
+- [ ] Codex の同等問題と解決手法 (Throughline は Claude / Codex 両対応)

package/docs/RAG/_raw/01-hooks/hooks-reference-extract.md

@@ -0,0 +1,250 @@
+# Claude Code Hooks Reference — Extract
+
+Source: <https://code.claude.com/docs/en/hooks> (fetched 2026-05-24)
+
+## Hook events (31 total)
+
+### Per-Session
+
+- `SessionStart` — session begins or resumes
+- `Setup` — when launched with `--init-only` / `--init` / `--maintenance`
+- `SessionEnd` — session terminates
+
+### Per-Turn
+
+- `UserPromptSubmit` — user submits a prompt, before Claude processes it
+- `UserPromptExpansion` — when a user-typed command expands into a prompt
+- `Stop` — Claude finishes responding
+- `StopFailure` — turn ends due to API error
+
+### Per-Tool-Call
+
+- `PreToolUse` — before tool call
+- `PostToolUse` — after tool call succeeds
+- `PostToolUseFailure` — after tool call fails
+- `PostToolBatch` — after parallel tool batch resolves
+- `PermissionRequest` — when permission dialog appears
+- `PermissionDenied` — denied by auto mode classifier
+
+### Agent/Team
+
+- `SubagentStart` / `SubagentStop`
+- `TaskCreated` / `TaskCompleted`
+- `TeammateIdle`
+
+### File/Config
+
+- `InstructionsLoaded` — when CLAUDE.md / `.claude/rules/*.md` loaded
+- `ConfigChange`
+- `FileChanged`
+- `CwdChanged`
+- `WorktreeCreate` / `WorktreeRemove`
+
+### Compaction
+
+- `PreCompact` — before context compaction
+- `PostCompact` — after context compaction
+
+### MCP
+
+- `Elicitation` / `ElicitationResult`
+
+### Notification
+
+- `Notification`
+
+---
+
+## Common input payload (all events)
+
+```json
+{
+  "session_id": "abc123",
+  "transcript_path": "/home/user/.claude/projects/.../transcript.jsonl",
+  "cwd": "/home/user/my-project",
+  "permission_mode": "default|plan|acceptEdits|auto|dontAsk|bypassPermissions",
+  "hook_event_name": "PreToolUse",
+  "effort": { "level": "low|medium|high|xhigh|max" },
+  "agent_id": "optional-subagent-id",
+  "agent_type": "optional-agent-name"
+}
+```
+
+### SessionStart input
+
+```json
+{
+  "session_id": "abc123",
+  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
+  "cwd": "/Users/...",
+  "hook_event_name": "SessionStart",
+  "source": "startup|resume|clear|compact",
+  "model": "claude-sonnet-4-6"
+}
+```
+
+### UserPromptSubmit input
+
+```json
+{
+  "session_id": "abc123",
+  "transcript_path": "...",
+  "cwd": "/Users/...",
+  "permission_mode": "default",
+  "hook_event_name": "UserPromptSubmit",
+  "prompt": "Write a function to calculate the factorial of a number"
+}
+```
+
+---
+
+## hookSpecificOutput
+
+Common shape:
+
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PostToolUse",
+    "additionalContext": "text string to inject into Claude's context"
+  }
+}
+```
+
+### What `additionalContext` actually does (CRITICAL)
+
+> The `additionalContext` field passes a string from your hook into Claude's context window. **Claude Code wraps the string in a system reminder** and inserts it into the conversation at the point where the hook fired. Claude reads the reminder on the next model request, but it does not appear as a chat message in the interface.
+
+**Placement by event:**
+
+| Event Category | Placement |
+|---|---|
+| `SessionStart`, `Setup`, `SubagentStart` | At the start of the conversation, before the first prompt |
+| `UserPromptSubmit`, `UserPromptExpansion` | Alongside the submitted prompt |
+| `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PostToolBatch` | Next to the tool result |
+
+**Character limit:** 10,000 characters per context string. Excess → written to file in session dir, file path + preview passed to Claude.
+
+**Content type:** delivered AS A SYSTEM REMINDER (not user message). Same category as stdout.
+
+### SessionStart hookSpecificOutput (THE KEY DISCOVERY)
+
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "SessionStart",
+    "additionalContext": "context string",
+    "initialUserMessage": "first message (SessionStart only)",
+    "watchPaths": ["/path/to/watch1", "/path/to/watch2"]
+  }
+}
+```
+
+🎯 **`initialUserMessage` is a SessionStart-only field that becomes the first user message of the session.** This goes into `messages[]` as a real user-role turn, NOT a system reminder.
+
+This is the unexplored angle for Throughline: instead of injecting context (system reminder = "briefing"), inject the resume context AS the first user message ("the user just said this, including past history") so the model treats it as actual conversation input.
+
+### UserPromptSubmit hookSpecificOutput
+
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "UserPromptSubmit",
+    "additionalContext": "context string",
+    "sessionTitle": "auto-set session title"
+  }
+}
+```
+
+(No `initialUserMessage` — it only exists on SessionStart.)
+
+---
+
+## Hook output handling
+
+| Exit Code | Meaning | JSON Processed? | Blocking? |
+|---|---|---|---|
+| **0** | Success | YES (if JSON present) | No |
+| **2** | Blocking error | NO (JSON ignored) | Yes (event-dependent) |
+| Other | Non-blocking error | NO | No |
+
+### Stdout
+
+| Event | stdout becomes Claude-visible? |
+|---|---|
+| `SessionStart` / `UserPromptSubmit` / `UserPromptExpansion` | YES (as system reminder) |
+| Other events | NO (debug log only) |
+
+### Resume / replay behavior
+
+> Once injected, the text is saved in the session transcript. For mid-session events like `PostToolUse` or `UserPromptSubmit`, resuming with `--continue` or `--resume` replays the saved text rather than re-running the hook for past turns, so values like timestamps or commit SHAs become stale on resume. **`SessionStart` hooks run again on resume with `source` set to `"resume"`, so they can refresh their context.**
+
+### JSON output fields (exit 0 only)
+
+```json
+{
+  "continue": true,
+  "stopReason": "message if continue is false",
+  "suppressOutput": false,
+  "systemMessage": "warning shown to user",
+  "terminalSequence": "OSC escape sequence",
+  "hookSpecificOutput": {
+    "hookEventName": "EventName",
+    "additionalContext": "..."
+  }
+}
+```
+
+| Field | Default | Effect |
+|---|---|---|
+| `continue` | `true` | If `false`, Claude stops processing entirely |
+| `stopReason` | — | Message shown when `continue: false` |
+| `suppressOutput` | `false` | Hide hook's stdout from transcript (still in debug log) |
+| `systemMessage` | — | Warning shown to user |
+| `terminalSequence` | — | OSC 0/1/2/9/99/777, BEL only |
+
+### PreToolUse decision control (extra)
+
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "allow|deny|ask|defer",
+    "permissionDecisionReason": "explanation text",
+    "additionalContext": "context for Claude",
+    "updatedInput": { "command": "modified command" }
+  }
+}
+```
+
+`updatedInput` modifies tool parameters before execution. Note: only PreToolUse has `updatedInput`.
+
+### When multiple hooks return additionalContext
+
+> When several hooks return `additionalContext` for the same event, Claude receives all of the values.
+
+---
+
+## Transcript / messages[] construction (incompletely documented)
+
+The docs do NOT detail how messages[] is constructed from JSONL. What we can infer:
+
+1. Hook context = system reminders (not user/assistant messages)
+2. Stdout = system reminders for SessionStart / UserPromptSubmit / UserPromptExpansion, log-only otherwise
+3. Hook outputs are persisted in transcript and replayed on `--continue` / `--resume`
+4. SessionStart re-runs on resume with `source: "resume"` (so it can refresh)
+5. **`initialUserMessage`** appears to be the only documented way for a hook to inject a real user-role message
+
+---
+
+## Output method summary
+
+| Method | Exit | Content Type | Visible to Claude? | Use Case |
+|---|---|---|---|---|
+| Plain stdout (SessionStart / UserPromptSubmit / UserPromptExpansion) | 0 | Text | YES (system reminder) | Quick context injection |
+| Plain stdout (other) | 0 | Text | NO (debug log) | Logging only |
+| Exit code 2 | 2 | stderr | YES (as error) | Policy enforcement |
+| JSON `additionalContext` | 0 | JSON | YES (system reminder) | Structured context |
+| **JSON `initialUserMessage` (SessionStart only)** | 0 | JSON | **YES (as user message!)** | **First user-role injection** |
+| JSON `decision: "block"` | 0 | JSON | YES (decision reason) | Event-specific block |
+| JSON `continue: false` | 0 | JSON | Halts session | Hard stop |

package/docs/RAG/_raw/02-messages-api/messages-api-extract.md

@@ -0,0 +1,126 @@
+# Anthropic Messages API — Extract
+
+Source: <https://platform.claude.com/docs/en/api/messages> (fetched 2026-05-24)
+
+## Messages array structure
+
+### Role values
+
+Only `"user"` and `"assistant"`. No `"system"` role in messages[].
+
+> "Our models are trained to operate on alternating `user` and `assistant` conversational turns."
+
+> "Consecutive `user` or `assistant` turns in your request will be combined into a single turn."
+
+### Content block types
+
+Each message's `content` is either a string (shorthand for `[{"type": "text", "text": "..."}]`) or an array of `ContentBlockParam`.
+
+| Type | Schema | Purpose |
+|---|---|---|
+| `text` | `{type: "text", text, cache_control?, citations?}` | Plain text |
+| `image` | `{type: "image", source, cache_control?}` | Images |
+| `document` | `{type: "document", source, title?, context?, citations?, cache_control?}` | PDF / plain text |
+| `tool_use` | `{type: "tool_use", id, name, input, caller?, cache_control?}` | Model's tool invocation |
+| `tool_result` | `{type: "tool_result", tool_use_id, content?, is_error?, cache_control?}` | Tool execution result |
+| `thinking` | `{type: "thinking", thinking, signature}` | Extended thinking (input only) |
+| `redacted_thinking` | `{type: "redacted_thinking", data}` | Redacted thinking |
+| `search_result` | `{type: "search_result", title, source, content, cache_control?, citations?}` | Web search results |
+| `server_tool_use` | `{type: "server_tool_use", id, name, input, caller?, cache_control?}` | Server-side tool execution |
+
+---
+
+## System field (top-level)
+
+```json
+{
+  "system": "You are a helpful assistant.",
+  "messages": [{"role": "user", "content": "Hello"}]
+}
+```
+
+> "Note that if you want to include a system prompt, you can use the top-level `system` parameter — there is no `system` role for input messages in the Messages API."
+
+`system` accepts string OR `TextBlockParam[]`:
+
+```json
+{
+  "system": [
+    {"type": "text", "text": "Today's date is 2024-06-01.",
+     "cache_control": {"type": "ephemeral", "ttl": "5m"}}
+  ]
+}
+```
+
+---
+
+## Conversation continuation & synthetic messages (CRITICAL FOR THROUGHLINE)
+
+### Synthetic assistant prefill
+
+> "If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response."
+
+Example:
+
+```json
+{
+  "messages": [
+    {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"},
+    {"role": "assistant", "content": "The best answer is ("}
+  ]
+}
+```
+
+Response: model continues from `"The best answer is ("` and outputs `"B)"`.
+
+### No differentiation between real & synthetic messages (KEY)
+
+> "When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation."
+
+**The documentation does not distinguish between:**
+
+- Historically real messages from past API calls
+- Newly constructed/injected synthetic messages in the current request
+
+→ Models treat all messages equally regardless of source. **No metadata field indicates whether a message was real or synthetic.**
+
+This validates the D-route theory: IF we could inject prior turns into messages[], the model would treat them as continuation. The question is purely about **how to control messages[] from within Claude Code**.
+
+### Turn combining
+
+> "Consecutive `user` or `assistant` turns in your request will be combined into a single turn."
+
+This applies uniformly regardless of source.
+
+---
+
+## Fields outside messages[]
+
+Top-level request parameters (relevant for context):
+
+| Parameter | Type | Purpose |
+|---|---|---|
+| `system` | `string \| TextBlockParam[]` | System prompt |
+| `model` | `string` | Required |
+| `max_tokens` | `number` | Required |
+| `temperature`, `top_p`, `top_k`, `stop_sequences` | — | sampling |
+| `tools`, `tool_choice` | — | Tool definitions |
+| `thinking` | `ThinkingConfig` | Extended thinking budget |
+| `stream` | `boolean` | Streaming |
+| `metadata` | `{user_id?}` | Request tracking |
+| `cache_control` | `CacheControlEphemeral` | Top-level cache marker |
+| `service_tier` | `"auto" \| "standard_only"` | Capacity tier |
+| `output_config` | `{format?, effort?}` | Output formatting |
+
+No "transcript" or "session_history" field — all conversation context goes through `messages[]` or `system`.
+
+---
+
+## Implications for Throughline
+
+1. **Only `messages[]` carries "real" conversation history**. `system` is briefing material.
+2. **The model treats all `messages[]` entries equally** — synthetic past turns are indistinguishable from real ones.
+3. **For "本人体感" (the assistant feeling like it was the one talking), the past turns MUST be in `messages[]`, not in `system`.**
+4. **Synthetic assistant prefill is officially supported** — we could end messages[] with an assistant turn to constrain continuation.
+
+→ Claude Code's challenge: how does CC build the API request's `messages[]`? If we can influence that (via `initialUserMessage` or another mechanism), we can solve the "本人体感" problem.