refactor: underscore-prefix internal fold-state fields in SessionSummaryEntry

Author: qing-ant

src/claude_agent_sdk/_internal/session_summary.py

@@ -71,12 +71,12 @@ def _entry_text_blocks(entry: dict[str, Any]) -> list[str]:
 def _fold_first_prompt(summary: SessionSummaryEntry, entry: dict[str, Any]) -> None:
     """Replicate ``_extract_first_prompt_from_head`` for a single parsed entry.
 
-    Mutates ``summary`` in place: sets ``first_prompt`` + ``first_prompt_locked``
-    on a real match, or stashes a ``command_fallback`` for slash-command
-    messages. Skips tool_result, isMeta, isCompactSummary, and auto-generated
-    patterns.
+    Mutates ``summary`` in place: sets ``first_prompt`` +
+    ``_first_prompt_locked`` on a real match, or stashes a
+    ``_command_fallback`` for slash-command messages. Skips tool_result,
+    isMeta, isCompactSummary, and auto-generated patterns.
     """
-    if summary.get("first_prompt_locked"):
+    if summary.get("_first_prompt_locked"):
         return
     if entry.get("type") != "user":
         return
@@ -97,15 +97,15 @@ def _fold_first_prompt(summary: SessionSummaryEntry, entry: dict[str, Any]) -> N
             continue
         cmd_match = _COMMAND_NAME_RE.search(result)
         if cmd_match:
-            if not summary.get("command_fallback"):
-                summary["command_fallback"] = cmd_match.group(1)
+            if not summary.get("_command_fallback"):
+                summary["_command_fallback"] = cmd_match.group(1)
             continue
         if _SKIP_FIRST_PROMPT_PATTERN.match(result):
             continue
         if len(result) > 200:
             result = result[:200].rstrip() + "\u2026"
         summary["first_prompt"] = result
-        summary["first_prompt_locked"] = True
+        summary["_first_prompt_locked"] = True
         return
 
 
@@ -181,8 +181,8 @@ def summary_entry_to_sdk_info(
 
     first_prompt = (
         entry.get("first_prompt")
-        if entry.get("first_prompt_locked")
-        else entry.get("command_fallback")
+        if entry.get("_first_prompt_locked")
+        else entry.get("_command_fallback")
     ) or None
     custom_title = entry.get("custom_title") or entry.get("ai_title") or None
     summary = (

src/claude_agent_sdk/types.py

@@ -1166,6 +1166,10 @@ class SessionSummaryEntry(TypedDict, total=False):
     :func:`fold_session_summary` and return the full set from
     :meth:`SessionStore.list_session_summaries`. Every field is
     append-incremental (set-once or last-wins) so adapters never re-read.
+
+    Fields prefixed ``_`` are opaque fold state — stores MUST persist them
+    verbatim across :func:`fold_session_summary` calls but SHOULD NOT
+    interpret them.
     """
 
     session_id: Required[str]
@@ -1177,11 +1181,6 @@ class SessionSummaryEntry(TypedDict, total=False):
     cwd: str
     first_prompt: str
     """First meaningful user prompt, truncated to 200 chars."""
-    first_prompt_locked: bool
-    """Internal: ``True`` once a non-command prompt has been found."""
-    command_fallback: str
-    """Internal: first ``<command-name>`` seen, used when no real prompt
-    appears."""
     custom_title: str
     ai_title: str
     last_prompt: str
@@ -1190,6 +1189,11 @@ class SessionSummaryEntry(TypedDict, total=False):
     git_branch: str
     tag: str
     file_size: int
+    _first_prompt_locked: bool
+    """Opaque fold state: ``True`` once a non-command prompt has been found."""
+    _command_fallback: str
+    """Opaque fold state: first ``<command-name>`` seen, used when no real
+    prompt appears."""
 
 
 class SessionListSubkeysKey(TypedDict):

tests/test_session_summary.py

@@ -181,7 +181,7 @@ def test_first_prompt_skips_meta_tool_result_and_compact(self) -> None:
             ],
         )
         assert s["first_prompt"] == "real first"
-        assert s["first_prompt_locked"] is True
+        assert s["_first_prompt_locked"] is True
 
     def test_first_prompt_command_fallback(self) -> None:
         s = fold_session_summary(
@@ -192,12 +192,12 @@ def test_first_prompt_command_fallback(self) -> None:
                 _user("<command-name>/second</command-name>"),
             ],
         )
-        assert s.get("first_prompt_locked") is not True
-        assert s["command_fallback"] == "/init"
+        assert s.get("_first_prompt_locked") is not True
+        assert s["_command_fallback"] == "/init"
         # A later real prompt locks it.
         s2 = fold_session_summary(s, KEY, [_user("now real")])
         assert s2["first_prompt"] == "now real"
-        assert s2["first_prompt_locked"] is True
+        assert s2["_first_prompt_locked"] is True
 
     def test_first_prompt_skip_pattern(self) -> None:
         s = fold_session_summary(
@@ -246,8 +246,8 @@ def test_precedence_chain(self) -> None:
             "session_id": "s",
             "mtime": 1,
             "first_prompt": "fp",
-            "first_prompt_locked": True,
-            "command_fallback": "/cmd",
+            "_first_prompt_locked": True,
+            "_command_fallback": "/cmd",
             "summary_hint": "sh",
             "last_prompt": "lp",
             "ai_title": "ai",
@@ -272,7 +272,7 @@ def test_precedence_chain(self) -> None:
         info = summary_entry_to_sdk_info(base, None)
         assert info is not None and info.summary == "fp" and info.first_prompt == "fp"
 
-        base["first_prompt_locked"] = False
+        base["_first_prompt_locked"] = False
         info = summary_entry_to_sdk_info(base, None)
         assert (
             info is not None and info.summary == "/cmd" and info.first_prompt == "/cmd"