@doguyilmaz/konvoy 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dogu Yilmaz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,300 @@
+# konvoy
+
+One session across Claude Code, Codex, Kiro CLI and opencode. konvoy binds a foreign
+session per CLI, keeps them on one shared brief, and lets you move between them without
+re-explaining anything.
+
+## Install
+
+macOS, via the tap (a signed binary; no Bun needed):
+
+```bash
+brew install --cask doguyilmaz/tap/konvoy
+```
+
+Linux, from the release tarball (no Bun needed):
+
+```bash
+curl -fsSL https://github.com/doguyilmaz/konvoy/releases/latest/download/konvoy_linux_amd64.tar.gz | tar xz konvoy
+install -m 755 konvoy ~/.local/bin/konvoy
+```
+
+With Bun 1.4+ already installed, from npm:
+
+```bash
+bun add -g @doguyilmaz/konvoy        # or run once: bunx @doguyilmaz/konvoy help
+```
+
+From a checkout:
+
+```bash
+bun install
+bun run build          # produces ./dist/konvoy
+```
+
+Updating follows the channel: `brew upgrade --cask konvoy`, `bun add -g @doguyilmaz/konvoy@latest`, or `bun run build`.
+
+The brew and tarball binaries carry the Bun runtime, so each is about 60 MB on disk and 25–35 MB
+to download; the npm package is a few kilobytes of source and runs on the Bun you already have.
+
+## Use
+
+```bash
+konvoy new "refactor the auth layer"
+konvoy send codex "start with the token refresh path"
+konvoy ls
+konvoy resume                  # make a session current again and show its roster
+konvoy roster
+konvoy usage --all --chart     # GATE reads as a dash until a `gate` command is configured
+konvoy status
+konvoy attach codex    # drops you into the real Codex TUI, same session
+konvoy attach kiro --id cli_8a1…   # adopt a session you started in kiro's own TUI; the next turn resumes it
+konvoy doctor
+konvoy update --all    # every agent CLI; konvoy itself follows its install channel (see Install)
+konvoy rm stale-slug --yes
+konvoy version
+konvoy dashboard --port 4000  # local page with the same numbers as `usage --chart`
+```
+
+## Sample output
+
+Captured by running konvoy against a scratch database, not copied from a real project.
+
+`konvoy usage --all --chart`:
+
+```text
+all sessions
+AGENT     TURNS  IN     OUT   SPEND     GATE
+claude    27     25560  5040  $6.18     -
+codex     17     14800  2850  $1.39     -
+kiro      6      4920   930   0.190 cr  -
+opencode  3      2400   450   -         -
+
+spend is in each agent's own unit; a dash means the CLI reported none
+
+turns per day
+Sun ·▪█
+Mon ·▩·
+Tue ·▩·
+Wed ·▫·
+Thu ·▩·
+Fri ▪█·
+Sat ▩█·
+
+share of turns
+claude    █████████░░░░░░░░░  51%
+codex     ██████░░░░░░░░░░░░  32%
+kiro      ██░░░░░░░░░░░░░░░░  11%
+opencode  █░░░░░░░░░░░░░░░░░  6%
+
+turns per day by agent
+claude    ▄▅▂▇▄▁▅█▇▅
+codex     ▂▂▄▁▅▄▂▄▅▄
+kiro      ▁▂▁▂▁▁▂▁▄▂
+opencode  ▁▁▂▁▁▁▁▂▁▂
+```
+
+A failover notice, when codex hits its weekly limit mid-chain:
+
+```text
+konvoy: codex is blocked (rate) — "You've hit your weekly limit · resets 7am" — claude is taking over
+```
+
+A handoff, with `delegation.enabled` on and `roles.reviewer` set to `claude`. codex ends its
+turn with a `<<<konvoy ... >>>` block naming the `reviewer` role:
+
+```text
+Fixed: the refresh call was firing on a fixed 55-minute timer, so a laptop asleep past
+that mark woke up to a 401. Switched it to refresh on 401 with a single in-flight retry.
+
+<<<konvoy
+to: reviewer
+task: check the retry does not loop when the refresh itself 401s
+open:
+- whether a second consecutive 401 should sign the user out instead of retrying again
+decisions:
+- refresh on 401 rather than on a timer, it tracks the actual failure instead of a guess
+>>>
+```
+
+konvoy resolves `reviewer` to claude, runs it, and prints:
+
+```text
+konvoy: codex handed off to claude — "check the retry does not loop when the refresh itself 401s"
+```
+
+claude's turn runs with codex's task as its prompt, preceded by this prelude:
+
+```text
+goal: fix the token refresh bug
+
+codex handed off to reviewer:
+task: check the retry does not loop when the refresh itself 401s
+open:
+- whether a second consecutive 401 should sign the user out instead of retrying again
+decisions:
+- refresh on 401 rather than on a timer, it tracks the actual failure instead of a guess
+```
+
+## How it works
+
+One konvoy session holds a binding per agent, and each binding holds that agent's own
+foreign session id — konvoy's id and the agent's id are never the same thing. Only claude
+accepts a caller-chosen session id up front; the other three assign their own and hand it
+back after the first turn, which konvoy stores in that agent's binding and resumes on every
+turn after.
+
+```mermaid
+flowchart LR
+  session["konvoy session<br/>(one slug)"]
+  session --> bClaude["binding: claude"]
+  session --> bCodex["binding: codex"]
+  session --> bKiro["binding: kiro"]
+  session --> bOpencode["binding: opencode"]
+
+  bClaude -->|"via --session-id or --resume<br/>← session_id"| claudeCli(["claude session"])
+  bCodex -->|"resume &lt;id&gt; subcommand<br/>← thread_id"| codexCli(["codex thread"])
+  bKiro -->|"via --resume-id<br/>← sessionId"| kiroCli(["kiro-cli session"])
+  bOpencode -->|"via --session<br/>← sessionID"| opencodeCli(["opencode session"])
+```
+
+## Configure
+
+Global `~/.config/konvoy/config.jsonc`, per project `.konvoy/config.jsonc`. The project
+file wins. `konvoy config get` shows each agent's resolved settings and whether a value came
+from that agent, from `defaults`, or from konvoy's own built-in.
+
+```jsonc
+{
+  "defaults": { "effort": "high", "permission": "edit" },
+  "agents": {
+    "claude": { "model": "opus", "effort": "max" },
+    "codex":  { "model": "gpt-6-astra" }
+  },
+  "roles": { "lead": "claude", "reviewer": "kiro" }
+}
+```
+
+`effort` is one scale — `low | medium | high | max` — mapped onto each CLI's own dial and
+clamped to what the target model actually supports.
+
+If a CLI is not on your `PATH`, point konvoy at it directly and every command — `doctor`,
+`status`, `send`, `attach`, `update` — uses that path:
+
+```jsonc
+{ "agents": { "opencode": { "bin": "~/.opencode/bin/opencode" } } }
+```
+
+`konvoy config set <key> <value> [--global]` rewrites the layer it touches as plain JSON, so
+any comments in that file are lost — `--global` targets the global file instead of the
+project one. Hand-edit the file instead when you want to keep them.
+
+Name a `failover` chain and konvoy follows it when an agent can't work, instead of asking:
+
+```jsonc
+{ "failover": { "chain": ["codex", "claude", "kiro"], "upstreamRetries": 3 } }
+```
+
+A rate limit or an auth failure moves to the next agent in the chain at once. An agent that failed on auth shows as `auth_required` in the roster until one of its turns succeeds. An upstream
+error (a reachable-but-refusing API) retries the same agent with backoff up to
+`upstreamRetries` times before moving on. A crash, a timeout, or an interrupted turn never
+moves the chain — the fault is in the work, and the next agent would just fail the same way.
+There is no failback: once konvoy moves, it stays moved. An empty chain (the default) turns
+the feature off.
+
+```mermaid
+flowchart TD
+  run["run current agent"] --> check{"error kind"}
+  check -->|"rate or auth"| move["move to next chain agent<br/>(no retry)"]
+  check -->|upstream| retry{"retries < upstreamRetries?"}
+  retry -->|"yes, with backoff"| run
+  retry -->|no| move
+  check -->|"none, crash, timeout,<br/>interrupted, or other"| stay["return result<br/>chain stops here"]
+  move --> run
+```
+
+Set `style: "brief"` to have an agent lead with the action, number multi-step work, and skip
+preamble and pleasantries — it shapes the answer you read, not what agents send each other:
+
+```jsonc
+{ "defaults": { "style": "brief" }, "agents": { "kiro": { "style": null } } }
+```
+
+Set `delegation.enabled` to have every turn told how to hand work to another agent — a
+`<<<konvoy ... >>>` block naming `to:` and `task:`, with optional `open:` and `decisions:`
+lists — instead of the weaker summary konvoy derives on its own. The agent decides when a
+turn is actually handing off; a turn that isn't emits no block at all, so this costs nothing
+on the turns that don't need it. Off by default: a single-agent session has no handoff to
+describe.
+
+```jsonc
+{ "delegation": { "enabled": true } }
+```
+
+Name a `gate` command — your test suite, a linter, whatever exits non-zero on bad work — and
+konvoy runs it after each turn that produced something, recording a pass or fail against that
+turn. A command that can't even be spawned records nothing, and a failed turn is never gated:
+
+```jsonc
+{ "gate": { "command": "bun test" } }
+```
+
+`harness` decides how much of a CLI's own setup a turn loads. `minimal`, the default, strips
+what konvoy already supplies — claude runs with no MCP servers, slash commands or settings
+files, codex with `--ignore-user-config` — and measured 2.6× less context per turn than
+`inherit`, which runs the CLI exactly as you would by hand, hooks and skills included. kiro and
+opencode run with their own configuration either way. Privileged: the global config only.
+
+```jsonc
+{ "defaults": { "harness": "inherit" } }
+```
+
+`gate` is privileged like `bin`, `permission` and `harness` — only the global config may set
+it, since a gate runs on every turn with no per-turn opt-in, unlike an agent binary the user
+chose to run. That also means one gate command serves every project; there's no per-project
+override yet.
+
+## Requirements
+
+Whichever of `claude`, `codex`, `kiro-cli`, `opencode` you want in the convoy. Bun 1.4+ only for the npm install or a checkout; the brew and tarball binaries carry their own runtime.
+Each authenticates itself; konvoy never handles credentials.
+
+## Releasing
+
+Bump `version` in `package.json`, then `git tag vX.Y.Z && git push --tags`. The release
+workflow builds four binaries (macOS arm64 and x64, signed and notarized; Linux amd64 and
+arm64), publishes them with checksums, updates `Casks/konvoy.rb` in `doguyilmaz/homebrew-tap`,
+and publishes to npm. It reads these repository secrets, each declared in `.env.schema`:
+`HOMEBREW_TAP_GITHUB_TOKEN`, `MACOS_SIGN_P12`, `MACOS_SIGN_PASSWORD`,
+`MACOS_NOTARY_ISSUER_ID`, `MACOS_NOTARY_KEY_ID`, `MACOS_NOTARY_KEY`. Signing and the tap push are
+skipped when their secret is absent; npm is published through trusted publishing (OIDC), configured
+once on npmjs.com, so there is no npm token. To publish by hand, put the
+values in `.env.local` (gitignored) and run each step through `bunx varlock run -- <command>`,
+which injects and redacts them instead of having them pasted into a terminal.
+
+## Development
+
+```bash
+bun test
+bun run typecheck
+bun run mutate         # mutation coverage of src/
+bun run verify:claims  # checks konvoy's own claims about the four CLIs against what --help says here
+bun run smoke          # two real turns per installed, authenticated agent, the second resumed — spends quota
+```
+
+`verify:claims` is the standing form of a manual check: it re-reads each CLI's own `--help`
+and confirms what this README and the adapters assume — that every flag an adapter puts on a
+command line still exists, that each agent's update and auth-status subcommands exist, that
+only claude accepts a caller-chosen session id, and that opencode's `--session` continues a
+session rather than creating one. The flag list is built from the adapters' real argv, so a flag
+added to an adapter is checked without touching the script. It never sends a prompt or spends
+quota, and it isn't part of `bun test` since it needs the CLIs installed to mean anything.
+
+`smoke` closes the gap `verify:claims` and the frozen fixtures in `tests/fixtures/streams/`
+both leave open: it runs two turns per installed, logged-in agent through konvoy's real
+`send()`. The first stores a nonce and must return a foreign session id, some text and no
+error; the second is resumed through the binding konvoy captured and must give the nonce back —
+the one cheap proof that a bound session carries its context, which every unit test of it
+checks with fakes. It skips an agent that isn't installed or isn't logged in, and flags
+when an installed CLI's version has drifted from the one a fixture was captured against — the
+moment to re-capture. It spends real quota, so it is opt-in and never part of `bun test`.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@doguyilmaz/konvoy",
+  "version": "0.1.1",
+  "description": "One session across Claude Code, Codex, Kiro CLI and opencode — bind, hand off, fail over",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/doguyilmaz/konvoy.git"
+  },
+  "homepage": "https://github.com/doguyilmaz/konvoy#readme",
+  "bugs": "https://github.com/doguyilmaz/konvoy/issues",
+  "keywords": [
+    "cli",
+    "coding-agents",
+    "claude-code",
+    "codex",
+    "kiro",
+    "opencode",
+    "bun"
+  ],
+  "bin": {
+    "konvoy": "./src/cli.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "bun test",
+    "build": "bun build ./src/cli.ts --compile --format=esm --minify --sourcemap --bytecode --no-compile-autoload-dotenv --no-compile-autoload-bunfig --outfile dist/konvoy",
+    "typecheck": "bunx tsc --noEmit",
+    "mutate": "bun run tests/mutations/run.ts",
+    "verify:claims": "bun run scripts/verify-claims.ts",
+    "smoke": "bun run scripts/smoke.ts"
+  },
+  "dependencies": {
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.6.0",
+    "varlock": "^1.20.0"
+  }
+}

package/src/adapters/claude.ts

@@ -0,0 +1,83 @@
+import type { Binding, KonvoyEvent, Permission, SpawnPlan, TurnContext } from '../types'
+import { classifyError, safeJson, stripControlChars, withPrelude, type Adapter } from './types'
+
+const PERMISSION: Record<Permission, string> = {
+  safe: 'manual',
+  edit: 'acceptEdits',
+  yolo: 'bypassPermissions',
+}
+
+export const claudeAdapter: Adapter = {
+  id: 'claude',
+  bin: 'claude',
+  supportsPresetSessionId: true,
+
+  turn(ctx: TurnContext): SpawnPlan {
+    const cmd = [ctx.bin ?? 'claude', '-p', '--output-format', 'stream-json', '--verbose']
+    if (ctx.binding?.foreignId) cmd.push('--resume', ctx.binding.foreignId)
+    else cmd.push('--session-id', ctx.sessionId)
+    if (ctx.model) cmd.push('--model', ctx.model)
+    cmd.push('--effort', ctx.effort)
+    cmd.push('--permission-mode', PERMISSION[ctx.permission])
+    if ((ctx.harness ?? 'minimal') === 'minimal') {
+      cmd.push('--strict-mcp-config', '--mcp-config', '{"mcpServers":{}}', '--disable-slash-commands', '--setting-sources', '')
+    }
+    cmd.push('--', withPrelude(ctx))
+    return { cmd, cwd: ctx.cwd }
+  },
+
+  parse(line: string): KonvoyEvent[] {
+    const o = safeJson(line)
+    if (!o) return []
+
+    if (o.subtype === 'init' && typeof o.session_id === 'string') {
+      return [{ t: 'session', foreignId: stripControlChars(o.session_id) }]
+    }
+
+    if (o.type === 'assistant') {
+      const message = o.message as { content?: unknown[] } | undefined
+      const blocks = Array.isArray(message?.content) ? message.content : []
+      const events: KonvoyEvent[] = []
+      for (const raw of blocks) {
+        if (typeof raw !== 'object' || raw === null) continue
+        const block = raw as { type?: string; text?: string; thinking?: string; name?: string }
+        if (block.type === 'text' && block.text) events.push({ t: 'text', text: block.text })
+        if (block.type === 'thinking' && block.thinking) events.push({ t: 'thinking', text: block.thinking })
+        if (block.type === 'tool_use') events.push({ t: 'tool', name: block.name ?? 'tool', status: 'start' })
+      }
+      return events
+    }
+
+    if (o.type === 'result') {
+      const text = typeof o.result === 'string' ? o.result : ''
+      // a result can be is_error with no text at all — claude puts the reason on stderr then, and
+      // an invented placeholder here would stand in the way of turn.ts reading it
+      if (o.is_error) return [{ t: 'error', message: text, kind: classifyError(text) }]
+      const usage = o.usage as
+        | { input_tokens?: number; output_tokens?: number; cache_creation_input_tokens?: number; cache_read_input_tokens?: number }
+        | undefined
+      // claude splits input across three fields and input_tokens holds only the uncached
+      // remainder, so it reads near zero on a cached turn. codex's input_tokens already
+      // contains its cached count; summing here is what puts both agents in one unit.
+      const input = usage
+        ? (usage.input_tokens ?? 0) + (usage.cache_creation_input_tokens ?? 0) + (usage.cache_read_input_tokens ?? 0)
+        : undefined
+      return [
+        {
+          t: 'usage',
+          inputTokens: input,
+          outputTokens: usage?.output_tokens,
+          costUsd: typeof o.total_cost_usd === 'number' ? o.total_cost_usd : undefined,
+        },
+        { t: 'done', final: text },
+      ]
+    }
+
+    return []
+  },
+
+  attach(binding: Binding): SpawnPlan {
+    if (!binding.foreignId) return { cmd: ['claude'] }
+    return { cmd: ['claude', '--resume', binding.foreignId] }
+  },
+}

package/src/adapters/codex.ts

@@ -0,0 +1,67 @@
+import type { Binding, KonvoyEvent, Permission, SpawnPlan, TurnContext } from '../types'
+import { classifyError, safeJson, stripControlChars, withPrelude, type Adapter } from './types'
+
+const SANDBOX: Record<Permission, string[]> = {
+  safe: ['-s', 'read-only'],
+  edit: ['-s', 'workspace-write'],
+  yolo: ['--dangerously-bypass-approvals-and-sandbox'],
+}
+
+export const codexAdapter: Adapter = {
+  id: 'codex',
+  bin: 'codex',
+  supportsPresetSessionId: false,
+
+  turn(ctx: TurnContext): SpawnPlan {
+    const cmd = [ctx.bin ?? 'codex', 'exec', '--json', '--skip-git-repo-check']
+    if ((ctx.harness ?? 'minimal') === 'minimal') cmd.push('--ignore-user-config')
+    if (ctx.model) cmd.push('-m', ctx.model)
+    cmd.push('-c', `model_reasoning_effort=${ctx.effort}`)
+    cmd.push(...SANDBOX[ctx.permission])
+    // `resume` is a subcommand of `exec` with its own small flag set; the flags above belong to
+    // `exec` and are only parsed when they come first
+    if (ctx.binding?.foreignId) cmd.push('resume', ctx.binding.foreignId)
+    cmd.push('--', withPrelude(ctx))
+    return { cmd, cwd: ctx.cwd }
+  },
+
+  parse(line: string): KonvoyEvent[] {
+    const o = safeJson(line)
+    if (!o) return []
+
+    if (o.type === 'thread.started' && typeof o.thread_id === 'string') {
+      return [{ t: 'session', foreignId: stripControlChars(o.thread_id) }]
+    }
+
+    if (o.type === 'item.completed') {
+      const item = o.item as { type?: string; text?: string; message?: string } | undefined
+      if (!item?.type) return []
+      if (item.type === 'agent_message') return item.text ? [{ t: 'text', text: item.text }] : []
+      if (item.type === 'reasoning') return item.text ? [{ t: 'thinking', text: item.text }] : []
+      if (item.type === 'error') {
+        const message = item.message ?? ''
+        return [{ t: 'error', message, kind: classifyError(message), source: 'item' }]
+      }
+      return [{ t: 'tool', name: item.type, status: 'ok' }]
+    }
+
+    if (o.type === 'turn.completed') {
+      const usage = o.usage as { input_tokens?: number; output_tokens?: number } | undefined
+      if (!usage) return []
+      return [{ t: 'usage', inputTokens: usage.input_tokens, outputTokens: usage.output_tokens }]
+    }
+
+    if (o.type === 'turn.failed') {
+      const error = o.error as { message?: string } | undefined
+      const message = error?.message ?? ''
+      return [{ t: 'error', message, kind: classifyError(message), source: 'turn' }]
+    }
+
+    return []
+  },
+
+  attach(binding: Binding): SpawnPlan {
+    if (!binding.foreignId) return { cmd: ['codex'] }
+    return { cmd: ['codex', 'resume', binding.foreignId] }
+  },
+}

package/src/adapters/effort.ts

@@ -0,0 +1,16 @@
+import type { Effort } from '../types'
+
+const LADDER = ['minimal', 'low', 'medium', 'high', 'xhigh', 'max', 'ultra'] as const
+
+export function clampEffort(requested: Effort, supported?: readonly string[]): { value: string; clamped: boolean } {
+  if (!supported || supported.length === 0) return { value: requested, clamped: false }
+  if (supported.includes(requested)) return { value: requested, clamped: false }
+  const wanted = LADDER.indexOf(requested as (typeof LADDER)[number])
+  const ranked = supported
+    .map((s) => ({ s, i: LADDER.indexOf(s as (typeof LADDER)[number]) }))
+    .filter((x) => x.i >= 0)
+    .sort((a, b) => a.i - b.i)
+  if (ranked.length === 0) return { value: supported[0]!, clamped: true }
+  const below = ranked.filter((x) => x.i < wanted).pop()
+  return { value: (below ?? ranked[0]!).s, clamped: true }
+}

package/src/adapters/index.ts

@@ -0,0 +1,20 @@
+import type { AgentId } from '../types'
+import type { Adapter } from './types'
+import { claudeAdapter } from './claude'
+import { codexAdapter } from './codex'
+import { kiroAdapter } from './kiro'
+import { opencodeAdapter } from './opencode'
+
+export const adapters: Record<AgentId, Adapter> = {
+  claude: claudeAdapter,
+  codex: codexAdapter,
+  kiro: kiroAdapter,
+  opencode: opencodeAdapter,
+}
+
+export function getAdapter(id: AgentId): Adapter {
+  return adapters[id]
+}
+
+export { agentIds } from '../config/schema'
+export type { Adapter }

package/src/adapters/kiro.ts

@@ -0,0 +1,79 @@
+import type { Binding, KonvoyEvent, Permission, SpawnPlan, TurnContext } from '../types'
+import { classifyError, safeJson, stripControlChars, withPrelude, type Adapter } from './types'
+
+const TRUST: Record<Permission, string> = {
+  safe: '--trust-tools=',
+  edit: '--trust-tools=fs_read,fs_write,grep,glob,execute_bash',
+  yolo: '--trust-all-tools',
+}
+
+export const kiroAdapter: Adapter = {
+  id: 'kiro',
+  bin: 'kiro-cli',
+  supportsPresetSessionId: false,
+
+  turn(ctx: TurnContext): SpawnPlan {
+    const cmd = [ctx.bin ?? 'kiro-cli', 'chat', '--no-interactive', '--output-format', 'stream-json']
+    if (ctx.binding?.foreignId) cmd.push('--resume-id', ctx.binding.foreignId)
+    if (ctx.model) cmd.push('--model', ctx.model)
+    cmd.push('--effort', ctx.effort, TRUST[ctx.permission], '--', withPrelude(ctx))
+    return { cmd, cwd: ctx.cwd }
+  },
+
+  parse(line: string): KonvoyEvent[] {
+    const o = safeJson(line)
+    if (!o) return []
+    const data = o.data as Record<string, unknown> | undefined
+    if (!data) return []
+
+    const events: KonvoyEvent[] = []
+    if (typeof data.sessionId === 'string') events.push({ t: 'session', foreignId: stripControlChars(data.sessionId) })
+
+    if (o.type === 'sessionUpdate') {
+      const update = data.update as
+        | { sessionUpdate?: string; content?: { text?: string }; title?: string; status?: string }
+        | undefined
+      const text = update?.content?.text
+      switch (update?.sessionUpdate) {
+        case 'agent_message_chunk':
+          if (text) events.push({ t: 'text', text })
+          break
+        case 'agent_thought_chunk':
+          if (text) events.push({ t: 'thinking', text })
+          break
+        case 'tool_call':
+          events.push({ t: 'tool', name: update.title ?? 'tool', status: 'start' })
+          break
+        case 'tool_call_update':
+          events.push({ t: 'tool', name: update.title ?? 'tool', status: update.status === 'failed' ? 'error' : 'ok' })
+          break
+      }
+    }
+
+    if (o.type === 'metadata') {
+      const metering = Array.isArray(data.meteringUsage)
+        ? (data.meteringUsage as { value?: number; unit?: string }[])
+        : undefined
+      const credits = metering?.find((m) => m.unit === 'credit')?.value
+      if (typeof credits === 'number') events.push({ t: 'usage', credits })
+    }
+
+    if (o.type === 'runFinished') {
+      if (data.status === 'success') {
+        // finalText comes with a finalTextTruncated flag — kiro truncates it. Only an untruncated
+        // copy is authoritative; otherwise no done is emitted and the streamed chunks stand.
+        if (typeof data.finalText === 'string' && data.finalTextTruncated !== true) events.push({ t: 'done', final: data.finalText })
+      } else {
+        const message = typeof data.stopReason === 'string' ? data.stopReason : ''
+        events.push({ t: 'error', message, kind: classifyError(message) })
+      }
+    }
+
+    return events
+  },
+
+  attach(binding: Binding): SpawnPlan {
+    if (!binding.foreignId) return { cmd: ['kiro-cli', 'chat'] }
+    return { cmd: ['kiro-cli', 'chat', '--resume-id', binding.foreignId] }
+  },
+}