claude-dev-env 8.99.0 → 8.100.0

package/bin/install-pstack-plugin.mjs

@@ -91,12 +91,13 @@ const HOST_DEFINITIONS = Object.freeze({
  * verb gets refresh commands: the marketplace add and plugin install leave an
  * existing entry in place, and the update commands then pull the newest
  * published version over it, so an installed plugin stays installed through
- * the whole run. When any refresh command fails, or the host has no update
- * verb, the removal commands run and take out each installed plugin, its
- * cached versions, and the marketplace clone, and the install commands that
- * follow fetch the newest published version into an empty slot. Removing a
- * marketplace uninstalls each plugin it supplied, so the plan removes and adds
- * that marketplace once for the whole set.
+ * the whole run. When a refresh command fails for a reason only a rebuild
+ * fixes, or the host has no update verb, the removal commands run and take
+ * out each installed plugin, its cached versions, and the marketplace clone,
+ * and the install commands that follow fetch the newest published version
+ * into an empty slot. Removing a marketplace uninstalls each plugin it
+ * supplied, so the plan removes and adds that marketplace once for the whole
+ * set.
  *
  * Claude Code and Codex publish a marketplace under different plugin verbs, so
  * the install verb belongs to the host and the marketplace and identifier
@@ -219,7 +220,12 @@ function runHostCommand(executable, commandArguments, options) {
         env: { ...process.env, ...options.environment },
         windowsVerbatimArguments: invocation.windowsVerbatimArguments,
     });
-    return { status: spawned.status, stderr: spawned.stderr ?? '', error: spawned.error };
+    return {
+        status: spawned.status,
+        stdout: spawned.stdout ?? '',
+        stderr: spawned.stderr ?? '',
+        error: spawned.error,
+    };
 }
 
 const COMMAND_NOT_FOUND_EXIT_CODE = 9009;
@@ -297,15 +303,33 @@ function lockedFolderDetail(allSpecs, host, homeDirectory, errorText, findLocker
     }).join('');
 }
 
+const REBUILD_REQUIRED_PATTERN = /doesn't match its extraKnownMarketplaces entry|Source path does not exist/;
+
+function commandFailureDetail(outcome) {
+    return singleLineDetail(outcome.stderr) || singleLineDetail(outcome.stdout)
+        || outcome.error?.message || `exit ${outcome.status}`;
+}
+
+function failedCommandOutcome(allSpecs, host, homeDirectory, executable, commandArguments, outcome, findLockers) {
+    const detail = commandFailureDetail(outcome);
+    const lockAdvice = lockedFolderDetail(allSpecs, host, homeDirectory, detail, findLockers);
+    return {
+        host,
+        executable,
+        status: 'failed',
+        warning: `${executable} ${commandArguments.join(' ')} failed: ${detail}${lockAdvice}`,
+    };
+}
+
 function refreshInPlace(plan, executable, commandEnvironment, runCommand) {
     for (const commandArguments of plan.refreshCommands) {
         const outcome = runCommand(executable, [...commandArguments], {
             environment: commandEnvironment,
         });
-        if (namesAnAbsentCommand(outcome)) return 'absent';
-        if (outcome.status !== 0 || outcome.error) return 'failed';
+        if (namesAnAbsentCommand(outcome)) return { state: 'absent' };
+        if (outcome.status !== 0 || outcome.error) return { state: 'failed', commandArguments, outcome };
     }
-    return 'refreshed';
+    return { state: 'refreshed' };
 }
 
 function removeOrphanedVersionsForHost(allSpecs, host, homeDirectory) {
@@ -326,11 +350,18 @@ function installForHost(allSpecs, host, homeDirectory, environment, runCommand,
     }
     if (plan.refreshCommands.length > 0) {
         const refreshOutcome = refreshInPlace(plan, executable, commandEnvironment, runCommand);
-        if (refreshOutcome === 'absent') return absentHostOutcome(allSpecs, host, executable);
-        if (refreshOutcome === 'refreshed') {
+        if (refreshOutcome.state === 'absent') return absentHostOutcome(allSpecs, host, executable);
+        if (refreshOutcome.state === 'refreshed') {
             removeOrphanedVersionsForHost(allSpecs, host, homeDirectory);
             return { host, executable, status: 'installed', warning: null };
         }
+        const refreshOutput = `${refreshOutcome.outcome.stderr ?? ''}\n${refreshOutcome.outcome.stdout ?? ''}`;
+        if (!REBUILD_REQUIRED_PATTERN.test(refreshOutput)) {
+            return failedCommandOutcome(
+                allSpecs, host, homeDirectory, executable,
+                refreshOutcome.commandArguments, refreshOutcome.outcome, findLockers,
+            );
+        }
     }
     for (const commandArguments of plan.removalCommands) {
         const outcome = runCommand(executable, [...commandArguments], {
@@ -347,14 +378,9 @@ function installForHost(allSpecs, host, homeDirectory, environment, runCommand,
         });
         if (namesAnAbsentCommand(outcome)) return absentHostOutcome(allSpecs, host, executable);
         if (outcome.status !== 0 || outcome.error) {
-            const detail = singleLineDetail(outcome.stderr) || outcome.error?.message || `exit ${outcome.status}`;
-            const lockAdvice = lockedFolderDetail(allSpecs, host, homeDirectory, detail, findLockers);
-            return {
-                host,
-                executable,
-                status: 'failed',
-                warning: `${executable} ${commandArguments.join(' ')} failed: ${detail}${lockAdvice}`,
-            };
+            return failedCommandOutcome(
+                allSpecs, host, homeDirectory, executable, commandArguments, outcome, findLockers,
+            );
         }
     }
     removeOrphanedVersionsForHost(allSpecs, host, homeDirectory);
@@ -385,12 +411,14 @@ export function restartNotice(allSpecs, allInstalledHosts) {
  * plugin, both of which leave an existing entry alone, then updates the
  * marketplace and each plugin. An installed plugin stays installed and enabled
  * through the run, so a session that starts mid-run still loads it, and a
- * failed network step leaves the prior version in place. When a refresh
- * command fails, such as a marketplace add whose sparse paths changed, the
- * host falls back to the clean install Codex always runs: it removes every
- * plugin in the set and then the marketplace, so an older version never
- * survives beside the new one, and adds them again. A removal that finds
- * nothing to remove exits non-zero on a fresh home, and the install goes on.
+ * failed refresh command reports the host failed and leaves the prior version
+ * in place. Two refresh errors need a rebuild: a source that no longer
+ * matches the settings entry, and a source path the sparse clone lacks. The
+ * host reads either from the failing refresh command's output, then falls
+ * back to the clean install Codex always runs: it removes every plugin in the
+ * set and then the marketplace, so an older version never survives beside the
+ * new one, and adds them again. A removal that finds nothing to remove exits
+ * non-zero on a fresh home, and the install goes on.
  * Before each Claude marketplace add, the install deletes the half-made clone
  * folder an interrupted earlier add left, so the add starts in an empty slot.
  *
@@ -482,7 +510,7 @@ export function removeRetiredMarketplacePlugins(allRetiredSpecs, options, depend
         );
         if (namesAnAbsentCommand(outcome)) break;
         if (outcome.status !== 0 || outcome.error) {
-            const detail = singleLineDetail(outcome.stderr) || outcome.error?.message || `exit ${outcome.status}`;
+            const detail = commandFailureDetail(outcome);
             failedRemovals.push({ pluginIdentifier: eachSpec.pluginIdentifier, detail });
             continue;
         }

package/bin/install-pstack-plugin.test.mjs

@@ -117,6 +117,30 @@ test('a failed Claude refresh falls back to removing and adding the marketplace
     ]);
 });
 
+test('a Claude refresh error printed on standard output still triggers the rebuild', () => {
+    const runner = recordingRunner((executable, commandArguments) => (
+        commandArguments[2] === 'add' && runner.calls.length === 1
+            ? { status: 1, stdout: "its source doesn't match its extraKnownMarketplaces entry", stderr: '' }
+            : { status: 0, stderr: '' }));
+    const outcome = installMarketplacePlugins([USAGE_WRAPUP_PLUGIN_SPEC], { ...ROOTS, hosts: ['claude'] }, runner);
+    assert.equal(outcome.status, 'installed');
+    assert.ok(runner.calls.some(call => call.commandArguments.includes('uninstall')));
+});
+
+test('a Claude refresh that fails on the network keeps the installed plugin and reports the failure', () => {
+    const runner = recordingRunner((executable, commandArguments) => (
+        commandArguments[1] === 'update'
+            ? { status: 1, stderr: 'Failed to update plugin: getaddrinfo ENOTFOUND github.com' }
+            : { status: 0, stderr: '' }));
+    const outcome = installMarketplacePlugins([PSTACK_PLUGIN_SPEC], { ...ROOTS, hosts: ['claude'] }, runner);
+    assert.equal(outcome.status, 'failed');
+    assert.match(outcome.hosts[0].warning, /claude plugin update pstack@pstack-claude failed: .*ENOTFOUND/);
+    const allRemovalCalls = runner.calls.filter(call => (
+        call.commandArguments.includes('uninstall') || call.commandArguments.includes('remove')
+    ));
+    assert.deepEqual(allRemovalCalls, []);
+});
+
 test('each host removes the installed plugin and marketplace before a clean install', () => {
     assert.deepEqual(marketplacePluginsPlan([PSTACK_PLUGIN_SPEC], 'claude').removalCommands, [
         ['plugin', 'uninstall', PSTACK_PLUGIN_IDENTIFIER],
@@ -131,9 +155,10 @@ test('each host removes the installed plugin and marketplace before a clean inst
 test('a removal that finds nothing installed still lets the install run', () => {
     const runner = recordingRunner((executable, commandArguments) => (
         commandArguments.includes('uninstall') || commandArguments.includes('remove')
-            || commandArguments.includes('update')
             ? { status: 1, stderr: 'not installed' }
-            : { status: 0, stderr: '' }));
+            : commandArguments.includes('update')
+                ? { status: 1, stderr: 'Source path does not exist: plugins/pstack' }
+                : { status: 0, stderr: '' }));
     const outcome = installMarketplacePlugins([PSTACK_PLUGIN_SPEC], { ...ROOTS, hosts: ['claude'] }, runner);
     assert.equal(outcome.status, 'installed');
     assert.deepEqual(runner.calls.at(-1).commandArguments, ['plugin', 'install', PSTACK_PLUGIN_IDENTIFIER]);

package/hooks/blocking/merge_review_gate.py

@@ -1,11 +1,14 @@
-"""Deny an agent's merge until a review of the merged head came back clean.
+"""Deny an agent's pull request open or merge until a review of that 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 or every finding
-it reports is ruled out with a link to the posted rulings. The merge then
-names that exact head::
+The agent reviews its branch before it opens the pull request, and loops a
+code review on the pull request, fixing and 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 open and the merge then name that exact head::
 
+    open, open receipt says 0 findings at abc123, branch head abc123 -> allow
+    open, no open receipt for the branch head                        -> deny, review first
     merge, receipt says 0 findings at abc123, merge pinned to abc123 -> allow
+    merge, open receipt clean 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
@@ -32,12 +35,18 @@ hooks_directory = str(Path(__file__).resolve().parent.parent)
 if hooks_directory not in sys.path:
     sys.path.insert(0, hooks_directory)
 
+from blocking.merge_review_gate_parts.open_request import OpenRequest, open_request_from
+from blocking.merge_review_gate_parts.receipts import (
+    has_clean_open_review,
+    is_clean_receipt,
+    receipt_path,
+    same_commit,
+)
 from hooks_constants.hook_specific_output_keys import (
     HOOK_SPECIFIC_OUTPUT_KEY,
     PERMISSION_DECISION_KEY,
 )
 from hooks_constants.merge_review_gate_constants import (
-    ALL_RECEIPT_DIRECTORY_SEGMENTS,
     ALL_SHELL_TOOL_NAMES,
     AUTO_MERGE_REASON_TEMPLATE,
     AUTO_MERGE_TOOL_SUFFIX,
@@ -52,6 +61,7 @@ from hooks_constants.merge_review_gate_constants import (
     HOOK_EVENT_NAME,
     MATCH_HEAD_PATTERN,
     MERGE_TOOL_SUFFIX,
+    NO_CLEAN_OPEN_REVIEW_REASON_TEMPLATE,
     NO_CLEAN_REVIEW_REASON_TEMPLATE,
     NUMBER_FIELD,
     OPTION_WITH_VALUE_PATTERN,
@@ -59,18 +69,13 @@ from hooks_constants.merge_review_gate_constants import (
     PERMISSION_DECISION_REASON_KEY,
     PR_NUMBER_PATTERN,
     PR_URL_PATTERN,
-    RECEIPT_DIRECTORY_ENVIRONMENT_VARIABLE,
-    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_OPEN_TARGET_REASON,
     UNKNOWN_TARGET_REASON,
     UNPINNED_MERGE_REASON_TEMPLATE,
 )
@@ -101,31 +106,25 @@ class MergeRequest:
         return f"{self.owner}/{self.repo}"
 
 
-def receipt_directory() -> Path:
-    """Return the folder that holds one review receipt per pull request.
-
-    Returns:
-        The folder CLAUDE_MERGE_REVIEW_RECEIPT_DIR names, else ``~/.claude/merge-reviews``.
-    """
-    override = os.environ.get(RECEIPT_DIRECTORY_ENVIRONMENT_VARIABLE)
-    if override:
-        return Path(override)
-    return Path.home().joinpath(*ALL_RECEIPT_DIRECTORY_SEGMENTS)
-
-
-def receipt_path(owner: str, repo: str, number: int) -> Path:
-    """Return where the review receipt for one pull request lives.
+def open_deny_reason(request: OpenRequest) -> str | None:
+    """Return why a pull request open must wait for a clean review, or None to allow it.
 
     Args:
-        owner: Repository owner.
-        repo: Repository name.
-        number: Pull request number.
+        request: The open the tool call asks for.
 
     Returns:
-        The receipt file path.
+        The deny reason, or None when the open may run.
     """
-    return receipt_directory() / RECEIPT_FILE_NAME_TEMPLATE.format(
-        owner=owner.casefold(), repo=repo.casefold(), number=number
+    if not request.owner or not request.repo:
+        return UNKNOWN_OPEN_TARGET_REASON
+    if _is_exempt(request.slug):
+        return None
+    if not request.head:
+        return UNKNOWN_OPEN_TARGET_REASON
+    if has_clean_open_review(request.repo, request.head):
+        return None
+    return NO_CLEAN_OPEN_REVIEW_REASON_TEMPLATE.format(
+        slug=request.slug, head=request.head, review_command=_review_command()
     )
 
 
@@ -216,15 +215,15 @@ def _without_option_values(arguments: str) -> str:
     return OPTION_WITH_VALUE_PATTERN.sub(" ", arguments)
 
 
-def _is_exempt(request: MergeRequest) -> bool:
+def _is_exempt(slug: str) -> bool:
     listed = os.environ.get(EXEMPT_REPOSITORIES_ENVIRONMENT_VARIABLE, "")
     all_exempt = {
         each.strip().casefold() for each in listed.split(REPOSITORY_SEPARATOR) if each.strip()
     }
-    return request.slug.casefold() in all_exempt
+    return slug.casefold() in all_exempt
 
 
-def _clean_head(request: MergeRequest) -> str | None:
+def _numbered_receipt(request: MergeRequest) -> dict[str, object] | None:
     if request.number is None:
         return None
     try:
@@ -233,78 +232,26 @@ def _clean_head(request: MergeRequest) -> str | None:
         )
     except (OSError, ValueError):
         return None
-    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.
+    return receipt if isinstance(receipt, dict) else None
 
-    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 _receipt_head(all_receipt_fields: dict[str, object] | None) -> str | None:
+    head = all_receipt_fields.get(RECEIPT_HEAD_KEY) if all_receipt_fields else None
+    return head if isinstance(head, str) and head else None
 
 
-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 _clean_head(request: MergeRequest, all_receipt_fields: dict[str, object] | None) -> str | None:
+    if all_receipt_fields is None or request.number is None:
+        return None
+    if not is_clean_receipt(all_receipt_fields, request.owner, request.repo, request.number):
+        return None
+    return _receipt_head(all_receipt_fields)
 
 
 def _review_command() -> str:
     return os.environ.get(REVIEW_COMMAND_ENVIRONMENT_VARIABLE) or DEFAULT_REVIEW_COMMAND
 
 
-def _same_commit(first: str, second: str) -> bool:
-    shorter, longer = sorted((first.casefold(), second.casefold()), key=len)
-    return longer.startswith(shorter)
-
-
 def deny_reason(request: MergeRequest) -> str | None:
     """Return why a merge must wait for a clean review, or None to allow it.
 
@@ -316,17 +263,30 @@ def deny_reason(request: MergeRequest) -> str | None:
     """
     if not request.owner or not request.repo or request.number is None:
         return UNKNOWN_TARGET_REASON
-    if _is_exempt(request):
+    if _is_exempt(request.slug):
+        return None
+    numbered_receipt = _numbered_receipt(request)
+    numbered_head = _receipt_head(numbered_receipt)
+    pass_on_pinned_head = (
+        numbered_head is not None
+        and request.pinned_head is not None
+        and same_commit(numbered_head, request.pinned_head)
+    )
+    if (
+        request.pinned_head
+        and not pass_on_pinned_head
+        and has_clean_open_review(request.repo, request.pinned_head)
+    ):
         return None
     fields = {"slug": request.slug, "number": request.number}
-    clean_head = _clean_head(request)
+    clean_head = _clean_head(request, numbered_receipt)
     if clean_head is None:
         return NO_CLEAN_REVIEW_REASON_TEMPLATE.format(review_command=_review_command(), **fields)
     if request.pinned_head is None and request.is_auto_merge:
         return AUTO_MERGE_REASON_TEMPLATE.format(head=clean_head, **fields)
     if request.pinned_head is None:
         return UNPINNED_MERGE_REASON_TEMPLATE.format(head=clean_head, **fields)
-    if not _same_commit(clean_head, request.pinned_head):
+    if not same_commit(clean_head, request.pinned_head):
         return STALE_REVIEW_REASON_TEMPLATE.format(
             head=clean_head, pinned=request.pinned_head, **fields
         )
@@ -334,7 +294,7 @@ def deny_reason(request: MergeRequest) -> str | None:
 
 
 def decision_for(all_payload_fields: dict[str, object]) -> dict[str, object] | None:
-    """Return a deny decision for a merge with no clean review, else None.
+    """Return a deny decision for an open or merge with no clean review, else None.
 
     Args:
         all_payload_fields: The parsed PreToolUse input.
@@ -342,10 +302,11 @@ def decision_for(all_payload_fields: dict[str, object]) -> dict[str, object] | N
     Returns:
         The hook output that denies the call, or None to allow it.
     """
-    request = merge_request_from(all_payload_fields)
-    if request is None:
-        return None
-    reason = deny_reason(request)
+    open_request = open_request_from(all_payload_fields)
+    merge_request = merge_request_from(all_payload_fields)
+    reason = (open_deny_reason(open_request) if open_request is not None else None) or (
+        deny_reason(merge_request) if merge_request is not None else None
+    )
     if reason is None:
         return None
     return {

package/hooks/blocking/merge_review_gate_parts/__init__.py

@@ -0,0 +1 @@
+"""Decomposed concern modules the ``merge_review_gate`` entry hook wires together."""

package/hooks/blocking/merge_review_gate_parts/open_request.py

@@ -0,0 +1,163 @@
+"""Read the pull request open a PreToolUse payload asks for, and the head it opens with."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+hooks_directory = str(Path(__file__).resolve().parent.parent.parent)
+if hooks_directory not in sys.path:
+    sys.path.insert(0, hooks_directory)
+
+from hooks_constants.merge_review_gate_constants import (
+    ALL_ORIGIN_URL_ARGUMENTS,
+    ALL_SHELL_TOOL_NAMES,
+    CHANGE_FOLDER_PATTERN,
+    CREATE_TEXT_OPTION_PATTERN,
+    CREATE_TOOL_SUFFIX,
+    CURRENT_HEAD_REFERENCE,
+    CWD_FIELD,
+    GH_PR_CREATE_PATTERN,
+    GIT_TIMEOUT_SECONDS,
+    HEAD_BRANCH_FIELD,
+    HEAD_OPTION_PATTERN,
+    ORIGIN_URL_PATTERN,
+    OWNER_FIELD,
+    PULL_REQUEST_SCRIPT_CREATE_PATTERN,
+    REMOTE_BRANCH_PREFIX,
+    REPO_FIELD,
+    REPO_OPTION_PATTERN,
+)
+
+
+@dataclass(frozen=True)
+class OpenRequest:
+    """One pull request a tool call asks to open.
+
+    Attributes:
+        owner: Repository owner, or empty when it could not be read.
+        repo: Repository name, or empty when it could not be read.
+        head: The commit the pull request would open with, or None.
+    """
+
+    owner: str
+    repo: str
+    head: str | None
+
+    @property
+    def slug(self) -> str:
+        """Return ``owner/repo``."""
+        return f"{self.owner}/{self.repo}"
+
+
+def open_request_from(all_payload_fields: dict[str, object]) -> OpenRequest | None:
+    """Read the pull request open a PreToolUse payload asks for.
+
+    ::
+
+        mcp__github__create_pull_request {owner, repo, head}
+        gh pr create --repo o/r --head branch
+        python pull_request.py create --repo o/r --head branch
+
+    A branch resolves in the payload's folder or a ``cd`` target, as
+    ``origin/<branch>`` first. No head means ``HEAD``; no repository, ``origin``.
+
+    Args:
+        all_payload_fields: The parsed PreToolUse input.
+
+    Returns:
+        The open request, or None when the call opens no pull request.
+    """
+    tool_name = all_payload_fields.get("tool_name")
+    tool_input = all_payload_fields.get("tool_input")
+    if not isinstance(tool_name, str) or not isinstance(tool_input, dict):
+        return None
+    working_folder = all_payload_fields.get(CWD_FIELD)
+    folder = working_folder if isinstance(working_folder, str) and working_folder else None
+    if tool_name.endswith(CREATE_TOOL_SUFFIX):
+        return _tool_open_request(tool_input, folder)
+    command = tool_input.get("command")
+    if tool_name not in ALL_SHELL_TOOL_NAMES or not isinstance(command, str):
+        return None
+    return _shell_open_request(command, folder)
+
+
+def _tool_open_request(all_tool_input: dict[object, object], folder: str | None) -> OpenRequest:
+    branch = all_tool_input.get(HEAD_BRANCH_FIELD)
+    return OpenRequest(
+        owner=str(all_tool_input.get(OWNER_FIELD, "")),
+        repo=str(all_tool_input.get(REPO_FIELD, "")),
+        head=_branch_commit(branch, folder) if isinstance(branch, str) and branch else None,
+    )
+
+
+def _shell_open_request(command: str, folder: str | None) -> OpenRequest | None:
+    options_only = CREATE_TEXT_OPTION_PATTERN.sub(" ", command)
+    create_match = GH_PR_CREATE_PATTERN.search(
+        options_only
+    ) or PULL_REQUEST_SCRIPT_CREATE_PATTERN.search(options_only)
+    if not create_match:
+        return None
+    folder = _folder_after_changes(options_only[: create_match.start()], folder)
+    rest = create_match["rest"]
+    repo_match = REPO_OPTION_PATTERN.search(rest)
+    owner, repo = (
+        (repo_match["owner"], repo_match["repo"]) if repo_match else _origin_repository(folder)
+    )
+    head_match = HEAD_OPTION_PATTERN.search(rest)
+    branch = head_match["head"] if head_match else CURRENT_HEAD_REFERENCE
+    return OpenRequest(owner=owner, repo=repo, head=_branch_commit(branch, folder))
+
+
+def _folder_after_changes(command_before_create: str, folder: str | None) -> str | None:
+    all_changes = list(CHANGE_FOLDER_PATTERN.finditer(command_before_create))
+    if not all_changes:
+        return folder
+    target = Path(os.path.expanduser(all_changes[-1]["folder"].strip("\"'")))
+    if not target.is_absolute() and folder:
+        target = Path(folder) / target
+    return str(target)
+
+
+def _run_git(all_arguments: list[str], folder: str | None) -> str | None:
+    try:
+        completed = subprocess.run(
+            ["git", *all_arguments],
+            cwd=folder,
+            capture_output=True,
+            text=True,
+            timeout=GIT_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if completed.returncode != 0:
+        return None
+    return completed.stdout.strip() or None
+
+
+def _branch_commit(branch: str, folder: str | None) -> str | None:
+    branch_name = branch.split(":", 1)[-1]
+    all_references = (
+        (branch_name,)
+        if branch_name == CURRENT_HEAD_REFERENCE
+        else (REMOTE_BRANCH_PREFIX + branch_name, branch_name)
+    )
+    for each_reference in all_references:
+        commit = _run_git(
+            ["rev-parse", "--verify", "--quiet", f"{each_reference}^{{commit}}"], folder
+        )
+        if commit:
+            return commit
+    return None
+
+
+def _origin_repository(folder: str | None) -> tuple[str, str]:
+    origin_url = _run_git(list(ALL_ORIGIN_URL_ARGUMENTS), folder)
+    origin_match = ORIGIN_URL_PATTERN.search(origin_url) if origin_url else None
+    if not origin_match:
+        return "", ""
+    return origin_match["owner"], origin_match["repo"]