External Agent Plugin

The External Agent plugin lets the main agent delegate work to external coding-agent CLIs — Claude Code, Codex, OpenCode, Gemini — or to a peer Codumentor instance, each running unattended in a sandbox. Every configured backend becomes its own tool (claude_code, codex, …) that takes a task description and returns the external agent's result, with its live transcript shown in a UI card.

Configuration

plugins:
  - module: codumentor.plugins.external_agent
    class: ExternalAgentPlugin
    args:
      enabled: true
      default_sandbox_tier: 0      # 0 = bare subprocess, 1 = bwrap overlay
      target_agents: "main"
      backends:
        claude-code:
          binary: claude
          mode: technical_user     # see "Auth modes" below
          # api_key omitted → use the Claude CLI's own auth store in $HOME
        codex:
          binary: codex
          mode: technical_user

Parameters

• enabled (optional): Whether the plugin is active (default: true)
• target_agents (optional): Which agents receive the backend tools (default: "main")
• default_sandbox_tier (optional): Default isolation level for all backends (default: 0)
• 0 — bare subprocess
• 1 — bubblewrap (bwrap) overlay sandbox with optional resource limits and network egress allow-listing
• default_limits (optional): Global resource limits (memory_max_bytes, wall_clock_seconds) applied unless a backend overrides them
• backends (required): Map of backend name → backend config. Each entry accepts:
• binary: executable name (defaults per backend: claude, codex, opencode, gemini)
• mode: authentication mode (see below)
• api_key: credential, supporting ${env:VAR} / ${secret:NAME} placeholders; omit to fall back to the CLI's own auth store in $HOME
• allowed_egress (tier 1): hostnames the backend may reach
• limits: per-backend resource-limit override
• base_url (Codumentor backend only): peer instance URL

Auth modes

• technical_user — a single deployer-provided credential (from api_key, or the CLI's $HOME auth store) shared by all callers.
• byo_key — each user supplies their own API key via User Secrets.
• byo_subscription — each user authenticates their own CLI subscription (OAuth) into a per-user $HOME.

Tool Reference

One tool is registered per configured backend:

Tool	Backend
claude_code	Anthropic Claude Code CLI
codex	OpenAI Codex CLI
opencode	OpenCode CLI
gemini	Google Gemini CLI (no session resume)
codumentor	A peer Codumentor instance over HTTP (base_url)

Each tool takes a query (the task) and an optional subagent_id to resume a previous session with that backend.

Notes

• Sandbox tiers: tier 0 runs the CLI as a plain subprocess; tier 1 wraps it in a bwrap overlay (copy-on-write, repo read-only) and can enforce memory/wall-clock limits (via systemd-run --user) and a network egress allow-list. Tier 1 requires bubblewrap (and, for limits, user-level systemd).
• Credentials are never shown to the agent — they are resolved at spawn time from the configured mode. A call is rejected (not spawned) if no credential resolves.
• Permissions: one user approval covers a whole external-agent invocation, not each internal step the external agent takes.
• A per-user settings widget lets users manage their own BYO keys; a transcript card streams the external agent's messages, tool calls, thinking, and token counts.