harivansh-afk/sandbox-agent
1
0
Fork 0
mirror of https://github.com/harivansh-afk/sandbox-agent.git synced 2026-04-15 14:03:52 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
sandbox-agent/research/wip-agent-support.md
NathanFlurry 4c8d93e077
docs: add mcp and skill session config (#106)
2026-02-09 10:13:25 +00:00

17 KiB
Raw Blame History

Universal Agent Configuration Support

Work-in-progress research on configuration features across agents and what can be made universal.

TODO: Features Needed for Full Coverage

Currently Implemented (in CreateSessionRequest)

  • agent - Agent selection (claude, codex, opencode, amp)
  • agentMode - Agent mode (plan, build, default)
  • permissionMode - Permission mode (default, plan, bypass)
  • model - Model selection
  • variant - Reasoning variant
  • agentVersion - Agent version selection
  • mcp - MCP server configuration (Claude/Codex/OpenCode/Amp)
  • skills - Skill path configuration (link or copy into agent skill roots)

Tier 1: Universal Features (High Priority)

  • projectInstructions - Inject CLAUDE.md / AGENTS.md content
    • Write to appropriate file before agent spawn
    • All agents support this natively
  • workingDirectory - Set working directory for session
    • Currently captures server cwd on session creation; not yet user-configurable
  • mcp - MCP server configuration
    • Claude: Writes .mcp.json entries under mcpServers
    • Codex: Updates .codex/config.toml with mcp_servers
    • Amp: Calls amp mcp add for each server
    • OpenCode: Uses /mcp API
  • skills - Skill path configuration
    • Claude: Link to ./.claude/skills/<name>/
    • Codex: Link to ./.agents/skills/<name>/
    • OpenCode: Link to ./.opencode/skill/<name>/ + config skills.paths
    • Amp: Link to Claude/Codex-style directories
  • credentials - Pass credentials via API (not just env vars)
    • Currently extracted from host env
    • Need API-level credential injection

Filesystem API (Implemented)

  • /v1/fs - Read/write/list/move/delete/stat files and upload batches
    • Batch upload is tar-only (application/x-tar) with path output capped at 1024
    • Relative paths resolve from session working dir when sessionId is provided
    • CLI sandbox-agent api fs ... covers all filesystem endpoints

Message Attachments (Implemented)

  • MessageRequest.attachments - Attach uploaded files when sending prompts
    • OpenCode receives file parts; other agents get attachment paths appended to the prompt

Tier 2: Partial Support (Medium Priority)

  • appendSystemPrompt - High-priority system prompt additions
    • Claude: --append-system-prompt flag
    • Codex: developer_instructions config
    • OpenCode: Custom agent definition
    • Amp: Not supported (fallback to projectInstructions)
  • resumeSession / native session resume
    • Claude: --resume SESSION_ID
    • Codex: Thread persistence (automatic)
    • OpenCode: -c/--continue
    • Amp: --continue SESSION_ID

Tier 3: Agent-Specific Pass-through (Low Priority)

  • agentSpecific.claude - Raw Claude options
  • agentSpecific.codex - Raw Codex options (e.g., replaceSystemPrompt)
  • agentSpecific.opencode - Raw OpenCode options (e.g., customAgent)
  • agentSpecific.amp - Raw Amp options (e.g., permissionRules)

Event/Feature Coverage Gaps (from compatibility matrix)

Feature Claude Codex OpenCode Amp Status
Tool Calls —* ✓ ✓ ✓ Claude coming soon
Tool Results —* ✓ ✓ ✓ Claude coming soon
Questions (HITL) —* — ✓ — Only OpenCode
Permissions (HITL) —* — ✓ — Only OpenCode
Images — ✓ ✓ — 2/4 agents
File Attachments — ✓ ✓ — 2/4 agents
Session Lifecycle — ✓ ✓ — 2/4 agents
Reasoning/Thinking — ✓ — — Codex only
Command Execution — ✓ — — Codex only
File Changes — ✓ — — Codex only
MCP Tools ✓ ✓ ✓ ✓ Supported via session MCP config injection
Streaming Deltas — ✓ ✓ — 2/4 agents

* Claude features marked as "coming imminently"

Implementation Order (Suggested)

  1. mcp - Done (session config injection + agent config writers)
  2. skills - Done (session config injection + skill directory linking)
  3. projectInstructions - Highest value, all agents support
  4. appendSystemPrompt - High-priority instructions
  5. workingDirectory - Basic session configuration
  6. resumeSession - Session continuity
  7. credentials - API-level auth injection
  8. agentSpecific - Escape hatch for edge cases

Legend

  • ✅ Native support
  • 🔄 Can be adapted/emulated
  • ❌ Not supported
  • ⚠️ Supported with caveats

1. Instructions & System Prompt

Feature Claude Codex OpenCode Amp Universal?
Project instructions file ✅ CLAUDE.md ✅ AGENTS.md 🔄 Config-based ⚠️ Limited ✅ Yes - write to agent's file
Append to system prompt ✅ --append-system-prompt ✅ developer_instructions 🔄 Custom agent ❌ ⚠️ Partial - 3/4 agents
Replace system prompt ❌ ✅ model_instructions_file 🔄 Custom agent ❌ ❌ No - Codex only
Hierarchical discovery ✅ cwd → root ✅ root → cwd ❌ ❌ ❌ No - Claude/Codex only

Priority Comparison

Agent Priority Order (highest → lowest)
Claude --append-system-prompt > base prompt > CLAUDE.md
Codex AGENTS.md > developer_instructions > base prompt
OpenCode Custom agent prompt > base prompt
Amp Server-controlled (opaque)

Key Differences

Claude: System prompt additions have highest priority. CLAUDE.md is injected as first user message (below system prompt).

Codex: Project instructions (AGENTS.md) have highest priority and can override system prompt. This is the inverse of Claude's model.

2. Permission Modes

Feature Claude Codex OpenCode Amp Universal?
Read-only ✅ plan ✅ read-only 🔄 Rulesets 🔄 Rules ✅ Yes
Write workspace ✅ acceptEdits ✅ workspace-write 🔄 Rulesets 🔄 Rules ✅ Yes
Full bypass ✅ --dangerously-skip-permissions ✅ danger-full-access 🔄 Allow-all ruleset ✅ --dangerously-skip-permissions ✅ Yes
Per-tool rules ❌ ❌ ✅ ✅ ❌ No - OpenCode/Amp only

Universal Mapping

type PermissionMode = "readonly" | "write" | "bypass";

// Maps to:
// Claude: plan | acceptEdits | --dangerously-skip-permissions
// Codex: read-only | workspace-write | danger-full-access
// OpenCode: restrictive ruleset | permissive ruleset | allow-all
// Amp: reject rules | allow rules | dangerouslyAllowAll

3. Agent Modes

Feature Claude Codex OpenCode Amp Universal?
Plan mode ✅ --permission-mode plan 🔄 Prompt prefix ✅ --agent plan 🔄 Mode selection ✅ Yes
Build/execute mode ✅ Default ✅ Default ✅ --agent build ✅ Default ✅ Yes
Chat mode ❌ 🔄 Prompt prefix ❌ ❌ ❌ No - Codex only
Custom agents ❌ ❌ ✅ Config-defined ❌ ❌ No - OpenCode only

4. Model & Variant Selection

Feature Claude Codex OpenCode Amp Universal?
Model selection ✅ --model ✅ -m/--model ✅ -m provider/model ⚠️ --mode (abstracted) ⚠️ Partial
Model discovery API ✅ Anthropic API ✅ model/list RPC ✅ GET /provider ❌ Server-side ⚠️ Partial - 3/4
Reasoning variants ❌ ✅ model_reasoning_effort ✅ --variant ✅ Deep mode levels ⚠️ Partial

5. MCP & Tools

Feature Claude Codex OpenCode Amp Universal?
MCP servers ✅ mcpServers in settings ✅ mcp_servers in config ✅ /mcp API ✅ --toolbox ✅ Yes - inject config
Tool restrictions ❌ ❌ ✅ Per-tool permissions ✅ Permission rules ⚠️ Partial

MCP Config Mapping

Agent Local Server Remote Server
Claude .mcp.json or .claude/settings.json → mcpServers Same, with url
Codex .codex/config.toml → mcp_servers Same schema
OpenCode /mcp API with McpLocalConfig McpRemoteConfig with url, headers
Amp amp mcp add CLI Supports remote with headers

Local MCP servers can be bundled (for example with tsup) and uploaded via the filesystem API, then referenced in the session mcp config to auto-start and serve custom tools.

6. Skills & Extensions

Feature Claude Codex OpenCode Amp Universal?
Skills/plugins ✅ .claude/skills/ ✅ .agents/skills/ ✅ .opencode/skill/ 🔄 Claude-style ✅ Yes - link dirs
Slash commands ✅ .claude/commands/ ✅ Custom prompts (deprecated) ❌ ❌ ⚠️ Partial

Skill Path Mapping

Agent Project Skills User Skills
Claude .claude/skills/<name>/SKILL.md ~/.claude/skills/<name>/SKILL.md
Codex .agents/skills/ ~/.agents/skills/
OpenCode .opencode/skill/, .claude/skills/, .agents/skills/ ~/.config/opencode/skill/
Amp Uses Claude/Codex directories —

7. Session Management

Feature Claude Codex OpenCode Amp Universal?
Resume session ✅ --resume ✅ Thread persistence ✅ -c/--continue ✅ --continue ✅ Yes
Session ID ✅ session_id ✅ thread_id ✅ sessionID ✅ session_id ✅ Yes

8. Human-in-the-Loop

Feature Claude Codex OpenCode Amp Universal?
Permission requests ✅ Events ⚠️ Upfront only ✅ SSE events ❌ Pre-configured ⚠️ Partial
Questions ⚠️ Limited in headless ❌ ✅ Full support ❌ ❌ No - OpenCode best

9. Credentials

Feature Claude Codex OpenCode Amp Universal?
API key env var ✅ ANTHROPIC_API_KEY ✅ OPENAI_API_KEY ✅ Both ✅ ANTHROPIC_API_KEY ✅ Yes
OAuth tokens ✅ ✅ ✅ ✅ ✅ Yes
Config file auth ✅ ~/.claude.json ✅ ~/.codex/auth.json ✅ ~/.local/share/opencode/auth.json ✅ ~/.amp/config.json ✅ Yes - extract per agent

Configuration Files Per Agent

Claude Code

File/Location Purpose
CLAUDE.md Project instructions (hierarchical, cwd → root)
~/.claude/CLAUDE.md Global user instructions
~/.claude/settings.json User settings (permissions, MCP servers, env)
.claude/settings.json Project-level settings
.claude/settings.local.json Local overrides (gitignored)
~/.claude/commands/ Custom slash commands (user-level)
.claude/commands/ Project-level slash commands
~/.claude/skills/ Installed skills
~/.claude/keybindings.json Custom keyboard shortcuts
~/.claude/projects/<hash>/memory/MEMORY.md Auto-memory per project
~/.claude.json Authentication/credentials
~/.claude.json.api API key storage

OpenAI Codex

File/Location Purpose
AGENTS.md Project instructions (hierarchical, root → cwd)
AGENTS.override.md Override file (takes precedence)
~/.codex/AGENTS.md Global user instructions
~/.codex/AGENTS.override.md Global override
~/.codex/config.toml User configuration
.codex/config.toml Project-level configuration
~/.codex/auth.json Authentication/credentials

Key config.toml options:

  • model - Default model
  • developer_instructions - Appended to system prompt
  • model_instructions_file - Replace entire system prompt
  • project_doc_max_bytes - Max AGENTS.md size (default 32KB)
  • project_doc_fallback_filenames - Alternative instruction files
  • mcp_servers - MCP server configuration

OpenCode

File/Location Purpose
~/.local/share/opencode/auth.json Authentication
~/.config/opencode/config.toml User configuration
.opencode/config.toml Project configuration

Amp

File/Location Purpose
~/.amp/config.json Main configuration
~/.config/amp/settings.json Additional settings
.amp/rules.json Project permission rules

Summary: Universalization Tiers

Tier 1: Fully Universal (implement now)

Feature API Notes
Project instructions projectInstructions: string Write to CLAUDE.md / AGENTS.md
Permission mode permissionMode: "readonly" | "write" | "bypass" Map to agent-specific flags
Agent mode agentMode: "plan" | "build" Map to agent-specific mechanisms
Model selection model: string Pass through to agent
Resume session sessionId: string Map to agent's resume flag
Credentials credentials: { apiKey?, oauthToken? } Inject via env vars
MCP servers mcp: McpConfig Write to agent's config (docs drafted)
Skills skills: { paths: string[] } Link to agent's skill dirs (docs drafted)

Tier 2: Partial Support (with fallbacks)

Feature API Notes
Append system prompt appendSystemPrompt: string Falls back to projectInstructions for Amp
Reasoning variant variant: string Ignored for Claude

Tier 3: Agent-Specific (pass-through)

Feature Notes
Replace system prompt Codex only (model_instructions_file)
Per-tool permissions OpenCode/Amp only
Custom agents OpenCode only
Hierarchical file discovery Let agents handle natively

Recommended Universal API

interface UniversalSessionConfig {
  // Tier 1 - Universal
  agent: "claude" | "codex" | "opencode" | "amp";
  model?: string;
  permissionMode?: "readonly" | "write" | "bypass";
  agentMode?: "plan" | "build";
  projectInstructions?: string;
  sessionId?: string;  // For resume
  workingDirectory?: string;
  credentials?: {
    apiKey?: string;
    oauthToken?: string;
  };

  // MCP servers (docs drafted in docs/mcp.mdx)
  mcp?: Record<string, McpServerConfig>;

  // Skills (docs drafted in docs/skills.mdx)
  skills?: {
    paths: string[];
  };

  // Tier 2 - Partial (with fallbacks)
  appendSystemPrompt?: string;
  variant?: string;

  // Tier 3 - Pass-through
  agentSpecific?: {
    claude?: { /* raw Claude options */ };
    codex?: { replaceSystemPrompt?: string; /* etc */ };
    opencode?: { customAgent?: AgentDef; /* etc */ };
    amp?: { permissionRules?: Rule[]; /* etc */ };
  };
}

interface McpServerConfig {
  type: "local" | "remote";
  // Local
  command?: string;
  args?: string[];
  env?: Record<string, string>;
  timeoutMs?: number;
  // Remote
  url?: string;
  headers?: Record<string, string>;
}

Implementation Notes

Priority Inversion Warning

Claude and Codex have inverted priority for project instructions vs system prompt:

  • Claude: --append-system-prompt > base prompt > CLAUDE.md
  • Codex: AGENTS.md > developer_instructions > base prompt

This means:

  • In Claude, system prompt additions override project files
  • In Codex, project files override system prompt additions

When using both appendSystemPrompt and projectInstructions, document this behavior clearly or consider normalizing by only using one mechanism.

File Injection Strategy

For projectInstructions, sandbox-agent should:

  1. Create a temp directory or use session working directory
  2. Write instructions to the appropriate file:
    • Claude: .claude/CLAUDE.md or CLAUDE.md in cwd
    • Codex: .codex/AGENTS.md or AGENTS.md in cwd
    • OpenCode: Config file or environment
    • Amp: Limited - may only influence via context
  3. Start agent in that directory
  4. Agent discovers and loads instructions automatically

MCP Server Injection

For mcp, sandbox-agent should:

  1. Write MCP config to agent's settings file:
    • Claude: .mcp.json or .claude/settings.json → mcpServers key
    • Codex: .codex/config.toml → mcp_servers
    • OpenCode: Call /mcp API
    • Amp: Run amp mcp add or pass via --toolbox
  2. Ensure MCP server binaries are available in PATH
  3. Handle cleanup on session end

Skill Linking

For skills.paths, sandbox-agent should:

  1. For each skill path, symlink or copy to agent's skill directory:
    • Claude: .claude/skills/<name>/
    • Codex: .agents/skills/<name>/
    • OpenCode: Update skills.paths in config
  2. Skill directory must contain SKILL.md
  3. Handle cleanup on session end