Fixing Broken Agent Toolchains: Diagnosing Pyenv Shims and Terminal Path Traps

Description and use

Autonomous agents frequently run commands in non‑interactive subshells, causing them to use the wrong Python binary and trigger pyenv errors. By creating a wrapper that explicitly sets PYENV_ROOT, updates PATH, and executes the correct python, tool execution becomes deterministic.

Problem

Autonomous coding agents often run non‑interactive subshells that inherit the wrong Python binary, leading to errors like "pyenv: version not installed" or crashes of tools such as pytest and ruff.

Outcome

By wrapping the Python binary and explicitly resolving the local .python-version, agents consistently use the intended Python environment, eliminating shim hijacking and related errors.

Workflow

• 1. Run diagnostic probes: bash -c 'which python && pyenv which python 2>/dev/null || which -a python' and bash -c 'echo "PYENV_VERSION: ${PYENV_VERSION:-<unset>}"; echo "PATH: $PATH"' to inspect active path and PYENV_VERSION.
• 2. Create a wrapper script at ./.agent/bin/python with shebang #!/usr/bin/env bash, set -euo pipefail, export PYENV_ROOT and PATH, eval pyenv init, resolve TARGET_PYTHON via pyenv which python, and exec the target with passed arguments.
• 3. Make the wrapper executable with chmod +x ./.agent/bin/python.
• 4. Configure the agent’s command execution environment (e.g., .aider.conf.yml) to invoke tools through the wrapper, e.g., test-cmd: "./.agent/bin/python -m pytest tests/".
• 5. For high tooling load, optionally set up a multi‑model failover relay gateway to avoid LLM rate limits while maintaining the pyenv sandbox.

Evidence

When an agent spins up a non-interactive bash or zsh session to run a test runner, build harness, or linter, it frequently invokes the wrong Python binary or fails with cryptic pyenv: version not installed errors.

Source

Create a helper wrapper at ./.agent/bin/python: ... # Resolve local .python-version explicitly ... exec "${TARGET_PYTHON}" "$@"

Source