return_background — Claude Code prompt for background jobs
The return_background Claude Code prompt coordinates background jobs and waits. It defines queue boundaries, result checks, and recovery after failures.
MIT ★ 488 updated 2026-11-15
.claude/commands/return_background.mdWhat return_background does
The prompt sets rules for queuing work and waiting for it to finish. The agent keeps each returned job ID and calls wait_for_tool only in a later submission, after receiving that ID. An enqueue receipt confirms acceptance, not execution or arrival.
A tail job that finishes in the same episode queue confirms that earlier jobs have ended. A timeout or cancellation does not create that barrier, nor does it apply across resources. finish is not a queue barrier. When an earlier result matters, the agent checks it with get_tool_result.
At a physical decision boundary, the agent waits for motion to finish, then checks feedback and the observation of its effect. A successful tool call alone does not prove physical success. If a prerequisite fails, queued dependents can be cancelled with the exposed cancellation tools; an action already running cannot be forcibly stopped.
What it helps with
- queue independent work before a blocking wait
- confirm earlier jobs have ended in the same queue
- inspect feedback before relying on an action result
- cancel queued dependents after a prerequisite fails
Example prompts for the agent
- Run independent jobs in the background, then wait according to
return_background. - After a physical action, inspect its feedback and the observation before continuing.
- If a prerequisite fails, cancel unjustified queued work and inspect the measured state.
How to install return_background
Manually: put the files in place
.claude/commands/return_background.mdHow to use
Paste the text at the start of a chat or into project instructions
Questions about return_background
How do I install return_background in Claude Code?
Add the file to the project at .claude/commands/return_background.md.
What does return_background do?
It sets rules for background jobs: when to wait, how to check results, and how to handle dependent jobs after a failure.
When does a completed background job confirm that earlier jobs have ended?
Only when the tail job actually finishes in the same episode queue. A timeout or cancellation provides no such barrier, and the guarantee does not cross resource queues.
Source text
return_background.md · MIT
Issue independent work before a blocking wait when resource scheduling allows it to overlap a running job. An enqueue receipt is acceptance, not execution or arrival. Keep returned job IDs. Call wait_for_tool only after receiving its job_id, in a later submission; never invent IDs or place a wait beside the submission that will create its ID. For confirmed order on the same episode queue, a tail job that actually finishes execution means earlier jobs have ended. A timeout or cancelled tail provides no such barrier, and no barrier extends to another resource. finish is not a queue barrier. The tail result certifies only its own execution: inspect relevant earlier feedback with get_tool_result if a prerequisite is uncertain. Wait at physical decision boundaries, then inspect feedback and the observation showing the effect. Job completion and tool call_ok=true do not establish physical success. Read-only work may overlap motion when it needs no new state; a historical view is not a completion barrier. Wait for motion before relying on geometry it may invalidate. Any action-model call remains one queue boundary, including all of its internal chunks. Failed or partial actions do not automatically cancel queued dependents. If a prerequisite fails, use the exposed cancellation tools to remove unjustified queued work. Cancellation cannot forcibly stop an already running action. Resolve running work and inspect the measured state before planning recovery.
© Open-RUA · MIT · Open-RUA/uni-robot-agent