delegate
Delegate a task to an AI coding agent and return its normalized result. Supports fallback, model selection, and safety modes.
Instructions
Delegate a task to one ACP agent and return its normalized result.
cli is an agent id (see capabilities); model is optional (the agent's default otherwise).
safety_mode is read_only | propose | write | yolo; when omitted, the configured default_safety_mode
applies (read_only out of the box). write and yolo also need a trusted workspace (trust_workspace=true
or a configured allowlist). files lists paths to put in scope. role names a persona (see
list_roles) whose system prompt is prepended to prompt. effort (low | medium | high | xhigh) asks
the agent to spend more reasoning where it has a knob (codex/cursor via the model id, cline via
--thinking, junie via env); a reported no-op for an agent with none. Omitted, the configured
default_effort (per-agent or global) applies. fallback is an ordered list of alternate targets
(cli / cli:model strings or {cli, model} objects) tried when the primary fails on a
re-execution-safe failure (a spawn/handshake failure that never ran the prompt); a benched alternate is
skipped and fallback_chain records the path. A write/yolo delegation never falls back.
allow_model_fallback (default true) first retries the same agent on its configured fallback model on a
model-unavailable failure, where it has one. persist keeps this run as a durable job under
<jobs_dir>/<run_id>/ (state.json + answer / diff artifacts); None follows default_persistence
(ephemeral out of the box), true / false force it. session_id resumes a prior agent session: pass
the session_id from an earlier delegate result and the agent reloads that conversation (ACP
session/load) instead of starting fresh, so a follow-up turn continues it; agents that do not persist
their own sessions fail RESUME_FAILED. mode="async" runs the turn as a background job and returns a
job_id (poll with job_status / job_result); mode="sync" awaits it.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cli | Yes | ||
| mode | No | sync | |
| role | No | ||
| files | No | ||
| model | No | ||
| effort | No | ||
| prompt | Yes | ||
| persist | No | ||
| fallback | No | ||
| timeout_s | No | ||
| session_id | No | ||
| safety_mode | No | ||
| working_dir | No | ||
| trust_workspace | No | ||
| external_tracking | No | ||
| allow_model_fallback | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |