claude-dev-env 8.79.0 → 8.80.0

package/.agents/skills/pr-lifecycle/reference/review-loop-before-merge.md

@@ -4,8 +4,8 @@ A pull request the agent made merges only after a code review of its head comes
 
 1. Review the head with the command `CLAUDE_MERGE_REVIEW_COMMAND` names. Where it is unset, run `/code-review high --max-findings all` against the base.
 2. Record the pass: `python3 ~/.claude/scripts/merge_review_receipt.py <owner>/<name> <number> <head sha> <finding count>`.
-3. Fix or answer every finding, push, and review the new head.
-4. Repeat until a pass records `CLEAN`.
+3. Fix every valid finding, push, and review the new head. Answer each finding you rule out on the pull request with its file:line evidence.
+4. Repeat until a pass records `CLEAN`. A pass whose every finding is ruled out records `CLEAN` with `--ruled-out <finding count> --rulings <link to the rulings comment on this pull request>`.
 5. Merge pinned to that head: `expectedHeadSha` on the merge tool, or `--match-head-commit` on `gh pr merge`.
 
 `hooks/blocking/merge_review_gate.py` denies any other merge. In a merge-queue repository, enqueue with `gh pr merge <number> --repo <owner>/<name> --auto --match-head-commit <head sha>`; auto-merge that names no head is denied. A repository whose own CI and merge queue review and merge its pull requests is listed in `CLAUDE_MERGE_REVIEW_EXEMPT_REPOSITORIES`, comma separated as `owner/name`, and skips the gate.

package/bin/install.settings-defaults.test.mjs

@@ -5,6 +5,7 @@
 import { test } from 'node:test';
 import { strict as assert } from 'node:assert';
 import {
+    mkdirSync,
     mkdtempSync,
     rmSync,
     writeFileSync,
@@ -263,14 +264,15 @@ test('sandbox uninstall removes only package-owned permission entries and keeps
     }
 });
 
-test('package settings.json publishes the session agent, advisor model, auto-compact and auto mode defaults', () => {
+test('package settings.json publishes the session agent, advisor model, auto-compact, auto mode and idle compaction defaults', () => {
     const packageSettings = JSON.parse(readFileSync(PACKAGE_SETTINGS_PATH, 'utf8'));
     const settingsDefaults = settingsDefaultsFromPackageSettings(packageSettings);
     assert.deepEqual(
         Object.keys(settingsDefaults).sort(),
-        ['advisorModel', 'agent', 'autoCompactWindow', 'autoMode', 'modelSettings'],
+        ['advisorModel', 'agent', 'autoCompactWindow', 'autoMode', 'env', 'modelSettings'],
     );
     assert.equal(settingsDefaults.autoCompactWindow, 350000);
+    assert.deepEqual(settingsDefaults.env, { CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS: '100000' });
     assert.deepEqual(settingsDefaults.modelSettings, {
         'claude-haiku-5-5': { autoCompactWindow: 100000 },
         'claude-haiku-4-5': { autoCompactWindow: 100000 },
@@ -301,6 +303,29 @@ test('a missing default is added and a user-set value is kept', () => {
     assert.equal(userSettings.advisorModel, 'sonnet');
 });
 
+test('install adds the idle compaction variable to an env block and keeps a user value on rerun', () => {
+    const sandboxHome = mkdtempSync(join(tmpdir(), 'cde-settings-defaults-'));
+    try {
+        const settingsPath = join(sandboxHome, '.claude', 'settings.json');
+        mkdirSync(join(sandboxHome, '.claude'), { recursive: true });
+        writeFileSync(settingsPath, JSON.stringify({ env: { EDITOR: 'vim' } }, null, 4) + '\n');
+        const firstRun = runInstallerInSandbox(sandboxHome);
+        assert.equal(firstRun.status, 0, firstRun.stderr);
+        assert.deepEqual(JSON.parse(readFileSync(settingsPath, 'utf8')).env, {
+            EDITOR: 'vim',
+            CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS: '100000',
+        });
+        const userChoice = JSON.parse(readFileSync(settingsPath, 'utf8'));
+        userChoice.env.CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS = '300000';
+        writeFileSync(settingsPath, JSON.stringify(userChoice, null, 4) + '\n');
+        const secondRun = runInstallerInSandbox(sandboxHome);
+        assert.equal(secondRun.status, 0, secondRun.stderr);
+        assert.equal(JSON.parse(readFileSync(settingsPath, 'utf8')).env.CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS, '300000');
+    } finally {
+        rmSync(sandboxHome, { recursive: true, force: true });
+    }
+});
+
 test('install adds advisorModel when missing and keeps a user choice on rerun', () => {
     const sandboxHome = mkdtempSync(join(tmpdir(), 'cde-settings-defaults-'));
     try {

package/bin/merge_settings_defaults.mjs

@@ -2,38 +2,57 @@
  * Merge package-owned scalar setting defaults into a settings object.
  *
  * Every top-level key in the package settings.json other than the managed
- * lists (`permissions`) is a default. Install adds a default only when the
- * user settings lack that key, so a value the user already set stays as is.
+ * lists (`permissions`) is a default. Install adds a scalar default only when
+ * the user settings lack that key, so a value the user already set stays as
+ * is. The nested keys below merge field by field instead.
  *
  * A per-model key (`modelSettings`) merges one level deeper: install adds each
  * model entry, and each field inside an entry, that the user settings lack.
+ *
+ * A per-variable key (`env`) merges one level deep. Install adds each variable
+ * the user's block lacks and keeps each variable the user already set.
  */
 
 export const MANAGED_LIST_SETTING_KEYS = Object.freeze(['permissions']);
-export const PER_MODEL_SETTING_KEYS = Object.freeze(['modelSettings']);
 
 function isPlainObject(candidate) {
     return Boolean(candidate) && typeof candidate === 'object' && !Array.isArray(candidate);
 }
 
-function mergeMissingPerModelFields(targetPerModel, defaultPerModel, settingKey) {
+function addMissingField(targetFields, fieldName, fieldDefault) {
+    if (Object.hasOwn(targetFields, fieldName)) return false;
+    targetFields[fieldName] = structuredClone(fieldDefault);
+    return true;
+}
+
+function mergeMissingFields(targetFields, defaultFields, keyPrefix) {
+    const addedKeys = [];
+    for (const [fieldName, fieldDefault] of Object.entries(defaultFields)) {
+        if (addMissingField(targetFields, fieldName, fieldDefault)) {
+            addedKeys.push(`${keyPrefix}.${fieldName}`);
+        }
+    }
+    return addedKeys;
+}
+
+function mergeMissingPerModelFields(targetPerModel, defaultPerModel, keyPrefix) {
     const addedKeys = [];
     for (const [modelName, defaultFields] of Object.entries(defaultPerModel)) {
-        if (!Object.hasOwn(targetPerModel, modelName)) {
-            targetPerModel[modelName] = { ...defaultFields };
-            addedKeys.push(`${settingKey}.${modelName}`);
+        if (addMissingField(targetPerModel, modelName, defaultFields)) {
+            addedKeys.push(`${keyPrefix}.${modelName}`);
             continue;
         }
         if (!isPlainObject(targetPerModel[modelName])) continue;
-        for (const [fieldName, fieldDefault] of Object.entries(defaultFields)) {
-            if (Object.hasOwn(targetPerModel[modelName], fieldName)) continue;
-            targetPerModel[modelName][fieldName] = fieldDefault;
-            addedKeys.push(`${settingKey}.${modelName}.${fieldName}`);
-        }
+        addedKeys.push(...mergeMissingFields(targetPerModel[modelName], defaultFields, `${keyPrefix}.${modelName}`));
     }
     return addedKeys;
 }
 
+const NESTED_MERGE_BY_SETTING_KEY = new Map([
+    ['modelSettings', mergeMissingPerModelFields],
+    ['env', mergeMissingFields],
+]);
+
 /**
  * Read the setting defaults from a package settings source object.
  *
@@ -52,7 +71,8 @@ export function settingsDefaultsFromPackageSettings(packageSettings) {
 }
 
 /**
- * Add each default whose key the target settings lack.
+ * Add each default whose key the target settings lack, and fill the missing
+ * entries and fields inside an existing `modelSettings` or `env` object.
  *
  * @param {Record<string, unknown>} targetSettings Mutated in place.
  * @param {Record<string, unknown>} settingsDefaults
@@ -61,16 +81,14 @@ export function settingsDefaultsFromPackageSettings(packageSettings) {
 export function mergeMissingSettingsDefaults(targetSettings, settingsDefaults) {
     const addedKeys = [];
     for (const [settingKey, defaultValue] of Object.entries(settingsDefaults)) {
-        const isPerModelMerge = PER_MODEL_SETTING_KEYS.includes(settingKey)
-            && isPlainObject(targetSettings[settingKey])
-            && isPlainObject(defaultValue);
-        if (isPerModelMerge) {
-            addedKeys.push(...mergeMissingPerModelFields(targetSettings[settingKey], defaultValue, settingKey));
+        const mergeNested = NESTED_MERGE_BY_SETTING_KEY.get(settingKey);
+        if (mergeNested && isPlainObject(targetSettings[settingKey]) && isPlainObject(defaultValue)) {
+            addedKeys.push(...mergeNested(targetSettings[settingKey], defaultValue, settingKey));
             continue;
         }
-        if (Object.hasOwn(targetSettings, settingKey)) continue;
-        targetSettings[settingKey] = structuredClone(defaultValue);
-        addedKeys.push(settingKey);
+        if (addMissingField(targetSettings, settingKey, defaultValue)) {
+            addedKeys.push(settingKey);
+        }
     }
     return { addedKeys };
 }

package/bin/merge_settings_defaults.test.mjs

@@ -94,3 +94,45 @@ test('mergeMissingSettingsDefaults should keep a per-model value the user alread
     );
     assert.deepEqual(targetSettings.modelSettings, { 'claude-haiku-5-5': { autoCompactWindow: 150000 } });
 });
+
+test('mergeMissingSettingsDefaults should add a missing env variable to a present env block and keep the user values', () => {
+    const targetSettings = {
+        env: { CLAUDE_MERGE_REVIEW_COMMAND: 'review', CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS: '300000' },
+    };
+
+    assert.deepEqual(
+        mergeMissingSettingsDefaults(targetSettings, {
+            env: { CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS: '100000', EDITOR: 'code' },
+        }),
+        { addedKeys: ['env.EDITOR'] },
+    );
+    assert.deepEqual(targetSettings, {
+        env: {
+            CLAUDE_MERGE_REVIEW_COMMAND: 'review',
+            CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS: '300000',
+            EDITOR: 'code',
+        },
+    });
+});
+
+test('mergeMissingSettingsDefaults should add the whole env block when the user settings have none', () => {
+    const targetSettings = {};
+
+    assert.deepEqual(
+        mergeMissingSettingsDefaults(targetSettings, { env: { CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS: '100000' } }),
+        { addedKeys: ['env'] },
+    );
+    assert.deepEqual(targetSettings, { env: { CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS: '100000' } });
+});
+
+test('mergeMissingSettingsDefaults should keep a non-object env value as the user set it', () => {
+    for (const userEnv of [null, ['CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS=300000']]) {
+        const targetSettings = { env: structuredClone(userEnv) };
+
+        assert.deepEqual(
+            mergeMissingSettingsDefaults(targetSettings, { env: { CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS: '100000' } }),
+            { addedKeys: [] },
+        );
+        assert.deepEqual(targetSettings, { env: userEnv });
+    }
+});

package/docs/account-broker.md

@@ -18,7 +18,7 @@ python scripts/account_broker.py check --product codex
 printf "%s" "prompt" | python scripts/account_broker.py run --product claude --report report.json -- claude --output-format json -p
 ```
 
-`accounts` prints the roster without reading meters. `choose` prints `decision`, `accounts`, and `state_path`. Each decision contains `action`, `account`, `profile`, `home`, `reason`, `tier`, and `resets_at`. `profile` is the name of the profile whose home the account uses, such as `editor` for a home at `~/.claude-profiles/editor`. It is null for the main account, a Codex account, a home outside the profiles root, a home whose folder name is not a valid profile name such as `main`, and a wait decision. `--spent` takes an account's name or its profile. The account order file matches the name, command, or launcher, and resume affinity stores the command, or the name for an account without one. When a mark is one account's name and another account's profile, the name wins. Every mark is read before the first one is saved, so an unreadable mark saves none. `accounts` and the `choose` account list carry the same `profile` field. A wait decision has no account or home and includes the soonest reset in UTC. A failed meter read excludes the account for that choice. `--spent` saves an exclusion until the supplied Unix reset, the account's soonest known meter reset, or one hour when neither is available. A `--spent` name absent from the roster is saved until the supplied Unix reset, or for one hour when no reset is given. A mark splits at its last colon, so an absent name that contains a colon, such as `C:\bin\old.cmd`, takes an explicit reset, such as `C:\bin\old.cmd:1800000000`. While any such mark is still in the future, `choose` waits until the soonest mark and exits 3, and with no Codex roster `--spent default` waits until that mark passes. Meter reads younger than 60 seconds are reused.
+`accounts` prints the roster without reading meters. `choose` prints `decision`, `accounts`, and `state_path`. Each decision contains `action`, `account`, `profile`, `home`, `reason`, `tier`, and `resets_at`. `profile` is the name of the profile whose home the account uses, such as `editor` for a home at `~/.claude-profiles/editor`. It is null for the main account, a Codex account, a home outside the profiles root, a home whose folder name is not a valid profile name such as `main`, and a wait decision. `--spent` takes an account's name or its profile. The account order file matches the name, command, or launcher, and resume affinity stores the command, or the name for an account without one. When a mark is one account's name and another account's profile, the name wins. Every mark is read before the first one is saved, so an unreadable mark saves none. `accounts` and the `choose` account list carry the same `profile` field. A wait decision has no account or home and includes the soonest reset in UTC. An account counts as free at the latest reset of the windows that hold it, and one hour out when one of those windows has no reset time. A failed meter read excludes the account for that choice. `--spent` saves an exclusion until the supplied Unix reset, the account's soonest known meter reset, or one hour when neither is available. A `--spent` name absent from the roster is saved until the supplied Unix reset, or for one hour when no reset is given. A mark splits at its last colon, so an absent name that contains a colon, such as `C:\bin\old.cmd`, takes an explicit reset, such as `C:\bin\old.cmd:1800000000`. While any such mark is still in the future, `choose` waits until the soonest mark and exits 3, and with no Codex roster `--spent default` waits until that mark passes. Meter reads younger than 60 seconds are reused.
 
 `check` prints nothing and exits 3 while every account is below its floor. `run` sets `CLAUDE_CONFIG_DIR` or `CODEX_HOME` for each attempt. A Claude job also starts without the parent session's variables, such as `CLAUDE_CODE_SESSION_ID` and `CLAUDECODE`, so a child started from inside a Claude Code session runs as its own session. `ALL_PARENT_CLAUDE_SESSION_VARIABLES` lists them. It replays the same stdin bytes when a usage limit or start failure leads to another account. Send the prompt on stdin. When the command resolves to a `.cmd` or `.bat` file, the broker refuses an argument that holds a cmd.exe metacharacter and records `start_failed`. It writes the command's stdout to stdout and diagnostics to stderr. A resumed Claude session uses the account bound to its session when that account has room.
 

package/docs/codex-accounts.md

@@ -12,7 +12,7 @@ A job asks the broker which account to use.
 | `scripts/account_broker.py` | `choose --product codex` names the account and tier a job runs on; `check --product codex` reports whether any account has room |
 | `scripts/codex_account_choice.py` | `sync` links the shared setup into every account's home; `setup` and `install` write one launcher per account |
 | `scripts/codex_account_meters.py` | Reads one account's rate-limit windows through `codex app-server` with `CODEX_HOME` set to that account's home |
-| `scripts/dev_env_scripts_constants/codex_account_constants.py` | The fallback account names, the roster variable and file, the launcher template, the shared entry names, the 10% bar, the 1% Luna stop, and the 20% 5-hour floor for Luna |
+| `scripts/dev_env_scripts_constants/codex_account_constants.py` | The fallback account names, the roster variable and file, the launcher template, the shared entry names, the 10% bar, the 1% Luna stop, and the 20% short-window floor for Luna |
 
 ## Names and order
 
@@ -86,16 +86,17 @@ aside.
 
 ## Which account a job uses
 
-Room is the smaller of an account's two windows: the 5-hour window and the week.
+Room is the least percent left across an account's windows, such as the 5-hour window and the week.
+A window that reports no length counts as weekly.
 
 | Condition | Answer |
 |---|---|
 | One or more accounts with more than 10% left | `normal` on the account with the most room |
 | No account over 10%, one or more over 1% | `luna` on the account with the most room |
-| An account that reports a 5-hour window, with under 20% of that window left | never takes `luna` |
+| An account that reports a window shorter than a week, such as the 5-hour window, with under 20% of that window left | never takes `luna` |
 | No account over 1% | `wait`, naming the next reset when known |
-| A meter read fails | The broker reads it once more |
-| A meter is unread after both reads | The account has `meters: null` and the failure text in `unread_reason`; a `wait` reason names the account and that text |
+| A meter read fails | The broker reads it again, up to 3 reads, waiting 1 second and then 2 seconds |
+| A meter is unread after every read | The account has `meters: null` and the failure text in `unread_reason`; a `wait` reason names the account and that text |
 
 ```
 python packages/claude-dev-env/scripts/account_broker.py choose --product codex

package/hooks/blocking/cloud_graphql_gate.py

@@ -0,0 +1,213 @@
+#!/usr/bin/env python3
+"""PreToolUse gate: keep cloud sessions from calling GitHub GraphQL.
+
+The Claude Code cloud proxy answers every request to
+``api.github.com/graphql`` with HTTP 403, an unauthenticated one included, so
+no token or setting makes the call work there. Inside a cloud session, where
+``CLAUDE_CODE_REMOTE`` is ``true``, a command segment is denied when it runs
+a ``gh`` command that calls GraphQL or points an HTTP client such as ``curl``
+at the GraphQL endpoint. The deny reason names the REST routes that do the same
+jobs. ``gh`` calls GraphQL for ``api graphql``, for every ``pr``, ``issue``,
+``project`` and ``discussion`` subcommand except ``pr diff`` and ``pr list
+--web``, and for ``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``,
+``release view`` with a tag, ``workflow run`` without ``--ref``, ``repo sync``
+without ``--branch``, ``repo create --template``, and ``repo edit`` with a
+security setting. An interactive ``repo edit`` needs a terminal, which an agent
+call lacks, so gh stops before any request. The command
+words skip options and the values of ``-R``, ``--json`` and the like, so ``gh -R o/r pr list``
+and ``gh api -X POST graphql`` read as ``pr list`` and ``api graphql``. A
+``gh`` call with ``--help`` or ``-h`` passes, because it reaches no network,
+unless the flag is the separate value of an option such as ``--body``. An HTTP client or a script
+interpreter such as ``python -c`` is denied when an argument names
+``api.github.com/graphql``, with or without a port. A URL held in a shell
+variable, or built inside a script file, is not in the command text, so the
+gate cannot see it. The programs checked for the endpoint are a fixed list, so
+another program that names it, such as ``java`` or ``dotnet``, passes and gets
+the proxy's 403. The program is read past wrappers, shell keywords such as
+``if`` and ``!``, command substitutions, ``eval``, ``Invoke-Expression``,
+``find -exec``, ``Start-Process``, PowerShell ``-EncodedCommand`` and chained
+commands. Outside a
+cloud session the gate stays quiet, because GraphQL works there. Section 7.1 of
+``docs/references/cloud-pr-loop-compatibility.md`` holds the probe or gh source
+line behind each command in the map.
+
+Hosted by ``blocking/bash_pre_tool_use_dispatcher.py`` for the Bash and
+PowerShell tools.
+"""
+
+from __future__ import annotations
+
+import json
+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,
+        DENY_DECISION,
+        HOOK_EVENT_NAME,
+    )
+    from hooks_constants.cloud_graphql_gate_constants import (
+        ALL_GH_COMMAND_PATHS_CALLING_GRAPHQL_WITH_AN_OPERAND,
+        ALL_GH_GRAPHQL_COMMAND_GROUPS,
+        ALL_GH_GRAPHQL_COMMAND_PATHS,
+        ALL_GH_GRAPHQL_OPTIONS_BY_COMMAND_PATH,
+        ALL_GH_HELP_FLAGS,
+        ALL_GH_REST_COMMAND_PATHS_IN_GRAPHQL_GROUPS,
+        ALL_GH_REST_OPTIONS_BY_COMMAND_PATH,
+        ALL_HTTP_CLIENT_PROGRAM_NAMES,
+        ALL_SCRIPT_INTERPRETER_PROGRAM_NAMES,
+        CLOUD_GRAPHQL_DENY_REASON,
+        GATE_HOOK_NAME,
+        GH_API_SUBCOMMAND,
+        GH_COMMAND_PATH_LENGTH,
+        GH_ENDPOINT_PATH_SEPARATOR,
+        GH_GRAPHQL_ENDPOINT,
+        GH_PROGRAM_NAME,
+        GITHUB_GRAPHQL_ENDPOINT_PATTERN,
+    )
+    from hooks_constants.cloud_session import is_cloud_session
+    from hooks_constants.gh_command_words import gh_command_words_and_options
+    from hooks_constants.hook_block_logger import log_hook_block
+    from hooks_constants.piped_pytest_blocker_constants import PYTHON_INTERPRETER_BASENAME_PATTERN
+    from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+    from hooks_constants.shell_command_wrappers import (
+        all_wrapped_command_segments,
+        segment_program_and_arguments,
+    )
+except ImportError as import_error:
+    raise ImportError(
+        "The cloud GraphQL gate cannot import its dependencies; "
+        "ensure the hooks directory is importable."
+    ) from import_error
+
+
+def _is_graphql_endpoint(endpoint: str) -> bool:
+    """Return True when a ``gh api`` endpoint word is ``graphql``, ``/graphql`` or the full URL."""
+    return (
+        endpoint.strip(GH_ENDPOINT_PATH_SEPARATOR).lower() == GH_GRAPHQL_ENDPOINT
+        or GITHUB_GRAPHQL_ENDPOINT_PATTERN.search(endpoint) is not None
+    )
+
+
+def _gh_arguments_call_graphql(all_arguments: list[str]) -> bool:
+    """Return True when gh, run with these arguments, sends a GraphQL request.
+
+    Args:
+        all_arguments: The tokens after the ``gh`` program name.
+    """
+    all_command_words, all_option_names = gh_command_words_and_options(all_arguments)
+    if any(each_option in ALL_GH_HELP_FLAGS for each_option in all_option_names):
+        return False
+    if all_command_words[:1] == [GH_API_SUBCOMMAND]:
+        return any(_is_graphql_endpoint(each_word) for each_word in all_command_words[1:])
+    command_path = tuple(all_command_words[:GH_COMMAND_PATH_LENGTH])
+    all_rest_options = ALL_GH_REST_OPTIONS_BY_COMMAND_PATH.get(command_path, frozenset())
+    if any(each_option in all_rest_options for each_option in all_option_names):
+        return False
+    all_graphql_options = ALL_GH_GRAPHQL_OPTIONS_BY_COMMAND_PATH.get(command_path, frozenset())
+    if any(each_option in all_graphql_options for each_option in all_option_names):
+        return True
+    if command_path in ALL_GH_COMMAND_PATHS_CALLING_GRAPHQL_WITH_AN_OPERAND:
+        return len(all_command_words) > GH_COMMAND_PATH_LENGTH
+    if any(
+        command_path[: len(each_path)] == each_path for each_path in ALL_GH_GRAPHQL_COMMAND_PATHS
+    ):
+        return True
+    return (
+        len(command_path) == GH_COMMAND_PATH_LENGTH
+        and command_path[0] in ALL_GH_GRAPHQL_COMMAND_GROUPS
+        and command_path not in ALL_GH_REST_COMMAND_PATHS_IN_GRAPHQL_GROUPS
+    )
+
+
+def _calls_github_graphql(all_segment_tokens: list[str]) -> bool:
+    """Return True when a segment runs a GraphQL gh command or sends an HTTP client to the endpoint.
+
+    Args:
+        all_segment_tokens: One command segment's shell tokens.
+    """
+    program_name, all_arguments = segment_program_and_arguments(all_segment_tokens)
+    normalized_program_name = program_name.lower()
+    if normalized_program_name == GH_PROGRAM_NAME:
+        return _gh_arguments_call_graphql(all_arguments)
+    if (
+        normalized_program_name in ALL_HTTP_CLIENT_PROGRAM_NAMES
+        or normalized_program_name in ALL_SCRIPT_INTERPRETER_PROGRAM_NAMES
+        or PYTHON_INTERPRETER_BASENAME_PATTERN.fullmatch(normalized_program_name) is not None
+    ):
+        return any(
+            GITHUB_GRAPHQL_ENDPOINT_PATTERN.search(each_argument) is not None
+            for each_argument in all_arguments
+        )
+    return False
+
+
+def calls_github_graphql(command: str) -> bool:
+    """Return True when any command segment calls the GitHub GraphQL API.
+
+    ::
+
+        gh api graphql -f query='query{viewer{login}}'       -> True
+        gh pr create --title t --body-file b.md              -> True
+        gh api -X POST graphql -f query='query{viewer{login}}' -> True
+        gh -R o/r pr list                                    -> True
+        curl -X POST https://api.github.com/graphql -d @q    -> True
+        gh api repos/o/r/pulls/1/ccr/review_threads          -> False
+        gh pr diff 12                                        -> False
+        gh pr list --web                                     -> False
+        grep -rn "api.github.com/graphql" scripts            -> False
+
+    Args:
+        command: The shell command text the agent is about to run.
+    """
+    return any(
+        _calls_github_graphql(each_segment)
+        for each_segment in all_wrapped_command_segments(command)
+    )
+
+
+def _write_deny_decision() -> None:
+    sys.stdout.write(
+        json.dumps(
+            {
+                "hookSpecificOutput": {
+                    "hookEventName": HOOK_EVENT_NAME,
+                    "permissionDecision": DENY_DECISION,
+                    "permissionDecisionReason": CLOUD_GRAPHQL_DENY_REASON,
+                }
+            }
+        )
+    )
+    sys.stdout.flush()
+
+
+def main() -> None:
+    """Deny a GitHub GraphQL call inside a cloud session, or stay quiet."""
+    if not is_cloud_session():
+        return
+    hook_payload = read_hook_input_dictionary_from_stdin()
+    if hook_payload is None:
+        return
+    tool_name = hook_payload.get("tool_name")
+    if tool_name not in ALL_BASH_AND_POWERSHELL_TOOL_NAMES:
+        return
+    tool_input = hook_payload.get("tool_input")
+    if not isinstance(tool_input, dict):
+        return
+    command = tool_input.get("command", "")
+    if not isinstance(command, str) or not calls_github_graphql(command):
+        return
+    log_hook_block(
+        GATE_HOOK_NAME, HOOK_EVENT_NAME, CLOUD_GRAPHQL_DENY_REASON, str(tool_name), command
+    )
+    _write_deny_decision()
+
+
+if __name__ == "__main__":
+    main()

package/hooks/blocking/headless_claude_broker_gate.py

@@ -19,7 +19,6 @@ PowerShell tools.
 from __future__ import annotations
 
 import json
-import os
 import sys
 from pathlib import Path
 
@@ -32,14 +31,13 @@ try:
         DENY_DECISION,
         HOOK_EVENT_NAME,
     )
+    from hooks_constants.cloud_session import is_cloud_session
     from hooks_constants.headless_claude_broker_gate_constants import (
         ALL_PRINT_MODE_FLAGS,
         ALL_WINDOWS_LAUNCHER_SUFFIXES,
         BROKER_COMMAND_DENY_REASON,
         CLAUDE_PROFILE_LAUNCHER_PREFIX,
         CLAUDE_PROGRAM_NAME,
-        CLOUD_SESSION_ENV_TRUE_VALUE,
-        CLOUD_SESSION_ENV_VAR,
         GATE_HOOK_NAME,
         PRINT_MODE_LONG_FLAG_WITH_VALUE_PREFIX,
     )
@@ -119,11 +117,6 @@ def starts_unbrokered_headless_claude(command: str) -> bool:
     )
 
 
-def is_cloud_session() -> bool:
-    """Return True when this hook runs inside a Claude Code cloud session."""
-    return os.environ.get(CLOUD_SESSION_ENV_VAR, "").strip().lower() == CLOUD_SESSION_ENV_TRUE_VALUE
-
-
 def main() -> None:
     """Deny a headless Claude start that skips the broker outside a cloud session, or stay quiet."""
     if is_cloud_session():

package/hooks/blocking/merge_review_gate.py

@@ -1,13 +1,15 @@
 """Deny an agent's merge until a review of the merged head came back clean.
 
 The agent that drives a pull request loops a code review on it, fixing and
-pushing each finding, until one pass reports zero findings. The merge then
+pushing each finding, until one pass reports zero findings or every finding
+it reports is ruled out with a link to the posted rulings. The merge then
 names that exact head::
 
     merge, receipt says 0 findings at abc123, merge pinned to abc123 -> allow
+    merge, receipt rules out all 3 findings with a link, pinned       -> allow
     merge, receipt at abc123, merge pinned to def456                 -> deny, review again
     merge, receipt at abc123, merge names no head                    -> deny, pin it
-    merge, no receipt or the receipt counts findings                 -> deny, run the loop
+    merge, no receipt or the receipt counts open findings            -> deny, run the loop
     auto-merge or enqueue pinned to the clean head                    -> allow
     auto-merge that names no head                                     -> deny, pin it
     repository listed in CLAUDE_MERGE_REVIEW_EXEMPT_REPOSITORIES      -> allow
@@ -61,10 +63,13 @@ from hooks_constants.merge_review_gate_constants import (
     RECEIPT_FILE_NAME_TEMPLATE,
     RECEIPT_FINDINGS_KEY,
     RECEIPT_HEAD_KEY,
+    RECEIPT_RULED_OUT_KEY,
+    RECEIPT_RULINGS_KEY,
     REPO_FIELD,
     REPO_OPTION_PATTERN,
     REPOSITORY_SEPARATOR,
     REVIEW_COMMAND_ENVIRONMENT_VARIABLE,
+    RULINGS_LINK_PATTERN,
     STALE_REVIEW_REASON_TEMPLATE,
     UNKNOWN_TARGET_REASON,
     UNPINNED_MERGE_REASON_TEMPLATE,
@@ -228,12 +233,69 @@ def _clean_head(request: MergeRequest) -> str | None:
         )
     except (OSError, ValueError):
         return None
-    if not isinstance(receipt, dict) or receipt.get(RECEIPT_FINDINGS_KEY) != 0:
+    if not isinstance(receipt, dict) or not is_clean_receipt(
+        receipt, request.owner, request.repo, request.number
+    ):
         return None
     head = receipt.get(RECEIPT_HEAD_KEY)
     return head if isinstance(head, str) and head else None
 
 
+def is_clean_receipt(
+    all_receipt_fields: dict[str, object], owner: str, repo: str, number: int
+) -> bool:
+    """Return whether a recorded pass lets the merge through.
+
+    A pass is clean when it reported zero findings, or when every finding it
+    reported is ruled out and the receipt links the rulings comment posted on
+    this same pull request::
+
+        findings 0                                                -> clean
+        findings 2, ruled out 2, .../acme/tools/pull/12#issuecomment-9 -> clean
+        findings 2, ruled out 2, .../acme/other/pull/12#issuecomment-9 -> not clean
+
+    Args:
+        all_receipt_fields: The parsed receipt of one review pass.
+        owner: Owner of the pull request the merge targets.
+        repo: Repository of the pull request the merge targets.
+        number: Number of the pull request the merge targets.
+
+    Returns:
+        True when the pass counts as clean.
+    """
+    finding_count = all_receipt_fields.get(RECEIPT_FINDINGS_KEY)
+    if not _is_count(finding_count):
+        return False
+    return finding_count == 0 or _rules_out_every_finding(
+        all_receipt_fields, finding_count, owner, repo, number
+    )
+
+
+def _is_count(candidate: object) -> bool:
+    return isinstance(candidate, int) and not isinstance(candidate, bool) and candidate >= 0
+
+
+def _rules_out_every_finding(
+    all_receipt_fields: dict[str, object], finding_count: object, owner: str, repo: str, number: int
+) -> bool:
+    ruled_out_count = all_receipt_fields.get(RECEIPT_RULED_OUT_KEY)
+    return (
+        _is_count(ruled_out_count)
+        and ruled_out_count == finding_count
+        and _links_rulings_on(all_receipt_fields.get(RECEIPT_RULINGS_KEY), owner, repo, number)
+    )
+
+
+def _links_rulings_on(rulings: object, owner: str, repo: str, number: int) -> bool:
+    rulings_match = RULINGS_LINK_PATTERN.fullmatch(rulings) if isinstance(rulings, str) else None
+    return (
+        rulings_match is not None
+        and rulings_match["owner"].casefold() == owner.casefold()
+        and rulings_match["repo"].casefold() == repo.casefold()
+        and int(rulings_match["number"]) == number
+    )
+
+
 def _review_command() -> str:
     return os.environ.get(REVIEW_COMMAND_ENVIRONMENT_VARIABLE) or DEFAULT_REVIEW_COMMAND
 

package/hooks/blocking/pr_lifecycle_skill_gate.py

@@ -32,7 +32,6 @@ from hooks_constants.pr_lifecycle_skill_gate_constants import (
     DENY_REASON,
     ENVIRONMENT_ASSIGNMENT_PATTERN,
     GH_API_COMMAND,
-    GH_OPTIONS_WITH_VALUE,
     GH_PULL_REQUEST_COMMAND,
     GIT_ACTIONS,
     GIT_GLOBAL_OPTIONS_WITH_VALUE,
@@ -49,6 +48,7 @@ from hooks_constants.pr_lifecycle_skill_gate_constants import (
     SUBAGENT_TRANSCRIPT_DIRECTORY_NAME,
     SUBAGENT_TRANSCRIPT_FILE_TEMPLATE,
 )
+from hooks_constants.gh_command_words import gh_command_words
 from hooks_constants.hook_specific_output_keys import (
     HOOK_SPECIFIC_OUTPUT_KEY,
     PERMISSION_DECISION_KEY,
@@ -113,13 +113,12 @@ def _is_git_action(all_words: list[str]) -> bool:
 
 
 def _is_gh_action(all_words: list[str]) -> bool:
-    action, next_index = _next_command_word(all_words, 1, GH_OPTIONS_WITH_VALUE)
-    if action == GH_PULL_REQUEST_COMMAND:
-        subcommand, _ = _next_command_word(all_words, next_index, GH_OPTIONS_WITH_VALUE)
-        return subcommand is not None
-    if action != GH_API_COMMAND:
+    all_gh_words = gh_command_words(all_words[1:])
+    if all_gh_words[:1] == [GH_PULL_REQUEST_COMMAND]:
+        return len(all_gh_words) > 1
+    if all_gh_words[:1] != [GH_API_COMMAND]:
         return False
-    all_api_arguments = all_words[next_index:]
+    all_api_arguments = all_words[all_words.index(GH_API_COMMAND, 1) + 1 :]
     if any(each_name in each_word for each_word in all_api_arguments for each_name in ALL_API_ACTION_NAMES):
         return True
     return any(