docs: polish ACP docs (#7946)

Signed-off-by: Adrian Cole <adrian@tetrate.io>

documentation/docs/experimental/vs-code-extension.md

@@ -18,7 +18,7 @@ The extension uses the [Agent Client Protocol (ACP)](/docs/guides/acp-clients) t
 
 :::info Prerequisites
 - [VS Code](https://code.visualstudio.com/) version 1.95.0 or higher
-- [goose CLI](/docs/getting-started/installation) version 1.16.0 or higher
+- [goose CLI](/docs/getting-started/installation)
 :::
 
 1. Go to [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=block.vscode-goose)

documentation/docs/goose-architecture/goose-architecture.md

@@ -27,7 +27,19 @@ Extensions expose their functionality to goose through tools. Tools are the func
 
 goose comes with a set of [built-in extensions](/docs/getting-started/using-extensions#built-in-extensions), each designed to enhance your interaction. These include tools for development, web scraping, automation, memory, and more. goose also supports [connecting to external extensions](/docs/getting-started/using-extensions#adding-extensions) or [creating custom extensions](/docs/tutorials/custom-extensions) as MCP servers. 
 
-To learn more about the design and implementation of extensions and tools, refer to the [Extensions Design Guide](/docs/goose-architecture/extensions-design#tools). 
+To learn more about the design and implementation of extensions and tools, refer to the [Extensions Design Guide](/docs/goose-architecture/extensions-design#tools).
+
+## Agent Client Protocol (ACP)
+
+goose supports the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) in two ways:
+
+### goose as an ACP Server
+
+`goose acp` starts goose as an ACP server over stdio, letting editors like JetBrains and Zed connect to it directly. See [Using goose in ACP Clients](/docs/guides/acp-clients).
+
+### ACP Agents as Providers
+
+goose can delegate to external ACP agents (like Claude Code or Codex) as [providers](/docs/guides/acp-providers). The ACP agent handles tool execution internally. goose passes configured extensions through as MCP servers.
 
 ## Interactive Loop
 ![interactive loop](../assets/guides/interactive-loop.png)

documentation/docs/guides/acp-clients.md

@@ -17,8 +17,10 @@ The client manages the goose lifecycle automatically, including:
 
 - **Initialization**: The client runs the `goose acp` command to initialize the connection
 - **Communication**: The client communicates with goose over stdio using JSON-RPC
-- **Multiple Sessions**: The client manages multiple concurrent goose conversations simultaneously
+- **Multiple Sessions**: The client manages multiple concurrent conversations, each with isolated state
-- **Session Isolation**: Each session maintains its own isolated state, including conversation history, agent context, and extension configurations, allowing concurrent sessions to run without interference
+- **Model and Mode Switching**: The client can switch models and modes mid-session without restarting
+- **File Operations**: The client handles file reads and writes, so goose sees changes not yet saved to disk and edits show as native diffs
+- **Terminal**: The client runs commands in its own terminal, so output appears alongside the conversation
 
 :::info Session Persistence
 ACP sessions are saved to goose's session history where you can access and manage them using goose. Access to session history in ACP clients might vary.
@@ -42,7 +44,7 @@ Ensure you have both Zed and goose CLI installed:
 - **Zed**: Download from [zed.dev](https://zed.dev/)
 - **goose CLI**: Follow the [installation guide](/docs/getting-started/installation)
 
-  - ACP support works best with version 1.16.0 or later - check with `goose --version`.
+  - Verify goose is installed: `goose --version`
 
   - Temporarily run `goose acp` to test that ACP support is working:
 

documentation/docs/guides/acp-providers.md

@@ -29,7 +29,7 @@ Wraps [claude-agent-acp](https://github.com/zed-industries/claude-agent-acp), an
 
 ### Codex ACP
 
-Wraps [codex-acp](https://github.com/zed-industries/codex-acp), an ACP adapter for OpenAI's Codex. Uses the same ChatGPT subscription as the `codex` CLI provider. Codex's sandbox blocks network by default — goose automatically enables network access when HTTP MCP servers are configured.
+Wraps [codex-acp](https://github.com/zed-industries/codex-acp), an ACP adapter for OpenAI's Codex. Uses the same ChatGPT subscription as the `codex` CLI provider. Codex's sandbox blocks network by default; goose automatically enables network access when HTTP MCP servers are configured.
 
 **Requirements:**
 - Node.js and npm
@@ -142,6 +142,7 @@ GOOSE_PROVIDER=codex-acp goose run \
 |----------------------|---------------------|-----------|
 | `GOOSE_PROVIDER`     | Set to `claude-acp` | None      |
 | `GOOSE_MODEL`        | Model to use        | `default` |
+| `GOOSE_MODE`         | Permission mode     | `auto`    |
 
 **Known Models:**
 - `default` (opus)
@@ -165,6 +166,7 @@ See [claude-agent-acp](https://github.com/zed-industries/claude-agent-acp) for s
 |----------------------|--------------------|-----------------|
 | `GOOSE_PROVIDER`     | Set to `codex-acp` | None            |
 | `GOOSE_MODEL`        | Model to use       | `gpt-5.2-codex` |
+| `GOOSE_MODE`         | Permission mode    | `auto`          |
 
 **Known Models:**
 - `gpt-5.2-codex`