Close the MCP tool surface and remove the plaintext passphrase cache

[vvillait88]

Summary

Closes AS-006 and the passphrase half of AS-011 from the Q3 2026 penetration test. They are one chain: the dangerous MCP tools all need the keystore passphrase, and the plaintext cache is what supplies it unattended.

AS-006, the MCP tool surface. It is generated from the CLI's command definitions, so every command reaches agents by default. Served as tools, the CLI's safety gates stop meaning anything: --danger and the typed EXPORT confirm become boolean parameters the model sets for itself, and whatever they guard is returned into the transcript and the model provider's logs. wallet create, wallet show-mnemonic, wallet export, wallet remove, send and unlock are now hidden from MCP clients while remaining on the CLI, where a human is present.

Two commands were checked and deliberately left exposed, on what they actually return rather than their names: init creates wallets but its result carries only chain lists and flags, never the mnemonic, and wallet import takes a secret in rather than handing one out.

Spend limits now apply to send (the reporter's step 7). They were enforced on the 402 paths only, so a configured ceiling could be walked past with a raw transfer. USDC only: a native transfer moves gas tokens this command does not price in dollars, and inventing a conversion would be a worse guess than not claiming one.

AS-011, the plaintext passphrase cache. ~/.agentscore/.unlock held the passphrase in cleartext for up to 8 hours beside the keystores it unlocks, with file modes as the only protection, which stop nothing already running as that user. The unlock command and the read path are both gone.

An installation upgrading from a version that wrote the file gets it deleted rather than ignored. Ignoring it is the worst of the three options: the secret stays on disk with nothing left that admits to using it.

Type of change

• Bug fix (no breaking change)
• New feature (no breaking change)
• Breaking change (existing callers must update)
• Docs, tests, or internal maintenance only

Breaking on two surfaces, both deliberate. The unlock command is removed, and six tools no longer appear over MCP.

Public API

CLI: unlock is gone. Anyone who used it for interactive convenience now either exports AGENTSCORE_PAY_PASSPHRASE or types the passphrase per command. The no-TTY error explains this rather than suggesting the removed command. All other commands are unchanged, including the six hidden from MCP.

MCP: wallet_export, wallet_show-mnemonic, wallet_create, wallet_remove, send and unlock now return Unknown tool. That is the intent of the finding.

send gains a spend-limit check, a no-op unless limits.json sets one.

Test plan

bun run lint, bun run typecheck, bun run knip clean. bun run test: 57 files, 574 tests passing.

The agent fleet is unaffected, verified by running its exact sequence rather than reasoning about it. Our GTM agent shells agentscore-pay balance and agentscore-pay pay --chain tempo --max-spend N with AGENTSCORE_PAY_PASSPHRASE exported into its sandbox. Run non-interactively with only that variable set, init creates all three wallets and balance returns them, and no cache file is written. It never starts an MCP server, and prompts.ts checks the environment before it ever touched the cache, so neither change reaches it.

The surface test drives a real MCP handshake. Two earlier versions were unsound and are worth recording: grepping for mcp: false would pass whether or not the flag reached the tool list, and walking the Cli object does not work because incur builds it as a closure with no command map. It carries a positive control, so an empty handshake cannot read as success. Verified live against the reporter's steps: get_tool_details returns Unknown tool for all five named tools, and search_tools for "export" and "unlock" returns empty where it previously returned the wallet tools.

Three guards were drilled: un-hiding wallet export and send fails the surface test naming each tool; removing the enforce block fails the limit test; and restoring the cache read leaves the leftover file on disk, which the removal test catches.

Two test files changed for reasons worth stating. The error-envelope suite used unlock --for bad-format as a convenient bare invalid_input and now uses assess with no identity, which raises the same shape. tests/unlock-cmd.test.ts is deleted with the command it covered.

Checklist

• Tests cover the new behavior, and the suite passes locally
• Lint, format, and type checks pass
• Docs and README examples updated if the public surface changed
• No secrets, credentials, or personal data in the diff or the tests