Python on this machine — the reasons

The hard rules live in ~/.claude/CLAUDE.md. This skill holds the measurements behind them, so that a future session does not re-derive the wrong belief from the same evidence and "fix" something that is already correct.

Decided 2026-08-17.

No pyenv — ~/.pyenv does not exist and must not come back. No development Python from Homebrew. No pip install into a system interpreter.

The enforcement lives in uv.toml, and that is the whole point

~/.config/uv/uv.toml sets python-preference = "only-managed". That is what actually enforces uv-only Python: uv then refuses a system interpreter outright.

It is deliberately not in ~/.zshrc. A shell export reaches interactive shells only — a LaunchAgent and a cron entry never source .zshrc — so setting it there leaves it unset in exactly the place a wrong interpreter would be invisible.

uv's default without the setting is "prefer managed, but fall back to a system Python if no managed one is installed", so the gap is real rather than theoretical. env-drift-check.py's uv run --script shebang runs under the vigie LaunchAgent and picks correctly today only because managed 3.11/3.12/3.13 happen to be installed.

The falsifying control that was actually run. uv discovers ~/.config/uv/uv.toml on every invocation regardless of shell. Verified with a probe file set to only-system: that flipped uv python find to Homebrew's 3.14 with no env var set, and the same run without the file did not. The check was made to produce the opposite answer before its silence was trusted.

Note UV_PYTHON_PREFERENCE is absent from uv 0.12.5's --help, which documents UV_MANAGED_PYTHON instead. The old var is still parsed, but the config key is the stable form — write the config key.

Homebrew's python@3.14 stays installed, and that is not a loophole

It is installed_on_request=false — its dependents are whatever brew uses --installed python@3.14 prints. brew uninstall python@3.14 takes those with it.

So the rule is "Homebrew Python is a library dependency of Homebrew formulae, never a development interpreter", not "no Homebrew Python exists". Do not try to remove it. Do not file its presence as a finding.

Why a bare python3 is dangerous rather than merely untidy

There is no bare python and no bare pip on PATH at all. Any doc or script saying python -m venv / pip install -e . is already broken, not merely unfashionable. Several were, and were fixed in the same change.

A bare python3 resolves to /opt/homebrew/bin/python3 — the dependency interpreter above — with Apple's /usr/bin/python3 (3.9.6) behind it.

Measured: 3.9 runs a stdlib-only snippet fine. So an interpreter swap under a scheduled job would be invisible until something used 3.10+ syntax. That is the reason nothing in ~/.claude/scripts/ or ~/.claude/hooks/ calls a bare python3 any more — not tidiness, a silent-failure mode.

In a hook, the answer is usually jq, not uv

All four hooks were reading JSON fields with python3; secret-scan alone spawned an interpreter three times per invocation, on every Write and every Edit.

A field lookup needs no interpreter at all, and /usr/bin/jq ships with macOS, so it resolves under any PATH a hook can inherit. Routing a per-keystroke hook through uv run would have been strictly worse than the problem it solved.

Keep Python only where a real language is required — push-build-gate's env-prefix parser and payload_gate.py — and there resolve the interpreter once, after the hook's cheap pre-filter, with the same resolver the scripts use.

Never launch payload_gate.py via uv run. hook.sh reads exit 2 as block the push and exit 3 as warn. A launcher that can emit its own failure codes into that channel can manufacture a verdict.

A hook that cannot resolve its interpreter fails OPEN, loudly — exit 1, the only non-blocking code whose stderr the owner actually sees. Fail closed on the guard's verdict; fail open on the guard's own malfunction.

The three invocation patterns

• Per-project: uv sync. Creates .venv, installs from uv.lock, installs the project. Commit the lockfile.
• One-off tooling with a requirements file: uv run --with-requirements. No venv, no install step, cached after first use.
• A standalone script: a PEP 723 header and a #!/usr/bin/env -S uv run --script shebang, then executed directly. Never invoke such a script as python3 script.py — that bypasses the shebang, which is the single place its interpreter and dependencies are declared. That exact bug was live in vigie's env-drift collector until 2026-08-17.

The editable-install trap

uv sync installs the project editable by default. That is the configuration behind the MultiplexedPath / NotADirectoryError break in midas-core: importlib.resources.files() on a package with no __init__.py dies once any editable install exists, and the wheel path hides it.

Re-run the single-directory assertion after any move to uv sync — the editable finder's tables are frozen at install time.

A public repo keeps its pip path

claude-code-setup documents both: uv for the owner, requirements.txt for anyone cloning it. Do not force uv on readers of a published repo.