feat(secret-prompt): ask the release manager for an upload token without exposing it

[potiuk]

What we are asking for

Please review and accept:

1. A new tool, tools/secret-prompt/ (substrate:release, stdlib-only Python). It asks the release manager for a secret and execs one command with it in one environment variable:

   secret-prompt --env TWINE_PASSWORD --set TWINE_USERNAME=__token__ --prefix pypi- -- twine upload dist/*
   

   It asks in the terminal when there is one, and otherwise through a macOS osascript dialog, zenity/kdialog on a Linux desktop, or pinentry.
2. A recommendation, not a requirement: adopters declare credentialed stage_command/publish_command entries wrapped in it. This goes in the release-build.md template, the promote skill's convenience-artefacts.md and the release-management spec. The skills still render those commands verbatim and never ask for or handle the token themselves.

We are not asking to change how any skill behaves, to add a dependency, or to store a credential anywhere.

Why

Release steps like the PyPI upload need a credential only the release manager holds. When an agent runs the step on their behalf, or a script has no terminal, read -s has nowhere to prompt. The token then ends up in a file or on a command line, and from there in shell history, ps or the agent's transcript. This came up during Apache Airflow's 2026-10 providers waves: three PyPI uploads (two final, one rc) ran from an agent session using exactly this osascript hidden-answer dialog, with the token never written down.

Guarantees

• The secret reaches only the one command's environment, through exec, so that command keeps its exit status.
• Nothing runs unless a non-empty secret matching --prefix arrives; cancelling runs nothing.
• Error messages name only the expected prefix, never what was entered.
• Every prompt ends with what the caller can't change: "It will be passed to:" the command, resolved to an absolute path before asking and run exactly as shown, and "with:" every --set variable plus any inherited variable sharing the secret's prefix (TWINE_* for TWINE_PASSWORD, so a TWINE_REPOSITORY_URL pointing elsewhere is visible). An agent picks the command, so this is what stops a look-alike prompt from handing the token to something that prints or forwards it.
• Those lines can't be faked. The command is shown in full or refused (over 1000 characters). Arguments, values and inherited names with a newline, escape sequence or bidi character are refused before anything is asked. --prompt/--title must be one plain line. zenity/kdialog decline text they might render as markup.
• An inherited value is shown only when its name routes the secret (*_URL, *_HOST, *_REPOSITORY, *_INDEX, *_USERNAME, *_CERT, …) and has nothing credential-like in it. Every other value is listed as NAME=(set; value not shown), since a dialog receives the prompt in its argv. That way a credential under an unexpected name stays hidden. A URL always shows its host, so where the secret may go is never hidden: under a routing name up to its path, otherwise as scheme://host/***. --set values are shown as given.
• Nothing is asked when an inherited variable can't be shown safely. That covers a URL carrying a user or password, a routing value that may hold a credential (user:pw@proxy, alice:s3cret, host/simple?token=…), a value too quoted to parse, and a credential-named variable that also changes how the command runs (an *_ASKPASS). The error names the variable to unset.
• --env/--set refuse names that change how the command runs (PATH, HOME, LD_*, DYLD_*, PYTHON*, NODE_* except NODE_AUTH_TOKEN, GIT_*, …).
• Not covered: an environment the caller already controls, such as an LD_PRELOAD or a ~/.pypirc set up beforehand. The README says so.

Testing

70 tests run without a real dialog. They cover:

• backend selection, the run gates, and the cancel-versus-failure fallback;
• a forced backend that isn't installed, and zenity with a stale display;
• AppleScript receiving the prompt after --;
• the pinentry protocol, against a fake pinentry;
• each refusal above, the resolved-path prompt and inherited-value hiding;
• an end-to-end run checking that the secret appears in none of the output.

ruff and mypy are clean, and the full workspace-pytest hook passed on the first commit.

Cross-references are refreshed: the capability map row, plus the regenerated docs/vendor-neutrality.md and .github/labeler.yml. The release-management-lifecycle spec is updated with a new behaviour bullet.

---

Was generative AI tooling used to co-author this PR?

• Yes — Claude Code (Opus 5)

Generated-by: Claude Code (Opus 5)