feat: add gemini-acp provider, update docs on subscription models + improvements to codex (#8000)

Signed-off-by: Michael Neale <michael.neale@gmail.com>

crates/goose/src/providers/chatgpt_codex.rs

@@ -45,8 +45,9 @@ const OAUTH_TIMEOUT_SECS: u64 = 300;
 const HTML_AUTO_CLOSE_TIMEOUT_MS: u64 = 2000;
 
 const CHATGPT_CODEX_PROVIDER_NAME: &str = "chatgpt_codex";
-pub const CHATGPT_CODEX_DEFAULT_MODEL: &str = "gpt-5.1-codex";
+pub const CHATGPT_CODEX_DEFAULT_MODEL: &str = "gpt-5.3-codex";
 pub const CHATGPT_CODEX_KNOWN_MODELS: &[&str] = &[
+    "gpt-5.4",
     "gpt-5.3-codex",
     "gpt-5.2-codex",
     "gpt-5.1-codex",
@@ -56,6 +57,14 @@ pub const CHATGPT_CODEX_KNOWN_MODELS: &[&str] = &[
 
 const CHATGPT_CODEX_DOC_URL: &str = "https://openai.com/chatgpt";
 
+const GPT_53_CODEX_TOOL_PREAMBLE: &str = "\
+You are a coding agent. You have access to tools to accomplish tasks. \
+Always use your tools to fulfill requests - do not just describe what you would do. \
+Keep going until the query is completely resolved before yielding back to the user. \
+Autonomously resolve the query using the tools available to you. \
+Do NOT guess or make up an answer. \
+Before making tool calls, send a brief message explaining what you're about to do.";
+
 #[derive(Debug)]
 struct ChatGptCodexAuthState {
     oauth_mutex: TokioMutex<()>,
@@ -181,11 +190,16 @@ fn create_codex_request(
 ) -> Result<Value> {
     let input_items = build_input_items(messages)?;
 
+    let instructions = match model_config.model_name.as_str() {
+        "gpt-5.3-codex" => format!("{GPT_53_CODEX_TOOL_PREAMBLE}\n\n{system}"),
+        _ => system.to_string(),
+    };
+
     let mut payload = json!({
         "model": model_config.model_name,
         "input": input_items,
         "store": false,
-        "instructions": system,
+        "instructions": instructions,
     });
 
     let payload_obj = payload

crates/goose/src/providers/claude_code.rs

@@ -589,7 +589,7 @@ impl ProviderDef for ClaudeCodeProvider {
         ProviderMetadata::new(
             CLAUDE_CODE_PROVIDER_NAME,
             "Claude Code CLI",
-            "Requires claude CLI installed, no MCPs. Use Anthropic provider for full features.",
+            "[Deprecated: use claude-acp instead] Requires claude CLI installed, no MCPs. Use claude-acp for ACP support with extensions.",
             CLAUDE_CODE_DEFAULT_MODEL,
             // Only a few agentic choices; fetched dynamically via fetch_supported_models.
             vec![],

crates/goose/src/providers/codex.rs

@@ -598,7 +598,7 @@ impl ProviderDef for CodexProvider {
         ProviderMetadata::new(
             CODEX_PROVIDER_NAME,
             "OpenAI Codex CLI",
-            "Execute OpenAI models via Codex CLI tool. Requires codex CLI installed.",
+            "[Deprecated: use chatgpt_codex or codex-acp instead] Execute OpenAI models via Codex CLI tool. Requires codex CLI installed.",
             CODEX_DEFAULT_MODEL,
             CODEX_KNOWN_MODELS.to_vec(),
             CODEX_DOC_URL,

crates/goose/src/providers/gemini_acp.rs

@@ -0,0 +1,81 @@
+use anyhow::Result;
+use futures::future::BoxFuture;
+use std::path::PathBuf;
+
+use crate::acp::{
+    extension_configs_to_mcp_servers, AcpProvider, AcpProviderConfig, PermissionMapping,
+};
+use crate::config::search_path::SearchPaths;
+use crate::config::{Config, GooseMode};
+use crate::model::ModelConfig;
+use crate::providers::base::{ProviderDef, ProviderMetadata};
+
+const GEMINI_ACP_PROVIDER_NAME: &str = "gemini-acp";
+pub const GEMINI_ACP_DEFAULT_MODEL: &str = "default";
+const GEMINI_ACP_DOC_URL: &str = "https://github.com/google-gemini/gemini-cli";
+
+pub struct GeminiAcpProvider;
+
+impl ProviderDef for GeminiAcpProvider {
+    type Provider = AcpProvider;
+
+    fn metadata() -> ProviderMetadata {
+        ProviderMetadata::new(
+            GEMINI_ACP_PROVIDER_NAME,
+            "Gemini CLI (ACP)",
+            "ACP provider for Google's Gemini CLI. Install: npm install -g @google/gemini-cli",
+            GEMINI_ACP_DEFAULT_MODEL,
+            vec![],
+            GEMINI_ACP_DOC_URL,
+            vec![],
+        )
+    }
+
+    fn from_env(
+        model: ModelConfig,
+        extensions: Vec<crate::config::ExtensionConfig>,
+    ) -> BoxFuture<'static, Result<AcpProvider>> {
+        Box::pin(async move {
+            let config = Config::global();
+            let command_name: String = config.get_gemini_cli_command().unwrap_or_default().into();
+            let resolved_command = SearchPaths::builder().with_npm().resolve(&command_name)?;
+            let goose_mode = config.get_goose_mode().unwrap_or(GooseMode::Auto);
+
+            let permission_mapping = PermissionMapping {
+                allow_option_id: Some("allow".to_string()),
+                reject_option_id: Some("reject".to_string()),
+                rejected_tool_status: sacp::schema::ToolCallStatus::Failed,
+            };
+
+            let mut args = vec!["--acp".to_string()];
+            if model.model_name != "default" {
+                args.push("--model".to_string());
+                args.push(model.model_name.clone());
+            }
+
+            let provider_config = AcpProviderConfig {
+                command: resolved_command,
+                args,
+                env: vec![],
+                env_remove: vec![],
+                work_dir: std::env::current_dir().unwrap_or_else(|_| PathBuf::from(".")),
+                mcp_servers: extension_configs_to_mcp_servers(&extensions),
+                session_mode_id: Some(map_goose_mode(goose_mode)),
+                permission_mapping,
+                notification_callback: None,
+            };
+
+            let metadata = Self::metadata();
+            AcpProvider::connect(metadata.name, model, goose_mode, provider_config).await
+        })
+    }
+}
+
+fn map_goose_mode(goose_mode: GooseMode) -> String {
+    match goose_mode {
+        GooseMode::Auto => "yolo".to_string(),
+        GooseMode::Approve => "default".to_string(),
+        GooseMode::SmartApprove => "auto_edit".to_string(),
+        GooseMode::Chat => "plan".to_string(),
+    }
+}

crates/goose/src/providers/gemini_cli.rs

@@ -161,7 +161,7 @@ impl ProviderDef for GeminiCliProvider {
         ProviderMetadata::new(
             GEMINI_CLI_PROVIDER_NAME,
             "Gemini CLI",
-            "Execute Gemini models via gemini CLI tool",
+            "[Deprecated: use gemini-acp instead] Execute Gemini models via gemini CLI tool. Requires gemini CLI installed.",
             GEMINI_CLI_DEFAULT_MODEL,
             GEMINI_CLI_KNOWN_MODELS.to_vec(),
             GEMINI_CLI_DOC_URL,

crates/goose/src/providers/init.rs

@@ -14,6 +14,7 @@ use super::{
     cursor_agent::CursorAgentProvider,
     databricks::DatabricksProvider,
     gcpvertexai::GcpVertexAIProvider,
+    gemini_acp::GeminiAcpProvider,
     gemini_cli::GeminiCliProvider,
     githubcopilot::GithubCopilotProvider,
     google::GoogleProvider,
@@ -51,6 +52,7 @@ async fn init_registry() -> RwLock<ProviderRegistry> {
         registry.register::<LocalInferenceProvider>(false);
         registry.register::<ChatGptCodexProvider>(true);
         registry.register::<ClaudeAcpProvider>(false);
+        registry.register::<GeminiAcpProvider>(false);
         registry.register::<ClaudeCodeProvider>(true);
         registry.register::<CodexAcpProvider>(false);
         registry.register::<CodexProvider>(true);

crates/goose/src/providers/mod.rs

@@ -21,6 +21,7 @@ pub mod errors;
 pub mod formats;
 mod gcpauth;
 pub mod gcpvertexai;
+pub mod gemini_acp;
 pub mod gemini_cli;
 pub mod githubcopilot;
 pub mod google;

crates/goose/tests/providers.rs

@@ -17,6 +17,7 @@ use goose::providers::codex_acp::CODEX_ACP_DEFAULT_MODEL;
 use goose::providers::create_with_named_model;
 use goose::providers::databricks::DATABRICKS_DEFAULT_MODEL;
 use goose::providers::errors::ProviderError;
+use goose::providers::gemini_acp::GEMINI_ACP_DEFAULT_MODEL;
 use goose::providers::google::GOOGLE_DEFAULT_MODEL;
 use goose::providers::litellm::LITELLM_DEFAULT_MODEL;
 use goose::providers::openai::OPEN_AI_DEFAULT_MODEL;
@@ -890,6 +891,14 @@ async fn test_codex_acp_provider() -> Result<()> {
         .await
 }
 
+// Requires: npm install -g @google/gemini-cli
+#[tokio::test]
+async fn test_gemini_acp_provider() -> Result<()> {
+    ProviderTestConfig::with_agentic_provider("gemini-acp", GEMINI_ACP_DEFAULT_MODEL, "gemini")
+        .run()
+        .await
+}
+
 #[ctor::dtor]
 fn print_test_report() {
     TEST_REPORT.print_summary();

documentation/blog/2026-03-19-use-goose-with-your-ai-subscription/index.md

@@ -0,0 +1,74 @@
+---
+title: "Use Goose with Your AI Subscription"
+description: "A quick update on using subscriptions for claude, gemini and codex"
+authors: 
+    - mic
+---
+
+You can use your subscriptions for codex, claude and gemini now with goose, thanks to ACP! (Agent Client Protocol).
+Codex is also special in that you can login directly to chatgpt - nothing else needs to be installed. 
+
+Gemini natively supports ACP, so it now works with a gemini acp provider in goose. At the time of writing, claude requires just one utility installed just once.
+
+<!--truncate-->
+
+## Why subscriptions?
+
+Well you can use what you already pay for. Obviously! and sessions and so on are still in goose. 
+ACP gives a deeper connection to these agents than using the CLI as providers. In this world - you can think of this as a stack of agents: 
+goose plugs into gemini via ACP (and other things, clients could plug in to goose!) but gemini (and also claude code) also act as an agent loop somewhat. 
+With ACP you are using the tools that are (mostly) in the underlying agent. Codex, however, is a full power LLM api, so you can use extensions natively in goose for that one.
+
+## Claude Code — via ACP
+
+If you have a Claude Code subscription, you can use it through goose via the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/). This requires installing a small adapter package:
+
+```bash
+npm install -g @zed-industries/claude-agent-acp
+```
+
+Then configure goose to use it via the claude acp extension (CLI or GUI)
+
+
+Or set it via environment variables:
+
+```bash
+export GOOSE_PROVIDER=claude-acp
+goose
+```
+
+goose passes your MCP extensions through to Claude via ACP, so any custom MCP servers you've configured in goose are available to the agent.
+
+## ChatGPT — sign in with your account
+
+If you have ChatGPT Plus or Pro, the `chatgpt_codex` provider lets you use goose with your existing account. Just pick ChatGPT when you are setting up the goose app for the first time (or changing to that provider)
+
+The first time you run it, goose will open a browser window for you to sign in with your ChatGPT account. After that, your session is cached locally.
+
+The recommended model is `gpt-5.3-codex`, which is the default. You can also select `gpt-5.4` (OpenAI's latest omni model) or `gpt-5.2-codex` from the model picker.
+
+## Gemini — via ACP (native)
+
+If you have a Google account with Gemini access, the Gemini CLI speaks ACP natively — no separate adapter needed. Just install the Gemini CLI itself:
+
+```bash
+npm install -g @google/gemini-cli
+```
+
+... and run `gemini` at least once. 
+
+On first run, Gemini CLI will ask you to authenticate with your Google account. After that, goose passes your extensions directly through to Gemini via ACP. 
+
+## What about the old CLI providers?
+
+Goose previously supported `claude-code`, `codex`, and `gemini-cli` as "pass-through" CLI providers. These will be removed soon as ACP is the future! 
+
+## Quick reference
+
+| Subscription | Provider | Install | Extensions |
+|---|---|---|---|
+| Claude Code | `claude-acp` | `npm install -g @zed-industries/claude-agent-acp` | ✅ via MCP |
+| ChatGPT Plus/Pro | `chatgpt_codex` | Nothing — OAuth sign-in | ✅ via MCP |
+| Gemini | `gemini-acp` | `npm install -g @google/gemini-cli` | ✅ via MCP |
+
+Pick the one that matches what you're already paying for, and you're good to go.

documentation/docs/getting-started/providers.md

@@ -55,18 +55,9 @@ goose automatically enables Anthropic's [prompt caching](https://platform.claude
 
 ### CLI Providers
 
-goose also supports special "pass-through" providers that work with existing CLI tools, allowing you to use your subscriptions instead of paying per token:
-
 | Provider                                                                    | Description                                                                                                                                                                                                               | Requirements                                                                                                                                                                          |
 |-----------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| [Claude Code](https://www.anthropic.com/claude-code) (`claude-code`)                       | Uses Anthropic's Claude CLI tool with your Claude Code subscription. Provides access to Claude with 200K context limit.                                                                                      | Claude CLI installed and authenticated, active Claude Code subscription                                                                                                              |
-| [OpenAI Codex](https://developers.openai.com/codex/cli) (`codex`)          | Uses OpenAI's Codex CLI tool with your ChatGPT Plus/Pro subscription. Provides access to GPT-5 models with up to 400K context limit.                                                                         | Codex CLI installed and authenticated, active ChatGPT Plus/Pro subscription                                                                                                          |
 | [Cursor Agent](https://docs.cursor.com/en/cli/overview) (`cursor-agent`)   | Uses Cursor's AI CLI tool with your Cursor subscription. Provides access to GPT-5, Claude 4, and other models through the cursor-agent command-line interface.                                              | cursor-agent CLI installed and authenticated                                                                                                         |
-| [Gemini CLI](https://ai.google.dev/gemini-api/docs) (`gemini-cli`)         | Uses Google's Gemini CLI tool with your Google AI subscription. Provides access to Gemini with 1M context limit.                                                                                               | Gemini CLI installed and authenticated                                                                                                                |
-
-:::tip CLI Providers
-CLI providers are cost-effective alternatives that use your existing subscriptions. They work differently from API providers as they execute CLI commands and integrate with the tools' native capabilities. See the [CLI Providers guide](/docs/guides/cli-providers) for detailed setup instructions.
-:::
 
 ### ACP Providers
 
@@ -76,6 +67,7 @@ goose supports [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) a
 |-----------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | [Claude ACP](https://github.com/zed-industries/claude-agent-acp) (`claude-acp`) | Uses Claude Code via ACP. Passes goose extensions to the agent as MCP servers. | `npm install -g @zed-industries/claude-agent-acp`, active Claude Code subscription |
 | [Codex ACP](https://github.com/zed-industries/codex-acp) (`codex-acp`) | Uses OpenAI Codex via ACP. Passes goose extensions to the agent as MCP servers. | `npm install -g @zed-industries/codex-acp`, active ChatGPT Plus/Pro subscription |
+| [Gemini ACP](https://github.com/google-gemini/gemini-cli) (`gemini-acp`) | Uses Google's Gemini CLI via ACP (native `--acp` support). Passes goose extensions to the agent as MCP servers. | `npm install -g @google/gemini-cli`, authenticated with Google account |
 
 :::tip ACP Providers
 See the [ACP Providers guide](/docs/guides/acp-providers) for detailed setup instructions.

documentation/docs/guides/acp-providers.md

@@ -11,6 +11,10 @@ goose supports [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) a
 
 ACP providers pass goose [extensions](/docs/getting-started/using-extensions) through to the agent as MCP servers, so the agent can call your extensions directly.
 
+:::tip Use Your Existing Subscriptions
+ACP providers let you use goose with your existing Claude Code, ChatGPT Plus/Pro, or Google Gemini subscriptions — no per-token API costs. They are the recommended replacement for the deprecated [CLI providers](/docs/guides/cli-providers).
+:::
+
 :::warning Limitations
 - **No session fork or resume**: You can start new sessions, but `goose session resume` and `goose session fork` are not supported yet.
 - **ACP session ID differs from goose session ID**: Telemetry fields may not correlate across the two.
@@ -20,7 +24,7 @@ ACP providers pass goose [extensions](/docs/getting-started/using-extensions) th
 
 ### Claude ACP
 
-Wraps [claude-agent-acp](https://github.com/zed-industries/claude-agent-acp), an ACP adapter for Anthropic's Claude Code. Uses the same Claude subscription as the `claude-code` CLI provider.
+Wraps [claude-agent-acp](https://github.com/zed-industries/claude-agent-acp), an ACP adapter for Anthropic's Claude Code. Uses the same Claude subscription as the deprecated `claude-code` CLI provider.
 
 **Requirements:**
 - Node.js and npm
@@ -29,13 +33,22 @@ 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 deprecated `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
 - Active ChatGPT Plus/Pro subscription or OpenAI API credits
 - Authenticated with your OpenAI account (`codex` CLI working)
 
+### Gemini ACP
+
+Uses Google's [Gemini CLI](https://github.com/google-gemini/gemini-cli) directly via its native `--acp` flag. No shim needed — Gemini CLI speaks ACP natively. Replaces the deprecated `gemini-cli` CLI provider.
+
+**Requirements:**
+- Node.js and npm
+- Gemini CLI installed (`npm install -g @google/gemini-cli`)
+- Authenticated with your Google account (run `gemini` once to authenticate via browser)
+
 ## Setup Instructions
 
 ### Claude ACP
@@ -110,6 +123,42 @@ Wraps [codex-acp](https://github.com/zed-industries/codex-acp), an ACP adapter f
    │  gpt-5.2-codex
    ```
 
+### Gemini ACP
+
+1. **Install Gemini CLI**
+
+   ```bash
+   npm install -g @google/gemini-cli
+   ```
+
+2. **Authenticate with Google**
+
+   Run `gemini` once and follow the browser-based authentication flow.
+
+3. **Configure goose**
+
+   Set the provider environment variable:
+   ```bash
+   export GOOSE_PROVIDER=gemini-acp
+   ```
+
+   Or configure through the goose CLI using `goose configure`:
+
+   ```bash
+   ┌   goose-configure
+   │
+   ◇  What would you like to configure?
+   │  Configure Providers
+   │
+   ◇  Which model provider should we use?
+   │  Gemini CLI (ACP)
+   │
+   ◇  Model fetch complete
+   │
+   ◇  Enter a model from that provider:
+   │  default
+   ```
+
 ## Usage Examples
 
 ### Basic Usage
@@ -134,6 +183,12 @@ GOOSE_PROVIDER=codex-acp goose run \
   -t 'Search for flights from BKI to SYD tomorrow'
 ```
 
+```bash
+GOOSE_PROVIDER=gemini-acp goose run \
+  --with-extension 'npx -y @modelcontextprotocol/server-everything' \
+  -t 'Use the echo tool to say hello'
+```
+
 ## Configuration Options
 
 ### Claude ACP Configuration
@@ -185,13 +240,32 @@ See [claude-agent-acp](https://github.com/zed-industries/claude-agent-acp) for s
 
 See [codex-acp](https://github.com/zed-industries/codex-acp) for approval policy and sandbox details.
 
+### Gemini ACP Configuration
+
+| Environment Variable | Description         | Default     |
+|----------------------|---------------------|-------------|
+| `GOOSE_PROVIDER`     | Set to `gemini-acp` | None        |
+| `GOOSE_MODEL`        | Model to use        | `default`   |
+| `GOOSE_MODE`         | Permission mode     | `auto`      |
+
+**Permission Modes (`GOOSE_MODE`):**
+
+| Mode            | Gemini Mode  | Behavior                                                      |
+|-----------------|-------------|---------------------------------------------------------------|
+| `auto`          | `yolo`      | Auto-approves all tool calls                                  |
+| `smart-approve` | `auto_edit` | Auto-approves file edits, prompts for other operations        |
+| `approve`       | `default`   | Prompts for all permission-required operations                |
+| `chat`          | `plan`      | Planning only, no tool execution                              |
+
+See the [Gemini CLI documentation](https://github.com/google-gemini/gemini-cli) for approval mode details.
+
 ## Error Handling
 
 ACP providers depend on external npm packages, so ensure:
 
-- The ACP adapter binary is installed and in your PATH (`claude-agent-acp` or `codex-acp`)
+- The ACP agent binary is installed and in your PATH (`claude-agent-acp`, `codex-acp`, or `gemini`)
 - The underlying CLI tool is authenticated and working
 - Subscription limits are not exceeded
 - Node.js and npm are installed
 
-If goose can't find the binary, session startup will fail with an error. Run `which claude-agent-acp` or `which codex-acp` to verify installation.
+If goose can't find the binary, session startup will fail with an error. Run `which claude-agent-acp`, `which codex-acp`, or `which gemini` to verify installation.

documentation/docs/guides/cli-providers.md

@@ -7,6 +7,10 @@ description: Use Claude Code, Codex, Cursor Agent, or Gemini CLI subscriptions i
 
 # CLI Providers
 
+:::warning Deprecated — Use ACP Providers
+The Claude Code (`claude-code`), Codex (`codex`), and Gemini CLI (`gemini-cli`) providers are deprecated. Use the [ACP providers](/docs/guides/acp-providers) (`claude-acp`, `codex-acp`, `gemini-acp`) instead, which support goose extensions via MCP and use the standardized Agent Client Protocol. CLI providers are kept for backward compatibility only.
+:::
+
 goose can make use of pass-through providers that integrate with existing CLI tools from Anthropic, OpenAI, Cursor, and Google. These providers allow you to use your existing Claude Code, Codex, Cursor Agent, and Google Gemini CLI subscriptions through goose's interface, adding session management, persistence, and workflow integration capabilities to these tools.
 
 :::warning Limitations