background-work

name	background-work
description	Use when starting, inspecting, rerunning, following up, or cancelling durable background commands or subagents.
metadata	{"id":"runs","title":"Background Work","summary":"Built-in guidance for detached background commands, subagents, inspection, and follow-up behavior.","status":"active"}
tools	["bash","background_bash","subagent","the unified conversation deferred-resume admin command"]

Background Work

Use intent-shaped tools. For waiting/resuming this conversation later, use the unified conversation deferred-resume admin command; do not run sleep in bash.

Choose the tool

Tool	Use case
bash	Shell commands; set background: true for durable background commands.
background_bash	Lifecycle tool for background command records.
subagent	A delegated agent task that should run durably outside the current turn.
scheduled_task	A persistent automation with a cron/time trigger and delivery policy.
the unified conversation deferred-resume admin command	Continue this same conversation later.

Background commands

Completion delivery is the normal “wake me when this finishes” path. If a background command/subagent uses deliverResultToConversation: true, do not also schedule a the unified conversation deferred-resume admin command merely to check whether it finished. Only schedule a separate wakeup for a distinct time-based action that should happen regardless of completion timing, and include a clear reason.

For Neon Pilot administration from shell, prefer the CLI equivalents:

neon-pilot background-commands list --json
neon-pilot background-commands start --command "pnpm test" --cwd /repo --json
neon-pilot background-commands logs <run-id> --tail 200 --json
neon-pilot background-commands cancel <run-id> --json

Start a detached command with bash:

{
  "command": "npm test",
  "background": true,
  "taskSlug": "tests",
  "cwd": "/path/to/repo"
}

Use get, logs, rerun, and cancel for lifecycle management.

Subagents

Start delegated agent work:

{
  "action": "start",
  "taskSlug": "review-diff",
  "prompt": "Review the current diff and summarize the risks.",
  "cwd": "/path/to/repo"
}

Use follow_up to continue a stopped subagent and get, logs, rerun, and cancel for lifecycle management. Do not use background_bash on subagent IDs.

The product UI should say Background commands and Subagents. Treat “run” as the durable storage record only.