claude-dev-env 8.78.3 → 8.80.0

package/hooks/features/bash-dispatchers.md

@@ -8,6 +8,7 @@ This family rewrites a Git Bash command when path conversion would change a revi
 - `blocking/msys_rev_path_rewriter.py` adds a narrow `MSYS2_ARG_CONV_EXCL` prefix for affected revision and path tokens.
 - `blocking/headless_claude_broker_gate.py` denies a headless `claude -p` or `claude --print` call and names the broker command to run instead.
 - `blocking/gh_global_account_switch_gate.py` denies `gh auth switch`, `gh auth login`, and `gh auth logout` and names the per-command `GH_TOKEN` form to run instead.
+- `blocking/cloud_graphql_gate.py` denies the `gh` commands that call GraphQL (`gh api graphql` with any flags before the endpoint, `gh pr`, `gh issue`, `gh project` and `gh discussion` except `gh pr diff` and `gh pr list --web`, `gh status`, `gh org list`, `gh release list`, `gh release view` with a tag, `gh workflow run` without `--ref`, and a few `repo`, `label`, `search`, `ruleset` and `gist` commands, read past `if`, `!` and command substitutions) and an HTTP client or `python -c` style call to `api.github.com/graphql`, with or without a port, inside a cloud session, where the proxy answers GraphQL with HTTP 403, and names the REST routes to run instead.
 - `blocking/bash_post_call_dispatcher.py` runs hosted observers and joins their context output without blocking the call.
 - `advisory/pr_done_reminder.py` adds a pull request checklist after a successful push or pull request creation.
 
@@ -17,6 +18,7 @@ This family rewrites a Git Bash command when path conversion would change a revi
 - `blocking/msys_rev_path_rewriter.py` runs inside that dispatcher on `PreToolUse`, matcher `Bash`, timeout `60` seconds. `ALL_BASH_HOSTED_HOOK_ENTRIES` selects the `Bash` tool.
 - `blocking/headless_claude_broker_gate.py` runs inside that dispatcher on `PreToolUse`, matcher `Bash`, timeout `60` seconds, for the Bash and PowerShell tools.
 - `blocking/gh_global_account_switch_gate.py` runs inside that dispatcher on `PreToolUse`, matcher `Bash`, timeout `60` seconds, for the Bash and PowerShell tools.
+- `blocking/cloud_graphql_gate.py` runs inside that dispatcher on `PreToolUse`, matcher `Bash`, timeout `60` seconds, for the Bash and PowerShell tools, when `CLAUDE_CODE_REMOTE` is `true`.
 - `blocking/bash_post_call_dispatcher.py` runs on `PostToolUse`, matcher `Bash|PowerShell`, timeout `60` seconds in `hooks.json`.
 - `advisory/pr_done_reminder.py` runs inside that dispatcher on `PostToolUse`, matcher `Bash|PowerShell`, timeout `60` seconds. `ALL_BASH_POST_TOOL_USE_HOSTED_HOOK_ENTRIES` selects `Bash` and `PowerShell`.
 
@@ -29,6 +31,7 @@ Preconditions:
 - **Pre-call dispatch.** Input is a clean Bash command. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_bash_pre_tool_use_dispatcher.py -q`. The adjacent test observes the combined decision and hosted precedence.
 - **Revision rewrite.** Input is a Git command with `origin/main:.claude/settings.json`. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_msys_rev_path_rewriter.py -q`. The adjacent test observes the `origin/main:` exclusion prefix.
 - **Broker gate.** Input is a `claude -p task` command. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_headless_claude_broker_gate.py -q`. The adjacent test observes a denial that names the broker command.
+- **Cloud GraphQL gate.** Input is a `gh api graphql` command with `CLAUDE_CODE_REMOTE=true`. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_cloud_graphql_gate.py -q`. The adjacent test observes a denial that names the REST routes, and silence outside a cloud session.
 - **Post-call dispatch.** Input is a Bash call that yields hosted context. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_bash_post_call_dispatcher.py -q`. The adjacent test observes a joined context payload and exit code zero.
 - **Pull request reminder.** Input is a completed push or pull request creation. Run `python -m pytest packages/claude-dev-env/hooks/advisory/test_pr_done_reminder.py -q`. The adjacent test checks the reminder trigger and checklist verdict.
 

package/hooks/features/conduct-gates.md

@@ -12,7 +12,8 @@ This family stops a chat reply, edited message, or tool call when its payload br
 - `blocking/step_note_gate.py` requires a status line before a tool call while its opt-in flag is on.
 - `blocking/verify_before_acting.py` blocks a completed mutating call when the agent's reasoning contains an unchecked claim.
 - `blocking/pr_lifecycle_skill_gate.py` denies a commit, push, pull request action, or merge until the `pr-lifecycle` skill appears in the transcript since the last compaction.
-- `blocking/merge_review_gate.py` denies an agent's merge until a review pass on the merged head reported zero findings. It reads the receipt `scripts/merge_review_receipt.py` writes, requires the merge, auto-merge or merge-queue entry to be pinned to that head, and skips repositories listed in `CLAUDE_MERGE_REVIEW_EXEMPT_REPOSITORIES`. Its deny reason names the review command `CLAUDE_MERGE_REVIEW_COMMAND` sets.
+- `blocking/merge_review_gate.py` denies an agent's merge until a review pass on the merged head reported zero findings, or ruled out every finding and linked the posted rulings. It reads the receipt `scripts/merge_review_receipt.py` writes, requires the merge, auto-merge or merge-queue entry to be pinned to that head, and skips repositories listed in `CLAUDE_MERGE_REVIEW_EXEMPT_REPOSITORIES`. Its deny reason names the review command `CLAUDE_MERGE_REVIEW_COMMAND` sets.
+- `blocking/merge_over_review_offer_gate.py` denies a decision card or question that offers a merge while it names open review findings, a red check, unaddressed review comments, or an override. It reads the whole card as one text: every question, header, context, reason, and option, whether the option is a string or a label with a consequence or description.
 - `blocking/artifact_dark_mode_gate.py` denies an Artifact page publish when the page, inside the publish wrapper, keeps a light body or shows text under 4.5:1 contrast in dark mode. `blocking/artifact_dark_mode_render.cjs` renders the page in headless Chromium for it.
 
 ## When it fires
@@ -26,6 +27,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
 - `blocking/verify_before_acting.py` runs on `PostToolUse`, matcher `Write|Edit|MultiEdit|NotebookEdit|Agent|Task|apply_patch|Bash|PowerShell|mcp__.*`, timeout `10` seconds in `hooks.json`.
 - `blocking/pr_lifecycle_skill_gate.py` runs on `PreToolUse`, matcher `Bash|PowerShell|mcp__.*__(create_pull_request|merge_pull_request|enable_pr_auto_merge|update_pull_request|actions_run_trigger)`, timeout `10` seconds in `hooks.json`.
 - `blocking/merge_review_gate.py` runs on `PreToolUse`, matcher `Bash|PowerShell|mcp__.*__(merge_pull_request|enable_pr_auto_merge)`, timeout `10` seconds in `hooks.json`.
+- `blocking/merge_over_review_offer_gate.py` runs on `PreToolUse`, matcher `AskUserQuestion|mcp__.*__ask_decision`, timeout `10` seconds in `hooks.json`.
 - `blocking/artifact_dark_mode_gate.py` runs on `PreToolUse`, matcher `Artifact`, timeout `60` seconds in `hooks.json`.
 
 ## Proving it
@@ -43,6 +45,7 @@ Preconditions:
 - **Checked claim.** Input is a Write after hedged reasoning in the transcript. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_verify_before_acting.py -q`. The adjacent test observes a block and a logged blocked outcome.
 - **Lifecycle skill.** Input is a `git commit` or `gh pr create` command with no `pr-lifecycle` invocation in the transcript. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_pr_lifecycle_skill_gate.py -q`. The adjacent test observes a denial, then a silent allow once the skill or its slash command appears.
 - **Clean review.** Input is a merge with no receipt, a receipt with findings, a merge pinned to a newer head, an unpinned merge, or auto-merge with no head. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_merge_review_gate.py -q`. The adjacent test observes a denial for each; a merge or auto-merge pinned to the clean head and a merge in an exempt repository pass.
+- **Merge offer.** Input is a decision card or AskUserQuestion that offers "Merge now", the merge queue, or a yes to "Merge it now?" while any part of the card names open findings or unaddressed review comments. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_merge_over_review_offer_gate.py -q`. The adjacent test observes a denial for each, including an offer and findings in separate questions; a card with no merge offer, a card about the merge review check itself, a card about shipping a docs change, and a merge offer after a clean review pass.
 - **Dark mode page.** Input is an Artifact publish of a page that themes `html` but leaves `body` to the publish wrapper. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_artifact_dark_mode_gate.py -q`. The adjacent test observes a denial that names the text and its contrast; a page that themes `body` passes. The render tests skip on a host with no Node Playwright and Chromium.
 
 ## Gotchas
@@ -54,4 +57,4 @@ Preconditions:
 - 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.
 - The dark mode gate denies a page publish when Node, Playwright or Chromium is missing, and its reason names the install command. It checks both dark signals, `prefers-color-scheme: dark` and `data-theme="dark"` on the root element.
-- The clean-review gate trusts the receipt. A receipt the agent writes by hand with zero findings passes, so the pr-lifecycle skill names the review loop that writes it. A `gh pr merge` that names no repository is denied, because the gate cannot tell which repository the current branch belongs to.
+- The clean-review gate trusts the receipt. A receipt the agent writes by hand with zero findings, or with every finding ruled out and a rulings link, passes, so the pr-lifecycle skill names the review loop that writes it. A `gh pr merge` that names no repository is denied, because the gate cannot tell which repository the current branch belongs to.

package/hooks/hooks.json

@@ -164,6 +164,16 @@
           }
         ]
       },
+      {
+        "matcher": "AskUserQuestion|mcp__.*__ask_decision",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/merge_over_review_offer_gate.py",
+            "timeout": 10
+          }
+        ]
+      },
       {
         "matcher": "mcp__.*__(add_issue_comment|issue_write|update_issue_comment)",
         "hooks": [

package/hooks/hooks_constants/bash_pre_tool_use_dispatcher_constants.py

@@ -75,4 +75,8 @@ ALL_BASH_HOSTED_HOOK_ENTRIES: tuple[BashHostedHookEntry, ...] = (
         applicable_tool_names=ALL_BASH_AND_POWERSHELL_TOOL_NAMES,
         replaced_by_plugin_name=SHELL_GUARDS_PLUGIN_NAME,
     ),
+    BashHostedHookEntry(
+        script_relative_path="blocking/cloud_graphql_gate.py",
+        applicable_tool_names=ALL_BASH_AND_POWERSHELL_TOOL_NAMES,
+    ),
 )

package/hooks/hooks_constants/cloud_graphql_gate_constants.py

@@ -0,0 +1,116 @@
+"""Constants for the gate that stops cloud sessions from calling GitHub GraphQL.
+
+Holds the ``gh`` commands that call GraphQL, the ``gh`` subcommands inside
+those groups that call REST, the options that keep a GraphQL command on REST,
+the commands that call GraphQL only with an operand or only with certain
+options, the help flags that reach no network, the HTTP client and script
+interpreter programs and the GraphQL endpoint pattern they could name, the
+hook name the block log records, and the deny message that names the REST
+routes to run instead.
+"""
+
+from __future__ import annotations
+
+import re
+
+__all__ = [
+    "GH_PROGRAM_NAME",
+    "GH_API_SUBCOMMAND",
+    "GH_GRAPHQL_ENDPOINT",
+    "GH_ENDPOINT_PATH_SEPARATOR",
+    "GH_COMMAND_PATH_LENGTH",
+    "ALL_GH_GRAPHQL_COMMAND_GROUPS",
+    "ALL_GH_REST_COMMAND_PATHS_IN_GRAPHQL_GROUPS",
+    "ALL_GH_GRAPHQL_COMMAND_PATHS",
+    "ALL_GH_HELP_FLAGS",
+    "ALL_GH_REST_OPTIONS_BY_COMMAND_PATH",
+    "ALL_GH_COMMAND_PATHS_CALLING_GRAPHQL_WITH_AN_OPERAND",
+    "ALL_GH_GRAPHQL_OPTIONS_BY_COMMAND_PATH",
+    "ALL_HTTP_CLIENT_PROGRAM_NAMES",
+    "ALL_SCRIPT_INTERPRETER_PROGRAM_NAMES",
+    "GITHUB_GRAPHQL_ENDPOINT_PATTERN",
+    "GATE_HOOK_NAME",
+    "CLOUD_GRAPHQL_DENY_REASON",
+]
+
+GH_PROGRAM_NAME: str = "gh"
+GH_API_SUBCOMMAND: str = "api"
+GH_GRAPHQL_ENDPOINT: str = "graphql"
+GH_ENDPOINT_PATH_SEPARATOR: str = "/"
+GH_COMMAND_PATH_LENGTH: int = 2
+ALL_GH_GRAPHQL_COMMAND_GROUPS: frozenset[str] = frozenset({"pr", "issue", "project", "discussion"})
+ALL_GH_REST_COMMAND_PATHS_IN_GRAPHQL_GROUPS: frozenset[tuple[str, ...]] = frozenset(
+    {("pr", "diff")}
+)
+ALL_GH_GRAPHQL_COMMAND_PATHS: frozenset[tuple[str, ...]] = frozenset(
+    {
+        ("status",),
+        ("org", "list"),
+        ("repo", "view"),
+        ("repo", "clone"),
+        ("repo", "list"),
+        ("repo", "archive"),
+        ("repo", "unarchive"),
+        ("label", "list"),
+        ("search", "prs"),
+        ("search", "issues"),
+        ("ruleset", "list"),
+        ("gist", "list"),
+        ("release", "list"),
+        ("workflow", "run"),
+        ("repo", "sync"),
+    }
+)
+ALL_GH_HELP_FLAGS: frozenset[str] = frozenset({"--help", "-h"})
+ALL_GH_REST_OPTIONS_BY_COMMAND_PATH: dict[tuple[str, ...], frozenset[str]] = {
+    ("pr", "list"): frozenset({"--web", "-w"}),
+    ("workflow", "run"): frozenset({"--ref", "-r"}),
+    ("repo", "sync"): frozenset({"--branch", "-b"}),
+}
+ALL_GH_GRAPHQL_OPTIONS_BY_COMMAND_PATH: dict[tuple[str, ...], frozenset[str]] = {
+    ("repo", "create"): frozenset({"--template", "-p"}),
+    ("repo", "edit"): frozenset(
+        {
+            "--enable-advanced-security",
+            "--enable-secret-scanning",
+            "--enable-secret-scanning-push-protection",
+        }
+    ),
+}
+ALL_GH_COMMAND_PATHS_CALLING_GRAPHQL_WITH_AN_OPERAND: frozenset[tuple[str, ...]] = frozenset(
+    {("release", "view")}
+)
+ALL_HTTP_CLIENT_PROGRAM_NAMES: frozenset[str] = frozenset(
+    {"curl", "wget", "http", "https", "invoke-restmethod", "invoke-webrequest", "irm", "iwr"}
+)
+ALL_SCRIPT_INTERPRETER_PROGRAM_NAMES: frozenset[str] = frozenset(
+    {"node", "deno", "bun", "ruby", "perl", "php"}
+)
+GITHUB_GRAPHQL_ENDPOINT_PATTERN: re.Pattern[str] = re.compile(
+    r"api\.github\.com(?::\d+)?/graphql", re.IGNORECASE
+)
+GATE_HOOK_NAME: str = "cloud_graphql_gate.py"
+CLOUD_GRAPHQL_DENY_REASON: str = (
+    "BLOCKED: the Claude Code cloud proxy answers every GitHub GraphQL request with "
+    "HTTP 403, whatever the token. gh api graphql calls it, and so do gh pr and gh issue "
+    "(all but gh pr diff and gh pr list --web), gh project, gh discussion, gh status, "
+    "gh org list, gh repo view/clone/list/archive/unarchive, gh label list, "
+    "gh search prs/issues, gh ruleset list, gh gist list, gh release list, "
+    "gh release view with a tag, gh workflow run without --ref, gh repo sync without "
+    "--branch, gh repo create --template, and gh repo edit with a security setting. "
+    "Use REST through gh api repos/{owner}/{repo}/... or the mcp__github__ tools. "
+    "Open a PR: mcp__github__create_pull_request, or gh api repos/{owner}/{repo}/pulls "
+    "--input pr.json with title, head, base, body and draft in the JSON. "
+    "Read a PR: gh api repos/{owner}/{repo}/pulls/{n}. "
+    "Checks: gh api repos/{owner}/{repo}/commits/{sha}/check-runs. "
+    "Issues: gh api repos/{owner}/{repo}/issues/{n}. "
+    "Clone: git clone https://github.com/{owner}/{repo}. "
+    "Review threads: GET /repos/{owner}/{repo}/pulls/{n}/ccr/review_threads. "
+    "Resolve a thread: POST /repos/{owner}/{repo}/pulls/{n}/ccr/comments/{comment_id}/resolve "
+    "(or /unresolve). "
+    "Auto-merge: PUT or DELETE /repos/{owner}/{repo}/pulls/{n}/ccr/auto_merge. "
+    "Draft state: POST /repos/{owner}/{repo}/pulls/{n}/ccr/ready_for_review "
+    "or /ccr/convert_to_draft. "
+    "A query with no REST route cannot run in this session; it needs a machine outside "
+    "the cloud proxy."
+)

package/hooks/hooks_constants/cloud_session.py

@@ -0,0 +1,17 @@
+"""Tell a hook whether it runs inside a Claude Code cloud session."""
+
+from __future__ import annotations
+
+import os
+
+from hooks_constants.cloud_session_constants import (
+    CLOUD_SESSION_ENV_TRUE_VALUE,
+    CLOUD_SESSION_ENV_VAR,
+)
+
+__all__ = ["is_cloud_session"]
+
+
+def is_cloud_session() -> bool:
+    """Return True when ``CLAUDE_CODE_REMOTE`` is ``true``, whatever its case or padding."""
+    return os.environ.get(CLOUD_SESSION_ENV_VAR, "").strip().lower() == CLOUD_SESSION_ENV_TRUE_VALUE

package/hooks/hooks_constants/cloud_session_constants.py

@@ -0,0 +1,11 @@
+"""Names the environment variable and value a Claude Code cloud session sets."""
+
+from __future__ import annotations
+
+__all__ = [
+    "CLOUD_SESSION_ENV_VAR",
+    "CLOUD_SESSION_ENV_TRUE_VALUE",
+]
+
+CLOUD_SESSION_ENV_VAR: str = "CLAUDE_CODE_REMOTE"
+CLOUD_SESSION_ENV_TRUE_VALUE: str = "true"

package/hooks/hooks_constants/gh_command_words.py

@@ -0,0 +1,52 @@
+"""Read the command words and the standalone options of a ``gh`` call.
+
+::
+
+    gh -R o/r pr list --web          words ["pr", "list"], options ["-R", "--web"]
+    gh api -X POST graphql           words ["api", "graphql"], options ["-X"]
+    gh pr merge 12 --body -h         words ["pr", "merge", "12"], options ["--body"]
+
+An option's separate value is neither a word nor an option, so a value that
+looks like a flag, such as the ``-h`` body above, reads as text.
+"""
+
+from __future__ import annotations
+
+from hooks_constants.gh_command_words_constants import (
+    ALL_GH_OPTIONS_WITH_A_VALUE,
+    GH_OPTION_PREFIX,
+    GH_OPTION_VALUE_SEPARATOR,
+)
+
+__all__ = ["gh_command_words", "gh_command_words_and_options"]
+
+
+def gh_command_words_and_options(all_arguments: list[str]) -> tuple[list[str], list[str]]:
+    """Return the command words and the option names in one pass.
+
+    Each option's separate value is skipped, and an option name drops any
+    ``=value`` part.
+
+    Args:
+        all_arguments: The tokens after the ``gh`` program name.
+    """
+    all_command_words: list[str] = []
+    all_option_names: list[str] = []
+    is_option_value = False
+    for each_argument in all_arguments:
+        is_option = not is_option_value and each_argument.startswith(GH_OPTION_PREFIX)
+        if is_option:
+            all_option_names.append(each_argument.split(GH_OPTION_VALUE_SEPARATOR, 1)[0])
+        if not is_option and not is_option_value:
+            all_command_words.append(each_argument)
+        is_option_value = is_option and each_argument in ALL_GH_OPTIONS_WITH_A_VALUE
+    return all_command_words, all_option_names
+
+
+def gh_command_words(all_arguments: list[str]) -> list[str]:
+    """Return the gh arguments that are neither an option nor an option's separate value.
+
+    Args:
+        all_arguments: The tokens after the ``gh`` program name.
+    """
+    return gh_command_words_and_options(all_arguments)[0]

package/hooks/hooks_constants/gh_command_words_constants.py

@@ -0,0 +1,64 @@
+"""Names the ``gh`` options that take a separate value, and the option prefix and value separator.
+
+A reader of a ``gh`` command skips the token after each of these options, so
+``gh -R o/r pr list`` reads as ``pr list`` and ``gh pr merge 12 --body -h``
+reads ``-h`` as the body text. ``-f``, ``-F``, ``-H``, ``-p`` and ``-t`` take a value in
+``gh api``, ``gh workflow run`` and ``gh pr create`` alike.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "ALL_GH_OPTIONS_WITH_A_VALUE",
+    "GH_OPTION_PREFIX",
+    "GH_OPTION_VALUE_SEPARATOR",
+]
+
+ALL_GH_OPTIONS_WITH_A_VALUE: frozenset[str] = frozenset(
+    {
+        "-R",
+        "--repo",
+        "--hostname",
+        "--config",
+        "-H",
+        "--header",
+        "--head",
+        "-X",
+        "--method",
+        "-F",
+        "--field",
+        "--body-file",
+        "-f",
+        "--raw-field",
+        "--input",
+        "-q",
+        "--jq",
+        "-t",
+        "--template",
+        "-p",
+        "--preview",
+        "--title",
+        "--cache",
+        "--json",
+        "-b",
+        "--body",
+        "-B",
+        "--base",
+        "-S",
+        "--search",
+        "-L",
+        "--limit",
+        "-s",
+        "--state",
+        "-l",
+        "--label",
+        "-a",
+        "--assignee",
+        "-A",
+        "--author",
+        "-m",
+        "--milestone",
+    }
+)
+GH_OPTION_PREFIX: str = "-"
+GH_OPTION_VALUE_SEPARATOR: str = "="

package/hooks/hooks_constants/headless_claude_broker_gate_constants.py

@@ -3,9 +3,7 @@
 Holds the Claude program name and its profile-launcher prefix, the Windows
 launcher suffixes stripped before the name check, the two print-mode flags, the
 hook name the block log records, and the deny message that names the broker
-command to run instead. It also names the environment variable a Claude Code
-cloud session sets, where the gate stands aside because the session has one
-account.
+command to run instead.
 """
 
 from __future__ import annotations
@@ -18,8 +16,6 @@ __all__ = [
     "PRINT_MODE_LONG_FLAG_WITH_VALUE_PREFIX",
     "GATE_HOOK_NAME",
     "BROKER_COMMAND_DENY_REASON",
-    "CLOUD_SESSION_ENV_VAR",
-    "CLOUD_SESSION_ENV_TRUE_VALUE",
 ]
 
 CLAUDE_PROGRAM_NAME: str = "claude"
@@ -28,8 +24,6 @@ ALL_WINDOWS_LAUNCHER_SUFFIXES: tuple[str, ...] = (".cmd", ".exe", ".ps1", ".bat"
 ALL_PRINT_MODE_FLAGS: frozenset[str] = frozenset({"-p", "--print"})
 PRINT_MODE_LONG_FLAG_WITH_VALUE_PREFIX: str = "--print="
 GATE_HOOK_NAME: str = "headless_claude_broker_gate.py"
-CLOUD_SESSION_ENV_VAR: str = "CLAUDE_CODE_REMOTE"
-CLOUD_SESSION_ENV_TRUE_VALUE: str = "true"
 BROKER_COMMAND_DENY_REASON: str = (
     "BLOCKED: Start a headless Claude session through the account broker. "
     "Run: python \"$HOME/.claude/scripts/account_broker.py\" run --product claude "

package/hooks/hooks_constants/hook_block_logger.py

@@ -1,15 +1,30 @@
 """Shared fail-safe logger for hook block events.
 
 Every blocking hook calls log_hook_block at the moment it decides to block,
-so the user has a single log showing what tripped and why.
+so the user has a single log showing what tripped and why. A GitHub token or
+an Authorization header value in the preview is replaced before it is written.
 """
 
 import datetime
 import json
+import re
 from pathlib import Path
 
 _HOOK_BLOCKS_LOG_RELATIVE_PATH = ".claude/logs/hook-blocks.log"
 _MAX_PREVIEW_LENGTH = 500
+_REDACTION_MARKER = "[REDACTED]"
+_GITHUB_TOKEN_PATTERN = re.compile(r"\b(?:gh[pousr]_|github_pat_)[A-Za-z0-9_]+")
+_AUTHORIZATION_VALUE_PATTERN = re.compile(
+    r"(?P<header>authorization['\"]?\s*:\s*['\"]?)[^'\"\r\n]+", re.IGNORECASE
+)
+
+
+def _preview_without_secrets(offending_input_preview: str) -> str:
+    """Return the preview with GitHub tokens and Authorization header values replaced."""
+    without_tokens = _GITHUB_TOKEN_PATTERN.sub(_REDACTION_MARKER, offending_input_preview)
+    return _AUTHORIZATION_VALUE_PATTERN.sub(
+        lambda each_match: each_match.group("header") + _REDACTION_MARKER, without_tokens
+    )
 
 
 def log_hook_block(
@@ -31,7 +46,8 @@ def log_hook_block(
         block_reason: The human-readable reason the hook is blocking.
         tool_name: The Claude tool name when available, e.g. ``Bash``.
         offending_input_preview: A short excerpt of the input that triggered
-            the block; truncated to 500 characters before writing.
+            the block; secrets are replaced, then it is truncated to 500
+            characters before writing.
     """
     try:
         home_directory = Path.home()
@@ -51,7 +67,9 @@ def log_hook_block(
         if tool_name is not None:
             log_record["tool"] = tool_name
         if offending_input_preview is not None:
-            log_record["preview"] = offending_input_preview[:_MAX_PREVIEW_LENGTH]
+            log_record["preview"] = _preview_without_secrets(offending_input_preview)[
+                :_MAX_PREVIEW_LENGTH
+            ]
 
         with log_path.open("a", encoding="utf-8") as log_file:
             log_file.write(json.dumps(log_record) + "\n")

package/hooks/hooks_constants/merge_over_review_offer_gate_constants.py

@@ -0,0 +1,34 @@
+"""Constants for the gate that keeps merge-over-review offers off decision cards."""
+
+import re
+
+TOOL_INPUT_KEY = "tool_input"
+HOOK_EVENT_NAME = "PreToolUse"
+DENY_DECISION = "deny"
+PERMISSION_DECISION_REASON_KEY = "permissionDecisionReason"
+ALL_CARD_TEXT_FIELDS = ("question", "header", "context", "reason")
+QUESTIONS_FIELD = "questions"
+OPTIONS_FIELD = "options"
+TEXT_SEPARATOR = " "
+ALL_OPTION_TEXT_FIELDS = ("label", "consequence", "description")
+MERGE_OFFER_PATTERN = re.compile(
+    r"\b(?:merg(?:e|es|ing)|squash(?:es|ing)?|auto-merge)\b"
+    r"(?!\s+(?:review|check|base|conflicts?|state|status|gate)\b)",
+    re.IGNORECASE,
+)
+CLEAN_REVIEW_PATTERN = re.compile(
+    r"\b(?:no|zero|0)\s+(?:open\s+|review\s+|blocking\s+)?(?:findings?|failures?|threads?|comments?)\b",
+    re.IGNORECASE,
+)
+OPEN_REVIEW_PATTERN = re.compile(
+    r"\b(?:findings?|override|red|failing|failed|failures?|not clean|unresolved|unaddressed"
+    r"|changes requested|review comments?|open (?:review )?threads?|issues? (?:left|remain(?:ing)?)"
+    r"|\d+ remaining)\b",
+    re.IGNORECASE,
+)
+MERGE_OVER_REVIEW_OFFER_REASON = (
+    "This card offers a merge while it names open review findings, a red check, or an"
+    " override. A pull request merges only after a review pass on its head reports zero"
+    " findings. Drop the merge offer, keep fixing and rerunning the review, and ask only"
+    " about choices that keep that bar."
+)

package/hooks/hooks_constants/merge_review_gate_constants.py

@@ -25,6 +25,10 @@ PR_NUMBER_PATTERN = re.compile(r"(?:^|\s)#?(?P<number>\d+)(?:\s|$)")
 PR_URL_PATTERN = re.compile(
     r"github\.com/(?P<owner>[\w.-]+)/(?P<repo>[\w.-]+)/pull/(?P<number>\d+)"
 )
+RULINGS_LINK_PATTERN = re.compile(
+    r"https://github\.com/(?P<owner>[\w.-]+)/(?P<repo>[\w.-]+)/pull/(?P<number>\d+)"
+    r"#issuecomment-\d+"
+)
 REPO_OPTION_PATTERN = re.compile(r"(?:-R|--repo)[\s=](?P<owner>[\w.-]+)/(?P<repo>[\w.-]+)")
 MATCH_HEAD_PATTERN = re.compile(r"--match-head-commit[\s=](?P<sha>[0-9a-fA-F]{7,40})")
 API_SHA_FIELD_PATTERN = re.compile(r"(?:-f|-F|--field|--raw-field)[\s=]sha=(?P<sha>[0-9a-fA-F]{7,40})")
@@ -43,15 +47,21 @@ RECEIPT_FILE_NAME_TEMPLATE = "{owner}__{repo}__{number}.json"
 REPOSITORY_SEPARATOR = ","
 RECEIPT_HEAD_KEY = "head"
 RECEIPT_FINDINGS_KEY = "findings"
+RECEIPT_RULED_OUT_KEY = "ruled_out"
+RECEIPT_RULINGS_KEY = "rulings"
 RECORD_COMMAND = "python3 ~/.claude/scripts/merge_review_receipt.py"
 
 NO_CLEAN_REVIEW_REASON_TEMPLATE = (
     "{slug}#{number} has no clean review on the head you are merging. Run the review "
     "loop: review the pull request head with `{review_command}`, fix and push every "
     "finding, and review again "
-    "until a pass reports zero findings. Record that pass with `"
+    "until a pass reports zero findings or every finding is ruled out with file:line "
+    "evidence. Record that pass with `"
     + RECORD_COMMAND
-    + " {slug} {number} <head sha> 0`, then merge pinned to that head."
+    + " {slug} {number} <head sha> <finding count>`, adding `--ruled-out <finding count> "
+    "--rulings <link to the rulings comment on this pull request>` when every finding is "
+    "ruled out, then merge "
+    "pinned to that head."
 )
 UNPINNED_MERGE_REASON_TEMPLATE = (
     "{slug}#{number} has a clean review for {head}, but this merge names no head. "
@@ -60,7 +70,8 @@ UNPINNED_MERGE_REASON_TEMPLATE = (
 )
 STALE_REVIEW_REASON_TEMPLATE = (
     "{slug}#{number} was reviewed clean at {head}, and this merge names {pinned}. "
-    "Review the new head until a pass reports zero findings, record it, then merge."
+    "Review the new head until a pass reports zero findings or every finding is ruled "
+    "out, record it, then merge."
 )
 AUTO_MERGE_REASON_TEMPLATE = (
     "Auto-merge on {slug}#{number} names no head, so it could merge a head no review "

package/hooks/hooks_constants/mod_handoff.py

@@ -13,10 +13,9 @@ import json
 import os
 from pathlib import Path
 
+from hooks_constants.cloud_session import is_cloud_session
 from hooks_constants.mod_handoff_constants import (
     ALL_SETTINGS_FILE_NAMES_IN_PRECEDENCE_ORDER,
-    CLOUD_SESSION_ENV_TRUE_VALUE,
-    CLOUD_SESSION_ENV_VAR,
     CLAUDE_CONFIG_DIR_ENV_VAR,
     CLAUDE_PROJECT_DIR_ENV_VAR,
     DEFAULT_CLAUDE_CONFIG_DIRECTORY_NAME,
@@ -81,7 +80,7 @@ def is_mod_plugin_enabled(plugin_name: str) -> bool:
     Args:
         plugin_name: The plugin that holds the mod replacing the calling hook.
     """
-    if os.environ.get(CLOUD_SESSION_ENV_VAR, "").strip().lower() == CLOUD_SESSION_ENV_TRUE_VALUE:
+    if is_cloud_session():
         return False
     is_enabled = False
     for each_path in all_settings_paths_in_precedence_order():

package/hooks/hooks_constants/mod_handoff_constants.py

@@ -8,8 +8,6 @@ from __future__ import annotations
 
 __all__ = [
     "ALL_SETTINGS_FILE_NAMES_IN_PRECEDENCE_ORDER",
-    "CLOUD_SESSION_ENV_TRUE_VALUE",
-    "CLOUD_SESSION_ENV_VAR",
     "CLAUDE_CONFIG_DIR_ENV_VAR",
     "CLAUDE_PROJECT_DIR_ENV_VAR",
     "DEFAULT_CLAUDE_CONFIG_DIRECTORY_NAME",
@@ -22,8 +20,6 @@ __all__ = [
 ]
 
 ENABLED_PLUGINS_SETTINGS_KEY = "enabledPlugins"
-CLOUD_SESSION_ENV_VAR = "CLAUDE_CODE_REMOTE"
-CLOUD_SESSION_ENV_TRUE_VALUE = "true"
 PLUGIN_MARKETPLACE_SEPARATOR = "@"
 SHELL_GUARDS_PLUGIN_NAME = "shell-guards"
 SESSION_PROMPTS_PLUGIN_NAME = "session-prompts"

package/hooks/hooks_constants/piped_pytest_blocker_constants.py

@@ -19,8 +19,9 @@ that consumes these program, wrapper, and option constants lives in
 ``pytest_invocation``.
 
 Two wrapper shapes reach the program behind them differently. ``sudo``,
-``uvx``, ``xargs``, ``env``, and ``timeout`` take their own options and then the
-command, and ``ALL_WRAPPER_OPTION_GRAMMARS_BY_NAME`` names each one's
+``uvx``, ``xargs``, ``env``, ``timeout``, ``command``, and ``exec`` take their own
+options and then the command, and a shell keyword such as ``if``, ``then``,
+``do``, or ``!`` runs the command after it, and ``ALL_WRAPPER_OPTION_GRAMMARS_BY_NAME`` names each one's
 value-taking options, its flag-only options, and the operands it reads before
 the command, so ``xargs -I {} rm {}`` and ``timeout --signal KILL 5 git push``
 both reach the program. ``uv``, ``poetry``, ``pipenv``, ``pdm``, ``hatch``, ``rye``, and
@@ -149,6 +150,8 @@ __all__ = [
     "WrapperOptionGrammar",
     "WINDOWS_EXECUTABLE_SUFFIX",
     "RUN_SUBCOMMAND_OPTION_GRAMMAR",
+    "SHELL_KEYWORD_OPTION_GRAMMAR",
+    "ALL_SHELL_KEYWORDS_BEFORE_A_COMMAND",
     "ALL_WRAPPER_OPTION_GRAMMARS_BY_NAME",
     "ALL_RUN_SUBCOMMAND_WRAPPER_COMMANDS",
     "RUN_SUBCOMMAND_NAME",
@@ -312,6 +315,14 @@ RUN_SUBCOMMAND_OPTION_GRAMMAR = WrapperOptionGrammar(
     all_flag_options=frozenset(),
     leading_operand_count=0,
 )
+SHELL_KEYWORD_OPTION_GRAMMAR = WrapperOptionGrammar(
+    all_value_taking_options=frozenset(),
+    all_flag_options=frozenset(),
+    leading_operand_count=0,
+)
+ALL_SHELL_KEYWORDS_BEFORE_A_COMMAND: frozenset[str] = frozenset(
+    {"if", "then", "elif", "else", "while", "until", "do", "!", "{"}
+)
 ALL_WRAPPER_OPTION_GRAMMARS_BY_NAME: dict[str, WrapperOptionGrammar] = {
     "sudo": WrapperOptionGrammar(
         all_value_taking_options=frozenset(
@@ -365,6 +376,20 @@ ALL_WRAPPER_OPTION_GRAMMARS_BY_NAME: dict[str, WrapperOptionGrammar] = {
         all_flag_options=frozenset({"-v", "--verbose", "--preserve-status", "--foreground"}),
         leading_operand_count=1,
     ),
+    "command": WrapperOptionGrammar(
+        all_value_taking_options=frozenset(),
+        all_flag_options=frozenset({"-p"}),
+        leading_operand_count=0,
+    ),
+    "exec": WrapperOptionGrammar(
+        all_value_taking_options=frozenset({"-a"}),
+        all_flag_options=frozenset({"-c", "-l"}),
+        leading_operand_count=0,
+    ),
+    **{
+        each_keyword: SHELL_KEYWORD_OPTION_GRAMMAR
+        for each_keyword in ALL_SHELL_KEYWORDS_BEFORE_A_COMMAND
+    },
 }
 ALL_RUN_SUBCOMMAND_WRAPPER_COMMANDS: frozenset[str] = frozenset(
     {

package/hooks/hooks_constants/pr_lifecycle_skill_gate_constants.py

@@ -25,7 +25,6 @@ COMMAND_SEPARATORS = ";|&\n()`"
 COMMAND_WHITESPACE = " \t\r"
 OPTION_AND_VALUE_WORD_COUNT = 2
 GIT_GLOBAL_OPTIONS_WITH_VALUE = frozenset({"-C", "-c", "--git-dir", "--work-tree", "--namespace", "--config-env"})
-GH_OPTIONS_WITH_VALUE = frozenset({"-R", "--repo", "--hostname", "--config", "-H", "--header", "-X", "--method", "-F", "--field", "-f", "--raw-field", "--input", "--jq", "-q", "--template", "-t", "--cache"})
 GIT_ACTIONS = frozenset({"commit", "push"})
 GH_PULL_REQUEST_COMMAND = "pr"
 GH_API_COMMAND = "api"