Feature request: adapter hook between connect_and_authenticate() and _establish_session()

[georgeharker]

I'm building mcp-companion, a Neovim plugin that runs a local MCP bridge server and injects it into ACP sessions so that agents like opencode/copilot get access to additional MCP tools (project context, custom tools, etc.), including mcp over http and oauth support.

The ACP spec explicitly supports this pattern — from the Session Setup docs:

Clients MAY use this ability to provide tools directly to the underlying language model by including their own MCP server.

The bridge entry needs to be added to adapter_modified.defaults.mcpServers before session/new is sent. However, the transport type (HTTP vs stdio/mcp-remote) depends on the agent's mcpCapabilities.http capability, which is only available from _agent_info after the INITIALIZE RPC completes.

The problem

There's currently no hook point between authentication completing (when _agent_info is populated) and session creation (when mcpServers is read). The lifecycle looks like:

connect_and_authenticate()
  → start_agent_process()
    → prepare_adapter()        ← adapter_modified created
    → handlers.setup(adapter)  ← too early, no _agent_info yet
    → spawn process
  → INITIALIZE RPC             ← _agent_info now available
  → _authenticate()
                               ← Ideally there would be a hook here
_establish_session()
  → reads adapter_modified.defaults.mcpServers
  → sends session/new

The handlers.setup callback runs before INITIALIZE, so it can't inspect _agent_info. There's no User event fired between authentication and session creation either.

Current workaround

I'm monkey-patching Connection._establish_session on the prototype to inject the bridge entry just before the original runs:

https://github.com/georgeharker/mcp-companion/blob/main/lua/mcp_companion/cc/init.lua#L249-L312

This works but it's fragile — it depends on internal method signatures and adapter_modified structure.

Proposed solution

A before_session adapter handler, called after connect_and_authenticate() succeeds but before _establish_session() runs. It would receive the Connection instance (which has _agent_info populated):

-- In connect_and_initialize(), between lines 167-171:
function Connection:connect_and_initialize()
  if self:is_connected() then return self end
  if not self:connect_and_authenticate() then return nil end

  -- NEW: allow adapters/extensions to modify session params
  if self.adapter_modified.handlers
      and self.adapter_modified.handlers.before_session then
    self.adapter_modified.handlers.before_session(self)
  end

  if not self:_establish_session() then return nil end
  self:apply_default_model()
  self:apply_default_mode()
  return self
end

The same hook would be needed in ensure_session() (~line 240) for the reconnection path.

Alternatively, a User event like CodeCompanionACPSessionPre fired at this point would also work and would be more general-purpose — any extension could listen for it. Ideally it would have mutable access to the modified adapter to be able to ensure that mcps got inserted there.

Use case

With this hook, mcp-companion could cleanly:

1. Read conn._agent_info.agentCapabilities.mcpCapabilities.http to determine transport
2. Build the appropriate MCP server entry (HTTP or stdio)
3. Insert it into conn.adapter_modified.defaults.mcpServers

No monkey-patching required.

Alternative

if default mcpServers could be specified as an http vs stdio list, then the acp setup machinery itself could decide which list to send to the other side, and I'd just populate both with the relevant defaults.

Any thoughts on a clean implementation?

[olimorris]

Absolutely down for this. Always keen to make tweaks to CodeCompanion to better enable extensions.

An event is more in keeping with how CodeCompanion allows external plugins to interact, so that would be my preference. CodeCompanionChatACPSessionPre seems reasonable to me to fit in with the other events.

[georgeharker]

Great! Thanks Oli!

Would you like me to sketch a PR?

George

[olimorris]

Yes please do and I'll make sure I prioritise it.

[georgeharker]

Created #2938