claude-dev-env 8.32.2 → 8.33.0

package/hooks/blocking/verify_before_acting.py

@@ -0,0 +1,323 @@
+#!/usr/bin/env python3
+"""PostToolUse hook that blocks a mutating call made on an unchecked claim.
+
+The hook reads the thinking text of the assistant message that made the call,
+found in the session transcript by the call's ``tool_use_id``. When that
+reasoning hedges, the hook blocks and quotes the hedge sentence::
+
+    flag: The config probably lives in settings.json.   -> Write blocks
+    ok:   The config lives in settings.json, as read.   -> Write passes
+    ok:   The config probably lives in settings.json.   -> gh pr view passes
+
+The tool has already run, so the block reason tells the model to check the
+claim now with a read-only tool and to undo the change when the check
+contradicts it.
+
+A call counts as mutating when its tool is in ALL_ALWAYS_MUTATING_TOOL_NAMES
+(Write, Edit, MultiEdit, NotebookEdit, apply_patch, Agent, Task), when a
+segment of its shell command runs a writing program, a git or gh write, an
+in-place sed, or a PowerShell write cmdlet, or redirects output into a file,
+or when an MCP tool's last name segment is in ALL_MCP_MUTATING_ACTION_NAMES or
+holds a write verb as one of its words and no read verb. Shell segments come
+from the quote-aware parser after every wrapper is stepped over, so
+``rg 'gh pr merge' docs`` reads and ``sudo git push`` writes. Every other call
+is a check and passes with no log line.
+
+Each mutating call writes one JSON line to DECISION_LOG_RELATIVE_PATH under
+the home directory: blocked, allowed_clean, or reasoning_unseen when the
+transcript record is missing or its thinking text is empty. A missing or
+unreadable input always allows, so the hook never fails closed.
+"""
+
+from __future__ import annotations
+
+import datetime
+import json
+import sys
+import time
+from pathlib import Path
+
+hooks_root_directory = str(Path(__file__).resolve().parent.parent)
+if hooks_root_directory not in sys.path:
+    sys.path.insert(0, hooks_root_directory)
+
+from hooks_constants.bash_post_call_dispatcher_constants import (
+    HOOK_EVENT_NAME_KEY,
+    HOOK_SPECIFIC_OUTPUT_KEY,
+    POST_TOOL_USE_HOOK_EVENT_NAME,
+)
+from hooks_constants.hook_block_logger import log_hook_block
+from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+from hooks_constants.shell_command_mutation import is_mutating_shell_command
+from hooks_constants.verify_before_acting_constants import (
+    ALL_ALWAYS_MUTATING_TOOL_NAMES,
+    ALL_MCP_MUTATING_ACTION_NAMES,
+    ALL_MCP_MUTATING_VERBS,
+    ALL_MCP_READ_VERBS,
+    ALL_SHELL_TOOL_NAMES,
+    ALLOW_EXIT_CODE,
+    BLOCK_DECISION,
+    BLOCK_ID_KEY,
+    BLOCK_REASON_TEMPLATE,
+    BLOCK_TYPE_KEY,
+    COMMAND_KEY,
+    CONTENT_KEY,
+    DECISION_KEY,
+    DECISION_LOG_RELATIVE_PATH,
+    LOG_APPEND_MODE,
+    LOG_LINE_END,
+    HEDGE_PATTERN,
+    LOG_HEDGE_SENTENCE_KEY,
+    LOG_OUTCOME_KEY,
+    LOG_TIMESTAMP_KEY,
+    LOG_TOOL_NAME_KEY,
+    LOG_TOOL_USE_ID_KEY,
+    MAXIMUM_QUOTE_LENGTH,
+    MCP_ACTION_WORD_SPLIT_PATTERN,
+    MCP_SEGMENT_SEPARATOR,
+    MCP_TOOL_PREFIX,
+    MESSAGE_ID_KEY,
+    MESSAGE_KEY,
+    OUTCOME_ALLOWED_CLEAN,
+    OUTCOME_BLOCKED,
+    OUTCOME_REASONING_UNSEEN,
+    QUOTE_LEAD_LENGTH,
+    REASON_KEY,
+    SENTENCE_SPLIT_PATTERN,
+    THINKING_BLOCK_TYPE,
+    THINKING_JOINER,
+    THINKING_TEXT_KEY,
+    TOOL_INPUT_KEY,
+    TOOL_NAME_KEY,
+    TOOL_USE_BLOCK_TYPE,
+    TOOL_USE_ID_KEY,
+    TRANSCRIPT_DECODE_ERRORS,
+    TRANSCRIPT_ENCODING,
+    TRANSCRIPT_PATH_KEY,
+    TRANSCRIPT_POLL_INTERVAL_SECONDS,
+    TRANSCRIPT_POLL_LIMIT_SECONDS,
+    TRIM_MARKER,
+    WHITESPACE_RUN_PATTERN,
+    WORD_SEPARATOR,
+)
+
+def is_mutating_call(tool_name: str, tool_input: object) -> bool:
+    """Return True when the call writes, sends, or spawns rather than reads."""
+    if tool_name in ALL_ALWAYS_MUTATING_TOOL_NAMES:
+        return True
+    if tool_name in ALL_SHELL_TOOL_NAMES:
+        command = tool_input.get(COMMAND_KEY) if isinstance(tool_input, dict) else None
+        return isinstance(command, str) and is_mutating_shell_command(command)
+    if tool_name.startswith(MCP_TOOL_PREFIX):
+        last_segment = tool_name.rsplit(MCP_SEGMENT_SEPARATOR, maxsplit=1)[-1]
+        if last_segment in ALL_MCP_MUTATING_ACTION_NAMES:
+            return True
+        all_action_words = {
+            each_word.lower()
+            for each_word in MCP_ACTION_WORD_SPLIT_PATTERN.split(last_segment)
+            if each_word
+        }
+        return bool(all_action_words & ALL_MCP_MUTATING_VERBS) and not (
+            all_action_words & ALL_MCP_READ_VERBS
+        )
+    return False
+
+
+def _parsed_record(transcript_line: str) -> dict[str, object] | None:
+    try:
+        parsed_line = json.loads(transcript_line)
+    except json.JSONDecodeError:
+        return None
+    return parsed_line if isinstance(parsed_line, dict) else None
+
+
+def _message_of(all_record_fields: dict[str, object] | None) -> dict[str, object]:
+    message = all_record_fields.get(MESSAGE_KEY) if all_record_fields is not None else None
+    return message if isinstance(message, dict) else {}
+
+
+def _content_blocks(all_record_fields: dict[str, object] | None) -> list[dict[str, object]]:
+    all_content = _message_of(all_record_fields).get(CONTENT_KEY)
+    if not isinstance(all_content, list):
+        return []
+    return [each_block for each_block in all_content if isinstance(each_block, dict)]
+
+
+def _thinking_texts(all_blocks: list[dict[str, object]]) -> list[str]:
+    all_thinking_values = [
+        each_block.get(THINKING_TEXT_KEY)
+        for each_block in all_blocks
+        if each_block.get(BLOCK_TYPE_KEY) == THINKING_BLOCK_TYPE
+    ]
+    return [each_value for each_value in all_thinking_values if isinstance(each_value, str)]
+
+
+def _tool_use_position(all_blocks: list[dict[str, object]], tool_use_id: str) -> int | None:
+    for each_position, each_block in enumerate(all_blocks):
+        if (
+            each_block.get(BLOCK_TYPE_KEY) == TOOL_USE_BLOCK_TYPE
+            and each_block.get(BLOCK_ID_KEY) == tool_use_id
+        ):
+            return each_position
+    return None
+
+
+def _earlier_thinking(all_earlier_lines: list[str], message_id: str) -> list[str]:
+    all_texts: list[str] = []
+    for each_line in all_earlier_lines:
+        if message_id not in each_line:
+            continue
+        record = _parsed_record(each_line)
+        if _message_of(record).get(MESSAGE_ID_KEY) == message_id:
+            all_texts.extend(_thinking_texts(_content_blocks(record)))
+    return all_texts
+
+
+def acting_reasoning(all_transcript_lines: list[str], tool_use_id: str) -> str | None:
+    """Return the thinking text of the message that made the call, or None when unfound.
+
+    Scans from the end for the record whose ``tool_use`` block carries the id,
+    then joins the thinking blocks of every earlier record sharing its
+    ``message.id`` with the thinking that precedes the call in its own record.
+    Only lines holding the id substring are parsed, so a long transcript stays
+    inside the hook timeout.
+    """
+    for each_index in range(len(all_transcript_lines) - 1, -1, -1):
+        transcript_line = all_transcript_lines[each_index]
+        if tool_use_id not in transcript_line:
+            continue
+        record = _parsed_record(transcript_line)
+        all_blocks = _content_blocks(record)
+        tool_use_position = _tool_use_position(all_blocks, tool_use_id)
+        if tool_use_position is None:
+            continue
+        message_id = _message_of(record).get(MESSAGE_ID_KEY)
+        all_texts = (
+            _earlier_thinking(all_transcript_lines[:each_index], message_id)
+            if isinstance(message_id, str) and message_id
+            else []
+        )
+        all_texts.extend(_thinking_texts(all_blocks[:tool_use_position]))
+        return THINKING_JOINER.join(all_texts)
+    return None
+
+
+def _transcript_lines(transcript_path_value: object) -> list[str] | None:
+    if not isinstance(transcript_path_value, str) or not transcript_path_value:
+        return None
+    try:
+        transcript_text = Path(transcript_path_value).read_text(
+            encoding=TRANSCRIPT_ENCODING, errors=TRANSCRIPT_DECODE_ERRORS
+        )
+    except (OSError, ValueError):
+        return None
+    return transcript_text.splitlines()
+
+
+def _quoted_excerpt(sentence: str, hedge_start: int) -> str:
+    if len(sentence) <= MAXIMUM_QUOTE_LENGTH:
+        return sentence
+    window_start = max(
+        0, min(hedge_start - QUOTE_LEAD_LENGTH, len(sentence) - MAXIMUM_QUOTE_LENGTH)
+    )
+    window_end = window_start + MAXIMUM_QUOTE_LENGTH
+    leading_marker = TRIM_MARKER if window_start > 0 else ""
+    trailing_marker = TRIM_MARKER if window_end < len(sentence) else ""
+    return leading_marker + sentence[window_start:window_end].strip() + trailing_marker
+
+
+def first_hedge_sentence(reasoning: str) -> str | None:
+    """Return the first hedge sentence, trimmed around its hedge phrase, or None."""
+    for each_sentence in SENTENCE_SPLIT_PATTERN.split(reasoning):
+        normalized_sentence = WHITESPACE_RUN_PATTERN.sub(WORD_SEPARATOR, each_sentence).strip()
+        hedge_match = HEDGE_PATTERN.search(normalized_sentence)
+        if hedge_match is not None:
+            return _quoted_excerpt(normalized_sentence, hedge_match.start())
+    return None
+
+
+def _log_decision(
+    tool_name: str, tool_use_id: object, outcome: str, hedge_sentence: str | None
+) -> None:
+    try:
+        log_path = Path.home() / DECISION_LOG_RELATIVE_PATH
+    except RuntimeError:
+        return
+    log_record: dict[str, object] = {
+        LOG_TIMESTAMP_KEY: datetime.datetime.now().isoformat(),
+        LOG_TOOL_NAME_KEY: tool_name,
+        LOG_TOOL_USE_ID_KEY: tool_use_id if isinstance(tool_use_id, str) else None,
+        LOG_OUTCOME_KEY: outcome,
+    }
+    if hedge_sentence is not None:
+        log_record[LOG_HEDGE_SENTENCE_KEY] = hedge_sentence
+    try:
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+        with log_path.open(LOG_APPEND_MODE, encoding=TRANSCRIPT_ENCODING) as log_file:
+            log_file.write(json.dumps(log_record) + LOG_LINE_END)
+    except OSError:
+        pass
+
+
+def _call_reasoning(all_hook_fields: dict[str, object]) -> str | None:
+    """Return the call's reasoning, polling to a deadline while its record is unwritten.
+
+    PostToolUse can start before the harness appends the tool-use record, so a
+    missing record is read again until TRANSCRIPT_POLL_LIMIT_SECONDS passes.
+    """
+    tool_use_id = all_hook_fields.get(TOOL_USE_ID_KEY)
+    if not isinstance(tool_use_id, str) or not tool_use_id:
+        return None
+    deadline = time.monotonic() + TRANSCRIPT_POLL_LIMIT_SECONDS
+    while True:
+        all_transcript_lines = _transcript_lines(all_hook_fields.get(TRANSCRIPT_PATH_KEY))
+        if all_transcript_lines is None:
+            return None
+        reasoning = acting_reasoning(all_transcript_lines, tool_use_id)
+        if reasoning is not None or time.monotonic() >= deadline:
+            return reasoning
+        time.sleep(TRANSCRIPT_POLL_INTERVAL_SECONDS)
+
+
+def _emit_block(tool_name: str, tool_use_id: object, hedge_sentence: str) -> None:
+    block_reason = BLOCK_REASON_TEMPLATE.format(tool_name=tool_name, hedge_sentence=hedge_sentence)
+    _log_decision(tool_name, tool_use_id, OUTCOME_BLOCKED, hedge_sentence)
+    log_hook_block(
+        Path(__file__).name,
+        POST_TOOL_USE_HOOK_EVENT_NAME,
+        block_reason,
+        tool_name=tool_name,
+        offending_input_preview=hedge_sentence,
+    )
+    block_payload = {
+        DECISION_KEY: BLOCK_DECISION,
+        REASON_KEY: block_reason,
+        HOOK_SPECIFIC_OUTPUT_KEY: {HOOK_EVENT_NAME_KEY: POST_TOOL_USE_HOOK_EVENT_NAME},
+    }
+    sys.stdout.write(json.dumps(block_payload))
+
+
+def main() -> int:
+    hook_input = read_hook_input_dictionary_from_stdin()
+    if hook_input is None:
+        return ALLOW_EXIT_CODE
+    tool_name = hook_input.get(TOOL_NAME_KEY)
+    if not isinstance(tool_name, str) or not is_mutating_call(
+        tool_name, hook_input.get(TOOL_INPUT_KEY)
+    ):
+        return ALLOW_EXIT_CODE
+    tool_use_id = hook_input.get(TOOL_USE_ID_KEY)
+    reasoning = _call_reasoning(hook_input)
+    if reasoning is None or not reasoning.strip():
+        _log_decision(tool_name, tool_use_id, OUTCOME_REASONING_UNSEEN, None)
+        return ALLOW_EXIT_CODE
+    hedge_sentence = first_hedge_sentence(reasoning)
+    if hedge_sentence is None:
+        _log_decision(tool_name, tool_use_id, OUTCOME_ALLOWED_CLEAN, None)
+        return ALLOW_EXIT_CODE
+    _emit_block(tool_name, tool_use_id, hedge_sentence)
+    return ALLOW_EXIT_CODE
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/hooks/hooks.json

@@ -241,6 +241,16 @@
             "timeout": 60
           }
         ]
+      },
+      {
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit|Agent|Task|apply_patch|Bash|PowerShell|mcp__.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/verify_before_acting.py",
+            "timeout": 10
+          }
+        ]
       }
     ],
     "InstructionsLoaded": [

package/hooks/hooks_constants/piped_pytest_blocker_constants.py

@@ -18,9 +18,12 @@ parsing lives in ``shell_command_pipeline``. Pytest invocation classification
 that consumes these program, wrapper, and option constants lives in
 ``pytest_invocation``.
 
-Two wrapper shapes reach the program behind them differently. ``sudo`` and
-``uvx`` take their own option flags and then the command, so the step-over drops
-the flags. ``uv``, ``poetry``, ``pipenv``, ``pdm``, ``hatch``, ``rye``, and
+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
+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
 ``coverage`` take the literal ``run`` subcommand first, so the step-over reads
 that word and passes only when it is there — ``uv sync`` and ``coverage report``
 keep the wrapper as its own program. ``uv`` spells the same pass-through as
@@ -110,6 +113,7 @@ the blocker's own lexer.
 from __future__ import annotations
 
 import re
+from typing import NamedTuple
 
 from hooks_constants.shell_command_segments import ALL_SHELL_CONTROL_OPERATOR_TOKENS
 from hooks_constants.unscoped_search_blocker_constants import (
@@ -142,7 +146,10 @@ __all__ = [
     "ALL_VALUE_TAKING_WRAPPER_OPTION_FLAGS",
     "ALL_VALUE_TAKING_SHELL_OPTION_FLAGS",
     "ALL_VALUE_TAKING_INTERPRETER_OPTION_FLAGS",
-    "ALL_FLAG_TAKING_WRAPPER_COMMANDS",
+    "WrapperOptionGrammar",
+    "WINDOWS_EXECUTABLE_SUFFIX",
+    "RUN_SUBCOMMAND_OPTION_GRAMMAR",
+    "ALL_WRAPPER_OPTION_GRAMMARS_BY_NAME",
     "ALL_RUN_SUBCOMMAND_WRAPPER_COMMANDS",
     "RUN_SUBCOMMAND_NAME",
     "TOOL_SUBCOMMAND_NAME",
@@ -291,9 +298,74 @@ ALL_VALUE_TAKING_SHELL_OPTION_FLAGS: frozenset[str] = frozenset(
     }
 )
 
-ALL_FLAG_TAKING_WRAPPER_COMMANDS: frozenset[str] = frozenset(
-    {"sudo", "sudo.exe", "uvx", "uvx.exe"}
+class WrapperOptionGrammar(NamedTuple):
+    """The options one wrapper reads before the command it runs."""
+
+    all_value_taking_options: frozenset[str]
+    all_flag_options: frozenset[str]
+    leading_operand_count: int
+
+
+WINDOWS_EXECUTABLE_SUFFIX = ".exe"
+RUN_SUBCOMMAND_OPTION_GRAMMAR = WrapperOptionGrammar(
+    all_value_taking_options=ALL_VALUE_TAKING_WRAPPER_OPTION_FLAGS,
+    all_flag_options=frozenset(),
+    leading_operand_count=0,
 )
+ALL_WRAPPER_OPTION_GRAMMARS_BY_NAME: dict[str, WrapperOptionGrammar] = {
+    "sudo": WrapperOptionGrammar(
+        all_value_taking_options=frozenset(
+            {
+                "-u",
+                "-g",
+                "-C",
+                "-h",
+                "-p",
+                "-D",
+                "-R",
+                "-T",
+                "-U",
+                "-r",
+                "-t",
+                "--user",
+                "--group",
+                "--close-from",
+                "--host",
+                "--prompt",
+                "--chdir",
+                "--chroot",
+                "--command-timeout",
+                "--other-user",
+                "--role",
+                "--type",
+            }
+        ),
+        all_flag_options=frozenset({"-E", "-H", "-i", "-k", "-n", "-S", "-s", "-b", "-P"}),
+        leading_operand_count=0,
+    ),
+    "uvx": RUN_SUBCOMMAND_OPTION_GRAMMAR,
+    "xargs": WrapperOptionGrammar(
+        all_value_taking_options=frozenset(
+            {"-I", "-n", "-L", "-P", "-d", "-a", "-s", "-E", "--max-args", "--max-procs"}
+        ),
+        all_flag_options=frozenset(
+            {"-r", "-0", "-t", "-p", "-x", "-i", "-e", "-l", "--null", "--no-run-if-empty"}
+        ),
+        leading_operand_count=0,
+    ),
+    "env": WrapperOptionGrammar(
+        all_value_taking_options=frozenset(
+            {"-u", "-C", "-S", "--unset", "--chdir", "--split-string"}
+        ),
+        all_flag_options=frozenset({"-i", "-0", "-v", "--ignore-environment", "--null"}),
+        leading_operand_count=0,
+    ),
+    "timeout": WrapperOptionGrammar(
+        all_value_taking_options=frozenset({"-s", "-k", "--signal", "--kill-after"}),
+        all_flag_options=frozenset({"-v", "--verbose", "--preserve-status", "--foreground"}),
+        leading_operand_count=1,
+    ),
+}
 ALL_RUN_SUBCOMMAND_WRAPPER_COMMANDS: frozenset[str] = frozenset(
     {
         "uv",

package/hooks/hooks_constants/pr_done_reminder_constants.py

@@ -13,9 +13,6 @@ __all__ = [
     "GH_PROGRAM_NAME",
     "GH_PR_SUBCOMMAND",
     "GH_PR_CREATE_ACTION",
-    "ALL_GIT_OPTIONS_WITH_VALUE",
-    "ALL_POWERSHELL_PROGRAM_NAMES",
-    "ALL_POWERSHELL_COMMAND_FLAGS",
     "ALL_GH_PR_VIEW_ARGUMENTS",
     "GH_PR_VIEW_TIMEOUT_SECONDS",
     "NO_PULL_REQUEST_MARKER",
@@ -43,11 +40,6 @@ GIT_PUSH_SUBCOMMAND: str = "push"
 GH_PROGRAM_NAME: str = "gh"
 GH_PR_SUBCOMMAND: str = "pr"
 GH_PR_CREATE_ACTION: str = "create"
-ALL_GIT_OPTIONS_WITH_VALUE: frozenset[str] = frozenset({"-C", "-c"})
-ALL_POWERSHELL_PROGRAM_NAMES: frozenset[str] = frozenset(
-    {"pwsh", "pwsh.exe", "powershell", "powershell.exe"}
-)
-ALL_POWERSHELL_COMMAND_FLAGS: frozenset[str] = frozenset({"-command", "-c"})
 
 ALL_GH_PR_VIEW_ARGUMENTS: tuple[str, ...] = (
     "gh",

package/hooks/hooks_constants/pytest_invocation.py

@@ -21,7 +21,6 @@ from __future__ import annotations
 
 from hooks_constants.piped_pytest_blocker_constants import (
     ALL_CLUSTERED_STRING_EXEC_OPTION_LETTERS,
-    ALL_FLAG_TAKING_WRAPPER_COMMANDS,
     ALL_PYTEST_PROGRAM_BASENAMES,
     ALL_QUOTE_CHARACTERS,
     ALL_RUN_SUBCOMMAND_WRAPPER_COMMANDS,
@@ -30,28 +29,33 @@ from hooks_constants.piped_pytest_blocker_constants import (
     ALL_STRING_EXECUTING_SHELL_BASENAMES,
     ALL_VALUE_TAKING_INTERPRETER_OPTION_FLAGS,
     ALL_VALUE_TAKING_SHELL_OPTION_FLAGS,
-    ALL_VALUE_TAKING_WRAPPER_OPTION_FLAGS,
+    ALL_WRAPPER_OPTION_GRAMMARS_BY_NAME,
     COMMAND_OPTION_TOKEN_PATTERN,
     END_OF_OPTIONS_TOKEN,
     MODULE_RUN_FLAG,
     PYTEST_MODULE_NAME,
     PYTHON_INTERPRETER_BASENAME_PATTERN,
     RUN_SUBCOMMAND_NAME,
+    RUN_SUBCOMMAND_OPTION_GRAMMAR,
     SHORT_OPTION_CLUSTER_PATTERN,
     SHORT_OPTION_PREFIX,
     TOOL_SUBCOMMAND_NAME,
+    WINDOWS_EXECUTABLE_SUFFIX,
     WRAPPED_COMMAND_TOKEN_JOIN,
+    WrapperOptionGrammar,
 )
 from hooks_constants.shell_command_pipeline import (
     all_operator_aware_tokenizations,
     segments_with_following_operator,
 )
 from hooks_constants.shell_command_segments import (
+    LEADING_ASSIGNMENT_PATTERN,
     effective_leading_program,
     token_basename,
 )
 
 __all__ = [
+    "all_tokens_after_wrappers",
     "segment_reports_a_pytest_exit_code",
     "segment_runs_pytest",
     "string_exec_inner_command",
@@ -153,8 +157,17 @@ def _runs_pytest_as_a_module(all_interpreter_argument_tokens: list[str]) -> bool
     return _some_module_run_flag_names_pytest(all_module_tokens)
 
 
-def _all_tokens_from_the_first_operand(all_tokens: list[str]) -> list[str]:
-    """Return the tokens from the first non-option one on, dropping option flags."""
+def _option_token_count(stripped_token: str, grammar: WrapperOptionGrammar) -> int:
+    """Return how many tokens one wrapper option spans, counting its separate value."""
+    if stripped_token in grammar.all_flag_options:
+        return 1
+    return 1 + _option_value_token_count(stripped_token, grammar.all_value_taking_options)
+
+
+def _all_tokens_from_the_first_operand(
+    all_tokens: list[str], grammar: WrapperOptionGrammar
+) -> list[str]:
+    """Return the tokens from the first non-option one on, dropping the wrapper's options."""
     all_remaining_tokens = all_tokens
     while all_remaining_tokens:
         stripped_token = unquoted_token(all_remaining_tokens[0])
@@ -162,35 +175,60 @@ def _all_tokens_from_the_first_operand(all_tokens: list[str]) -> list[str]:
             return all_remaining_tokens[1:]
         if COMMAND_OPTION_TOKEN_PATTERN.match(stripped_token) is None:
             return all_remaining_tokens
-        flag_value_token_count = _option_value_token_count(
-            stripped_token, ALL_VALUE_TAKING_WRAPPER_OPTION_FLAGS
-        )
-        all_remaining_tokens = all_remaining_tokens[1 + flag_value_token_count :]
+        all_remaining_tokens = all_remaining_tokens[_option_token_count(stripped_token, grammar) :]
     return []
 
 
-def _all_tokens_after_one_wrapper(all_segment_tokens: list[str]) -> list[str] | None:
-    """Return the tokens a single leading pass-through wrapper runs, else None."""
+def _wrapper_basename(token: str) -> str:
+    return token_basename(unquoted_token(token)).removesuffix(WINDOWS_EXECUTABLE_SUFFIX)
+
+
+def _wrapper_program_index(all_segment_tokens: list[str]) -> int | None:
+    """Return the index of the program a wrapper step reads.
+
+    A wrapper with its own option grammar is read where it stands, so the
+    ``-u HOME`` behind ``env`` stays an option. Any other leading program is
+    found past assignments and plain launchers such as ``time`` and ``nohup``.
+    """
+    for each_index, each_token in enumerate(all_segment_tokens):
+        if LEADING_ASSIGNMENT_PATTERN.match(each_token) is not None:
+            continue
+        if _wrapper_basename(each_token) in ALL_WRAPPER_OPTION_GRAMMARS_BY_NAME:
+            return each_index
+        break
     leading_program = effective_leading_program(all_segment_tokens)
     if leading_program is None:
         return None
-    program_basename = token_basename(unquoted_token(leading_program))
-    leading_index = all_segment_tokens.index(leading_program)
-    all_argument_tokens = _all_tokens_from_the_first_operand(
-        all_segment_tokens[leading_index + 1 :]
-    )
-    if program_basename in ALL_FLAG_TAKING_WRAPPER_COMMANDS:
-        return all_argument_tokens
+    return all_segment_tokens.index(leading_program)
+
+
+def _all_tokens_after_one_wrapper(all_segment_tokens: list[str]) -> list[str] | None:
+    """Return the tokens a single leading pass-through wrapper runs, else None."""
+    leading_index = _wrapper_program_index(all_segment_tokens)
+    if leading_index is None:
+        return None
+    program_basename = _wrapper_basename(all_segment_tokens[leading_index])
+    grammar = ALL_WRAPPER_OPTION_GRAMMARS_BY_NAME.get(program_basename)
+    if grammar is not None:
+        all_operand_tokens = _all_tokens_from_the_first_operand(
+            all_segment_tokens[leading_index + 1 :], grammar
+        )
+        return all_operand_tokens[grammar.leading_operand_count :]
     if program_basename not in ALL_RUN_SUBCOMMAND_WRAPPER_COMMANDS:
         return None
+    all_argument_tokens = _all_tokens_from_the_first_operand(
+        all_segment_tokens[leading_index + 1 :], RUN_SUBCOMMAND_OPTION_GRAMMAR
+    )
     if all_argument_tokens and unquoted_token(all_argument_tokens[0]) == TOOL_SUBCOMMAND_NAME:
-        all_argument_tokens = _all_tokens_from_the_first_operand(all_argument_tokens[1:])
+        all_argument_tokens = _all_tokens_from_the_first_operand(
+            all_argument_tokens[1:], RUN_SUBCOMMAND_OPTION_GRAMMAR
+        )
     if not all_argument_tokens or unquoted_token(all_argument_tokens[0]) != RUN_SUBCOMMAND_NAME:
         return None
-    return _all_tokens_from_the_first_operand(all_argument_tokens[1:])
+    return _all_tokens_from_the_first_operand(all_argument_tokens[1:], RUN_SUBCOMMAND_OPTION_GRAMMAR)
 
 
-def _all_tokens_after_wrappers(all_segment_tokens: list[str]) -> list[str]:
+def all_tokens_after_wrappers(all_segment_tokens: list[str]) -> list[str]:
     """Return the segment tokens with every leading pass-through wrapper stepped over."""
     all_remaining_tokens = all_segment_tokens
     while True:
@@ -225,7 +263,7 @@ def segment_runs_pytest(all_segment_tokens: list[str]) -> bool:
         True when the segment's program is pytest or a Python interpreter
         running the pytest module, including through pass-through wrappers.
     """
-    all_unwrapped_tokens = _all_tokens_after_wrappers(all_segment_tokens)
+    all_unwrapped_tokens = all_tokens_after_wrappers(all_segment_tokens)
     leading_program = effective_leading_program(all_unwrapped_tokens)
     if leading_program is None:
         return False
@@ -297,7 +335,7 @@ def string_exec_inner_command(all_segment_tokens: list[str]) -> str | None:
         The inner command string the shell executes, or None when the segment
         is not a string-executing shell wrapper with a command string.
     """
-    all_unwrapped_tokens = _all_tokens_after_wrappers(all_segment_tokens)
+    all_unwrapped_tokens = all_tokens_after_wrappers(all_segment_tokens)
     leading_program = effective_leading_program(all_unwrapped_tokens)
     if leading_program is None:
         return None