Adapter contract
ProviderAdapter is synchronous, Send + Sync, and describes detection, capability reporting, permission mapping, launch and resume plans, event decoding, and shutdown. Optional capture and handoff hooks default to typed unsupported results.
The adapter must not spawn processes, own transport execution, write native settings, read credentials, or keep per-run mutable state outside its decoder.
Agents found on the machine
No agent is known by name. The programs on the search path are read, and a program whose --help describes a coding agent becomes an adapter. The id is the name of its program without the extension, and what the adapter can do depends on what the help lists:
| What the adapter can do | Learned from |
|---|---|
| Start with a first prompt | An option that starts an interactive session with a prompt, or a positional argument for it. |
| Resume a given session | An option that takes a session id, or a resume subcommand that takes one. |
| Continue the latest of the folder | A switch such as “continue”, or resume with its “last” flag. |
| Choose the session id at start | An option for the session id. Then the id is known, and resume uses it. |
| Start in a subcommand | A top level help that lists a subcommand whose own help describes the conversation. |
| Set permissions | A skip-everything flag, a mode flag with named choices, or sandbox and approval flags. |
See Providers & plugins for how the lookup works, and Sessions & resume for what uuldana-cli does when the session id is not known. A manifest in the adapters directory describes a provider by hand and wins over what was learned for the same id.
Permission mappings never claim a restriction the program’s flags do not enforce.
Capability evidence
| Support | Meaning |
|---|---|
Supported |
A capability statement with an evidence level. |
Unsupported |
Explicitly unavailable. |
Unknown |
Not established; never satisfies a requirement. |
Evidence precedence is Declared < Probed < Negotiated. Equal or stronger observations can replace declarations. Transport constraints apply last, so even a declaration cannot claim native terminal UI over ACP.
Registry and discovery
The registry accepts adapters, verifies the contract version, and rejects duplicate ids or an empty transport set. HostProbe supplies read-only executable discovery, short bounded commands, environment lookup, and platform information.
The command line registers every provider manifest found in the adapters directory next to config.json, then the agents learned on the machine (a learned agent is skipped when a manifest has the same id). A manifest that cannot be used is reported as adapter not loaded and never hides the others. See Provider SDK for the manifest format.
Compatibility is per installation
Detection and probed capabilities reflect the installed agent version. No provider order, account model, CLI mode, permission flag, or session feature is universally valid across agents.