execute_subtask
Execute AI prompts using the cheapest provider with automatic fallback. Supports file creation, surgical edits, and convergence retries.
Instructions
Execute a prompt via the cheapest available AI CLI provider.
Routes to the cheapest model for the given tier across all installed CLI tools (GitHub Copilot, Codex, Cursor, and others). Falls back to next cheapest on failure.
When target_file is provided, writes the result directly to that path and returns file metadata. This is the preferred way to create files for low-tier subtasks — saves tokens by avoiding round-trip through the main agent.
Surgical edit modes (set mode=): rewrite (full-file injection + length-ratio guard), blocks (Aider-style SEARCH/REPLACE, token-efficient), patch (unified diff).
Returns:
result: the model's response text
provider: which CLI tool was used
model: which model handled it
tier: the tier that was requested
fallback_used: whether a fallback provider was needed
file_written: path written to (when target_file is set)
lines_written: line count of written file
diff: unified diff showing changes (when target_file is set)
change_type: 'created', 'modified', or 'unchanged'
lines_added: number of lines added
lines_removed: number of lines removed
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Write mode for target_file edits: 'write' (default) — model output written verbatim. Safe for new files. 'rewrite' — injects current file, asks for complete rewrite with length-ratio guard (rejects if output < 50% of original). Max file size: 32 KiB. 'blocks' — Aider-style SEARCH/REPLACE blocks. Token-efficient surgical edits. Max file size: 128 KiB. 'patch' — provider returns unified diff applied with patch semantics. | |
| tier | No | Complexity tier: low, medium, or high (default: low) | |
| effort | No | Optional reasoning effort hint. When supported by the selected provider, this is passed through to execution. | |
| prompt | Yes | The prompt to send to the model | |
| task_id | No | Optional caller-supplied task identifier used for inspection and telemetry correlation. | |
| timeout | No | Timeout in seconds (default: per-tier from config, max: 600) | |
| wave_id | No | Optional wave identifier. Subtasks sharing the same wave_id are shown as a parallel group in list_subtasks. Use the same value for all execute_subtask calls dispatched simultaneously (e.g. 'wave-1', 'wave-2'). | |
| prefer_free | No | Prefer free-tier providers (default: true) | |
| provider_id | No | Optional exact provider identifier, such as 'codex'. When set, execution is restricted to that provider. | |
| target_file | No | Absolute path to write the result to. When set, the model's output is written directly to this file. Parent directories are created automatically. Ideal for low-tier file generation. | |
| convergence_target | No | Optional quality convergence policy (plan 14). Re-executes until gate score meets min_score or max_rounds is exhausted. Each round appends prior output to the prompt. | |
| allow_out_of_workspace | No | Allow writing target_file to a path outside the workspace root. Every grant is logged. Explicit per-call opt-in. |