Module askpass 

The SSH askpass bridge (spec §5.3 of SPEC_REMOTE_TERMINALS_AND_DURABLE_SESSIONS_2026_10_02.md).

When an agent runs something over SSH there is no terminal for ssh to ask a password, a passphrase or a new host key in, and the agent must never see or answer one. So that ssh runs with SSH_ASKPASS pointing at agentmux-bashwrap and SSH_ASKPASS_REQUIRE=force: every prompt goes to bashwrap, which asks srv, which shows it to the user in a dialog, and the answer goes straight back to ssh.

Who may ask is the security question: every agent holds srv’s auth key, so a route open to that key alone would let an agent pop a fake “password” dialog and read what the user types. Each such ssh therefore gets its own secret, in its own environment and nowhere else; the askpass route answers only a live secret, and the secret decides which agent and host the dialog names. It is revoked when that ssh exits.

What the secret does not do: prove the prompt text is ssh’s. A process running as the same OS user can read another process’s environment (/proc/<pid>/environ on Linux) and so post a prompt of its own under a live secret. That is the residual AgentMux accepts elsewhere (a same-user process reading other processes’ memory is machine compromise; such a process could read ~/.ssh directly), so the dialog says plainly that the prompt is relayed and unverified, and asks the user to answer only when they expect ssh to be asking.

Structs

AskpassGrant

What a secret was issued for.

Revoke

Revokes its secret when dropped: held by whatever waits for the ssh, so every way that ssh ends (exit, failed spawn, stop) ends the secret too.

Enums

PromptKind

How a prompt is answered.

Constants

ENV_SECRET

Where bashwrap finds the secret; set only on the ssh it belongs to.

META_KEY_AGENT

META_KEY_AGENT_BLOCK

Block meta on an agent’s SSH PtyShell: the agent’s pane and name. Its ssh then gets an askpass secret (blockcontroller::shell::lifecycle), so its prompts go to the user, never to the terminal the agent reads.

Functions

classify

What kind of answer prompt wants. hint is ssh’s own SSH_ASKPASS_PROMPT (OpenSSH 8.4+): confirm is yes or no, none a notice; without it, a (yes/no in the text is yes or no and anything else secret.

digest 🔒

Stored by digest, so a timing difference in the lookup says nothing about how much of a guessed secret matches a real one.

grant

Issue a secret for one ssh run.

lookup

What secret was issued for, while its ssh runs.

program

The askpass program, agentmux-bashwrap: the bundled one, or (a dev build) the one beside srv, or the first on PATH.

registry 🔒

revoke

End a secret: its ssh exited.

ssh_env

The environment the ssh gets: askpass for every prompt, with its secret, and how bashwrap reaches srv.