johannSoCodeyPublic

plan: run Codey inside T3 Code through its Grok provider slot

T3 Code's drivers are compiled in and there is no plugin mechanism, but
every driver takes a user-set binary path and driver kinds are an open
slug. So the way in is to occupy a slot rather than add one.

Researched all four candidate surfaces against pingdotgg/t3code 9accc567.
Claude is driven through Anthropic's own SDK behind a version-gated model
manifest; Codex is a 99-method schema-pinned mirror of OpenAI's protocol;
OpenCode is a server, not a CLI. Grok is a plain ACP agent spawned as
'<binaryPath> agent stdio', gated only by two regex-loose shell probes,
and it does not fingerprint the agent the way Antigravity does.

The design doc carries the field-level contract; the plan builds
internal/acp and internal/serve on top of the Observe and Approve seams
the agent loop already has.

Browse Files

Jjonicommitted 4 weeks ago1 parent aa469bacommitc1086c0

Showing 2 changed files with 765 additions and 0 deletions.

+459−0docs/superpowers/plans/2026-09-19-t3code-provider.mdaddedView File

++ # Codey inside T3 Code — implementation plan
++ > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
++ **Goal:** Run Codey as an agent inside T3 Code without touching T3 Code's
++ source. The user enables the Grok provider in **Settings → Providers**, sets
++ **Binary path** to the `codey` binary, and gets Codey threads with streaming
++ text, visible tool calls, working approvals and a stop button.
++ **Architecture:** Codey grows a third front end alongside the TUI and `-p`.
++ `internal/acp` owns the wire — newline-delimited JSON-RPC 2.0 over stdin and
++ stdout, with the handful of ACP methods T3 Code actually exercises.
++ `internal/serve` is the bridge: one `*agent.Agent` per ACP session, its
++ `Observe` callback translated into `session/update` notifications and its
++ `Approve` gate translated into `session/request_permission` round trips.
++ `cmd/codey` grows an `agent stdio` verb plus the two shell probes T3 Code runs
++ before it will show the provider as ready. Nothing in `internal/agent`,
++ `internal/llm` or `internal/tui` changes in phase 1.
++ **Tech Stack:** Go 1.26, stdlib only — `encoding/json`, `bufio`, `context`,
++ `sync`. No ACP library exists for Go and the surface is five methods; hand-
++ rolling it is smaller than a dependency.
++ **Spec:** `docs/superpowers/specs/2026-09-19-t3code-provider-design.md` — read
++ it first. It carries the evidence for why the Grok slot and not Codex's
++ app-server, and the exact field-level contract quoted out of T3 Code's source.
++ ## Global Constraints
++ - Go module is `codey`; import paths are `codey/internal/...`.
++ - **Stdout belongs to the protocol.** In `agent stdio` mode nothing may write
++   to stdout except the JSON-RPC encoder — no `fmt.Println`, no metrics logger,
++   no stray `log`. Diagnostics go to stderr, which T3 Code drains and (on the
++   Grok path) discards. A single stray line desynchronises the parser and the
++   thread dies with a decode error.
++ - **`jsonrpc: "2.0"` is mandatory on every message we send.** T3 Code's ACP
++   codec declares it `Schema.Literal("2.0")` on requests, notifications and
++   responses (`packages/effect-acp/src/_internal/shared.ts:83-103`). This is the
++   opposite of their Codex path, where the field must be absent — do not carry
++   habits between the two.
++ - **A notification must have no `id` key.** Not `null`, absent.
++ - **Never leave an inbound request unanswered**, including methods we do not
++   implement: answer `-32601`. T3 Code answers our requests on its read loop, so
++   a hang on either side stalls the whole session.
++ - T3 Code's inbound notification queue is `sliding(32)`
++   (`packages/effect-acp/src/protocol.ts:89`). Coalesce text deltas rather than
++   emitting one notification per token.
++ - `internal/acp` imports no other `internal` package and knows nothing about
++   agents: it is a JSON-RPC peer with ACP's types. `internal/serve` may import
++   `internal/acp`, `internal/agent`, `internal/tools`, `internal/approval`;
++   nothing imports `internal/serve` back except `cmd/codey`.
++ - Every test is offline and in-process: a `net.Pipe` or an `io.Pipe` pair, no
++   subprocess, no network, no sleeping on wall-clock time.
++ - New exported identifiers get a doc comment in the existing house style.
++ - Run `gofmt -w` on every file you touch, and `go test ./...` before each task
++   is ticked off.
++ ---
++ ## Phase 1 — a text turn appears in T3 Code
++ ### Task 1: `internal/acp` — types and the JSON-RPC peer
++ **Files:**
++ - Create: `internal/acp/wire.go`, `internal/acp/types.go`, `internal/acp/conn.go`, `internal/acp/conn_test.go`
++ **Interfaces:**
++ - Consumes: nothing.
++ - Produces:
++   ```go
++   // wire.go
++   type Message struct {
++       JSONRPC string          `json:"jsonrpc"`
++       ID      *json.RawMessage `json:"id,omitempty"`
++       Method  string          `json:"method,omitempty"`
++       Params  json.RawMessage `json:"params,omitempty"`
++       Result  json.RawMessage `json:"result,omitempty"`
++       Error   *Error          `json:"error,omitempty"`
++   }
++   type Error struct { Code int `json:"code"`; Message string `json:"message"`; Data any `json:"data,omitempty"` }
++   const (
++       CodeParse = -32700; CodeInvalidRequest = -32600
++       CodeMethodNotFound = -32601; CodeInvalidParams = -32602; CodeInternal = -32603
++   )
++   // conn.go
++   type Handler interface {
++       Initialize(context.Context, InitializeRequest) (InitializeResponse, error)
++       Authenticate(context.Context, AuthenticateRequest) error
++       NewSession(context.Context, NewSessionRequest) (NewSessionResponse, error)
++       Prompt(context.Context, PromptRequest) (PromptResponse, error)
++       Cancel(context.Context, CancelParams)
++   }
++   type Conn struct{ /* unexported */ }
++   func NewConn(r io.Reader, w io.Writer, h Handler) *Conn
++   func (c *Conn) Serve(ctx context.Context) error            // returns nil on clean EOF
++   func (c *Conn) Notify(ctx context.Context, method string, params any) error
++   func (c *Conn) Request(ctx context.Context, method string, params any, out any) error
++   ```
++   `types.go` holds the ACP structs, spelled exactly as the spec quotes them:
++   `InitializeRequest{ProtocolVersion int, ClientCapabilities, ClientInfo}`,
++   `InitializeResponse{ProtocolVersion int, AgentInfo, AgentCapabilities, AuthMethods}`,
++   `AuthenticateRequest{MethodID string}`, `NewSessionRequest{Cwd string,
++   McpServers []json.RawMessage, AdditionalDirectories []string}`,
++   `NewSessionResponse{SessionID string, Models *ModelState}`,
++   `PromptRequest{SessionID string, Prompt []ContentBlock}`,
++   `PromptResponse{StopReason string}`, `SessionNotification{SessionID string,
++   Update Update}`, `RequestPermissionParams/Result`.
++   `ContentBlock` is a tagged struct (`Type`, `Text`, `Data`, `MimeType`, `Path`)
++   — decode leniently, we only read `text`.
++ **Behaviour that the tests pin down:**
++ Reader goroutine owns the decoder; **each inbound request is dispatched on its
++ own goroutine** so that a `session/cancel` notification arriving mid-prompt is
++ seen immediately. A single mutex serialises writes. Outbound request ids are
++ integers from a counter; replies are correlated through a `map[string]chan`
++ keyed by `string(id)`.
++ - [ ] **Step 1: Write the failing tests**
++   `conn_test.go` drives a `Conn` over an `io.Pipe` pair with a stub handler
++   and asserts: every outbound line carries `"jsonrpc":"2.0"`; a notification
++   line has no `id` key at all (assert on the raw bytes, not on a decoded map);
++   a request for an unknown method comes back as `-32601` with the same `id`; a
++   handler returning an error becomes `-32603` and does not kill the connection;
++   malformed JSON on a line is answered `-32700` where an id can be recovered
++   and skipped otherwise, and the loop survives; `Request` blocks until the
++   matching response arrives and returns the decoded result; `Request` with a
++   cancelled context returns `ctx.Err()` and drops the pending entry; a
++   `session/cancel` notification is delivered while a `session/prompt` handler
++   is still running; clean EOF on the reader returns `nil` from `Serve`.
++ - [ ] **Step 2: Implement `wire.go` and `types.go`**
++   Encoding is one compact JSON object per line. `ID` is kept as
++   `json.RawMessage` so a string id and a numeric id both round-trip byte-exact.
++ - [ ] **Step 3: Implement `conn.go`**
++ - [ ] **Step 4: Verify**
++ ```bash
++ gofmt -w internal/acp && go test ./internal/acp/...
++ ```
++ ---
++ ### Task 2: `internal/serve` — the session bridge, text only
++ **Files:**
++ - Create: `internal/serve/serve.go`, `internal/serve/session.go`, `internal/serve/update.go`, `internal/serve/serve_test.go`
++ **Interfaces:**
++ - Consumes: `internal/acp`, `internal/agent`, `internal/tools`, `internal/metrics`.
++ - Produces:
++   ```go
++   type Options struct {
++       NewAgent func(root string) (*agent.Agent, error) // one agent per session
++       Log      *metrics.Logger
++   }
++   type Server struct{ /* unexported */ }
++   func New(opts Options) *Server
++   func (s *Server) Run(ctx context.Context, r io.Reader, w io.Writer) error
++   ```
++   `NewAgent` is a factory taking the session's `cwd`, mirroring the
++   `toolsIn(root)` factory `cmd/codey/main.go:286` already uses to rebuild a
++   tool set against a worktree. T3 Code hands us a cwd per `session/new` and it
++   is not necessarily the process's own.
++ **Behaviour:**
++ - `initialize` → `{protocolVersion: 1, agentInfo: {name: "codey", version},
++   agentCapabilities: {promptCapabilities: {image: true}}, authMethods: []}`.
++   Accept any `protocolVersion` the client offers and answer with `1`; T3 Code
++   sends `1` today (`acp/AcpSessionRuntime.ts:696-705`).
++ - `authenticate` → `{}` for any `methodId`. T3 Code sends `cached_token` or
++   `xai.api_key` and does not catch a failure here, so this must never error.
++ - `session/new` → build an agent rooted at `params.cwd`, store it under a fresh
++   session id (`codey-` + 16 random hex), reply `{sessionId}`. Ignore
++   `mcpServers`.
++ - `session/prompt` → concatenate the text blocks, run the agent, stream, reply
++   `{stopReason: "end_turn"}`. `"cancelled"` if the session was cancelled,
++   `"refusal"` on a hard agent error after emitting the error text as a chunk.
++ - `session/cancel` → cancel that session's in-flight turn context. Idempotent,
++   and harmless when nothing is running.
++ `update.go` owns the translation, and is the file worth unit-testing hardest:
++ | `agent.Event` | `session/update` |
++ |---|---|
++ | `EventTextDelta` | `agent_message_chunk` with `content: {type: "text", text}` |
++ | `EventText` (non-streaming) | same, once |
++ | everything else | dropped in phase 1 |
++ Deltas are coalesced: buffer until 50 ms have passed or 512 bytes have
++ accumulated, then flush one notification. This is what keeps us clear of T3
++ Code's `sliding(32)` queue on a fast model.
++ - [ ] **Step 1: Write the failing tests**
++   Drive `Server.Run` over pipes with a fake `NewAgent` whose `Run` emits a
++   scripted `[]agent.Event`. Assert: the full handshake in order
++   (`initialize` → `authenticate` → `session/new` → `session/prompt`) produces a
++   session id and a `{stopReason:"end_turn"}`; the text arrives as
++   `session/update` notifications carrying the session id and reassembling to
++   the original string; deltas are coalesced rather than one-per-event; a
++   `session/prompt` for an unknown session id is an error, not a panic; a
++   `session/cancel` during a turn cancels the agent's context and the prompt
++   replies `{stopReason:"cancelled"}`; two sessions run concurrently without
++   their updates crossing over.
++ - [ ] **Step 2: Implement `session.go`** — the session table, per-session
++   mutex, per-turn cancel func.
++ - [ ] **Step 3: Implement `update.go`** — the event translation and the
++   coalescer. The coalescer takes a clock function so tests do not sleep.
++ - [ ] **Step 4: Implement `serve.go`** — wire the handler methods onto the
++   session table.
++ - [ ] **Step 5: Verify**
++ ```bash
++ gofmt -w internal/serve && go test ./internal/serve/...
++ ```
++ ---
++ ### Task 3: `cmd/codey` — the `agent stdio` verb and the two probes
++ **Files:**
++ - Modify: `cmd/codey/main.go`
++ - Create: `cmd/codey/agentcmd.go`, `cmd/codey/agentcmd_test.go`
++ **Behaviour:**
++ Argument parsing has to be positional-agnostic, because T3 Code splits its
++ flags around the subcommand: `--permission-mode default agent stdio`, but
++ `agent --always-approve stdio` (`acp/GrokAcpSupport.ts:33-46`). Scan `os.Args`
++ for the bare words `agent` and `stdio` and for the three flags anywhere in the
++ line; ignore anything else rather than erroring, since `launchArgs` is a free
++ text field the user can put anything in.
++ Three entry points:
++ - `codey --version` → one line, `codey <semver>`, exit 0. Must match
++   `/\bv?(\d+\.\d+\.\d+)\b/` (`apps/server/src/provider/providerSnapshot.ts:114-119`).
++   Keep the existing `-v` verbose flag working; `--version` is new and distinct.
++ - `codey models` → exit 0, and print, in this order:
++   ```
++   You are logged in as <endpoint or account>.
++   * codey-opus-5 (default)
++   - codey-sonnet-5
++   ```
++   T3 Code reads login state off `/you are logged in/i` and models off
++   `^\s*[*-]\s+(\S+)` bullet lines, with `(default)` marking the default
++   (`Layers/GrokProvider.ts:258-286`). Source the list from the same
++   `GET /v1/models` the TUI model picker uses; on failure print the configured
++   model alone and still exit 0 — a non-zero exit makes T3 Code discard the
++   whole listing.
++ - `codey agent [--permission-mode X] [--always-approve] stdio` → build the
++   `serve.Server` and run it on stdin/stdout.
++ Permission modes map onto the existing `approval.Policy`:
++ | T3 Code mode | Codey behaviour |
++ |---|---|
++ | `default` (or absent) | ask for every mutating tool |
++ | `acceptEdits` | auto-approve `edit`/`write`, ask for `bash` |
++ | `auto` | auto-approve all but ask for anything the policy calls non-rememberable |
++ | `--always-approve` | the equivalent of `-yolo` |
++ - [ ] **Step 1: Write the failing tests**
++   `agentcmd_test.go` tests the argument scanner as a pure function over
++   `[]string` — all five argv shapes T3 Code produces, plus junk from
++   `launchArgs`, plus `--version` and `models`. Then a test that asserts the
++   version line matches T3 Code's regex and the `models` output parses under a
++   Go transliteration of their bullet parser.
++ - [ ] **Step 2: Implement the scanner and the three entry points**
++   Take the branch as early in `main` as possible — before the metrics logger
++   opens, before the wizard, before anything can print to stdout.
++ - [ ] **Step 3: Verify**
++ ```bash
++ gofmt -w ./cmd/codey && go test ./... && go build -o /tmp/codey ./cmd/codey
++ /tmp/codey --version && /tmp/codey models
++ ```
++ ---
++ ### Task 4: End-to-end against the real T3 Code
++ **Files:**
++ - Create: `internal/serve/conformance_test.go`
++ **Steps:**
++ - [ ] **Step 1: A conformance test that replays T3 Code's exact handshake**
++   Hard-code the literal JSON T3 Code sends — `initialize` with
++   `{"protocolVersion":1,"clientCapabilities":{"fs":{"readTextFile":false,"writeTextFile":false},"terminal":false},"clientInfo":{"name":"t3-code","version":"0.0.0"}}`,
++   then `authenticate` with `{"methodId":"cached_token"}`, then `session/new`,
++   then `session/prompt` — and assert our replies decode against the shapes in
++   the design doc. This file is the early-warning system for their churn: when
++   a nightly breaks us, this is what tells us where.
++ - [ ] **Step 2: Wire it up by hand**
++   In T3 Code: Settings → Providers → Grok → enable, Binary path = the built
++   `codey`, instance display name "Codey". Or edit `~/.t3/userdata/settings.json`
++   directly (restart the app afterwards):
++   ```json
++   "providerInstances": {
++     "codey": {
++       "driver": "grok",
++       "displayName": "Codey",
++       "enabled": true,
++       "config": { "binaryPath": "/home/joni/Work/GO/coding-harness/codey" },
++       "environment": [
++         { "name": "ANTHROPIC_API_KEY", "value": "sk-ant-...", "sensitive": true }
++       ]
++     }
++   }
++   ```
++   The per-instance `environment` array is how Codey gets its credential without
++   inheriting whatever the desktop app was launched with.
++ - [ ] **Step 3: Confirm the provider card and one turn**
++   The card should read installed, authenticated, with our model list. Start a
++   thread, ask something that needs no tools, and watch the text stream in.
++ - [ ] **Step 4: Capture the traffic for the next phase**
++   T3 Code logs every provider event to
++   `~/.t3/userdata/logs/provider/events.<threadId>.log`, tagged `CANON:` for its
++   normalised model and `NTIVE:` for the raw wire. That file is the ground truth
++   for anything phase 2 gets wrong.
++ ---
++ ## Phase 2 — a first-class provider
++ ### Task 5: Tool calls become visible
++ **Files:**
++ - Modify: `internal/agent/loop.go` (add `ID` to `Event`), `internal/serve/update.go`
++ - Modify: `internal/agent/loop_test.go`, `internal/serve/serve_test.go`
++ `agent.Event` carries `Tool string` but nothing pairing a start with its result
++ (`internal/agent/loop.go:180-191`). ACP keys `tool_call` and `tool_call_update`
++ by `toolCallId`. Pairing by order would work today because dispatch is
++ sequential, but it is a landmine the first time it is not.
++ - [ ] **Step 1:** Add `ID string` to `agent.Event`, populated from the
++   `tool_use` block's id on `EventToolStart` and echoed on `EventToolResult`.
++   Existing observers ignore it; the TUI is unaffected.
++ - [ ] **Step 2:** Emit `tool_call` on start with
++   `{toolCallId, title, kind, status: "pending", rawInput}` and
++   `tool_call_update` on result with `status: "completed"|"failed"` and
++   `content: [{type: "content", content: {type: "text", text}}]`.
++   `kind` maps our tools onto ACP's vocabulary: `read`, `edit`, `execute`,
++   `search`, `fetch`, `think`, `other`.
++ - [ ] **Step 3:** Verify the tool rows render in T3 Code, and that a failed
++   tool shows as failed rather than silently completing.
++ ### Task 6: Approvals
++ **Files:**
++ - Modify: `internal/serve/serve.go`, `internal/serve/session.go`
++ - [ ] **Step 1:** Implement an `approval.Prompt` that sends
++   `session/request_permission` with
++   `options: [{optionId:"allow-once", name:"Allow", kind:"allow_once"},
++   {optionId:"allow-always", name:"Always allow", kind:"allow_always"},
++   {optionId:"reject-once", name:"Reject", kind:"reject_once"}]`
++   and blocks on the reply. Use exactly those three ids: Grok echoes back one of
++   ours, but Cursor's adapter hardcodes those literals
++   (`acp/AcpAdapterSupport.ts:46-55`), so choosing them now means the same binary
++   works in a Cursor instance too.
++ - [ ] **Step 2:** Map the reply — `selected`/`allow-always` →
++   `approval.AlwaysThisCommand`, `selected`/`allow-once` → `Once`,
++   `selected`/`reject-once` → `Deny`, `cancelled` → abort the turn.
++ - [ ] **Step 3:** Respect the launch permission mode: in `--always-approve` no
++   request is sent at all.
++ - [ ] **Step 4:** Verify against T3 Code's approval panel, including the
++   interaction with its own permission-mode selector, and confirm that
++   cancelling a pending approval does not wedge the session.
++ ### Task 7: Models, effort and the picker
++ **Files:**
++ - Modify: `internal/serve/serve.go`, `cmd/codey/agentcmd.go`
++ - [ ] **Step 1:** Return the model list in `session/new` as
++   `{models: {currentModelId, availableModels: [{modelId, name}]}}`. T3 Code's
++   Grok path reads it (`acp/GrokAcpSupport.ts:124-154`) and prefers it over the
++   `codey models` output.
++ - [ ] **Step 2:** Handle `session/set_model` / `session/set_config_option` by
++   switching the session's model, and reply `{}` to any config option we do not
++   recognise rather than erroring — Cursor's adapter sends one unconditionally.
++ - [ ] **Step 3:** Carry reasoning effort through `_meta.reasoningEffort` if it
++   is present on the selected model.
++ ---
++ ## Phase 3 — polish, in rough order of value
++ - [ ] **Reasoning.** Surface thinking blocks from the loop as
++   `agent_thought_chunk`. Needs a new event kind in `internal/agent`; today the
++   loop never reports them to observers.
++ - [ ] **Diffs.** Emit `tool_call` content of kind `diff` with `path`, `oldText`,
++   `newText` from `edit`/`write`, so T3 Code's diff viewer lights up instead of
++   showing our text summary.
++ - [ ] **Resume.** Advertise `agentCapabilities.sessionCapabilities.resume` and
++   implement `session/load` on top of `agent.ResolveSession`, replaying the
++   history as `session/update`s. Until we advertise it, T3 Code will not ask
++   (`acp/AcpSessionRuntime.ts:726`), so this is purely additive.
++ - [ ] **Plans.** Map our todo-ish output onto the `plan` update, or skip it —
++   it is optional and we have no plan object today.
++ - [ ] **Slash commands.** `available_commands_update` can expose `/compact` and
++   the skills list in T3 Code's composer.
++ - [ ] **Usage.** Feed token counts somewhere visible; the Grok path has no
++   usage channel, so this may be the first thing that argues for the fork.
++ - [ ] **README.** A "Using Codey from T3 Code" section: the settings recipe,
++   what the Grok branding means, and the fact that it says Grok on the tin.
++ ---
++ ## How we will know it works
++ 1. `go test ./...` green, including the conformance test.
++ 2. `codey --version` and `codey models` satisfy T3 Code's parsers — asserted in
++    Go, then observed on the provider card.
++ 3. A thread in T3 Code: text streams, tool rows appear and complete, an
++    approval prompt appears and is answerable, the stop button ends the turn,
++    and the thread survives a second prompt in the same session.
++ 4. `~/.t3/userdata/logs/provider/events.<threadId>.log` contains no decode
++    errors and no `warning` rows we did not intend.
++ ## Out of scope
++ - Any change to T3 Code's source. The fork — a `codey` driver in
++   `BUILT_IN_DRIVERS` — is discussed at the end of the design doc and stays a
++   later decision. Nothing in this plan is wasted if we take it: the same ACP
++   server is what such a driver would talk to.
++ - The Codex app-server path. Specified in the design doc's appendix as the
++   fallback, not built.
++ - MCP. T3 Code offers us an MCP server on `session/new`; we ignore it.

+306−0docs/superpowers/specs/2026-09-19-t3code-provider-design.mdaddedView File

++ # Codey as a T3 Code provider — design
++ **Question:** can T3 Code drive Codey without patching T3 Code? If so, through
++ which of its provider slots, and what exactly does Codey have to say?
++ **Answer:** yes. Speak ACP over stdio, put the binary path in the Grok
++ provider's settings, and T3 Code drives Codey with no source change on their
++ side. Everything below is evidence for that choice and the contract it
++ commits us to.
++ Researched against `github.com/pingdotgg/t3code` at commit `9accc567`
++ (2026-09-19), which is the same generation as the 0.0.43 nightly installed on
++ this machine. Every file reference is into that tree.
++ ## How T3 Code's provider layer is built
++ T3 Code is a control plane, not an agent: it spawns somebody else's CLI and
++ renders what comes back. There are six drivers — Codex, Claude, Cursor, Grok,
++ OpenCode, Antigravity (`apps/server/src/provider/builtInDrivers.ts:50-56`).
++ Three facts decide everything:
++ **Drivers are compiled in.** `BUILT_IN_DRIVERS` is "the static set of
++ `ProviderDriver`s this build ships with"
++ (`apps/server/src/provider/builtInDrivers.ts:1-22`). There is no plugin
++ mechanism, no config-declared driver, no external process registry. Adding a
++ seventh driver means editing their repo and rebuilding the Electron app.
++ **But driver kinds are an open slug, on purpose.** `ProviderDriverKind` is "an
++ **open** branded slug, not a closed literal union … The server hosts forks,
++ ships in PRs that add drivers, and users frequently roll between branches and
++ forks" (`packages/contracts/src/providerInstance.ts:16-33`). Settings naming a
++ driver this build does not know round-trip intact and surface as an
++ "unavailable" card. So a fork that adds a `codey` driver is a supported shape —
++ it is just not a shape that survives the auto-updater.
++ **Each instance carries user-editable config, and there can be several per
++ driver.** `ProviderInstanceConfig` is
++ `{driver, displayName?, accentColor?, environment?, enabled?, config?}`
++ (`packages/contracts/src/providerInstance.ts:124-131`), keyed by a user-chosen
++ instance id, and every built-in driver sets `supportsMultipleInstances: true`
++ (e.g. `Drivers/GrokDriver.ts:60-61`). The per-driver `config` payload always
++ contains `binaryPath`, and usually `launchArgs` and `customModels`
++ (`packages/contracts/src/settings.ts:562-735`). This is the seam. On this
++ machine it is already visible in `~/.t3/userdata/settings.json`:
++ ```json
++ "providerInstances": {
++   "codex": { "driver": "codex", "enabled": false,
++     "config": { "binaryPath": "codex", "homePath": "", "shadowHomePath": "",
++                 "launchArgs": "", "customModels": [] } }
++ }
++ ```
++ `binaryPath` is used verbatim — nothing anywhere keys off the file's *name*.
++ Per-instance environment variables are editable in the same UI
++ (`docs/user/install.md:130-133`).
++ So the plan the user proposed is the right one: don't add a driver, occupy one.
++ ## The four candidate surfaces
++ ### Claude — rejected
++ T3 Code does not spawn `claude` itself. It hands the path to Anthropic's own
++ SDK: `"@anthropic-ai/claude-agent-sdk": "^0.3.276"` (`apps/server/package.json:26`),
++ `pathToClaudeCodeExecutable: claudeBinaryPath` (`Layers/ClaudeAdapter.ts:4916`).
++ The contract is therefore the *SDK's* CLI contract, which lives in a node
++ package T3 Code upgrades on its own schedule, and which we would have to
++ re-derive by experiment rather than read.
++ Worse, the model picker is a baked-in manifest with version gates:
++ `provider/model-manifest.json` gives `claude-opus-5` `"minVersion": "2.1.219"`,
++ and `ClaudeModelCatalog.ts:148-158` refuses a model whose `minVersion` exceeds
++ what `claude --version` printed. Our own model names would never appear;
++ we would be advertising Anthropic slugs and lying about a Claude Code version.
++ ### Codex — possible, expensive
++ Spawned as `<binaryPath> app-server` plus the user's `launchArgs`
++ (`Layers/codexLaunchArgs.ts:12-15`), newline-delimited JSON-RPC over stdio,
++ no `jsonrpc` field, notifications must carry no `id` key at all
++ (`packages/effect-codex-app-server/src/protocol.ts:82-95, 459-474`).
++ It has one genuinely attractive property the others lack: **models come from
++ the binary at runtime**. The probe pages through `model/list` and shows what it
++ is told (`Layers/CodexProvider.ts:325-341`), so Codey's own model names would
++ appear in T3 Code's picker. There is no version gate; the version is scraped
++ out of the `initialize` result's `userAgent` with `/\/([^\s]+)/`
++ (`Layers/CodexProvider.ts:422-424`).
++ Against it: the protocol is enormous and strictly decoded. 99 client request
++ methods, 70 server notifications (`_generated/meta.gen.ts:6-191`), generated
++ from a pinned upstream ref and schema-checked per method, so a missing required
++ field is a hard decode error rather than a shrug. The minimum is bigger than it
++ looks — `thread/start` must return a fully populated `thread` object
++ (`cliVersion`, `sessionId`, `preview`, `ephemeral`, `createdAt`, `updatedAt`,
++ `source`, `status`, `turns`) of which T3 Code reads exactly three fields
++ (`_generated/schema.gen.ts:31819-31855`, consumed at
++ `Layers/CodexSessionRuntime.ts:2447-2453`). And `account/read` must answer
++ `requiresOpenaiAuth: false` with an account object or the probe stops
++ (`Layers/CodexProvider.ts:426-434`).
++ It is implementable — the full method-by-method spec is in the appendix — but
++ it is a moving target owned by OpenAI and mirrored by T3 Code.
++ ### OpenCode — rejected
++ T3-managed OpenCode runs one HTTP server per thread with directory-scoped MCP
++ registration and per-directory persistent approval grants
++ (`docs/internals/providers.md:13-24`). We would be impersonating a server, not
++ a CLI, and inheriting its grant semantics.
++ ### Grok — chosen
++ Grok is an ACP agent. T3 Code spawns:
++ ```ts
++ { command: grokSettings?.binaryPath || "grok",
++   args: [...grokAcpSpawnArgs(runtimeMode)],
++   cwd,
++   env: { ...environment, GROK_OAUTH2_REFERRER: "t3code" } }
++ ```
++ (`acp/GrokAcpSupport.ts:48-63`), where `grokAcpSpawnArgs` is
++ `["agent", "stdio"]` by default and prefixes `["--permission-mode", "default"
++ | "acceptEdits" | "auto"]` or appends `--always-approve` for the four runtime
++ modes (`acp/GrokAcpSupport.ts:33-46`).
++ That is the whole launch contract. The ACP side is four methods and one
++ notification, and ACP is an open, documented protocol rather than a vendor
++ mirror. Crucially, the initialize *result* has exactly one required field:
++ `protocolVersion`; `agentCapabilities`, `authMethods`, `agentInfo` and
++ `promptCapabilities` are all `optionalKey`
++ (`packages/effect-acp/src/_generated/schema.gen.ts:6574-6605`). Unknown
++ `sessionUpdate` discriminators hit `default: break`
++ (`acp/AcpRuntimeModel.ts:882-883`), so we can grow into the protocol instead of
++ having to land on it.
++ The two shell probes that gate the provider card are regex-loose:
++ - `grok --version` must exit 0 and print something matching
++   `/\bv?(\d+\.\d+\.\d+)\b/` (`Layers/GrokProvider.ts:394`, parser at
++   `providerSnapshot.ts:114-119`).
++ - `grok models` must exit 0. Login state is `/you are logged in/i` versus
++   `/not authenticated|not logged in/i`; models are bullet lines
++   `* slug (default)` or `- slug` (`Layers/GrokProvider.ts:258-286`).
++ Compare Antigravity, which fingerprints the agent properly —
++ `agentInfo.name === "antigravity-acp"` plus four required capabilities
++ (`AntigravityInstallation.ts:493-499`). Nothing of the sort exists on the Grok
++ path: no filename check, no minimum version, no config file under `~/.grok`.
++ Cursor is nearly as cheap but adds three obligations: an `about --format json`
++ probe that must report a `YYYY.MM.DD` `cliVersion` and a non-null `userEmail`
++ or the card goes to `status: "error"` (`Layers/CursorProvider.ts:1086-1097,
++ 932-952`); an unconditional `session/set_config_option` on model selection
++ (`acp/CursorAcpSupport.ts:113`); and hardcoded permission option ids
++ `"allow-always"` / `"allow-once"` / `"reject-once"` that the agent must accept
++ verbatim (`acp/AcpAdapterSupport.ts:46-55`). Grok, by contrast, echoes back an
++ option id chosen from the ones *we* advertised
++ (`Layers/GrokAdapter.ts:1219-1237`).
++ ### Scoring
++ | | Claude | Codex | OpenCode | Cursor | **Grok** |
++ |---|---|---|---|---|---|
++ | Transport we must implement | SDK-private | JSON-RPC, 99+70 methods | HTTP+SSE server | ACP | **ACP** |
++ | Minimum methods | n/a | 4 req + 4 notif, strict schemas | many | 4 + probe | **4 + 1 notif** |
++ | Startup gates | version-gated model manifest | `account/read` auth shape | server lifecycle | `about` JSON + email | **two regexes** |
++ | Our own model names show | no | yes | partly | via extension | via `models` output |
++ | Protocol owner | Anthropic SDK | OpenAI, mirrored | SST | Cursor | **open standard** |
++ | Fingerprints the agent | — | — | — | — | **no** |
++ ## The contract we are signing up to
++ ### Command line
++ | invocation | must do |
++ |---|---|
++ | `codey --version` | exit 0, print a line containing `x.y.z` |
++ | `codey models` | exit 0, print `You are logged in as …` and one `* slug (default)` / `- slug` line per model |
++ | `codey agent stdio` | speak ACP over stdin/stdout until EOF |
++ | `codey agent --always-approve stdio` | same, with every tool auto-approved |
++ | `codey --permission-mode default\|acceptEdits\|auto agent stdio` | same, with that approval policy |
++ `codey login`, `codey update` and any other subcommand may be absent; T3 Code
++ only ever mentions them in error text. Note the flag placement: T3 Code puts
++ `--permission-mode` *before* the `agent` subcommand and `--always-approve`
++ *between* `agent` and `stdio`, so the argument parser has to be positional-
++ agnostic rather than a strict `agent` subcommand with its own flag set.
++ ### ACP, client → us
++ 1. `initialize` — `{protocolVersion: 1, clientCapabilities: {fs: {readTextFile: false, writeTextFile: false}, terminal: false}, clientInfo: {name: "t3-code", version}}` (`acp/AcpSessionRuntime.ts:696-705, 566-578`). Minimum valid reply: `{"protocolVersion": 1}`. We will also send `agentInfo` and `agentCapabilities`.
++ 2. `authenticate` — `{methodId: "cached_token"}`, or `"xai.api_key"` if `XAI_API_KEY` is set in the instance env (`acp/GrokAcpSupport.ts:65-69`). Sent unconditionally and *not* caught: an error here aborts session start (`acp/AcpSessionRuntime.ts:710-718`). Reply `{}` regardless of the id.
++ 3. `session/new` — `{cwd, mcpServers: [], additionalDirectories?}`. Only `sessionId` is required back (`acp/AcpSessionRuntime.ts:836-860`).
++ 4. `session/prompt` — `{sessionId, prompt: ContentBlock[]}`. Only `stopReason` is read from the result (`Layers/CursorAdapter.ts:1112`).
++ 5. `session/cancel` — notification; T3 Code synthesises `{stopReason: "cancelled"}` locally (`acp/AcpSessionRuntime.ts:1027-1029`).
++ `session/load` / resume is only attempted when
++ `agentCapabilities.sessionCapabilities.resume` is true
++ (`acp/AcpSessionRuntime.ts:726`), so omitting it is a supported state, not a
++ failure.
++ ### ACP, us → client
++ `session/update` notifications, switched on `sessionUpdate`
++ (`acp/AcpRuntimeModel.ts:795-884`):
++ | variant | fields read | we need it |
++ |---|---|---|
++ | `agent_message_chunk` | `content.text` | **yes** — the visible answer |
++ | `agent_thought_chunk` | `content.text` | phase 2 (we have no reasoning events yet) |
++ | `tool_call` | `toolCallId`, `title`, `kind`, `status`, `content`, `rawInput` | **yes** — otherwise tools are invisible |
++ | `tool_call_update` | same, merged by `toolCallId`; terminal on `completed`/`failed` | **yes** |
++ | `plan` | `entries[].content`, `.status` | no |
++ | `available_commands_update` | `availableCommands` | later, for slash commands |
++ | `current_mode_update`, `config_option_update` | mode / config ids | no |
++ And `session/request_permission` — we send `{sessionId, toolCall: {kind, title, rawInput, locations}, options: [{optionId, name, kind}]}`; T3 Code replies `{outcome: {outcome: "selected", optionId}}` or `{outcome: {outcome: "cancelled"}}` (`Layers/CursorAdapter.ts:746-754`). On the Grok path the id comes from our own list (`Layers/GrokAdapter.ts:1219-1237`), so we choose the vocabulary — but we should still accept `allow-always`/`allow-once`/`reject-once` verbatim so that pointing the same binary at a Cursor instance also works.
++ ### What T3 Code will show
++ The card, icon and colour come from `GROK_PRESENTATION`, so out of the box it
++ says Grok. The instance's `displayName` and `accentColor` are user-editable
++ (`packages/contracts/src/providerInstance.ts:124-131`) and are stamped onto
++ every event by `withInstanceIdentity`, so renaming the instance to "Codey" gets
++ most of the way. The xAI glyph stays. That is the price of not forking.
++ Model slugs pass through `resolveGrokAcpBaseModelId` and get a display name
++ from `displayNameFromGrokModelSlug`, which title-cases on `-`/`_`
++ (`Layers/GrokProvider.ts:272-293`). `codey-opus-5` renders as "Codey Opus 5".
++ ## What this costs on our side
++ Codey today is a TUI and a `-p` one-shot. It already has the two seams an
++ adapter needs — `Agent.Observe func(Event)` and `Agent.Approve Approver`
++ (`internal/agent/loop.go:205-211`) — plus a tool registry, a session store and
++ an approval policy that can remember decisions. The new work is a third front
++ end: `internal/acp` (wire) + `internal/serve` (bridge), and an `agent stdio`
++ verb in `cmd/codey`. Nothing in `internal/agent` needs to change for phase 1.
++ Three gaps show up when mapping our `Event` onto ACP:
++ - **`Event` has no tool call id.** `EventToolStart`/`EventToolResult` carry
++   `Tool string` and nothing that pairs them
++   (`internal/agent/loop.go:180-191`). ACP's `tool_call` /`tool_call_update`
++   are keyed by `toolCallId`. Sequential dispatch means we can pair by order for
++   now, but the honest fix is to add an id to the event.
++ - **No reasoning events.** The loop never surfaces thinking blocks to
++   observers, so `agent_thought_chunk` has nothing to carry.
++ - **No diff events.** Our `edit`/`write` tools return text; T3 Code's diff view
++   wants `tool_call` content of kind `diff` with old/new text.
++ None of these block a working turn; all three are what separate "it works"
++ from "it looks like a first-class provider".
++ ## Risks
++ - **Their churn.** T3 Code ships nightly and the Grok path is explicitly young:
++   the driver is disabled by default because "the binding is not yet stable
++   enough to probe on every install" (`packages/contracts/src/settings.ts:713-716`).
++   Mitigation: the contract surface we depend on is five methods, and a conformance
++   test that replays T3 Code's exact handshake catches a break in seconds.
++ - **Occupying a slot means losing it.** A user who wants both real Grok and
++   Codey needs two instances of the `grok` driver. That works
++   (`supportsMultipleInstances: true`) but it is a confusing settings page.
++ - **It says Grok.** See above.
++ - **Upstream ACP version.** T3 Code sends `protocolVersion: 1`. If they move to
++   2 we have to follow; the handshake is where we would find out.
++ ## The fork option, for the record
++ Because driver kinds are open and forks are anticipated, a `codey` driver is
++ about one file (`Drivers/CodeyDriver.ts`), one line in `BUILT_IN_DRIVERS`, and
++ a settings schema — additive, no rewriting, and it would get us our own name,
++ icon and config fields. The cost is that it only exists in a build we compile
++ and ship ourselves, and it has to be rebased onto a repo that moves daily.
++ The right sequencing is impersonation first: the ACP server we build for the
++ Grok slot is exactly the server a `codey` driver would talk to, so nothing is
++ thrown away if we later decide the fork is worth maintaining.
++ ## Appendix: the Codex app-server contract
++ Kept because it is the fallback if the Grok path is withdrawn, and because it
++ is the only slot that lets our model names reach the picker honestly.
++ Launch: `<binaryPath> app-server [launchArgs]`, `CODEX_HOME` set in the child
++ env, tilde-expanded (`Layers/CodexProvider.ts:368-378`).
++ Must answer:
++ - `initialize` → `{codexHome, platformFamily, platformOs, userAgent}`, all four required; version is scraped from `userAgent` after the first `/`.
++ - `thread/start` → `{approvalPolicy, approvalsReviewer, cwd, model, modelProvider, sandbox, thread{...}}` — the strictest decode in the flow.
++ - `turn/start` → `{turn: {id, items: [], status: "inProgress"}}`.
++ - `turn/interrupt` → `{}`.
++ - probe path: `account/read` → `{requiresOpenaiAuth: false, account: {...}}`; `model/list` → `{data: [...]}`; `skills/list` (a failure here fails the whole probe, unlike `account/rateLimits/read`, which degrades).
++ Must emit: `turn/started`, `item/agentMessage/delta`, `item/completed`,
++ `turn/completed` — the last is what ends the turn
++ (`Layers/CodexAdapter.ts:1613`).
++ Traps: notifications must have no `id` key at all; inbound queues are
++ `sliding(32)` so bursts drop oldest; a server→client request left unanswered
++ blocks T3 Code's entire stdin loop (`Layers/CodexSessionRuntime.ts:2565-2571`);
++ there is no shutdown RPC — exit on stdin EOF.