Is command shims apply to the entire system or can it be refactored to configurable?

[HackingGate]

Propose a scope, is configurable per-repo good? If a repo not configured with uphold, pass the original command and parms as-is.

Review the design also...
How other open source project such as uv design and handle shims system?
Activate a venv first? Must call command prefix? Will AI agents call prefix?

[HackingGate]

The defect half is in #31: an unreadable policy used to block the very git checkout that would repair it, and UPHOLD_ALLOW=all is read before the policy now. This comment answers the design question.

What the scope actually is today

Two different things get called "the shim", and separating them answers most of the question.

The link is machine-wide. A file named git on PATH ahead of the real one is reached by every git that shell runs, in every directory, forever. That is a property of PATH, not of this tool.

What it DOES is already per repository, and already opt-out by absence. The binary discovers policy/principles.toml from the working directory upward, stopping at the repository boundary. With no policy -- /tmp, somebody else's checkout, a shell that never enters a participating tree -- it execs the real command and gets out of the way. Verified: git status in a directory with no policy runs git, exit 0, nothing printed.

So the answer to "if a repo is not configured with uphold, pass the original command as-is" is that this is what happens, and it is deliberate: refusing there protects nothing, breaks git everywhere, and gets the link removed -- which loses the seam in the repositories that DID declare it. The source comment at that branch says exactly this, and it is the right reasoning.

What remains is narrower than "system-wide or configurable": the cost of the link is one process exec on every invocation of a shimmed command, everywhere, forever, to find a policy that usually is not there.

How other tools handle the same problem

• uv, rustup, pyenv, volta put shims in a directory the user adds to PATH, and the shim resolves a version from the tree. Same shape as this: machine-wide reach, per-tree behaviour. None of them asks for a prefix.
• direnv, mise hook the SHELL rather than PATH: a per-directory change applied on cd, so nothing intercepts anything outside a participating tree. This is the "activate first" shape.
• pre-commit and lefthook install into .git/hooks, which is per repository and reaches only what git itself runs -- and is exactly why the shim exists: gh pr create, npm publish and a branch name are not things git runs.
• A prefix (uphold shim gh pr create ...) is what this binary already supports directly, and it is the shape that fails at the one job the seam has. The invocation nobody remembers to prefix is the invocation that publishes something unchecked -- which includes every agent, script and muscle-memory gh pr create on the machine.

The proposal

Keep the current default and make the reach a decision somebody writes down:

1. A directory of links rather than links scattered on PATH. ~/.local/uphold/shims/, one link per shimmed command, added to PATH by the operator. That makes the whole seam one PATH entry to add, inspect, or drop, and ls answers "what am I standing in front of".
2. A shell hook as an alternative install, in the direnv shape, for whoever wants the shims to exist only inside participating trees. The mechanism does not change -- the same links, on PATH only where a policy is found.
3. Nothing per repository beyond the policy that already exists. A repository cannot decide whether a link on somebody else's PATH is reached; it can decide what happens when it is, and that is the [[shim]] block it already writes.

What should NOT be built, on the same argument the tool makes everywhere else: a mode where the shim is silent about doing nothing. A shim that finds no policy and passes through is right; a shim that finds one and decides not to look because a setting said so is a check that did not happen, reported as a pass.

On AI agents, since the issue asks

An agent runs gh pr create because that is what its instructions say. It will not prefix, and it will not read a note asking it to -- which is the argument FOR the PATH link rather than against it: the seam has to be in the path of the invocation somebody forgot about, and an agent is the most reliable producer of those. This session is the evidence: every pull request in this fleet today went through uphold shim gh pr create, and one was refused for naming a private organisation in a body headed for a public repository.