External Agent

Lets the main agent delegate work to external coding-agent CLIs — Claude Code, Codex, OpenCode, Gemini — or to a peer Codumentor instance. Each configured backend becomes its own tool (claude_code, codex, …). The live transcript appears in a UI card.

The user approves once per invocation, not each step the external agent takes inside its run. Credentials are never shown to the LLM.

External-agent tools are offered only when the caller's access profile grants every repository.

Configuration

plugins:
  - module: codumentor.plugins.external_agent
    class: ExternalAgentPlugin
    args:
      enabled: true
      # default_sandbox_tier: 1   # omit to auto-pick (see below)
      target_agents: "main"
      backends:
        claude-code:
          binary: claude
          mode: technical_user
          # api_key omitted → CLI's own auth store in $HOME
        codex:
          binary: codex
          mode: technical_user

Parameters

enabled (optional, default true).
target_agents (optional, default "main"): "main", "subagent", or "all".
default_sandbox_tier (optional): Isolation for CLI backends.
omit (default) — auto: tier 1 when Workspace Isolation is active, otherwise tier 0.
0 — bare subprocess on the host. Explicit 0 while workspace isolation is on is a downgrade (logged as a warning).
1 — bubblewrap overlay (copy-on-write, repo read-only), optional memory/wall-clock limits and a network allow-list. Needs bubblewrap; limits also need user-level systemd.
default_limits (optional): memory_max_bytes, wall_clock_seconds unless a backend overrides them.
backends (required): Map of backend name → settings. Known names: claude-code, codex, opencode, gemini, codumentor.

Each backend entry may include:

binary: Executable (defaults: claude, codex, opencode, gemini).
mode: technical_user, byo_key, or byo_subscription (see below).
api_key: Credential. Supports ${env:VAR} and ${secret:NAME}. Omit to use the CLI's own $HOME auth store.
extra_env: Extra environment variables for the subprocess (e.g. proxies).
allowed_egress (tier 1): Hostnames the backend may reach. If omitted, a small per-backend default (vendor APIs) is used. [] means no network.
limits: Per-backend override of default_limits.
expose_mcp_tools: Optional list of Codumentor tools the external agent may call: memory_store, memory_search, read_file, list_files. Empty (default) exposes none.
base_url (codumentor backend only): Peer instance URL.

Auth modes

technical_user — one deployer credential (api_key, or the CLI login in host $HOME) shared by all callers.
byo_key — each user supplies an API key via User Secrets. The settings panel is for those keys.
byo_subscription — each user logs their own CLI subscription (OAuth) into a per-user $HOME.

A call is rejected (not spawned) if no credential resolves.

Install the CLI, log in on the host (claude /login, codex login, …), omit api_key, and keep mode: technical_user (or byo_subscription for per-user stores).

Under sandbox tier 1 the agent does not see host $HOME. Known auth paths are copied into the session home at spawn:

~/.claude/.credentials.json, ~/.claude.json
~/.codex/, ~/.config/codex
~/.config/claude, ~/.config/claude-code
~/.config/github-copilot

If a CLI stores login somewhere else, the sandboxed run can fail with auth_required even though the host CLI works. The copy can refresh OAuth in the sandbox copy; if the host CLI later reports logged out, log in again on the host (or use byo_subscription).

Tools

One tool per configured backend:

Tool	YAML key	Backend
`claude_code`	`claude-code`	Anthropic Claude Code CLI
`codex`	`codex`	OpenAI Codex CLI
`opencode`	`opencode`	OpenCode CLI
`gemini`	`gemini`	Google Gemini CLI (no native session resume; follow-ups recap in the prompt)
`codumentor`	`codumentor`	Peer Codumentor instance over HTTP (`base_url`)

Each takes query (the task) and optional subagent_id to resume that backend's session (except Gemini, as above).

Notes