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

说明与用途

自主编码代理经常在非交互式子 shell 中执行命令，导致使用错误的 Python 解释器并触发 pyenv 错误。通过创建一个显式设置 PYENV_ROOT、更新 PATH 并执行正确 python 的包装器，可以使工具执行变得确定性。

问题

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.

结果

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.

工作流

• 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.

证据

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.

来源

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

来源