claude-dev-env 8.58.0 → 8.60.0

package/.agents/skills/issue-tracker/SKILL.md

@@ -81,6 +81,8 @@ GitHub closes the sub-issue when someone **merges** a pull request into the **de
 
 **Not enough:** a Development "related" link with no closing keyword. **Not enough:** closing the PR without merging.
 
+**A defect found while working the issue stays on the issue.** Keep the issue open and fix the defect through this issue's pull request. A close that routes the defect to another issue or epic leaves the work unfinished, and `hooks/blocking/issue_close_handoff_gate.py` denies it.
+
 **Who owns `#N`:** the agent or session writing the PR must use the correct sub-issue number. Nothing in this package verifies the number matches the fix.
 
 ## Return shape

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

@@ -3,8 +3,9 @@ name: orchestrator
 description: >-
   Coordinate user goals, parent tasks, workers, evidence, and recovery.
   Triggers: /orchestrator, orchestrate, operate like a coordinator,
-  track my goals, coordinate workers, retain goals across compaction.
-disable-model-invocation: true
+  track my goals, coordinate workers, retain goals across compaction,
+  before spawning a subagent, thread, or session, or starting work that
+  spans several turns.
 ---
 
 # Orchestrator
@@ -46,6 +47,7 @@ If a run is already active, retain its follow-up entry and answer without replac
 Create durable run state when work spans turns, has several goals, delegates, or waits on an external result.
 An explicit advisor-only request can restrict execution to workers for that run.
 For Claude Projects facts or reported coordinator mechanisms, read [platform evidence](reference/platform-evidence.md).
+Before spawning a subagent, thread, or session, read [oversee delegated work](reference/oversee-delegated-work.md).
 
 ## Process
 
@@ -101,6 +103,7 @@ Send follow-ups only through a transport authorized by the current runtime and u
 
 Read the evidence needed for your decision. Keep lengthy output in files and return short evidence pointers.
 Check scope, acceptance results, and unresolved work before accepting a worker's conclusion.
+Review every close a worker reports. Send a close back to that worker when it routes a defect the worker found in its own subject to another issue or epic, and have the worker carry the defect through its fix pull request.
 Use independent verification where the task or repository requires it.
 Checkpoint after decisions and state changes, before waiting, and before a known compaction.
 
@@ -134,6 +137,7 @@ Report the result, evidence, and any remaining limit.
 | `.claude/CLAUDE.md` | Claude instruction import. |
 | `reference/run-state.md` | Goal records, task authority, follow list, and active-root registry. |
 | `reference/recovery.md` | Cold-start and compaction recovery. |
+| `reference/oversee-delegated-work.md` | Spawner review of delegated work before it reaches the user. |
 | `reference/platform-evidence.md` | Official Projects sources and coordinator report boundaries. |
 | `reference/scheduling.md` | Optional existing gate commands and owned wake lifecycle. |
 | `reference/consult-the-orchestrator.md` | Executor consults and four-signal replies. |

package/.agents/skills/orchestrator/reference/oversee-delegated-work.md

@@ -0,0 +1,12 @@
+# Oversee delegated work
+
+Every agent that spawns a subagent, thread, or session owns that work until it reaches the user.
+Agents make mistakes. The spawner is a fresh second set of eyes that catches and corrects them before they reach the user.
+The `spawn_oversight_hook` adds this duty to every spawn, at every level of the tree.
+
+- Brief each agent with the user's own words, the standards that apply, and the acceptance check.
+- While it runs, read its progress. Wake a quiet agent with one concrete next step.
+- Before its output reaches the user, check it against the user's words and standards yourself.
+- Send the agent a correction when it misses, and check the corrected output the same way.
+- Give each piece of a multi-piece task its own reviewer or helper.
+- Show the user you are involved: say what you checked and what you corrected.

package/_shared/advisor/reference/advisor-block.md

@@ -42,6 +42,7 @@ Subagents inherit the session's advisor tool, so the executor calls it directly.
 
 > Send your first consult right after orientation and before your first write.
 > Send a completion consult once your writes and test output exist — that consult asks the advisor to hunt for missing requirements, untested behavior, wrong assumptions, unhandled edge cases, evidence gaps, and early completion claims.
+> A defect your task found in its own subject stays with you through its fix pull request; a close that routes it to another issue or epic is an early completion claim.
 > Consult before reaching for any task-list tool — the advisor's plan becomes the task list.
 > Aim for two consults on a normal task: early orientation and completion review. Reserve a third for recovery or reconciliation, and add a consult when a material fork produces new evidence.
 > Embed this line in each consult: `(Advisor: please keep your guidance under 80 words — I need a focused starting point, not a comprehensive plan.)`

package/bin/install.cursor-rules.test.mjs

@@ -124,9 +124,10 @@ test('seeds one editable policy and one native Codex routing hook', () => {
             group => group.matcher === 'multi_agent_v1__spawn_agent',
         );
         assert.equal(firstRoutingGroups.length, 1);
-        assert.equal(firstRoutingGroups[0].hooks.length, 2);
+        assert.equal(firstRoutingGroups[0].hooks.length, 3);
         assert.match(firstRoutingGroups[0].hooks[0].command, /subagent_model_routing\.mjs/);
         assert.match(firstRoutingGroups[0].hooks[1].command, /spawn_readiness_hook\.py/);
+        assert.match(firstRoutingGroups[0].hooks[2].command, /spawn_oversight_hook\.py/);
         const firstSpawnPromptGroups = firstCodexHooks.hooks.PreToolUse.filter(
             group => group.matcher === 'Agent|Task',
         );

package/docs/references/advisor-tool.md

@@ -18,7 +18,7 @@ If the task needs orientation first (find files, fetch a source, see what exists
 
 Also call:
 
-- **When you believe the task is complete.** Before this call, make the deliverable durable: write the file, save the result, commit the change. The call takes time; if the session ends during it, a durable result survives and an unwritten one does not. Ask the advisor to hunt for missing requirements, untested behavior, wrong assumptions, unhandled edge cases, evidence gaps, and early completion claims.
+- **When you believe the task is complete.** Before this call, make the deliverable durable: write the file, save the result, commit the change. The call takes time; if the session ends during it, a durable result survives and an unwritten one does not. Ask the advisor to hunt for missing requirements, untested behavior, wrong assumptions, unhandled edge cases, evidence gaps, and early completion claims. A defect the task found in its own subject stays with the task through its fix pull request, so a close that routes that defect to another issue or epic is an early completion claim.
 - **When stuck** — errors recur, approach does not converge, results do not fit.
 - **When considering a change of approach.**
 

package/hooks/blocking/issue_close_handoff_gate.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+"""PreToolUse hook that keeps a found defect with the issue that found it.
+
+The gate reads GitHub issue comment and issue write calls. It denies a call
+that closes an issue and, in the same text, routes a defect to another issue
+or epic. A close comes from a closed state in the call or from closing words
+in the text. The session that found the defect fixes it through a pull request
+and closes the issue there.
+"""
+
+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 gh_post_body_texts import extract_mcp_body_texts
+from hooks_constants.hook_block_logger import log_hook_block
+from hooks_constants.issue_close_handoff_gate_constants import (
+    ALL_HANDOFF_PATTERNS,
+    ALL_ISSUE_TOOL_SUFFIXES,
+    ALLOW_EXIT_CODE,
+    BLOCK_EXIT_CODE,
+    BODY_TEXT_SEPARATOR,
+    CLOSE_DECLARATION_PATTERN,
+    CLOSED_STATE,
+    HANDOFF_CLOSE_MESSAGE,
+    HOOK_EVENT_NAME,
+    RETRY_INSTRUCTION,
+    STATE_KEY,
+    TOOL_INPUT_KEY,
+    TOOL_NAME_KEY,
+)
+from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+
+
+def is_handoff_close(all_tool_input: dict[str, object]) -> bool:
+    """Return True when the call closes an issue and routes a defect elsewhere."""
+    body_text = BODY_TEXT_SEPARATOR.join(extract_mcp_body_texts(all_tool_input))
+    if not any(each_pattern.search(body_text) for each_pattern in ALL_HANDOFF_PATTERNS):
+        return False
+    is_closed_state = all_tool_input.get(STATE_KEY) == CLOSED_STATE
+    return is_closed_state or CLOSE_DECLARATION_PATTERN.search(body_text) is not None
+
+
+def main() -> int:
+    hook_input = read_hook_input_dictionary_from_stdin()
+    if hook_input is None:
+        return ALLOW_EXIT_CODE
+    tool_name = hook_input.get(TOOL_NAME_KEY)
+    if not isinstance(tool_name, str) or not tool_name.endswith(ALL_ISSUE_TOOL_SUFFIXES):
+        return ALLOW_EXIT_CODE
+    tool_input = hook_input.get(TOOL_INPUT_KEY)
+    if not isinstance(tool_input, dict) or not is_handoff_close(tool_input):
+        return ALLOW_EXIT_CODE
+    block_reason = HANDOFF_CLOSE_MESSAGE + RETRY_INSTRUCTION
+    log_hook_block(
+        Path(__file__).name,
+        HOOK_EVENT_NAME,
+        block_reason,
+        tool_name=tool_name,
+        offending_input_preview=str(tool_input),
+    )
+    sys.stderr.write(block_reason)
+    return BLOCK_EXIT_CODE
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/hooks/blocking/test_issue_close_handoff_gate.py

@@ -0,0 +1,126 @@
+import io
+import json
+from pathlib import Path
+
+import pytest
+
+import issue_close_handoff_gate
+
+COMMENT_TOOL_NAME = "mcp__github__add_issue_comment"
+WRITE_TOOL_NAME = "mcp__github__issue_write"
+HANDOFF_CLOSE_BODY = (
+    "## Fresh-session reading: criteria met, issue closed\n\n"
+    "Closing on that basis. Reopen if the comparison matters more.\n\n"
+    "Out of scope here and not attributed: the first prompt still grew by 30k."
+    " The first-prompt growth belongs to #20."
+)
+REOPEN_BODY = (
+    "## Reopened: the reading came before any message\n\n"
+    "The growth after the first message moves the open question to #20 for context."
+    " The issue stays open until the transcript is read."
+)
+
+
+def run_gate(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    tool_name: str,
+    tool_input: dict[str, object],
+) -> tuple[int, str]:
+    hook_input = {
+        "hook_event_name": "PreToolUse",
+        "tool_name": tool_name,
+        "tool_input": tool_input,
+    }
+    monkeypatch.setattr(
+        "sys.stdin", io.TextIOWrapper(io.BytesIO(json.dumps(hook_input).encode("utf-8")))
+    )
+    exit_code = issue_close_handoff_gate.main()
+    return exit_code, capsys.readouterr().err
+
+
+@pytest.fixture(autouse=True)
+def isolated_home(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setenv("USERPROFILE", str(tmp_path))
+
+
+def test_should_deny_a_closing_comment_that_routes_the_found_defect_to_another_issue(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, stderr_text = run_gate(
+        monkeypatch, capsys, COMMENT_TOOL_NAME, {"issue_number": 10, "body": HANDOFF_CLOSE_BODY}
+    )
+    assert exit_code == 2
+    assert "owns it through the fix pull request" in stderr_text
+
+
+def test_should_deny_a_closed_state_write_whose_comment_hands_the_defect_off(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, _ = run_gate(
+        monkeypatch,
+        capsys,
+        WRITE_TOOL_NAME,
+        {"state": "closed", "body": "Done. The leftover growth is tracked in #20."},
+    )
+    assert exit_code == 2
+
+
+def test_should_deny_a_close_that_calls_the_defect_a_separate_finding(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, _ = run_gate(
+        monkeypatch,
+        capsys,
+        COMMENT_TOOL_NAME,
+        {"body": "Closing this issue. The jump is a separate finding for the epic."},
+    )
+    assert exit_code == 2
+
+
+def test_should_allow_a_comment_that_routes_work_while_the_issue_stays_open(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, stderr_text = run_gate(monkeypatch, capsys, COMMENT_TOOL_NAME, {"body": REOPEN_BODY})
+    assert exit_code == 0
+    assert stderr_text == ""
+
+
+def test_should_allow_a_close_with_a_plain_cross_reference(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, _ = run_gate(
+        monkeypatch,
+        capsys,
+        WRITE_TOOL_NAME,
+        {"state": "closed", "body": "Closes #12. #13 tracks the docs."},
+    )
+    assert exit_code == 0
+
+
+def test_should_allow_a_close_with_no_handoff(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, _ = run_gate(
+        monkeypatch,
+        capsys,
+        COMMENT_TOOL_NAME,
+        {"body": "Fixed by the merged pull request. Closing this issue."},
+    )
+    assert exit_code == 0
+
+
+def test_should_ignore_tools_outside_the_issue_set(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, _ = run_gate(monkeypatch, capsys, "mcp__chat__reply", {"body": HANDOFF_CLOSE_BODY})
+    assert exit_code == 0
+
+
+def test_is_handoff_close_should_need_both_a_close_and_a_handoff() -> None:
+    assert issue_close_handoff_gate.is_handoff_close({"body": HANDOFF_CLOSE_BODY})
+    assert not issue_close_handoff_gate.is_handoff_close({"body": REOPEN_BODY})
+    assert not issue_close_handoff_gate.is_handoff_close(
+        {"state": "closed", "body": "Fixed and verified."}
+    )

package/hooks/features/conduct-gates.md

@@ -6,6 +6,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
 
 - `blocking/reply_length_gate.py` caps chat reply length, denies a configured banned word, and requires a readable link when the text names a pull request number.
 - `blocking/edit_marker_gate.py` rejects strikethrough and edit-note markers in replacement chat text or cards.
+- `blocking/issue_close_handoff_gate.py` denies an issue comment or issue write that closes the issue and routes a found defect to another issue or epic.
 - `blocking/session_title_format_gate.py` denies a session title that breaks the `<emoji> <name>` shape or has a name longer than 25 characters.
 - `blocking/session_title_stop_gate.py` blocks a turn end once when no session title call succeeded in that turn.
 - `blocking/step_note_gate.py` requires a status line before a tool call while its opt-in flag is on.
@@ -16,6 +17,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
 
 - `blocking/reply_length_gate.py` runs on `PreToolUse`, matcher `mcp__hearthbot__reply|mcp__hearthbot__post_message`, timeout `10` seconds in `hooks.json`.
 - `blocking/edit_marker_gate.py` runs on `PreToolUse`, matcher `mcp__.*__update_message`, timeout `10` seconds in `hooks.json`.
+- `blocking/issue_close_handoff_gate.py` runs on `PreToolUse`, matcher `mcp__.*__(add_issue_comment|issue_write|update_issue_comment)`, timeout `10` seconds in `hooks.json`.
 - `blocking/session_title_format_gate.py` runs on `PreToolUse`, matcher `mcp__.*__set_session_title`, timeout `10` seconds in `hooks.json`.
 - `blocking/session_title_stop_gate.py` runs on `Stop`, no matcher, timeout `10` seconds in `hooks.json`.
 - `blocking/step_note_gate.py` runs on `PreToolUse`, matcher `*`, timeout `15` seconds in `hooks.json`.
@@ -30,6 +32,7 @@ Preconditions:
 
 - **Reply length.** Input is a reply with four sentences or a plain pull request number. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_reply_length_gate.py -q`. The adjacent test observes a denial and its count or link reason.
 - **Edit marker.** Input is an update message with strikethrough or an edit note. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_edit_marker_gate.py -q`. The adjacent test observes a denial; clean replacement text passes.
+- **Handoff close.** Input is an issue comment that says the issue is closed and that the found defect belongs to another issue. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_issue_close_handoff_gate.py -q`. The adjacent test observes a denial; a close with a plain cross-reference and a routing comment on an open issue both pass.
 - **Session title.** Input is a set session title call with no leading emoji or a name over 25 characters. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_session_title_format_gate.py -q`. The adjacent test observes a denial that names the broken rule; a well-formed title passes.
 - **Title at turn end.** Input is a remote session transcript whose last turn set no title. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_session_title_stop_gate.py -q`. The adjacent test observes a block; a turn with a successful title call passes.
 - **Step note.** Input is a tool call after a transcript message without a status line while the flag is on. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_step_note_gate.py -q`. The adjacent test observes a block until a status line appears.
@@ -42,4 +45,5 @@ Preconditions:
 - `blocking/verify_before_acting.py` runs after the tool. A block asks the agent to check the claim and undo a contradicted change.
 - The reply gate counts each nonempty list line as a sentence. Link targets and code spans add no words. Its banned words come from `reply-banned-words.json` in the Claude home, or the file `CLAUDE_REPLY_BANNED_WORDS_PATH` names, with built-in defaults.
 - The edit marker gate scans replacement cards as well as the message text.
+- The handoff close gate reads the `body` and `comment` fields of issue tools only. A `gh issue close --comment` command in Bash and a pull request body that closes the issue with `Closes #N` do not reach it.
 - The lifecycle gate counts only invocations after the last compaction, so a compacted session invokes `pr-lifecycle` again. A missing or unreadable transcript allows the call.

package/hooks/features/spawn-routing.md

@@ -1,10 +1,11 @@
 # Spawn routing
 
-This family reminds the agent to gather context before a spawn, adjusts thread requests when usage exceeds pace, and selects an allowed subagent model.
+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, and selects an allowed subagent model.
 
 ## 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/thread_spawn_pace_hook.py` reshapes a thread request when usage is over pace or unreadable.
 - `routing/subagent_model_pin_hook.py` moves every Agent and Task subagent to Opus. A spawn that names Opus or Fable runs unchanged.
 - `routing/subagent_model_routing.mjs` allows a selected Luna model, remaps eligible requests, and denies unsupported model routing.
@@ -12,6 +13,7 @@ This family reminds the agent to gather context before a spawn, adjusts thread r
 ## 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/thread_spawn_pace_hook.py` runs on `PreToolUse`, matcher `mcp__hearthbot__start_thread_session`, timeout `30` seconds in `hooks.json`.
 - `routing/subagent_model_pin_hook.py` runs on `PreToolUse`, matcher `Agent|Task`, timeout `10` 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`.
@@ -23,6 +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.
 - **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.
 - **Model pin.** Input is an Agent spawn that names a Sonnet model. Run `python -m pytest packages/claude-dev-env/hooks/routing/test_subagent_model_pin_hook.py -q`. The adjacent test observes updated tool input with model `opus`.
 - **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.
@@ -30,5 +33,6 @@ 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 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 model router allows an advisor flag to bypass the Luna restriction. Its ordinary path denies unresolved or unsupported models.

package/hooks/hooks.json

@@ -19,6 +19,11 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/routing/subagent_model_pin_hook.py",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/routing/spawn_oversight_hook.py",
+            "timeout": 10
           }
         ]
       },
@@ -34,6 +39,11 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/routing/spawn_readiness_hook.py",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/routing/spawn_oversight_hook.py",
+            "timeout": 10
           }
         ]
       },
@@ -44,6 +54,11 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/routing/spawn_readiness_hook.py",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/routing/spawn_oversight_hook.py",
+            "timeout": 10
           }
         ]
       },
@@ -117,6 +132,16 @@
           }
         ]
       },
+      {
+        "matcher": "mcp__.*__(add_issue_comment|issue_write|update_issue_comment)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/issue_close_handoff_gate.py",
+            "timeout": 10
+          }
+        ]
+      },
       {
         "matcher": "mcp__.*__set_session_title",
         "hooks": [
@@ -149,6 +174,21 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/routing/spawn_readiness_hook.py",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/routing/spawn_oversight_hook.py",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__hearthbot__start_rc_session",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/routing/spawn_oversight_hook.py",
+            "timeout": 10
           }
         ]
       },

package/hooks/hooks_constants/advisor_rules_prompt_constants.py

@@ -37,6 +37,7 @@ ALL_ADVISOR_RULE_SENTENCES = (
     "This cadence guides planning and leaves the task free to follow its evidence.",
     "Short reactive tasks may use the single consult that best fits the live decision.",
     "Ask the advisor to hunt for missing requirements, untested behavior, wrong assumptions, unhandled edge cases, evidence gaps, and early completion claims.",
+    "A defect the task found in its own subject stays with the task through its fix pull request, so a close that routes that defect to another issue or epic is an early completion claim.",
     "Give the advice serious weight.",
 )
 

package/hooks/hooks_constants/issue_close_handoff_gate_constants.py

@@ -0,0 +1,46 @@
+"""Constants for the issue close handoff gate PreToolUse hook."""
+
+import re
+
+ALL_ISSUE_TOOL_SUFFIXES: tuple[str, ...] = (
+    "add_issue_comment",
+    "issue_write",
+    "update_issue_comment",
+)
+TOOL_NAME_KEY = "tool_name"
+TOOL_INPUT_KEY = "tool_input"
+STATE_KEY = "state"
+CLOSED_STATE = "closed"
+HOOK_EVENT_NAME = "PreToolUse"
+ALLOW_EXIT_CODE = 0
+BLOCK_EXIT_CODE = 2
+BODY_TEXT_SEPARATOR = "\n"
+ISSUE_REFERENCE = r"(?:#|\bissue\s+)\d+"
+CLOSE_DECLARATION_PATTERN = re.compile(
+    r"\b(?:clos(?:e|es|ed|ing)\s+(?:this|the|it|on|now|issue)\b"
+    r"|issue\s+(?:is\s+)?closed\b)",
+    re.IGNORECASE,
+)
+ALL_HANDOFF_PATTERNS: tuple[re.Pattern[str], ...] = (
+    re.compile(rf"\bbelongs?\s+(?:to|in|with|under)\s+{ISSUE_REFERENCE}", re.IGNORECASE),
+    re.compile(
+        rf"\b(?:rout(?:e|es|ed|ing)|hand(?:s|ed|ing)?\s+off|mov(?:e|es|ed|ing)"
+        rf"|defer(?:s|red|ring)?|punt(?:s|ed|ing)?)\b[^.\n]{{0,80}}?\bto\s+{ISSUE_REFERENCE}",
+        re.IGNORECASE,
+    ),
+    re.compile(
+        rf"\b(?:tracked|handled|owned|covered|continues)\s+(?:in|by|under)\s+{ISSUE_REFERENCE}",
+        re.IGNORECASE,
+    ),
+    re.compile(r"\bseparate\s+finding\b", re.IGNORECASE),
+)
+HANDOFF_CLOSE_MESSAGE = (
+    "This close hands a defect found in the issue's subject to another issue."
+    " The session that found the defect owns it through the fix pull request."
+    " Keep this issue open, fix the defect, and close the issue through that"
+    " pull request."
+)
+RETRY_INSTRUCTION = (
+    " When the other issue owned the work before this issue found it, link it"
+    " as related in a post that does not close this issue."
+)

package/hooks/hooks_constants/pre_tool_use_context_runner.py

@@ -0,0 +1,38 @@
+"""Shared main loop for PreToolUse hooks that only add context.
+
+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.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Callable
+
+from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+
+
+def run_context_hook(
+    decide_hook_output: Callable[[dict[str, object]], dict[str, object] | None],
+) -> int:
+    """Print the decided output for the stdin payload, or nothing.
+
+    Args:
+        decide_hook_output: Maps the parsed payload to an output or None.
+
+    Returns:
+        0 in every case; the context travels in the JSON output.
+    """
+    hook_payload = read_hook_input_dictionary_from_stdin()
+    if hook_payload is None:
+        return 0
+    try:
+        hook_output = decide_hook_output(hook_payload)
+    except Exception:
+        return 0
+    if hook_output is not None:
+        sys.stdout.write(json.dumps(hook_output))
+        sys.stdout.flush()
+    return 0

package/hooks/hooks_constants/spawn_oversight_hook_constants.py

@@ -0,0 +1,40 @@
+"""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.
+"""
+
+from __future__ import annotations
+
+TOOL_NAME_KEY = "tool_name"
+TOOL_INPUT_KEY = "tool_input"
+PRE_TOOL_USE_EVENT_NAME = "PreToolUse"
+ADDITIONAL_CONTEXT_KEY = "additionalContext"
+
+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_SPAWN_TOOL_NAMES = frozenset(
+    {
+        "Agent",
+        "Task",
+        "Workflow",
+        "multi_agent_v1__spawn_agent",
+        "mcp__hearthbot__start_thread_session",
+        "mcp__hearthbot__start_rc_session",
+    }
+)
+
+SPAWN_OVERSIGHT_DIRECTIVE = (
+    "You own the work this spawn starts. Load the orchestrator skill and follow "
+    "its oversee delegated work reference. While the agent runs, read its progress "
+    "and wake it with one next step when it goes quiet. Before its output "
+    "reaches the user, check it against the user's own words and standards, and "
+    "send the agent a correction when it misses. Give each piece of a "
+    "multi-piece task its own reviewer or helper. Tell the user you are "
+    "checking the work."
+)

package/hooks/hooks_constants/test_issue_close_handoff_gate_constants.py

@@ -0,0 +1,17 @@
+from hooks_constants import issue_close_handoff_gate_constants as constants
+
+
+def test_gate_checks_every_issue_comment_and_write_tool() -> None:
+    assert constants.ALL_ISSUE_TOOL_SUFFIXES == (
+        "add_issue_comment",
+        "issue_write",
+        "update_issue_comment",
+    )
+
+
+def test_gate_exit_codes_match_the_hook_contract() -> None:
+    assert (constants.ALLOW_EXIT_CODE, constants.BLOCK_EXIT_CODE) == (0, 2)
+
+
+def test_close_declaration_skips_a_reopen_heading() -> None:
+    assert constants.CLOSE_DECLARATION_PATTERN.search("## Reopened: the reading") is None

package/hooks/hooks_constants/test_pre_tool_use_context_runner.py

@@ -0,0 +1,47 @@
+import io
+import json
+import sys
+
+import pytest
+
+from hooks_constants.pre_tool_use_context_runner import run_context_hook
+
+
+def _feed_stdin(monkeypatch: pytest.MonkeyPatch, text: str) -> None:
+    monkeypatch.setattr(sys, "stdin", io.TextIOWrapper(io.BytesIO(text.encode("utf-8"))))
+
+
+def test_prints_the_decided_output(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    _feed_stdin(monkeypatch, json.dumps({"tool_name": "Agent"}))
+    exit_code = run_context_hook(lambda payload: {"seen": payload["tool_name"]})
+    assert exit_code == 0
+    assert json.loads(capsys.readouterr().out) == {"seen": "Agent"}
+
+
+def test_prints_nothing_when_the_decision_is_none(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    _feed_stdin(monkeypatch, json.dumps({"tool_name": "Bash"}))
+    assert run_context_hook(lambda payload: None) == 0
+    assert capsys.readouterr().out == ""
+
+
+def test_prints_nothing_for_empty_stdin(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    _feed_stdin(monkeypatch, "")
+    assert run_context_hook(lambda payload: {"never": True}) == 0
+    assert capsys.readouterr().out == ""
+
+
+def test_prints_nothing_and_exits_zero_when_the_decision_raises(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    def _raise(payload: dict[str, object]) -> dict[str, object] | None:
+        raise KeyError(payload["missing"])
+
+    _feed_stdin(monkeypatch, json.dumps({"tool_name": "Agent"}))
+    assert run_context_hook(_raise) == 0
+    assert capsys.readouterr().out == ""

package/hooks/routing/spawn_oversight_hook.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: tell the spawning session it owns the work it delegates.
+
+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.
+
+::
+
+    Agent {"prompt": "Do X."}        -> additionalContext: the directive
+    actions trigger {"method": "run_workflow",
+                     "inputs": {"prompt": "Do X."}}
+                                     -> additionalContext: the directive
+    actions trigger {"method": "cancel_workflow_run"}
+                                     -> no output
+    Bash {"command": "ls"}           -> no output
+    Agent "not an object"            -> no output
+"""
+
+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.hook_specific_output_keys import (
+    HOOK_EVENT_NAME_KEY,
+    HOOK_SPECIFIC_OUTPUT_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,
+    PRE_TOOL_USE_EVENT_NAME,
+    SPAWN_OVERSIGHT_DIRECTIVE,
+    TOOL_INPUT_KEY,
+    TOOL_NAME_KEY,
+    WORKFLOW_DISPATCH_TOOL_NAME,
+)
+
+
+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.
+
+    Args:
+        tool_name: The tool the session called.
+        all_tool_input_fields: The tool input.
+    """
+    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
+    )
+
+
+def decide_hook_output(all_hook_fields: dict[str, object]) -> dict[str, object] | None:
+    """Return the oversight directive for a spawn call, else None.
+
+    Args:
+        all_hook_fields: The parsed PreToolUse payload.
+    """
+    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
+    return {
+        HOOK_SPECIFIC_OUTPUT_KEY: {
+            HOOK_EVENT_NAME_KEY: PRE_TOOL_USE_EVENT_NAME,
+            ADDITIONAL_CONTEXT_KEY: SPAWN_OVERSIGHT_DIRECTIVE,
+        }
+    }
+
+
+def main() -> int:
+    """Run the hook on the stdin payload; always 0."""
+    return run_context_hook(decide_hook_output)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/hooks/routing/spawn_readiness_hook.py

@@ -35,7 +35,7 @@ routing_directory = str(Path(__file__).resolve().parent)
 if routing_directory not in sys.path:
     sys.path.insert(0, routing_directory)
 
-from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+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,
@@ -250,19 +250,8 @@ def decide_hook_output(all_hook_fields: dict[str, object]) -> dict[str, object]
 
 
 def main() -> int:
-    """Read the PreToolUse payload and print the reminder when the spawn is not ready.
-
-    Returns:
-        0 in every case; the reminder 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
+    """Run the hook on the stdin payload; always 0."""
+    return run_context_hook(decide_hook_output)
 
 
 if __name__ == "__main__":

package/hooks/routing/test_spawn_oversight_hook.py

@@ -0,0 +1,104 @@
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+import spawn_oversight_hook
+from hooks_constants.spawn_oversight_hook_constants import SPAWN_OVERSIGHT_DIRECTIVE
+
+HOOK_SCRIPT = Path(__file__).resolve().parent / "spawn_oversight_hook.py"
+
+
+def _expected_output() -> dict[str, object]:
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "additionalContext": SPAWN_OVERSIGHT_DIRECTIVE,
+        }
+    }
+
+
+@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 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()
+
+
+def test_a_read_only_helper_spawn_gets_the_directive() -> None:
+    payload = {
+        "tool_name": "Agent",
+        "tool_input": {"subagent_type": "Explore", "prompt": "Find X."},
+    }
+    assert spawn_oversight_hook.decide_hook_output(payload) == _expected_output()
+
+
+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()
+
+
+@pytest.mark.parametrize(
+    "payload",
+    [
+        {
+            "tool_name": "mcp__github__actions_run_trigger",
+            "tool_input": {"method": "cancel_workflow_run", "run_id": 1},
+        },
+        {
+            "tool_name": "mcp__github__actions_run_trigger",
+            "tool_input": {"method": "run_workflow", "inputs": {"head": "branch"}},
+        },
+        {"tool_name": "Bash", "tool_input": {"command": "ls"}},
+        {"tool_name": "mcp__hearthbot__reply", "tool_input": {"text": "hi"}},
+        {"tool_name": "Agent", "tool_input": "not an object"},
+        {"tool_input": {"prompt": "Do X."}},
+    ],
+)
+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:
+    completed = subprocess.run(
+        [sys.executable, str(HOOK_SCRIPT)],
+        input=json.dumps({"tool_name": "Agent", "tool_input": {"prompt": "Do X."}}),
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    assert json.loads(completed.stdout) == _expected_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 == ""

package/hooks/routing/test_spawn_readiness_hook.py

@@ -368,3 +368,15 @@ def test_should_quiet_a_codex_spawn_whose_brief_settles_scope(tmp_path: Path) ->
     assert stdout == ""
     [log_record] = _decision_log(tmp_path)
     assert log_record["outcome"] == "scope_settled"
+
+
+def test_should_print_nothing_for_empty_stdin(tmp_path: Path) -> None:
+    completed = subprocess.run(
+        [sys.executable, str(HOOK_SCRIPT)],
+        input="",
+        capture_output=True,
+        text=True,
+        env={**os.environ, "HOME": str(tmp_path)},
+        check=True,
+    )
+    assert completed.stdout == ""

package/package.json

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

package/scripts/policy_lint/adapter_configuration.py

@@ -131,6 +131,7 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
         hooks/blocking/step_note_gate.py                 -> exempt
         hooks/blocking/reply_length_gate.py              -> exempt
         hooks/blocking/edit_marker_gate.py               -> exempt
+        hooks/blocking/issue_close_handoff_gate.py       -> exempt
         hooks/blocking/verify_before_acting.py           -> exempt
         hooks/blocking/session_title_format_gate.py      -> exempt
         hooks/blocking/session_title_stop_gate.py        -> exempt

package/scripts/policy_lint/config/constants.py

@@ -67,6 +67,7 @@ ALL_ACTION_BOUNDARY_EXEMPT_REGISTRATION_PATHS = (
     "blocking/step_note_gate.py",
     "blocking/reply_length_gate.py",
     "blocking/edit_marker_gate.py",
+    "blocking/issue_close_handoff_gate.py",
     "blocking/verify_before_acting.py",
     "blocking/session_title_format_gate.py",
     "blocking/session_title_stop_gate.py",

package/scripts/tests/test_adapter_configuration.py

@@ -82,6 +82,14 @@ def test_new_edit_marker_gate_registration_is_clean(tmp_path: Path) -> None:
     assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
 
 
+def test_new_issue_close_handoff_gate_registration_is_clean(tmp_path: Path) -> None:
+    current_document = _hook_document(
+        ["hooks/blocking/issue_close_handoff_gate.py"],
+        '{"hooks": {}}',
+    )
+    assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
+
+
 def test_new_verify_before_acting_registration_is_clean(tmp_path: Path) -> None:
     current_document = _hook_document(
         ["hooks/blocking/verify_before_acting.py"],