From e835f2b29ba728f22a05e520bde0f10086d5b9d3 Mon Sep 17 00:00:00 2001 From: Nathan Flurry Date: Sat, 24 Jan 2026 23:12:41 -0800 Subject: [PATCH] docs: update agent docs with mode/permission info, add amp.md --- research/agents/amp.md | 217 ++++++++++++++++++++++++++++++ research/{ => agents}/claude.md | 38 +++++- research/{ => agents}/codex.md | 21 ++- research/{ => agents}/opencode.md | 55 +++++++- 4 files changed, 317 insertions(+), 14 deletions(-) create mode 100644 research/agents/amp.md rename research/{ => agents}/claude.md (79%) rename research/{ => agents}/codex.md (89%) rename research/{ => agents}/opencode.md (90%) diff --git a/research/agents/amp.md b/research/agents/amp.md new file mode 100644 index 0000000..918f1a3 --- /dev/null +++ b/research/agents/amp.md @@ -0,0 +1,217 @@ +# Amp Research + +Research notes on Sourcegraph Amp's configuration, credential discovery, and runtime behavior. + +## Overview + +- **Provider**: Anthropic (via Sourcegraph) +- **Execution Method**: CLI subprocess (`amp` command) +- **Session Persistence**: Session ID (string) +- **SDK**: `@sourcegraph/amp-sdk` (closed source) +- **Binary Location**: `/usr/local/bin/amp` + +## CLI Usage + +### Interactive Mode +```bash +amp "your prompt here" +amp --model claude-sonnet-4 "your prompt" +``` + +### Non-Interactive Mode +```bash +amp --print --output-format stream-json "your prompt" +amp --print --output-format stream-json --dangerously-skip-permissions "prompt" +amp --continue SESSION_ID "follow up" +``` + +### Key CLI Flags + +| Flag | Description | +|------|-------------| +| `--print` | Output mode (non-interactive) | +| `--output-format stream-json` | JSONL streaming output | +| `--dangerously-skip-permissions` | Skip permission prompts | +| `--continue SESSION_ID` | Resume existing session | +| `--model MODEL` | Specify model | +| `--toolbox TOOLBOX` | Toolbox configuration | + +## Credential Discovery + +### Priority Order + +1. Environment variable: `ANTHROPIC_API_KEY` +2. Sourcegraph authentication +3. Claude Code credentials (shared) + +### Config File Locations + +| Path | Description | +|------|-------------| +| `~/.amp/config.json` | Primary config | +| `~/.claude/.credentials.json` | Shared with Claude Code | + +Amp can use Claude Code's OAuth credentials as fallback. + +## Streaming Response Format + +Amp outputs newline-delimited JSON events: + +```json +{"type": "system", "subtype": "init", "session_id": "...", "tools": [...]} +{"type": "assistant", "message": {...}, "session_id": "..."} +{"type": "user", "message": {...}, "session_id": "..."} +{"type": "result", "subtype": "success", "result": "...", "session_id": "..."} +``` + +### Event Types + +| Type | Description | +|------|-------------| +| `system` | System initialization with tools list | +| `assistant` | Assistant message with content blocks | +| `user` | User message (tool results) | +| `result` | Final result with session ID | + +### Content Block Types + +```typescript +type ContentBlock = + | { type: "text"; text: string } + | { type: "tool_use"; id: string; name: string; input: Record } + | { type: "thinking"; thinking: string } + | { type: "redacted_thinking"; data: string }; +``` + +## Response Schema + +```typescript +interface AmpResultMessage { + type: "result"; + subtype: "success"; + duration_ms: number; + is_error: boolean; + num_turns: number; + result: string; + session_id: string; +} +``` + +## Session Management + +- Session ID captured from streaming events +- Use `--continue SESSION_ID` to resume +- Sessions stored internally by Amp CLI + +## Agent Modes vs Permission Modes + +### Permission Modes (Declarative Rules) + +Amp uses declarative permission rules configured before execution: + +```typescript +interface PermissionRule { + tool: string; // Glob pattern: "Bash", "mcp__playwright__*" + matches?: { [argumentName: string]: string | string[] | boolean }; + action: "allow" | "reject" | "ask" | "delegate"; + context?: "thread" | "subagent"; +} +``` + +| Action | Behavior | +|--------|----------| +| `allow` | Automatically permit | +| `reject` | Automatically deny | +| `ask` | Prompt user (CLI handles internally) | +| `delegate` | Delegate to subagent context | + +### Example Rules + +```typescript +const permissions: PermissionRule[] = [ + { tool: "Read", action: "allow" }, + { tool: "Bash", matches: { command: "git *" }, action: "allow" }, + { tool: "Write", action: "ask" }, + { tool: "mcp__*", action: "reject" } +]; +``` + +### Agent Modes + +No documented agent mode concept. Behavior controlled via: +- `--toolbox` flag for different tool configurations +- Permission rules for capability restrictions + +### Bypass All Permissions + +```bash +amp --dangerously-skip-permissions "prompt" +``` + +Or via SDK: +```typescript +execute(prompt, { dangerouslyAllowAll: true }); +``` + +## Human-in-the-Loop + +### No Interactive HITL API + +While permission rules support `"ask"` action, Amp does not expose an SDK-level API for programmatically responding to permission requests. The CLI handles user interaction internally. + +For universal API integration, Amp should be run with: +- Pre-configured permission rules, or +- `dangerouslyAllowAll: true` to bypass + +## SDK Usage + +```typescript +import { execute, type AmpOptions } from '@sourcegraph/amp-sdk'; + +interface AmpOptions { + cwd?: string; + dangerouslyAllowAll?: boolean; + toolbox?: string; + mcpConfig?: MCPConfig; + permissions?: PermissionRule[]; + continue?: boolean | string; +} + +const result = await execute(prompt, options); +``` + +## Installation + +```bash +# Get latest version +VERSION=$(curl -s https://storage.googleapis.com/amp-public-assets-prod-0/cli/cli-version.txt) + +# Linux x64 +curl -fsSL "https://storage.googleapis.com/amp-public-assets-prod-0/cli/${VERSION}/amp-linux-x64" \ + -o /usr/local/bin/amp && chmod +x /usr/local/bin/amp + +# Linux ARM64 +curl -fsSL "https://storage.googleapis.com/amp-public-assets-prod-0/cli/${VERSION}/amp-linux-arm64" \ + -o /usr/local/bin/amp && chmod +x /usr/local/bin/amp + +# macOS ARM64 +curl -fsSL "https://storage.googleapis.com/amp-public-assets-prod-0/cli/${VERSION}/amp-darwin-arm64" \ + -o /usr/local/bin/amp && chmod +x /usr/local/bin/amp + +# macOS x64 +curl -fsSL "https://storage.googleapis.com/amp-public-assets-prod-0/cli/${VERSION}/amp-darwin-x64" \ + -o /usr/local/bin/amp && chmod +x /usr/local/bin/amp +``` + +## Timeout + +- Default timeout: 5 minutes (300,000 ms) +- Process killed with `SIGTERM` on timeout + +## Notes + +- Amp is similar to Claude Code (same streaming format) +- Can share credentials with Claude Code +- No interactive HITL - must use pre-configured permissions +- SDK is closed source but types are documented +- MCP server integration supported via `mcpConfig` diff --git a/research/claude.md b/research/agents/claude.md similarity index 79% rename from research/claude.md rename to research/agents/claude.md index d3b1e85..d22f4a8 100644 --- a/research/claude.md +++ b/research/agents/claude.md @@ -140,13 +140,39 @@ Claude CLI outputs newline-delimited JSON events: - Default timeout: 5 minutes (300,000 ms) - Process is killed with `SIGTERM` on timeout -## Agent Modes +## Agent Modes vs Permission Modes -| Mode | Behavior | -|------|----------| -| `build` | Default execution mode | -| `plan` | Adds `--permission-mode plan` flag | -| `chat` | Available but no special handling | +Claude conflates agent mode and permission mode - `plan` is a permission restriction that forces planning behavior. + +### Permission Modes + +| Mode | CLI Flag | Behavior | +|------|----------|----------| +| `default` | (none) | Normal permission prompts | +| `acceptEdits` | `--permission-mode acceptEdits` | Auto-accept file edits | +| `plan` | `--permission-mode plan` | Read-only, must ExitPlanMode to execute | +| `bypassPermissions` | `--dangerously-skip-permissions` | Skip all permission checks | + +### Subagent Types + +Claude supports spawning subagents via the `Task` tool with `subagent_type`: +- Custom agents defined in config +- Built-in agents like "Explore", "Plan" + +### ExitPlanMode (Plan Approval) + +When in `plan` permission mode, agent invokes `ExitPlanMode` tool to request execution: + +```typescript +interface ExitPlanModeInput { + allowedPrompts?: Array<{ + tool: "Bash"; + prompt: string; // e.g., "run tests" + }>; +} +``` + +This triggers a user approval event. In the universal API, this is converted to a question event with approve/reject options. ## Error Handling diff --git a/research/codex.md b/research/agents/codex.md similarity index 89% rename from research/codex.md rename to research/agents/codex.md index 19a8ec0..cbb757d 100644 --- a/research/codex.md +++ b/research/agents/codex.md @@ -193,9 +193,22 @@ function getThreadId(thread: unknown): string | null { } ``` -## Agent Modes +## Agent Modes vs Permission Modes -Modes are implemented via prompt prefixing: +Codex separates sandbox levels (permissions) from behavioral modes (prompt prefixes). + +### Permission Modes (Sandbox Levels) + +| Mode | CLI Flag | Behavior | +|------|----------|----------| +| `read-only` | `-s read-only` | No file modifications | +| `workspace-write` | `-s workspace-write` | Can modify workspace files | +| `danger-full-access` | `-s danger-full-access` | Full system access | +| `bypass` | `--dangerously-bypass-approvals-and-sandbox` | Skip all checks | + +### Agent Modes (Prompt Prefixes) + +Codex doesn't have true agent modes - behavior is controlled via prompt prefixing: | Mode | Prompt Prefix | |------|---------------| @@ -215,6 +228,10 @@ function withModePrefix(prompt: string, mode: AgentMode): string { } ``` +### Human-in-the-Loop + +Codex has no interactive HITL in SDK mode. All permissions must be configured upfront via sandbox level. + ## Error Handling - `turn.failed` events are captured but don't throw diff --git a/research/opencode.md b/research/agents/opencode.md similarity index 90% rename from research/opencode.md rename to research/agents/opencode.md index 6bbd6e8..8a19fd2 100644 --- a/research/opencode.md +++ b/research/agents/opencode.md @@ -403,14 +403,57 @@ interface TokenUsage { Available in message `info` field for assistant messages. -## Agent Modes +## Agent Modes vs Permission Modes -| Mode | Agent ID | -|------|----------| -| `build` | `"build"` | -| `plan` | `"plan"` | +OpenCode properly separates these concepts: -Modes map directly to OpenCode agent IDs. +### Agent Modes + +Agents are first-class concepts with their own system prompts and behavior: + +| Agent ID | Description | +|----------|-------------| +| `build` | Default execution agent | +| `plan` | Planning/analysis agent | +| Custom | User-defined agents in config | + +```typescript +// Sending a prompt with specific agent +await client.session.promptAsync({ + body: { + agent: "plan", // or "build", or custom agent ID + parts: [{ type: "text", text: "..." }] + } +}); +``` + +### Listing Available Agents + +```typescript +const agents = await client.app.agents({}); +// Returns: [{ id: "build", name: "Build", primary: true }, ...] +``` + +### Permission Modes + +Permissions are configured via rulesets on the session, separate from agent selection: + +```typescript +interface PermissionRuleset { + // Tool-specific permission rules +} +``` + +### Human-in-the-Loop + +OpenCode has full interactive HITL via SSE events: + +| Event | Endpoint | +|-------|----------| +| `question.asked` | `POST /question/{id}/reply` | +| `permission.asked` | `POST /permission/{id}/reply` | + +See `research/human-in-the-loop.md` for full API details. ## Defaults