[senanurcetin]

Summary

Subagent transcripts could appear as regular sessions in list_sessions_from_store(). If the first entry had no isSidechain key (for example a summary record), fold_session_summary() latched is_sidechain=False and ignored a later explicit isSidechain: true.

Changes

• session_summary.py: latch is_sidechain only when the entry has an explicit boolean isSidechain. The first explicit value wins, including across append batches.
• tests/test_session_summary.py: three fold_session_summary regression tests (flag after an unmarked first entry, flag across append batches, explicit false stays latched) and one list_sessions_from_store fast-path test.

No public API or CLI protocol changes.

Out of scope

The disk lite reader (_parse_session_info_from_lite()) is unchanged. It still checks only the first line of the 64 KiB head window, as the TypeScript SDK does. A transcript whose first explicit isSidechain comes after the first line is still listed by list_sessions(). Fixing that without reading more than the head and tail on the listing hot path needs its own discussion, so I've left it for a separate issue.

Testing

On 1d7344b (Windows, Python 3.11): full suite 1633 passed, 21 skipped; tests/test_session_summary.py 54 passed; ruff check, ruff format --check and mypy src/ scripts/ clean.

AI assistance

This contribution was developed with AI assistance (ChatGPT). The bug was reproduced, regression tests were added, and the changes were verified against the local SDK test suite before submission.
The rework that reduced this PR to the minimal fix was done with Claude Code (Claude Opus 5.5).

[mangeshraut712]

Checking isinstance(entry.get('isSidechain'), bool) in fold_session_summary ensures that initial header or summary records without an isSidechain key do not prematurely latch is_sidechain=False and mask subsequent subagent entries.

Matching this in _parse_session_info_from_lite by checking lines across head preserves parity between disk fast-path listing and in-memory session folding. The unit and parity tests in test_session_summary.py cover append batches and nested metadata checks thoroughly.

[mangeshraut712]

Thanks for the fix — the "first explicit boolean wins" semantics in fold_session_summary and the new regression tests are clear, and all 57 tests in tests/test_session_summary.py pass locally.

One parity gap remains: the lite fast path only scans head (the first 64 KiB, LITE_READ_BUF_SIZE), and tail — which _read_session_lite already reads — is never scanned for isSidechain. src/claude_agent_sdk/_internal/sessions.py:438 still misses a subagent whose first explicit "isSidechain":true lands after the head windowestrategy, so the batch path included a session the fold path excluded.

Reproduction (all entries before the flag are valid JSON, no truncation at the boundary):

lines = ['{"type":"summary","summary":"agent task"}',
         '{"type":"user","message":{"role":"user","content":"first prompt"}}']
lines += ['{"type":"assistant","message":{"role":"assistant","content":"'+'p'*7000+'"}}' for _ in range(10)]
lines.append('{"type":"user","message":{"role":"user","content":"subagent prompt"},"isSidechain":true}')
jsonl = "\n".join(lines) + "\n"   # 70,848 bytes; flag line starts past byte 65,536

lite = _jsonl_to_lite(jsonl, 0)
_parse_session_info_from_lite("sid", lite, DIR)  # -> SDKSessionInfo (included)
fold_session_summary(None, key, [json.loads(l) for l in lines])  # is_sidechain True -> summary_entry_to_sdk_info -> None (excluded)

A subagent transcript with a large tool result or long assistant context before its first user message easily exceeds 64 KiB, so this is the same "subagent appears in the regular session list" bug this PR fixes — it just moved from "first line" to "first 64 KiB". The same edge applies to a JSON line that straddles the head/tail read boundary: json.loads fails via the continue on ValueError at line 443 and the flag is silently dropped even though the full line sits in tail.

Suggest scanning tail as well (it is already in memory; if head and tail overlap, dedupe by size/last-newline head.find(), and skip lines already seen in head when tail == head), and/or adding a test with a >64 KiB transcript where the first explicit flag is past the window.

[senanurcetin]

Thanks @mangeshraut712 for the detailed reproduction and the boundary-case analysis.

I inspected the current PR head (25e2f11). Your finding is valid: _parse_session_info_from_lite() checks isSidechain only in the head window, so the disk fast path can disagree with fold_session_summary() when the first explicit flag occurs later.

One additional consideration: scanning the tail alone may not guarantee first explicit boolean wins for larger transcripts, because the first flag could occur in the unexamined middle. A complete fix should preserve that ordering, potentially using a streaming fallback when the head contains no explicit flag.

The regression coverage should include:

• First explicit isSidechain: true beyond 64 KiB.
• JSONL records crossing read boundaries.
• Conflicting explicit boolean values in different windows.
• Parity between the disk fast path and in-memory folding.

The current implementation does not resolve these cases yet. No passing validation or code fix is claimed by this response.

[senanurcetin]

@mangeshraut712 follow-up on the head/tail parity gap you found: it's fixed in two commits, and the current head is d435801.

• 182c597: the lite reader now takes the first explicit isSidechain boolean from the sampled bytes. For files up to 128 KiB it reconstructs the overlapping head and tail reads exactly. For larger files it also checks the tail, with no extra file reads.
• d435801: as I noted earlier, the tail alone can't prove ordering for larger transcripts. So when the head has no explicit flag and the file is larger than the two 64 KiB windows, it now scans the JSONL records in order. On disk it reads line by line; for store bytes already in memory it uses BytesIO. A tail flag can no longer override an earlier explicit flag in the unread middle, and the fast path is kept when the head already decides it.

New regression tests cover:

• late flags and head false precedence;
• lines that span the read boundaries, and multibyte UTF-8;
• conflicting booleans in the middle and tail;
• oversized single lines;
• Unicode-escaped flag keys.

The d435801 tests fail before the fix and pass after it.

Locally at d435801: 68/68 in tests/test_session_summary.py, and 1,647 passed / 21 skipped across the SDK suite. Ruff lint/format and targeted mypy are clean. Upstream CI hasn't run on this head yet.

Would you mind re-running your boundary reproduction against d435801?

[senanurcetin]

@mangeshraut712 thanks again for the reproduction. You were right that the disk lite path can disagree with the fold when the first explicit flag comes after the head.

I've cut the PR back to the fold_session_summary fix and its tests (1d7344b). The head/tail and ordered-scan code I added later made list_sessions() read the whole file for any large transcript with no flag in its head. That reader exists to avoid exactly that, so the fix cost more than the edge case is worth, and the tail can't show which flag came first anyway.

So the gap you found is still there: _parse_session_info_from_lite() checks only the first line, as the TypeScript SDK does. I'd rather open a separate issue for it, with a bounded option (complete lines in the head window only), than grow this PR.