agent

NAME

agent — spawn a one-shot sub-agent that blocks until completion

SYNOPSIS

agent [--model <id>] [--thinking <level>] [--read-only <paths>] <cwd> <allowed-commands> <prompt>

DESCRIPTION

Spawns a sub-scoop, feeds it a task, blocks until the agent loop completes, then prints the scoop's final message on stdout. The sub-scoop is ephemeral: it is automatically dropped when the command exits, leaving no persistent state or conversational context behind.

Unlike scoop_scoop, which creates a persistent scoop you can converse with via feed_scoop, agent is synchronous and one-shot. It behaves like any other shell command — it blocks, returns an exit code, writes to stdout/stderr, and composes with pipes, redirects, and background jobs.

ARGUMENTS

<cwd>

Working directory for the spawned scoop. Becomes the scoop's sole writable prefix (in addition to system-writable paths). Relative paths are resolved against the invoking shell's cwd; ., .., and absolute paths are all supported. The directory must exist and must be writable by the caller — you cannot escape your own sandbox by passing a parent prefix like /scoops.
<allowed-commands>

Comma-separated list of shell commands the scoop may run. Use * to allow every command. Whitespace is trimmed around each entry; duplicates are tolerated. Example: curl,jq,grep.
<prompt>

The prompt forwarded verbatim to the scoop. The spawned agent has no access to the caller's conversation history — all necessary context must be packed into this string.

OPTIONS

--model <id>

Override the model used by the spawned scoop. Defaults to inheriting the parent scoop's model (or the cone's active model when invoked from the terminal). Run models to list available model IDs.
--thinking <level>

Set the reasoning/thinking level for the spawned scoop. One of: off, minimal, low, medium, high, xhigh. Defaults to inheriting the parent's level (or off when there is no parent). xhigh is silently clamped to high when the resolved model doesn't support it. Ignored for non-reasoning models. Aliased as --effort.
--read-only <paths>

Comma-separated VFS paths exposed read-only to the spawned scoop. This is a pure replace — when set, the default /workspace/ and the implicit invoking-cwd read-only addition are both dropped. Pass an explicit list if you want them back (e.g. --read-only "/workspace/,$(pwd)"). Each entry is normalized to a trailing slash.
-h, --help

Show usage information and exit.

SANDBOX

The spawned scoop operates in a restricted filesystem sandbox:

Read-only access (default)

/workspace/ — the global workspace
The invoking shell's cwd — so the agent can read files from where it was launched

Both are dropped when --read-only is passed.

Write access

<cwd> — the specified working directory (sole caller-controlled writable prefix)
/shared/ — shared inter-scoop directory
/scoops/<name>/ — the scoop's own scratch folder
/tmp/ — always-on ambient scratch (not toggleable)

Escape prevention

When invoked from a scoop shell, <cwd> must be writable by the calling scoop. A scoop cannot pass /scoops to gain write access over sibling sandboxes.

EXIT STATUS

0

The sub-scoop completed successfully. Final message printed to stdout.
1

Argument validation error, sandbox violation, bridge unavailable, or the sub-scoop encountered an error. Diagnostic written to stderr.
>0

Propagated from the sub-scoop's own exit code on failure. Error text written to stderr.

WHEN TO USE

Prefer agent when the task is:

One-shot and composable — you want the result inlined into a pipeline.
Narrow scope — a restricted command allow-list keeps the agent focused.
Self-contained — one prompt, one answer, no conversational follow-ups needed.
Cheap cleanup — the scoop is auto-dropped; no drop_scoop required.

Prefer scoop_scoop when you need:

Persistent conversation with feed_scoop follow-ups.
Sprinkle ownership (sprinkles require their owning scoop to stay alive).
Parallel fan-out with later synthesis via scoop_wait.

EXAMPLES

# Simple one-word response
agent . "*" "say hello in one word"

# Restricted allow-list for a focused file-counting task
agent /home ls,wc,find "how many files do I have in my home directory"

# Use a faster model for a quick summary
agent --model claude-haiku-4-5 . "*" "summarize the README in one sentence"

# High reasoning effort for a complex task
agent --thinking high . "*" "design a migration plan for the database schema"

# Custom read-only visibility
agent --read-only /workspace/,/shared/assets/ . "*" "review the docs and assets"

# Pipe result into downstream processing
SUMMARY=$(agent /tmp "curl,jq" "Fetch https://api.example.com/status and return the version field")
echo "Current version: $SUMMARY"

# Parallel extraction with background jobs
for url in site-a site-b site-c; do
  agent /tmp "curl,jq" "Fetch https://$url/api, return the top-level title field." >> /tmp/titles.txt &
done
wait

# Delegate a focused refactor with a restricted allow-list
agent /workspace/src "rg,sed,node" "Rename getCwd to getCurrentWorkingDirectory across *.ts"

NOTES

Ephemeral agent scoops do not notify the cone on completion — the caller gets the result on stdout only. Running agent from a non-cone shell does not trigger an unsolicited cone turn.
The spawned scoop gets its own conversation; it cannot see the caller's history. Pack all necessary context into the prompt.
Output is normalized to exactly one trailing newline on stdout. Null or empty final messages produce a bare newline.
The agent command validates that <cwd> exists and is a directory before spawning the sub-scoop.