claude-dev-env 8.93.2 → 8.94.0

package/.agents/skills/orchestrator/SKILL.md

@@ -97,6 +97,7 @@ Reuse a reachable worker whose context fits. Give a fresh worker the saved assig
 Register each delegated task before spawn and set one owner before the worker writes.
 Keep one writer per shared file. Isolate concurrent writers in separate worktrees or output directories.
 Pass the user's relevant words, goal ID, assignment locator, owned files, constraints, and acceptance check.
+State the user's outcome on an `Outcome:` line. Any route you name is a suggested default. Add an `On a blocker:` line: the worker tries other routes that reach the outcome and hands the user a step only when it needs their hands.
 Pass the active standing-instruction loading requirements to every descendant.
 Use [executor consult blocks](reference/executor-consult-block.md) and the [consult contract](reference/consult-the-orchestrator.md).
 Send follow-ups only through a transport authorized by the current runtime and user.

package/hooks/features/spawn-routing.md

@@ -1,11 +1,11 @@
 # Spawn routing
 
-This family reminds the agent to gather context before a spawn, tells it that it owns the spawned work, adjusts thread requests when usage exceeds pace, selects an allowed subagent model, and sends a Haiku spawn to a headless slim-profile run.
+This family reminds the agent to gather context before a spawn, refuses a brief without the user's outcome and a blocker clause, tells it that it owns the spawned work, adjusts thread requests when usage exceeds pace, selects an allowed subagent model, and sends a Haiku spawn to a headless slim-profile run.
 
 ## Checks
 
 - `routing/spawn_readiness_hook.py` adds context to a spawn that comes before a read step, or before an answered question or a settled-scope line. The spawn still runs.
-- `routing/spawn_oversight_hook.py` adds the orchestrator oversight directive to every spawn: watch the agent, check its output against the user's words and standards, and correct it before the output reaches the user. The spawn still runs.
+- `routing/spawn_oversight_hook.py` denies a spawn whose brief has no `Outcome:` line or no `On a blocker:` clause, each with text after it. A spawn that passes gets the orchestrator oversight directive: watch the agent, check its output against the user's words and standards, and correct it before the output reaches the user. `routing/spawn_brief_text.py` reads the brief from each spawn tool for this hook and the readiness hook.
 - `routing/thread_spawn_pace_hook.py` reshapes a thread request when usage is over pace or unreadable.
 - `routing/subagent_model_routing.mjs` allows a selected Luna model, remaps eligible requests, and denies unsupported model routing.
 - `blocking/haiku_spawn_slim_gate.py` denies an Agent, Task, or thread spawn whose `model` names Haiku. The deny reason gives the headless `claude -p` command that loads the slim profile through the account broker.
@@ -13,7 +13,7 @@ This family reminds the agent to gather context before a spawn, tells it that it
 ## When it fires
 
 - `routing/spawn_readiness_hook.py` runs on `PreToolUse` with matchers `Agent|Task`, `multi_agent_v1__spawn_agent`, `Workflow|mcp__github__actions_run_trigger`, and `mcp__hearthbot__start_thread_session`, each at `10` seconds in `hooks.json`. A workflow dispatch counts only when its inputs carry a `prompt`.
-- `routing/spawn_oversight_hook.py` runs on `PreToolUse` with matchers `Agent|Task`, `multi_agent_v1__spawn_agent`, `Workflow|mcp__github__actions_run_trigger`, `mcp__hearthbot__start_thread_session`, and `mcp__hearthbot__start_rc_session`, each at `10` seconds in `hooks.json`. A workflow dispatch counts only when its inputs carry a `prompt`.
+- `routing/spawn_oversight_hook.py` runs on `PreToolUse` with matchers `Agent|Task`, `multi_agent_v1__spawn_agent`, `Workflow|mcp__github__actions_run_trigger`, `mcp__hearthbot__start_thread_session`, and `mcp__hearthbot__start_rc_session|mcp__hearthbot__start_remote_control`, each at `10` seconds in `hooks.json`. A workflow dispatch counts only when its inputs carry a `prompt`.
 - `routing/thread_spawn_pace_hook.py` runs on `PreToolUse`, matcher `mcp__hearthbot__start_thread_session`, timeout `30` seconds in `hooks.json`.
 - `routing/subagent_model_routing.mjs` runs on `PreToolUse`, matcher `multi_agent_v1__spawn_agent`, timeout `10` seconds through the quoted Node command in `hooks.json`.
 - `blocking/haiku_spawn_slim_gate.py` runs on `PreToolUse` with matchers `Agent|Task` and `mcp__hearthbot__start_thread_session`, each at `10` seconds in `hooks.json`.
@@ -25,7 +25,7 @@ Preconditions:
 - Run each command from the repository root. Python and pytest cover the two Python scripts; Node covers the model router.
 
 - **Spawn readiness.** Input is a spawn after a read, a question, and its answer. Run `python -m pytest packages/claude-dev-env/hooks/routing/test_spawn_readiness_hook.py -q`. The adjacent test observes no output for a ready spawn and reminder context for each missing step.
-- **Spawn oversight.** Input is a spawn from each registered tool, a subagent's own spawn, and a non-spawn call. Run `python -m pytest packages/claude-dev-env/hooks/routing/test_spawn_oversight_hook.py -q`. The adjacent test observes the directive for every spawn and no output for the other calls.
+- **Spawn oversight.** Input is a route-only brief, a brief with both clauses, and briefs with one clause, on each registered tool, plus a non-spawn call. Run `python -m pytest packages/claude-dev-env/hooks/routing/test_spawn_oversight_hook.py packages/claude-dev-env/hooks/routing/test_spawn_brief_text.py -q`. The adjacent test observes a deny for each brief missing a clause, the directive for the passing brief, and no output for the other calls.
 - **Thread pace.** Input is a thread spawn with usage over pace. Run `python -m pytest packages/claude-dev-env/hooks/routing/test_thread_spawn_pace_hook.py -q`. The adjacent test observes updated tool input with the selected model, effort, and advisor line.
 - **Haiku slim gate.** Input is a spawn with a Haiku alias or model ID, and spawns on other models or with no model. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_haiku_spawn_slim_gate.py -q`. The adjacent test observes a deny with the headless command for each Haiku spawn and no output for the rest.
 - **Model routing.** Input is a `multi_agent_v1__spawn_agent` payload with a model choice. Run `node --test packages/claude-dev-env/hooks/routing/subagent_model_routing.test.mjs`. The adjacent test observes an allow or deny decision with the routed model.
@@ -33,7 +33,7 @@ Preconditions:
 ## Gotchas
 
 - `routing/spawn_readiness_hook.py` also runs after the pace hook on thread spawns. A reshaped request still gets the readiness check.
-- The oversight hook fires inside subagents too, so each level of the tree oversees the level below it. It emits `additionalContext` only and never blocks.
+- The oversight hook fires inside subagents and on read-only helper types too, so every brief at every level carries the outcome and the blocker clause. A `Workflow` call with no script text, such as a saved or resumed run, passes with the directive.
 - The readiness hook emits `additionalContext` only, so it never blocks. It passes subagent calls, read-only helper types, a non-object tool input, and unreadable transcripts.
 - The Haiku slim gate reads only the spawn's `model` field. A spawn that names no model passes, even when its agent definition or `CLAUDE_CODE_SUBAGENT_MODEL` resolves it to Haiku.
 - The model router allows an advisor flag to bypass the Luna restriction. Its ordinary path denies unresolved or unsupported models.

package/hooks/hooks.json

@@ -250,7 +250,7 @@
         ]
       },
       {
-        "matcher": "mcp__hearthbot__start_rc_session",
+        "matcher": "mcp__hearthbot__start_rc_session|mcp__hearthbot__start_remote_control",
         "hooks": [
           {
             "type": "command",

package/hooks/hooks_constants/pre_tool_use_context_runner.py

@@ -1,8 +1,9 @@
-"""Shared main loop for PreToolUse hooks that only add context.
+"""Shared main loop for PreToolUse hooks that print a decided JSON output.
 
 Reads the payload from stdin, asks the hook's decide function for an output,
-and writes it as JSON. Exit status is always 0, so the tool call runs; a
-decide function that raises leaves the call with no output.
+and writes it as JSON. The output may add context or deny the call. Exit
+status is always 0; a decide function that raises leaves the call with no
+output.
 """
 
 from __future__ import annotations

package/hooks/hooks_constants/spawn_oversight_hook_constants.py

@@ -1,8 +1,8 @@
 """Constants for the spawn oversight PreToolUse hook.
 
-Groups: the spawn tools it answers, the workflow dispatch that carries an
-agent prompt, the payload keys it reads, and the
-oversight directive it adds to every spawn.
+Groups: the payload keys it reads, the brief markers it requires, the
+refusal it gives a brief without them, and the oversight directive it adds to
+every spawn that passes.
 """
 
 from __future__ import annotations
@@ -11,23 +11,29 @@ TOOL_NAME_KEY = "tool_name"
 TOOL_INPUT_KEY = "tool_input"
 PRE_TOOL_USE_EVENT_NAME = "PreToolUse"
 ADDITIONAL_CONTEXT_KEY = "additionalContext"
+PERMISSION_DECISION_REASON_KEY = "permissionDecisionReason"
+DENY_DECISION = "deny"
+WORKFLOW_TOOL_NAME = "Workflow"
 
-WORKFLOW_DISPATCH_TOOL_NAME = "mcp__github__actions_run_trigger"
-DISPATCH_METHOD_INPUT_KEY = "method"
-DISPATCH_RUN_WORKFLOW_METHOD = "run_workflow"
-DISPATCH_INPUTS_KEY = "inputs"
-DISPATCH_PROMPT_INPUT_KEY = "prompt"
+ALL_OUTCOME_MARKERS = ("outcome:",)
+ALL_BLOCKER_CLAUSE_MARKERS = ("on a blocker:", "at a blocker:")
+MARKER_DECORATION_CHARACTERS = "*_` \t"
 
-ALL_SPAWN_TOOL_NAMES = frozenset(
-    {
-        "Agent",
-        "Task",
-        "Workflow",
-        "multi_agent_v1__spawn_agent",
-        "mcp__hearthbot__start_thread_session",
-        "mcp__hearthbot__start_rc_session",
-    }
+MISSING_OUTCOME_REASON = (
+    "The brief has no outcome line. Add `Outcome: <what the user has when the "
+    "work is done>`."
 )
+MISSING_BLOCKER_CLAUSE_REASON = (
+    "The brief has no blocker clause. Add `On a blocker: try other routes that "
+    "reach the outcome; hand the user a step only when it needs their hands.` "
+    "Name any route as `Suggested route: <route>`, a default the worker may leave."
+)
+REFUSAL_PREFIX = "Spawn refused before the worker starts."
+REFUSAL_SUFFIX = (
+    "The worker owns reaching the outcome by any allowed route. Add the "
+    "missing lines and call the spawn again."
+)
+REASON_SEPARATOR = " "
 
 SPAWN_OVERSIGHT_DIRECTIVE = (
     "You own the work this spawn starts. Load the orchestrator skill and follow "

package/hooks/hooks_constants/spawn_readiness_hook_constants.py

@@ -24,6 +24,8 @@ ALL_BRIEF_FIELDS_BY_SPAWN_TOOL_NAME = {
     THREAD_SPAWN_TOOL_NAME: "instructions",
     CODEX_SPAWN_TOOL_NAME: "message",
     WORKFLOW_TOOL_NAME: "script",
+    "mcp__hearthbot__start_rc_session": "instructions",
+    "mcp__hearthbot__start_remote_control": "instructions",
 }
 WORKFLOW_DISPATCH_TOOL_NAME = "mcp__github__actions_run_trigger"
 DISPATCH_METHOD_INPUT_KEY = "method"

package/hooks/routing/spawn_brief_text.py

@@ -0,0 +1,85 @@
+"""Read the brief a spawn call hands its agents, for the spawn hooks that check it.
+
+Each spawn tool keeps its brief in its own input field. A ``Workflow`` call
+carries a script or a path to one, and a workflow dispatch carries the brief in
+its ``prompt`` input.
+
+::
+
+    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
+    Bash              {"command": "ls"}                           -> None
+"""
+
+from __future__ import annotations
+
+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)
+
+from hooks_constants.spawn_readiness_hook_constants import (
+    ALL_BRIEF_FIELDS_BY_SPAWN_TOOL_NAME,
+    DISPATCH_INPUTS_KEY,
+    DISPATCH_METHOD_INPUT_KEY,
+    DISPATCH_PROMPT_INPUT_KEY,
+    DISPATCH_RUN_WORKFLOW_METHOD,
+    TRANSCRIPT_DECODE_ERRORS,
+    TRANSCRIPT_ENCODING,
+    WORKFLOW_DISPATCH_TOOL_NAME,
+    WORKFLOW_SCRIPT_PATH_INPUT_KEY,
+    WORKFLOW_TOOL_NAME,
+)
+
+
+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, ValueError):
+        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_text(tool_name: object, 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.
+
+    A spawn tool whose brief field is missing or not a string gives "", so a
+    hook can tell an empty brief from a call that spawns nothing.
+
+    Args:
+        tool_name: The tool the session called.
+        all_tool_input_fields: The tool input.
+
+    Returns:
+        The brief text, "" for a spawn with no readable brief, or None.
+    """
+    if tool_name == WORKFLOW_DISPATCH_TOOL_NAME:
+        return _dispatch_prompt(all_tool_input_fields)
+    if not isinstance(tool_name, str) or tool_name not in ALL_BRIEF_FIELDS_BY_SPAWN_TOOL_NAME:
+        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 ""

package/hooks/routing/spawn_oversight_hook.py

@@ -1,25 +1,29 @@
 #!/usr/bin/env python3
-"""PreToolUse hook: tell the spawning session it owns the work it delegates.
+"""PreToolUse hook: refuse a spawn brief without the user's outcome and a blocker clause.
 
 Registered on every tool that starts another agent: ``Agent``, ``Task``,
 ``Workflow``, ``multi_agent_v1__spawn_agent``,
-``mcp__hearthbot__start_thread_session``, and
-``mcp__hearthbot__start_rc_session``, plus a workflow dispatch whose inputs
-carry a ``prompt`` for an agent. Each spawn gets the oversight directive
-as ``additionalContext``, so the spawn runs and keeps its normal permission
-flow. A subagent that spawns its own agents gets the same directive, so every
-level of the tree oversees the level below it.
+``mcp__hearthbot__start_thread_session``, ``mcp__hearthbot__start_rc_session``,
+and ``mcp__hearthbot__start_remote_control``, plus a workflow dispatch whose
+inputs carry a ``prompt`` for an agent. The brief needs an ``Outcome:`` line
+and an ``On a blocker:`` clause, each with text after it, so the worker owns
+the outcome and any route named is a default.
 
 ::
 
-    Agent {"prompt": "Do X."}        -> additionalContext: the directive
-    actions trigger {"method": "run_workflow",
-                     "inputs": {"prompt": "Do X."}}
-                                     -> additionalContext: the directive
+    Agent {"prompt": "Run X via RC."}            -> deny: no outcome, no blocker clause
+    Agent {"prompt": "Outcome: ... On a blocker: ..."}
+                                                 -> additionalContext: the directive
+    Workflow {"name": "saved-review"}            -> additionalContext: the directive
     actions trigger {"method": "cancel_workflow_run"}
-                                     -> no output
-    Bash {"command": "ls"}           -> no output
-    Agent "not an object"            -> no output
+                                                 -> no output
+    Bash {"command": "ls"}                       -> no output
+    Agent "not an object"                        -> no output
+
+A passing spawn gets the oversight directive, so the spawner owns the work it
+delegates. Subagent and read-only helper spawns are checked the same way. A
+``Workflow`` call with no script text, such as a saved or resumed run, passes
+with the directive.
 """
 
 from __future__ import annotations
@@ -30,57 +34,85 @@ 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_specific_output_keys import (
     HOOK_EVENT_NAME_KEY,
     HOOK_SPECIFIC_OUTPUT_KEY,
+    PERMISSION_DECISION_KEY,
 )
 from hooks_constants.pre_tool_use_context_runner import run_context_hook
 from hooks_constants.spawn_oversight_hook_constants import (
     ADDITIONAL_CONTEXT_KEY,
-    ALL_SPAWN_TOOL_NAMES,
-    DISPATCH_INPUTS_KEY,
-    DISPATCH_METHOD_INPUT_KEY,
-    DISPATCH_PROMPT_INPUT_KEY,
-    DISPATCH_RUN_WORKFLOW_METHOD,
+    ALL_BLOCKER_CLAUSE_MARKERS,
+    ALL_OUTCOME_MARKERS,
+    DENY_DECISION,
+    MARKER_DECORATION_CHARACTERS,
+    MISSING_BLOCKER_CLAUSE_REASON,
+    MISSING_OUTCOME_REASON,
+    PERMISSION_DECISION_REASON_KEY,
     PRE_TOOL_USE_EVENT_NAME,
+    REASON_SEPARATOR,
+    REFUSAL_PREFIX,
+    REFUSAL_SUFFIX,
     SPAWN_OVERSIGHT_DIRECTIVE,
     TOOL_INPUT_KEY,
     TOOL_NAME_KEY,
-    WORKFLOW_DISPATCH_TOOL_NAME,
+    WORKFLOW_TOOL_NAME,
 )
+from spawn_brief_text import spawn_brief_text
 
 
-def starts_an_agent(tool_name: object, all_tool_input_fields: dict[str, object]) -> bool:
-    """Return True when the call starts an agent: a spawn tool or a prompt dispatch.
+def has_marked_clause(brief: str, all_markers: tuple[str, ...]) -> bool:
+    """Return True when a marker appears in the brief with text after it on its line.
+
+    ::
+
+        "Outcome: the test passes." , ("outcome:",)  -> True
+        "- **Outcome:** the test passes."            -> True
+        "Do X.\\nOutcome:\\nOn a blocker:"            -> False
 
     Args:
-        tool_name: The tool the session called.
-        all_tool_input_fields: The tool input.
+        brief: The text the spawn hands its agents.
+        all_markers: Lowercase marker strings such as ``"outcome:"``.
     """
-    if tool_name in ALL_SPAWN_TOOL_NAMES:
-        return True
-    if tool_name != WORKFLOW_DISPATCH_TOOL_NAME:
-        return False
-    if all_tool_input_fields.get(DISPATCH_METHOD_INPUT_KEY) != DISPATCH_RUN_WORKFLOW_METHOD:
-        return False
-    workflow_inputs = all_tool_input_fields.get(DISPATCH_INPUTS_KEY)
-    return isinstance(workflow_inputs, dict) and isinstance(
-        workflow_inputs.get(DISPATCH_PROMPT_INPUT_KEY), str
+    return any(
+        _has_text_after_marker(each_line, each_marker)
+        for each_line in brief.lower().splitlines()
+        for each_marker in all_markers
     )
 
 
-def decide_hook_output(all_hook_fields: dict[str, object]) -> dict[str, object] | None:
-    """Return the oversight directive for a spawn call, else None.
+def _has_text_after_marker(line: str, marker: str) -> bool:
+    all_segments_after_marker = line.split(marker)[1:]
+    return any(
+        each_segment.strip(MARKER_DECORATION_CHARACTERS)
+        for each_segment in all_segments_after_marker
+    )
+
+
+def brief_gaps(brief: str) -> list[str]:
+    """Return the refusal reason for each required clause the brief lacks.
+
+    ::
+
+        "Run X on the PC via RC."                    -> [no outcome, no blocker clause]
+        "Outcome: X is done. On a blocker: try ..."  -> []
 
     Args:
-        all_hook_fields: The parsed PreToolUse payload.
+        brief: The text the spawn hands its agents.
     """
-    all_tool_input_fields = all_hook_fields.get(TOOL_INPUT_KEY)
-    if not isinstance(all_tool_input_fields, dict):
-        return None
-    if not starts_an_agent(all_hook_fields.get(TOOL_NAME_KEY), all_tool_input_fields):
-        return None
+    all_gaps = []
+    if not has_marked_clause(brief, ALL_OUTCOME_MARKERS):
+        all_gaps.append(MISSING_OUTCOME_REASON)
+    if not has_marked_clause(brief, ALL_BLOCKER_CLAUSE_MARKERS):
+        all_gaps.append(MISSING_BLOCKER_CLAUSE_REASON)
+    return all_gaps
+
+
+def _directive_output() -> dict[str, object]:
     return {
         HOOK_SPECIFIC_OUTPUT_KEY: {
             HOOK_EVENT_NAME_KEY: PRE_TOOL_USE_EVENT_NAME,
@@ -89,6 +121,42 @@ def decide_hook_output(all_hook_fields: dict[str, object]) -> dict[str, object]
     }
 
 
+def _deny_output(all_gaps: list[str]) -> dict[str, object]:
+    return {
+        HOOK_SPECIFIC_OUTPUT_KEY: {
+            HOOK_EVENT_NAME_KEY: PRE_TOOL_USE_EVENT_NAME,
+            PERMISSION_DECISION_KEY: DENY_DECISION,
+            PERMISSION_DECISION_REASON_KEY: REASON_SEPARATOR.join(
+                [REFUSAL_PREFIX, *all_gaps, REFUSAL_SUFFIX]
+            ),
+        }
+    }
+
+
+def decide_hook_output(all_hook_fields: dict[str, object]) -> dict[str, object] | None:
+    """Return a deny for a brief that lacks a clause, the directive for one that passes.
+
+    Args:
+        all_hook_fields: The parsed PreToolUse payload.
+
+    Returns:
+        None for a call that spawns no agent, else the deny or the directive.
+    """
+    all_tool_input_fields = all_hook_fields.get(TOOL_INPUT_KEY)
+    if not isinstance(all_tool_input_fields, dict):
+        return None
+    tool_name = all_hook_fields.get(TOOL_NAME_KEY)
+    brief = spawn_brief_text(tool_name, all_tool_input_fields)
+    if brief is None:
+        return None
+    if tool_name == WORKFLOW_TOOL_NAME and not brief:
+        return _directive_output()
+    all_gaps = brief_gaps(brief)
+    if all_gaps:
+        return _deny_output(all_gaps)
+    return _directive_output()
+
+
 def main() -> int:
     """Run the hook on the stdin payload; always 0."""
     return run_context_hook(decide_hook_output)

package/hooks/routing/spawn_readiness_hook.py

@@ -39,15 +39,10 @@ from hooks_constants.pre_tool_use_context_runner import run_context_hook
 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,
     LOG_APPEND_MODE,
     LOG_LINE_END,
     LOG_OUTCOME_KEY,
@@ -70,50 +65,22 @@ from hooks_constants.spawn_readiness_hook_constants import (
     TRANSCRIPT_ENCODING,
     TRANSCRIPT_PATH_KEY,
     WORKFLOW_DISPATCH_TOOL_NAME,
-    WORKFLOW_SCRIPT_PATH_INPUT_KEY,
-    WORKFLOW_TOOL_NAME,
 )
 from hooks_constants.hook_specific_output_keys import (
     HOOK_EVENT_NAME_KEY,
     HOOK_SPECIFIC_OUTPUT_KEY,
 )
+from spawn_brief_text import spawn_brief_text
 from spawn_readiness_steps import readiness_gaps, session_steps
 
 
-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.
+    """Return the brief a spawn call hands its agents, or None when the hook skips it.
 
     ::
 
         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
 
@@ -121,16 +88,12 @@ def spawn_brief(tool_name: str, all_tool_input_fields: dict[str, object]) -> str
         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:
+    if (
+        tool_name != WORKFLOW_DISPATCH_TOOL_NAME
+        and 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 ""
+    return spawn_brief_text(tool_name, all_tool_input_fields)
 
 
 def scope_settled_line(brief: str) -> str | None:

package/hooks/routing/test_spawn_brief_text.py

@@ -0,0 +1,36 @@
+from pathlib import Path
+
+import pytest
+
+from spawn_brief_text import spawn_brief_text
+
+
+@pytest.mark.parametrize(
+    ("tool_name", "tool_input", "expected_brief"),
+    [
+        ("Agent", {"prompt": "Do X."}, "Do X."),
+        ("mcp__hearthbot__start_remote_control", {"instructions": "Do Y."}, "Do Y."),
+        ("multi_agent_v1__spawn_agent", {"message": "Do Z."}, "Do Z."),
+        ("Agent", {"description": "No prompt"}, ""),
+        (
+            "mcp__github__actions_run_trigger",
+            {"method": "run_workflow", "inputs": {"prompt": "Do W."}},
+            "Do W.",
+        ),
+        ("mcp__github__actions_run_trigger", {"method": "cancel_workflow_run"}, None),
+        ("Bash", {"command": "ls"}, None),
+        ("Workflow", {"name": "saved-review"}, ""),
+    ],
+)
+def test_should_return_the_brief_each_spawn_tool_carries(
+    tool_name: str, tool_input: dict[str, object], expected_brief: str | None
+) -> None:
+    assert spawn_brief_text(tool_name, tool_input) == expected_brief
+
+
+def test_should_read_a_workflow_script_file(tmp_path: Path) -> None:
+    script_path = tmp_path / "workflow.js"
+    script_path.write_text("agent('Outcome: done.')", encoding="utf-8")
+    assert spawn_brief_text("Workflow", {"scriptPath": str(script_path)}) == (
+        "agent('Outcome: done.')"
+    )

package/hooks/routing/test_spawn_oversight_hook.py

@@ -6,12 +6,63 @@ from pathlib import Path
 import pytest
 
 import spawn_oversight_hook
-from hooks_constants.spawn_oversight_hook_constants import SPAWN_OVERSIGHT_DIRECTIVE
+from hooks_constants.spawn_oversight_hook_constants import (
+    MISSING_BLOCKER_CLAUSE_REASON,
+    MISSING_OUTCOME_REASON,
+    SPAWN_OVERSIGHT_DIRECTIVE,
+)
 
 HOOK_SCRIPT = Path(__file__).resolve().parent / "spawn_oversight_hook.py"
 
+ROUTE_ONLY_BRIEF = "Run X on the PC via RC and send me the output."
+GOOD_BRIEF = (
+    "Outcome: the user has X's output in this thread. Suggested route: RC on the PC. "
+    "On a blocker: try the bridge, a cloud run, or another route that reaches the "
+    "outcome; hand the user a step only when it needs their hands."
+)
+OUTCOME_ONLY_BRIEF = (
+    "Outcome: the user has X's output in this thread. Suggested route: RC on the PC."
+)
+BLOCKER_ONLY_BRIEF = (
+    "Run X on the PC via RC. On a blocker: try the bridge or a cloud run; hand the "
+    "user a step only when it needs their hands."
+)
+MARKDOWN_BRIEF = (
+    "Fix the parser.\n\n"
+    "- **Outcome:** the parser test passes on main.\n"
+    "- **On a blocker:** try another route; hand the user a step only when it needs "
+    "their hands.\n"
+)
+EMPTY_MARKERS_BRIEF = "Do X.\nOutcome:\nOn a blocker:"
+
+ALL_BRIEF_FIELDS_BY_TOOL_NAME = {
+    "Agent": "prompt",
+    "Task": "prompt",
+    "Workflow": "script",
+    "multi_agent_v1__spawn_agent": "message",
+    "mcp__hearthbot__start_thread_session": "instructions",
+    "mcp__hearthbot__start_rc_session": "instructions",
+    "mcp__hearthbot__start_remote_control": "instructions",
+}
+WORKFLOW_DISPATCH_TOOL_NAME = "mcp__github__actions_run_trigger"
+
+
+def _spawn_payload(tool_name: str, brief: str) -> dict[str, object]:
+    if tool_name == WORKFLOW_DISPATCH_TOOL_NAME:
+        return {
+            "tool_name": tool_name,
+            "tool_input": {"method": "run_workflow", "inputs": {"prompt": brief}},
+        }
+    return {
+        "tool_name": tool_name,
+        "tool_input": {ALL_BRIEF_FIELDS_BY_TOOL_NAME[tool_name]: brief},
+    }
 
-def _expected_output() -> dict[str, object]:
+
+ALL_SPAWN_TOOL_NAMES = [*ALL_BRIEF_FIELDS_BY_TOOL_NAME, WORKFLOW_DISPATCH_TOOL_NAME]
+
+
+def _directive_output() -> dict[str, object]:
     return {
         "hookSpecificOutput": {
             "hookEventName": "PreToolUse",
@@ -20,45 +71,101 @@ def _expected_output() -> dict[str, object]:
     }
 
 
-@pytest.mark.parametrize(
-    "tool_name",
-    [
-        "Agent",
-        "Task",
-        "Workflow",
-        "multi_agent_v1__spawn_agent",
-        "mcp__hearthbot__start_thread_session",
-        "mcp__hearthbot__start_rc_session",
-    ],
-)
-def test_every_spawn_tool_gets_the_oversight_directive(tool_name: str) -> None:
-    payload = {"tool_name": tool_name, "tool_input": {"prompt": "Do X."}}
-    assert spawn_oversight_hook.decide_hook_output(payload) == _expected_output()
+def _deny_reason(hook_output: dict[str, object] | None) -> str:
+    assert hook_output is not None
+    hook_specific_output = hook_output["hookSpecificOutput"]
+    assert isinstance(hook_specific_output, dict)
+    assert hook_specific_output["hookEventName"] == "PreToolUse"
+    assert hook_specific_output["permissionDecision"] == "deny"
+    reason = hook_specific_output["permissionDecisionReason"]
+    assert isinstance(reason, str)
+    return reason
 
 
-def test_a_subagent_spawning_its_own_agent_gets_the_directive() -> None:
-    payload = {
-        "tool_name": "Agent",
-        "tool_input": {"prompt": "Do X."},
-        "agent_id": "agent_child",
-    }
-    assert spawn_oversight_hook.decide_hook_output(payload) == _expected_output()
+@pytest.mark.parametrize("tool_name", ALL_SPAWN_TOOL_NAMES)
+def test_a_route_only_brief_is_refused_on_every_spawn_tool(tool_name: str) -> None:
+    reason = _deny_reason(
+        spawn_oversight_hook.decide_hook_output(_spawn_payload(tool_name, ROUTE_ONLY_BRIEF))
+    )
+    assert MISSING_OUTCOME_REASON in reason
+    assert MISSING_BLOCKER_CLAUSE_REASON in reason
+
+
+@pytest.mark.parametrize("tool_name", ALL_SPAWN_TOOL_NAMES)
+def test_a_brief_with_outcome_and_blocker_clause_passes_with_the_directive(
+    tool_name: str,
+) -> None:
+    payload = _spawn_payload(tool_name, GOOD_BRIEF)
+    assert spawn_oversight_hook.decide_hook_output(payload) == _directive_output()
+
+
+@pytest.mark.parametrize("tool_name", ALL_SPAWN_TOOL_NAMES)
+def test_an_outcome_without_a_blocker_clause_is_refused(tool_name: str) -> None:
+    reason = _deny_reason(
+        spawn_oversight_hook.decide_hook_output(_spawn_payload(tool_name, OUTCOME_ONLY_BRIEF))
+    )
+    assert MISSING_BLOCKER_CLAUSE_REASON in reason
+    assert MISSING_OUTCOME_REASON not in reason
+
+
+@pytest.mark.parametrize("tool_name", ALL_SPAWN_TOOL_NAMES)
+def test_a_blocker_clause_without_an_outcome_is_refused(tool_name: str) -> None:
+    reason = _deny_reason(
+        spawn_oversight_hook.decide_hook_output(_spawn_payload(tool_name, BLOCKER_ONLY_BRIEF))
+    )
+    assert MISSING_OUTCOME_REASON in reason
+    assert MISSING_BLOCKER_CLAUSE_REASON not in reason
+
+
+def test_markers_with_no_text_after_them_are_refused() -> None:
+    reason = _deny_reason(
+        spawn_oversight_hook.decide_hook_output(_spawn_payload("Agent", EMPTY_MARKERS_BRIEF))
+    )
+    assert MISSING_OUTCOME_REASON in reason
+    assert MISSING_BLOCKER_CLAUSE_REASON in reason
 
 
-def test_a_read_only_helper_spawn_gets_the_directive() -> None:
+def test_markdown_bullet_markers_pass() -> None:
+    payload = _spawn_payload("Agent", MARKDOWN_BRIEF)
+    assert spawn_oversight_hook.decide_hook_output(payload) == _directive_output()
+
+
+def test_a_missing_brief_field_is_refused() -> None:
+    payload = {"tool_name": "Agent", "tool_input": {"description": "No prompt"}}
+    assert MISSING_OUTCOME_REASON in _deny_reason(spawn_oversight_hook.decide_hook_output(payload))
+
+
+def test_a_subagent_spawning_its_own_agent_is_checked() -> None:
+    payload = {**_spawn_payload("Agent", ROUTE_ONLY_BRIEF), "agent_id": "agent_child"}
+    assert MISSING_OUTCOME_REASON in _deny_reason(spawn_oversight_hook.decide_hook_output(payload))
+
+
+def test_a_read_only_helper_spawn_is_checked() -> None:
     payload = {
         "tool_name": "Agent",
         "tool_input": {"subagent_type": "Explore", "prompt": "Find X."},
     }
-    assert spawn_oversight_hook.decide_hook_output(payload) == _expected_output()
+    assert MISSING_OUTCOME_REASON in _deny_reason(spawn_oversight_hook.decide_hook_output(payload))
 
 
-def test_a_workflow_dispatch_with_an_agent_prompt_gets_the_directive() -> None:
-    payload = {
-        "tool_name": "mcp__github__actions_run_trigger",
-        "tool_input": {"method": "run_workflow", "inputs": {"prompt": "Do X."}},
-    }
-    assert spawn_oversight_hook.decide_hook_output(payload) == _expected_output()
+def test_a_workflow_script_file_is_read_for_the_markers(tmp_path: Path) -> None:
+    script_path = tmp_path / "workflow.js"
+    script_path.write_text(f"agent({json.dumps(ROUTE_ONLY_BRIEF)})", encoding="utf-8")
+    payload = {"tool_name": "Workflow", "tool_input": {"scriptPath": str(script_path)}}
+    assert MISSING_OUTCOME_REASON in _deny_reason(spawn_oversight_hook.decide_hook_output(payload))
+
+
+@pytest.mark.parametrize(
+    "tool_input",
+    [
+        {"name": "saved-review"},
+        {"resumeFromRunId": "wf_abc123"},
+        {"scriptPath": "/nonexistent/workflow.js"},
+    ],
+)
+def test_a_workflow_with_no_script_text_gets_the_directive(tool_input: dict[str, object]) -> None:
+    payload = {"tool_name": "Workflow", "tool_input": tool_input}
+    assert spawn_oversight_hook.decide_hook_output(payload) == _directive_output()
 
 
 @pytest.mark.parametrize(
@@ -82,23 +189,46 @@ def test_other_calls_get_no_output(payload: dict[str, object]) -> None:
     assert spawn_oversight_hook.decide_hook_output(payload) is None
 
 
-def test_script_prints_the_directive_for_a_spawn() -> None:
+def _run_script(stdin_text: str) -> str:
     completed = subprocess.run(
         [sys.executable, str(HOOK_SCRIPT)],
-        input=json.dumps({"tool_name": "Agent", "tool_input": {"prompt": "Do X."}}),
+        input=stdin_text,
         capture_output=True,
         text=True,
         check=True,
     )
-    assert json.loads(completed.stdout) == _expected_output()
+    return completed.stdout
+
+
+@pytest.mark.parametrize("tool_name", ALL_SPAWN_TOOL_NAMES)
+def test_script_refuses_the_route_only_brief(tool_name: str) -> None:
+    stdout = _run_script(json.dumps(_spawn_payload(tool_name, ROUTE_ONLY_BRIEF)))
+    assert MISSING_OUTCOME_REASON in _deny_reason(json.loads(stdout))
+
+
+@pytest.mark.parametrize("tool_name", ALL_SPAWN_TOOL_NAMES)
+def test_script_passes_the_good_brief(tool_name: str) -> None:
+    stdout = _run_script(json.dumps(_spawn_payload(tool_name, GOOD_BRIEF)))
+    assert json.loads(stdout) == _directive_output()
 
 
 def test_script_prints_nothing_for_empty_stdin() -> None:
-    completed = subprocess.run(
-        [sys.executable, str(HOOK_SCRIPT)],
-        input="",
-        capture_output=True,
-        text=True,
-        check=True,
-    )
-    assert completed.stdout == ""
+    assert _run_script("") == ""
+
+
+def test_has_marked_clause_should_find_a_marker_mid_line_with_text_after_it() -> None:
+    assert spawn_oversight_hook.has_marked_clause("Do X. Outcome: X is done.", ("outcome:",))
+    assert not spawn_oversight_hook.has_marked_clause("Do X. Outcome: **", ("outcome:",))
+
+
+def test_brief_gaps_should_name_each_missing_clause() -> None:
+    assert spawn_oversight_hook.brief_gaps(GOOD_BRIEF) == []
+    assert spawn_oversight_hook.brief_gaps(ROUTE_ONLY_BRIEF) == [
+        MISSING_OUTCOME_REASON,
+        MISSING_BLOCKER_CLAUSE_REASON,
+    ]
+
+
+def test_a_workflow_script_path_that_cannot_be_opened_gets_the_directive() -> None:
+    payload = {"tool_name": "Workflow", "tool_input": {"scriptPath": "bad\u0000path.js"}}
+    assert json.loads(_run_script(json.dumps(payload))) == _directive_output()

package/hooks/routing/test_spawn_readiness_hook.py

@@ -394,3 +394,16 @@ def test_should_print_nothing_for_empty_stdin(tmp_path: Path) -> None:
         check=True,
     )
     assert completed.stdout == ""
+
+
+def test_should_skip_a_read_only_helper_brief_and_read_a_remote_control_brief() -> None:
+    assert (
+        spawn_readiness_hook.spawn_brief("Agent", {"subagent_type": "Explore", "prompt": "Find X."})
+        is None
+    )
+    assert (
+        spawn_readiness_hook.spawn_brief(
+            "mcp__hearthbot__start_remote_control", {"instructions": "Do X."}
+        )
+        == "Do X."
+    )

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.93.2",
+    "version": "8.94.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {