delegate
Assign a coding task to an ACP agent and get its normalized result, with configurable model, safety mode, session resume, and fallback agents.
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). direct_workspace_mutation=true asks for a write/yolo agent to edit
working_dir itself, with live terminal access there, instead of an isolated worktree/temp copy — no
diff is captured and nothing is applied back, so the run leaves no record of what it changed. Asking is
not enough: the operator must have set allow_direct_workspace_mutation in config, working_dir must
be explicit and on the configured trusted_workspaces allowlist (trust_workspace=true does NOT
qualify), and it is refused inside a delegation chain. propose cannot use it at all (INVALID_INPUT).
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 | max)
asks the agent to spend more reasoning where it has a knob (codex via an advertised model[tier] id or a
confirmed reasoning_effort config option; cursor via the model id; cline via --thinking; junie via env).
max is accepted and clamped to the agent's ceiling where it has one. 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 | ||
| direct_workspace_mutation | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |