throughline 0.4.11 → 0.5.0

package/docs/RAG/_raw/03-settings/sessions-extract.md

@@ -0,0 +1,64 @@
+# Claude Code Sessions — Extract
+
+Source: <https://code.claude.com/docs/en/sessions> (fetched 2026-05-24)
+
+## Session storage
+
+- JSONL at `~/.claude/projects/<project>/<session-id>.jsonl`
+- `<project>` derived from working directory path
+- Each line is a JSON object (message / tool use / metadata)
+- Override storage location: `CLAUDE_CONFIG_DIR` env var
+- Default retention: 30 days, configurable via `cleanupPeriodDays`
+- Disable transcript writes: `CLAUDE_CODE_SKIP_PROMPT_HISTORY` (env), or `--no-session-persistence` (CLI flag)
+
+## Resume / continue
+
+| Command | Behavior |
+|---|---|
+| `claude --continue` | Resumes most recent session in current directory |
+| `claude --resume` | Opens session picker |
+| `claude --resume <name>` | Resumes named session directly |
+| `claude --from-pr <number>` | Resumes session linked to PR |
+| `/resume` (inside session) | Switches to a different conversation |
+
+## /clear behavior (KEY)
+
+> `/clear`: start fresh with an empty context. **The previous conversation is saved and resumable**.
+
+- /clear empties CC's in-memory context buffer
+- Previous conversation remains in JSONL, retrievable via `--continue` / `--resume`
+- This implies CC has BOTH an in-memory state AND the persisted JSONL — and after /clear, the in-memory state is reset but the file is preserved
+
+## /compact behavior
+
+> `/compact [instructions]`: replace history with a summary, optionally focused on what you specify
+
+- Summarizes existing context in-place
+- Optionally focused via instructions
+- Triggers `PreCompact` / `PostCompact` hooks (mid-session events)
+
+## /context
+
+> `/context`: show what is currently consuming context
+
+## Branch / fork
+
+> `/branch [name]` or `--fork-session` with `--continue` / `--resume`:
+> Creates a copy of the conversation so far and switches into it, leaving the original intact.
+
+- Permission grants don't carry over to new branch
+- Resuming the same session in two terminals interleaves messages into one transcript
+
+## Naming
+
+- `claude -n <name>` (at startup)
+- `/rename <name>` (mid-session)
+- `Ctrl+R` in session picker
+- Auto-naming on plan accept
+
+## Implications for Throughline
+
+1. **/clear preserves JSONL**. CC's in-memory state is the canonical source for the new session's messages[], NOT the JSONL.
+2. **/compact preserves session continuity** — same session_id, just summarized. This is the documented "memory preservation" path.
+3. **`--continue` / `--resume` are the official "restore from JSONL" mechanisms** but they pull the WHOLE prior conversation (no Throughline-style L1/L2/L3 selective compression).
+4. **There's no documented hook to influence in-memory state after /clear**, only context attachments (system reminders).

package/docs/RAG/_raw/04-skills/initialUserMessage-investigation.md

@@ -0,0 +1,101 @@
+# `initialUserMessage` Field — Investigation Results
+
+## Sources
+
+- Official hooks reference: <https://code.claude.com/docs/en/hooks> (mentions field in SessionStart hookSpecificOutput shape)
+- First-party hook-dev SKILL: <https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/hook-development/SKILL.md> (does NOT mention)
+- Open-source CC implementation `Gitlawb/openclaude`:
+  - `src/utils/hooks.ts` — schema definition
+  - `src/utils/sessionStart.ts` — storage + retrieval mechanism
+  - `src/cli/print.ts` — consumer (the critical one)
+  - `src/main.tsx` — initialMessages array construction
+
+## The schema (confirmed)
+
+```typescript
+// From openclaude src/utils/hooks.ts and src/types/hooks.ts
+interface HookResult {
+  additionalContext?: string
+  initialUserMessage?: string
+  watchPaths?: string[]
+  updatedInput?: Record<string, unknown>
+  // ...
+}
+
+// SessionStart hook output processing
+case 'SessionStart':
+  result.additionalContext = json.hookSpecificOutput.additionalContext
+  result.initialUserMessage = json.hookSpecificOutput.initialUserMessage
+  if ('watchPaths' in json.hookSpecificOutput && json.hookSpecificOutput.watchPaths) {
+    result.watchPaths = json.hookSpecificOutput.watchPaths
+  }
+  break
+```
+
+## The CRITICAL constraint (from openclaude source comment)
+
+```typescript
+// src/cli/print.ts:
+// SessionStart hooks can emit initialUserMessage — the first user turn for
+// headless orchestrator sessions where stdin is empty.
+takeInitialUserMessage,
+```
+
+**`initialUserMessage` is for HEADLESS MODE ONLY.** It's invoked when `claude -p` is launched and stdin doesn't provide a prompt — the hook can supply the "first user turn" as a substitute.
+
+## Storage / consumption mechanism
+
+```typescript
+// src/utils/sessionStart.ts
+// Set by processSessionStartHooks when a hook emits initialUserMessage;
+// consumed once by takeInitialUserMessage. This side channel avoids changing
+// the return type of processSessionStartHooks.
+let pendingInitialUserMessage: string | undefined = undefined
+
+if (hookResult.initialUserMessage) {
+  pendingInitialUserMessage = hookResult.initialUserMessage
+}
+
+export function takeInitialUserMessage(): string | undefined {
+  const v = pendingInitialUserMessage
+  pendingInitialUserMessage = undefined
+  return v
+}
+```
+
+```typescript
+// src/cli/print.ts
+const hookInitialUserMessage = takeInitialUserMessage()
+if (hookInitialUserMessage) {
+  structuredIO.prependUserMessage(hookInitialUserMessage)
+}
+// then runHeadlessStreaming() processes the queue
+```
+
+## What this means for Throughline
+
+`initialUserMessage` does NOT solve the `/clear` continuation problem because:
+
+1. `/clear` is an INTERACTIVE mode operation
+2. Interactive mode always has a user typing the next prompt — there's no "missing first user message" slot to fill
+3. `initialUserMessage` is consumed by `print.ts` (print mode = `claude -p`), not by the interactive REPL
+
+**Conclusion**: `initialUserMessage` is the wrong tool for our problem. It can't be used to make `/clear` continuation feel native.
+
+## What IS the right tool? (As of this research)
+
+For interactive `/clear`-then-prompt continuity, the available hook surfaces are:
+
+- `additionalContext` → system reminder ("briefing" framing, what we have now)
+- `stdout` (SessionStart/UserPromptSubmit/UserPromptExpansion) → system reminder (same as above)
+- `PreCompact`/`PostCompact` hooks → fire on /compact, not /clear (different code path)
+- `decision: block` for UserPromptSubmit → can block prompts, doesn't help inject memory
+- Modifying transcript JSONL externally → ignored by CC's in-memory parent chain (proven dead via Phase 0 experiments)
+
+**The current Claude Code hook system does NOT provide a documented mechanism to inject true conversation history (messages[]) into an interactive session after /clear.**
+
+The only paths that would solve this are:
+
+1. **Use /compact instead of /clear** — preserves session continuity in-place; PreCompact hook can influence the summary
+2. **Agent SDK rewrite (E)** — bypass Claude Code's REPL, build a custom runtime that controls messages[] directly
+3. **API-level proxy** — intercept the Claude Code → Anthropic API call and rewrite messages[]

package/docs/THROUGHLINE_CLEAR_AUTO_HANDOFF_PLAN.md

@@ -95,13 +95,14 @@ on SessionStart(source, session_id, project_path):
 
 `consumeBaton` が先発なので「両方同時成立」は構造上発生しない (= baton ありなら baton 経路、無ければ source 判定)。typed `/clear` も UserPromptSubmit hook で baton を書くため、通常はほぼ常に baton path が走る。auto path は VSCode 拡張のメニュー由来 `/clear` のように UserPromptSubmit に届かない経路のためのフォールバック。
 
-### 2.2 注入内容: L1 + L2 + L3 refs のみ (baton/auto どちらの経路でも同一)
+### 2.2 注入内容: 現在地アンカー + L1 + L2 + L3 refs (baton/auto どちらの経路でも同一)
 
-含める:
+含める (順序):
 - ヘッダ + Reading Contract framing (= Codex 側 `renderCodexRolloutMemoryPreview` の写像)
+- **現在地アンカー** (v0.4.12+): 最新 user turn と最新 assistant turn の本文をヘッダ直下に再掲 (各 600 字で truncate)
 - **L1 summaries** (古い turn の一行要約)
 - **L2 bodies** (直近 20 turn の verbatim)
-- **L3 references** (= `throughline detail <時刻>` の取り出しコマンド一覧、Codex 風の `- ${kind}: ${detailCommand}` フォーマット)
+- **L3 references** (= `throughline detail <時刻>` の取り出しコマンド一覧、各 L1/L2 行末尾の inline suffix として集約)
 - Continuation Instruction (= 「これは過去ログではなく現在進行中の作業」と明示)
 
 含めない (= 削除):
@@ -109,7 +110,9 @@ on SessionStart(source, session_id, project_path):
 - 中断直前の thinking (extended thinking セクション)
 - 既存の Claude 向け footer の冗長な使い方説明
 
-理由: L2 全文があれば最後の assistant turn 自体に「次に何をしようとしていたか」が含まれている。memo / thinking は redundant。
+理由:
+- L2 末尾アンカーだけだと、L2 が長いセッションで注意が前半 (= L2 内の最古ターン) に固着し、古い計画ターンを「現在の作業」と誤認するケースがあった (実観測あり)。最新ターンをヘッダ直下にも再掲して、最初に目に入る位置で文脈を固定する。
+- L2 全文があれば最後の assistant turn 自体に「次に何をしようとしていたか」が含まれている。memo / thinking は redundant。
 
 ### 2.3 `/tl` の役割: **残すが簡素化**