v2: shell: no handle at launch to stop/cancel running background commands

[Ploppy3]

Summary

Background shell commands do return a call ID — but only on completion, not at launch. This means there is still no way to reference or cancel a running background command while it is executing.

New finding (v2 update)

When a background shell finishes, the completion notification includes a call ID:

id: call_00_GHYwLiUePO5p7d23ATlI7431
state: completed
command: sleep 60 && echo "done"

However, at launch time, the response is simply:

"The command was moved to the background. You will be notified automatically when the command finishes."

No ID, PID, or handle is provided at that point.

What this means

• The infrastructure does track background commands with an ID — it is simply not exposed at launch.
• If the ID were returned at launch (same as subagent's ses_... ID), it could enable a kill/cancel mechanism.
• Currently, the only way to stop a background command is indirect — pkill by name or kill by port — which is fragile and error-prone.

Desired behavior

1. Return the call ID (e.g. call_00_...) immediately when launching a background shell.
2. Provide a mechanism (tool or parameter) to cancel/kill a running background command using that ID.

Environment

• opencode version: 0.0.0-next-15329 (v2 beta, next channel)
• OS: Linux 7.0.0-27-generic (x86_64, Ubuntu)
• Terminal: xterm-256color, truecolor
• Shell: /bin/bash
• Install/channel: next (v2 beta)

[github-actions]

This issue might be a duplicate of existing issues. Please check:

• V2: define shell backgrounding semantics #34366: Tracks the design and implementation of V2 shell backgrounding semantics, including cancellation, process handles, and owner/session-bound observation — which is the same gap you're describing here.
• V2: define restart semantics for foreground and background shells #36348: Covers related semantics around background shell lifecycle, ownership, and completion delivery across restarts.

[Klark61]

Thanks for tracking this — I hit exactly this on Windows (dev servers that can't be stopped without pkill/taskkill by name), and I'd like to propose a concrete shape that also addresses #34366.

Prior art

• Claude Code backgrounds a running Bash call (Ctrl+B), returns a task ID, writes output to a file the agent reads later, and auto-terminates on session exit or >5 GB output (disable via CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1).
• Cline executes commands directly in the terminal, watches output in real time, and reacts to new output as it appears (with cancellation via the SDK's abort signal).

Both prove the model: the agent launches, gets a handle, observes, and kills — instead of blocking until exit or the 60s timeout.

Proposed API surface

Three pieces, all session-scoped (jobs are not cross-session addressable, mirroring Claude Code):

1. bash gains async?: boolean. When set, the tool returns immediately with { job_id, pid, started_at } instead of blocking. Output is captured into a 1 MiB in-memory ring buffer with file spill (reusing the existing truncation path). The synchronous path is unchanged when async is omitted.

2. bash_status({ job_id, tail_bytes? }) → { state: "running"|"exited"|"killed", elapsed_ms, exit_code?, output_so_far }. Non-blocking poll. The agent calls it in a loop, reasoning between polls (wait / kill / proceed). Suggested throttling: min 500 ms, max 5 s, backoff when output is unchanged across two polls.

3. bash_kill({ job_id, signal? }) → { killed, pid }.

   • Windows: taskkill /PID <pid> /T /F — the /T is load-bearing. Dev servers (vite, next dev) spawn worker children that hold the stdout pipe open; killing only the parent leaves orphans that keep the pipe alive (the Bash tool hangs until timeout on Windows when spawned process keeps a stdout/stderr pipe open (dev servers, daemons) #32504 symptom). /T walks the tree, /F forces.
   • POSIX: SIGTERM, escalating to SIGKILL after 5 s.

A session-scope finalizer kills any still-running jobs when the session ends, so an agent that forgets to call bash_kill doesn't leak processes.

How this lands on the existing issues

• Bash tool hangs until timeout on Windows when spawned process keeps a stdout/stderr pipe open (dev servers, daemons) #32504 (pipe-hang): async:true returns immediately; the agent polls instead of blocking on pipe EOF.
• Shell tool can return (no output) with exit 0 on first call when using workdir #35511 ((no output) race): in async mode the reader fiber is owned by the job, not the tool-call scope, so it isn't interrupted on tool return — the ring always has whatever was drained.
• V2: define shell backgrounding semantics #34366: answers the open questions — background?: boolean (I'd call it async to avoid overloading the subagent background term), return shape, completion delivery via bash_status, owner-bound get/cancel, output retention (ring + spill), and platform cleanup guarantees.

Smallest viable first PR

Ship async:true + bash_status first; bash_kill as a follow-up. Before bash_kill lands, the agent can still kill via a normal synchronous bash call using the pid returned by the async launch (taskkill /PID <pid> /T /F on Windows). This keeps PR 1 focused on the observation problem (the harder half) and lets the registry/ring design bake before committing kill semantics.

I've verified the current shell.ts on dev — the spawner.spawn / Stream.decodeText(handle.all) / handle.kill({ forceKillAfter }) primitives are exactly what async mode needs, so the change is a fork inside run() plus a new JobRegistry, not a rewrite.

Happy to open a PR against dev if there's interest. If BackgroundJob (referenced in #34366 as already existing for subagent background mode) is the intended shared primitive, I'm glad to build on top of it instead of a standalone registry — just point me at its interface.

[Ploppy3]

Updating with new v2 findings: background shell commands do return a call ID (call_00_GHYwLiUePO5p7d23ATlI7431) — but only in the completion notification, not at launch. This confirms the infrastructure tracks them; the fix would be to expose the ID at launch time, which would then enable a cancel/kill mechanism. Keeping this open to avoid stale.