Narrow the modern-python shims to the commands uv run replaces (#255)

* Narrow the modern-python shims to the commands uv run replaces

Closes #207.

The shims sit on PATH, so they intercept every subprocess any tool
spawns, not just what Claude types. Two of the intercepted invocations
were not package management at all, and blocking them broke real tooling.

`uv pip` now passes through when it carries --project, --directory or
--target. Those say a tool is building an environment it owns, where
`uv add` is not the available advice: prek installs every hook with
`uv pip install --project / --directory <cache>`, so the refusal made
`git commit` fail in any repo whose hooks need a Python environment.
A bare `uv pip install requests` is still refused.

`python -c`, `python -m <module>` and `python -` now reach the real
interpreter. None of them resolves a script against a project's
dependencies, which is what `uv run` exists to do, and `uv run python3 -`
is not a drop-in replacement inside a pipeline. `python -m pip` stays
intercepted, as do bare `python` and `python script.py`.

Passing anything through is new for the python shim, which previously
ended every branch in exit 1, so it gains the same skip-my-own-dir PATH
walk the uv shim already had. That walk now uses parameter expansion
rather than basename, because the one case where it must report failure
is a PATH holding nothing but the shim, where shelling out to coreutils
fails first with a confusing error.

Verified by A/B on the two symptoms #207 reports, running each suite
against the old shim and the new one:

- zeroize-audit's rust-regression smoke test: FAILED at line 72 before,
  "Rust regression smoke checks passed." after.
- prek hook installation from a cold cache: refused before, "check json
  Passed" after.

bats goes from 19 cases to 38. Five python cases inverted rather than
being deleted: the ones asserting that -c and -m are refused now assert
they run. AGENTS.md's note on `make shell-suites` is corrected rather
than removed — the #207 interceptions are gone, but the target still
fails because variant-analysis invokes `python3 <script>.py`, which the
shim intercepts by design. That one belongs to variant-analysis.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* Decide on the mode selector, not on argument position

Two gaps in the narrowing, both from review.

`uv pip install --help` documents `-t, --target <TARGET>`, so the short
form has to be exempt alongside the long one. Without it the same
tool-managed install was allowed or refused depending on spelling.

The python shim read only $1 to find the mode selector, so `python -u -c
'code'` was refused while `python -c 'code'` ran, even though they are
the same invocation. It now steps over interpreter flags to find the
selector, giving `-W`, `-X` and `--check-hash-based-pycs` the two slots
they take. `-u -m pip` is still refused, and so is `-u script.py`: a
script path is what `uv run` replaces regardless of what precedes it.

bats 38 -> 43. Both #207 regressions re-verified after the restructure:
zeroize-audit's smoke test passes and prek installs hooks from a cold
cache.

Not fixed here, deliberately: `uv --no-progress pip install requests`
still slips past the refusal, because the subcommand check reads $1 as
well. Parsing that correctly means knowing which uv global flags take a
value, and getting it wrong would refuse a command that works today. The
failure mode is a missed nudge rather than a breakage — the real uv runs
and behaves correctly — so it does not belong in a change whose purpose
is to refuse less.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

.claude-plugin/marketplace.json

@@ -241,7 +241,7 @@
     },
     {
       "name": "modern-python",
-      "version": "1.5.3",
+      "version": "1.6.0",
       "description": "Modern Python best practices. Use when creating new Python projects, and writing Python scripts, or migrating existing projects from legacy tools.",
       "author": {
         "name": "William Tan",

AGENTS.md

@@ -239,9 +239,13 @@ is strong evidence and not a guarantee:
   `pre-commit run -a`) to cover those locally.
 - **the version-increment check**, which needs a base ref to diff against and so has
   no meaning outside a PR.
-- **`make shell-suites`**, which is a target but not part of `check`: it fails on any
-  machine with the `modern-python` plugin installed, because its shim intercepts the
-  `python3 -` that zeroize-audit's suite uses (#207).
+- **`make shell-suites`**, which is a target but not part of `check`: it still fails on a
+  machine with the `modern-python` plugin installed, though no longer for the reason
+  #207 describes. The `python3 -` interception that broke zeroize-audit is gone as of
+  modern-python 1.6.0. What remains is `plugins/variant-analysis/tests/` invoking
+  `python3 <script>.py`, which the shim intercepts *by design* — a bare script run is
+  exactly what `uv run python` replaces. That one is variant-analysis's to fix. With no
+  shim on PATH the whole target passes.
 
 Both scan every plugin; the validator is not scoped down in CI. Only the
 version-increment check is limited to the plugins a branch touched, and it is the one

plugins/modern-python/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "modern-python",
-  "version": "1.5.3",
+  "version": "1.6.0",
   "description": "Modern Python best practices. Use when creating new Python projects, and writing Python scripts, or migrating existing projects from legacy tools.",
   "author": {
     "name": "William Tan",

plugins/modern-python/README.md

@@ -39,15 +39,17 @@ Modern Python tooling and best practices using uv, ruff, ty, and pytest. Based o
 
 This plugin includes a `SessionStart` hook that prepends PATH shims for `python`, `pip`, `pipx`, and `uv`. When Claude runs a bare `python`, `pip`, or `pipx` command, the shell resolves to the shim, which prints an error with the correct `uv` alternative and exits non-zero. The suggested alternative always uses the exact command name `python` (never `python3`) so it also works outside a project; see the header comment in [`hooks/shims/python`](hooks/shims/python) for the full rationale.
 
+The shims sit on PATH, so they see every subprocess a tool spawns, not only what Claude types. That is why the intercepted set is narrow: it covers the invocations `uv run` and `uv add` genuinely replace, and passes the rest through to the real binary. `python -c`, `python -m <module>` and `python -` read a program from the command line, an installed module, or stdin, so none of them resolves a script against a project's dependencies; `uv pip` carrying `--project`, `--directory` or `--target` is a tool building an environment it owns. Redirecting those broke real tooling, including `prek` hook installation and any script piping into `python3 -` ([#207](https://github.com/trailofbits/skills/issues/207)).
+
 | Intercepted Command | Suggested Alternative |
 |---------------------|----------------------|
 | `python ...` | `uv run python ...` |
-| `python -m module` | `uv run python -m module` |
 | `python -m pip` | `uv add`/`uv remove` |
 | `pip install pkg` | `uv add pkg` or `uv run --with pkg` |
 | `pip uninstall pkg` | `uv remove pkg` |
 | `pip freeze` | `uv export` |
 | `uv pip ...` | `uv add`/`uv remove`/`uv sync` |
+| *(passed through)* | `python -c`, `python -m <module>`, `python -`, and `uv pip` with `--project`, `--directory` or `--target` |
 | `pipx install <pkg>` | `uv tool install <pkg>` |
 | `pipx run <pkg>` | `uvx <pkg>` |
 | `pipx uninstall <pkg>` | `uv tool uninstall <pkg>` |

plugins/modern-python/hooks/shims/python

@@ -1,9 +1,43 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# PATH shim for python/python3 — intercepts bare invocations and
-# suggests the uv equivalent.  Works for both names via $0.
-cmd="$(basename "$0")"
+# PATH shim for python/python3 — intercepts the invocations `uv run` replaces and
+# passes the rest through to the real interpreter.  Works for both names via $0.
+#
+# Parameter expansion rather than basename/dirname on purpose: this shim has to work
+# when PATH holds nothing but its own directory, which is exactly the case where it
+# must report that no real interpreter was found. Shelling out to coreutils there
+# fails first, with a confusing error about basename.
+cmd="${0##*/}"
+
+# What is intercepted, and what is not (#207):
+#
+# `python` and `python script.py` are what `uv run` exists to replace — they resolve a
+# script against a project's dependencies, and running them bare gets the system
+# interpreter with none of them.
+#
+# `-c`, `-m` and `-` are not that. They read a program from the command line, a module
+# already on the path, or stdin, and none of them resolves a script's dependencies.
+# `uv run python3 -` is also not a drop-in replacement inside a pipeline, so redirecting
+# it there broke real scripts — zeroize-audit's smoke test among them.
+#
+# `-m pip` stays intercepted: that IS package management, and it is the foot-gun.
+
+# Hand off to the real interpreter, skipping this shim's directory in PATH.
+exec_real() {
+  local shim_dir path_entries dir resolved
+  shim_dir="$(cd "${0%/*}" && pwd)"
+  IFS=: read -ra path_entries <<<"${PATH:-}"
+  for dir in "${path_entries[@]}"; do
+    resolved="$(cd "$dir" 2>/dev/null && pwd)" || continue
+    [[ "$resolved" == "$shim_dir" ]] && continue
+    if [[ -x "$dir/$cmd" ]]; then
+      exec "$dir/$cmd" "$@"
+    fi
+  done
+  echo "ERROR: real $cmd binary not found on PATH" >&2
+  exit 127
+}
 
 # Canonical rationale for the suggestion's shape (the README,
 # setup-shims.sh, and python-shim.bats point here):
@@ -15,31 +49,54 @@ cmd="$(basename "$0")"
 # to this shim.
 #
 # Arguments are requoted with %q so the suggestion stays runnable when they
-# contain spaces or shell metacharacters (e.g. -c 'print(1+1)').
+# contain spaces or shell metacharacters.
 args=""
 if (($#)); then
   args="$(printf ' %q' "$@")"
 fi
 
-case "${1:-}" in
+# Find the mode selector, stepping over any interpreter flags in front of it. Reading
+# only $1 would make the decision depend on argument order: `python -u -c 'code'` means
+# exactly what `python -c 'code'` means, and refusing one while allowing the other is an
+# accident, not a rule. `-W`, `-X` and `--check-hash-based-pycs` take a separate value,
+# so they consume two slots; everything else beginning with `-` consumes one.
+mode=""
+argv=("$@")
+i=0
+while ((i < ${#argv[@]})); do
+  case "${argv[i]}" in
+    -c | -m | -)
+      mode="${argv[i]}"
+      break
+      ;;
+    -W | -X | --check-hash-based-pycs)
+      ((i += 2))
+      ;;
+    -*)
+      ((i += 1))
+      ;;
+    *)
+      # A script path. This is the case `uv run` exists to replace.
+      break
+      ;;
+  esac
+done
+
+case "$mode" in
   -m)
-    case "${2:-}" in
-      pip)
-        echo "ERROR: \`$cmd -m pip\` is not supported. Use:" >&2
-        echo "  uv add <package>       # add a dependency" >&2
-        echo "  uv remove <package>    # remove a dependency" >&2
-        ;;
-      *)
-        if (($# < 2)); then
-          args=" -m <module>"
-        fi
-        echo "ERROR: Use \`uv run python$args\` instead of \`$cmd$args\`" >&2
-        ;;
-    esac
+    if [[ "${argv[i + 1]:-}" == "pip" ]]; then
+      echo "ERROR: \`$cmd -m pip\` is not supported. Use:" >&2
+      echo "  uv add <package>       # add a dependency" >&2
+      echo "  uv remove <package>    # remove a dependency" >&2
+      exit 1
+    fi
+    exec_real "$@"
+    ;;
+  -c | -)
+    exec_real "$@"
     ;;
   *)
     echo "ERROR: Use \`uv run python$args\` instead of \`$cmd$args\`" >&2
+    exit 1
     ;;
 esac
-
-exit 1

plugins/modern-python/hooks/shims/python-shim.bats

@@ -1,7 +1,22 @@
 #!/usr/bin/env bats
 # Tests for python/python3 PATH shim
 
+bats_require_minimum_version 1.5.0
+
 SHIM="${BATS_TEST_DIRNAME}/python"
+SHIM3="${BATS_TEST_DIRNAME}/python3"
+
+# Pass-through cases need to reach a real interpreter. /usr/bin holds python3 on both
+# macOS and the CI image, and pinning PATH to it keeps the test off any shim that
+# happens to be installed on the machine running this — including an older copy of
+# this very shim, which would otherwise answer instead of the real binary.
+REAL_PATH="/usr/bin:/bin"
+
+real_python3_or_skip() {
+  [[ -x /usr/bin/python3 ]] || skip "no /usr/bin/python3 to pass through to"
+}
+
+# --------------------------------------------------------------- still intercepted
 
 @test "exits non-zero for bare python" {
   run "$SHIM"
@@ -15,18 +30,6 @@ SHIM="${BATS_TEST_DIRNAME}/python"
   [[ "$output" == *"uv run python script.py"* ]]
 }
 
-@test "exits non-zero for python -c" {
-  run "$SHIM" -c 'print(1)'
-  [[ $status -ne 0 ]]
-  [[ "$output" == *"uv run python"* ]]
-}
-
-@test "exits non-zero for python -m pytest" {
-  run "$SHIM" -m pytest
-  [[ $status -ne 0 ]]
-  [[ "$output" == *"uv run python -m pytest"* ]]
-}
-
 @test "exits non-zero for python -m pip install" {
   run "$SHIM" -m pip install requests
   [[ $status -ne 0 ]]
@@ -34,14 +37,14 @@ SHIM="${BATS_TEST_DIRNAME}/python"
   [[ "$output" == *"uv remove"* ]]
 }
 
-@test "suggests uv run python -m <module> for arbitrary modules" {
-  run "$SHIM" -m http.server
+@test "python3 -m pip suggests uv add" {
+  run "$SHIM3" -m pip install foo
   [[ $status -ne 0 ]]
-  [[ "$output" == *"uv run python -m http.server"* ]]
+  [[ "$output" == *"uv add"* ]]
 }
 
 @test "works when invoked as python3 via symlink" {
-  run "${BATS_TEST_DIRNAME}/python3"
+  run "$SHIM3"
   [[ $status -ne 0 ]]
   [[ "$output" == *'instead of `python3'* ]]
 }
@@ -49,43 +52,92 @@ SHIM="${BATS_TEST_DIRNAME}/python"
 # The suggestion must use the exact name `python`, never `python3`; see
 # the header comment in ./python for the full rationale.
 @test "suggests exact 'uv run python', not python3, when invoked as python3" {
-  run "${BATS_TEST_DIRNAME}/python3" script.py
+  run "$SHIM3" script.py
   [[ $status -ne 0 ]]
   [[ "$output" == *"Use \`uv run python script.py\`"* ]]
   [[ "$output" != *"uv run python3"* ]]
 }
 
-@test "suggests exact 'uv run python -m', not python3, for modules" {
-  run "${BATS_TEST_DIRNAME}/python3" -m http.server
-  [[ $status -ne 0 ]]
-  [[ "$output" == *"Use \`uv run python -m http.server\`"* ]]
-  [[ "$output" != *"uv run python3"* ]]
-}
-
-@test "-m suggestion preserves arguments after the module" {
-  run "${BATS_TEST_DIRNAME}/python3" -m http.server 8000
-  [[ $status -ne 0 ]]
-  [[ "$output" == *"Use \`uv run python -m http.server 8000\` instead of \`python3 -m http.server 8000\`"* ]]
-}
-
-# %q output can differ across bash versions, so build the expectation with
-# the same requoting the shim uses, after checking it actually escapes.
-@test "suggestion requotes -c code so it stays copy-paste runnable" {
-  run "$SHIM" -c 'print(1+1)'
-  [[ $status -ne 0 ]]
-  quoted="$(printf '%q' 'print(1+1)')"
-  [[ "$quoted" != 'print(1+1)' ]]
-  [[ "$output" == *"Use \`uv run python -c $quoted\`"* ]]
-}
-
 @test "bare invocation suggests uv run python without trailing space" {
   run "$SHIM"
   [[ $status -ne 0 ]]
   [[ "$output" == *"Use \`uv run python\` instead of \`python\`"* ]]
 }
 
-@test "python3 -m pip suggests uv add" {
-  run "${BATS_TEST_DIRNAME}/python3" -m pip install foo
+# %q output can differ across bash versions, so build the expectation with
+# the same requoting the shim uses, after checking it actually escapes.
+@test "suggestion requotes a script path so it stays copy-paste runnable" {
+  run "$SHIM" 'my script.py'
+  [[ $status -ne 0 ]]
+  quoted="$(printf '%q' 'my script.py')"
+  [[ "$quoted" != 'my script.py' ]]
+  [[ "$output" == *"Use \`uv run python $quoted\`"* ]]
+}
+
+# ------------------------------------------------------------- deliberately allowed
+#
+# None of these resolves a script against a project's dependencies, which is the thing
+# `uv run` exists to do, so redirecting them was wrong. See #207 and ./python's header.
+
+@test "python -c runs the code instead of refusing" {
+  real_python3_or_skip
+  run env PATH="$REAL_PATH" "$SHIM3" -c 'print(1+1)'
+  [[ $status -eq 0 ]]
+  [[ "$output" == "2" ]]
+}
+
+@test "python -m <module> reaches the module instead of refusing" {
+  real_python3_or_skip
+  run env PATH="$REAL_PATH" "$SHIM3" -m json.tool --help
+  [[ $status -eq 0 ]]
+  [[ "$output" == *"json.tool"* ]]
+}
+
+@test "python - reads the program from stdin" {
+  real_python3_or_skip
+  run bash -c "echo 'print(3+3)' | env PATH='$REAL_PATH' '$SHIM3' -"
+  [[ $status -eq 0 ]]
+  [[ "$output" == "6" ]]
+}
+
+# An interpreter flag before the mode selector must not change the decision: `-u -c` is
+# the same invocation as `-c`. Reading only $1 made the answer depend on argument order.
+
+@test "an interpreter flag before -c does not resurrect the refusal" {
+  real_python3_or_skip
+  run env PATH="$REAL_PATH" "$SHIM3" -u -c 'print(1+1)'
+  [[ $status -eq 0 ]]
+  [[ "$output" == "2" ]]
+}
+
+@test "a value-taking interpreter flag before -c is stepped over correctly" {
+  real_python3_or_skip
+  run env PATH="$REAL_PATH" "$SHIM3" -X utf8 -c 'print(1+1)'
+  [[ $status -eq 0 ]]
+  [[ "$output" == "2" ]]
+}
+
+@test "a flag before a script path still refuses" {
+  run "$SHIM3" -u script.py
+  [[ $status -ne 0 ]]
+  [[ "$output" == *"uv run python"* ]]
+}
+
+@test "a flag before -m pip still refuses" {
+  run "$SHIM3" -u -m pip install foo
   [[ $status -ne 0 ]]
   [[ "$output" == *"uv add"* ]]
 }
+
+@test "exits 127 with error when the real interpreter is not found" {
+  # A PATH holding the shim and nothing else cannot test this: the shebang is
+  # `/usr/bin/env bash`, so env exits 127 looking for bash and the shim never runs —
+  # the right status for the wrong reason. Give it bash and no python3.
+  local only_bash="$BATS_TEST_TMPDIR/only-bash"
+  mkdir -p "$only_bash"
+  ln -sf "$(command -v bash)" "$only_bash/bash"
+  [[ ! -x "$only_bash/python3" ]]
+
+  run -127 env PATH="${BATS_TEST_DIRNAME}:$only_bash" "$SHIM3" -c 'print(1)'
+  [[ "$output" == *"real python3 binary not found"* ]]
+}

plugins/modern-python/hooks/shims/uv

@@ -4,7 +4,24 @@ set -euo pipefail
 # PATH shim for uv — intercepts `uv pip` (legacy interface) and passes
 # everything else through to the real uv binary.
 
-if [[ "${1:-}" == "pip" ]]; then
+# Flags that mean a tool is building an environment it owns, rather than a person
+# managing this project's dependencies. `uv add` is not the right advice there: prek
+# installs every hook with `uv pip install --project / --directory <cache>`, and there
+# is no project to add to. Refusing it broke `git commit` in any repo whose hooks need
+# a Python environment, which is half of #207.
+uv_pip_is_tool_managed() {
+  local arg
+  for arg in "$@"; do
+    case "$arg" in
+      --project | --project=* | --directory | --directory=* | --target | --target=* | -t | -t=*)
+        return 0
+        ;;
+    esac
+  done
+  return 1
+}
+
+if [[ "${1:-}" == "pip" ]] && ! uv_pip_is_tool_managed "$@"; then
   echo "ERROR: \`uv pip\` is the legacy interface. Use instead:" >&2
   echo "  uv add <package>       # instead of uv pip install" >&2
   echo "  uv remove <package>    # instead of uv pip uninstall" >&2

plugins/modern-python/hooks/shims/uv-shim.bats

@@ -2,6 +2,8 @@
 # Tests for uv PATH shim
 # Requires: nix shell nixpkgs#uv -c bats ...
 
+bats_require_minimum_version 1.5.0
+
 SHIM="${BATS_TEST_DIRNAME}/uv"
 
 setup() {
@@ -38,10 +40,37 @@ setup() {
   [[ "$output" == *"uv"* ]]
 }
 
+# `uv pip` carrying one of these is a tool building an environment it owns, not a person
+# managing project dependencies — `uv add` is not the advice it needs. prek installs
+# every hook this way, and refusing it broke `git commit` in any repo whose hooks need a
+# Python environment. See #207.
+@test "allows uv pip when --directory says a tool owns the environment" {
+  run "$SHIM" pip list --directory /tmp
+  [[ "$output" != *"legacy interface"* ]]
+}
+
+@test "allows uv pip when --project says a tool owns the environment" {
+  run "$SHIM" pip install --project / --help
+  [[ "$output" != *"legacy interface"* ]]
+}
+
+@test "allows uv pip when --target says a tool owns the environment" {
+  run "$SHIM" pip install --target /tmp/nowhere --help
+  [[ "$output" != *"legacy interface"* ]]
+}
+
+# `uv pip install --help` documents `-t, --target <TARGET>`, so the short form has to be
+# exempt too — otherwise the same install is allowed or refused depending on spelling.
+@test "allows uv pip when the short -t names the target" {
+  run "$SHIM" pip install -t /tmp/nowhere --help
+  [[ "$output" != *"legacy interface"* ]]
+}
+
 @test "exits 127 with error when real uv is not found" {
-  # Include /usr/bin for coreutils but exclude dirs with a real uv
+  # Include /usr/bin for coreutils but exclude dirs with a real uv.
+  # `run -127` declares the expected status, which is what this asserts; without it
+  # bats warns (BW01) that a 127 looks like a command that was not found by accident.
   local path_no_uv="${BATS_TEST_DIRNAME}:/usr/bin:/bin"
-  run env PATH="$path_no_uv" "$SHIM" --version
-  [[ $status -eq 127 ]]
+  run -127 env PATH="$path_no_uv" "$SHIM" --version
   [[ "$output" == *"real uv binary not found"* ]]
 }