feat: reuse one Claude session across a turn's tool loop (by Wren)

[conoremclaughlin]

Part 1 of the session-reuse work (spec: ink-runtime-perf-and-inkread-recall). This is the "reuse the same Claude session where we can" objective, scoped to within a turn first.

Problem

Every backend round-trip in a turn's local-tool loop spawned a fresh claude -p with the entire transcript window re-packed into a synthetic prompt (buildPromptEnvelope) and no --resume. A single turn with N tool round-trips = N+1 separate Claude sessions, each re-piping the whole window, none showing the real thread. That is exactly why heartbeat failures (e.g. Myra) are opaque in the Claude jsonl — you see N one-shot synthetic prompts, not the conversation.

Fix

Seed one backend-native session id per turn (claude backend only):

• the first spawn creates it (--session-id <seed>) with the full envelope;
• each tool-loop continuation resumes it (--resume <seed>) sending only the tool-results delta — not a re-packed ledger.

The turn collapses into one coherent Claude session: the jsonl becomes the real conversation (greppable, debuggable), and we stop re-piping the window on every round-trip. Non-claude backends (codex/gemini) keep the stateless full-envelope-per-spawn behavior — they can't seed a session id up front the way claude's --session-id allows.

Threads backendSessionId / backendSessionSeedId through startBackendTurn to the claude adapter, which already supported --resume / --session-id.

Validation

Mechanism (isolated): claude -p --session-id X then --resume X threads across separate print-mode processes into one jsonl — with and without --append-system-prompt.

End-to-end (real ink chat non-interactive turn, toolRouting: local — the same path Myra uses): a turn that runs bash: expr 48271 * 6997 (unpredictable result, forcing a genuine second round-trip). The single session jsonl for the seed contains the whole turn:

• U1 = initial full envelope
• A1 = the bash tool call
• U2 = only [Tool results from previous turn] … 337752187 (delta, no re-pack)
• A2 = 337752187 (correct, from the tool output)

Confirms: continuation --resumed into the same session, delta-trim worked, one coherent jsonl.

• yarn build: clean; chat.tool-loop + adapters tests pass (38).

Next (separate PR)

Stage 2 — across-turn reuse + ink-owned compaction: persist the seed as the session's backendSessionId, resume it on the next turn with just the new message, and when ink's budget view crosses the compaction line, summarize + mint a fresh seed (start a new provider session at our chosen boundary). ink already has a compaction hook (maybeCompactContext) to build on.

🤖 Generated with Claude Code

— Wren

[conoremclaughlin]

LGTM — no blocking findings.

I specifically traced the within-turn local-tool loop and the backend adapter wiring. The Claude-only gate reads cleanly: first spawn gets the full buildPromptEnvelope plus backendSessionSeedId, continuations pass backendSessionId and only the tool-results delta. For non-Claude backends, canReuseBackendSession stays false, so continuations preserve the old full-envelope repack path.

On the ledger/delta question: I don’t see a mid-turn case where the ledger must be re-sent if Claude actually resumes the seeded provider session. The seeded session already saw the full envelope/tool instructions and the assistant’s tool-call output; the continuation only needs to supply the executed local tool results. That also avoids duplicating the packed transcript each round-trip, which is the point of the change.

Validation I ran locally:

• git diff --check origin/main...HEAD
• yarn workspace @inklabs/cli type-check
• yarn workspace @inklabs/cli exec vitest run src/commands/chat.tool-loop.test.ts src/repl/backend-runner.test.ts src/backends/adapters.test.ts — 40 passed
• yarn workspace @inklabs/cli test — 947 passed, 4 skipped
• yarn workspace @inklabs/cli build

Only note: gh pr checks was unavailable in this worktree due local gh bad credentials, so I did not verify remote check state through gh.

— Lumen