[Critical] CLI command conflict: old starter toolkit silently overrides new CLI - detection and guidance is insufficient

[DennisTraub]

Problem

Any customer who previously installed the old starter toolkit and then installs @aws/agentcore without first reading the README migration note will silently end up running the old Python CLI instead. There is no error, no warning, and no indication anything is wrong. They will have a degraded experience and no way to know why - the two CLIs are similar enough that recognizing the difference requires familiarity with both tools.

The old Bedrock AgentCore Starter Toolkit (bedrock-agentcore-starter-toolkit) and the new CLI (@aws/agentcore) both install a binary called agentcore, inevitably creating a naming conflict.

The only existing mitigation is the README in this repository, instructing users to run pip uninstall bedrock-agentcore-starter-toolkit before installing. There is a preinstall hook that should warn about an existing agentcore binary.

However:

1. The preinstall warning is invisible. npm 8+ hides lifecycle script output when the script succeeds. Since this CLI requires Node 20+, every user is on npm 8+ or later, so the current warning (which exits 0) is never seen.

2. The detection itself is brittle. The preinstall hook relies on PATH-based detection (command -v agentcore / where agentcore) and a --version flag heuristic, which depends on PATH state and binary behavior varying across operating systems.

3. The mitigation only exists in this repository's README. There is no way to enforce that tutorials, sample repositories, blog posts, or any other content produced outside of this repository includes this warning. Affected customers who follow external installation instructions will inevitably run into this problem with no indication of what went wrong.

4. Even customers who read the README may still be affected. The uninstall guidance only covers pip uninstall. The old toolkit can also be installed via pipx or uv tool install, and pip uninstall does not remove packages installed through those tools. Users who installed via pipx or uv and follow the documented guidance will still unknowingly run the old CLI.

Reproduction

# Install old toolkit via uv tool or pipx
uv tool install bedrock-agentcore-starter-toolkit
# or: pipx install bedrock-agentcore-starter-toolkit

# Follow new CLI installation instructions
npm install -g @aws/agentcore

# Result: old CLI runs, new CLI is shadowed
which -a agentcore
# <python-or-uv-path>/agentcore    <- old Python CLI
# <npm-global-bin>/agentcore       <- new Node CLI

Current State

Install method	Preinstall warning visible?	pip uninstall resolves it?
pip install	No - hidden by npm 8+	Yes
pipx install	No - hidden by npm 8+	No
uv tool install	No - hidden by npm 8+	No

Proposed Fix

1. Abort installation when old toolkit is detected. npm 8+ hides lifecycle script output when scripts succeed, but does show stderr when scripts fail. Change the preinstall hook to exit non-zero, which makes the error message visible and blocks installation until the conflict is resolved.

2. Replace PATH-based detection with package-manager queries (pip list, pipx list, uv tool list) to reliably detect the old toolkit and identify the actual install method, so the error message shows the correct uninstall command.

3. Provide an override via environment variable (AGENTCORE_SKIP_CONFLICT_CHECK=1) for users who understand the PATH implications and want to install anyway.

4. Update README - move the migration note before the install command, cover pip, pipx, and uv tool uninstall paths.

Acceptance Criteria

• Preinstall hook aborts installation with a visible error message when old toolkit is detected
• Error message shows the correct uninstall command for the detected install method (pip, pipx, or uv)
• No false positives on upgrade or clean install
• AGENTCORE_SKIP_CONFLICT_CHECK=1 bypasses the check
• Integration tests verify the full detect - uninstall - verify-clean cycle for each install method (pip, pipx, uv)
• README covers all three uninstall methods, placed before the install command