claude-code - 💡(How to fix) Fix [FEATURE] Persist recap / post_turn_summary to session JSONL for downstream parsing

Preflight Checklist

• I have searched existing requests and this feature hasn't been requested yet
• This is a single feature request (not multiple features)

Problem Statement

Claude Code's session recap (a.k.a. post_turn_summary / "away summary", introduced in the /recap family of changes — disable via /config or CLAUDE_CODE_ENABLE_AWAY_SUMMARY=0) generates a short, useful summary of what's happened in the session so far and renders it as a grey overlay in the CLI when you return after being away.

The summary is good — concise, factual, exactly the kind of thing a downstream tool would want for cross-session analytics, dashboards, or chat-history search. But it's currently render-only: it doesn't land in the per-session JSONL under ~/.claude/projects/<encoded-cwd>/<uuid>.jsonl, so anything outside the live CLI has to re-derive the same summary itself (we're piping transcripts through a local LLM merger for exactly this purpose; Claude Code is already doing the work, we'd just like to read the result).

Adjacent issues:

• #34610 (closed) requested the /recap command itself — feature shipped despite the not-planned close.
• #48084 asks for docs of /recap + away-summary controls (docs gap).
• #53516 asks for a stable, documented schema of JSONL line types generally — this would be one new entry in that schema.
• #55023 / #55863 are platform-specific render bugs for the overlay.
• #57743 asks for UI/visual separation of summaries — orthogonal.

None of these request persistence. This one does.

Proposed Solution

When the recap fires (auto on return after the away threshold, or manually via /recap), append a line to the active session's JSONL with a stable, parseable shape — mirroring the existing synthetic-entry pattern used by ai-title, last-prompt, and file-history-snapshot:

{
  "type": "recap",
  "recap": "<the same text rendered in the overlay>",
  "trigger": "away" | "manual" | "post_turn",
  "leafUuid": "<uuid of the assistant turn the recap was computed from>",
  "sessionId": "<sessionId>",
  "timestamp": "<RFC3339>"
}

Notes:

• trigger lets consumers tell auto-fires apart from operator-invoked ones (the operator-invoked ones are usually the more curated ones).
• leafUuid ties the recap to a specific point in the transcript so downstream tools can scope "recap of work up to X" cleanly. Matches the existing last-prompt shape.
• No change to the rendered UX. Persisting in addition to rendering is additive.
• Opting out: respect the existing CLAUDE_CODE_ENABLE_AWAY_SUMMARY=0 / /config switch — if recap is disabled, no JSONL entry either.

Why it's worth doing

• Downstream summarizers can skip their own work. Fleet tooling that ingests JSONL (chat search, session dashboards, multi-host rollups) gets a first-class human-readable summary per session without running a second LLM pass over the transcript. In our setup this would let us drop a planned Gemma-based ASR-merge/summary step entirely.
• No new surface to maintain. The recap is already produced and rendered; this is one additional writeLine next to the existing rendering step.
• Schema-friendly. Falls inside the lane #53516 already opened — if Anthropic ever stabilises the JSONL line-type schema, recap is a natural member.

Alternatives considered

• Read the rendered overlay from the TUI — fragile, terminal-only.
• Re-summarize the transcript downstream — duplicates work the CLI already does, with a different model and different quality.
• Use ai-title as a proxy — too short (single line, no progress detail).

Environment

• Claude Code 2.1.150, Linux.
• Recap confirmed working as a CLI overlay in this version.