Code agents, delegation & pipelines

When a task is bigger than a single tool call — a multi-file refactor, a research-then-summarize chain, a fan-out of parallel sub-tasks — your agent can hand the work off rather than do it inline. This page covers two families of tools:

• Code-agent tools (claude_code, claude_code_runner, codex_cli, gemini_cli, google_agents_cli, opencode_cli) — delegate a coding task to an external coding CLI that runs its own full agent loop.
• Orchestration tools (delegate, swarm, llm_task, execute_pipeline) — coordinate Revka’s own sub-agents, run a tool-less LLM call, or chain several tools in one shot.

Every tool here is config-gated and disabled by default. Each one runs under the same security policy as the rest of the catalog: the autonomy level, the per-hour action budget, and the workspace path containment all apply before anything is spawned. For the broader picture of how agents coordinate, see Agents, teams & swarms and Spawning & coordinating agents.

Note

Code-agent CLIs and execute_pipeline are not in the default (minimal) tool registry. Enable them explicitly in config.toml, and make sure the underlying CLI binary is installed and authenticated on the host. See the Tools overview for the full registry.

Code-agent tools

These tools delegate to a separate coding CLI installed on the host. The CLI runs its own agent loop — reading files, editing, running shell commands — inside a working directory that must resolve inside your Revka workspace. A working directory that resolves outside the workspace (including via .. or symlinks) is rejected.

Authentication is delegated to the CLI’s own session by default. claude_code, codex_cli, gemini_cli, and opencode_cli all use the binary’s existing OAuth/login session — no API key is read from Revka unless you opt in by listing a key variable in env_passthrough (for example ANTHROPIC_API_KEY to switch Claude Code to API-key billing).

Common limits for all six tools: a default execution timeout of 600 s (coding tasks are long-running) and a 2 MB output cap (max_output_bytes, default 2097152).

claude_code

Delegate a coding task to Claude Code (claude -p). Supports file editing, bash execution, structured output, and multi-turn sessions.

{
  "prompt": "Refactor the authentication module to use JWT",
  "working_directory": "src/auth"
}

Field	Type	Default	Meaning
prompt	string	— (required)	The coding task to delegate.
allowed_tools	string[]	["Read","Edit","Bash","Write"]	Override the Claude Code tool allowlist for this call.
system_prompt	string	from config	Override or append a system prompt for this invocation.
session_id	string	—	Resume a previous Claude Code session by its ID.
json_schema	object	—	Request structured output conforming to this JSON Schema.
working_directory	string	workspace root	Working directory; must resolve inside the workspace.

Pass json_schema when you want machine-parseable output instead of prose, and session_id to continue a prior multi-turn run.

[claude_code]
enabled = true
timeout_secs = 600
allowed_tools = ["Read", "Edit", "Bash", "Write"]
max_output_bytes = 2097152
# Opt in to API-key billing instead of the CLI's OAuth session:
env_passthrough = ["ANTHROPIC_API_KEY"]

claude_code_runner

Spawn a Claude Code task in a tmux session with live Slack progress updates and an SSH handoff link. Unlike claude_code, this returns immediately with a session ID and an attach command — the work continues in the background. Use it for long migrations you want to monitor from Slack and attach to over SSH.

{
  "prompt": "Migrate database schema to v3",
  "slack_channel": "C0123456789"
}

Field	Type	Default	Meaning
prompt	string	— (required)	The coding task to delegate.
working_directory	string	workspace root	Working directory; must resolve inside the workspace.
slack_channel	string	—	Slack channel ID to post progress updates to.

[claude_code_runner]
enabled = true
ssh_host = "myhost.example.com"   # used to build the SSH handoff link
tmux_prefix = "zc-claude-"         # tmux session name prefix
session_ttl = 3600                 # seconds before auto-cleanup

The runner posts tool-execution events back to Revka’s gateway, which updates a single Slack message in place. The returned attach command lets you ssh in and tmux attach to watch or take over the live session.

codex_cli

Delegate a coding task to Codex CLI (codex -q). Runs the full Codex agent loop with file editing and bash execution.

{ "prompt": "Add unit tests for the parser module", "working_directory": "src/parser" }

Field	Type	Default	Meaning
prompt	string	— (required)	The coding task to delegate.
working_directory	string	workspace root	Working directory; must resolve inside the workspace.

[codex_cli]
enabled = true
timeout_secs = 600
max_output_bytes = 2097152
env_passthrough = ["OPENAI_API_KEY"]   # optional; defaults to the CLI's own session

gemini_cli

Delegate a coding task to Gemini CLI (gemini -p). Same shape as codex_cli.

{ "prompt": "Convert this Python script to use async/await", "working_directory": "scripts" }

Field	Type	Default	Meaning
prompt	string	— (required)	The coding task to delegate.
working_directory	string	workspace root	Working directory; must resolve inside the workspace.

[gemini_cli]
enabled = true
timeout_secs = 600
max_output_bytes = 2097152
env_passthrough = ["GOOGLE_API_KEY"]   # optional

google_agents_cli

Run Google Agents CLI (agents-cli) lifecycle commands for ADK / A2A agents on the Google Agent Platform. Unlike the other code-agent tools, this takes an argv-style command array, not a free-text prompt, and is restricted to an allowlisted set of subcommands — it is not arbitrary shell.

Supported subcommands include: setup, create, scaffold, install, lint, run, eval, deploy, publish, infra, data-ingestion, playground, update, login --status, and info. Use agents-cli run for non-interactive ADK project prompts; use deploy, eval run, and publish gemini-enterprise for lifecycle operations.

{ "command": ["scaffold", "--template", "rag"], "working_directory": "my-agent" }

Field	Type	Default	Meaning
command	string[]	— (required)	Subcommand and its arguments.
working_directory	string	workspace root	Working directory; must resolve inside the workspace.

[google_agents_cli]
enabled = true
timeout_secs = 600       # deploy/eval commands can be long
max_output_bytes = 2097152
env_passthrough = []      # uses the binary's own Google Cloud / AI Studio creds by default

opencode_cli

Delegate a coding task to OpenCode CLI (opencode run). Same shape as codex_cli.

{ "prompt": "Implement a binary search tree in Rust" }

Field	Type	Default	Meaning
prompt	string	— (required)	The coding task to delegate.
working_directory	string	workspace root	Working directory; must resolve inside the workspace.

[opencode_cli]
enabled = true
timeout_secs = 600
max_output_bytes = 2097152
env_passthrough = []      # uses the CLI's own session by default

Caution

A code-agent CLI runs with file-edit and shell capabilities inside your workspace. Treat enabling one the same way you treat enabling shell: lock down the host, keep the working directory scoped, and review the autonomy level. See Policy, commands & sandboxing.

Orchestration tools

delegate

Delegate a subtask to a named sub-agent defined in your [agents.<name>] config. By default the sub-agent runs a single prompt; with agentic = true in its config it runs a full tool-call loop with its own tool allowlist. delegate also supports background execution (returns a task_id immediately) and parallel fan-out across several agents at once.

{
  "agent": "researcher",
  "prompt": "Summarize the top 5 recent papers on diffusion models",
  "background": false
}

Field	Type	Default	Meaning
action	string	delegate	delegate | check_result | list_results | cancel_task.
agent	string	— (required for delegate)	Agent name from [agents.<name>] config.
prompt	string	— (required for delegate)	Task prompt for the sub-agent.
context	string	—	Context to prepend to the prompt.
background	boolean	false	Return immediately with a task_id instead of blocking.
parallel	string[]	—	Agent names to run concurrently on the same prompt.
task_id	string	—	For check_result / cancel_task (returned by a background delegate).

The background workflow is: call delegate with background: true, capture the returned task_id, then later call action: "check_result" with that task_id. Use action: "list_results" to see all background tasks and action: "cancel_task" to stop a running one.

Sub-agents are defined in config. The delegate tool itself is excluded from sub-agent allowlists to prevent re-entrant delegation loops, and max_depth caps nested delegation.

[agents.researcher]
provider = "openrouter"
model = "anthropic/claude-sonnet-4-6"
system_prompt = "You are a research assistant."
agentic = true                                    # enables the tool-call loop
allowed_tools = ["web_search", "http_request", "file_read"]
max_iterations = 8
agentic_timeout_secs = 600

# Global delegate defaults (used unless overridden per-agent):
[delegate]
timeout_secs = 120          # non-agentic calls
agentic_timeout_secs = 300  # agentic loops

Note

agentic = true requires at least one entry in allowed_tools. Provider validity for every configured agent is checked by revka doctor, so run it before relying on delegation in production.

See Config: provider, agent & routing for the full [agents.<name>] schema.

swarm

Orchestrate a named swarm of agents to collaboratively handle a task. Where delegate targets a single agent, swarm coordinates several according to a strategy defined in config:

• sequential — a pipeline; each agent’s output feeds the next.
• parallel — fan-out then fan-in; all agents run concurrently and results are combined.
• router — an LLM selects which agent(s) should handle the task.

{
  "swarm": "research-team",
  "prompt": "Analyze the competitive landscape for AI code assistants"
}

Field	Type	Default	Meaning
swarm	string	— (required)	Swarm name from [swarms.<name>] config.
prompt	string	— (required)	Task prompt for the swarm.
context	string	—	Additional context.

[swarms.research-team]
agents = ["researcher", "coder"]   # names from [agents.<name>]
strategy = "sequential"             # sequential | parallel | router
timeout_secs = 300
# router_prompt = "..."             # used when strategy = "router"

See Agents, skills & teams API and Built-in workflows & orchestration patterns for related orchestration.

llm_task

Run a prompt through an LLM with no tool access and return the response. Optionally validate the output against a JSON Schema. This is the right tool for structured extraction, classification, summarization, and transformation — anything that’s a pure prompt-in / answer-out call. Use delegate instead when the work needs tools.

{
  "prompt": "Extract the company name and founding year from: <text>",
  "schema": {
    "type": "object",
    "properties": {
      "company": { "type": "string" },
      "founded": { "type": "integer" }
    },
    "required": ["company", "founded"]
  }
}

Field	Type	Default	Meaning
prompt	string	— (required)	The prompt to send.
schema	object	—	JSON Schema; when set, the model is instructed to return matching JSON.
model	string	default_model	Override the model for this call.
temperature	number	default_temperature	Override temperature (0.0–2.0).

With no overrides, llm_task uses the root config’s default_provider, default_model, and default_temperature.

execute_pipeline

Execute a multi-step tool pipeline in a single call. Steps run sequentially by default, and a step can reference the output of an earlier step with {{step[N].result}} interpolation. Set parallel: true to run all steps concurrently — but note that parallel mode does not interpolate between steps, since there is no defined ordering.

{
  "steps": [
    { "tool": "web_search_tool", "args": { "query": "Rust async runtimes 2026" } },
    { "tool": "llm_task", "args": { "prompt": "Summarize these results:\n{{step[0].result}}" } },
    { "tool": "file_write", "args": { "path": "out/summary.md", "content": "{{step[1].result}}" } }
  ]
}

Field	Type	Default	Meaning
steps	array	— (required)	Each element is { "tool": "<name>", "args": { ... } }.
parallel	boolean	false	Run all steps concurrently. No {{step[N].result}} interpolation in this mode.

{{step[N].result}} interpolation: N is the zero-based index of an earlier step. The placeholder is replaced with that step’s textual result before the current step runs. It works anywhere inside the args object — strings, nested objects, and arrays are all walked. Only prior steps can be referenced; sequential execution is what makes interpolation possible.

[pipeline]
enabled = true
max_steps = 20
# Allowlist: steps referencing a tool not on this list are rejected before execution.
allowed_tools = ["web_search_tool", "llm_task", "file_read", "file_write", "shell"]

Caution

allowed_tools is enforced before any step runs — an empty list rejects every pipeline. List exactly the tools your pipelines need, and remember that each step still runs under the same security policy and action budget as a direct tool call.

Choosing the right tool

You want to…	Use
Hand a coding task to an external coding CLI’s full agent loop	claude_code, codex_cli, gemini_cli, opencode_cli
Run a long coding task in the background with Slack progress + SSH handoff	claude_code_runner
Drive Google ADK / Agent Platform lifecycle commands	google_agents_cli
Run one configured sub-agent (optionally with tools, in background, or in parallel)	delegate
Coordinate several configured agents by strategy	swarm
Make a tool-less LLM call, optionally schema-validated	llm_task
Chain several tools in one call, passing results between them	execute_pipeline

Related pages

• Agents, teams & swarms — the orchestration model.
• Spawning & coordinating agents — patterns for multi-agent work.
• Config: provider, agent & routing — [agents.<name>] and routing config.
• Filesystem & code tools — the lower-level shell, file, and git tools code agents build on.
• Workflows & SOP overview — declarative multi-step automation beyond a single pipeline call.