A driver connects Steery to one harness. A harness is an agent product
in which a person runs conversations. The Steery runtime starts a driver as a child process.
The runtime speaks the program protocol to the driver: JSON-RPC 2.0 over standard input and
output (PROTOCOL.md in steery-dev/sdk). The driver does
these things:
- reads the harness's conversations
- plans what the setup of the harness writes
- says how to start, read and resume a turn
The driver decides nothing and writes nothing of its own. The runtime itself names no harness. A driver tells the runtime everything that the runtime knows about a harness.
Each driver is its own program, steery-driver-<id>, built on the steery-sdk crate. A driver
answers with the newest version of the program protocol that the runtime offers, of those in
PROTOCOLS (common/src/program.rs), which also says what each version adds. Every runtime
that Steery supports offers the oldest of them. The driver keeps the version that it picked.
Steery adds the drivers below in the same way as it adds any program: from this repository's
releases. Each release has a prebuilt executable per target. The command is
steery programs add https://github.com/steery-dev/drivers, and Steery's installer runs it.
Everything that a person sees of a driver comes from its initialize answer: its label, its
short name, its tint and its mark.
| Driver | Harness | Crate | Levels |
|---|---|---|---|
omp |
omp | pi-family |
observe, drive, live (Steery's plugin door) |
pi |
pi | pi-family |
observe, drive, live (Steery's plugin door) |
claude-code |
Claude Code | claude-code |
observe, drive, live (Claude Code's inbox) |
codex |
Codex | codex |
observe, drive, live (Codex's own doors: picks) |
grok |
Grok Build | acp-family |
observe, drive, live (Grok's leader: picks) |
opencode |
OpenCode 2 | acp-family |
observe, drive, live (Steery's plugin door) |
hermes |
Hermes Agent | acp-family |
observe, drive, live (Hermes's gateway: picks) |
kilo |
Kilo | acp-family |
observe, drive, live (Steery's plugin door) |
copilot |
Copilot | acp-family |
observe, drive, live |
cursor |
Cursor | acp-family |
observe, drive |
cline |
Cline | acp-family |
observe, drive, live |
goose |
Goose | acp-family |
observe, drive |
amp |
Amp | amp |
observe, drive, live (Steery's plugin door) |
gemini |
Gemini CLI | acp-family |
observe, drive, live (Steery's plugin door) |
qwen |
Qwen Code | acp-family |
observe, drive, live (Qwen's own door, qwen serve: picks) |
antigravity |
Antigravity | acp-family |
observe, drive, live (Antigravity's own door: keeps) |
openclaw |
OpenClaw | acp-family |
observe, drive, live (OpenClaw's gateway: picks) |
droid |
Droid | acp-family |
observe, drive |
kiro |
Kiro CLI | acp-family |
observe, drive |
openhands |
OpenHands | acp-family |
observe, drive |
crush |
Crush | crush |
observe, drive, live (Crush's server: keeps) |
warp |
Warp | warp |
observe |
aider |
Aider | aider |
observe, drive |
Each crate is a Cargo workspace of its own, with its own Cargo.lock. Thus each crate builds
alone. The drivers share the common crate, steery-driver-common. Each driver
names it by path (../common). The common crate has these modules:
program: finds the harness's executable and asks its release, with a bounded probe that it kills past its bound.lines: reads a transcript's lines within bounds.follow: reads a file that its writer only appends to, from the point where the last read stopped.tree: keeps a transcript that is a tree of records between reads. It reads the transcript along its path in batches. Then it reads the records off the path, within the same bound.login: runs the harness's own sign-in on a terminal of the driver's (see Signing in).gateway: checks a company gateway's address, and tries its key once, in the header that the person named, throughcurlwithin 8 s (see Claude Code, Needs).
Each driver keeps only two things: how its harness's records name their parent, and what the records say.
A driver looks for its harness's executable in two places, in this order:
- On
PATH. - In the folder where the harness's own installer writes it. A shell that did not read its
profile after the install possibly does not have this folder on
PATH.
setup/plan gives the executable it found as found.binary. Every later start runs this
executable. When the driver does not find the harness, setup/plan answers install. This is
the vendor's own installer. steery setup shows it whole, and runs it only after the person
agrees (PROTOCOL.md §4.1).
| Driver | Installer folder | install (offered where its shell and curl are on PATH) |
|---|---|---|
omp |
PI_INSTALL_DIR, else ~/.local/bin |
sh -c "curl -fsSL https://omp.sh/install | sh -s -- --binary" |
pi |
its agent folder's bin (~/.pi/agent/bin) |
sh -c "curl -fsSL https://pi.dev/install.sh | sh". Offered only where npm is here and node --version names 22.19 or newer within 5 s. Else refused, with the requirement that is missing. |
claude-code |
~/.local/bin |
bash -c "curl -fsSL https://claude.ai/install.sh | bash" |
codex |
CODEX_INSTALL_DIR, else ~/.local/bin |
sh -c "curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_NON_INTERACTIVE=1 sh" |
grok |
~/.grok/bin |
bash -c "curl -fsSL https://x.ai/cli/install.sh | bash" |
copilot |
~/.local/bin |
bash -c "curl -fsSL https://gh.io/copilot-install | bash" |
opencode |
~/.opencode/bin |
bash -c "curl -fsSL https://opencode.ai/v2/install | bash -s -- --no-modify-path". OpenCode 2 only: an opencode that names a 1.x release does not count as found, and a note names it. |
cursor |
~/.local/bin |
sh -c "curl -fsS https://cursor.com/install | bash" |
amp |
AMP_HOME/bin, else ~/.amp/bin (and its link ~/.local/bin/amp) |
bash -c "curl -fsSL https://ampcode.com/install.sh | bash" |
cline |
npm's global folder | npm install --global cline, offered where npm is on PATH |
goose |
GOOSE_BIN_DIR, else ~/.local/bin |
bash -c "curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | CONFIGURE=false bash", offered where bash, curl and tar are on PATH |
gemini |
npm's global folder (npm prefix -g) |
npm install -g @google/gemini-cli. Offered only where npm is here and node --version names 20 or newer within 5 s. Else refused, with the requirement that is missing. |
qwen |
npm's global folder (npm prefix -g) |
npm install -g @qwen-code/qwen-code. Offered only where npm is here and node --version names 22 or newer within 5 s. Else refused, with the requirement that is missing. |
antigravity |
~/.local/bin (it adds the folder to the shell's profile) |
bash -c "curl -fsSL https://antigravity.google/cli/install.sh | bash", offered where bash and curl are on PATH |
openclaw |
npm's global folder, else ~/.npm-global/bin (the installer's user prefix), else ~/.local/bin (its git install's wrapper) |
bash -c "curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard --no-prompt", offered where bash and curl are on PATH |
droid |
~/.local/bin |
sh -c "curl -fsSL https://app.factory.ai/cli | sh", offered where curl and sh are on PATH |
kiro |
~/.local/bin |
bash -c "curl -fsSL https://cli.kiro.dev/install | bash", offered where curl and bash are on PATH |
openhands |
/usr/local/bin where writable, else ~/.local/bin |
bash -c "curl -fsSL https://install.openhands.dev/install.sh | bash", offered where bash and curl are on PATH |
crush |
Homebrew's bin (/opt/homebrew/bin, /usr/local/bin, /home/linuxbrew/.linuxbrew/bin) |
brew install charmbracelet/tap/crush where brew is on PATH, else npm install --global @charmland/crush where npm is. Else refused. |
aider |
uv's tool folder, else pipx's (both ~/.local/bin) |
uv tool install --python python3.12 aider-chat@latest where uv is on PATH, else pipx install aider-chat where pipx is. Else refused. |
warp |
Contents/Resources/bin of Warp.app (oz) or WarpPreview.app (oz-preview), in /Applications or ~/Applications |
brew install --cask warp on a Mac where brew is on PATH. Else refused: Warp installs from warp.dev/download. |
When the driver does not offer install, setup/plan answers refused with the reason in one
line. steery setup --harness <id> shows this line. Two examples:
- "pi's installer needs Node.js 22.19 or newer and npm (
npmis not on PATH)" - "omp's installer needs
shandcurlon PATH:curlis not there"
Without Node.js 22.19 or newer and npm, pi's installer exits 0 and installs nothing. Thus the driver does not offer it there, and Steery never runs it there.
The driver can find the harness in more than one place: two folders on PATH, or one folder on
PATH and the installer's folder. A link to the same file counts as one place. Then
setup/plan says so in a note. The note names the executable that Steery runs (the first on
PATH, else the one in the installer's folder). It also names the others, which Steery never
runs. The protocol has no field for a list of binaries (Found has one binary). Thus the note
is the only place for this list.
sign_in tells a person what to do at the machine. The person reads it on their phone after
" is not logged in on :". models' signed_in tells whether the harness is
signed in, as the harness itself says.
| Driver | sign_in |
signed_in |
|---|---|---|
omp |
run `omp login` in a terminal (omp login is the terminal counterpart of /login) |
not told |
pi |
run `pi` in a terminal and type /login in it (pi has no login command. Its auth prints credentials and checks readiness.) |
not told |
claude-code |
run `claude auth login` in a terminal |
claude auth status --json's loggedIn |
codex |
run `codex login` in a terminal |
codex login status. Exit 0: signed in. Exit 1 with Not logged in: not signed in. |
grok |
run `grok login` in a terminal |
grok models' first line. You are logged in with … or You are using XAI_API_KEY.: signed in. You are not authenticated.: not signed in. |
copilot |
run `copilot login` in a terminal |
its own server's (copilot --headless --stdio) auth.getStatus isAuthenticated, bound 10 s. It counts a gh sign-in and COPILOT_GITHUB_TOKEN, GH_TOKEN, GITHUB_TOKEN. |
opencode |
run `opencode auth login` in a terminal |
not told. OpenCode's free models need no account, so an empty model list never means signed out. |
cursor |
run `cursor-agent login` in a terminal |
models runs cursor-agent models: Authentication required means not signed in. cursor-agent status says signed in while turns refuse, so the driver does not ask it. |
amp |
run `amp login` in a terminal |
amp threads list --json --limit 1. Exit 0: signed in. Exit 1 with Run 'amp login': not signed in. setup/plan asks the same, and an AMP_API_KEY counts as signed in. |
cline |
run `cline auth` in a terminal |
models starts cline --acp: session/new refused with ACP -32000 (auth required) means not signed in. |
goose |
run `goose configure` in a terminal |
models starts goose acp: session/new refused with Failed to resolve provider and model means not signed in. |
gemini |
run `gemini` in a terminal and choose how to sign in |
gemini models list lists signed in or not, so the driver reads what Gemini reads first: security.auth.selectedType, else the type that GOOGLE_GENAI_USE_GCA, GOOGLE_GENAI_USE_VERTEXAI or GEMINI_API_KEY picks. No type: not signed in. Google sign-in: oauth_creds.json there, else not told (the Keychain). Key: GEMINI_API_KEY there, else not told (the Keychain). |
antigravity |
run `agy` in a terminal and sign in with Google, or set `GEMINI_API_KEY` |
agy models. Exit 0 with a list: signed in. Please sign in or environment variable is not set on standard error: not signed in. A Google sign-in lives in the system keyring, so the command is what tells. |
openclaw |
run `openclaw onboard` in a terminal |
openclaw models status --json --check. Exit 0 or 2 (a sign-in expires soon): signed in. Exit 1 (auth.missingProvidersInUse names the providers): not signed in. |
droid |
run `droid` in a terminal and sign in, or set `FACTORY_API_KEY`; a custom model of your own runs without a Factory account |
not told: a custom model in Droid's settings runs turns with no account, so the plan asks for no sign-in and only notes it |
kiro |
run `kiro-cli login` in a terminal |
models runs kiro-cli whoami --format json. Exit 0 names the account: signed in. Exit 1 ({"account":null}): not signed in. |
openhands |
run `openhands` in a terminal and set up its model |
agent_settings.json names a model: signed in. None: not signed in, and start refuses. OpenHands runs local models with no account. |
crush |
run `crush` in a terminal and pick a provider |
crush models on a terminal lists a provider it cannot run as (not configured). No other provider: not signed in. |
warp |
open Warp and sign in to a Warp account |
not told: observe has no models |
aider |
none: Aider takes a model's key from its environment or a .env |
not told: an Ollama model needs no key |
Each probe has a bound of 5 s. The driver kills a probe that runs past it. A probe gives no answer in these cases:
- It did not start.
- It did not end in time.
- It exited in another way. For example,
codex login statusalso exits 1 for aconfig.tomlthat it cannot read. Also, itsNot logged insays nothing whenconfig.tomlnames amodel_providerof its own.
When the probe gives no answer, signed_in is absent and the driver claims nothing. The driver
writes the reason to standard error, which is the runtime's log of the driver. Models has no
field for a reason. To show the reason to a person, the SDK needs a field for it:
signed_in_why?: string beside signed_in. This is a protocol change.
When the probe gives no answer, setup/plan keeps the last answer that the probe gave in this
driver process, and plans the sign-in need from it. With no answer known yet, it plans no
need. So the card does not go and come back while the probe fails now and then. models still
reports signed_in as the probe says. Every needs/give that returns done, by any way,
forgets the kept answer: a probe with no answer right after a sign-in then plans no need, as
with nothing known, and does not plan the sign-in again.
When the harness is not signed in, setup/plan asks the sign-in need (protocol 5). It gives
its ways best first:
- A way whose return the Steery app catches.
- A code that the person types on the vendor's page.
- A key.
A way that runs the harness's own login starts that login unmodified on a terminal of the
driver's (common/src/login.rs). The driver answers with the login's
link as the next step. The driver keeps the login for 10 minutes. Only one login waits at a
time. When the link returns to a loopback address, the link's fills names the step's
address field. This field is secret and never required. Then needs/give takes one of these:
| Given | What the driver does |
|---|---|
an address on the login's own port (http://localhost:<port>/…, 127.0.0.1, [::1]) |
GETs it from inside this host. The harness's own listener then completes the sign-in. |
| anything else | types it into the login's prompt, where it has one. Else refused, with the address to paste. |
| nothing | done when the login exited 0 within 20 s. Else refused, with a request to paste the address (or finish on the page). |
| Driver | Ways, in order | Next step's link |
|---|---|---|
claude-code |
claude-sign-in, api-key, gateway (a company's own gateway) |
the link that claude auth login gave the driver's $BROWSER (localhost:<port>/callback). Else its printed manual link. |
codex |
chatgpt, device, api-key (OpenAI) |
codex login's link (127.0.0.1:1455). --device-auth's page, with its code in the step's label. |
copilot |
copilot-sign-in, github-token (copilot login --with-token) |
GitHub's device page (copilot login --device-code), with its code in the step's label |
omp |
one per provider below, api-key |
the link that omp login <provider> prints. A code that it shows goes in the step's label. |
pi |
api-key |
none |
grok |
grok-sign-in, api-key (xAI, kept as XAI_API_KEY) |
grok login --device-auth's page (accounts.x.ai/oauth2/device?user_code=…), with its code in the step's label. A key counts where grok models with it, in an empty GROK_HOME, fetched xAI's models. |
amp |
amp, api-key (Amp) |
the link that amp login prints after "Open this URL in your browser to authorize:". |
openclaw |
openclaw-sign-in, api-key (OpenRouter, kept as OPENROUTER_API_KEY) |
none. openclaw models auth login and openclaw onboard pick a provider interactively, so the person runs one on this host's terminal and the driver checks models status --check again. A key counts where models status --check with it exits 0 or 2. |
omp lists its providers' ids and names (RPC get_login_providers, the omp login picker). It
does not list how each provider signs in. Most providers only read an API key on their prompt.
Thus the driver keeps its own list of omp's OAuth providers (pi-family/src/sign_in.rs, omp
18.12.6):
- Return to an address:
openai-codex,google-gemini-cli,google-antigravity,openrouter,devin,stencil,gitlab-duo,gitlab-duo-agentandzai-coding-plan. The last two return to an app's address, which the person pastes. - Code on the vendor's page:
openai-codex-device,github-copilot,cursor,kimi-code,xai-oauth,muse-code,factory-droidandkilo. The driver answers the GitHub Enterprise question ofgithub-copilotwith Enter: github.com. - Left out:
anthropic(its terms),perplexityandsnowflake(each asks for an email or an account first).
A person can ask to give sign-in again where the harness is signed in already (protocol 15).
The runtime then names the need in setup/plan's ask. A driver plans it with a title that
says a change, and the same ways. Claude Code, Codex, omp and pi do this. A driver that picked
14 or older ignores ask. Where one way outranks another that an earlier done gave as
variables, its done names those variables as unset. The runtime stops keeping them. Only
Claude Code names unset; see its section. Every other driver names none.
The SDK and the protocol are in steery-dev/sdk. Every
crate names the SDK by git, at one tag, in its Cargo.toml
(steery-sdk = { git = "https://github.com/steery-dev/sdk", tag = "v<version>" }). Every
crate pins its toolchain in rust-toolchain.toml.
git clone https://github.com/steery-dev/drivers
cd drivers/pi-family && cargo build
cargo testEvery build goes through Kache, the compiler cache that
.cargo/config.toml names. Install Kache once on each machine:
- Mac:
brew install kunobi-ninja/kunobi/kache && kache daemon install - Linux: its APT package
./release.sh <tag> does these steps:
- It builds every driver with
--release --lockedandcargo zigbuild, for each target that Steery runs on, intodist/<target>/. The targets areaarch64-apple-darwin,x86_64-apple-darwin,x86_64-unknown-linux-gnuandaarch64-unknown-linux-gnu. The Linux builds link glibc 2.30 at most. - It packs them into
dist/release/withsteery programs pack --release <tag> --out dist/release <target>=dist/<target>…. The result is one archive per driver and target, and the manifest,steery-programs.json(PROTOCOL.md §7.1). - With
--publish, it makes the GitHub release<tag>of those files (gh release create). It records the release on Steery'sdrivers-releasestrain:buildas it starts, thenshipped, orfailedwith the step that stopped it. Steery'srelease-of-commitreads that train to say which release first carries a commit.
With --no-pack, it stops after the build, and --publish needs the pack step. It needs these:
cargo-zigbuildzig- the four targets (
rustup target add) steeryonPATH, or named bySTEERY; with--publish, signed in to thesteery-devworkspace
steery programs test target/debug/steery-driver-omp
steery programs test target/debug/steery-driver-pisteery programs test [--setting NAME[=VALUE]]… <command> [args…] starts the driver. It checks
these things, one line per check:
- what the driver says it is
- the methods that read and change nothing
- an id sent twice
- a method that the driver does not have
- its shutdown
The command exits 0 only when every check passes. A read that gets a refusal word that its
method lists counts as an answer. --setting NAME=VALUE passes a setting to initialize.
--setting NAME takes the value from the environment, so a secret stays off the command line.
The command skips a method that needs a required setting which is not given. models asks the
harness itself, so the harness must be on PATH for that check to pass. Each crate's own
cargo test covers what the crate reads and writes.
A driver for a harness that Steery does not ship is a program like these drivers. pi-family/
is the worked example. Copy it and keep its shape (the layout is below, under omp and pi).
-
Its crate depends on
steery-sdkby git, as above. It depends onsteery-driver-commonby path where it keeps a tree, follows a file or reads a receipt. In this repository this path is../common. In a copy elsewhere, thecommoncrate goes beside the driver's crate. The crate usestokiofor its runtime andserde_jsonfor the parameters. It declares an empty[workspace], so it builds alone. Its binary has the namesteery-driver-<id>.src/bin/omp.rsis one line,steery_driver_pi_family::serve(Harness::Omp). This line callssteery_sdk::serve(|_notifier| Driver::new(harness)). The SDK reads requests and answers each one. It also gives the notifier, which the driver uses for what it says unasked. -
initialize(Program::initializeinsrc/lib.rs) answers with the newest protocol that the runtime offers and that the driver speaks (steery_sdk::pick). It refuses a runtime that offers none of them. It keeps thehomeandconfigthat it gets. Its answer iswire::Initialized, with these fields:program:id,kind: Harness,release,label,short, and optionallytintandmark. This is what a person sees of the driver.harness:HarnessInfofromsrc/harness.rs(PROTOCOL.md §3.1). It holds the levels, the harness's minimum release, how the harness signs in, its facts, its hooks and its door.- no
machine. - the settings that the driver needs (none here; §3.4).
-
The methods (
Program::call) are one match from eachsteery_sdk::methodname to the module that answers it. The module reads its parameters withsteery_sdk::params. It gives its answer withsteery_sdk::result. The methods are:- observe (§4.1):
setup/plan,sessions/list,sessions/locate,sessions/read,hook/read,mcp/list. - drive (§4.2):
held,idle,models,start,turn/read,receipt/*,reader,terminal. - any other method answers
Error::Unknown.
A refusal is
Error::refusedwith one of the protocol's words (steery_sdk::refusal). - observe (§4.1):
-
Live (§4.3) is a door. A harness with its own door (
picks,keeps) answerssay,pickandstopin its driver.claude-code,codex,copilot,cline,hermes,grok,antigravityandqwendo this. omp, pi, Kilo, OpenCode, Amp and Gemini CLI have no door of their own, so their door isplugin. This repository keeps Steery's plugin for omp and pi inpi-family/plugin/, Kilo's inacp-family/plugin/kilo.ts, OpenCode's inacp-family/plugin/opencode.tsand Amp's inamp/plugin/steery.ts, andsetup/planinstalls it. Gemini CLI loads no plugin of Steery's: its turn process speaks the door itself (acp-family/src/turn/door.rs). The plugin speaks the plugin door, version 1 (§4.4), to the runtime itself. Thus the driver has no live methods. The runtime uses the live methods only on conversations that Steery started. The runtime never steers a conversation that a person started.
mcp/list (protocol 4) answers with the MCP servers that a conversation loads:
- Without
cwd: the person's own servers. - With
cwd: the servers that a conversation started in that folder loads, as the harness itself decides.
For each server, only its name leaves the machine. For a URL server, the URL's scheme, host,
port and path also leave the machine. The file common/src/mcp.rs reads
the mcpServers files that omp, pi and Claude Code share.
| Driver | Everywhere | In a folder, ahead of those | complete |
|---|---|---|---|
omp |
agent folder's mcp.json, .mcp.json. enabled: false off unless in enabledServers. disabledServers off. |
.omp/mcp.json, .omp/.mcp.json. The folder's mcp.json, .mcp.json last. None where config.yml says mcp.enableProjectConfig: false. |
never: other tools' files, plugins, extensions |
pi |
agent folder's mcp.json |
.pi/mcp.json, where trust.json trusts exactly that folder |
never: extensions register servers |
claude-code |
~/.claude.json mcpServers |
local scope projects["<folder>"]. .mcp.json where the folder is trusted and the server approved, not rejected. (start runs claude --bg, not -p. claude --bg is an interactive background session that waits on approval.) disabledMcpServers off. |
not with managed configuration, a plugin on, or a claude.ai sign-in |
codex |
codex mcp list --json run at / |
the same, run in the folder | never: account connectors |
grok |
grok inspect --json run at /: config.toml, ~/.claude.json, ~/.cursor/mcp.json. A server imported from another tool and turned off there is left out. |
the same, run in the folder: .grok/config.toml where trusted, .mcp.json |
never: plugins, servers an ACP client forwards |
copilot |
mcp-config.json mcpServers, installed plugins' servers, built-in servers (copilot mcp list --json). disabledMcpServers in settings.json off. |
not read: a folder's .mcp.json, .github/mcp.json, .vscode/mcp.json |
not with cwd |
opencode |
the system folder's, then the config folder's opencode.json, opencode.jsonc (comments and trailing commas read), then the file OPENCODE_CONFIG names. mcp.servers (OpenCode 2) over mcp.<name> (OpenCode 1's shape). enabled: false off. |
each folder's opencode.json, opencode.jsonc, from / down to it; then each folder's .opencode/ ones, in the same order |
not with managed preferences, OPENCODE_CONFIG_CONTENT, a plugin or plugins list, or a module in a config folder's plugin/ or plugins/ |
cursor |
~/.cursor/mcp.json, whatever CURSOR_CONFIG_DIR says |
.cursor/mcp.json, listed before its person approves it in Cursor |
never: plugins, team servers |
amp |
amp mcp list --json run at / |
the same, run in the folder (it adds .amp/settings.json) |
never: skills, plugins and toolboxes bring servers |
cline |
Cline's MCP settings file: CLINE_MCP_SETTINGS_PATH, else <CLINE_DIR or ~/.cline>/data/settings/cline_mcp_settings.json. mcpServers.<name>, nested transport or flat shape. disabled: true off. |
the same file: Cline reads none per folder | not when the file is not JSON |
goose |
/etc/goose/config.yaml, the files GOOSE_ADDITIONAL_CONFIG_FILES names, then <GOOSE_PATH_ROOT>/config or <XDG_CONFIG_HOME or ~/.config>/goose's config.yaml, a later file's entry over an earlier's. extensions.<key> of type stdio, streamable_http or builtin; enabled: false off. |
the same files: Goose reads none per folder | never: plugins and recipes bring extensions |
gemini |
mcpServers of the system defaults, settings.json, the system settings, and each extension's gemini-extension.json. mcp.allowed, mcp.excluded and mcp-server-enablement.json turn servers off. |
.gemini/settings.json where trustedFolders.json trusts the folder. A folder not trusted lists none. |
never: an administrator's remote settings |
qwen |
mcpServers of the system defaults, settings.json, the system settings, mcp.serverCommand (named mcp), and each extension that extension-enablement.json leaves on: its qwen-extension.json, else its .mcp.json. mcp.allowed and mcp.excluded turn servers off. |
.qwen/settings.json where the folder is trusted (trustedFolders.json, or folder trust off), and .mcp.json. These are listed only where mcpApprovals.json approves them under their config's hash, or tools.approvalMode is yolo. |
never: servers on Qwen's command line or added in a running conversation |
antigravity |
~/.gemini/config/mcp_config.json mcpServers, then each plugin's mcp_config.json in ~/.gemini/config/plugins/<plugin>/, named <plugin>_<server>. disabled: true off; a plugin off where config.json has plugins.<plugin>.enabled: false. |
.agents/mcp_config.json and .agents/plugins/<plugin>/mcp_config.json in the folder. The person's server wins a name both give. |
never: --add-dir widens the workspace, a plugin installed while Antigravity runs |
openclaw |
mcp.servers of <state>/openclaw.json (comments and trailing commas read). enabled: false off. A server with a command runs it, so it keeps no URL. |
the same file: OpenClaw reads none per folder | never: enabled plugins bring servers |
droid |
~/.factory/mcp.json mcpServers. disabled: true off. |
.factory/mcp.json in the folder and in each folder above it, the nearest ranked first. Droid loads one definition of a name given at several levels; its documentation does not say which. |
never: servers its organization manages win and are not readable |
kiro |
~/.kiro/settings/mcp.json mcpServers. disabled: true off. |
.kiro/settings/mcp.json in the folder, over the person's file where a name is in both |
never: powers and agents bring servers |
openhands |
<root>/mcp.json mcpServers. enabled: false off. |
the same file: OpenHands reads none per folder | always |
crush |
/etc/crush/crush.json, then <CRUSH_GLOBAL_CONFIG or XDG_CONFIG_HOME/crush or ~/.config/crush>/crush.json, then the crush.json of Crush's data folder. mcp.<name>, a later file's fields over an earlier's. disabled: true off. |
each folder's crush.json, .crush.json, from the project's git root down to it, then .crush/crush.json. The store's mcp_disabled_servers and mcp_enabled_servers over every file. |
not where a crushrc that Crush reads exists: it is a shell script |
warp |
each channel's ~/.warp/.mcp.json, ~/.warp-preview/.mcp.json: the first key Warp reads (mcp.servers, servers, mcpServers, mcp_servers). Servers installed in Warp that it restores running (mcp_server_installations.restore_running). |
none: a project's files never start on their own | never: team servers come from Warp's servers, and other agents' files start where a Warp setting says so |
Steery adds a driver in the same way as every program, Steery's own included (PROTOCOL.md §7.2):
steery programs add https://github.com/steery-dev/drivers
steery programs add https://github.com/me/my-harness@v0.1.0 --setting MY_HARNESS_TOKEN<source> is one of these:
- a GitHub repository: its latest release, which
steery programs updatefollows, or@<tag>for that release - a release's manifest,
steery-programs.json, by URL or path - one program's archive
- a built
steery-driver-<id>itself
To publish your own driver, do what this repository does:
- Build the driver for each target.
- Pack it with
steery programs pack. - Make the release of those files.
Steery builds nothing on the computer that it adds the driver to.
For each program, Steery does these steps with the build for this computer:
- It fetches the build.
- It checks the build against its sha256.
- It copies the build into Steery's programs folder.
- It starts the build and checks it as
steery programs testchecks it, with the settings given.
A driver's settings (PROTOCOL.md §3.4) are, for example, an API key or the account that the
driver acts as. The person gives them here once: --setting NAME=VALUE, or --setting NAME to
take the value from the environment. When the person does not give a secret setting, they type
it at the terminal, with no echo. Steery prints what it will add and asks once at the terminal.
--yes gives that answer in all other places. The runtime sends the settings in each
initialize that it sends the driver. The runtime runs as a service (launchd, systemd), and
the environment of this service holds none of the person's shell variables. Thus a driver reads
nothing that it needs from its environment.
steery programs remove <id> removes it.
omp is a fork of pi. Both harnesses do these things:
- write the same transcript
- load the same plugin
- read the same
PI_*variables for their folders - run as kept processes in their RPC mode
Thus one crate holds both drivers: a library, and two binaries, steery-driver-omp and
steery-driver-pi. Each binary is one line that serves the library for its harness. Neither
driver has settings.
Needs (protocol 5: a driver that picked version 4 plans no needs). When the harness lists
no model, the plan asks sign-in. For omp, this is when omp models --json prints
{"models":[]}. For pi, this is when pi --list-models prints "No models available". The
ways are:
- In omp only: one way per OAuth provider that
omp login <provider>signs in to, by its id (see Signing in). - In both:
api-key. This is an Anthropic API key. The driver checks that it starts withsk-ant-api. The driver returns it asANTHROPIC_API_KEY, which both harnesses read.
Neither harness has a gateway way. omp sends a stored Anthropic login (OAuth sk-ant-oat)
in place of ANTHROPIC_API_KEY, and ANTHROPIC_BASE_URL then sends that plan token to the
company's gateway. omp signs the login out when the gateway refuses it. omp has no command
that says, without the secret, whether a login is stored. pi 1.5.2 ignores
ANTHROPIC_BASE_URL: it reads a gateway's address only from providers.anthropic.baseUrl in
models.json, which the driver does not write.
The driver never offers omp's and pi's own Claude login. That login signs a third-party app in to a Claude plan, and Anthropic's terms forbid this. Because pi has no login command, pi has only the key.
Ask (protocol 15). Where setup/plan's ask names sign-in and the harness is found,
the plan has the need also where the harness lists a model. Its title says a change
(Change how omp signs in to a model provider?, Change how pi gets its Anthropic API key?).
The ways are the same. A driver that picked 14 or older ignores ask. No way names unset:
each gives ANTHROPIC_API_KEY or nothing.
What each driver does:
-
Conversations (
sessions/list,sessions/locate,sessions/read). The driver reads them from the transcripts under the agent folder, insessions/<folder>/<started-at>_<id>.jsonl. The agent folder is~/.omp/agent,~/.pi/agent, orPI_CODING_AGENT_DIR. For omp,PI_CONFIG_DIRandOMP_PROFILEalso change the agent folder. The driver also reads transcripts from these folders:- the folder that
PI_CODING_AGENT_SESSION_DIRnames - the folder in pi's
sessionDirsetting - the folders of the transcripts that the harness's moments named
A transcript is a tree: each entry names its parent. The conversation is the path from the last entry back to a root. The driver reads only that path. A conversation can go back to an earlier entry and continue from there. Then the next read starts again from the beginning (
reset). The events are these:- turns and how they ended
- words
- calls, grouped as Steery groups them
- tokens per response
- models (in pi with their thinking level)
- forks
- omp's sub-agents
A failed model call ends its turn only when the harness does not continue after it. The driver still gives the tokens that an abandoned branch used, once, as the
tokensof each of its responses. - the folder that
-
Setup (
setup/plan). The plan has these entries:- the skill,
extension/<harness>-SKILL.mdin the runtime's config folder, beside the plugin's copy. It stays out of the harness's ownskills/folder, where the harness would list it a second time (skill: prompt, protocol 17). - Steery's plugin
- in omp, the MCP entry in
mcp.json
The plugin is a loader in
extensions/steery.ts, plus the copy of the extension that the loader runs. The runtime's config folder keeps this copy. In pi, the plugin carries the MCP entry and registers it for each conversation, with headers that name that conversation. The entry hasexposure: direct, so pi gives its model each tool by name. Asteeryserver in pi's ownmcp.json, or in the.pi/mcp.jsonof a folder that pi trusts, wins over the plugin's entry, with no headers. The plan notes each such server that it finds. A pi process that starts while the runtime is down waits its own 10 s for the entry. Then it runs without Steery. The plugin connects the entry again when the door is back. When omp and pi are both installed and share one folder, the plan writes no setup for either harness.The plugin reads the skill's file as each conversation begins, frontmatter cut. It appends the body to every turn's system prompt as
<skill name="steery">…</skill>, the same text on each turn. A missing file adds nothing. Once a moment's answer saysquiet: true(a chat's session, told nothing of Steery), the plugin adds the block no more in that conversation. A bare turn (--steery-bare, in omp and pi) and a sub-agent's copy (its lead's words reach it) get no block. - the skill,
-
Moments (
hook/read). The plugin forwards each moment that the harness gives it over the door. The driver reads it as a Moment. A start says the harness'sreasonand the transcript it came from. At protocol 17 a fork's start (pi'sfork, omp'sforkswitch andbranch) names its parent (forked_from). omp's switch to another conversation and every compaction (Steery's or the harness's) say a start too: the context is fresh, so the runtime owes its start's words again. The prompt hook sayscontextand nonotice(17). -
Turn ends (
settle). At protocol 17 the plugin settles every turn end the harness offers, with itsoutcome(finished,failed,interrupted) andcontinued. The runtime decides from its own record whether a turn asked, waits, was parked, failed, or is a sub-agent's, and says nothing then. The plugin wraps the words it gets back in<system-reminder reason="steery">, as every other moment's. Against a runtime on 16 the plugin sends 16's settle (asked,parked,waitingall false), only after a turn that stopped by itself, not for a sub-agent, and leaves the words as the runtime wraps them. -
Drive (
held,idle,models,start,turn/read,receipt/*,reader,terminal).held: there is no registry, so the runtime looks for processes. In pi, the runtime also looks for a stray process, because a pi process without the plugin does not hold a file open.models: omp's models come fromomp models --json. When omp'senabledModelsnames models, the driver gives only those. The default comes fromconfig.yml, or fromconfig.yamlwhen that is the only file there. The omp harness itself reads both, in that order, and writes the one that it read. The code of omp namesconfig.yamlits legacy-compatible fallback. For pi, the models come frompi --list-modelsand its RPC mode'sget_available_models.start: a turn is a kept process,--mode rpc(omp's with--no-ui), with its standard input held. The process stays alive between turns. It takes the words of every turn, the first turn included, through the plugin door. For omp, a turn continues by id (--resume). Before the launch, the driver checks a model against omp's catalog. For pi, a turn continues by transcript (--session <file>). The pi command also passes a model to the plugin (--steery-model). The plugin then ends the process with a refusal when pi does not run that model exactly. Neither harness makes a worktree for a turn. Thus a fork or a new conversation that asks for a worktree (facts.worktrees) starts in a worktree that the driver makes, detached atHEAD. The driver makes it where omp keeps its own worktrees: underOMP_WORKTREE_DIR, else~/.omp/wt(for pi,~/.pi/wt), as<4 hex>/<repository>. A turn in a folder that is in no repository runs in that folder.turn/read: the harness's own refusals on standard error. The runtime discards the harness's standard output. The door says what the harness does.receipt/mark,receipt/find: the person's message that carries the delivery marker. They look in the transcript after a mark. When the harness rewrote the file after the mark, they look in all of it (some omp compactions do this). Words that the door gives during a turn go in at the next tool.reader: a one-shot--printreader. It closes everything that a flag can close.terminal: the command line that resumes a conversation in a terminal.
The live methods (say, pick, stop, force, compact) belong to the plugin door
(PROTOCOL.md §4.4). The runtime speaks this door itself, so the drivers have no live methods.
The door answers a say when the harness holds the words, with the time in queued_at. When
the runtime asks the same say again, the door answers when the harness took the words into
its turn (taken_at). Both omp and pi take a steer only between tool calls. force aborts the
running turn, so the held words go in next, in the same process. At an abort, omp puts the words
that are still queued into a turn of their own.
The door's state says compacting for every compaction that the harness runs:
- pi: from its
session_before_compactto itssession_compact(orsession_compact_failed). - omp's own compaction: from
auto_compaction_starttoauto_compaction_end. - a compaction that something asks of omp (
/compact, an extension's): fromsession_before_compacttosession_compact. When this compaction fails,compactingends at omp's next run. omp tells an extension nothing about the failure.
The door's model and thinking come, in pi, from model_select and thinking_level_select.
omp says neither. Thus the door reads omp's own model and thinking every second while the door
is open.
To connect another harness, copy pi-family/ and keep its shape:
| File | What it holds |
|---|---|
src/bin/<id>.rs |
The binary: serve(Harness::…). |
src/lib.rs |
initialize, and one match from each method to the module that answers it. Methods that the harness cannot do answer Error::Unknown. |
src/harness.rs |
Everything about the harness as Steery reads it: id, HarnessInfo (levels, minimum, identity, facts, hooks), its folders, its executable. Every other module asks here, and never names a harness itself. |
src/transcripts.rs |
Where the harness files conversations. sessions/list, locate, read, and the cursor's mark. steery_driver_common::tree holds the rest of the cursor and the batched read. |
src/tree.rs |
The transcript's format: here, how pi's entries name their parent, as a steery_driver_common::tree::Shape. |
src/events.rs |
One record → the protocol's events. |
src/calls.rs |
A tool call → Call: its group, MCP server, Steery's own tool, the questions it asks. |
src/hooks.rs |
hook/read: a hook's document → Moment. |
src/models.rs |
models: what the harness lists, and the files whose change changes it. |
src/drive.rs |
held, idle, start, turn/read, receipt/*, reader, terminal. |
src/setup.rs |
setup/plan: the entries, each with what it carries. |
plugin/ |
Steery's plugin for harnesses whose door is plugin: the extension and its loader. The build embeds them in the binary. |
A harness with its own door (picks, keeps) has no plugin/. Its driver answers say,
pick and stop itself. A driver whose harness has hook commands as moments also answers
hook/answer.
pi-family/plugin/extension.ts speaks the plugin door, version 1. It draws nothing in the
harness and takes no answer there. loader.ts is the file that the harness loads. It runs the
copy of the extension that the runtime's config folder names. When the config folder names a
newer copy, the loader moves every session onto it. Typecheck the two files against pi's
published types:
cd pi-family/plugin && npm i && npm run checkOne crate, one binary: steery-driver-claude-code. It has no settings. Claude Code keeps
everything under its configuration root, CLAUDE_CONFIG_DIR or ~/.claude.
Needs (protocol 5: a driver that picked version 4 plans no needs). When
claude auth status --json says "loggedIn": false, the plan asks sign-in in three ways. An
ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN in Claude Code's environment counts as signed in.
The ways are:
claude-sign-in, offered first. The driver runs the unmodifiedclaude auth loginon a terminal of its own, withBROWSERnaming a script of the driver's. This script records the link that Claude Code opens (redirect_uri=http://localhost:<port>/callback). The driver answers this link as the stepclaude-sign-in-return, and the address fills the step's field. Sometimes no$BROWSERcall comes within 3 s of the printed manual link. Then the step has the manual link. Its page shows a code, and nothing fills the field.api-key: an Anthropic API key. The driver checks that it starts withsk-ant-api. The driver returns it asANTHROPIC_API_KEY. Claude Code uses that variable unasked only in-p(the reader). A--bgsession uses it only after approval. Thus a turn that holds the key passes--settings '{"apiKeyHelper": "printf %s \"$ANTHROPIC_API_KEY\""}', and writes nothing. Thedoneof this way also returnsCLAUDE_KEY_FROM_STEERY=1. This marker says that the person gave this key through Steery, so turns take the key throughapiKeyHelperalso where Claude Code is signed in to a plan. The driver signs nothing out, and the plan stays signed in. Without the marker, a turn takes the key throughapiKeyHelperonly where Claude Code has no sign-in of its own, or where a gateway is used. The marker has noSTEERY_prefix, because a turn moves everySTEERY_variable into the session's settings, and the marker is for the driver alone. Thegatewayway does not use it:ANTHROPIC_AUTH_TOKENoutranks a plan, and a turn sends ax-api-keykey throughapiKeyHelper.gateway: a company's own gateway that speaks the Anthropic Messages API, as Claude Desktop's gateway configuration (inferenceGatewayBaseUrl,inferenceGatewayApiKey,inferenceGatewayAuthScheme). The fields areurl,key(secret) andheader(optional).-
urlishttps, orhttponly onlocalhostor a loopback IP address. It has no user, query or fragment, and it does not end in/v1, because Claude Code adds/v1/messages. The driver returns it asANTHROPIC_BASE_URL. -
headerempty orbearer: the driver returns the key asANTHROPIC_AUTH_TOKEN, which Claude Code sends asAuthorization: Bearer. It outranks a plan's sign-in. An interactive session used it with no approval (2.1.73). -
headerx-api-key: the driver returns the key asANTHROPIC_API_KEY, which Claude Code sends asx-api-key. A turn reads it throughapiKeyHelperalso where Claude Code is signed in to a plan. Else a--bgsession would send the plan's token to the gateway. -
The driver returns no other variable. Claude Code sends an empty
ANTHROPIC_AUTH_TOKENas an emptyAuthorization: Bearerheader, so an empty variable does not unset one. -
The key is tried once before it is given, on this host, where Claude Code sends it (
steery_driver_common::gateway::check). The driver sendsGET <url>/v1/models, which costs no tokens, with the key in the header that the person named (andanthropic-version: 2023-06-01), throughcurl, within 8 s. The key goes tocurlon its standard input, sopsnever lists it. The gateway answers one of three ways:The gateway needs/give401or403refused ( refused) with the gateway's own words as the line:The gateway at <url> refused your key (HTTP 401): Invalid API key. Check the key and the key header.The runtime asks again with that line, and keeps the key nowhere. The line has the key cut out of it.a success done, as beforeno answer in time, a link that fails, no curlon the host, or any other status (a404where the gateway has no such path, a503)done, as before. ItslineendsSteery did not check the key: <why>.A person whose gateway is fine but slow is not stopped.A gateway that answers
401to a made-up key (proxy.steery.devdoes, 2026-11-16) now refuses it where the person gives it. Before, the driver checked the address and kept any key.
-
Claude Code keeps the sign-in on this host. The driver keeps no token. A driver that started
again has no sign-in that waits. Thus a step at that time is not-found.
Ask and unset (protocol 15). Where setup/plan's ask names sign-in and Claude Code is
found, the plan has the need also where Claude Code is signed in. Its title is Change how Claude Code signs in?. The ways are the same, but the about of api-key ends with Claude Code uses the key in place of your plan on this host. The plan stays signed in. Only this need
says it. A driver that picked 14 or
older ignores ask, and names no unset. Each way's done unsets the variables of the ways
that it outranks, so that the way just given is the one Claude Code uses:
| Way | unset |
|---|---|
api-key |
ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN |
gateway, bearer |
ANTHROPIC_API_KEY, CLAUDE_KEY_FROM_STEERY |
gateway, x-api-key |
ANTHROPIC_AUTH_TOKEN, CLAUDE_KEY_FROM_STEERY |
claude-sign-in-return |
ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL, CLAUDE_KEY_FROM_STEERY |
-
Conversations (
sessions/list,sessions/locate,sessions/read). The driver reads them fromprojects/<folder>/<id>.jsonlunder the root. It also reads them from theprojectsfolder of any transcript that the harness's moments named. A resumed conversation continues in its own file. Claude Code files a sub-agent's transcript under the transcript of its conversation, as<id>/subagents/agent-<agent>.jsonl. The.meta.jsonbeside it names its type, its task and the call that started it. A run that a program started (entrypoint: sdk-cli) is not a conversation until a person continues it. A run that the Claude app started (entrypoint: claude-desktop) isapp. The events are these:- turns and how they ended: an API error with its status and code, and the time when a limit ends, where the error says so
- words
- calls, grouped as Steery groups them
- tokens per response
- models
- sub-agents that its lead started, and how each ended, as Claude Code's
<task-notification>told it. The notification can come as a person's message or as a queued attachment.
A sub-agent's own turn ends where it returns its report (
SubagentHandback). An API error ends its turn only when Claude Code does not continue after it. The transcript can still get the answer of a retry. While it can, the error and the records after it wait for the next read, as in omp. -
Setup (
setup/plan). The plan has these entries:- Steery's MCP entry in
.claude.json(beside the root, when the root is~/.claude) - the skill in
skills/steery/SKILL.md, which Claude Code lists (skill: listed) - one hook group per event in
settings.json, at/hooks/<event>/-, beside the person's own groups. Steery's group runssteery hook claude-code <event>. At protocol 17 the events includeSubagentStop(sub_agent_end) andPreCompact(compacting).
found.releaseis whatclaude --versionsays. - Steery's MCP entry in
-
Moments (
hook/read,hook/answer). A hook's document becomes a Moment, with the state that Claude Code's documents carry:- the model (
SessionStart'smodel,PostModelSwitch'sto_model) - the effort (
effort.level) - at
StopFailure, the failure (error, with its words inlast_assistant_message) - at protocol 17, a fork's parent (
forked_from) at aSessionStartwhosesourceisfork. The document names none; the fork's transcript, which opens with the parent's records, does. - at protocol 17, no
promptfor words that are nobody's instruction: a background task's report (<task-notification>), or asourceofloop_wakeup,schedule_wakeuporpoll_event(Claude Code 2.1.325 fillssourceonly forpoll_event) - a
SubagentStopwith an emptyagent_type(an agent Claude Code runs for itself) gives no moment
The documents carry no time.
PreCompact/PostCompactcarry no compaction id or tokens. Thus compactions come only from the transcript. Every hook that sayscontextdeclaresroom: 10000at protocol 17: Claude Code keeps 10,000 characters whole and replaces a longer paragraph with a 2,000-character preview. No hook declaresnoticeat 17. Steery's answer becomes what Claude Code reads:hookSpecificOutput.additionalContext, at aStoporSubagentStoptoo, where it keeps the turn running as hook feedback (Claude Code 2.1.163)- at
PreCompact, the plain output that Claude Code reads as its instructions for the summary - a
PreToolUseorPermissionRequestdecision - the conversation's lead, written to
CLAUDE_ENV_FILE(append)
Cursor also runs the hooks in Claude Code's
settings.jsonfiles, under its own chat id. Its document hascursor_version, and the hook's process hasCURSOR_VERSION. Every hook entry namesCURSOR_VERSIONinenv, and no other Cursor variable. For either sign,hook/readgives no moment andhook/answerprints nothing. Thus a Cursor turn makes no Claude Code session, and the Claude Code driver never allows or blocks Cursor's tools. Thecursordriver reads Cursor's turns from its own hooks, in~/.cursor/hooks.json. - the model (
-
Drive (
held,idle,stop,receipt/*,models,start,turn/read,reader,terminal).-
held: Claude Code's registry,sessions/<pid>.json, names the live session in a conversation. Only its owner can stop a background session: the driver runsclaude stopwith the session's owner token. A terminal is a process that the runtime stops. When no session is registered, the runtime looks for processes that hold the transcript. -
idle: whatclaude agents --json --alllists, with the registry. -
stop: for a background session, the driver first runsclaude stop <job>, which keeps the conversation. Then it stops every command that the session's process started and that outlived it. The shells of its tools run in their own process groups, andclaude stopleaves them running. The driver sends SIGTERM to each command and to the group that the command leads. After 500 ms, it sends SIGKILL to what is still there. A stop that names a say (protocol 7) ends the session only when the running turn took that say's words. When another turn runs, or the words still wait in the inbox, the stop is refusedother-turn. When no turn runs, the answer isstopped: false. -
start: a turn is a background session (claude --bg,--resume,--fork-session,-w,--model,--effort). The plan runs this driver's own binary in its turn mode (steery-driver-claude-code turn …). The turn mode starts the session. It follows the session throughclaude agentsto the point where its turn stopped.turn/readreads those lines and Claude Code's own refusals (untrusted,not-found,harness-busy,selection-unsupported). The launch gives that session its ownStopandStopFailurehooks (--settings). These hooks run the binary'sheardmode into a file that the follower reads. The file tells whether a stop that the listing shows belongs to this turn. It also holds Claude Code's words for an API error. Each line that the turn mode writes also tells whether the session's transcript holds the person's input with the words' delivery marker yet. The turn mode looks only after the point where the transcript ended before the launch.turn/readgives that astook(none for words with no marker). Steery's own variables (STEERY_STARTED) reach the session in the same settings, asenv. They never go through the launch's environment. Claude Code's supervisor keeps the environment of the launch that started it, for every later session.Claude Code can keep the background job of a conversation (
jobs/<id>/state.json). A continue of that conversation wakes the job withclaude --bg --resume <id>and no other flag, because any flag beside it starts a copy. The job continues with the settings that its first launch gave it. The driver first refuses a model or an effort that the job would not run (selection-unsupported). When Claude Code starts a copy anyway, the driver stops and removes the copy. It refuses the turn in Claude Code's words. When the runtime stops a turn (a signal to the turn mode), the turn mode ends its session throughclaude stop. This keeps the conversation. Then it stops the commands that the session left running, asstopdoes. It does this because no signal of the runtime reaches a process of the supervisor. -
receipt/mark,receipt/find: the person's input that carries the delivery marker, in the transcript after a mark. -
models: Claude Code's documented aliases (opus,sonnet,haiku,fable,best,opusplan,opus[1m],sonnet[1m]). The model insettings.jsoncomes first. The list holds only the models thatavailableModelsallows. This is the managed list where one is set, else the user'ssettings.json. An alias is in the list only when every model that it can run is allowed. Each model in the list has Claude Code's effort levels.signed_incomes fromclaude auth status. The driver watches the files that a login rewrites (.claude.json,.credentials.json). At protocol 18, asigned_in: truelist also sayssigned_in_at: the later of.credentials.json's change and, on macOS, themdatof the keychain itemClaude Code-credentials(security find-generic-password, which prints no secret without-w), with-and 8 hex digits of the SHA-256 ofCLAUDE_CONFIG_DIRadded where that is set. -
reader:claude --printwith no tools, no MCP server,--safe-mode, and no session kept. -
terminal:claude --resume <id>, orclaude attach <job>while a background session holds the conversation. Also the Claude app's link for a conversation that the app started.
-
-
Live (
say,session/changed) is for a conversation that Steery started and that a Claude Code session holds.- Words go into the inbox socket that the registered session opens, after its peer token.
The socket says nothing back. Thus the words are unconfirmed (
took: false), and the runtime finds them withreceipt/find. - The driver keeps a say with an
id(protocol 7) together with the point where the transcript ended when its words went in. The transcript then names the turn that took the words. This is auserrecord that begins the turn, or a queued prompt that a running turn reads between its calls.session/changednames the say in that turn'ssays, and insettledafter the turn ended. - The driver reads the transcript as it grows. The transcript also gives
retrying,jobsand a dialog's title. retrying: true while a running turn waits for theretryInMsof its newestapi_errorrecord that no answer followed.retryholds the record'sretryAttempt,maxRetriesplus one, and the error'sformattedwords.LiveRetryhas no field for the time of the next try.jobs: the shells, monitors and sub-agents that the main thread's calls left running (backgroundTaskId, a monitor'staskId, anasync_launchedagentId). The driver counts only jobs from the time when the process that holds the session took it (its registry entry'sstartedAt). Work ends with the process that ran it, and that end tells nothing. A job stays injobsuntil a<task-notification>tells its end, or until aTaskStop/KillShellcall stops it. The notification tells the end by a finalstatus. For a monitor, it tells the end by aneventthat says the monitor expired, timed out or was stopped. Claude Code files the notification as a queued command in a running turn, or as the words of a turn of its own.- A
permission promptdialog's title,Allow <tool>: <command or path>?. It comes from the first call with no result in the newest answer. Claude Code asks about an answer's calls in its order. When that call is a sub-agent's, the title does not name the call. - The driver does not count work that started before the newest answer to which a newly started driver reads back.
- Nothing that Claude Code writes shows a compaction while it runs. Its
compact_boundarycomes only after the compaction is done. Thuscompactingstays false. - The session keeps its own model, so
pickis unsupported.
- Words go into the inbox socket that the registered session opens, after its peer token.
The socket says nothing back. Thus the words are unconfirmed (
cd claude-code && cargo build
steery programs test target/debug/steery-driver-claude-code
cargo testcargo test needs no Claude Code. The reader's test runs only where claude is on PATH.
One binary, steery-driver-codex, with no settings. It speaks to Codex only through what Codex
publishes:
- its rollout files
hooks.jsonandconfig.tomlcodex app-server(its JSON-RPC over standard input and output)codex app-server proxy(the bytes of a running app server's control socket)- the Codex app's router
<CODEX_HOME>/ipc/ipc.sock codex execcodex mcp listandcodex features list
Codex's home is CODEX_HOME, else ~/.codex.
Needs (protocol 5: a driver that picked version 4 plans no needs). When
codex login status says not logged in (see Signing in), the plan asks sign-in in three
ways. The driver runs each way on a terminal of its own, in Codex's home.
chatgpt:codex login. Its printed loopback link (127.0.0.1:1455) is the stepchatgpt-return. The address fills this step.device:codex login --device-auth. Its page and one-time code are the stepdevice-code, with no field.api-key: an OpenAI API key.codex login --with-api-keyreads it on standard input, and Codex keeps it.
Ask (protocol 15). Where the person asks to give sign-in again, though Codex is logged
in, the plan has the need with the title Change how Codex signs in? and the same ways. Each
way keeps its sign-in in Codex's own home, so no done gives a variable or names unset.
When Codex's own hooks/list lists a Steery hook as untrusted or modified, the plan also
asks hooks in one way, trust. Codex runs a hook only after its person trusted the hook's
exact content. Until then a Steery turn cannot ask its person for more permissions (Codex
refuses the escalation with no one to ask), and Codex hands no moment over. On the person's
Go, the driver writes Codex's own trust for each such hook at its current hash, through the
app server's config/batchWrite in Codex's home (hooks.state.<key>.trusted_hash). It
trusts only the hooks whose command is the runtime's hook line from the last plan. Where
every Steery hook runs already, the way is not-found. A hook that an administrator manages
is not the person's to trust. A driver on version 4 says the same as a note.
-
Conversations (
sessions/list,sessions/locate,sessions/read). The driver reads rollouts fromsessions/<yyyy>/<mm>/<dd>/rollout-<started-at>-<thread>.jsonl. A thread that continues in more than one rollout is one conversation. Its newest rollout is the current one. When two rollouts are equally current, they name the conversation ambiguously (complete: false). The driver lists a sub-agent's rollout under its lead, never as a conversation. (Thesession_idof that rollout names another thread.) The driver also does not list acodex execrun as a conversation. The driver reads a fork's history (history_base) from its parent's rollout, up to the point where the fork took it. Then comes aforkevent, then the fork's own rollout. The events are these:- turns and how they ended (a failure is classified by its status or by Codex's own code)
- the person's words, with the files and pictures that the person attached (with no fragments of Codex's own)
- the agent's words and reasoning
- calls and their results
- each response's own tokens (
token_usage_record, by its response id, cache writes included) - the running total, with the context left
- compactions, with the context before and after them. The context after is the count that Codex makes right after the compaction. Codex records no reason.
- models and efforts
- sub-agents that started, and how they ended
- rollbacks
The driver refuses a rollback that does not say how many turns went.
-
Setup (
setup/plan). The plan has these entries:- The MCP entry in
config.toml(mcp_servers.steery). Itstool_timeout_secis the runtime's bound. It hasdefault_tools_approval_mode = "approve", because underapproval_policy = "never"Codex refuses a tool that it would ask about. - The rule
rules/steery.rules, which runssteeryoutside Codex's sandbox. The macOS sandbox denies the Keychain, so inside the sandbox the CLI cannot reach this machine's key. - The skill in
skills/steery/SKILL.md. - One hook group per moment in
hooks.json, beside the person's own (/hooks/<Event>/-).
Codex runs a hook only after its person trusted it. Codex keys that trust by the hook's place. Another tool can put a group ahead of a Steery hook that the person trusted, and so move it. Then the plan writes the same trust again at the hook's new place. The plan asks Codex's own
hooks/listwhere the hook now stands, and never computes it here. - The MCP entry in
-
Hooks (
hook/read,hook/answer). Codex's documents become Moments. The driver keeps the model that each document names as state. An answer becomes what Codex parses:additionalContextonSessionStartandUserPromptSubmitdecision: "block"atStop- a
permissionDecisiononPreToolUse - a
decisionwith itsbehavior(and the standing permission chosen) onPermissionRequest
At protocol 17, each hook that says
contextdeclaresroom: 2500, and none saysnotice. Codex keeps 2,500 tokens of a paragraph, at 4 bytes a token, and saves a longer one to a file with a head and tail in its place. A character takes up to 4 bytes. -
Drive.
-
held: a native owner, where one takes the thread's words. The owner is the window of the Codex app that owns the thread. Or it is a running app server of its home that has the thread loaded with nothing queued. Else the runtime looks, because an app server that holds the thread is out of reach. -
idle: the owner's own state. Else, while nothing holds the rollout, the state of the rollout's newest turn. It gives the model and thinking that the thread runs on, and when its newest turn began and ended. The model and thinking come from the running app server'sthread/readwhere one has the thread loaded. Else they come from the rollout's newestturn_context. -
start: this binary in its turn mode,steery-driver-codex turn --codex <codex> <continue|fork|new> [<thread>] [--worktree] [--model m] [--thinking t] --inbox <socket>. A continue is refusedno-placewhere the folder that the thread opened in is gone: Codex resumes a thread only there, and every command of the turn would fail to start. The turn mode does these steps:- It opens the thread (
thread/resume,thread/fork,thread/start). Where the person's configuration names no sandbox for the folder (config/read), it asks forworkspace-write, as the Codex app does for each thread it starts. Codex otherwise runs a folder that nobody trustedread-only, and the turn writes nothing. - It starts the turn.
- It writes every message of the app server to standard output.
- It takes more words on the inbox (
turn/steer, orturn/startafter the turn ended). - It ends with the last turn.
A worktree goes where Codex makes its own,
<CODEX_HOME>/worktrees/<4 hex>/<repo>. - It opens the thread (
-
turn/read: the thread named, the words taken (by their delivery marker), and how each turn completed. Also the app server's refusals:harness-busybeside a live writer, andmodel-missingfor a turn that failedmodelNotFound(a model that Codex lists, but that the account does not get). The events of its lines go to the runtime before the driver reads the rollout. Each event has the rollout's own id. The events are these:- turns that began and ended
- the agent's words and reasoning
- shell and MCP calls and their results
- the running token total
- the model (rerouted included)
- the thread's title (
thread/name/updated)
The driver leaves a person's words and a compaction to the rollout. The app server names them by ids that the rollout does not keep.
-
stop: the owner interrupts its own turn, and the driver sees the turn end. A stop that names a say (protocol 7) interrupts only the turn that the say's words went into. It goes through the window or app server that owns the thread now, also for a terminal Codex's thread. When another turn runs, or the driver cannot tell which turn runs, the stop is refusedother-turn. When no turn runs, the answer isstopped: false. -
receipt/mark,receipt/find: the thread's turns before the words, and the one turn after them that carries the delivery marker. -
models: the app server'smodel/list, the default first.signed_incomes fromcodex login status(see Signing in). The driver watchesauth.jsonandsecrets/codex_auth.age, so it sees a login at once. At protocol 18, asigned_in: truelist also sayssigned_in_at: the latest of those files' changes and, on macOS, themdatof the keychain itemCodex Auth, accountcli|and 16 hex digits of the SHA-256 of Codex's home (itskeyringandautostores). -
reader:codex exec --json --ephemeralwith every MCP server off, no tool or feature that it does not need, and a read-only sandbox.reader/readtakes its last agent message. -
terminal:codex resume <thread>, and the app'scodex://threads/<thread>.
-
-
Live (
say,pick, andsession/changed) is for a conversation that Steery started.- Words go to the window that owns the thread. The window takes them as words typed into its
composer. Else they go into the running app server's queue. The queue's acknowledgement is
not delivery (
took: false). - The driver ties a say with an
id(protocol 7) to the turn that took its words. This is the turn that Codex named when it took them. Else it is the turn whose person input carries the say's delivery marker, once the thread's history has it.session/changednames the say in that turn'ssays, and insettledafter the turn ended. - The driver checks a pick against the list of an app server of its own. For a thread that a
running app server has loaded, the driver sets the pick as the thread's settings
(
thread/settings/update). For a thread that a window owns, the driver keeps the pick. It sends the pick with the next words that Steery says there (thread-follower-start-turncarries model and effort). The driver reads it back as picked. - The driver follows each thread that the runtime asks about, and says it as
session/changed. For a window, it follows the window's own state of the thread through the router. A running app server can have a thread loaded: the window's own, or one with nothing but its queue. The driver follows that thread through that app server. It looks at the thread every second, and at once onthread/status/changed. It never subscribes to the thread. An app server sends a thread's approvals to every client subscribed to it, and this client refuses them. - The live state carries these:
- the turn
pending(the queue,thread/queue/list)- the model and thinking
- the context left
- the calls that run, and the calls that ended lately (from the rollout's newest records)
settled
- Words go to the window that owns the thread. The window takes them as words typed into its
composer. Else they go into the running app server's queue. The queue's acknowledgement is
not delivery (
Build and check it, with Codex on PATH:
cd codex && cargo build
steery programs test target/debug/steery-driver-codex
cargo testOne binary, steery-driver-copilot, with no settings, at live. It speaks to GitHub Copilot
CLI only through what Copilot publishes:
- its conversation files under
session-state/ hooks/*.json,mcp-config.jsonandskills/copilot --headless --stdio(Copilot's own server: JSON-RPC withContent-Lengthframes)- the same server of a Copilot window started with
--ui-server, on its loopback port copilot -pwith--output-format json(a turn),copilot -s(a one-shot read),copilot --resume=<id>,copilot mcp list --jsonandcopilot login
Copilot's home is COPILOT_HOME, else ~/.copilot.
Copilot's own server is a module of this crate, not a crate of its own. Only Copilot speaks
it, and it is one JSON-RPC client of about 170 lines (rpc.rs). Drive asks it
auth.getStatus, models.list, sessions.fork and sessions.delete; Live asks a window's.
Needs (protocol 5). When auth.getStatus says isAuthenticated: false, the plan asks
sign-in in two ways:
copilot-sign-in:copilot login --device-code. Its page and one-time code are the step.github-token: a GitHub token.copilot login --with-tokenreads it on standard input, and Copilot keeps it.
- Conversations (
sessions/list,sessions/locate,sessions/read). The driver readssession-state/<id>/events.jsonl: one event on each line, each naming the event before it inparentId.workspace.yamlbeside it gives the folder and the times. A resume (--resume=<id>) appends to the same file. The driver does not list a run whoseclient_nameissdk: a program started it through Copilot's SDK. The events are turns and how they ended (abort: interrupted), the person's and the agent's words, reasoning, calls and their results, each response's tokens, compactions, models and sub-agents. - Setup (
setup/plan). The plan has these entries:- The MCP entry in
mcp-config.json(mcpServers.steery). - Steery's skill,
skills/steery/SKILL.md. - Steery's own hooks file,
hooks/steery.json. Copilot loads every file inhooks/, so the person's hooks stay where they are. Each hook runs the runtime's hook line with|| true: Copilot reads a non-zero exit atpreToolUseas a denied call.
- The MCP entry in
- Hooks (
hook/read,hook/answer), in Copilot's camelCase form:sessionStart,userPromptSubmitted,preToolUse,postToolUse,postToolUseFailure,permissionRequest,notification,agentStop,sessionEnd,subagentStart.sessionStartgives Steery's paragraph asadditionalContext, the only output Copilot reads there. This is how the agent learns its conversation's id.preToolUseanswerspermissionDecision(allow,deny,ask).permissionRequestanswersbehavior(allow,deny). Its document names no call id.- Copilot drops the output of
userPromptSubmitted, so Steery only reads it.
- Drive (
held,idle,stop,receipt/*,models,start,turn/read,reader,terminal).held: every Copilot that opens a conversation writesinuse.<pid>.lockin its folder. A lock counts while its process runs and started before the lock: a killed Copilot leaves its lock behind. Else the runtime looks.idle: the newest turn ofevents.jsonl, with its model, whereassistant.turn_endended it. An open turn gives no sample: a run that died leaves its turn open.models: the server'smodels.list, with each model'ssupportedReasoningEffortsas its thinking.autois listed first, but a run that names no model takes the model after it, so the driver lists that one first.start: this binary in its turn mode, which becomescopilot --output-format json --no-ask-user [--model m] [--reasoning-effort t] [--add-dir r]with the words on standard input.- A continue adds
--resume=<id>. Copilot names a resumed conversation only in its last line, so the turn mode first writes{"steery": {"named": <id>}}. A continue is refusedno-placewhere its folder is gone. - A fork asks the server's
sessions.forkfor a copy of the history, then resumes the copy. - A worktree and a hand-over are refused
selection-unsupported. - The turn runs without
--allow-all-tools: Copilot with no terminal denies each call that its own rules and Steery'spermissionRequesthook do not allow.
- A continue adds
turn/read: Copilot's lines are the events ofevents.jsonl, with the same ids, then aresultwithexitCode.tookis theuser.messagethat carries the delivery marker. Standard error givesmodel-missing,not-found,selection-unsupported,start-failed.stop: Copilot stops a turn gracefully only for the server client that runs it (session.abort). The runtime's signals end every other turn.receipt/*: no door, so no mark.reader:copilot -s --no-ask-user --no-custom-instructions --disable-builtin-mcps, with--excluded-toolsfor every source, or onlyview,grep,glob. The reader runs under a conversation id of its own (--session-id), andsessions.deletethen removes it.terminal:cd '<cwd>' && copilot --ui-server --resume=<id>, withCOPILOT_HOMEwhere it is set. The window it opens has a door.
- Live (
held,say,pick,stop,session/changed), doorpicks. Copilot's door is a window started withcopilot --ui-server. Its server listens on a loopback port of its process, andsession.getForegroundnames the conversation it shows.held: a live lock's process with a listening port whose window shows the conversation. Its stop isowner, with a token of the window and the turn's start.say:session.sendwith the say's id asclientTurnId.queueisenqueue;steerisimmediate, which goes in at the running turn's next model call.immediateis refusedharness-busywhile a turn runs or words wait.pick:session.model.switchTo, orsetReasoningEffortalone. Copilot takes any model name and fails at the next turn, so the driver checks the pick againstmodels.list.stop:session.abort, where the token still names the turn that runs.session/changed: the window'ssession.eventLog.read, waiting for new events. Copilot logs nosession.idle: anabort, a new turn'suser.message, orsession.metadata.isProcessingfalse ends a turn. While a turn runs, the driver asksisProcessingeach second.- A window that was not started with
--ui-serverhas no door:sayis refusedno-door.setup/plannotes this. Copilot 1.0.109 accepts--ui-serverbut--helpdoes not list it, and no setting turns it on.
cd acp-family && cargo build
steery programs test target/debug/steery-driver-copilot
cargo testOne binary, steery-driver-cursor, from release 2026.7.1. Cursor keeps each chat in a SQLite
file, store.db, under chats/<md5 of its folder>/<id>/ or acp-sessions/<id>/.
- Drive (
held,idle,stop,receipt/*,models,start,turn/read,terminal). Actsnewandcontinue. No fork, and no words while a turn runs.held: the process that holds SQLite's lock on the chat'sstore.db. Cursor holds it while the chat is open. Else the runtime looks.idle: how the chat's last turn ended instore.db. It stands while nobody holds it.models: each<id> - <name>line ofcursor-agent models, the default first. Cursor has no thinking setting of its own: a level is part of a model's id.start:cursor-agent -p --output-format stream-json [--resume <id>] [--model m] [--add-dir r], with the words on standard input.- Cursor does not refuse
--resumeof an id it does not know: it starts a new chat under it. So a continue of a chat that Cursor does not keep is refusednot-found. - A continue is refused
no-placewhere its folder is gone. --modelalso makes the model Cursor's default: Cursor writes it intocli-config.json. A continue keeps that model (keeps.model).- A thinking pick, a worktree, a fork and a hand-over are refused
selection-unsupported. - The turn runs without
--force. Steery'spreToolUsehook answers each call.
- Cursor does not refuse
turn/read: the first line,systeminit, names the chat, new or resumed. Theuserline is the words Cursor took. The last line,result, ends the turn. Cursor writes a refusal on standard error and exits 1:ActionRequiredError: ...(a usage limit, a model the plan leaves out) andError: ...(signed out) end the turnfailedwith that line, refusedrefused.Workspace Trust Requiredis refuseduntrusted.stop: Cursor has no way to end a turn from outside its process. The runtime's signals end the turn. They do not reach Cursor'sworker-server, which outlives every turn.receipt/*: the mark is the number of the chat's turns. A receipt is the one person's words after it that carry the delivery marker.terminal:cd '<cwd>' && cursor-agent --resume <id>.
cd acp-family && cargo build
steery programs test target/debug/steery-driver-cursor
cargo test --test cursorOne binary, steery-driver-cline, from release 3.0.74. Cline keeps its conversations in
<CLINE_DIR or ~/.cline>/data/db/sessions.db (table sessions), with each one's messages in
data/sessions/<id>/<id>.messages.json. The driver starts Cline's turns through its own ACP
server (cline --acp).
- Live (
held,say,pick,stop,session/changed), doorpicks. Cline's door is its hub: a websocket server on a loopback port thatcline hub ensurestarts. The lock file<CLINE_DIR>/data/locks/hub/production.jsonnames itsurlandauthToken.- A
clinewindow joins the hub only where one already runs. In--yoloor--sandboxit never joins. Such a window runs its turns itself and has no door:sayis refusedno-door.setup/plannotes this, andterminalrunscline hub ensurefirst. held: acliclient of the hub that takes part in the conversation. Its stop isowner, with a token of the hub's pid and the turn's start. Else Drive'sheld.say:session.send_input.queueis deliveryqueue;steerissteer, which goes in at the running turn's next model call.immediateis refusedharness-busywhile a turn runs or words wait. The hub'ssession.pending_promptsevents match the words to the say's id.pick:session.update_connectionwithmodelId. The hub takes any name, so the driver checks the pick againstmodels. Cline lists no thinking levels over ACP, so a thinking pick is refusedselection-unsupported.stop:run.abort, where the token still names the turn that runs. The proof is the conversation going idle.session/changed: the hub's event stream (stream.subscribefor the conversation).run.startedandsession.updatedstatus say when a turn starts and ends;tool.startedandtool.finishedsay its calls.- The window's footer keeps the model it opened with after a
pick. The next turn runs on the picked model.
- A
cd acp-family && cargo build
steery programs test target/debug/steery-driver-cline
cargo testOne binary, steery-driver-grok, from release 1.0.77. Grok keeps its conversations in
<GROK_HOME or ~/.grok>/sessions/<encoded folder>/<id>/updates.jsonl. The driver starts
Grok's turns headless (grok -p … --output-format streaming-messages-json).
- Live (
held,say,pick,stop,session/changed), doorpicks. Grok's door is its leader:grok agent leaderon the Unix socket<root>/leader.sock(GROK_LEADER_SOCKEToverrides it). Each frame is a 4-byte big-endian length and JSON; ACP rides in{"type": "acp"}after aregister.- A TUI joins the leader only in leader mode:
[cli] use_leader = true, or--leader. Leader mode is off by default, and a sandbox profile turns it off. Such a window has no door:sayis refusedno-door.terminalopensgrok --leader --resume <id>, andsetup/plannotes this to the person, without reading the config. held: a conversation thatactive_sessions.jsonnames and the leader keeps resident. Its stop isowner, with the running prompt's id as the token. Else Drive'sheld.- The driver follows a conversation with
session/resume, which attaches it to the leader's broadcasts with no replay. say:session/prompt; the leader queues a prompt that comes while a turn runs.steerwhile a turn runs is_x.ai/interject, which goes in at the turn's next safe point.immediateis refusedharness-busywhile a turn runs or words wait.pick:session/set_modelwith_meta.reasoningEffort. A thinking level Grok does not list is refusedselection-unsupported.stop:session/cancel, where the token still names the turn that runs. The proof is the conversation going idle.session/changed: the leader'ssession/updatebroadcasts (tool_call,tool_call_update,turn_completed) and_x.ai/sessions/changedroster rows for the model and thinking.
- A TUI joins the leader only in leader mode:
cd acp-family && cargo build
steery programs test target/debug/steery-driver-grok
cargo testOne binary, steery-driver-qwen, at observe, drive and live, from release 0.27.2. Qwen keeps
everything under its root, QWEN_HOME or ~/.qwen. Each conversation is one JSON-lines chat
file, projects/<folder>/chats/<id>.jsonl (the folder is the conversation's cwd with each
character that is not a letter or a digit as -), with <id>.title.json beside it.
- Drive (
held,idle,stop,models,start,turn/read,reader,terminal). Actsnew,continueandfork. No words while a turn runs.held: Qwen keeps no lock and no pid. The runtime looks for the processes that hold or name the chat file.qwen --acpserves every conversation its client opens, so it is named beyond, not stopped.idle: how the last turn in the chat file's end ended. It stands while nobody holds it.models:session/new'smodels.availableModelsof aqwen --acpthat is never prompted, the current one first. Qwen has no thinking level a run can pick.start:qwen -o stream-json --approval-mode yolo [-r <id> [--fork-session]] [-m m] [--add-dir r], with the words on standard input, which Qwen reads as the prompt.yoloruns every call unasked, so Steery'sPreToolUsehook is the turn's one gate.startis refusedrefusedwhere no settings scope that Qwen loads in the folder holds Steery's guarded hook, ordisableAllHooksturns hooks off.- The guard: where the hook fails in a turn Steery started (
STEERY_STARTEDnames the pid of Qwen's parent), the call is blocked (exit 2). In the person's ownqwenit lets the call go. Its timeout is the longest Qwen waits, as a timed-out hook lets the call run. - A continue or a fork of a conversation Qwen does not keep here is refused
not-found. A modelmodelsdoes not list is refusedmodel-missing. A thinking pick, a worktree and a hand-over are refusedselection-unsupported.
turn/read:systeminitnames the conversation (a fork's new id). Atool_useortool_resultis a call that began or ended.resultends the turn:successfinished, else failed with its error; anAPI Error: 404 model ... not foundis refusedmodel-missing. On standard error,No saved session found with IDis refusednot-foundand an auth errorrefused.stop: Qwen has no way to end a turn from outside its process. The runtime's signal ends it: Qwen exits 130 with noresult, and the turn reads interrupted.reader:qwen -o text --chat-recording=false --approval-mode plan, its tools held toread_file,grep_search,globor none, and no MCP server.terminal:cd '<cwd>' && qwen -r <id>, withQWEN_HOMEwhere the root is not~/.qwen. Where a daemon runs the conversation:qwen attach --port <port> --session <id> [--workspace '<cwd>'], a second client of the same run.
- Live (
held,say,pick,stop,terminal,session/changed), doorpicks. Qwen's door is its daemon,qwen serve: HTTP/1.1 with JSON on a loopback port. A daemon runs each conversation that a client loads in it (its Web Shell,qwen attach, its API) and writes its chat file. Aqwenin a terminal orqwen --acpruns no daemon, so it has no door.- The driver finds each daemon by its record,
daemon-<port>.jsonin$QWEN_RUNTIME_DIR/daemonor<root>/daemon. A daemon with--require-authtakes the token ofdaemon-<port>-<pid>.tokenbeside the record, elseQWEN_SERVER_TOKEN. held: the daemon whoseGET /session/<id>/statusanswers 200 holds it. The driver asks every daemon at once and takes the first 200; a daemon that never answers costs at most 2 s. Its stop isowner, with the running prompt's id. Else Drive'sheld.say:steerwhile a turn runs isPOST /session/<id>/mid-turn-message: the daemon puts the words in at the turn's next step, else runs them as their own turn.queue, andsteerwhere nothing runs, isPOST /session/<id>/prompt, which waits behind any prompt that runs or waits.immediateis refusedharness-busywhile a turn runs or words wait. No daemon:no-door.pick:POST /session/<id>/modelwithqwen.session.modelPersistDefault: false, so the person's default stays. A model the daemon does not know is refusedmodel-missing. A thinking level is refusedselection-unsupported.stop:POST /session/<id>/cancel, where the token still names the prompt that runs (elsestopped: false), or the named say went into it (elseother-turn). The cancel names no prompt: a turn that ends between the check and the cancel lets it reach the next one. Words that wait stay, and the next of them starts.session/changed: the daemon'sGET /session/<id>/events.turn_completesettles a turn's says,mid_turn_message_injectedadds steered says to the running turn,tool_callandtool_call_updateare calls,usage_updateiscontext_left, andpermission_requestis aconfirmdialog untilpermission_resolved. The driver asksturns/current,pending-promptsandmid-turn-messagesfor what runs and waits. It stops following where no client has the conversation and nothing runs.
- The driver finds each daemon by its record,
Ran (Qwen Code 0.27.2, /opt/homebrew/bin/qwen, ollama qwen3:1.7b, a temporary
QWEN_HOME): a new turn through start that ran run_shell_command past the hook and
finished; a continue with the hook denying, the call blocked and the turn finished; a
fork whose init named a new conversation, its chat file holding the source's records and
the source's file left as it was; a stop by SIGINT (exit 130, interrupted);
a missing hook binary blocking every call of a turn Steery started, and letting the calls
run where STEERY_STARTED names another process; start refused where
the settings hold no hook. The recorded turns are in acp-family/tests/qwen/turns.
Ran live (qwen serve on a loopback port, the same temporary QWEN_HOME): held naming the
daemon; a say that ran on ollama qwen3:1.7b, its 47 session/changed with calls and
context_left, settled after 154 s; pick to qwen3:0.6b, and an unknown model refused
model-missing; a second say, held naming its prompt, and stop cancelling it in 0.1 s;
with a local OpenAI-compatible stand-in model, steer folded into a running turn, queue
waiting behind it, immediate refused harness-busy, and say with no daemon refused
no-door.
cd acp-family && cargo build
steery programs test target/debug/steery-driver-qwen
cargo test --test qwenOne binary, steery-driver-antigravity, from release 1.5.5. The driver starts Antigravity's
turns through its own ACP server (agy acp).
- Live (
held,say,stop,session/changed), doorkeeps. Antigravity's door is the language server inside eachagywindow. It speaks Connect (HTTP/1.1, JSON) on a loopback port of the window's process. It takes a request only with the CSRF token that the window read fromANTIGRAVITY_SERVER_CSRF_TOKENas it started. Without that variable the token is random and never leaves the window.- A window that started without the variable has no door:
sayis refusedno-door.setup/plannotes this. Interminalthe shell makes a fresh token as the command runs, so the window it opens has a door and no history keeps the token. The driver reads the token from the window process's environment. held: the process that holds the conversation's presence lock, where a port of it answersHeartbeatwith that token. Its stop isowner, with a token of the window and the turn's start. Else Drive'sheld.say:SendUserCascadeMessagewith the say's id asclientMessageId.queueisMESSAGE_DELIVERY_STRATEGY_WHEN_IDLE, which goes in at once where nothing runs.steerisMESSAGE_DELIVERY_STRATEGY_NEXT_INVOCATIONwhile a turn runs.immediateis refusedharness-busywhile a turn runs or words wait.pickis refusedselection-unsupported. The server takes a model only together with words, and the person's next turn goes back to the model in the window's footer.stop:CancelCascadeInvocation, where the token still names the turn that runs. Steered words that wait stay waiting, and go in first at the next turn.session/changed: the window'sStreamAgentStateUpdates. Its first message is the whole state, then what changed:status(CASCADE_RUN_STATUS_IDLEends a turn),pendingAgentMessagesUpdate, and the steps ofmainTrajectoryUpdatefor the says that went in and the calls that run.
- A window that started without the variable has no door:
cd acp-family && cargo build
steery programs test target/debug/steery-driver-antigravity
cargo testOne binary, steery-driver-openclaw, at observe, drive and live, from release 2026.11.3. OpenClaw keeps
everything in its state folder, OPENCLAW_STATE_DIR or ~/.openclaw. Each agent's
conversations are in its SQLite store, agents/<agent>/agent/openclaw-agent.sqlite, which the
driver opens read-only.
-
Conversations. A conversation is a window of
session_windows, by itssession_id; windows thatprevious_session_idlinks bycompaction,rolloverorrecoveryread as one. Its records are the rows oftranscript_events, JSON or zstd-packed, each naming its parent; the read walks the path from the active leaf, throughleafrecords. A sub-agent is asession_nodesrow whosespawned_bynames the parent; its task is its first message with OpenClaw's internal context blocks left out. A heartbeat poll or a retry prompt begins a turn with no words of the person's.run-failed-before-replyfails the turn. An in-place compaction iscompactedwith its token counts and summary. -
Setup. Two entries:
- Steery's MCP server at
/mcp/servers/steeryofopenclaw.json, withtransport: streamable-http(a URL server without it speaks SSE) andrequestTimeoutMs.openclaw acprefuses the servers that an ACP client forwards, so Steery's server sits in the person's ownmcp.servers.openclaw mcp setrefuses while the gateway runs. A server written into the file directly works:openclaw mcp status --jsonthen shows itok. OpenClaw parses JSON5, and the runtime writes plain JSON. Thus where the file is not plain JSON, the plan notes it. - Steery's skill in
skills/steery/SKILL.md, the managed skills folder, which every agent reads. - Steery's hook command line in
steery/hookof the state folder, which OpenClaw does not read. OpenClaw's own hooks are JavaScript modules, not commands, so only a turn that this driver runs calls Steery's hook.
- Steery's MCP server at
-
Needs (protocol 5):
sign-in, whereopenclaw models status --json --checkexits 1. See Signing in. -
models:openclaw models list --json, the models of its configured providers that areavailable, with the one taggeddefaultfirst. Each key<provider>/<model>is split at its first/. -
Drive (
start,held,idle,receipt/mark,receipt/find,terminal,turn/read,hook/read,hook/answer). A turn is this driver's binary in its turn mode, speaking ACP toopenclaw acp, a bridge onto the gateway that runs every turn.new:session/newwithmcpServers []; the bridge names the session<agent>:acp-bridge:<id>.continue:session/resumeby that key.forkis refusedselection-unsupported: the bridge has none.- Steery names a conversation by its first window's id.
turn/readmaps the ACP id back to it. A bridge key sets onlyparent_session_key, so onlyspawned_bymarks a sub-agent. - The model:
openclaw gateway call sessions.patchon the key before the turn, as the bridge has no model option. A model the lastmodelslacks is refused. The thinking level is the session'sthought_leveloption. - Words told mid-turn go in as the next prompt, after the running one ends: a second prompt cancels the running one.
- A permission is the gateway's exec approval, relayed with the call's
rawInput.hook/readnames it as theexeccall. It reaches ACP where the gateway waits on a person for it: execask, or the session'spermissionMode: guarded. held: the live door's holder where the gateway answers for the session (below); else the newest window of a key that a run writes now (activeWriterRunId).terminal:openclaw tui --session <key>in the conversation's folder.
-
Live (
held,say,pick,stop,session/changed), doorpicks. OpenClaw's door is its gateway,ws://127.0.0.1:<port>: every client (TUI, Control UI, apps, channels,openclaw acp) runs its turns there. The port isOPENCLAW_GATEWAY_PORT, elsegateway.port, else 18789.- The driver joins as an operator (
gateway-client, modebackend, scopesoperator.read,operator.writeandoperator.approvals: a run takes its sender's scopes, and anexecthat asks fails at registration without the last) with the gateway's own secret fromopenclaw.json:gateway.auth.token, orgateway.auth.passwordin modepassword, elseOPENCLAW_GATEWAY_TOKENorOPENCLAW_GATEWAY_PASSWORD. It answersconnect.challenge, thensessions.subscribe. - A conversation is reached by its key, where the key writes it now and
sessions.describeknows the key. Elseno-door. held:{person: {door: picks, stop: {owner: <run id>}}},nullwhere no run writes it.say:chat.sendwith the driver's own run id asidempotencyKey, sotookis that the gateway named the same run.steerinto a running run:queueMode: steer, in at the run's next boundary. Elsefollowup, which starts a run where none runs.immediatewhile a run writes or words wait:harness-busy.pick:sessions.patchofmodel(<provider>/<model>, asmodelssplit it) andthinkingLevel, read back fromresolved. A model the lastmodelslacks ismodel-missing. A patch that raced a change of the session (SESSION_MUTATION_AUTHORIZATION_CHANGED, orUNAVAILABLEwhile a reset rewrites its storage) is sent again every 25 ms for up to 3 s, then refusedrefused.stop:chat.abortof the runheldnamed, checked againstsay; proof is the run's lifecycleendwithaborted: true.session/changed: from the session'sagentevents (lifecycle, tool, approval, compaction) andsessions.changedrows: the turn and its says, calls and ended calls,compacting,pending, model, thinking andcontext_left. An exec approval is aconfirmdialog,Allow <command>?: lifecyclewaiting-approvaluntilapproval-resolved, where the run waits for an approval client; theapprovalstream where it asks after its run. An approval open before the driver joined sent its event already: on joining a running session, a second, short connection with scopeoperator.adminlists it fromexec.approval.list(the gateway lists an approval only to its run's client or an admin), then closes. The operator stays no admin: the gateway runs an admin's words as its owner's. A closed connection sends an empty state.
- The driver joins as an operator (
Ran (OpenClaw 2026.11.3, /opt/homebrew/bin/openclaw, ollama qwen3:1.7b): five real
conversations of openclaw agent (an exec call, two failed turns, one zstd record, one
openclaw sessions compact) and a heartbeat, listed and read from ~/.openclaw;
setup/plan, mcp/list and models against ~/.openclaw (468 models, signed_in: true);
and against an empty OPENCLAW_STATE_DIR with no key, where models status --check exits 1
and the plan asks for sign-in. A real sub-agent, spawned by sessions_spawn through the
gateway's tools.invoke (with gateway.tools.allow lifting its default deny for the probe),
listed under its lead, left out of the list, and read in place: its task, its answer.
Drive ran on the live gateway (127.0.0.1:18789, ollama qwen3:1.7b and qwen3:0.6b):
new (end_turn in 19.3 s) and three continue turns; a write tool call read back;
receipt/find true for its delivery, false for another; --model ollama/qwen3:0.6b set
by sessions.patch, both answers from qwen3:0.6b; words told on the inbox heard and
answered as the next prompt; with exec ask: always, an exec approval through the hook,
read by hook/read, allowed once, then the turn-end hook; with permissionMode: guarded,
touch rejected at the hook (hook/answer deny: option deny), the gateway's result
Exec denied (… user-denied) and no file; held and idle going running then
finished during a turn; steery programs test all ok.
Live ran on the same gateway (qwen3:1.7b, a session that chat.send began): held with
owner: null, then the run id; say immediate starting a run (took: true), a second
immediate refused harness-busy; say steer into that run while its exec sleep 8 ran,
its words read after the tool result and answered in the same run (alpha-doneKIWI), the
turn settled with both says; pick of qwen3:0.6b and off read back, no-such-model
refused model-missing; say queue then stop: refused other-turn for an older say,
then stopped: true, settled failed with aborted (rpc); session/changed naming the
exec call, its end and context_left. A pick right after an abort was refused
SESSION_MUTATION_AUTHORIZATION_CHANGED once, before the retry was built.
The rest of Live ran on the same gateway, through a recording proxy:
- Exec approval (
security: allowlist,ask: on-miss, an approval client connected withoperator.admin, as the Control UI does):touchwaited;confirmdialogAllow touch /tmp/ocproof/approved.txt?within 0.2 s; it cleared whenopenclaw approvals resolveallowed once; the file was made. - Raced
pick: 240thinkingpicks during runs while another client sent 51sessions.reset. One try only: 11AUTHORIZATION_CHANGEDretried and passed, 13UNAVAILABLErefused. With 3 tries: 134 of 134 picks passed, 32 refusals retried. - Raced
pick, with the 3 s retry: 298 of 298 picks passed during runs with no resets; 69 of 72 with a reset every 500 ms; 117 of 126 with five clients resetting back to back (about 20 resets a second), each refusal after 3 s. 425 of 425 rawsessions.patchpassed during a whole run, so a run alone does not race a patch. - Joined mid-approval: a
touchwaited on an approval client that answers after 60 s; the driver started after, sent theconfirmdialogAllow touch …?2.7 s later, cleared it when the approval was answered, and kept one connection to the gateway.
Not verified: window chains, forks and leaf records (none in a real store: /new and an
idle session.reset kept the same window); needs/give with a real OpenRouter key; the
installer on a host without OpenClaw; ~/.npm-global/bin and ~/.local/bin as install
folders (read from install.sh, not seen installed); retry and jobs (no gateway
event for them seen); a gateway on a non-loopback bind or with a password.
cd acp-family && cargo build
steery programs test target/debug/steery-driver-openclaw
cargo testOne binary, steery-driver-gemini, with no settings, at observe, drive and live, from release
0.67.0. Gemini keeps each conversation in <GEMINI_CLI_HOME or ~>/.gemini/tmp/<project>/chats/,
one append-only JSON-lines file each (session-<time>-<id8>.jsonl).
- Drive (
start,held,idle,receipt/*,models,turn/read,terminal). Actsnewandcontinue; no fork, no hand-over, no thinking level. A turn is this driver's binary in its turn mode, speaking ACP togemini --acpin the turn's own process.held: Gemini keeps no lock and no pid of a running turn, so the runtime looks.terminal:cd '<cwd>' && gemini --resume <id>.
- Live, door
plugin. Gemini loads no plugin of Steery's, so the turn process is the conversation's copy. The runtime keeps it past its words (stdin: held). It dials the door thatsetup/planwrote to<root>/steery/door,mode: rpc, with its own pid.say: a secondsession/promptaborts Gemini's running turn (packages/cli/src/acp/acpSession.ts). Thus words to a running turn,steerorqueue, wait in the copy (queued_at,pending) and go in together as the next prompt at its end (taken_at).idlewords to a running turn are refusedharness-busy.stop:session/cancel;pick:session/set_model.compactruns nothing of Steery's. The copy keeps no records: a welcome that asks for entries getslost.
Ran (Gemini CLI 0.67.0, npm install -g @google/gemini-cli, a model API on the loopback
through GOOGLE_GEMINI_BASE_URL): tests/gemini.rs runs setup/plan, start and the launch
plan. The real gemini --acp dials the test as the door. A say goes in at once; words said
while it runs wait and go in at its end; stop cancels a running turn; the runtime's signal
closes the door; sessions/list and sessions/read then read Gemini's own chat file.
Not verified: a signed-in Google model (no account here); a permission through the hook; a
pick of a model; force on a running turn.
cd acp-family && cargo build
steery programs test target/debug/steery-driver-gemini
PATH="<gemini's folder>:$PATH" cargo test --test geminiOne binary, steery-driver-droid, at observe and drive, from release 1.9.0. Droid keeps everything
in ~/.factory. Each conversation is one JSON-lines file under sessions/, in one of three
layouts: sessions/<folder>/<id>.jsonl (the folder is the conversation's cwd with each /
as -), sessions/<id>.jsonl, and sessions/btw/<id>.jsonl (a side question). Beside each,
<id>.settings.json holds its model and the tokens it spent.
- Conversations. The first record,
session_start, gives the title, the folder, and in a forkparentandforkedAtMessageId. A fork reads as its own conversation beside its source, itsparentnamed. Eachmessagenames its parent byparentId; a turn runs from a person's prompt (a user message withinteractionMode) to itsagent_turn_outcome, matched byturnId.model_provider_unreachableand other failed outcomes fail the turn; a turn with no outcome whose file stood still for 60 s reads as interrupted. A resumed conversation appends to its own file.llm_onlyandcontext-…messages (the system reminders Droid sends the model) are not the person's words. A file with no person's prompt is excluded. - Setup. Entries the runtime writes:
- Steery's MCP server at
/mcpServers/steeryof~/.factory/mcp.json. - One hook per event below in
~/.factory/hooks.json, beside the person's own. Droid runs the user's hooks in every folder, with no trust prompt. - Steery's skill in
~/.factory/skills/steery/SKILL.md. - No
droid: Factory's installer,curl -fsSL https://app.factory.ai/cli | sh. Older than 1.9.0: refused, withdroid update.
- Steery's MCP server at
- Hooks.
SessionStart,UserPromptSubmit,PreToolUse(asks),PostToolUse,Notification,Stop,SessionEnd. Each document comes on standard input in Claude Code's shape (session_id,transcript_path,cwd,hook_event_name, …); the answer is printed in Claude Code's shape too (hookSpecificOutput.permissionDecision,additionalContext,decision: "block"). A tool's document carries no call id.SessionStartappends Steery's lead toCLAUDE_ENV_FILE. - Knowing.
FACTORY_SESSION_IDin the agent's shell names the conversation. - Models. Droid has no models command;
modelsreadsdroid exec --help: "Available Models" (the default marked(default), listed first), "Custom Models" from~/.factory/settings.json, and each Factory model's levels from "Model details". A custom model lists no levels. It watches~/.factory/settings.json. - Drive. A turn is
droid exec -o stream-json --skip-permissions-unsafe [-s <id> | --fork <id>] [-m <model>] [-r <level>] --cwd <cwd>, the words on standard input. Each line of standard output is one record that names the conversation bysession_id:system/init(the model), the person'smessage(the words went in, under the turn id the file gives),tool_callandtool_result(the file's call ids),completion(finished) orerror(failed;Authentication failedisrefused). Droid refuses an unknown model (Invalid model:,model-missing) or level (Unsupported reasoning effort,selection-unsupported) on standard error before any record. - The gate. Under
--auto, Droid's own gate ends a headless turn (Exec ended early: insufficient permission) at a call its level or its denylist does not allow:--auto lowat anExecute,--auto highat a denylisted command. So the turn runs with--skip-permissions-unsafe, Steery'sPreToolUsehook is its only gate, andstartrefuses without that hook in~/.factory/hooks.json. A denied call fails and the turn goes on. Where Steery's hook itself fails in a turn Steery started (STEERY_STARTEDnames Droid's parent), the setup command exits 2: Droid blocks the call. - Continue.
-sof an id Droid does not keep opens a new conversation under that id, sostartrefuses an id the store lacks (not-found), and a gone folder (no-place). No worktree, nohand.stopis the runtime's signals;terminaliscd '<cwd>' && droid --resume '<id>'.
Ran (Droid 1.9.0, ~/.local/bin/droid, no Factory account, ollama qwen3:1.7b as a custom
model): real droid exec conversations in /tmp/droid-obs (an Execute call, a resume, a
fork, a failed turn, an interrupted turn, an MCP call) listed and read from ~/.factory;
hook/read over the documents Droid handed a logging hook for each event above; setup/plan
and mcp/list against ~/.factory. For drive: droid exec -o stream-json turns under
--auto low, --auto high and --skip-permissions-unsafe, with a hook that let the call
run, denied it, and failed; a resume, a fork, a killed turn, an unknown model and level, and a Factory model
signed out. fixtures/droid/turns holds those records.
Not verified: sub-agents (Task, SubagentStop), compaction (PreCompact), a Notification
document (none fired in droid exec), the sessions/<id>.jsonl and sessions/btw/ layouts
(read from the store's shape, no real file), which of several same-named MCP servers Droid
loads, the installer on a host without Droid, and any turn on a Factory model (no account).
cd acp-family && cargo build
steery programs test target/debug/steery-driver-droidOne binary, steery-driver-kiro, at observe and drive, from release 3.3.0 of Amazon's
kiro-cli. Kiro keeps everything in ~/.kiro. Each conversation is a folder
sessions/<bucket>/<sess_id>/: session.json (title, folder, model, a fork's parent) and
messages.jsonl, one record per line; a sub-agent's records are in
sub-executions/<id>.jsonl.
- Conversations. A turn runs from a
turn_startrecord to itsturn_end; aturn_startwith noturn_endreads as interrupted. A fork copies its source's history and reads as its own conversation, itsparentnamed. A folder with nomessages.jsonl(Kiro opened it and no prompt reached it) is not listed. - Setup. Entries the runtime writes:
- Steery's MCP server at
/mcpServers/steeryof~/.kiro/settings/mcp.json. - Steery's hooks in a file of their own,
~/.kiro/hooks/steery.json, beside the person's. - The command a turn's permission hook runs, in
~/.kiro/steery/hook. - Steery's skill in
~/.kiro/skills/steery/SKILL.md. - No
kiro-cli: Kiro's installer,curl -fsSL https://cli.kiro.dev/install | bash. Older than 3.3.0: refused, withkiro-cli update.
- Steery's MCP server at
- Hooks.
SessionStart,UserPromptSubmit,PostToolUse,Stop,SessionEnd, in the person's ownkiro-cli chat. Each document comes on standard input in Claude Code's shape (session_id,hook_event_name,cwd, …) with no transcript and no call id: the store names the call.Stopreads{"decision":"block","reason":…}. Kiro takes a decision before a call only from an exit code, so Steery gates no call throughPreToolUse. - Knowing.
KIRO_SESSION_IDin the agent's shell names the conversation. - Models.
modelsopens a session ofkiro-cli acpand reads itsmodelconfig option (each model'seffortLevelgives its levels), afterwhoamisays someone is signed in. Kiro sets any model it is told, an unknown one too, sostartrefuses a model or level the list lacks (model-missing,selection-unsupported). - Drive. A turn is this driver's own turn mode against
kiro-cli acp(the shared ACP turn):session/new,session/loadto continue,session/forkto fork, the model throughsession/set_config_option. Kiro asks the client before a shell command (session/request_permission, the tool in_meta.kiro.toolId); the turn answers through Steery's hook, and without that hook the ask is rejected. An ACP turn loads no hook files.heldreads~/.kiro/session-leases/<id>.leaseand names its process while it lives. No worktree.stopis the runtime's signals (SIGTERM ends the turncancelled);terminaliscd '<cwd>' && kiro-cli chat --resume-id '<id>'.
Ran (Kiro CLI 3.3.0, ~/.local/bin/kiro-cli, claude-haiku-4.5): ACP turns in
/tmp/kiro-smoke started, continued, forked, stopped mid-sleep 60, and denied a touch
through a permission hook; kiro-cli chat runs in /tmp/kiro-w2 with a shell call, file
reads and a sub-agent, read from ~/.kiro and through a logging hook for each event above.
fixtures/kiro holds those files.
Not verified: compaction (PreCompact, PostCompact), PreTaskExec, the skill and MCP
entries loaded by a fresh kiro-cli chat, and the installer on a host without Kiro.
cd acp-family && cargo build
PATH="$HOME/.local/bin:$PATH" steery programs test target/debug/steery-driver-kiroOne binary, steery-driver-openhands, at observe and drive, from release 1.16.0. OpenHands keeps
everything in OPENHANDS_PERSISTENCE_DIR, else ~/.openhands. Each conversation is a folder
conversations/<id as 32 hex digits> (OPENHANDS_CONVERSATIONS_DIR moves it): base_state.json
and events/event-<NNNNN>-<event id>.json, one file per event, written once.
- Conversations. A
MessageEventfromuserbegins a turn, unless it is OpenHands' own nudge to a model that answered with neither a call nor words.ActionEventis a call;ObservationEvent,UserRejectObservationandAgentErrorEventend it.ConversationErrorEventfails the turn. No event ends a turn: the next prompt does, elseexecution_status. A folder with no person's prompt (an ACP session never prompted) is excluded.statsgives each response's tokens. - Setup. Steery's MCP server at
/mcpServers/steeryofmcp.json(transport: http); Steery's skill in~/.openhands/skills/steery/SKILL.md(the home's, whateverOPENHANDS_PERSISTENCE_DIRsays); Steery's hook command line in<root>/steery/hook, which only this driver's turns read. Nohooks.jsonentry: a turn is OpenHands' ACP client, and OpenHands asks it before it runs anything. - Hooks. OpenHands asks once per batch of actions (
Confirm Agent Actions), not per call. The moment's call is the oldestActionEventthat nothing answered yet. Allow isaccept, denyreject; thealwayssuggestion isalways_proceed. - Knowing. OpenHands gives the agent no conversation id.
- Models. The one model
agent_settings.jsonnames. Its ACP server sets no model or reasoning effort per session, sostartrefuses another model and any thinking level. - Drive. A turn is
openhands acpunderturn:session/neworsession/load, thensession/prompt. A loaded conversation works in its server's folder and saves that folder over its own, so a continue runs where the conversation ran; a gone folder isno-place. No fork, nohand.stopis the runtime's signal, asession/cancel. OpenHands leavesexecution_status: runningwhere its process ends, so a stopped turn reads as interrupted.terminaliscd '<cwd>' && openhands --resume '<id>'.
Ran (OpenHands CLI 1.16.0, ~/.local/bin/openhands, ollama qwen3:4b and qwen3:1.7b): real
conversations through openhands acp and this driver's turns: a terminal call allowed, a
continue rejected, calls that failed validation, an unknown model, a turn stopped mid-answer
and continued after. fixtures/openhands holds those folders and the permission documents.
Not verified: --headless --json -t (no permission asked: the driver does not run it),
OpenHands Cloud conversations, sub-agents, compaction, a PauseEvent, and the installer on a
host without OpenHands.
cd acp-family && cargo build
steery programs test target/debug/steery-driver-openhandsOne binary, steery-driver-amp, with no settings, at observe, drive and live. Amp keeps its threads
on ampcode.com, not on this host. Thus the driver reads them only through Amp's own CLI:
amp threads list --jsonandamp threads export <thread>amp -x --stream-jsonandamp threads continue <thread> -x --stream-json, which the runtime runsamp mcp list --jsonamp login
It reads one file of Amp's own: installationID in Amp's device-id.json
(~/.local/share/amp, or $XDG_DATA_HOME/amp on Linux). Nothing else of that folder: it also
holds Amp's accounts and secrets. Amp's settings are $XDG_CONFIG_HOME/amp/settings.json, else
~/.config/amp/settings.json.
Needs (protocol 5). When amp threads list says Amp is not signed in (see Signing in), the
plan asks sign-in in two ways:
amp:amp login, on a terminal of the driver's. Its printed link is the stepamp-return. Where it returns to Amp's loopback listener, the address fills the step. Else the person pastes Amp's code, which the driver types into the login's prompt.api-key: an Amp API key (sgamp_…, made at ampcode.com/settings/security). The driver checks it withamp threads list, and gives it back asAMP_API_KEY. The runtime keeps it sealed. A key in the environment wins over Amp's saved accounts.
- Conversations (
sessions/list,sessions/locate,sessions/read).sessions/listasks for the threads of this host's installation:amp threads list --json --include-archived --limit 500 --installation-id <id>. A listing that fills 500 is not complete. The list does not say how a thread ran. Thus the driver exports each thread that is new or changed since it last listed it: at most 50 in one call, 8 at a time, within 10 s. A thread left unexported waits for the next call, and the listing is not complete. A thread thatamp -xran (clientCLI Execute Mode) had nobody at it: it isexcluded.- A session names no transcript, because this host has none. Its folder is the thread's first tree.
sessions/readexports the thread whole within 8 s, under the method's 10 s bound. Amp says "does not exist" for a thread that is gone or another account's:not-found. The driver refuses an export larger than 64 MiB.- The events are these: turns and how they ended (
end_turn,cancelled,error), the person's words and pictures, the agent's words and thinking, calls and their results, each response's tokens, and the model. A message that Amp still writes holds the cursor back. A person can edit an earlier message, which cuts the thread there. Then the cursor's last message is gone, and the read starts again (reset). sessions/foldis refusedselection-unsupported: Steery's plugin sends no records.
- Setup (
setup/plan). The plan has three entries: the MCP entry in Amp's settings (amp.mcpServers.steery, its URL alone), the skill in Amp's own skills folder (skills/steery/SKILL.mdunder Amp's settings folder), and Steery's plugin in Amp's system plugins folder (plugins/steery.tsthere), the door's address filled in. Amp names no thread in an MCP call's_meta, so the entry sends noSteery-*header. - MCP servers (
mcp/list): see MCP servers. - Drive (
start,turn/read). A turn isamp -x --stream-json, the words on standard input. A new thread adds--no-archive-after-execute, asamp -xarchives its thread otherwise. A continue isamp threads continue <thread> -x --stream-json.- Amp picks no model: it runs a mode.
modelslists the built-in modesmedium(Amp's default),low,high,ultra, passed as-m.claude-codeneeds a linked Claude subscription and is left out. No thinking pick. - A thread keeps the mode of its first message. A continue that asks another mode is
refused
selection-unsupported(keeps.model). Fork and hand:selection-unsupported. turn/read:system/initnames the thread before Amp takes the words. Theuserline that holds the delivery marker istook.resultends the turn, failed with Amp'serrorwhere it is one. Standard error'sError:line:harness-busy(the thread is open in another Amp),not-found,refused(signed out, out of credits), elsestart-failed. A line gives no event: the runtime reads the thread.held: Amp keeps no registry of who has a thread open, so the runtime looks at strayampprocesses.idleexports the thread and samples its last ended turn.stophas no graceful step; withsay,other-turn. Noreader:amp -xsaves every run as a thread and cannot run without its tools.terminal:amp threads continue <thread>in the folder, and the thread's page on ampcode.com as its app.
- Amp picks no model: it runs a mode.
- Live, door
plugin. Amp runs each plugin as a child of theampprocess, TUI or-x. For each root thread that starts there, the plugin dials the door (§4.4). Itshellonames the thread, theampprocess's pid, and the mode:jsonfor a turn Steery started (STEERY_STARTEDnames theampprocess's parent), elsetui, orprintfor a person'samp -x. A thread with a parent thread is Amp's sub-agent: it opens no door. The door carries no entries and noliveframes: Amp gives a plugin no text while a message forms.say:appendUserMessage, withsteerwhile a turn runs.queuewords wait for the turn's end.agent.starttakes them. A one-shot run takes words only during its own turn.pick:selection-unsupported(a thread keeps its mode).stop: Amp'scancel, where the turn that runs is one that its words began; elseother-turn. A stop that names no say parks the thread.settleatagent.end: the runtime's words continue the thread (action: continue).compact: declined; the context starts at the thread's first message.
What ran live, on an account with no credits (Amp 0.0.1794225648 and 0.0.1794484845):
- A new turn through the driver's plan: named, took, ended
failed"Out of Credits",refused.sessions/readthen gave the person's words. - A continue in another mode: refused before anything ran.
terminal: the command and URL. amp threads continue <thread> -xwith no credits appends the words, prints nothing and exits 1 (Amp's log:ReferenceError: Cannot access 'ae' before initialization). Stdin, argument and--stream-json-inputalike. A continue that reaches the model is not checked.- Steery's plugin as a project plugin under
amp -x --stream-json(0.0.1794484845), against a stand-in door:hello(the thread'sT-…,mode: json, theamppid, cwd),welcome,state, and the turn's begin. Out of credits, Amp exits beforeagent.end, sosay,stopandsettleon a running turn are not checked.
How an agent in Amp learns its thread's id is not checked yet: no Amp turn has reached the
model under the driver. The skill tells the agent to send the T-… of its thread's address,
or AMP_THREAD_ID where it is set.
Build and check it, with Amp on PATH:
cd amp && cargo build
steery programs test target/debug/steery-driver-amp
cargo test
cd plugin && npm install && npm run checkOne binary, steery-driver-crush, with no settings, at live. Crush keeps each
project's sessions in that project's SQLite store, <project>/.crush/crush.db. The
projects are listed in projects.json of Crush's data folder: $CRUSH_GLOBAL_DATA, else
$XDG_DATA_HOME/crush, else ~/.local/share/crush. Crush never lists there a project that
only its server opened, so the driver adds the server's workspaces (GET /v1/workspaces,
within 1 s), each store once. The driver opens each store read only.
- Conversations (
sessions/list,sessions/locate,sessions/read).sessions/listlists every session of every project, where the project is. A sub-agent (parent_session_id) is listed under its lead. A session whose id beginstitle-is Crush's own, which names its lead, and is never listed.sessions/readreads a session'smessagesincreated_atorder, 200 at a time. The events are these: turns and how they ended, the person's words and pictures, the agent's words and thinking, calls and their results, a sub-agent's start, a summary, and the model. Anagentcall's sub-agent is the session<message>$$<call>.- A turn ends at an answer's
finish:end_turnfinished,canceledinterrupted,errorfailed with the provider's words. Crush keeps tokens only of a session's newest response, so a read gives them once, at its end. - An answer that the model still writes has no
finish. It holds the cursor back. sessions/foldis refusedselection-unsupported: Crush's door iskeeps, not a plugin.
- Setup (
setup/plan). The plan has the MCP entry in the person'scrush.json(mcp.steery,type: httpand its URL), the skill in Crush's own skills folder ($CRUSH_SKILLS_DIR, else<XDG_CONFIG_HOME or ~/.config>/crush/skills), and one hook entry per event, appended tohooks.<event>of the samecrush.json. Crush sends no_metawith an MCP call, so the entry sends noSteery-*header. - MCP servers (
mcp/list): see MCP servers. - Drive (
start,turn/read,stop,held,idle,models,receipt/*,terminal,hook/read,hook/answer). Acts: new and continue; no fork, no worktree.startrunssteery-driver-crush turn <home> <crush> run -q -v, with-s <id>,-m <model>and--reasoning-effort <level>where given, the words on standard input.crush runprints only the answer, so the turn mode reads Crush's log (-v) for the session id, then the project's store for how the turn ended.- A continue runs only in the project whose store keeps the session: else
no-place. crush runapproves every call of its session itself (AutoApproveSession), so Steery'sPreToolUsehook is the turn's only gate.startis refusedrefusedwhere the person'scrush.jsonlacks it.- Hooks:
PreToolUse(asks, 24 h),PostToolUseandPostToolUseFailure(say, 5 s). Words for the session reach it in thecontextof a call's result. - Crush runs a call whose hook fails. The
PreToolUseentry runs the hook in a subshell and exits 2 where it fails in a turn Steery started: the turn mode passesSTEERY_STARTEDto Crush under its own pid, and the hook's$PPIDis that pid. stop: the turn mode gets the runtime's signal and sends Crush SIGINT, as Ctrl-C. Crush writes the turncanceled.held: a person's window that shows the session through Crush's server holds it (Live, below). Else every Crush with the project open holds its store, so the runtime looks there.models:crush modelson a terminal, each<provider>/<id>, with labels, thinking and costs from Crush'sproviders.json;models.largefirst.terminal:cd '<project>' && crush --session <id>.
- Live (
held,say,pick,stop,session/changed). Doorkeeps: Crush's server.- A Crush TUI opened with
CRUSH_CLIENT_SERVER=1runs its sessions incrush server, one per person, oncrush-<uid>.sockin$XDG_RUNTIME_DIR, else the temporary folder (getconf DARWIN_USER_TEMP_DIRon a Mac), else/tmp. HTTP/1.1 over that socket. - A session is held where the server's workspace for its project shows it to a client
(
attached_clientsabove 0). A TUI without the variable runs in its own process: no door. - The driver follows the workspace's events (
GET /v1/workspaces/<id>/events) and sendssession/changed: the turn, the says it took, calls, permissions and questions as dialogs, the model of the last answer, and settled turns. The person answers a dialog in the window. A dialog that opened before the driver followed is not seen: the server lists no open permission. sayposts/agent. Words that steer go without a run id and Crush folds them into the running turn at its next step. Others carry a run id and queue as their own turn.tookonce Crush writes their message or lists them in its queue.pickwith a model or thinking is refusedselection-unsupported: Crush picks the model for a whole workspace. With neither it reads back the session's model.stopposts/agent/sessions/<id>/canceland waits up to 8 s for the session to go idle. Crush drops the words that wait with it.
- A Crush TUI opened with
Crush puts no session id in a shell command's environment or an MCP call. The skill tells
the agent to run crush session last --json in its folder and send meta.uuid. A live
turn checked it: the agent's bash call printed its own session's id.
Build and check it, with Crush on PATH:
cd crush && cargo build
steery programs test target/debug/steery-driver-crush
cargo testOne binary, steery-driver-warp, with no settings, at observe. Warp keeps its agent's
conversations in each channel's warp.sqlite: Stable's and Preview's, each the app's and the
terminal front end's tui/warp.sqlite beside it. On macOS they sit in Warp's app group
container (~/Library/Group Containers/2BBY89MBSN.dev.warp/Library/Application Support/<bundle id>),
else in Application Support; on Linux in $XDG_STATE_HOME/warp-terminal. The driver opens each
store read only.
- Sessions (
sessions/list,sessions/read,sessions/locate).- A row of
agent_conversationsis a conversation:summarya JSON of its title and first folder,conversation_dataa JSON naming the conversation that started it. - Its tasks are rows of
agent_tasks, each a Protocol Bufferswarp.multi_agent.v1.Task. The driver reads the wire by Warp's field numbers (apis/multi_agent/v1/task.proto), without a schema. - The conversation's own agent works in its root tasks. A task with a parent, and a conversation that another started, are listed as sub-agents under their lead.
- A conversation with
is_unlisted_auto_code_diffis Warp's own and is never listed. - A turn begins at a person's query. Each request ends with Warp's
request_metadata: tokens by model, andOUTCOME_COMPLETEDfinished,OUTCOME_CANCELEDinterrupted,OUTCOME_ERROREDfailed. - A request without that record still streams: its words hold the cursor back.
sessions/readreads 200 messages at a time.
- A row of
- Setup (
setup/plan). The MCP entry goes in~/.warp/.mcp.json, under the first key Warp reads there (mcp.servers,servers,mcpServers,mcp_servers), elsemcpServers. The skill goes in~/.warp/skills. Warp sends no_metawith an MCP call, so the entry sends noSteery-*header. - MCP servers (
mcp/list): see MCP servers. - No drive and no live.
oz agent runruns Warp's agent headless but needs a Warp sign-in. The Warp CLI is a TUI only. Warp has no hooks.
Warp puts no conversation id in a shell command's environment or an MCP call. The skill tells
the agent to read the newest conversation_id of agent_conversations and check its title.
Build and check it, with Warp installed:
cd warp && cargo build
steery programs test target/debug/steery-driver-warp
cargo testOne binary, steery-driver-aider, with no settings, at drive. Aider keeps each
conversation as a Markdown chat history file that it appends to:
.aider.chat.history.md in the git root, or the file --chat-history-file names. The
id of a conversation is the SHA-256 of its file's path.
- Sessions (
sessions/list,sessions/read,sessions/locate).- The driver walks home 6 folders deep for the files, and reads the files the runtime
names. The walk skips
Library,Applications,Movies,Music,Pictures, and build output (node_modules,target,dist,build,vendor,venv,Pods). - A file whose every run took its words from
--messageor--message-fileis excluded. # aider chat started atopens a run. Its> Model:or> Main model:line is amodelevent.####lines are the person's words and begin a turn. The model's answer is the agent's words; its<thinking-content-…>block is a thought. Other>lines are thoughts.> Tokens:is atokensevent.- A turn ends at the next words or run:
failedafter a litellm error,interruptedafter^C. Aider writes no end, so the last turn stays open;idlesays how it ended. - The cursor is a byte offset and a hash of the 256 bytes before it.
- The driver walks home 6 folders deep for the files, and reads the files the runtime
names. The walk skips
- Setup (
setup/plan). No entries: Aider reads no MCP server, skill or hooks.mcp/listis refused. - Drive (
start,turn/read).startrunssteery-driver-aider turn <aider> --yes-always … --model <model> --chat-history-file <file> --message-file /dev/stdin, the words on standard input.- A new conversation takes the git root's
.aider.chat.history.md, else.aider.chat.history.<ms>.mdbeside it. A continue adds--restore-chat-history, only in the file's folder. A start with no model and none in the file refusesmodel-missing. modelslistsollama listasollama_chat/<name>; other litellm models are unlisted.stophas no graceful step: the turn mode forwards a signal to Aider asSIGINT.
- No live: Aider has no hooks, MCP, ACP or server.
Build and check it, with Aider installed:
cd aider && cargo build
steery programs test target/debug/steery-driver-aider
cargo testMIT, see LICENSE.