sandbox-agent/research/wip-agent-support.md

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