ACP+ Extension Schema for Goose

[lifeizhou-ap]

Problem

ACP newSession currently supports mcpServers, but Goose extensions are broader than MCP servers. Goose also has builtin extensions, platform extensions, inline Python extensions, and frontend-provided tools.

Using only mcpServers is lossy for Goose-aware clients because it cannot represent those other extension types or Goose-specific config such as display metadata, default enabled state, and secret-backed environment variables.

This proposal adds a Goose-specific extension schema for ACP while keeping mcpServers as the compatibility path for generic ACP clients.

Goals

• Represent all Goose extension types in ACP.
• Keep standard ACP mcpServers unchanged.
• Allow Goose-aware clients to provide an explicit extension set when creating a session.
• Separate available server-owned definitions, persistent config defaults, and active session extensions.
• Keep config editing rules simple and enforce them server-side.

New Session

Goose-aware clients can pass an explicit extension set through _meta.extensions.

{
  "cwd": "/repo",
  "mcpServers": [],
  "_meta": {
    "extensions": [
      {
        "type": "builtin",
        "name": "developer"
      },
      {
        "type": "mcp",
        "server": {
          "type": "stdio",
          "name": "github",
          "command": "github-mcp-server",
          "args": ["stdio"]
        },
        "envKeys": ["GITHUB_TOKEN"]
      },
      {
        "type": "inline_python",
        "name": "python-tools",
        "code": "..."
      }
    ]
  }
}

Recommended precedence:

if _meta.extensions is present:
  use that explicit Goose extension set

else if mcpServers is non-empty:
  use builtins + mcpServers

else:
  use builtins + config-enabled extensions

Presence should be based on the field existing, not on the list being non-empty. This allows a client to explicitly request an empty extension set:

{
  "_meta": {
    "extensions": []
  }
}

At the API level, _meta.extensions means the client supplied the explicit extension set.

Custom Methods

Available Extensions

Returns Goose-owned extension definitions that this server can offer. For the first version this returns builtin and platform extensions only.

#[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
#[request(
    method = "_goose/unstable/extensions/available",
    response = GetAvailableExtensionsResponse
)]
pub struct GetAvailableExtensionsRequest {}

#[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcResponse)]
#[serde(rename_all = "camelCase")]
pub struct GetAvailableExtensionsResponse {
    pub extensions: Vec<GooseExtension>,
}

Persistent Config

Persistent config controls which extensions future sessions use by default.

#[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
#[request(
    method = "_goose/unstable/config/extensions/list",
    response = GetExtensionsResponse
)]
pub struct GetExtensionsRequest {}

#[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcResponse)]
#[serde(rename_all = "camelCase")]
pub struct GetExtensionsResponse {
    pub extensions: Vec<GooseExtensionEntry>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub warnings: Vec<String>,
}

#[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
#[request(
    method = "_goose/unstable/config/extensions/add",
    response = EmptyResponse
)]
#[serde(rename_all = "camelCase")]
pub struct AddConfigExtensionRequest {
    pub extension: GooseExtension,
    #[serde(default)]
    pub enabled: bool,
}

#[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
#[request(
    method = "_goose/unstable/config/extensions/remove",
    response = EmptyResponse
)]
#[serde(rename_all = "camelCase")]
pub struct RemoveConfigExtensionRequest {
    pub config_key: String,
}

#[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
#[request(
    method = "_goose/unstable/config/extensions/set-enabled",
    response = EmptyResponse
)]
#[serde(rename_all = "camelCase")]
pub struct SetConfigExtensionEnabledRequest {
    pub config_key: String,
    pub enabled: bool,
}

AddConfigExtensionRequest is an upsert for user-authored extension configs. SetConfigExtensionEnabledRequest updates only the enabled default and is the supported way to enable or disable server-owned definitions such as builtin and platform extensions.

Session Extensions

Session extension APIs operate on the active extension set for one session.

#[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
#[request(
    method = "_goose/unstable/session/extensions/list",
    response = GetSessionExtensionsResponse
)]
#[serde(rename_all = "camelCase")]
pub struct GetSessionExtensionsRequest {
    pub session_id: String,
}

#[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcResponse)]
#[serde(rename_all = "camelCase")]
pub struct GetSessionExtensionsResponse {
    pub extensions: Vec<GooseExtension>,
}

#[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
#[request(
    method = "_goose/unstable/session/extensions/add",
    response = EmptyResponse
)]
#[serde(rename_all = "camelCase")]
pub struct AddExtensionRequest {
    pub session_id: String,
    pub extension: GooseExtension,
}

#[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
#[request(
    method = "_goose/unstable/session/extensions/remove",
    response = EmptyResponse
)]
#[serde(rename_all = "camelCase")]
pub struct RemoveExtensionRequest {
    pub session_id: String,
    pub name: String,
}

Session enabled state is represented by membership in the active extension set:

enable  -> session/extensions/add
disable -> session/extensions/remove

Shared Types

use agent_client_protocol::{JsonRpcRequest, JsonRpcResponse};
use agent_client_protocol::schema::McpServer;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum GooseExtension {
    Builtin {
        name: String,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        description: Option<String>,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        display_name: Option<String>,
    },
    Platform {
        name: String,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        description: Option<String>,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        display_name: Option<String>,
    },
    Mcp {
        server: McpServer,
        #[serde(default, rename = "envKeys", skip_serializing_if = "Vec::is_empty")]
        env_keys: Vec<String>,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        description: Option<String>,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        timeout: Option<u64>,
    },
    InlinePython {
        name: String,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        description: Option<String>,
        code: String,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        timeout: Option<u64>,
        #[serde(default, skip_serializing_if = "Vec::is_empty")]
        dependencies: Vec<String>,
    },
    Frontend {
        name: String,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        description: Option<String>,
        #[serde(default, skip_serializing_if = "Vec::is_empty")]
        tools: Vec<serde_json::Value>,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        instructions: Option<String>,
    },
}

#[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct GooseExtensionEntry {
    pub extension: GooseExtension,
    pub enabled: bool,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub config_key: Option<String>,
}

GooseExtension is the extension definition. GooseExtensionEntry wraps a definition with persistent config state.

Notes

MCP Wrapper

The MCP variant wraps ACP McpServer instead of duplicating stdio/http transport schemas:

{
  "type": "mcp",
  "server": {
    "type": "stdio",
    "name": "github",
    "command": "github-mcp-server"
  }
}

envKeys is Goose-specific and supports the desktop flow where secret values are stored separately and only environment variable names are persisted in extension config. ACP McpServer can carry literal environment values, but it does not represent Goose secret references.

Tool Filtering

Goose core has an available_tools allowlist for tool filtering, but this ACP extension lifecycle schema intentionally does not expose it. The desktop UI does not currently edit this field, and extensions created through this ACP schema should default to all tools available.

Ownership and Editing

Server-owned definitions:

• builtin
• platform
• bundled or otherwise server-managed extensions

For these extensions, the server owns identity and implementation metadata. Clients should not edit those fields. Clients may still enable or disable them as user preferences through config/extensions/set-enabled.

User-authored extension configs:

• mcp
• inline_python
• possibly frontend, if persistent frontend extensions are supported

These can be added and updated through config/extensions/add.

Recommended public operation rules:

config/extensions/add:
  allow user-authored mcp / inline_python / frontend
  reject builtin
  reject platform
  reject bundled or server-managed entries

config/extensions/set-enabled:
  allow any listed extension type

config/extensions/remove:
  allow user-authored extensions
  reject builtin
  reject platform
  reject bundled or server-managed entries

The server should enforce these rules. Client-side checks are only UX.

[jamadeo]

This sounds great. It's a good mix of following the protocol and keeping goose-custom functionality.