acp-background-runs

name

acp-background-runs

description

Route requests for ACP or external coding agents such as Codex, Claude Code, Gemini CLI, and OpenCode into non-blocking OpenClaw background ACP runs instead of executing synchronously in the current chat. Use when a user wants to hand coding work to an external agent and expects the current conversation to continue without waiting. Triggers: "ACP", "Codex", "Claude Code", "Gemini CLI", "OpenCode", "background run", "background task".

ACP / Codex Background Runs

When a user asks to use ACP or an external coding agent such as Codex, Claude Code, Gemini CLI, or OpenCode, do not execute the task synchronously in the current chat. Route it through the ACP runtime instead.

Default Rules

• Prefer sessions_spawn and set runtime: "acp" with the appropriate agentId
• Default to mode: "run"
• Only use thread: true or mode: "session" when the user explicitly asks for an ongoing interactive or thread-bound session
• Set cwd when the target repository or directory is known
• Prefer absolute paths for cwd; do not pass ~ directly, expand it first
• Use a relaxed runTimeoutSeconds for longer tasks; do not mechanically default to 300
• Do not wait in the current conversation and do not poll for progress
• Reply immediately after submission that the task has been accepted and is running in the background
• Rely on sessions_spawn completion notifications to send the final result back to the current conversation
• Only add streamTo: "parent" when the user explicitly asks for progress updates

Default Handling

If the user is simply dispatching an ACP / Codex task and does not explicitly request a persistent interactive session, treat it as a one-shot background run. Do not block the current conversation. Send the result back only when the background run completes.

Timeout Guidance

• Quick read-only checks, short analysis, light tasks: runTimeoutSeconds: 120-300
• Normal coding tasks, project inspection, small scoped edits: runTimeoutSeconds: 600
• Research, code changes, file generation, test runs, longer reports: runTimeoutSeconds: 1200
• Clearly long-running tasks: increase further to 1800-3600 as needed
• Do not default to 0; only use 0 when the user explicitly wants no timeout

mode / thread Decision Rules

• If the user only wants the external agent to finish a task in the background, use mode: "run"
• If the user explicitly wants to continue talking to the same external-agent context afterward, use thread: true
• If the user explicitly asks for a persistent session, thread session, or long-lived context, use both thread: true and mode: "session"
• If there is no explicit need for ongoing interaction, do not open mode: "session"

cwd Rules

• If the target repository, project directory, or work directory is known, set cwd
• Prefer absolute paths
• Expand ~ before passing the path into sessions_spawn
• If the user did not give a directory but the task clearly targets a known repo, resolve the actual path from context before spawning

Fallback When ACP Is Unavailable

• Try runtime: "acp" first
• Only fall back to runtime: "subagent" when the ACP target agentId is clearly unavailable, unconfigured, or ACP cannot be used in the current environment
• When falling back, tell the user explicitly that the task is being run via subagent, not a native ACP session
• Do not silently fall back

Reply After Submission

Use this short confirmation by default:

Task accepted. It is running in the background and will report back here when complete.

If streamTo: "parent" is enabled, also say that key progress updates will be streamed back.

Prohibited Actions

• Do not execute external coding-agent tasks synchronously in the current conversation when they should go through ACP
• Do not poll after submission
• Do not call sessions_list, sessions_history, or similar tools to track child-session progress
• Do not use sleep or timer-based waiting to fake background orchestration
• Rely on the sessions_spawn completion / announce mechanism for the final result

Recommended Parameter Template

{
  "task": "<user request>",
  "runtime": "acp",
  "agentId": "<codex|claude|gemini|opencode|...>",
  "mode": "run",
  "cwd": "/abs/path/if-known",
  "runTimeoutSeconds": 300
}

When To Adjust

• Need ongoing multi-turn context: add thread: true and, if needed, mode: "session"
• Task may run for many minutes: increase runTimeoutSeconds
• Task is only a quick read-only check: keep runTimeoutSeconds small
• User explicitly wants progress relayed back: add streamTo: "parent"
• ACP is unavailable but the task should still run in the background: explain the fallback and use runtime: "subagent"