feat: add ACP v2 support again

.agents/skills/check-acp-specification/.gitignore

@@ -0,0 +1 @@
+.repo

.agents/skills/check-acp-specification/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: check-acp-specification
+description: Check the current Agent Client Protocol specification, including its documentation, RFDs, Rust models, and JSON schemas. Use when ACP protocol behavior or models must be verified against the latest upstream specification. Do not use it as a Rust reference implementation.
+---
+
+# Check the ACP specification
+
+Use the official [Agent Client Protocol repository](https://github.com/agentclientprotocol/agent-client-protocol) as the source of truth for current ACP documentation, design decisions, Rust models, and JSON schemas.
+
+## Locate the repository
+
+The `.repo` file next to this `SKILL.md` is gitignored and contains one absolute path to a local clone of the specification repository. Read and trim that path before doing any upstream research.
+
+If `.repo` does not exist, explicitly ask the user for permission to clone the repository and for their preferred clone location. Do not clone it until permission is granted. If the user grants permission without choosing a location, clone `agent-client-protocol` beside the current ACP SDK checkout. After cloning, write the clone's absolute path to `.repo`.
+
+If `.repo` exists but its value does not identify a usable Git checkout, report the problem and ask the user whether to correct the path or create a clone. Do not silently replace an existing checkout.
+
+## Refresh before research
+
+Before exploring or searching the local specification checkout, update it:
+
+```bash
+git -C "<absolute path read from .repo>" pull --ff-only
+```
+
+Run this on every use of the skill, even if the checkout was used recently. If the pull fails, report the failure and do not describe the checkout as current. Do not discard local changes, reset branches, or otherwise repair the checkout without the user's authorization.
+
+After the pull succeeds, read the checkout's applicable `AGENTS.md` or other agent-guidance files before researching it, including more specific guidance in subdirectories you inspect.
+
+## Check the source of truth
+
+Choose the authoritative upstream evidence that matches the question:
+
+- Use documentation for stated public behavior and concepts.
+- Use RFDs for design intent, tradeoffs, and protocol evolution.
+- Use JSON schemas for wire names, shapes, required fields, optionality, nullability, and unions.
+- Use Rust model definitions as another representation of protocol data types and serialization shapes.
+
+Trace related evidence across these sources when the question spans semantics and wire representation. Treat schemas and normative documentation as protocol contracts. Do not infer runtime behavior, lifecycle semantics, or reference implementation details from the Rust models.
+
+Report the upstream revision checked, cite concrete repository-relative files and lines, and distinguish confirmed specification requirements from RFD proposals or Rust model representation details. If authoritative sources disagree, surface the discrepancy instead of choosing one without explanation.

.agents/skills/check-acp-typescript-sdk/.gitignore

@@ -0,0 +1 @@
+.repo

.agents/skills/check-acp-typescript-sdk/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: check-acp-typescript-sdk
+description: Check the current official Agent Client Protocol TypeScript SDK reference implementation, including runtime behavior, lifecycle semantics, error handling, tests, and API patterns. Use when behavior must be compared with the latest TypeScript reference behavior or you need to understand how to use the TypeScript SDK. Do not use it as the source of truth for protocol schemas or specification text.
+---
+
+# Check the ACP TypeScript SDK
+
+Use the official [Agent Client Protocol TypeScript SDK](https://github.com/agentclientprotocol/typescript-sdk) as the reference implementation for ACP runtime behavior.
+
+The TypeScript SDK is implementation evidence, not the normative protocol specification. Use the separate specification skill for current documentation, RFDs, and protocol models or schemas. If the implementation and specification disagree, report the discrepancy instead of silently treating the TypeScript behavior as the protocol contract.
+
+## Locate the repository
+
+The `.repo` file next to this `SKILL.md` is gitignored and contains one absolute path to a local clone of the TypeScript SDK repository. Read and trim that path before doing any reference-implementation research.
+
+If `.repo` does not exist, explicitly ask the user for permission to clone the repository and for their preferred clone location. Do not clone it until permission is granted. If the user grants permission without choosing a location, clone the repository as `acp-typescript-sdk` beside the current ACP checkout. After cloning, write the clone's absolute path to `.repo`.
+
+If `.repo` exists but its value does not identify a usable Git checkout, report the problem and ask the user whether to correct the path or create a clone. Do not silently replace an existing checkout.
+
+## Refresh before research
+
+Before exploring or searching the local TypeScript SDK checkout, update it:
+
+```bash
+git -C "<absolute path read from .repo>" pull --ff-only
+```
+
+Run this on every use of the skill, even if the checkout was used recently. If the pull fails, report the failure and do not describe the checkout as current. Do not discard local changes, reset branches, or otherwise repair the checkout without the user's authorization.
+
+After the pull succeeds, read the checkout's applicable `AGENTS.md` or other agent-guidance files before researching it, including more specific guidance in subdirectories you inspect.
+
+## Check the reference implementation
+
+Trace the complete TypeScript behavior relevant to the question rather than relying on similarly named types or isolated functions:
+
+- Start at the public API or protocol entry point and follow control flow through the owning runtime and transport layers.
+- Read focused tests alongside the implementation to confirm observable behavior, failure handling, cancellation, cleanup, and ordering.
+- Check examples when the question concerns supported API usage or lifecycle wiring.
+- Check model and serialization code (e.g. Zod schemas or TypeScript type definitions) when it directly affects how the reference implementation consumes or produces protocol data.
+
+Compare externally observable semantics rather than translating TypeScript structure mechanically. Account for Promise, event loop, and async/await behavior, error propagation, and shutdown rules explicitly when they affect parity.
+
+Report the upstream revision checked and cite concrete repository-relative files and lines. Distinguish behavior demonstrated by code or tests from interpretation, and note any relevant version constraints or untested paths.

.claude/agents

@@ -0,0 +1 @@
+../.agents/agents

.claude/skills

@@ -0,0 +1 @@
+../.agents/skills

AGENTS.md

@@ -15,6 +15,7 @@
 - When adding env/config knobs, document them in `readme-dev.md`.
 - When updating discriminated-union/event `switch` statements, do not add a trailing fallback like `return null` only to satisfy TypeScript.
 - Handle each variant with an explicit `case`; if intentionally ignored, use an explicit no-op case.
+- Code comments should be concise and in plain language; avoid verbosity and overly specific detail.
 
 ## Testing Guidelines
 

package.json

@@ -67,7 +67,7 @@
     "vitest": "^5.0.1"
   },
   "dependencies": {
-    "@agentclientprotocol/sdk": "^1.5.0",
+    "@agentclientprotocol/sdk": "~1.5.0",
     "@openai/codex": "^0.160.1",
     "cross-spawn": "^7.0.6",
     "diff": "^9.0.0",

readme-dev.md

@@ -125,3 +125,58 @@ The adapter restarts the Codex app-server when it dies (for example, killed for
   with the stderr of the last crash.
   A session that the app-server died opening twice in 30 minutes is not opened again for the rest of that time, so
   one session that is too large for the memory cannot take the other sessions down with it.
+
+### ACP v2 support
+
+The agent speaks both ACP v1 and the unstable ACP v2 (Draft) protocol from the same process; the
+version is negotiated on the first `initialize` request and fixed for the connection's lifetime.
+
+The v2 chain registers: `initialize`, `session/new|list|close|delete|resume` (v2 folds `session/load`
+into `session/resume` with `replayFrom`), `session/set_config_option`, `session/cancel`,
+`auth/login|logout`, `session/prompt` (plus `$/cancel_request`), `session/fork`, and
+`providers/list|set|disable`. Unstable extension methods on top of that: `_session/steering`,
+`_session/goal` (set/pause/resume/clear), and `_session/async_task/stop`. `session/fork` drops the
+v1 `modes` field (v2 removed the modes API in favor of config options), and forked sessions do not
+get an `available_commands_update`, matching v1. There are no new environment/config knobs specific
+to v2; it reuses the runtime environment variables above.
+
+#### AIR v2 client contract
+
+These are behaviors the AIR (JetBrains) ACP client relies on that aren't obvious from the wire
+schema alone:
+
+- On a failed prompt, read `sessionFailure` (`_meta.jetbrains.air.sessionFailure`) and `quota`
+  (`_meta.quota`) from the idle `state_update` that ends the turn, not from a separate error
+  channel. The same `_meta` v1 attaches to `PromptResponse` is copied onto the v2 idle update.
+- Custom session updates are renamed on v2: `subagent_spawned`/`subagent_state_update` become a
+  single `_subagent_update` (gated on the AIR `nativeSubagentSessions` capability; it will rename to
+  `subagent_update` once the subagent RFD, spec PR #1992, lands), and
+  `async_task_spawned`/`async_task_state_update` become `_async_task_spawned`/`_async_task_state_update`
+  (gated on the AIR `asyncTasks` capability). Payload shapes are unchanged.
+- The SDK client treats any `idle` state update as the stop of whichever prompt is pending, not just
+  one paired 1:1 with a `session/prompt` call.
+- A steer (`_session/steering`) shows up as a `user_message` once it actually lands in the turn.
+- On cancel, any permission or elicitation request still waiting on a client response is withdrawn
+  with `$/cancel_request`, not just the underlying Codex turn.
+- Turns Codex starts on its own (goal auto-turns, e.g. after `session/resume` or `session/new`) are
+  rendered the same as prompted turns (`running` then one `idle`) but with no corresponding
+  `session/prompt` call — clients should not assume every `running`/`idle` pair has a matching
+  outbound prompt.
+- After a tool call streams terminal output as `terminal_output_chunk`s, completion does not resend a
+  full `output` snapshot; the streamed chunks are the only copy of the output.
+- The AIR tool call contract (`docs/air-extensions.md`) does not apply on v2: every v2 client gets
+  the standard tool call reports, so `rawInputRendering`, `planContentDelta` and `diffPatch` are not
+  offered there. A read, search or list command has no terminal; its output arrives as `content`
+  text when it completes. A file change sends one diff per file whose Git patch is built from the
+  Codex diff.
+- Other AIR `_meta` keys (goal, message phase, mode kind, permission presentation) go only to AIR
+  clients, as on v1. Every v2 permission request still gets its prompt `title` and `description`.
+
+#### Known gaps
+
+- After `providers/disable("openai")`, `providers/list` still reports native OpenAI routing as the
+  current provider. The providers RFD says a disabled provider's `current` should be `null`; this is
+  left as-is and documented here rather than fixed.
+- Open question for AIR: AIR's fork points match Codex item ids, but on v2 a user message's
+  rendered id is the client-minted `clientId` (when the client supplied one), not the Codex item id.
+  A fork at a user message would not resolve. This is flagged for AIR, not fixed here.