coding-agent-adapters 0.2.18 → 0.3.0

package/README.md

@@ -161,6 +161,134 @@ aider.getRecommendedModels({ googleKey: 'AIza...' });
 // { powerful: 'gemini/gemini-3-pro', fast: 'gemini/gemini-3-flash' }
 ```
 
+## Workspace Files & Memory
+
+Each coding agent CLI has its own convention for project-level memory files (instructions the agent reads on startup) and config files. Adapters expose this knowledge so orchestration systems can write context to the correct files before spawning an agent.
+
+### Discovering Workspace Files
+
+```typescript
+import { ClaudeAdapter, AiderAdapter } from 'coding-agent-adapters';
+
+const claude = new ClaudeAdapter();
+claude.getWorkspaceFiles();
+// [
+//   { relativePath: 'CLAUDE.md', type: 'memory', autoLoaded: true, format: 'markdown', ... },
+//   { relativePath: '.claude/settings.json', type: 'config', autoLoaded: true, format: 'json', ... },
+//   { relativePath: '.claude/commands', type: 'config', autoLoaded: false, format: 'markdown', ... },
+// ]
+
+claude.memoryFilePath; // 'CLAUDE.md'
+
+const aider = new AiderAdapter();
+aider.memoryFilePath; // '.aider.conventions.md'
+```
+
+### Per-Adapter File Mappings
+
+| Adapter | Memory File | Config | Other |
+|---------|------------|--------|-------|
+| Claude | `CLAUDE.md` | `.claude/settings.json` | `.claude/commands` |
+| Gemini | `GEMINI.md` | `.gemini/settings.json` | `.gemini/styles` |
+| Codex | `AGENTS.md` | `.codex/config.json` | `codex.md` |
+| Aider | `.aider.conventions.md` | `.aider.conf.yml` | `.aiderignore` |
+
+### Writing Memory Files
+
+Use `writeMemoryFile()` to write instructions into a workspace before spawning an agent. Parent directories are created automatically.
+
+```typescript
+const adapter = new ClaudeAdapter();
+
+// Write to the adapter's default memory file (CLAUDE.md)
+await adapter.writeMemoryFile('/path/to/workspace', `# Project Context
+This is a TypeScript monorepo using pnpm workspaces.
+Always run tests before committing.
+`);
+
+// Append to an existing memory file
+await adapter.writeMemoryFile('/path/to/workspace', '\n## Additional Rules\nUse snake_case.\n', {
+  append: true,
+});
+
+// Write to a custom file (e.g., template-specific context for sub-agents)
+await adapter.writeMemoryFile('/path/to/workspace', '# Task-Specific Context\n...', {
+  fileName: 'TASK_CONTEXT.md',
+});
+```
+
+## Approval Presets
+
+Each coding agent CLI has its own config format for controlling tool permissions. The approval preset system provides 4 named levels that translate to the correct per-CLI config files and CLI flags.
+
+### Preset Levels
+
+| Preset | Description | Auto-approve | Require approval | Blocked |
+|--------|-------------|-------------|-----------------|---------|
+| `readonly` | Read-only. Safe for auditing. | file_read, planning, user_interaction | — | file_write, shell, web, agent |
+| `standard` | Standard dev. Reads + web auto, writes/shell prompt. | file_read, planning, user_interaction, web | file_write, shell, agent | — |
+| `permissive` | File ops auto-approved, shell still prompts. | file_read, file_write, planning, user_interaction, web, agent | shell | — |
+| `autonomous` | Everything auto-approved. Use with sandbox. | all categories | — | — |
+
+### Generating Configs
+
+```typescript
+import { generateApprovalConfig, listPresets, getPresetDefinition } from 'coding-agent-adapters';
+
+// List all available presets
+const presets = listPresets();
+
+// Generate CLI-specific config for a preset
+const config = generateApprovalConfig('claude', 'permissive');
+// {
+//   preset: 'permissive',
+//   cliFlags: [],
+//   workspaceFiles: [{ relativePath: '.claude/settings.json', content: '...', format: 'json' }],
+//   envVars: {},
+//   summary: 'Claude Code: File ops auto-approved, shell still prompts.',
+// }
+
+// Each CLI gets its own config format
+generateApprovalConfig('gemini', 'readonly');   // → .gemini/settings.json + --approval-mode plan
+generateApprovalConfig('codex', 'autonomous');  // → .codex/config.json + --full-auto
+generateApprovalConfig('aider', 'permissive');  // → .aider.conf.yml + --yes-always
+```
+
+### Using Presets with Adapters
+
+When `approvalPreset` is set in `adapterConfig`, the adapter's `getArgs()` automatically appends the correct CLI flags:
+
+```typescript
+const session = await manager.spawn({
+  name: 'sandboxed-agent',
+  type: 'claude',
+  workdir: '/path/to/project',
+  adapterConfig: {
+    anthropicKey: process.env.ANTHROPIC_API_KEY,
+    approvalPreset: 'autonomous',
+  },
+});
+```
+
+You can also write the config files to a workspace manually using `writeApprovalConfig()`:
+
+```typescript
+const adapter = new ClaudeAdapter();
+const writtenFiles = await adapter.writeApprovalConfig('/path/to/workspace', {
+  adapterConfig: { approvalPreset: 'permissive' },
+});
+// writtenFiles: ['/path/to/workspace/.claude/settings.json']
+```
+
+### Per-CLI Output
+
+| CLI | Config File | Key Controls |
+|-----|------------|--------------|
+| Claude Code | `.claude/settings.json` | `permissions.allow`, `permissions.deny`, `sandbox.*` |
+| Gemini CLI | `.gemini/settings.json` | `general.defaultApprovalMode`, `tools.allowed`, `tools.exclude` |
+| Codex | `.codex/config.json` | `approval_policy`, `sandbox_mode`, `tools.web_search` |
+| Aider | `.aider.conf.yml` | `yes-always`, `no-auto-commits` |
+
 ## Preflight Check
 
 Before spawning agents, check if the required CLIs are installed:
@@ -218,12 +346,18 @@ Extend `BaseCodingAdapter` to create adapters for other coding CLIs:
 
 ```typescript
 import { BaseCodingAdapter } from 'coding-agent-adapters';
+import type { AgentFileDescriptor, InstallationInfo, ModelRecommendations } from 'coding-agent-adapters';
 import type { SpawnConfig, ParsedOutput, LoginDetection, AutoResponseRule } from 'pty-manager';
 
 export class CursorAdapter extends BaseCodingAdapter {
   readonly adapterType = 'cursor';
   readonly displayName = 'Cursor';
 
+  readonly installation: InstallationInfo = {
+    command: 'npm install -g cursor-cli',
+    docsUrl: 'https://cursor.sh/docs',
+  };
+
   // Set to false if the CLI uses text prompts instead of TUI menus
   override readonly usesTuiMenus = false;
 
@@ -231,6 +365,16 @@ export class CursorAdapter extends BaseCodingAdapter {
     { pattern: /accept terms/i, type: 'tos', response: 'y', responseType: 'text', description: 'Accept TOS', safe: true, once: true },
   ];
 
+  getWorkspaceFiles(): AgentFileDescriptor[] {
+    return [
+      { relativePath: '.cursor/rules', description: 'Project rules', autoLoaded: true, type: 'memory', format: 'markdown' },
+    ];
+  }
+
+  getRecommendedModels(): ModelRecommendations {
+    return { powerful: 'claude-sonnet-4', fast: 'gpt-4o-mini' };
+  }
+
   getCommand(): string { return 'cursor'; }
   getArgs(config: SpawnConfig): string[] { return ['--cli']; }
   getEnv(config: SpawnConfig): Record<string, string> { return {}; }

package/dist/index.cjs

@@ -4,6 +4,362 @@ var promises = require('fs/promises');
 var path = require('path');
 var ptyManager = require('pty-manager');
 
+// src/base-coding-adapter.ts
+
+// src/approval-presets.ts
+var TOOL_CATEGORIES = [
+  { category: "file_read", risk: "low", description: "Read files, search, list directories" },
+  { category: "file_write", risk: "medium", description: "Write, edit, and create files" },
+  { category: "shell", risk: "high", description: "Execute shell commands" },
+  { category: "web", risk: "medium", description: "Web search and fetch" },
+  { category: "agent", risk: "medium", description: "Spawn sub-agents, skills, MCP tools" },
+  { category: "planning", risk: "low", description: "Task planning and todo management" },
+  { category: "user_interaction", risk: "low", description: "Ask user questions" }
+];
+var PRESET_DEFINITIONS = [
+  {
+    preset: "readonly",
+    description: "Read-only. Safe for auditing.",
+    autoApprove: ["file_read", "planning", "user_interaction"],
+    requireApproval: [],
+    blocked: ["file_write", "shell", "web", "agent"]
+  },
+  {
+    preset: "standard",
+    description: "Standard dev. Reads + web auto, writes/shell prompt.",
+    autoApprove: ["file_read", "planning", "user_interaction", "web"],
+    requireApproval: ["file_write", "shell", "agent"],
+    blocked: []
+  },
+  {
+    preset: "permissive",
+    description: "File ops auto-approved, shell still prompts.",
+    autoApprove: ["file_read", "file_write", "planning", "user_interaction", "web", "agent"],
+    requireApproval: ["shell"],
+    blocked: []
+  },
+  {
+    preset: "autonomous",
+    description: "Everything auto-approved. Use with sandbox.",
+    autoApprove: ["file_read", "file_write", "shell", "web", "agent", "planning", "user_interaction"],
+    requireApproval: [],
+    blocked: []
+  }
+];
+var CLAUDE_TOOL_CATEGORIES = {
+  // file_read
+  Read: "file_read",
+  Grep: "file_read",
+  Glob: "file_read",
+  LS: "file_read",
+  NotebookRead: "file_read",
+  // file_write
+  Write: "file_write",
+  Edit: "file_write",
+  // shell
+  Bash: "shell",
+  BashOutput: "shell",
+  KillShell: "shell",
+  // web
+  WebSearch: "web",
+  WebFetch: "web",
+  // agent
+  Task: "agent",
+  Skill: "agent",
+  // planning
+  TodoWrite: "planning",
+  // user_interaction
+  AskUserQuestion: "user_interaction"
+};
+var GEMINI_TOOL_CATEGORIES = {
+  // file_read
+  read_file: "file_read",
+  read_many_files: "file_read",
+  list_directory: "file_read",
+  glob: "file_read",
+  search_file_content: "file_read",
+  // file_write
+  write_file: "file_write",
+  replace: "file_write",
+  // shell
+  run_shell_command: "shell",
+  // web
+  web_fetch: "web",
+  google_web_search: "web",
+  // agent
+  activate_skill: "agent",
+  get_internal_docs: "agent",
+  // planning
+  save_memory: "planning",
+  write_todos: "planning",
+  // user_interaction
+  ask_user: "user_interaction"
+};
+var CODEX_TOOL_CATEGORIES = {
+  // shell (codex uses shell for most operations)
+  exec_command: "shell",
+  write_stdin: "shell",
+  shell_command: "shell",
+  // file_write
+  apply_patch: "file_write",
+  // file_read
+  grep_files: "file_read",
+  read_file: "file_read",
+  list_dir: "file_read",
+  // web
+  web_search: "web",
+  view_image: "web",
+  // agent
+  spawn_agent: "agent",
+  send_input: "agent",
+  resume_agent: "agent",
+  wait: "agent",
+  close_agent: "agent",
+  // planning
+  update_plan: "planning",
+  // user_interaction
+  request_user_input: "user_interaction"
+};
+var AIDER_COMMAND_CATEGORIES = {
+  // file_read
+  "/read-only": "file_read",
+  "/ls": "file_read",
+  "/map": "file_read",
+  "/map-refresh": "file_read",
+  "/tokens": "file_read",
+  "/diff": "file_read",
+  "/context": "file_read",
+  // file_write
+  "/add": "file_write",
+  "/drop": "file_write",
+  "/edit": "file_write",
+  "/code": "file_write",
+  "/architect": "file_write",
+  "/undo": "file_write",
+  // shell
+  "/run": "shell",
+  "/test": "shell",
+  "/lint": "shell",
+  "/git": "shell",
+  // web
+  "/web": "web",
+  // planning
+  "/ask": "planning",
+  // user_interaction
+  "/voice": "user_interaction",
+  "/help": "user_interaction",
+  // config/other
+  "/model": "planning",
+  "/settings": "planning",
+  "/commit": "file_write",
+  "/clear": "planning",
+  "/reset": "planning"
+};
+function getToolsForCategories(mapping, categories) {
+  return Object.entries(mapping).filter(([, cat]) => categories.includes(cat)).map(([tool]) => tool);
+}
+function generateClaudeApprovalConfig(preset) {
+  const def = getPresetDefinition(preset);
+  const allowTools = getToolsForCategories(CLAUDE_TOOL_CATEGORIES, def.autoApprove);
+  const denyTools = getToolsForCategories(CLAUDE_TOOL_CATEGORIES, def.blocked);
+  const settings = {
+    permissions: {}
+  };
+  const permissions = settings.permissions;
+  if (allowTools.length > 0) {
+    permissions.allow = allowTools;
+  }
+  if (denyTools.length > 0) {
+    permissions.deny = denyTools;
+  }
+  if (preset === "autonomous") {
+    settings.sandbox = {
+      enabled: true,
+      autoAllowBashIfSandboxed: true
+    };
+  }
+  const cliFlags = [];
+  if (preset === "autonomous") {
+    const allTools = Object.keys(CLAUDE_TOOL_CATEGORIES);
+    cliFlags.push("--tools", allTools.join(","));
+  }
+  return {
+    preset,
+    cliFlags,
+    workspaceFiles: [
+      {
+        relativePath: ".claude/settings.json",
+        content: JSON.stringify(settings, null, 2),
+        format: "json"
+      }
+    ],
+    envVars: {},
+    summary: `Claude Code: ${def.description}`
+  };
+}
+function generateGeminiApprovalConfig(preset) {
+  const def = getPresetDefinition(preset);
+  const cliFlags = [];
+  const allowedTools = getToolsForCategories(GEMINI_TOOL_CATEGORIES, def.autoApprove);
+  const excludeTools = getToolsForCategories(GEMINI_TOOL_CATEGORIES, def.blocked);
+  let approvalMode;
+  switch (preset) {
+    case "readonly":
+      approvalMode = "plan";
+      cliFlags.push("--approval-mode", "plan");
+      break;
+    case "standard":
+      approvalMode = "default";
+      break;
+    case "permissive":
+      approvalMode = "auto_edit";
+      cliFlags.push("--approval-mode", "auto_edit");
+      break;
+    case "autonomous":
+      approvalMode = "auto_edit";
+      cliFlags.push("-y");
+      break;
+  }
+  const settings = {
+    general: {
+      defaultApprovalMode: approvalMode
+    },
+    tools: {}
+  };
+  const tools = settings.tools;
+  if (allowedTools.length > 0) {
+    tools.allowed = allowedTools;
+  }
+  if (excludeTools.length > 0) {
+    tools.exclude = excludeTools;
+  }
+  return {
+    preset,
+    cliFlags,
+    workspaceFiles: [
+      {
+        relativePath: ".gemini/settings.json",
+        content: JSON.stringify(settings, null, 2),
+        format: "json"
+      }
+    ],
+    envVars: {},
+    summary: `Gemini CLI: ${def.description}`
+  };
+}
+function generateCodexApprovalConfig(preset) {
+  const cliFlags = [];
+  let approvalPolicy;
+  let sandboxMode;
+  let webSearch;
+  switch (preset) {
+    case "readonly":
+      approvalPolicy = "untrusted";
+      sandboxMode = "workspace-read";
+      webSearch = false;
+      cliFlags.push("--sandbox", "workspace-read", "-a", "untrusted");
+      break;
+    case "standard":
+      approvalPolicy = "on-failure";
+      sandboxMode = "workspace-write";
+      webSearch = true;
+      cliFlags.push("--sandbox", "workspace-write");
+      break;
+    case "permissive":
+      approvalPolicy = "on-request";
+      sandboxMode = "workspace-write";
+      webSearch = true;
+      cliFlags.push("-a", "on-request");
+      break;
+    case "autonomous":
+      approvalPolicy = "never";
+      sandboxMode = "workspace-write";
+      webSearch = true;
+      cliFlags.push("--full-auto");
+      break;
+  }
+  const config = {
+    approval_policy: approvalPolicy,
+    sandbox_mode: sandboxMode,
+    tools: {
+      web_search: webSearch
+    }
+  };
+  return {
+    preset,
+    cliFlags,
+    workspaceFiles: [
+      {
+        relativePath: ".codex/config.json",
+        content: JSON.stringify(config, null, 2),
+        format: "json"
+      }
+    ],
+    envVars: {},
+    summary: `Codex: ${getPresetDefinition(preset).description}`
+  };
+}
+function generateAiderApprovalConfig(preset) {
+  const def = getPresetDefinition(preset);
+  const cliFlags = [];
+  const lines = [];
+  switch (preset) {
+    case "readonly":
+      lines.push("yes-always: false");
+      lines.push("no-auto-commits: true");
+      cliFlags.push("--no-auto-commits");
+      break;
+    case "standard":
+      lines.push("yes-always: false");
+      break;
+    case "permissive":
+      lines.push("yes-always: true");
+      cliFlags.push("--yes-always");
+      break;
+    case "autonomous":
+      lines.push("yes-always: true");
+      cliFlags.push("--yes-always");
+      break;
+  }
+  return {
+    preset,
+    cliFlags,
+    workspaceFiles: [
+      {
+        relativePath: ".aider.conf.yml",
+        content: lines.join("\n") + "\n",
+        format: "yaml"
+      }
+    ],
+    envVars: {},
+    summary: `Aider: ${def.description}`
+  };
+}
+function generateApprovalConfig(adapterType, preset) {
+  switch (adapterType) {
+    case "claude":
+      return generateClaudeApprovalConfig(preset);
+    case "gemini":
+      return generateGeminiApprovalConfig(preset);
+    case "codex":
+      return generateCodexApprovalConfig(preset);
+    case "aider":
+      return generateAiderApprovalConfig(preset);
+    default:
+      throw new Error(`Unknown adapter type: ${adapterType}`);
+  }
+}
+function listPresets() {
+  return [...PRESET_DEFINITIONS];
+}
+function getPresetDefinition(preset) {
+  const def = PRESET_DEFINITIONS.find((d) => d.preset === preset);
+  if (!def) {
+    throw new Error(`Unknown preset: ${preset}`);
+  }
+  return def;
+}
+
 // src/base-coding-adapter.ts
 var BaseCodingAdapter = class extends ptyManager.BaseCLIAdapter {
   /**
@@ -114,6 +470,40 @@ Docs: ${this.installation.docsUrl}`
     content = content.trim();
     return content;
   }
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Approval Presets
+  // ─────────────────────────────────────────────────────────────────────────────
+  /**
+   * Extract the approval preset from a spawn config, if set.
+   */
+  getApprovalPreset(config) {
+    const adapterConfig = config.adapterConfig;
+    return adapterConfig?.approvalPreset;
+  }
+  /**
+   * Generate the approval config for this adapter, if a preset is set.
+   */
+  getApprovalConfig(config) {
+    const preset = this.getApprovalPreset(config);
+    if (!preset) return null;
+    return generateApprovalConfig(this.adapterType, preset);
+  }
+  /**
+   * Write approval config files to a workspace directory.
+   * Returns the list of files written (absolute paths).
+   */
+  async writeApprovalConfig(workspacePath, config) {
+    const approvalConfig = this.getApprovalConfig(config);
+    if (!approvalConfig) return [];
+    const written = [];
+    for (const file of approvalConfig.workspaceFiles) {
+      const fullPath = path.join(workspacePath, file.relativePath);
+      await promises.mkdir(path.dirname(fullPath), { recursive: true });
+      await promises.writeFile(fullPath, file.content, "utf-8");
+      written.push(fullPath);
+    }
+    return written;
+  }
   /**
    * Write content to this agent's memory file in a workspace.
    * Creates parent directories as needed.
@@ -248,6 +638,10 @@ var ClaudeAdapter = class extends BaseCodingAdapter {
         args.push("--cwd", config.workdir);
       }
     }
+    const approvalConfig = this.getApprovalConfig(config);
+    if (approvalConfig) {
+      args.push(...approvalConfig.cliFlags);
+    }
     return args;
   }
   getEnv(config) {
@@ -480,6 +874,10 @@ var GeminiAdapter = class extends BaseCodingAdapter {
         args.push("--cwd", config.workdir);
       }
     }
+    const approvalConfig = this.getApprovalConfig(config);
+    if (approvalConfig) {
+      args.push(...approvalConfig.cliFlags);
+    }
     return args;
   }
   getEnv(config) {
@@ -784,6 +1182,10 @@ var CodexAdapter = class extends BaseCodingAdapter {
         args.push("--cwd", config.workdir);
       }
     }
+    const approvalConfig = this.getApprovalConfig(config);
+    if (approvalConfig) {
+      args.push(...approvalConfig.cliFlags);
+    }
     return args;
   }
   getEnv(config) {
@@ -1219,6 +1621,10 @@ var AiderAdapter = class extends BaseCodingAdapter {
     if (credentials.anthropicKey) args.push("--api-key", `anthropic=${credentials.anthropicKey}`);
     if (credentials.openaiKey) args.push("--api-key", `openai=${credentials.openaiKey}`);
     if (credentials.googleKey) args.push("--api-key", `gemini=${credentials.googleKey}`);
+    const approvalConfig = this.getApprovalConfig(config);
+    if (approvalConfig) {
+      args.push(...approvalConfig.cliFlags);
+    }
     return args;
   }
   getEnv(config) {
@@ -1575,18 +1981,31 @@ async function printMissingAdapters(types) {
 }
 
 exports.ADAPTER_TYPES = ADAPTER_TYPES;
+exports.AIDER_COMMAND_CATEGORIES = AIDER_COMMAND_CATEGORIES;
 exports.AiderAdapter = AiderAdapter;
 exports.BaseCodingAdapter = BaseCodingAdapter;
+exports.CLAUDE_TOOL_CATEGORIES = CLAUDE_TOOL_CATEGORIES;
+exports.CODEX_TOOL_CATEGORIES = CODEX_TOOL_CATEGORIES;
 exports.ClaudeAdapter = ClaudeAdapter;
 exports.CodexAdapter = CodexAdapter;
+exports.GEMINI_TOOL_CATEGORIES = GEMINI_TOOL_CATEGORIES;
 exports.GeminiAdapter = GeminiAdapter;
+exports.PRESET_DEFINITIONS = PRESET_DEFINITIONS;
+exports.TOOL_CATEGORIES = TOOL_CATEGORIES;
 exports.checkAdapters = checkAdapters;
 exports.checkAllAdapters = checkAllAdapters;
 exports.clearPatternCache = clearPatternCache;
 exports.createAdapter = createAdapter;
 exports.createAllAdapters = createAllAdapters;
+exports.generateAiderApprovalConfig = generateAiderApprovalConfig;
+exports.generateApprovalConfig = generateApprovalConfig;
+exports.generateClaudeApprovalConfig = generateClaudeApprovalConfig;
+exports.generateCodexApprovalConfig = generateCodexApprovalConfig;
+exports.generateGeminiApprovalConfig = generateGeminiApprovalConfig;
 exports.getBaselinePatterns = getBaselinePatterns;
+exports.getPresetDefinition = getPresetDefinition;
 exports.hasDynamicPatterns = hasDynamicPatterns;
+exports.listPresets = listPresets;
 exports.loadPatterns = loadPatterns;
 exports.loadPatternsSync = loadPatternsSync;
 exports.preloadAllPatterns = preloadAllPatterns;