scoop — isolated sub-agents with sandboxed filesystems

SYNOPSIS

scoop_scoop(name, [model], [prompt])    Create a new scoop
feed_scoop(scoop_name, prompt)          Send instructions to a scoop
drop_scoop(scoop_name)                  Remove a scoop
list_scoops                             List all active scoops

DESCRIPTION

Scoops are isolated sub-agents created by the cone to do heavy lifting. Each scoop runs independently with its own sandboxed filesystem, shell, and conversation. The cone orchestrates — scoops do the work.

Scoops cannot see the cone's conversation history. They must be given complete, self-contained prompts with all necessary context, instructions, file paths, and expected output format.

LIFECYCLE

scoop_scoop(name, [model], [prompt])

Create a new scoop. The name is slugified into a folder name with -scoop appended (e.g., name "hero-block" becomes folder "hero-block-scoop"). If prompt is provided, the scoop starts working immediately — no separate feed_scoop needed. Optionally specify a model (e.g., "claude-sonnet-4-6"); defaults to the cone's model.
feed_scoop(scoop_name, prompt)

Send a task to an existing scoop. The prompt must be fully self-contained — include ALL context, file paths, instructions, and expected output. The scoop has zero access to the cone's conversation. You are notified when the scoop finishes.
drop_scoop(scoop_name)

Remove a scoop and destroy its context. The scoop is unregistered and stops all work. See WHEN TO DROP below for rules.
list_scoops

List all active scoops with their folder names and status.

FILESYSTEM

Each scoop gets a sandboxed filesystem enforced by RestrictedFS:

/scoops/{folder}/ — read/write. The scoop's private workspace.
/scoops/{folder}/workspace/ — working directory (shell starts here).
/scoops/{folder}/home/ — home directory.
/scoops/{folder}/tmp/ — temporary files.
/shared/ — read/write. Shared across all scoops and the cone.
/workspace/ — read-only. Access to cone's workspace including skills.

Write operations outside allowed paths throw EACCES. Read operations outside allowed paths return "not found". The cone has unrestricted access to the entire filesystem.

SCOOP MEMORY

Each scoop has its own CLAUDE.md at /scoops/{folder}/CLAUDE.md, created automatically on initialization. Use this for scoop-specific context, notes, and memory that persists across feed_scoop calls. The cone's memory lives at /workspace/CLAUDE.md.

NAMING CONVENTIONS

Scoop names are slugified: lowercased, non-alphanumeric characters replaced with hyphens, with -scoop appended. The folder name becomes the scoop's trigger (@{folder}) and assistant label.

If a scoop owns a sprinkle, the scoop name MUST match the sprinkle name. Sprinkle "giro-winners" requires scoop "giro-winners" (folder: "giro-winners-scoop"). This is how the cone routes work to the correct scoop.

WHEN TO DROP

Drop a scoop when:

It has completed its task and results have been synthesized by the cone.
It is stuck or misbehaving — drop and re-spawn with a better brief.

NEVER drop a scoop when:

It owns an open sprinkle — the scoop must stay alive for the sprinkle's lifetime to handle follow-up requests and lick events.
It is running a recurring or long-running task (e.g., watching a feed, handling webhooks).
It has active webhooks or cron tasks — the system will block removal with an error.
Work is still in progress — dropping mid-task loses all context.

PARALLEL DELEGATION

Spawn multiple scoops for independent work, then synthesize results in the cone:

scoop_scoop("research", prompt="Research X. Write findings to /shared/research.md")
scoop_scoop("prototype", prompt="Build prototype of Y in /scoops/prototype-scoop/workspace/")
# Wait for both to finish, then synthesize in the cone

Each scoop works independently and in parallel. The cone is notified when each scoop finishes. Synthesizing results — pulling everything together, resolving conflicts, making final decisions — is the cone's job.

WRITING GOOD PROMPTS

Scoops get complete self-contained prompts. They cannot see the cone's conversation, so include:

Full context and background for the task.
All relevant file paths, URLs, and data.
Specific instructions and expected output format.
Where to write results (e.g., /shared/results.md).

For sprinkle scoops, include the instruction to read the sprinkles skill first:

feed_scoop("dashboard", "You own the sprinkle 'dashboard'. Your job:
1. Run: read_file /workspace/skills/sprinkles/style-guide.md
2. Build the dashboard showing X, Y, Z
3. Write to /shared/sprinkles/dashboard/dashboard.shtml
4. Run: sprinkle open dashboard
5. Stay ready for follow-up instructions and lick events.")

TOOLS AVAILABLE TO SCOOPS

Scoops have the same core tools as the cone: read_file, write_file, edit_file, bash, javascript, and send_message. Scoops do NOT have scoop management tools (scoop_scoop, feed_scoop, drop_scoop, update_global_memory) — only the cone can manage scoops.