claude-dev-env 8.40.1 → 8.42.0

package/hooks/routing/spawn_readiness_hook.py

@@ -1,20 +1,24 @@
 #!/usr/bin/env python3
-"""PreToolUse hook: hold an agent spawn until the session has read and asked.
+"""PreToolUse hook: remind a session to read and ask before it spawns agents.
 
-Registered on ``Agent``, ``Task``, and ``mcp__hearthbot__start_thread_session``.
-It reads the session transcript and checks two things since the user's request:
+Registered on ``Agent``, ``Task``, ``mcp__hearthbot__start_thread_session``,
+``multi_agent_v1__spawn_agent``, ``Workflow``, and a workflow dispatch whose
+inputs carry a ``prompt``. It reads the session transcript and checks two
+things since the user's request:
 
 ::
 
-    no read step after the request              -> deny: investigate first
-    no interactive question, then an answer     -> deny: interview first
+    no read step after the request              -> context: investigate first
+    no interactive question, then an answer     -> context: interview first
     brief line "Scope settled: <reason>"        -> interview check passes, logged
-    both found                                  -> no output; the call runs
+    both found                                  -> no output
+    Codex payload (turn_id), no settled line    -> context: the Codex reminder
 
-``spawn_readiness_steps`` reads the transcript and finds the request. Four
-cases pass without a check: a call from inside a subagent, a read-only
-subagent type, a tool input that is not an object, and a transcript the hook
-cannot read. The last one is logged.
+The output is ``additionalContext`` alone, so the spawn runs and keeps its
+normal permission flow. ``spawn_readiness_steps`` reads the transcript and
+finds the request. Four cases pass without a check: a call from inside a
+subagent, a read-only subagent type, a tool input that is not an object, and a
+transcript the hook cannot read. The last one is logged.
 """
 
 from __future__ import annotations
@@ -31,13 +35,19 @@ routing_directory = str(Path(__file__).resolve().parent)
 if routing_directory not in sys.path:
     sys.path.insert(0, routing_directory)
 
-from hooks_constants.hook_block_logger import log_hook_block
 from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
 from hooks_constants.spawn_readiness_hook_constants import (
+    ADDITIONAL_CONTEXT_KEY,
     AGENT_ID_KEY,
     ALL_BRIEF_FIELDS_BY_SPAWN_TOOL_NAME,
     ALL_READ_ONLY_SUBAGENT_TYPES,
+    CODEX_TRANSCRIPT_REMINDER,
+    CODEX_TURN_ID_KEY,
     DECISION_LOG_RELATIVE_PATH,
+    DISPATCH_INPUTS_KEY,
+    DISPATCH_METHOD_INPUT_KEY,
+    DISPATCH_PROMPT_INPUT_KEY,
+    DISPATCH_RUN_WORKFLOW_METHOD,
     HOOK_EVENT_NAME_KEY,
     HOOK_SPECIFIC_OUTPUT_KEY,
     LOG_APPEND_MODE,
@@ -48,11 +58,9 @@ from hooks_constants.spawn_readiness_hook_constants import (
     LOG_TOOL_NAME_KEY,
     LOG_TOOL_USE_ID_KEY,
     MISSING_INTERVIEW_REASON,
+    OUTCOME_REMINDED,
     OUTCOME_SCOPE_SETTLED,
     OUTCOME_TRANSCRIPT_UNREADABLE,
-    PERMISSION_DECISION_KEY,
-    PERMISSION_DECISION_REASON_KEY,
-    PERMISSION_DENY,
     PRE_TOOL_USE_EVENT_NAME,
     REASON_SEPARATOR,
     SCOPE_SETTLED_PREFIX,
@@ -63,11 +71,67 @@ from hooks_constants.spawn_readiness_hook_constants import (
     TRANSCRIPT_DECODE_ERRORS,
     TRANSCRIPT_ENCODING,
     TRANSCRIPT_PATH_KEY,
+    WORKFLOW_DISPATCH_TOOL_NAME,
+    WORKFLOW_SCRIPT_PATH_INPUT_KEY,
+    WORKFLOW_TOOL_NAME,
 )
 from spawn_readiness_steps import readiness_gaps, session_steps
 
 
-def scope_settled_line(tool_name: str, all_tool_input_fields: dict[str, object]) -> str | None:
+def _workflow_script(all_tool_input_fields: dict[str, object]) -> str:
+    script = all_tool_input_fields.get(ALL_BRIEF_FIELDS_BY_SPAWN_TOOL_NAME[WORKFLOW_TOOL_NAME])
+    if isinstance(script, str):
+        return script
+    script_path = all_tool_input_fields.get(WORKFLOW_SCRIPT_PATH_INPUT_KEY)
+    if not isinstance(script_path, str) or not script_path:
+        return ""
+    try:
+        return Path(script_path).read_text(
+            encoding=TRANSCRIPT_ENCODING, errors=TRANSCRIPT_DECODE_ERRORS
+        )
+    except OSError:
+        return ""
+
+
+def _dispatch_prompt(all_tool_input_fields: dict[str, object]) -> str | None:
+    if all_tool_input_fields.get(DISPATCH_METHOD_INPUT_KEY) != DISPATCH_RUN_WORKFLOW_METHOD:
+        return None
+    workflow_inputs = all_tool_input_fields.get(DISPATCH_INPUTS_KEY)
+    if not isinstance(workflow_inputs, dict):
+        return None
+    prompt = workflow_inputs.get(DISPATCH_PROMPT_INPUT_KEY)
+    return prompt if isinstance(prompt, str) else None
+
+
+def spawn_brief(tool_name: str, all_tool_input_fields: dict[str, object]) -> str | None:
+    """Return the brief a spawn call hands its agents, or None when the call spawns none.
+
+    ::
+
+        Agent             {"prompt": "Do X."}                         -> "Do X."
+        Workflow          {"scriptPath": "w.js"}                      -> the text of w.js
+        actions trigger   {"method": "run_workflow",
+                           "inputs": {"prompt": "Do X."}}             -> "Do X."
+        actions trigger   {"method": "cancel_workflow_run"}           -> None
+        Agent             {"subagent_type": "Explore", "prompt": ...} -> None
+
+    Args:
+        tool_name: The tool the session called.
+        all_tool_input_fields: The tool input.
+    """
+    if tool_name == WORKFLOW_DISPATCH_TOOL_NAME:
+        return _dispatch_prompt(all_tool_input_fields)
+    if tool_name not in ALL_BRIEF_FIELDS_BY_SPAWN_TOOL_NAME:
+        return None
+    if all_tool_input_fields.get(SUBAGENT_TYPE_INPUT_KEY) in ALL_READ_ONLY_SUBAGENT_TYPES:
+        return None
+    if tool_name == WORKFLOW_TOOL_NAME:
+        return _workflow_script(all_tool_input_fields)
+    brief = all_tool_input_fields.get(ALL_BRIEF_FIELDS_BY_SPAWN_TOOL_NAME[tool_name])
+    return brief if isinstance(brief, str) else ""
+
+
+def scope_settled_line(brief: str) -> str | None:
     """Return the brief's "Scope settled:" line when it names a reason, else None.
 
     ::
@@ -77,12 +141,8 @@ def scope_settled_line(tool_name: str, all_tool_input_fields: dict[str, object])
         "Do X.\\nScope settled:"  -> None
 
     Args:
-        tool_name: The spawn tool, which decides the brief field.
-        all_tool_input_fields: The spawn input.
+        brief: The text the spawn hands its agents.
     """
-    brief = all_tool_input_fields.get(ALL_BRIEF_FIELDS_BY_SPAWN_TOOL_NAME.get(tool_name, ""))
-    if not isinstance(brief, str):
-        return None
     for each_line in brief.splitlines():
         stripped_line = each_line.strip()
         stated_reason = stripped_line.removeprefix(SCOPE_SETTLED_PREFIX).strip()
@@ -125,24 +185,35 @@ def _transcript_lines(transcript_path: object) -> list[str] | None:
         return None
 
 
-def _deny_output(reason: str) -> dict[str, object]:
+def _context_output(context: str) -> dict[str, object]:
     return {
         HOOK_SPECIFIC_OUTPUT_KEY: {
             HOOK_EVENT_NAME_KEY: PRE_TOOL_USE_EVENT_NAME,
-            PERMISSION_DECISION_KEY: PERMISSION_DENY,
-            PERMISSION_DECISION_REASON_KEY: reason,
+            ADDITIONAL_CONTEXT_KEY: context,
         }
     }
 
 
-def _is_checked_spawn(all_hook_fields: dict[str, object]) -> bool:
-    tool_input = all_hook_fields.get(TOOL_INPUT_KEY)
-    return (
-        all_hook_fields.get(TOOL_NAME_KEY) in ALL_BRIEF_FIELDS_BY_SPAWN_TOOL_NAME
-        and isinstance(tool_input, dict)
-        and not all_hook_fields.get(AGENT_ID_KEY)
-        and tool_input.get(SUBAGENT_TYPE_INPUT_KEY) not in ALL_READ_ONLY_SUBAGENT_TYPES
-    )
+def _transcript_gaps(
+    all_hook_fields: dict[str, object], tool_use_id: str | None
+) -> list[str] | None:
+    if all_hook_fields.get(CODEX_TURN_ID_KEY):
+        return [CODEX_TRANSCRIPT_REMINDER]
+    all_transcript_lines = _transcript_lines(all_hook_fields.get(TRANSCRIPT_PATH_KEY))
+    if all_transcript_lines is None:
+        return None
+    return readiness_gaps(session_steps(all_transcript_lines, tool_use_id))
+
+
+def _gaps_after_scope_settled(
+    all_gaps: list[str], brief: str, tool_name: str, tool_use_id: str | None
+) -> list[str]:
+    settled_line = scope_settled_line(brief)
+    all_settled_gaps = {MISSING_INTERVIEW_REASON, CODEX_TRANSCRIPT_REMINDER}
+    if settled_line is None or not all_settled_gaps.intersection(all_gaps):
+        return all_gaps
+    _log_decision(tool_name, tool_use_id, OUTCOME_SCOPE_SETTLED, settled_line)
+    return [each_gap for each_gap in all_gaps if each_gap not in all_settled_gaps]
 
 
 def decide_hook_output(all_hook_fields: dict[str, object]) -> dict[str, object] | None:
@@ -152,34 +223,35 @@ def decide_hook_output(all_hook_fields: dict[str, object]) -> dict[str, object]
         all_hook_fields: The parsed PreToolUse payload.
 
     Returns:
-        None to let the call run, else the deny JSON output.
+        None to stay quiet, else the reminder as additionalContext output.
     """
-    if not _is_checked_spawn(all_hook_fields):
+    tool_name = all_hook_fields.get(TOOL_NAME_KEY)
+    tool_input = all_hook_fields.get(TOOL_INPUT_KEY)
+    if not isinstance(tool_name, str) or not isinstance(tool_input, dict):
+        return None
+    if all_hook_fields.get(AGENT_ID_KEY):
+        return None
+    brief = spawn_brief(tool_name, tool_input)
+    if brief is None:
         return None
-    tool_name = str(all_hook_fields[TOOL_NAME_KEY])
     raw_tool_use_id = all_hook_fields.get(TOOL_USE_ID_KEY)
     tool_use_id = raw_tool_use_id if isinstance(raw_tool_use_id, str) else None
-    all_transcript_lines = _transcript_lines(all_hook_fields.get(TRANSCRIPT_PATH_KEY))
-    if all_transcript_lines is None:
+    all_gaps = _transcript_gaps(all_hook_fields, tool_use_id)
+    if all_gaps is None:
         _log_decision(tool_name, tool_use_id, OUTCOME_TRANSCRIPT_UNREADABLE, None)
         return None
-    all_gaps = readiness_gaps(session_steps(all_transcript_lines, tool_use_id))
-    settled_line = scope_settled_line(tool_name, all_hook_fields[TOOL_INPUT_KEY])
-    if settled_line is not None and MISSING_INTERVIEW_REASON in all_gaps:
-        all_gaps.remove(MISSING_INTERVIEW_REASON)
-        _log_decision(tool_name, tool_use_id, OUTCOME_SCOPE_SETTLED, settled_line)
+    all_gaps = _gaps_after_scope_settled(all_gaps, brief, tool_name, tool_use_id)
     if not all_gaps:
         return None
-    deny_reason = REASON_SEPARATOR.join(all_gaps)
-    log_hook_block(Path(__file__).name, PRE_TOOL_USE_EVENT_NAME, deny_reason, tool_name=tool_name)
-    return _deny_output(deny_reason)
+    _log_decision(tool_name, tool_use_id, OUTCOME_REMINDED, None)
+    return _context_output(REASON_SEPARATOR.join(all_gaps))
 
 
 def main() -> int:
-    """Read the PreToolUse payload and print a deny when the spawn is not ready.
+    """Read the PreToolUse payload and print the reminder when the spawn is not ready.
 
     Returns:
-        0 in every case; a deny travels in the JSON output.
+        0 in every case; the reminder travels in the JSON output.
     """
     hook_payload = read_hook_input_dictionary_from_stdin()
     if hook_payload is None:

package/hooks/routing/test_spawn_readiness_hook.py

@@ -8,12 +8,15 @@ import pytest
 
 import spawn_readiness_hook
 from hooks_constants.spawn_readiness_hook_constants import (
+    CODEX_TRANSCRIPT_REMINDER,
     MISSING_INTERVIEW_REASON,
     MISSING_INVESTIGATION_REASON,
 )
 
 HOOK_SCRIPT = Path(__file__).resolve().parent / "spawn_readiness_hook.py"
 THREAD_SPAWN_TOOL_NAME = "mcp__hearthbot__start_thread_session"
+CODEX_SPAWN_TOOL_NAME = "multi_agent_v1__spawn_agent"
+DISPATCH_TOOL_NAME = "mcp__github__actions_run_trigger"
 SETTLED_LINE = "Scope settled: the request names the file, the fix, and the test."
 
 
@@ -63,6 +66,12 @@ INTERVIEWED_TRANSCRIPT = [_user("Build the hook."), READ_STEP, QUESTION_STEP, RE
 def _spawn_input(tool_name: str, brief: str = "Do the task.") -> dict[str, object]:
     if tool_name == THREAD_SPAWN_TOOL_NAME:
         return {"title": "Task", "instructions": brief}
+    if tool_name == CODEX_SPAWN_TOOL_NAME:
+        return {"message": brief}
+    if tool_name == "Workflow":
+        return {"script": brief}
+    if tool_name == DISPATCH_TOOL_NAME:
+        return {"method": "run_workflow", "workflow_id": "build.yml", "inputs": {"prompt": brief}}
     return {"description": "Task", "prompt": brief}
 
 
@@ -104,11 +113,11 @@ def _spawn(
     )
 
 
-def _deny_reason(stdout: str) -> str:
+def _reminder(stdout: str) -> str:
     decision = json.loads(stdout)["hookSpecificOutput"]
+    assert set(decision) == {"hookEventName", "additionalContext"}
     assert decision["hookEventName"] == "PreToolUse"
-    assert decision["permissionDecision"] == "deny"
-    return decision["permissionDecisionReason"]
+    return decision["additionalContext"]
 
 
 def _decision_log(tmp_path: Path) -> list[dict[str, object]]:
@@ -118,30 +127,33 @@ def _decision_log(tmp_path: Path) -> list[dict[str, object]]:
     ]
 
 
-@pytest.mark.parametrize("tool_name", ["Agent", "Task", THREAD_SPAWN_TOOL_NAME])
-def test_should_let_the_spawn_run_after_a_read_a_question_and_a_reply(
+ALL_TRANSCRIPT_SPAWN_TOOL_NAMES = ["Agent", "Task", THREAD_SPAWN_TOOL_NAME, "Workflow", DISPATCH_TOOL_NAME]
+
+
+@pytest.mark.parametrize("tool_name", ALL_TRANSCRIPT_SPAWN_TOOL_NAMES)
+def test_should_stay_quiet_after_a_read_a_question_and_a_reply(
     tmp_path: Path, tool_name: str
 ) -> None:
     assert _spawn(tmp_path, INTERVIEWED_TRANSCRIPT, tool_name) == ""
 
 
-def test_should_deny_a_spawn_with_no_read_since_the_request(tmp_path: Path) -> None:
+def test_should_remind_a_spawn_with_no_read_since_the_request(tmp_path: Path) -> None:
     transcript = [_user("Build the hook."), QUESTION_STEP, REPLY_STEP]
-    assert _deny_reason(_spawn(tmp_path, transcript)) == MISSING_INVESTIGATION_REASON
+    assert _reminder(_spawn(tmp_path, transcript)) == MISSING_INVESTIGATION_REASON
 
 
-def test_should_deny_a_spawn_with_no_question_to_the_user(tmp_path: Path) -> None:
+def test_should_remind_a_spawn_with_no_question_to_the_user(tmp_path: Path) -> None:
     transcript = [_user("Build the hook."), READ_STEP]
-    assert _deny_reason(_spawn(tmp_path, transcript)) == MISSING_INTERVIEW_REASON
+    assert _reminder(_spawn(tmp_path, transcript)) == MISSING_INTERVIEW_REASON
 
 
-def test_should_deny_a_spawn_whose_question_has_no_reply_yet(tmp_path: Path) -> None:
+def test_should_remind_a_spawn_whose_question_has_no_reply_yet(tmp_path: Path) -> None:
     transcript = [_user("Build the hook."), READ_STEP, QUESTION_STEP]
-    assert _deny_reason(_spawn(tmp_path, transcript)) == MISSING_INTERVIEW_REASON
+    assert _reminder(_spawn(tmp_path, transcript)) == MISSING_INTERVIEW_REASON
 
 
 def test_should_name_both_gaps_when_the_session_did_neither(tmp_path: Path) -> None:
-    reason = _deny_reason(_spawn(tmp_path, [_user("Build the hook.")]))
+    reason = _reminder(_spawn(tmp_path, [_user("Build the hook.")]))
     assert reason == f"{MISSING_INVESTIGATION_REASON} {MISSING_INTERVIEW_REASON}"
 
 
@@ -150,7 +162,7 @@ def test_should_count_a_plain_chat_question_as_no_interview(
 ) -> None:
     statement = _tool_use("mcp__hearthbot__post_message", {"text": "Which repo should this land in?"})
     transcript = [_user("Build the hook."), READ_STEP, statement, REPLY_STEP, READ_STEP]
-    assert _deny_reason(_spawn(tmp_path, transcript)) == MISSING_INTERVIEW_REASON
+    assert _reminder(_spawn(tmp_path, transcript)) == MISSING_INTERVIEW_REASON
 
 
 def test_should_count_an_answered_ask_user_question_as_the_interview(tmp_path: Path) -> None:
@@ -182,13 +194,13 @@ def test_should_count_an_answered_decision_card_as_the_interview(tmp_path: Path)
 def test_should_skip_an_agent_relay_as_the_reply(tmp_path: Path) -> None:
     relay = _queued('<relay from="coordinator"><note>Keep going.</note></relay>')
     transcript = [_user("Build the hook."), READ_STEP, QUESTION_STEP, relay]
-    assert _deny_reason(_spawn(tmp_path, transcript)) == MISSING_INTERVIEW_REASON
+    assert _reminder(_spawn(tmp_path, transcript)) == MISSING_INTERVIEW_REASON
 
 
 def test_should_require_a_new_interview_for_a_follow_up_request(tmp_path: Path) -> None:
     earlier_spawn = _tool_use("Agent", {"prompt": "Build the hook."})
     transcript = [*INTERVIEWED_TRANSCRIPT, earlier_spawn, _user("Now add a second hook."), READ_STEP]
-    assert _deny_reason(_spawn(tmp_path, transcript)) == MISSING_INTERVIEW_REASON
+    assert _reminder(_spawn(tmp_path, transcript)) == MISSING_INTERVIEW_REASON
 
 
 def test_should_treat_two_messages_in_a_row_after_a_question_as_one_reply(
@@ -210,13 +222,13 @@ def test_should_pass_the_interview_on_a_scope_settled_line_and_log_it(tmp_path:
 
 def test_should_still_require_the_read_with_a_scope_settled_line(tmp_path: Path) -> None:
     brief = f"Fix the typo.\n{SETTLED_LINE}"
-    reason = _deny_reason(_spawn(tmp_path, [_user("Fix the typo.")], brief=brief))
+    reason = _reminder(_spawn(tmp_path, [_user("Fix the typo.")], brief=brief))
     assert reason == MISSING_INVESTIGATION_REASON
 
 
-def test_should_deny_a_scope_settled_line_with_no_reason(tmp_path: Path) -> None:
+def test_should_remind_on_a_scope_settled_line_with_no_reason(tmp_path: Path) -> None:
     transcript = [_user("Fix the typo."), READ_STEP]
-    reason = _deny_reason(_spawn(tmp_path, transcript, brief="Fix it.\nScope settled:"))
+    reason = _reminder(_spawn(tmp_path, transcript, brief="Fix it.\nScope settled:"))
     assert reason == MISSING_INTERVIEW_REASON
 
 
@@ -268,11 +280,91 @@ def test_should_let_the_spawn_run_and_log_when_the_transcript_is_unreadable(
 
 
 def test_should_return_the_scope_settled_line_from_the_brief() -> None:
-    tool_input = {"instructions": f"Do X.\n  {SETTLED_LINE}"}
-    assert (
-        spawn_readiness_hook.scope_settled_line(THREAD_SPAWN_TOOL_NAME, tool_input) == SETTLED_LINE
+    brief = spawn_readiness_hook.spawn_brief(
+        THREAD_SPAWN_TOOL_NAME, {"instructions": f"Do X.\n  {SETTLED_LINE}"}
     )
+    assert brief is not None
+    assert spawn_readiness_hook.scope_settled_line(brief) == SETTLED_LINE
 
 
 def test_should_ignore_a_tool_it_does_not_check() -> None:
     assert spawn_readiness_hook.decide_hook_output({"tool_name": "Read", "tool_input": {}}) is None
+
+
+@pytest.mark.parametrize("tool_name", ALL_TRANSCRIPT_SPAWN_TOOL_NAMES)
+def test_should_remind_every_spawn_surface_that_skipped_both_steps(
+    tmp_path: Path, tool_name: str
+) -> None:
+    reminder = _reminder(_spawn(tmp_path, [_user("Build the hook.")], tool_name))
+    assert reminder == f"{MISSING_INVESTIGATION_REASON} {MISSING_INTERVIEW_REASON}"
+    [log_record] = _decision_log(tmp_path)
+    assert log_record["outcome"] == "reminded"
+
+
+def test_should_read_a_workflow_script_from_its_path(tmp_path: Path) -> None:
+    script_path = tmp_path / "fan_out.js"
+    script_path.write_text(f"const brief = `Fix it.\n{SETTLED_LINE}`\n", encoding="utf-8")
+    stdout = _run_hook(
+        tmp_path,
+        {
+            "tool_name": "Workflow",
+            "tool_input": {"scriptPath": str(script_path)},
+            "transcript_path": str(_write_transcript(tmp_path, [_user("Fix it."), READ_STEP])),
+        },
+    )
+    assert stdout == ""
+    [log_record] = _decision_log(tmp_path)
+    assert log_record["outcome"] == "scope_settled"
+
+
+@pytest.mark.parametrize(
+    "tool_input",
+    [
+        {"method": "cancel_workflow_run", "run_id": 7},
+        {"method": "run_workflow", "workflow_id": "lint.yml", "inputs": {"ref": "main"}},
+        {"method": "run_workflow", "workflow_id": "lint.yml"},
+    ],
+)
+def test_should_ignore_a_workflow_call_that_starts_no_agent(
+    tmp_path: Path, tool_input: dict[str, object]
+) -> None:
+    stdout = _run_hook(
+        tmp_path,
+        {
+            "tool_name": DISPATCH_TOOL_NAME,
+            "tool_input": tool_input,
+            "transcript_path": str(_write_transcript(tmp_path, [_user("Build the hook.")])),
+        },
+    )
+    assert stdout == ""
+
+
+@pytest.mark.parametrize("tool_name", [CODEX_SPAWN_TOOL_NAME, "Agent"])
+def test_should_give_a_codex_spawn_the_codex_reminder_without_reading_the_transcript(
+    tmp_path: Path, tool_name: str
+) -> None:
+    stdout = _run_hook(
+        tmp_path,
+        {
+            "tool_name": tool_name,
+            "turn_id": "turn_1",
+            "tool_input": _spawn_input(tool_name),
+            "transcript_path": str(_write_transcript(tmp_path, INTERVIEWED_TRANSCRIPT)),
+        },
+    )
+    assert _reminder(stdout) == CODEX_TRANSCRIPT_REMINDER
+
+
+def test_should_quiet_a_codex_spawn_whose_brief_settles_scope(tmp_path: Path) -> None:
+    stdout = _run_hook(
+        tmp_path,
+        {
+            "tool_name": CODEX_SPAWN_TOOL_NAME,
+            "turn_id": "turn_1",
+            "tool_input": _spawn_input(CODEX_SPAWN_TOOL_NAME, f"Fix it.\n{SETTLED_LINE}"),
+            "transcript_path": None,
+        },
+    )
+    assert stdout == ""
+    [log_record] = _decision_log(tmp_path)
+    assert log_record["outcome"] == "scope_settled"

package/hooks/routing/test_spawn_readiness_steps.py

@@ -1,5 +1,6 @@
 import json
 
+from hooks_constants.spawn_readiness_hook_constants import MISSING_INVESTIGATION_REASON
 from spawn_readiness_steps import SessionStep, readiness_gaps, session_steps
 
 
@@ -81,7 +82,4 @@ def test_should_start_the_span_at_the_request_before_an_answered_question() -> N
         SessionStep.QUESTION,
         SessionStep.USER_MESSAGE,
     ]
-    assert readiness_gaps(all_steps) == [
-        "Investigate the request before this spawn. Read the files, threads, or sources it names, "
-        "so the brief and the agent count fit the task. Run the reads in a message before the spawn."
-    ]
+    assert readiness_gaps(all_steps) == [MISSING_INVESTIGATION_REASON]

package/hooks/session/skill_loaded_reminder.py

@@ -29,8 +29,6 @@ if _hooks_dir not in sys.path:
 
 from hooks_constants.skill_loaded_reminder_constants import (
     ALL_SELF_LOADING_SUBAGENT_TYPES,
-    ASSISTANT_ENTRY_TYPE,
-    COMPACT_BOUNDARY_SUBTYPE,
     COMPACTION_REMINDER,
     COMPACTION_SOURCE,
     NOT_LOADED_REMINDER,
@@ -38,18 +36,16 @@ from hooks_constants.skill_loaded_reminder_constants import (
     PRE_TOOL_USE_EVENT_NAME,
     PROMPT_SEPARATOR,
     SESSION_START_EVENT_NAME,
-    SKILL_TOOL_NAME,
     ALL_SLASH_COMMAND_MARKERS,
     SUBAGENT_START_EVENT_NAME,
     ALL_SPAWN_PROMPT_FIELDS_AND_PREFIXES_BY_TOOL_NAME,
-    TOOL_USE_BLOCK_TYPE,
-    USER_ENTRY_TYPE,
     USER_PROMPT_SUBMIT_EVENT_NAME,
     WORKFLOW_SUBAGENT_TYPE,
 )
 from hooks_constants.pre_tool_use_allow_output import write_pre_tool_use_allow_to_stdout
 from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
 from hooks_constants.setup_project_paths_constants import DECODE_ERRORS_POLICY, UTF8_ENCODING
+from transcript_skill_scan import skill_invocation_status
 
 
 def subagent_input_with_poteto_mode(
@@ -81,44 +77,6 @@ def subagent_input_with_poteto_mode(
     return {**all_tool_input_fields, field_name: invocation_prefix + PROMPT_SEPARATOR + prompt}
 
 
-def _invokes_poteto_mode(all_entry_fields: dict[str, object]) -> bool:
-    message = all_entry_fields.get("message")
-    if not isinstance(message, dict):
-        return False
-    content_blocks = message.get("content")
-    if all_entry_fields.get("type") == USER_ENTRY_TYPE and isinstance(content_blocks, str):
-        return any(each_marker in content_blocks for each_marker in ALL_SLASH_COMMAND_MARKERS)
-    if all_entry_fields.get("type") != ASSISTANT_ENTRY_TYPE or not isinstance(content_blocks, list):
-        return False
-    return any(
-        isinstance(each_block, dict)
-        and each_block.get("type") == TOOL_USE_BLOCK_TYPE
-        and each_block.get("name") == SKILL_TOOL_NAME
-        and isinstance(each_block.get("input"), dict)
-        and each_block["input"].get("skill") in ALL_POTETO_MODE_SKILL_NAMES
-        for each_block in content_blocks
-    )
-
-
-def _marker_entry(transcript_line: str) -> dict[str, object] | None:
-    if (
-        COMPACT_BOUNDARY_SUBTYPE not in transcript_line
-        and ALL_POTETO_MODE_SKILL_NAMES[0] not in transcript_line
-    ):
-        return None
-    try:
-        parsed_entry = json.loads(transcript_line)
-    except json.JSONDecodeError:
-        return None
-    return parsed_entry if isinstance(parsed_entry, dict) else None
-
-
-def _is_loaded_after(all_entry_fields: dict[str, object], was_loaded: bool) -> bool:
-    if all_entry_fields.get("subtype") == COMPACT_BOUNDARY_SUBTYPE:
-        return False
-    return was_loaded or _invokes_poteto_mode(all_entry_fields)
-
-
 def poteto_mode_status(all_transcript_lines: Iterable[str]) -> tuple[bool, bool]:
     """Report whether the skill was invoked and whether it remains loaded.
 
@@ -139,14 +97,9 @@ def poteto_mode_status(all_transcript_lines: Iterable[str]) -> tuple[bool, bool]
     Returns:
         Whether the skill was invoked at any point and whether it is loaded now.
     """
-    was_invoked = False
-    is_loaded = False
-    for each_line in all_transcript_lines:
-        all_entry_fields = _marker_entry(each_line)
-        if all_entry_fields is not None:
-            is_loaded = _is_loaded_after(all_entry_fields, is_loaded)
-            was_invoked = was_invoked or is_loaded
-    return was_invoked, is_loaded
+    return skill_invocation_status(
+        all_transcript_lines, ALL_POTETO_MODE_SKILL_NAMES, ALL_SLASH_COMMAND_MARKERS
+    )
 
 
 def is_poteto_mode_loaded(all_transcript_lines: Iterable[str]) -> bool:

package/hooks/session/test_skill_loaded_reminder.py

@@ -200,6 +200,10 @@ class TestIsPotetoModeLoaded:
         prefixed_command_line = TYPED_COMMAND_LINE.replace("/poteto-mode", "/pstack:poteto-mode")
         assert reminder.is_poteto_mode_loaded([prefixed_command_line])
 
+    def test_a_different_skill_call_does_not_load_it(self) -> None:
+        other_skill_call_line = SKILL_CALL_LINE.replace("poteto-mode", "pr-lifecycle")
+        assert not reminder.is_poteto_mode_loaded([other_skill_call_line])
+
     def test_a_compaction_after_the_skill_call_drops_it(self) -> None:
         assert not reminder.is_poteto_mode_loaded(
             [SKILL_CALL_LINE, COMPACT_BOUNDARY_LINE, READ_CALL_LINE]

package/hooks/test_transcript_skill_scan.py

@@ -0,0 +1,58 @@
+"""Tests for skill invocation state across transcript compactions."""
+
+import json
+import sys
+from pathlib import Path
+
+HOOKS_DIRECTORY = Path(__file__).resolve().parent
+if str(HOOKS_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(HOOKS_DIRECTORY))
+
+from transcript_skill_scan import is_skill_loaded_after_last_compaction, skill_invocation_status
+
+
+def _skill_entry(name: str) -> str:
+    return json.dumps(
+        {"type": "assistant", "message": {"content": [{"type": "tool_use", "name": "Skill", "input": {"skill": name}}]}}
+    )
+
+
+def test_matching_skill_after_compaction_loads() -> None:
+    lines = [
+        _skill_entry("pr-lifecycle"),
+        json.dumps({"type": "system", "subtype": "compact_boundary"}),
+        _skill_entry("plugin:pr-lifecycle"),
+    ]
+    assert is_skill_loaded_after_last_compaction(
+        lines, ("pr-lifecycle",), ("<command-name>/pr-lifecycle</command-name>",)
+    )
+
+
+def test_compaction_drops_a_loaded_skill() -> None:
+    lines = [_skill_entry("pr-lifecycle"), json.dumps({"subtype": "compact_boundary"})]
+    assert not is_skill_loaded_after_last_compaction(lines, ("pr-lifecycle",), ())
+
+
+def test_user_command_loads_and_quoted_tool_result_does_not() -> None:
+    marker = "<command-name>/pr-lifecycle</command-name>"
+    user_entry = json.dumps({"type": "user", "message": {"content": marker}})
+    quoted_result = json.dumps(
+        {"type": "user", "message": {"content": [{"type": "tool_result", "content": marker}]}}
+    )
+    assert is_skill_loaded_after_last_compaction([user_entry], ("pr-lifecycle",), (marker,))
+    assert not is_skill_loaded_after_last_compaction([quoted_result], ("pr-lifecycle",), (marker,))
+
+
+def test_malformed_entries_do_not_load() -> None:
+    assert not is_skill_loaded_after_last_compaction(
+        ["pr-lifecycle {", json.dumps({"type": "assistant", "message": {"content": "pr-lifecycle"}})],
+        ("pr-lifecycle",),
+        (),
+    )
+
+
+def test_invocation_status_separates_ever_invoked_from_loaded_now() -> None:
+    compaction = json.dumps({"subtype": "compact_boundary"})
+    assert skill_invocation_status([_skill_entry("pr-lifecycle")], ("pr-lifecycle",), ()) == (True, True)
+    assert skill_invocation_status([_skill_entry("pr-lifecycle"), compaction], ("pr-lifecycle",), ()) == (True, False)
+    assert skill_invocation_status([compaction, _skill_entry("other")], ("pr-lifecycle",), ()) == (False, False)