claude-dev-env 4.2.0 → 7.0.0

package/hooks/advisory/pr_done_reminder.py

@@ -0,0 +1,342 @@
+#!/usr/bin/env python3
+"""PostToolUse context reminder: the PR done checklist after a push.
+
+This hook never blocks. It watches every Bash call finish and, after a
+successful ``git push`` or ``gh pr create``, probes the branch's pull request
+through ``gh pr view`` and adds one loud checklist to the agent's context::
+
+    === PR DONE CHECKLIST (context reminder, never a block) ===
+    PR #42  https://github.com/acme/widgets/pull/42
+    Mergeable:   CONFLICTING  (CONFLICTS with the base branch. Merge origin/main ...)
+    CI checks:   1 failing, 2 pending, 4 total
+    Draft:       yes
+    Label done:  not set
+    Verdict:     NOT DONE. Do not add the done label yet.
+    Re-check:    gh pr view 42 --json mergeable,mergeStateStatus,statusCheckRollup,labels
+    A PR is done only when every line above is clean.
+
+Why a reminder and not a gate: agents keep working. The rule "a PR is done
+only when GitHub reports it mergeable and CI is clean" arrives as live state
+at the exact moment the agent just pushed, so no instruction file has to be
+remembered. A block would stall the run; this only informs it.
+
+Quiet branches: a non-Bash tool, a command that is not a push or a PR
+creation, a push whose harness-reported exit status is non-zero, or a ``gh``
+failure other than "no pull requests found" each emit nothing.
+
+Hosted by ``blocking/bash_post_call_dispatcher.py``, which forwards the
+``hookSpecificOutput.additionalContext`` this hook prints.
+"""
+
+from __future__ import annotations
+
+import json
+import shlex
+import subprocess
+import sys
+from pathlib import Path
+
+try:
+    _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.bash_pre_tool_use_dispatcher_constants import (
+        ALL_BASH_AND_POWERSHELL_TOOL_NAMES,
+    )
+    from hooks_constants.pr_done_reminder_constants import (
+        ADD_LABEL_COMMAND_TEMPLATE,
+        ALL_FAILING_CHECK_CONCLUSIONS,
+        ALL_PASSING_CHECK_CONCLUSIONS,
+        CHECK_COMPLETED_STATUS,
+        DONE_LABEL_NAME,
+        EXIT_CODE_ERROR_PREFIX,
+        GH_PR_CREATE_ACTION,
+        GH_PR_SUBCOMMAND,
+        ALL_GH_PR_VIEW_ARGUMENTS,
+        ALL_GIT_OPTIONS_WITH_VALUE,
+        ALL_POWERSHELL_COMMAND_FLAGS,
+        ALL_POWERSHELL_PROGRAM_NAMES,
+        GH_PR_VIEW_TIMEOUT_SECONDS,
+        GH_PROGRAM_NAME,
+        GIT_PROGRAM_NAME,
+        GIT_PUSH_SUBCOMMAND,
+        MERGEABLE_CLEAN_VALUE,
+        MERGEABLE_UNKNOWN_VALUE,
+        NO_PULL_REQUEST_MARKER,
+        NO_PULL_REQUEST_REMINDER,
+        RECHECK_COMMAND_TEMPLATE,
+        REMINDER_FOOTER,
+        REMINDER_HEADER,
+        REMINDER_LINE_SEPARATOR,
+        ALL_REMINDER_HINTS_BY_MERGEABLE,
+        STATUS_CONTEXT_STATE_KEY,
+        VERDICT_DONE,
+        VERDICT_NOT_DONE,
+    )
+    from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+    from hooks_constants.shell_command_segments import (
+        effective_leading_program,
+        split_into_segments,
+        token_basename,
+    )
+except ImportError as import_error:
+    raise ImportError(
+        "pr_done_reminder: cannot import its dependencies; "
+        "ensure the hooks directory is importable."
+    ) from import_error
+
+
+def _command_tokens(command: str) -> list[str]:
+    try:
+        return shlex.split(command, posix=True)
+    except ValueError:
+        return command.split()
+
+
+def _segment_program_and_arguments(all_segment_tokens: list[str]) -> tuple[str, list[str]]:
+    program_token = effective_leading_program(all_segment_tokens)
+    if program_token is None:
+        return "", []
+    program_index = all_segment_tokens.index(program_token)
+    return token_basename(program_token), all_segment_tokens[program_index + 1 :]
+
+
+def _git_subcommand(all_arguments: list[str]) -> str | None:
+    """Return git's subcommand after its global options.
+
+    ``git -C <path> push`` and ``git -c <key=value> push`` carry an option
+    value before the subcommand; ``--git-dir=<path>`` carries none. The first
+    token left after those is the subcommand, so ``git stash push`` yields
+    ``stash`` and ``git log --grep push`` yields ``log``.
+    """
+    should_skip_next_token = False
+    for each_argument in all_arguments:
+        if should_skip_next_token:
+            should_skip_next_token = False
+            continue
+        if each_argument in ALL_GIT_OPTIONS_WITH_VALUE:
+            should_skip_next_token = True
+            continue
+        if each_argument.startswith("-"):
+            continue
+        return each_argument
+    return None
+
+
+def _is_git_push(program_name: str, all_arguments: list[str]) -> bool:
+    return (
+        program_name == GIT_PROGRAM_NAME and _git_subcommand(all_arguments) == GIT_PUSH_SUBCOMMAND
+    )
+
+
+def _is_gh_pr_create(program_name: str, all_arguments: list[str]) -> bool:
+    return program_name == GH_PROGRAM_NAME and all_arguments[:2] == [
+        GH_PR_SUBCOMMAND,
+        GH_PR_CREATE_ACTION,
+    ]
+
+
+def _powershell_inner_commands(all_command_tokens: list[str]) -> list[str]:
+    """Return the script texts every ``pwsh -Command "..."`` wrapper runs.
+
+    Read from the raw shlex tokens, before segment splitting: the quoted
+    script is one token here, and splitting it on ``;`` first would cut a
+    ``git add -A; git push`` script in half.
+    """
+    all_inner_commands: list[str] = []
+    has_seen_powershell_program = False
+    for each_token_index, each_token in enumerate(all_command_tokens[:-1]):
+        if token_basename(each_token) in ALL_POWERSHELL_PROGRAM_NAMES:
+            has_seen_powershell_program = True
+            continue
+        if has_seen_powershell_program and each_token.lower() in ALL_POWERSHELL_COMMAND_FLAGS:
+            all_inner_commands.append(all_command_tokens[each_token_index + 1])
+            has_seen_powershell_program = False
+    return all_inner_commands
+
+
+def command_triggers_reminder(command: str) -> bool:
+    """Return True when any segment of the command is a git push or a gh pr create.
+
+    A ``pwsh -Command "..."`` wrapper is unwrapped and its inner text scanned
+    the same way, since the shell rule routes Bash-tool commands through pwsh.
+
+    Args:
+        command: The Bash command text the agent ran.
+    """
+    all_command_tokens = _command_tokens(command)
+    for each_inner_command in _powershell_inner_commands(all_command_tokens):
+        if command_triggers_reminder(each_inner_command):
+            return True
+    for each_segment in split_into_segments(all_command_tokens):
+        program_name, all_arguments = _segment_program_and_arguments(each_segment)
+        if _is_git_push(program_name, all_arguments) or _is_gh_pr_create(
+            program_name, all_arguments
+        ):
+            return True
+    return False
+
+
+def _harness_reported_failure(tool_response: object) -> bool:
+    return isinstance(tool_response, str) and tool_response.startswith(EXIT_CODE_ERROR_PREFIX)
+
+
+def _check_outcome(all_check_fields: dict[str, object]) -> str:
+    """Return failing, pending, or passing for one statusCheckRollup entry.
+
+    A CheckRun entry carries ``status`` and ``conclusion``; a StatusContext
+    entry carries ``state``. Both shapes appear in the same rollup list.
+    """
+    state_text = str(all_check_fields.get(STATUS_CONTEXT_STATE_KEY) or "").upper()
+    if state_text:
+        if state_text in ALL_FAILING_CHECK_CONCLUSIONS:
+            return "failing"
+        return "passing" if state_text in ALL_PASSING_CHECK_CONCLUSIONS else "pending"
+    if str(all_check_fields.get("status") or "").upper() != CHECK_COMPLETED_STATUS:
+        return "pending"
+    conclusion_text = str(all_check_fields.get("conclusion") or "").upper()
+    return "failing" if conclusion_text in ALL_FAILING_CHECK_CONCLUSIONS else "passing"
+
+
+def _check_counts(all_pr_fields: dict[str, object]) -> dict[str, int]:
+    all_checks = all_pr_fields.get("statusCheckRollup")
+    all_check_counts = {"failing": 0, "pending": 0, "passing": 0, "total": 0}
+    if not isinstance(all_checks, list):
+        return all_check_counts
+    for each_check_fields in all_checks:
+        if isinstance(each_check_fields, dict):
+            all_check_counts[_check_outcome(each_check_fields)] += 1
+            all_check_counts["total"] += 1
+    return all_check_counts
+
+
+def _checks_line(all_check_counts: dict[str, int]) -> str:
+    if all_check_counts["total"] == 0:
+        return "none reported"
+    return (
+        f"{all_check_counts['failing']} failing, "
+        f"{all_check_counts['pending']} pending, "
+        f"{all_check_counts['total']} total"
+    )
+
+
+def _has_done_label(all_pr_fields: dict[str, object]) -> bool:
+    all_labels = all_pr_fields.get("labels")
+    if not isinstance(all_labels, list):
+        return False
+    return any(
+        isinstance(each_label, dict) and each_label.get("name") == DONE_LABEL_NAME
+        for each_label in all_labels
+    )
+
+
+def _is_done(mergeable_value: str, all_check_counts: dict[str, int]) -> bool:
+    return (
+        mergeable_value == MERGEABLE_CLEAN_VALUE
+        and all_check_counts["failing"] == 0
+        and all_check_counts["pending"] == 0
+    )
+
+
+def _verdict_lines(number: object, is_done: bool) -> list[str]:
+    """Return the verdict line, the add-label command on DONE, and the re-check line."""
+    all_lines = [f"Verdict:     {VERDICT_DONE if is_done else VERDICT_NOT_DONE}"]
+    if is_done:
+        add_label_command = ADD_LABEL_COMMAND_TEMPLATE.format(number=number, label=DONE_LABEL_NAME)
+        all_lines.append(f"Add label:   {add_label_command}")
+    all_lines.append(f"Re-check:    {RECHECK_COMMAND_TEMPLATE.format(number=number)}")
+    return all_lines
+
+
+def build_reminder_context(all_pr_fields: dict[str, object]) -> str:
+    """Build the checklist text from a ``gh pr view --json`` object.
+
+    Args:
+        all_pr_fields: The parsed pull request JSON with number, url, isDraft,
+            mergeable, mergeStateStatus, statusCheckRollup, and labels.
+
+    Returns:
+        The multi-line checklist ending in a DONE or NOT DONE verdict.
+    """
+    number = all_pr_fields.get("number", "?")
+    mergeable_value = str(all_pr_fields.get("mergeable") or MERGEABLE_UNKNOWN_VALUE).upper()
+    mergeable_hint = ALL_REMINDER_HINTS_BY_MERGEABLE.get(
+        mergeable_value, ALL_REMINDER_HINTS_BY_MERGEABLE[MERGEABLE_UNKNOWN_VALUE]
+    )
+    all_check_counts = _check_counts(all_pr_fields)
+    all_lines = [
+        REMINDER_HEADER,
+        f"PR #{number}  {all_pr_fields.get('url', '')}",
+        f"Mergeable:   {mergeable_value}  ({mergeable_hint})",
+        f"CI checks:   {_checks_line(all_check_counts)}",
+        f"Draft:       {'yes' if all_pr_fields.get('isDraft') else 'no'}",
+        f"Label done:  {'set' if _has_done_label(all_pr_fields) else 'not set'}",
+        *_verdict_lines(number, _is_done(mergeable_value, all_check_counts)),
+        REMINDER_FOOTER,
+    ]
+    return REMINDER_LINE_SEPARATOR.join(all_lines)
+
+
+def _probe_pull_request(cwd: str) -> str | None:
+    """Return the reminder text from a live ``gh pr view``, or None to stay quiet."""
+    try:
+        completed_process = subprocess.run(
+            list(ALL_GH_PR_VIEW_ARGUMENTS),
+            cwd=cwd or None,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=GH_PR_VIEW_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    if completed_process.returncode != 0:
+        combined_output = f"{completed_process.stdout}\n{completed_process.stderr}".lower()
+        return NO_PULL_REQUEST_REMINDER if NO_PULL_REQUEST_MARKER in combined_output else None
+    try:
+        all_pr_fields = json.loads(completed_process.stdout)
+    except json.JSONDecodeError:
+        return None
+    if not isinstance(all_pr_fields, dict):
+        return None
+    return build_reminder_context(all_pr_fields)
+
+
+def _emit_context(context_text: str) -> None:
+    payload = {
+        "hookSpecificOutput": {
+            "hookEventName": "PostToolUse",
+            "additionalContext": context_text,
+        }
+    }
+    sys.stdout.write(json.dumps(payload))
+    sys.stdout.flush()
+
+
+def main() -> None:
+    """Add the PR done checklist to context after a successful push or PR creation.
+
+    Reads the PostToolUse payload from stdin. Every quiet branch returns with
+    no output, so this hook can never alter or block a tool call.
+    """
+    hook_payload = read_hook_input_dictionary_from_stdin()
+    if (
+        hook_payload is None
+        or hook_payload.get("tool_name") not in ALL_BASH_AND_POWERSHELL_TOOL_NAMES
+    ):
+        return
+    tool_input = hook_payload.get("tool_input")
+    command = tool_input.get("command", "") if isinstance(tool_input, dict) else ""
+    if not isinstance(command, str) or not command_triggers_reminder(command):
+        return
+    if _harness_reported_failure(hook_payload.get("tool_response")):
+        return
+    context_text = _probe_pull_request(str(hook_payload.get("cwd") or ""))
+    if context_text is not None:
+        _emit_context(context_text)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/advisory/test_pr_done_reminder.py

@@ -0,0 +1,249 @@
+"""Behavior tests for the PR done-checklist context reminder.
+
+The hook is a PostToolUse observer on Bash. It never blocks. These tests pin
+three things: which commands wake it, what the checklist says for each live
+PR state, and that a probe failure stays quiet. The ``gh`` probe is faked at
+the subprocess boundary so no test touches the network.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+try:
+    advisory_directory = str(Path(__file__).resolve().parent)
+    if advisory_directory not in sys.path:
+        sys.path.insert(0, advisory_directory)
+    import pr_done_reminder
+except ImportError as import_error:
+    raise ImportError(
+        "test_pr_done_reminder: cannot import its sibling modules; "
+        "ensure the advisory directory is importable."
+    ) from import_error
+
+
+_CLEAN_PR_OBJECT: dict[str, object] = {
+    "number": 42,
+    "url": "https://github.com/acme/widgets/pull/42",
+    "isDraft": True,
+    "mergeable": "MERGEABLE",
+    "mergeStateStatus": "CLEAN",
+    "statusCheckRollup": [
+        {"name": "pytest", "status": "COMPLETED", "conclusion": "SUCCESS"},
+        {"context": "lint", "state": "SUCCESS"},
+    ],
+    "labels": [],
+}
+
+
+def _payload(command: str, tool_response: object = None) -> str:
+    response: object = {"stdout": "", "stderr": ""} if tool_response is None else tool_response
+    return json.dumps(
+        {
+            "session_id": "reminder-session",
+            "cwd": "C:/repo",
+            "tool_name": "Bash",
+            "tool_input": {"command": command},
+            "tool_response": response,
+        }
+    )
+
+
+def _fake_gh(pr_object: dict[str, object] | None, stderr: str = "") -> object:
+    def _run(*args: object, **kwargs: object) -> subprocess.CompletedProcess[str]:
+        del args, kwargs
+        if pr_object is None:
+            return subprocess.CompletedProcess([], 1, stdout="", stderr=stderr)
+        return subprocess.CompletedProcess([], 0, stdout=json.dumps(pr_object), stderr="")
+
+    return _run
+
+
+def _run_main(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    payload_text: str,
+    fake_gh: object,
+) -> str:
+    monkeypatch.setattr(pr_done_reminder.subprocess, "run", fake_gh)
+    monkeypatch.setattr(sys, "stdin", io.StringIO(payload_text))
+    pr_done_reminder.main()
+    return capsys.readouterr().out
+
+
+def _additional_context(stdout_text: str) -> str:
+    return str(json.loads(stdout_text)["hookSpecificOutput"]["additionalContext"])
+
+
+@pytest.mark.parametrize(
+    "command",
+    [
+        "git push",
+        "git push -u origin feat/x",
+        "git -C C:/repo push origin HEAD",
+        "gh pr create --draft --title t --body-file b.md",
+        "git add -A && git commit -F m.txt && git push",
+        "git -c push.default=current push",
+        "git --git-dir=C:/repo/.git push",
+        'pwsh -NoProfile -Command "git push -u origin feat/x"',
+        "pwsh -NoProfile -Command 'gh pr create --draft --fill'",
+        'powershell -Command "git add -A; git push"',
+    ],
+)
+def test_should_wake_on_git_push_and_gh_pr_create(command: str) -> None:
+    assert pr_done_reminder.command_triggers_reminder(command) is True
+
+
+@pytest.mark.parametrize(
+    "command",
+    [
+        "git status",
+        "git pull",
+        "git stash push -u -q -- packages",
+        "git log --grep push",
+        "git commit -m push",
+        "gh pr view 42",
+        "gh pr ready --undo",
+        "echo git push",
+        'pwsh -NoProfile -Command "git status"',
+        "pytest tests/",
+    ],
+)
+def test_should_stay_quiet_for_other_commands(command: str) -> None:
+    assert pr_done_reminder.command_triggers_reminder(command) is False
+
+
+def test_should_say_done_when_mergeable_and_checks_pass() -> None:
+    context = pr_done_reminder.build_reminder_context(_CLEAN_PR_OBJECT)
+
+    assert context.startswith("=== PR DONE CHECKLIST")
+    assert "never a block" in context
+    assert "DONE. Add the label now:" in context
+    assert "gh pr edit 42 --add-label done" in context
+    assert "NOT DONE" not in context
+
+
+def test_should_keep_the_checklist_order_verdict_then_recheck_then_footer() -> None:
+    all_lines = pr_done_reminder.build_reminder_context(_CLEAN_PR_OBJECT).split("\n")
+
+    all_labels = [each_line.split(":")[0] for each_line in all_lines[1:-1]]
+    assert all_labels == [
+        "PR #42  https",
+        "Mergeable",
+        "CI checks",
+        "Draft",
+        "Label done",
+        "Verdict",
+        "Add label",
+        "Re-check",
+    ]
+    assert all_lines[-1] == "A PR is done only when every line above is clean."
+
+
+def test_should_say_not_done_and_name_the_conflict_fix() -> None:
+    conflicted = {**_CLEAN_PR_OBJECT, "mergeable": "CONFLICTING", "mergeStateStatus": "DIRTY"}
+
+    context = pr_done_reminder.build_reminder_context(conflicted)
+
+    assert "NOT DONE" in context
+    assert "CONFLICTS with the base branch" in context
+    assert "gh pr view 42 --json mergeable" in context
+    assert "gh pr edit 42 --add-label" not in context
+
+
+def test_should_count_failing_and_pending_checks() -> None:
+    mixed_checks = {
+        **_CLEAN_PR_OBJECT,
+        "statusCheckRollup": [
+            {"name": "pytest", "status": "COMPLETED", "conclusion": "FAILURE"},
+            {"name": "mypy", "status": "IN_PROGRESS", "conclusion": ""},
+            {"context": "lint", "state": "PENDING"},
+            {"context": "docs", "state": "SUCCESS"},
+        ],
+    }
+
+    context = pr_done_reminder.build_reminder_context(mixed_checks)
+
+    assert "1 failing" in context
+    assert "2 pending" in context
+    assert "4 total" in context
+    assert "NOT DONE" in context
+
+
+def test_should_tell_the_agent_to_wait_when_github_is_still_computing() -> None:
+    unknown = {**_CLEAN_PR_OBJECT, "mergeable": "UNKNOWN", "mergeStateStatus": "UNKNOWN"}
+
+    context = pr_done_reminder.build_reminder_context(unknown)
+
+    assert "still computing" in context
+    assert "NOT DONE" in context
+
+
+def test_should_report_the_done_label_when_already_set() -> None:
+    labeled = {**_CLEAN_PR_OBJECT, "labels": [{"name": "done"}]}
+
+    context = pr_done_reminder.build_reminder_context(labeled)
+
+    assert "Label done:  set" in context
+
+
+def test_main_should_emit_additional_context_after_a_successful_push(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    stdout_text = _run_main(monkeypatch, capsys, _payload("git push"), _fake_gh(_CLEAN_PR_OBJECT))
+
+    payload = json.loads(stdout_text)
+    assert payload["hookSpecificOutput"]["hookEventName"] == "PostToolUse"
+    assert "permissionDecision" not in payload["hookSpecificOutput"]
+    assert "decision" not in payload
+    assert "PR #42" in _additional_context(stdout_text)
+
+
+def test_main_should_also_serve_the_powershell_tool(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    payload = json.loads(_payload("git push"))
+    payload["tool_name"] = "PowerShell"
+
+    stdout_text = _run_main(monkeypatch, capsys, json.dumps(payload), _fake_gh(_CLEAN_PR_OBJECT))
+
+    assert "PR #42" in _additional_context(stdout_text)
+
+
+def test_main_should_stay_quiet_when_the_push_failed(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    failed_push = _payload("git push", "Error: Exit code 1\nrejected")
+
+    assert _run_main(monkeypatch, capsys, failed_push, _fake_gh(_CLEAN_PR_OBJECT)) == ""
+
+
+def test_main_should_stay_quiet_for_a_non_trigger_command(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    assert _run_main(monkeypatch, capsys, _payload("git status"), _fake_gh(_CLEAN_PR_OBJECT)) == ""
+
+
+def test_main_should_remind_to_open_a_pr_when_the_branch_has_none(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    no_pr = _fake_gh(None, stderr='no pull requests found for branch "feat/x"')
+
+    context = _additional_context(_run_main(monkeypatch, capsys, _payload("git push"), no_pr))
+
+    assert "No open pull request found" in context
+    assert "gh pr create --draft" in context
+
+
+def test_main_should_stay_quiet_on_any_other_gh_failure(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    gh_down = _fake_gh(None, stderr="error connecting to api.github.com")
+
+    assert _run_main(monkeypatch, capsys, _payload("git push"), gh_down) == ""

package/hooks/blocking/bash_post_call_dispatcher.py

@@ -14,9 +14,11 @@ collision, and needs no change to that shared, out-of-scope test file.
 Reads the tool payload from stdin once, selects the hosted hooks applicable to
 the payload's tool name, and runs each one in-process via the shared
 hosted-hook runner. A hosted PostToolUse hook here carries no permission
-decision -- it is a side-effecting observer, not a gate -- so this dispatcher
-runs the whole roster unconditionally and emits nothing itself, matching every
-hosted hook's own empty-stdout contract.
+decision -- it is an observer, not a gate -- so this dispatcher runs the whole
+roster unconditionally and never blocks. The one thing it forwards is context:
+a hosted hook may print a ``hookSpecificOutput.additionalContext`` string (the
+PR done reminder does), and the dispatcher joins every such string into one
+PostToolUse payload. A hook that prints nothing adds nothing.
 
 A single hosted hook crash fails open: ``run_hook_capturing_output`` isolates
 it, so it contributes nothing and does not stop the remaining hosted hooks.
@@ -27,11 +29,17 @@ imports load once into this process rather than once per hook.
 
 from __future__ import annotations
 
+import json
+import sys
 
 import _path_setup  # noqa: F401
 
 from hooks_constants.bash_post_call_dispatcher_constants import (
+    ADDITIONAL_CONTEXT_JOIN_SEPARATOR,
+    ADDITIONAL_CONTEXT_KEY,
     ALL_BASH_POST_TOOL_USE_HOSTED_HOOK_ENTRIES,
+    HOOK_SPECIFIC_OUTPUT_KEY,
+    POST_TOOL_USE_HOOK_EVENT_NAME,
 )
 from hooks_constants.bash_pre_tool_use_dispatcher_constants import BashHostedHookEntry
 from hooks_constants.hosted_hook_runner import (
@@ -50,15 +58,54 @@ def select_applicable_entries(tool_name: str) -> list[BashHostedHookEntry]:
     ]
 
 
+def additional_context_from_hook_output(captured_stdout: str) -> str | None:
+    """Return the additionalContext string a hosted hook printed, or None.
+
+    Empty output, non-JSON output, and JSON without a non-empty
+    ``hookSpecificOutput.additionalContext`` string all return None.
+    """
+    if not captured_stdout.strip():
+        return None
+    try:
+        hook_output = json.loads(captured_stdout)
+    except json.JSONDecodeError:
+        return None
+    if not isinstance(hook_output, dict):
+        return None
+    hook_specific_output = hook_output.get(HOOK_SPECIFIC_OUTPUT_KEY)
+    if not isinstance(hook_specific_output, dict):
+        return None
+    additional_context = hook_specific_output.get(ADDITIONAL_CONTEXT_KEY)
+    if not isinstance(additional_context, str) or not additional_context.strip():
+        return None
+    return additional_context
+
+
 def dispatch(payload_text: str, tool_name: str) -> None:
-    """Run every hosted hook applicable to tool_name, in registration order.
+    """Run every hosted hook applicable to tool_name, then forward their context.
 
     Each hosted hook's crash is isolated by ``run_hook_capturing_output``, so
-    one hook failing never stops a later one in the same roster.
+    one hook failing never stops a later one in the same roster. Every
+    additionalContext string the hooks printed is joined into one PostToolUse
+    payload on stdout; when no hook printed one, nothing is written.
     """
+    all_additional_context: list[str] = []
     for each_entry in select_applicable_entries(tool_name):
         script_path = resolved_hook_script_path(each_entry.script_relative_path)
-        run_hook_capturing_output(script_path, payload_text)
+        hook_run = run_hook_capturing_output(script_path, payload_text)
+        additional_context = additional_context_from_hook_output(hook_run.captured_stdout)
+        if additional_context is not None:
+            all_additional_context.append(additional_context)
+    if not all_additional_context:
+        return
+    payload = {
+        HOOK_SPECIFIC_OUTPUT_KEY: {
+            "hookEventName": POST_TOOL_USE_HOOK_EVENT_NAME,
+            ADDITIONAL_CONTEXT_KEY: ADDITIONAL_CONTEXT_JOIN_SEPARATOR.join(all_additional_context),
+        }
+    }
+    sys.stdout.write(json.dumps(payload))
+    sys.stdout.flush()
 
 
 def main() -> None: