Problem
The shell-config command-safety layer blocks pip, pip3, python, and python3 in favour of uv. This is correct — but AI agents (Claude Code, Codex, etc.) running in this environment don't know about it ahead of time.
The current failure loop:
- Agent generates
pip install <pkg> or python3 script.py
- Command is blocked by the safety layer
- Agent reads the error, re-generates with
uv / uv run
- ~2-4 extra LLM turns and extra tokens wasted per occurrence
This is a multi-layered-defence problem — the git hook and command safety correctly block, but the agent needs to be told upfront so it never generates the wrong command in the first place.
Proposed Fix
Add shell-config-specific guidance to CLAUDE.md and AGENTS.md (both are read by their respective agents at session start):
## Python tooling
- ALWAYS use `uv` instead of `pip`, `pip3`, `python`, or `python3`
- Run scripts: `uv run script.py` (not `python3 script.py`)
- Install packages: `uv add <pkg>` or `uv pip install <pkg>`
- Direct `pip`/`python3` calls are blocked by command-safety and will fail
Similarly for Node:
## Node/JS tooling
- ALWAYS use `bun` instead of `npm`, `yarn`, `pnpm`
- Direct `npm`/`yarn`/`pnpm` calls are blocked and will fail
Why this matters
This is a token-efficiency issue at scale. An agent doing 20 Python operations in a session could waste 40-80 extra turns just from pip→uv retries. The CLAUDE.md/AGENTS.md fix is zero-cost prevention.
The git pre-commit hook is the right last-line-of-defence. The agent guidance is the first line.
Problem
The shell-config command-safety layer blocks
pip,pip3,python, andpython3in favour ofuv. This is correct — but AI agents (Claude Code, Codex, etc.) running in this environment don't know about it ahead of time.The current failure loop:
pip install <pkg>orpython3 script.pyuv/uv runThis is a multi-layered-defence problem — the git hook and command safety correctly block, but the agent needs to be told upfront so it never generates the wrong command in the first place.
Proposed Fix
Add shell-config-specific guidance to
CLAUDE.mdandAGENTS.md(both are read by their respective agents at session start):Similarly for Node:
Why this matters
This is a token-efficiency issue at scale. An agent doing 20 Python operations in a session could waste 40-80 extra turns just from pip→uv retries. The CLAUDE.md/AGENTS.md fix is zero-cost prevention.
The git pre-commit hook is the right last-line-of-defence. The agent guidance is the first line.