claude-dev-env 8.36.4 → 8.37.1

package/hooks/hooks_constants/spawn_readiness_hook_constants.py

@@ -0,0 +1,111 @@
+"""Constants for the spawn readiness PreToolUse hook.
+
+Groups: the spawn tools it checks and their brief fields, the transcript entry
+shapes it reads, the tool names that count as a read or a question, the
+scope-settled line, and the deny messages and log fields.
+"""
+
+from __future__ import annotations
+
+TOOL_NAME_KEY = "tool_name"
+TOOL_INPUT_KEY = "tool_input"
+TOOL_USE_ID_KEY = "tool_use_id"
+TRANSCRIPT_PATH_KEY = "transcript_path"
+AGENT_ID_KEY = "agent_id"
+SUBAGENT_TYPE_INPUT_KEY = "subagent_type"
+
+THREAD_SPAWN_TOOL_NAME = "mcp__hearthbot__start_thread_session"
+ALL_BRIEF_FIELDS_BY_SPAWN_TOOL_NAME = {
+    "Agent": "prompt",
+    "Task": "prompt",
+    THREAD_SPAWN_TOOL_NAME: "instructions",
+}
+ALL_READ_ONLY_SUBAGENT_TYPES = frozenset({"Explore", "Plan", "claude-code-guide"})
+
+ENTRY_TYPE_KEY = "type"
+USER_ENTRY_TYPE = "user"
+ASSISTANT_ENTRY_TYPE = "assistant"
+ATTACHMENT_ENTRY_TYPE = "attachment"
+QUEUED_COMMAND_ATTACHMENT_TYPE = "queued_command"
+ATTACHMENT_KEY = "attachment"
+QUEUED_PROMPT_KEY = "prompt"
+MESSAGE_KEY = "message"
+CONTENT_KEY = "content"
+IS_META_KEY = "isMeta"
+IS_COMPACT_SUMMARY_KEY = "isCompactSummary"
+BLOCK_TYPE_KEY = "type"
+TEXT_BLOCK_TYPE = "text"
+TEXT_KEY = "text"
+TOOL_USE_BLOCK_TYPE = "tool_use"
+TOOL_RESULT_BLOCK_TYPE = "tool_result"
+BLOCK_ID_KEY = "id"
+BLOCK_NAME_KEY = "name"
+BLOCK_INPUT_KEY = "input"
+RESULT_TOOL_USE_ID_KEY = "tool_use_id"
+RESULT_IS_ERROR_KEY = "is_error"
+
+ALL_HARNESS_ENVELOPE_MARKERS = (
+    "<wake",
+    "<relay",
+    "<task-notification",
+    "<cross-session-message",
+    "<system-note",
+    "<local-command",
+)
+HUMAN_SENDER_MARKER = 'from="human"'
+
+ALL_READ_TOOL_NAMES = frozenset(
+    {
+        "Read",
+        "Grep",
+        "Glob",
+        "Bash",
+        "PowerShell",
+        "LS",
+        "NotebookRead",
+        "WebFetch",
+        "WebSearch",
+    }
+)
+MCP_TOOL_NAME_PREFIX = "mcp__"
+MCP_TOOL_NAME_SEPARATOR = "__"
+ALL_MCP_READ_VERB_PREFIXES = ("fetch", "read", "get", "list", "search", "query")
+ALL_INTERACTIVE_QUESTION_TOOL_NAMES = frozenset(
+    {"AskUserQuestion", "request_user_input", "request_user_input_async"}
+)
+ALL_INTERACTIVE_MCP_ACTIONS = frozenset({"ask_decision", "post_widget"})
+
+SCOPE_SETTLED_PREFIX = "Scope settled:"
+
+PRE_TOOL_USE_EVENT_NAME = "PreToolUse"
+HOOK_SPECIFIC_OUTPUT_KEY = "hookSpecificOutput"
+HOOK_EVENT_NAME_KEY = "hookEventName"
+PERMISSION_DECISION_KEY = "permissionDecision"
+PERMISSION_DECISION_REASON_KEY = "permissionDecisionReason"
+PERMISSION_DENY = "deny"
+MISSING_INVESTIGATION_REASON = (
+    "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."
+)
+MISSING_INTERVIEW_REASON = (
+    "Interview the user before this spawn. Ask your scope, requirements, and "
+    "goals questions through AskUserQuestion, a decision card, or an "
+    "interactive widget, and spawn after the answer. When the request "
+    "already settles scope, add a brief line that starts with "
+    f'"{SCOPE_SETTLED_PREFIX}" and names the reason.'
+)
+REASON_SEPARATOR = " "
+
+TRANSCRIPT_ENCODING = "utf-8"
+TRANSCRIPT_DECODE_ERRORS = "replace"
+DECISION_LOG_RELATIVE_PATH = ".claude/logs/spawn-readiness.jsonl"
+LOG_APPEND_MODE = "a"
+LOG_LINE_END = "\n"
+LOG_TIMESTAMP_KEY = "timestamp"
+LOG_TOOL_NAME_KEY = "tool_name"
+LOG_TOOL_USE_ID_KEY = "tool_use_id"
+LOG_OUTCOME_KEY = "outcome"
+LOG_SCOPE_SETTLED_LINE_KEY = "scope_settled_line"
+OUTCOME_SCOPE_SETTLED = "scope_settled"
+OUTCOME_TRANSCRIPT_UNREADABLE = "transcript_unreadable"

package/hooks/routing/spawn_readiness_hook.py

@@ -0,0 +1,195 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: hold an agent spawn until the session has read and asked.
+
+Registered on ``Agent``, ``Task``, and ``mcp__hearthbot__start_thread_session``.
+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
+    brief line "Scope settled: <reason>"        -> interview check passes, logged
+    both found                                  -> no output; the call runs
+
+``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
+
+import datetime
+import json
+import sys
+from pathlib import Path
+
+hooks_root_directory = str(Path(__file__).resolve().parent.parent)
+if hooks_root_directory not in sys.path:
+    sys.path.insert(0, hooks_root_directory)
+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 (
+    AGENT_ID_KEY,
+    ALL_BRIEF_FIELDS_BY_SPAWN_TOOL_NAME,
+    ALL_READ_ONLY_SUBAGENT_TYPES,
+    DECISION_LOG_RELATIVE_PATH,
+    HOOK_EVENT_NAME_KEY,
+    HOOK_SPECIFIC_OUTPUT_KEY,
+    LOG_APPEND_MODE,
+    LOG_LINE_END,
+    LOG_OUTCOME_KEY,
+    LOG_SCOPE_SETTLED_LINE_KEY,
+    LOG_TIMESTAMP_KEY,
+    LOG_TOOL_NAME_KEY,
+    LOG_TOOL_USE_ID_KEY,
+    MISSING_INTERVIEW_REASON,
+    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,
+    SUBAGENT_TYPE_INPUT_KEY,
+    TOOL_INPUT_KEY,
+    TOOL_NAME_KEY,
+    TOOL_USE_ID_KEY,
+    TRANSCRIPT_DECODE_ERRORS,
+    TRANSCRIPT_ENCODING,
+    TRANSCRIPT_PATH_KEY,
+)
+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:
+    """Return the brief's "Scope settled:" line when it names a reason, else None.
+
+    ::
+
+        "Do X.\\nScope settled: the request names the file and the fix."
+        -> "Scope settled: the request names the file and the fix."
+        "Do X.\\nScope settled:"  -> None
+
+    Args:
+        tool_name: The spawn tool, which decides the brief field.
+        all_tool_input_fields: The spawn input.
+    """
+    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()
+        if stripped_line.startswith(SCOPE_SETTLED_PREFIX) and stated_reason:
+            return stripped_line
+    return None
+
+
+def _log_decision(
+    tool_name: str, tool_use_id: str | None, outcome: str, settled_line: str | None
+) -> None:
+    try:
+        log_path = Path.home() / DECISION_LOG_RELATIVE_PATH
+    except RuntimeError:
+        return
+    log_record: dict[str, object] = {
+        LOG_TIMESTAMP_KEY: datetime.datetime.now().isoformat(),
+        LOG_TOOL_NAME_KEY: tool_name,
+        LOG_TOOL_USE_ID_KEY: tool_use_id,
+        LOG_OUTCOME_KEY: outcome,
+    }
+    if settled_line is not None:
+        log_record[LOG_SCOPE_SETTLED_LINE_KEY] = settled_line
+    try:
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+        with log_path.open(LOG_APPEND_MODE, encoding=TRANSCRIPT_ENCODING) as log_file:
+            log_file.write(json.dumps(log_record) + LOG_LINE_END)
+    except OSError:
+        pass
+
+
+def _transcript_lines(transcript_path: object) -> list[str] | None:
+    if not isinstance(transcript_path, str) or not transcript_path:
+        return None
+    try:
+        return Path(transcript_path).read_text(
+            encoding=TRANSCRIPT_ENCODING, errors=TRANSCRIPT_DECODE_ERRORS
+        ).splitlines()
+    except OSError:
+        return None
+
+
+def _deny_output(reason: 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,
+        }
+    }
+
+
+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 decide_hook_output(all_hook_fields: dict[str, object]) -> dict[str, object] | None:
+    """Choose the hook's output for one spawn call.
+
+    Args:
+        all_hook_fields: The parsed PreToolUse payload.
+
+    Returns:
+        None to let the call run, else the deny JSON output.
+    """
+    if not _is_checked_spawn(all_hook_fields):
+        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:
+        _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)
+    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)
+
+
+def main() -> int:
+    """Read the PreToolUse payload and print a deny when the spawn is not ready.
+
+    Returns:
+        0 in every case; a deny travels in the JSON output.
+    """
+    hook_payload = read_hook_input_dictionary_from_stdin()
+    if hook_payload is None:
+        return 0
+    hook_output = decide_hook_output(hook_payload)
+    if hook_output is not None:
+        sys.stdout.write(json.dumps(hook_output))
+        sys.stdout.flush()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/hooks/routing/spawn_readiness_steps.py

@@ -0,0 +1,266 @@
+"""Read a session transcript into the steps the spawn readiness hook checks.
+
+::
+
+    user "build X" ... Bash ... AskUserQuestion "Which layout?" ... answer "grid"
+    -> [USER_MESSAGE, READ, QUESTION, USER_MESSAGE]
+    -> readiness_gaps(...) == []
+
+A read is a file read, a search, a shell command, a fetch, an MCP read, or a
+read-only subagent. A question is an interactive prompt: an
+``AskUserQuestion`` or ``request_user_input`` call, whose answer is the
+reply, or an ``ask_decision`` card or ``post_widget`` widget, answered by
+the next user message. A plain chat message is no question. A user message is typed text or a human wake; a harness
+envelope with no human sender, such as an agent relay or a task notice, is
+left out.
+"""
+
+from __future__ import annotations
+
+import enum
+import json
+import sys
+from collections.abc import Iterable, Iterator
+from pathlib import Path
+
+hooks_root_directory = str(Path(__file__).resolve().parent.parent)
+if hooks_root_directory not in sys.path:
+    sys.path.insert(0, hooks_root_directory)
+
+from hooks_constants.spawn_readiness_hook_constants import (
+    ALL_BRIEF_FIELDS_BY_SPAWN_TOOL_NAME,
+    ALL_HARNESS_ENVELOPE_MARKERS,
+    ALL_MCP_READ_VERB_PREFIXES,
+    ALL_READ_ONLY_SUBAGENT_TYPES,
+    ALL_READ_TOOL_NAMES,
+    ALL_INTERACTIVE_MCP_ACTIONS,
+    ALL_INTERACTIVE_QUESTION_TOOL_NAMES,
+    ASSISTANT_ENTRY_TYPE,
+    ATTACHMENT_ENTRY_TYPE,
+    ATTACHMENT_KEY,
+    BLOCK_ID_KEY,
+    BLOCK_INPUT_KEY,
+    BLOCK_NAME_KEY,
+    BLOCK_TYPE_KEY,
+    CONTENT_KEY,
+    ENTRY_TYPE_KEY,
+    HUMAN_SENDER_MARKER,
+    IS_COMPACT_SUMMARY_KEY,
+    IS_META_KEY,
+    MCP_TOOL_NAME_PREFIX,
+    MCP_TOOL_NAME_SEPARATOR,
+    MESSAGE_KEY,
+    MISSING_INTERVIEW_REASON,
+    MISSING_INVESTIGATION_REASON,
+    QUEUED_COMMAND_ATTACHMENT_TYPE,
+    QUEUED_PROMPT_KEY,
+    RESULT_IS_ERROR_KEY,
+    RESULT_TOOL_USE_ID_KEY,
+    SUBAGENT_TYPE_INPUT_KEY,
+    TEXT_BLOCK_TYPE,
+    TEXT_KEY,
+    TOOL_RESULT_BLOCK_TYPE,
+    TOOL_USE_BLOCK_TYPE,
+    USER_ENTRY_TYPE,
+)
+
+
+class SessionStep(enum.Enum):
+    """One transcript step the readiness checks count."""
+
+    USER_MESSAGE = "user_message"
+    READ = "read"
+    QUESTION = "question"
+    OTHER_TOOL_CALL = "other_tool_call"
+
+
+def _is_user_text(text: str) -> bool:
+    if not text.strip():
+        return False
+    if any(each_marker in text for each_marker in ALL_HARNESS_ENVELOPE_MARKERS):
+        return HUMAN_SENDER_MARKER in text
+    return True
+
+
+def _mcp_step(action_name: str) -> SessionStep:
+    if action_name in ALL_INTERACTIVE_MCP_ACTIONS:
+        return SessionStep.QUESTION
+    if action_name.startswith(ALL_MCP_READ_VERB_PREFIXES):
+        return SessionStep.READ
+    return SessionStep.OTHER_TOOL_CALL
+
+
+def _tool_use_step(tool_name: str, tool_input: object) -> SessionStep:
+    all_input_fields = tool_input if isinstance(tool_input, dict) else {}
+    if tool_name in ALL_INTERACTIVE_QUESTION_TOOL_NAMES:
+        return SessionStep.QUESTION
+    if tool_name in ALL_READ_TOOL_NAMES:
+        return SessionStep.READ
+    if (
+        tool_name in ALL_BRIEF_FIELDS_BY_SPAWN_TOOL_NAME
+        and all_input_fields.get(SUBAGENT_TYPE_INPUT_KEY) in ALL_READ_ONLY_SUBAGENT_TYPES
+    ):
+        return SessionStep.READ
+    if tool_name.startswith(MCP_TOOL_NAME_PREFIX):
+        return _mcp_step(tool_name.rsplit(MCP_TOOL_NAME_SEPARATOR, 1)[-1])
+    return SessionStep.OTHER_TOOL_CALL
+
+
+def _content_of(all_entry_fields: dict[object, object]) -> object:
+    message = all_entry_fields.get(MESSAGE_KEY)
+    return message.get(CONTENT_KEY) if isinstance(message, dict) else None
+
+
+def _assistant_steps(
+    all_entry_fields: dict[object, object],
+    all_question_tool_use_ids: set[str],
+    spawn_tool_use_id: str | None,
+) -> Iterator[SessionStep]:
+    content = _content_of(all_entry_fields)
+    all_blocks = content if isinstance(content, list) else []
+    for each_block in all_blocks:
+        if (
+            not isinstance(each_block, dict)
+            or each_block.get(BLOCK_TYPE_KEY) != TOOL_USE_BLOCK_TYPE
+        ):
+            continue
+        block_id = each_block.get(BLOCK_ID_KEY)
+        tool_name = each_block.get(BLOCK_NAME_KEY)
+        if block_id == spawn_tool_use_id or not isinstance(tool_name, str):
+            continue
+        if tool_name in ALL_INTERACTIVE_QUESTION_TOOL_NAMES and isinstance(block_id, str):
+            all_question_tool_use_ids.add(block_id)
+        yield _tool_use_step(tool_name, each_block.get(BLOCK_INPUT_KEY))
+
+
+def _is_user_block(
+    all_block_fields: dict[object, object], all_question_tool_use_ids: set[str]
+) -> bool:
+    block_type = all_block_fields.get(BLOCK_TYPE_KEY)
+    if block_type == TEXT_BLOCK_TYPE:
+        return _is_user_text(str(all_block_fields.get(TEXT_KEY, "")))
+    return (
+        block_type == TOOL_RESULT_BLOCK_TYPE
+        and all_block_fields.get(RESULT_TOOL_USE_ID_KEY) in all_question_tool_use_ids
+        and not all_block_fields.get(RESULT_IS_ERROR_KEY)
+    )
+
+
+def _user_steps(
+    all_entry_fields: dict[object, object], all_question_tool_use_ids: set[str]
+) -> Iterator[SessionStep]:
+    if all_entry_fields.get(IS_META_KEY) or all_entry_fields.get(IS_COMPACT_SUMMARY_KEY):
+        return
+    content = _content_of(all_entry_fields)
+    if isinstance(content, str):
+        is_user_message = _is_user_text(content)
+    else:
+        all_blocks = content if isinstance(content, list) else []
+        is_user_message = any(
+            isinstance(each_block, dict) and _is_user_block(each_block, all_question_tool_use_ids)
+            for each_block in all_blocks
+        )
+    if is_user_message:
+        yield SessionStep.USER_MESSAGE
+
+
+def _queued_steps(all_entry_fields: dict[object, object]) -> Iterator[SessionStep]:
+    attachment = all_entry_fields.get(ATTACHMENT_KEY)
+    if (
+        not isinstance(attachment, dict)
+        or attachment.get(ENTRY_TYPE_KEY) != QUEUED_COMMAND_ATTACHMENT_TYPE
+    ):
+        return
+    queued_prompt = attachment.get(QUEUED_PROMPT_KEY)
+    if isinstance(queued_prompt, str) and _is_user_text(queued_prompt):
+        yield SessionStep.USER_MESSAGE
+
+
+def _parsed_entry(transcript_line: str) -> dict[object, object]:
+    try:
+        parsed_entry = json.loads(transcript_line)
+    except json.JSONDecodeError:
+        return {}
+    return parsed_entry if isinstance(parsed_entry, dict) else {}
+
+
+def _entry_steps(
+    transcript_line: str, all_question_tool_use_ids: set[str], spawn_tool_use_id: str | None
+) -> Iterator[SessionStep]:
+    parsed_entry = _parsed_entry(transcript_line)
+    entry_type = parsed_entry.get(ENTRY_TYPE_KEY)
+    if entry_type == ASSISTANT_ENTRY_TYPE:
+        return _assistant_steps(parsed_entry, all_question_tool_use_ids, spawn_tool_use_id)
+    if entry_type == USER_ENTRY_TYPE:
+        return _user_steps(parsed_entry, all_question_tool_use_ids)
+    if entry_type == ATTACHMENT_ENTRY_TYPE:
+        return _queued_steps(parsed_entry)
+    return iter(())
+
+
+def session_steps(
+    all_transcript_lines: Iterable[str], spawn_tool_use_id: str | None = None
+) -> list[SessionStep]:
+    """Read the transcript into the user messages and tool calls it holds, in order.
+
+    A tool call that is neither a read nor a question is an OTHER_TOOL_CALL,
+    so two user messages count as one only when nothing ran between them.
+
+    Args:
+        all_transcript_lines: The session transcript, one JSON entry per line.
+        spawn_tool_use_id: The id of the spawn under check, left out of the steps.
+    """
+    all_question_tool_use_ids: set[str] = set()
+    return [
+        each_step
+        for each_line in all_transcript_lines
+        for each_step in _entry_steps(each_line, all_question_tool_use_ids, spawn_tool_use_id)
+    ]
+
+
+def _request_position(all_steps: list[SessionStep]) -> int | None:
+    all_user_positions = [
+        each_position
+        for each_position, each_step in enumerate(all_steps)
+        if each_step is SessionStep.USER_MESSAGE
+        and (each_position == 0 or all_steps[each_position - 1] is not SessionStep.USER_MESSAGE)
+    ]
+    if not all_user_positions:
+        return None
+    for each_index in range(len(all_user_positions) - 1, 0, -1):
+        previous_position = all_user_positions[each_index - 1]
+        current_position = all_user_positions[each_index]
+        if SessionStep.QUESTION not in all_steps[previous_position:current_position]:
+            return current_position
+    return all_user_positions[0]
+
+
+def readiness_gaps(all_steps: list[SessionStep]) -> list[str]:
+    """Return the deny reasons the session has not yet cleared, in order.
+
+    ::
+
+        [USER_MESSAGE, READ, QUESTION, USER_MESSAGE]   -> []
+        [USER_MESSAGE, QUESTION, USER_MESSAGE]         -> [investigation reason]
+        [USER_MESSAGE, READ]                           -> [interview reason]
+        [USER_MESSAGE, READ, QUESTION]                 -> [interview reason]
+
+    The span starts at the request: the latest user message that answers no
+    question. The interview passes when a user message in that span answers
+    a question.
+
+    Args:
+        all_steps: The steps from ``session_steps``.
+    """
+    request_position = _request_position(all_steps)
+    span_steps = all_steps if request_position is None else all_steps[request_position:]
+    all_gaps: list[str] = []
+    if SessionStep.READ not in span_steps:
+        all_gaps.append(MISSING_INVESTIGATION_REASON)
+    has_reply = any(
+        each_step is SessionStep.USER_MESSAGE and SessionStep.QUESTION in span_steps[:each_position]
+        for each_position, each_step in enumerate(span_steps)
+    )
+    if not has_reply:
+        all_gaps.append(MISSING_INTERVIEW_REASON)
+    return all_gaps