coding-agent-adapters 0.2.19 → 0.4.0

package/README.md

@@ -94,6 +94,27 @@ Adapters detect prompts that block the session and require user action:
 | Codex | Directory trust, tool approval, update available, model migration, CWD selection |
 | Aider | File operations, shell commands, git init, pip install, destructive operations |
 
+### Task Completion Detection
+
+Each adapter implements `detectTaskComplete(output)` to recognize when the CLI has finished a task and returned to its idle prompt. This is more specific than `detectReady()` — it matches high-confidence completion indicators (duration summaries, explicit done messages) that short-circuit the LLM stall classifier in pty-manager.
+
+| Adapter | Completion Indicators | Source Patterns |
+|---------|----------------------|----------------|
+| Claude | Turn duration (`Cooked for 3m 12s`, custom verb) + `❯` prompt | `claude_completed_turn_duration` |
+| Gemini | `◇ Ready` window title, `Type your message` composer | `gemini_ready_title` |
+| Codex | `Worked for 1m 05s` separator + `›` prompt | `codex_completed_worked_for_separator`, `codex_ready_prompt` |
+| Aider | `Aider is waiting for your input`, mode prompts with edit/cost markers | `aider_completed_llm_response_ready` |
+
+```typescript
+const claude = new ClaudeAdapter();
+claude.detectTaskComplete('Cooked for 3m 12s\n❯ ');  // true
+claude.detectTaskComplete('Reading 5 files…');         // false
+
+const aider = new AiderAdapter();
+aider.detectTaskComplete('Applied edit to main.ts\nTokens: 1234\ncode> ');  // true
+aider.detectTaskComplete('Waiting for claude-sonnet-4-20250514');            // false
+```
+
 ### Exit Detection
 
 Adapters detect when a CLI session has ended:
@@ -217,6 +238,78 @@ await adapter.writeMemoryFile('/path/to/workspace', '# Task-Specific Context\n..
 });
 ```
 
+## 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:
@@ -318,6 +411,11 @@ export class CursorAdapter extends BaseCodingAdapter {
     return /cursor>\s*$/m.test(output);
   }
 
+  detectTaskComplete(output: string): boolean {
+    // High-confidence: task summary + idle prompt
+    return /completed in \d+s/.test(output) && /cursor>\s*$/m.test(output);
+  }
+
   parseOutput(output: string): ParsedOutput | null {
     return { type: 'response', content: output.trim(), isComplete: true, isQuestion: output.includes('?') };
   }