claude-dev-env 8.88.4 → 8.88.6

package/hooks/session/compaction_trim_eval.py

@@ -0,0 +1,343 @@
+#!/usr/bin/env python3
+"""Score how well the compaction agent hook condenses the user's messages.
+
+::
+
+    python3 compaction_trim_eval.py --reps 3
+    deploy_session.jsonl rep 1  facts 13/13  overruled 1/1  ratio 1.6x
+    ...
+    model: facts 1.00  overruled 1.00  ratio 1.7x  (9 runs)  errors 0
+    oracle (raw extract): facts 1.00 ...   null (empty reply): facts 0.00 ...
+
+Each case is a fixture transcript with planted facts: paths, numbers, a
+link, and a decision the user later reversed. The runner writes the
+extract with ``compaction_user_messages.py``, then sends the agent hook's
+own prompt from ``hooks.json`` to ``claude -p`` with the Read tool, the way
+Claude Code runs the hook. The grader checks that each fact survives and
+that the reversed line says ``overruled``.
+
+The oracle grades the raw extract and the null grades an empty reply, so a
+broken grader shows before any model score is trusted. A failed call goes
+to the errors list, never to a zero score.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+
+_hooks_directory = str(Path(__file__).resolve().parent.parent)
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+_session_directory = str(Path(__file__).resolve().parent)
+if _session_directory not in sys.path:
+    sys.path.insert(0, _session_directory)
+
+from compaction_user_messages import output_path_for, rendered_extract, typed_user_messages
+from hooks_constants.compaction_user_messages_constants import (
+    EVAL_ARGUMENTS_PLACEHOLDER,
+    EVAL_CASES_FILE_NAME,
+    EVAL_CLAUDE_EXECUTABLE,
+    EVAL_DEFAULT_MODEL,
+    EVAL_FIXTURE_DIRECTORY,
+    EVAL_HOOK_TYPE,
+    EVAL_HOOKS_JSON_PATH,
+    EVAL_JSON_OBJECT_START,
+    EVAL_MESSAGE_LINE_PATTERN_TEMPLATE,
+    EVAL_OVERRULED_MARKER,
+    EVAL_RESULTS_FILE_NAME,
+    EVAL_RESULTS_JSON_INDENT,
+    EVAL_SERVED_MODEL_SEPARATOR,
+    EVAL_SESSION_DIRECTORY,
+    EVAL_TIMEOUT_SECONDS,
+    EXTRACTOR_SCRIPT_NAME,
+    MESSAGES_HEADING,
+    OUTPUT_ENCODING,
+)
+
+
+@dataclass(frozen=True)
+class CaseScore:
+    """One graded condensed copy.
+
+    Attributes:
+        facts_kept: Planted facts found in the copy.
+        facts_total: Planted facts in the case.
+        overruled_marked: Reversed messages whose line says overruled.
+        overruled_total: Reversed messages in the case.
+        compression_ratio: Extract message characters per copy character.
+    """
+
+    facts_kept: int
+    facts_total: int
+    overruled_marked: int
+    overruled_total: int
+    compression_ratio: float
+
+
+@dataclass
+class EvalTally:
+    """Scores, errors, and per-run records gathered across every case."""
+
+    all_model_scores: list[CaseScore] = field(default_factory=list)
+    all_oracle_scores: list[CaseScore] = field(default_factory=list)
+    all_null_scores: list[CaseScore] = field(default_factory=list)
+    all_errors: list[str] = field(default_factory=list)
+    all_records: list[dict[str, object]] = field(default_factory=list)
+
+
+def _normalized(text: str) -> str:
+    return re.sub(r"\s+", " ", text).casefold()
+
+
+def _line_for_message(condensed_text: str, position: int) -> str:
+    line_pattern = re.compile(
+        EVAL_MESSAGE_LINE_PATTERN_TEMPLATE.format(position=position), re.MULTILINE
+    )
+    found_line = line_pattern.search(condensed_text)
+    return found_line.group(0) if found_line else ""
+
+
+def _overruled_marked(condensed_text: str, all_reversals: list[dict[str, int]]) -> int:
+    return sum(
+        EVAL_OVERRULED_MARKER
+        in _line_for_message(condensed_text, int(each_reversal["earlier"])).casefold()
+        for each_reversal in all_reversals
+    )
+
+
+def score_condensed(
+    condensed_text: str, all_case_fields: dict[str, object], extract_text: str
+) -> CaseScore:
+    """Grade one condensed copy against the case's planted facts.
+
+    ::
+
+        "#2 keep Postgres (overruled by #6)" and "#6 switch SQLite"
+        -> each fact found case-insensitively, the #2 line marked overruled
+
+    Args:
+        condensed_text: The text the hook would return as its reason.
+        all_case_fields: One entry from trim_cases.json.
+        extract_text: The extract the copy was made from, for the ratio.
+
+    Returns:
+        The counts and the compression ratio.
+    """
+    all_facts = [str(each_fact) for each_fact in all_case_fields["facts"]]
+    all_reversals = list(all_case_fields[EVAL_OVERRULED_MARKER])
+    normalized_copy = _normalized(condensed_text)
+    message_characters = len(extract_text.split(MESSAGES_HEADING, 1)[-1])
+    return CaseScore(
+        facts_kept=sum(_normalized(each_fact) in normalized_copy for each_fact in all_facts),
+        facts_total=len(all_facts),
+        overruled_marked=_overruled_marked(condensed_text, all_reversals),
+        overruled_total=len(all_reversals),
+        compression_ratio=message_characters / max(len(condensed_text), 1),
+    )
+
+
+def condensing_hook_prompt(hooks_json_text: str) -> str:
+    """Return the prompt of the PostToolUse agent hook that condenses the messages."""
+    all_registrations = json.loads(hooks_json_text)["hooks"]["PostToolUse"]
+    return next(
+        str(each_hook["prompt"])
+        for each_group in all_registrations
+        for each_hook in each_group["hooks"]
+        if each_hook.get("type") == EVAL_HOOK_TYPE
+        and EXTRACTOR_SCRIPT_NAME in str(each_hook.get("if", ""))
+    )
+
+
+def hook_reason(model_reply: str) -> str | None:
+    """Return the ``reason`` of the last JSON decision in the reply, or None when there is none."""
+    decoder = json.JSONDecoder()
+    found_reason = None
+    for each_index, each_character in enumerate(model_reply):
+        if each_character != EVAL_JSON_OBJECT_START:
+            continue
+        try:
+            decision, _ = decoder.raw_decode(model_reply, each_index)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(decision, dict) and isinstance(decision.get("reason"), str):
+            found_reason = decision["reason"]
+    return found_reason
+
+
+def _write_extract(transcript_path: Path) -> tuple[Path, str]:
+    all_lines = transcript_path.read_text(encoding=OUTPUT_ENCODING).splitlines()
+    extract_text = rendered_extract(typed_user_messages(all_lines))
+    extract_path = output_path_for(transcript_path)
+    extract_path.write_text(extract_text, encoding=OUTPUT_ENCODING)
+    return extract_path, extract_text
+
+
+def _hook_input(transcript_path: Path, extract_path: Path) -> str:
+    command = f"python3 {EVAL_SESSION_DIRECTORY / EXTRACTOR_SCRIPT_NAME} {transcript_path}"
+    return json.dumps(
+        {
+            "hook_event_name": "PostToolUse",
+            "tool_name": "Bash",
+            "tool_input": {"command": command},
+            "tool_response": {"stdout": f"{extract_path}\n", "stderr": "", "interrupted": False},
+        }
+    )
+
+
+def _ask_model(prompt_text: str, model_name: str) -> dict[str, object]:
+    command = [
+        shutil.which(EVAL_CLAUDE_EXECUTABLE) or EVAL_CLAUDE_EXECUTABLE,
+        "-p",
+        "--model",
+        model_name,
+        "--setting-sources",
+        "",
+        "--tools",
+        "Read",
+        "--allowedTools=Read",
+        "--no-session-persistence",
+        "--session-id",
+        str(uuid.uuid4()),
+        "--output-format",
+        "json",
+    ]
+    completed = subprocess.run(
+        command,
+        input=prompt_text,
+        capture_output=True,
+        text=True,
+        timeout=EVAL_TIMEOUT_SECONDS,
+        cwd=tempfile.gettempdir(),
+        check=False,
+    )
+    return json.loads(completed.stdout)
+
+
+def _run_line(run_label: str, case_score: CaseScore, all_served_models: list[str]) -> str:
+    return (
+        f"{run_label}  facts {case_score.facts_kept}/{case_score.facts_total}  "
+        f"overruled {case_score.overruled_marked}/{case_score.overruled_total}  "
+        f"ratio {case_score.compression_ratio:.1f}x  "
+        f"served {EVAL_SERVED_MODEL_SEPARATOR.join(all_served_models)}\n"
+    )
+
+
+def _run_once(
+    run_label: str,
+    prompt_text: str,
+    model_name: str,
+    all_case_fields: dict[str, object],
+    extract_text: str,
+    tally: EvalTally,
+) -> None:
+    try:
+        model_output = _ask_model(prompt_text, model_name)
+    except (OSError, subprocess.TimeoutExpired, json.JSONDecodeError) as call_error:
+        tally.all_errors.append(f"{run_label}: {type(call_error).__name__}")
+        return
+    condensed_text = hook_reason(str(model_output.get("result", "")))
+    if model_output.get("is_error") or condensed_text is None:
+        tally.all_errors.append(f"{run_label}: no reason in reply")
+        return
+    case_score = score_condensed(condensed_text, all_case_fields, extract_text)
+    all_served_models = sorted(dict(model_output.get("modelUsage") or {}))
+    tally.all_model_scores.append(case_score)
+    tally.all_records.append(
+        {
+            "run": run_label,
+            "served_models": all_served_models,
+            "score": case_score.__dict__,
+            "condensed": condensed_text,
+        }
+    )
+    sys.stdout.write(_run_line(run_label, case_score, all_served_models))
+
+
+def _run_case(
+    all_case_fields: dict[str, object],
+    hook_prompt: str,
+    parsed_arguments: argparse.Namespace,
+    tally: EvalTally,
+) -> None:
+    transcript_path = EVAL_FIXTURE_DIRECTORY / str(all_case_fields["transcript"])
+    extract_path, extract_text = _write_extract(transcript_path)
+    tally.all_oracle_scores.append(score_condensed(extract_text, all_case_fields, extract_text))
+    tally.all_null_scores.append(score_condensed("", all_case_fields, extract_text))
+    prompt_text = hook_prompt.replace(
+        EVAL_ARGUMENTS_PLACEHOLDER, _hook_input(transcript_path, extract_path)
+    )
+    for each_rep in range(1, parsed_arguments.reps + 1):
+        _run_once(
+            f"{transcript_path.name} rep {each_rep}",
+            prompt_text,
+            parsed_arguments.model,
+            all_case_fields,
+            extract_text,
+            tally,
+        )
+
+
+def _summary_line(label: str, all_scores: list[CaseScore]) -> str:
+    if not all_scores:
+        return f"{label}: no scored runs"
+    facts_total = sum(each_score.facts_total for each_score in all_scores)
+    facts_share = sum(each_score.facts_kept for each_score in all_scores) / facts_total
+    overruled_total = sum(each_score.overruled_total for each_score in all_scores)
+    overruled_marked = sum(each_score.overruled_marked for each_score in all_scores)
+    overruled_share = overruled_marked / max(overruled_total, 1)
+    mean_ratio = sum(each_score.compression_ratio for each_score in all_scores) / len(all_scores)
+    return (
+        f"{label}: facts {facts_share:.2f}  overruled {overruled_share:.2f}  "
+        f"ratio {mean_ratio:.1f}x  ({len(all_scores)} runs)"
+    )
+
+
+def _write_report(tally: EvalTally, output_directory: Path | None) -> None:
+    sys.stdout.write(
+        _summary_line("model", tally.all_model_scores) + f"  errors {len(tally.all_errors)}\n"
+    )
+    sys.stdout.write(_summary_line("oracle (raw extract)", tally.all_oracle_scores) + "\n")
+    sys.stdout.write(_summary_line("null (empty reply)", tally.all_null_scores) + "\n")
+    for each_error in tally.all_errors:
+        sys.stdout.write(f"error: {each_error}\n")
+    if output_directory is None:
+        return
+    output_directory.mkdir(parents=True, exist_ok=True)
+    (output_directory / EVAL_RESULTS_FILE_NAME).write_text(
+        json.dumps(
+            {"records": tally.all_records, "errors": tally.all_errors},
+            indent=EVAL_RESULTS_JSON_INDENT,
+        ),
+        encoding=OUTPUT_ENCODING,
+    )
+
+
+def main() -> int:
+    """Run every case through the hook prompt, grade it, and print the scores."""
+    argument_parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    argument_parser.add_argument("--reps", type=int, default=1)
+    argument_parser.add_argument("--model", default=EVAL_DEFAULT_MODEL)
+    argument_parser.add_argument("--output-dir", type=Path, default=None)
+    parsed_arguments = argument_parser.parse_args()
+    all_cases = json.loads(
+        (EVAL_FIXTURE_DIRECTORY / EVAL_CASES_FILE_NAME).read_text(encoding=OUTPUT_ENCODING)
+    )
+    hook_prompt = condensing_hook_prompt(EVAL_HOOKS_JSON_PATH.read_text(encoding=OUTPUT_ENCODING))
+    tally = EvalTally()
+    for each_case in all_cases:
+        _run_case(each_case, hook_prompt, parsed_arguments, tally)
+    _write_report(tally, parsed_arguments.output_dir)
+    return 0 if tally.all_model_scores and not tally.all_errors else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/hooks/session/compaction_user_messages.py

@@ -0,0 +1,306 @@
+#!/usr/bin/env python3
+"""Write every message the user typed in a session to a file, and print its path.
+
+::
+
+    python3 compaction_user_messages.py ~/.claude/projects/p/abc.jsonl
+    -> /tmp/compaction-user-messages-abc.md
+
+The agent runs this after a compaction. Only the path reaches its context.
+A PostToolUse agent hook reads the file, condenses it, and returns the
+condensed messages to the agent.
+
+The file holds the trim rules, then each typed message with its number and
+timestamp, oldest first. The whole transcript is read each time, so a second
+compaction yields the same messages plus the newer ones.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import tempfile
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+from pathlib import Path
+
+_hooks_directory = str(Path(__file__).resolve().parent.parent)
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+
+from hooks_constants.compaction_user_messages_constants import (
+    ALL_SKIPPED_ENTRY_FLAGS,
+    ASSISTANT_ENTRY_TYPE,
+    ATTACHMENT_ENTRY_TYPE,
+    ATTACHMENT_KEY,
+    BLOCK_SEPARATOR,
+    BLOCK_TYPE_KEY,
+    CONTENT_KEY,
+    CUT_MESSAGE_SUFFIX_TEMPLATE,
+    ENTRY_TYPE_KEY,
+    HARNESS_TAG_OPENING_PATTERN,
+    HUMAN_ORIGIN_KIND,
+    IMAGE_BLOCK_TYPE,
+    IMAGE_PLACEHOLDER,
+    LEFT_OUT_MESSAGES_TEMPLATE,
+    MAXIMUM_EXTRACT_CHARACTERS,
+    MAXIMUM_MESSAGE_CHARACTERS,
+    MESSAGE_HEADING_TEMPLATE,
+    MESSAGE_KEY,
+    MESSAGES_HEADING,
+    NO_MESSAGES_TEXT,
+    ORIGIN_KEY,
+    ORIGIN_KIND_KEY,
+    OUTPUT_ENCODING,
+    OUTPUT_FILE_PREFIX,
+    OUTPUT_FILE_SUFFIX,
+    QUEUED_COMMAND_ATTACHMENT_TYPE,
+    QUEUED_PROMPT_KEY,
+    SLASH_COMMAND_ARGS_PATTERN,
+    SLASH_COMMAND_NAME_PATTERN,
+    TEXT_BLOCK_TYPE,
+    TEXT_KEY,
+    TIMESTAMP_KEY,
+    TRANSCRIPT_ARGUMENT_COUNT,
+    TRIM_INSTRUCTIONS,
+    USAGE_EXIT_CODE,
+    USAGE_TEXT,
+    USER_ENTRY_TYPE,
+)
+from hooks_constants.session_file_id import session_file_id
+from hooks_constants.setup_project_paths_constants import DECODE_ERRORS_POLICY, UTF8_ENCODING
+
+
+@dataclass(frozen=True)
+class TypedMessage:
+    """One message the user typed, numbered by its place among all typed messages.
+
+    Attributes:
+        position: 1 for the first typed message, counting up.
+        timestamp: The transcript timestamp, or an empty string.
+        text: The message text, with a slash command shown as ``/name args``.
+    """
+
+    position: int
+    timestamp: str
+    text: str
+
+
+def _parsed_entry(transcript_line: str) -> dict[str, object]:
+    try:
+        parsed_entry = json.loads(transcript_line)
+    except json.JSONDecodeError:
+        return {}
+    return parsed_entry if isinstance(parsed_entry, dict) else {}
+
+
+def _block_text(block: object) -> str | None:
+    if not isinstance(block, dict):
+        return None
+    if block.get(BLOCK_TYPE_KEY) == TEXT_BLOCK_TYPE:
+        return str(block.get(TEXT_KEY, ""))
+    if block.get(BLOCK_TYPE_KEY) == IMAGE_BLOCK_TYPE:
+        return IMAGE_PLACEHOLDER
+    return None
+
+
+def _content_text(content: object) -> str:
+    if isinstance(content, str):
+        return content
+    all_blocks = content if isinstance(content, list) else []
+    all_parts = [_block_text(each_block) for each_block in all_blocks]
+    return BLOCK_SEPARATOR.join(each_part for each_part in all_parts if each_part is not None)
+
+
+def _typed_text(raw_text: str) -> str | None:
+    stripped_text = raw_text.strip()
+    command_name = SLASH_COMMAND_NAME_PATTERN.search(stripped_text)
+    if command_name:
+        command_args = SLASH_COMMAND_ARGS_PATTERN.search(stripped_text)
+        typed_args = command_args.group(1).strip() if command_args else ""
+        return f"{command_name.group(1)} {typed_args}".strip()
+    if not stripped_text or HARNESS_TAG_OPENING_PATTERN.match(stripped_text):
+        return None
+    return stripped_text
+
+
+def _is_typed_by_a_person(all_entry_fields: dict[str, object]) -> bool:
+    if any(all_entry_fields.get(each_flag) for each_flag in ALL_SKIPPED_ENTRY_FLAGS):
+        return False
+    origin = all_entry_fields.get(ORIGIN_KEY)
+    return not isinstance(origin, dict) or origin.get(ORIGIN_KIND_KEY) == HUMAN_ORIGIN_KIND
+
+
+def _entry_text(all_entry_fields: dict[str, object]) -> str | None:
+    entry_type = all_entry_fields.get(ENTRY_TYPE_KEY)
+    if entry_type == USER_ENTRY_TYPE and _is_typed_by_a_person(all_entry_fields):
+        message = all_entry_fields.get(MESSAGE_KEY)
+        content = message.get(CONTENT_KEY) if isinstance(message, dict) else None
+        return _typed_text(_content_text(content))
+    if entry_type != ATTACHMENT_ENTRY_TYPE:
+        return None
+    attachment = all_entry_fields.get(ATTACHMENT_KEY)
+    if not isinstance(attachment, dict):
+        return None
+    if attachment.get(ENTRY_TYPE_KEY) != QUEUED_COMMAND_ATTACHMENT_TYPE:
+        return None
+    queued_prompt = attachment.get(QUEUED_PROMPT_KEY)
+    return _typed_text(queued_prompt) if isinstance(queued_prompt, str) else None
+
+
+def _typed_texts(all_transcript_lines: Iterable[str]) -> Iterator[tuple[str, str]]:
+    previous_text = None
+    for each_line in all_transcript_lines:
+        all_entry_fields = _parsed_entry(each_line)
+        if all_entry_fields.get(ENTRY_TYPE_KEY) == ASSISTANT_ENTRY_TYPE:
+            previous_text = None
+            continue
+        entry_text = _entry_text(all_entry_fields)
+        if entry_text is None or entry_text == previous_text:
+            continue
+        previous_text = entry_text
+        yield str(all_entry_fields.get(TIMESTAMP_KEY, "")), entry_text
+
+
+def typed_user_messages(all_transcript_lines: Iterable[str]) -> list[TypedMessage]:
+    """Return the messages a person typed, in order, numbered from 1.
+
+    ::
+
+        user "fix the login bug"                       -> kept
+        user "<command-name>/deepen</command-name>
+              <command-args>speed it up</command-args>" -> "/deepen speed it up"
+        user tool_result, isMeta skill body,
+        isCompactSummary, isSidechain, origin peer     -> left out
+        user "<system-reminder>...", "<local-command-stdout>" -> left out
+        attachment queued_command "also check logs"    -> kept
+
+    A message repeated right after itself, such as a queued prompt that later
+    lands as a user entry, counts once.
+
+    Args:
+        all_transcript_lines: The session transcript, one JSON entry per line.
+
+    Returns:
+        The typed messages, oldest first.
+    """
+    return [
+        TypedMessage(position=each_position, timestamp=each_timestamp, text=each_text)
+        for each_position, (each_timestamp, each_text) in enumerate(
+            _typed_texts(all_transcript_lines), start=1
+        )
+    ]
+
+
+def _capped_text(text: str) -> str:
+    if len(text) <= MAXIMUM_MESSAGE_CHARACTERS:
+        return text
+    cut_count = len(text) - MAXIMUM_MESSAGE_CHARACTERS
+    return text[:MAXIMUM_MESSAGE_CHARACTERS] + CUT_MESSAGE_SUFFIX_TEMPLATE.format(
+        cut_count=cut_count
+    )
+
+
+def _rendered_message(message: TypedMessage) -> str:
+    return MESSAGE_HEADING_TEMPLATE.format(
+        position=message.position,
+        timestamp=message.timestamp,
+        text=_capped_text(message.text),
+    )
+
+
+def bounded_messages(all_messages: list[TypedMessage]) -> list[TypedMessage]:
+    """Return the messages that fit the extract budget: the first, then the newest.
+
+    ::
+
+        5 short messages             -> all 5
+        #1 plus 400 long messages    -> #1, then the newest that fit
+
+    The first message keeps the session's original ask. The newest carry the
+    latest corrections, which override older asks.
+
+    Args:
+        all_messages: Every typed message, oldest first.
+
+    Returns:
+        The kept messages, oldest first.
+    """
+    if not all_messages:
+        return []
+    first_message, *all_later_messages = all_messages
+    remaining_characters = MAXIMUM_EXTRACT_CHARACTERS - len(_rendered_message(first_message))
+    all_kept_later_messages: list[TypedMessage] = []
+    for each_message in reversed(all_later_messages):
+        message_size = len(_rendered_message(each_message))
+        if message_size > remaining_characters:
+            break
+        remaining_characters -= message_size
+        all_kept_later_messages.append(each_message)
+    return [first_message, *reversed(all_kept_later_messages)]
+
+
+def rendered_extract(all_messages: list[TypedMessage]) -> str:
+    """Return the file text: the trim rules, then the kept messages.
+
+    ::
+
+        [#1 "fix login"]  -> TRIM_INSTRUCTIONS + "# User messages..." + "## 1 | <ts>\\nfix login"
+
+    Args:
+        all_messages: Every typed message, oldest first.
+
+    Returns:
+        The text the extractor writes to its output file.
+    """
+    if not all_messages:
+        return TRIM_INSTRUCTIONS + MESSAGES_HEADING + NO_MESSAGES_TEXT
+    all_kept_messages = bounded_messages(all_messages)
+    left_out_count = len(all_messages) - len(all_kept_messages)
+    rendered_parts = [TRIM_INSTRUCTIONS, MESSAGES_HEADING]
+    for each_index, each_message in enumerate(all_kept_messages):
+        if each_index == 1 and left_out_count:
+            rendered_parts.append(LEFT_OUT_MESSAGES_TEMPLATE.format(left_out_count=left_out_count))
+        rendered_parts.append(_rendered_message(each_message))
+    return "".join(rendered_parts)
+
+
+def output_path_for(transcript_path: Path) -> Path:
+    """Return the temp file for one transcript, named after its session id.
+
+    ::
+
+        ~/.claude/projects/p/abc-123.jsonl -> /tmp/compaction-user-messages-abc-123.md
+
+    Args:
+        transcript_path: The session transcript.
+
+    Returns:
+        The path the extractor writes; a rerun overwrites it.
+    """
+    file_name = f"{OUTPUT_FILE_PREFIX}{session_file_id(transcript_path.stem)}{OUTPUT_FILE_SUFFIX}"
+    return Path(tempfile.gettempdir()) / file_name
+
+
+def main() -> int:
+    """Write the extract for the transcript named on the command line and print its path."""
+    if len(sys.argv) != TRANSCRIPT_ARGUMENT_COUNT:
+        sys.stderr.write(USAGE_TEXT)
+        return USAGE_EXIT_CODE
+    transcript_path = Path(sys.argv[1])
+    try:
+        with transcript_path.open(
+            encoding=UTF8_ENCODING, errors=DECODE_ERRORS_POLICY
+        ) as transcript:
+            all_messages = typed_user_messages(transcript)
+    except OSError as read_error:
+        sys.stderr.write(f"cannot read {transcript_path}: {read_error}\n")
+        return USAGE_EXIT_CODE
+    output_path = output_path_for(transcript_path)
+    output_path.write_text(rendered_extract(all_messages), encoding=OUTPUT_ENCODING)
+    sys.stdout.write(f"{output_path}\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/hooks/session/fixtures/compaction_user_messages/deploy_session.jsonl

@@ -0,0 +1,17 @@
+{"type": "user", "timestamp": "2026-10-19T10:00:01Z", "message": {"role": "user", "content": "<command-message>deepen</command-message>\n<command-name>/deepen</command-name>\n<command-args>migrate the billing service off the old cron box. the cron box is batch-07.internal and the job runs at 02:15 UTC</command-args>"}, "origin": {"kind": "human"}}
+{"type": "user", "timestamp": "2026-10-19T10:00:02Z", "message": {"role": "user", "content": [{"type": "text", "text": "Base directory for this skill: ~/.claude/skills/deepen\n\n# deepen ..."}]}, "isMeta": true}
+{"type": "assistant", "timestamp": "2026-10-19T10:00:03Z", "message": {"role": "assistant", "content": [{"type": "text", "text": "I will look at the cron config."}]}}
+{"type": "user", "timestamp": "2026-10-19T10:00:04Z", "message": {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "toolu_1", "content": "15 2 * * * /opt/billing/run.sh"}]}}
+{"type": "user", "timestamp": "2026-10-19T10:00:05Z", "message": {"role": "user", "content": "we store invoices in Postgres, keep using Postgres for the new service. the table is billing.invoices_v3"}, "origin": {"kind": "human"}}
+{"type": "user", "timestamp": "2026-10-19T10:00:06Z", "message": {"role": "user", "content": "<system-reminder>Task tools available.</system-reminder>"}}
+{"type": "assistant", "timestamp": "2026-10-19T10:00:07Z", "message": {"role": "assistant", "content": [{"type": "text", "text": "Understood."}]}}
+{"type": "user", "timestamp": "2026-10-19T10:00:08Z", "message": {"role": "user", "content": "ok"}, "origin": {"kind": "human"}}
+{"type": "user", "timestamp": "2026-10-19T10:00:09Z", "message": {"role": "user", "content": "dont touch packages/billing/legacy_export.py, finance still reads its CSV every Monday"}, "origin": {"kind": "human"}}
+{"type": "attachment", "timestamp": "2026-10-19T10:00:10Z", "attachment": {"type": "queued_command", "prompt": "<agent-message from=\"a1\">[Subagent hand-back] I suggest MySQL.</agent-message>"}}
+{"type": "user", "timestamp": "2026-10-19T10:00:11Z", "message": {"role": "user", "content": [{"type": "text", "text": "[Request interrupted by user]"}]}, "origin": {"kind": "human"}}
+{"type": "user", "timestamp": "2026-10-19T10:00:12Z", "message": {"role": "user", "content": "change of plan: switch the new service to SQLite, not Postgres. ops wont give us a db until Q3"}, "origin": {"kind": "human"}}
+{"type": "user", "timestamp": "2026-10-19T10:00:13Z", "message": {"role": "user", "content": [{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": ""}}, {"type": "text", "text": "this is the error from the staging run, exit code 137"}]}, "origin": {"kind": "human"}}
+{"type": "user", "timestamp": "2026-10-19T10:00:14Z", "message": {"role": "user", "content": "retry budget is 4 attempts with 30s backoff. the PR goes to https://github.com/acme/billing/pull/812 and needs Dana's review"}, "origin": {"kind": "human"}}
+{"type": "user", "timestamp": "2026-10-19T10:00:15Z", "message": {"role": "user", "content": "thanks"}, "origin": {"kind": "human"}}
+{"type": "system", "subtype": "compact_boundary", "timestamp": "2026-10-19T10:00:16Z", "content": "Conversation compacted"}
+{"type": "user", "timestamp": "2026-10-19T10:00:17Z", "message": {"role": "user", "content": "This session is being continued from a previous conversation..."}, "isCompactSummary": true}