Skip to content

acp-agents.md

Latest commit

 

History

History
108 lines (84 loc) · 4.15 KB

acp-agents.md

File metadata and controls

108 lines (84 loc) · 4.15 KB
Raw

ACP Agents

Expose external Agent Client Protocol agents as optional OpenCode subagents.

Use this when you want the orchestrator to delegate to software-connected tools such as Claude Code ACP, Gemini ACP, or another ACP-compatible coding agent.

How it works

Each acpAgents entry creates a lightweight wrapper subagent. The wrapper can only call acp_run, which:

  1. Starts the configured ACP subprocess over stdio.
  2. Sends initialize.
  3. Creates a session with session/new.
  4. Sends the task with session/prompt.
  5. Collects session/update agent_message_chunk text.
  6. Returns the external agent's final output to OpenCode.

The wrapper is sandboxed from normal local tools such as bash, edit, task, webfetch, grep, and glob.

Configuration

Add acpAgents to ~/.config/opencode/oh-my-opencode-slim.jsonc or a project-local .opencode/oh-my-opencode-slim.jsonc file:

{
  "acpAgents": {
    "claude-research": {
      "command": "claude-code-acp",
      "args": [],
      "description": "Claude Code subscription agent for deep research",
      "wrapperModel": "openai/gpt-5.6-luna",
      "permissionMode": "ask",
      "timeoutMs": 300000
    },
    "gemini-acp": {
      "command": "gemini",
      "args": ["--experimental-acp"],
      "description": "Gemini CLI through ACP"
    }
  }
}

Restart OpenCode after changing config. Then call the generated agent directly:

@claude-research investigate this bug and summarize the likely cause

Or let the orchestrator delegate to it when its routing prompt matches the task.

Options

Option Type Default Description
command string - ACP executable. Put flags in args, not here.
args string[] [] Arguments for the ACP command.
env object {} Extra environment variables for the subprocess.
cwd string current session directory Working directory override. ACP paths should be absolute.
description string generated Role text shown to OpenCode and the orchestrator.
prompt string generated Full prompt for the wrapper subagent. Usually unnecessary.
orchestratorPrompt string generated Exact routing block injected into the orchestrator prompt.
wrapperModel string fixer default Cheap OpenCode model used by the wrapper.
permissionMode ask | allow | reject ask How ACP permission requests are answered.
timeoutMs integer 300000 Timeout for one ACP run.

permission vs permissionMode: These are separate concepts.

  • permission (on normal custom, built-in, and preset agents) provides SDK-enforced, expressive per-tool rules with pattern support, accepting ask/allow/deny. See Agent Permissions.
  • permissionMode (ACP agents only) controls how the plugin answers the external ACP subprocess's permission requests, with simpler ask/allow/reject options.

Authentication

ACP agents may advertise authMethods during initialization and may require authentication before session/new. The bridge attempts the first advertised auth method if the agent reports an auth-required error.

Some agents still require manual setup first. For example, run the external agent's login command in your terminal before using the wrapper:

claude /login

Use the command required by your ACP server.

Safety notes

  • The plugin asks before launching the configured subprocess.
  • The wrapper agent can only call acp_run.
  • acp_run can only be called by the matching wrapper agent.
  • External ACP agents may still run their own tools depending on their own implementation and permission flow.
  • Keep secrets in environment variables and pass only the minimum needed via env.

Troubleshooting

  • Agent not available: restart OpenCode after editing config.
  • Unknown ACP agent: check that the acpAgents key name matches your @agent name.
  • Auth required: run the ACP agent's login/auth setup command directly.
  • No output: verify the command works as an ACP server in a terminal or ACP client.