feat: accept input while a session's foreground turn waits on background work

apps/backend/cmd/mock-agent/background_test.go

@@ -0,0 +1,105 @@
+package main
+
+import (
+	"testing"
+	"time"
+
+	acp "github.com/coder/acp-go-sdk"
+)
+
+// TestParseBackgroundDuration pins the /background argument parsing, including
+// the regression Copilot flagged on PR #3: a unit-bearing value like "1m" must
+// not be mangled into "1ms" by the bare-seconds fallback.
+func TestParseBackgroundDuration(t *testing.T) {
+	const def = 8 * time.Second
+	cases := []struct {
+		name string
+		cmd  string
+		want time.Duration
+	}{
+		{"no argument uses default", "/background", def},
+		{"bare number is seconds", "/background 12", 12 * time.Second},
+		{"explicit seconds", "/background 20s", 20 * time.Second},
+		{"explicit minutes (regression: not 1ms)", "/background 1m", time.Minute},
+		{"explicit hours", "/background 2h", 2 * time.Hour},
+		{"explicit milliseconds", "/background 500ms", 500 * time.Millisecond},
+		{"unparseable falls back to default", "/background soon", def},
+		{"zero falls back to default", "/background 0", def},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := parseBackgroundDuration(tc.cmd, def); got != tc.want {
+				t.Fatalf("parseBackgroundDuration(%q) = %v, want %v", tc.cmd, got, tc.want)
+			}
+		})
+	}
+}
+
+func TestDetachedBackgroundLifecycleFrames(t *testing.T) {
+	e, updates := newTestEmitter()
+	e.launchAsyncSubagentTool("detached-1", "Detached work", "Keep working", "general-purpose")
+	e.completeDetachedWork()
+
+	got := updates.getUpdates()
+	if len(got) != 3 {
+		t.Fatalf("updates = %d, want launch, async acknowledgement, and completion", len(got))
+	}
+	if got[0].notification.Update.ToolCall == nil {
+		t.Fatal("first update must register the subagent tool")
+	}
+	launch := got[1].notification.Update.ToolCallUpdate
+	if launch == nil {
+		t.Fatal("second update must acknowledge the async launch")
+	}
+	response := launch.Meta["claudeCode"].(map[string]any)["toolResponse"].(map[string]any)
+	if response[subagentKeyStatus] != subagentStatusAsync || response["isAsync"] != true {
+		t.Fatalf("async launch response = %#v", response)
+	}
+
+	usage := got[2].notification.Update.UsageUpdate
+	if usage == nil {
+		t.Fatal("third update must be a usage lifecycle boundary")
+	}
+	origin := usage.Meta[claudeOriginMetaKey].(map[string]any)
+	if origin["kind"] != claudeOriginTaskNotification {
+		t.Fatalf("completion origin = %#v", origin)
+	}
+	if got[2].notification.SessionId != acp.SessionId("test-session") {
+		t.Fatalf("completion session = %q", got[2].notification.SessionId)
+	}
+}
+
+func TestAsyncSubagentForegroundFramesMatchClaudeOrdering(t *testing.T) {
+	e, updates := newTestEmitter()
+	emitAsyncSubagentLifecycle(e, "/async-subagent-teardown", false)
+
+	got := updates.getUpdates()
+	if len(got) != 5 {
+		t.Fatalf("updates = %d, want launch, async acknowledgement, idle, thought, and message", len(got))
+	}
+	if got[0].notification.Update.ToolCall == nil {
+		t.Fatal("first update must start the Agent tool")
+	}
+	launch := got[1].notification.Update.ToolCallUpdate
+	if launch == nil {
+		t.Fatal("second update must acknowledge the async launch")
+	}
+	response := launch.Meta["claudeCode"].(map[string]any)["toolResponse"].(map[string]any)
+	if response["agentId"] != asyncSubagentAgentID || response[subagentKeyStatus] != subagentStatusAsync {
+		t.Fatalf("async launch response = %#v", response)
+	}
+	idle := got[2].notification.Update.UsageUpdate
+	if idle == nil {
+		t.Fatal("third update must be the foreground-idle usage boundary")
+	}
+	origin := idle.Meta[claudeOriginMetaKey].(map[string]any)
+	if origin["kind"] != claudeOriginHuman {
+		t.Fatalf("idle origin = %#v", origin)
+	}
+	if !isThoughtUpdate(got[3]) {
+		t.Fatal("fourth update must be final same-prompt thinking")
+	}
+	if !isTextUpdate(got[4]) || getTextContent(got[4]) != "Foreground response after async launch." {
+		t.Fatalf("fifth update must be final same-prompt assistant output, got %#v", got[4])
+	}
+}

apps/backend/cmd/mock-agent/emitter.go

@@ -179,11 +179,33 @@ func (e *emitter) endMonitorTool(id acp.ToolCallId) {
 const (
 	subagentKeyStatus       = "status"
 	subagentStatusCompleted = "completed"
+	subagentStatusAsync     = "async_launched"
 	subagentKeyDescription  = "description"
 	subagentKeyPrompt       = "prompt"
 	subagentKeySubagentType = "subagent_type"
 )
 
+const (
+	claudeOriginMetaKey          = "_claude/origin"
+	claudeOriginHuman            = "human"
+	claudeOriginTaskNotification = "task-notification"
+)
+
+// foregroundIdle emits the human-origin usage boundary Claude sends after it
+// hands the foreground back while detached work remains active.
+func (e *emitter) foregroundIdle() {
+	_ = e.conn.SessionUpdate(e.ctx, acp.SessionNotification{
+		SessionId: e.sid,
+		Update: acp.SessionUpdate{UsageUpdate: &acp.SessionUsageUpdate{
+			Size: 1_000_000,
+			Used: 24_000,
+			Meta: map[string]any{
+				claudeOriginMetaKey: map[string]any{"kind": claudeOriginHuman},
+			},
+		}},
+	})
+}
+
 // subagentClaudeMeta builds the `_meta.claudeCode.toolName=Agent` payload that
 // claude-agent-acp tags subagent (Task) tool_call notifications with. The
 // kandev ACP adapter recognizes subagents by this marker.
@@ -242,6 +264,54 @@ func (e *emitter) startSubagentTool(id acp.ToolCallId, description, prompt, suba
 	})
 }
 
+// launchAsyncSubagentTool mirrors Claude's detached Agent launch: the Task
+// invocation is terminal, but its independently-running workload is not.
+func (e *emitter) launchAsyncSubagentTool(
+	id acp.ToolCallId,
+	description, prompt, subagentType string,
+) {
+	e.startSubagentTool(id, description, prompt, subagentType)
+	withUpdateMeta := func(meta any) acp.ToolCallUpdateOpt {
+		return func(tu *acp.SessionToolCallUpdate) { tu.Meta = toMetaMap(meta) }
+	}
+	response := map[string]any{
+		"claudeCode": map[string]any{
+			"toolResponse": map[string]any{
+				"agentId":           asyncSubagentAgentID,
+				"agentType":         subagentType,
+				subagentKeyStatus:   subagentStatusAsync,
+				"isAsync":           true,
+				"outputFile":        "/tmp/kandev-e2e-detached.output",
+				"canReadOutputFile": true,
+			},
+		},
+	}
+	_ = e.conn.SessionUpdate(e.ctx, acp.SessionNotification{
+		SessionId: e.sid,
+		Update: acp.UpdateToolCall(id,
+			acp.WithUpdateRawOutput("Async agent launched successfully."),
+			withUpdateMeta(response),
+		),
+	})
+}
+
+// completeDetachedWork emits the same task-notification usage boundary Claude
+// sends when an async workload finishes. The provider does not expose the task
+// ID on this frame, so the orchestrator retires it only when one registration is
+// outstanding and the completion is therefore unambiguous.
+func (e *emitter) completeDetachedWork() {
+	_ = e.conn.SessionUpdate(e.ctx, acp.SessionNotification{
+		SessionId: e.sid,
+		Update: acp.SessionUpdate{UsageUpdate: &acp.SessionUsageUpdate{
+			Size: 1_000_000,
+			Used: 25_000,
+			Meta: map[string]any{
+				claudeOriginMetaKey: map[string]any{"kind": claudeOriginTaskNotification},
+			},
+		}},
+	})
+}
+
 // completeSubagentTool emits the terminal subagent tool_call_update with the
 // result text and the `toolResponse` metadata block.
 func (e *emitter) completeSubagentTool(id acp.ToolCallId, resultText string, r subagentResult) {

apps/backend/cmd/mock-agent/handler.go

@@ -270,11 +270,77 @@ func handlePrompt(e *emitter, prompt, model string) {
 		emitMarkdownShowcase(e, model)
 	case strings.EqualFold(cmd, "/sleep") || strings.HasPrefix(strings.ToLower(cmd), "/sleep "):
 		emitSleep(e, cmd)
+	case strings.EqualFold(cmd, "/background") || strings.HasPrefix(strings.ToLower(cmd), "/background "):
+		emitBackgroundWork(e, cmd)
+	case strings.EqualFold(cmd, "/detached-background") || strings.HasPrefix(strings.ToLower(cmd), "/detached-background "):
+		emitDetachedBackgroundWork(e, cmd)
+	case strings.EqualFold(cmd, "/async-subagent-lifecycle") || strings.HasPrefix(strings.ToLower(cmd), "/async-subagent-lifecycle "):
+		emitAsyncSubagentLifecycle(e, cmd, true)
+	case strings.EqualFold(cmd, "/async-subagent-teardown"):
+		emitAsyncSubagentLifecycle(e, cmd, false)
 	default:
 		emitRandomResponse(e, cmd, model)
 	}
 }
 
+const asyncSubagentAgentID = "agent_e2e_async_lifecycle"
+
+// emitAsyncSubagentLifecycle replays the ordering emitted by a detached Claude
+// Agent rather than the shell-oriented /detached-background sequence:
+//
+//  1. Agent tool launch acknowledgement with a stable agentId
+//  2. human-origin usage boundary (foreground idle)
+//  3. final thought and assistant output from the same prompt
+//  4. Prompt returns to its caller, completing the foreground turn
+//  5. optional ID-less task-notification boundary after the child finishes
+//
+// The teardown variant intentionally omits step 5 so execution termination is
+// the only evidence available to reconcile the registration.
+func emitAsyncSubagentLifecycle(e *emitter, cmd string, emitCompletion bool) {
+	d := parseBackgroundDuration(cmd, 20*time.Second)
+	toolCallID := nextToolID()
+	e.launchAsyncSubagentTool(
+		toolCallID,
+		"Async subagent exploration",
+		"Continue independently after the foreground turn ends",
+		"general-purpose",
+	)
+	e.foregroundIdle()
+	e.thought("The child is launched; I can return control to the operator.")
+	e.text("Foreground response after async launch.")
+
+	if !emitCompletion {
+		return
+	}
+	backgroundEmitter := &emitter{ctx: context.Background(), conn: e.conn, sid: e.sid}
+	go func() {
+		time.Sleep(d)
+		// Claude's async Agent invocation is terminal at launch. The later
+		// completion is a task-notification usage frame, not a second tool update.
+		backgroundEmitter.completeDetachedWork()
+	}()
+}
+
+// emitDetachedBackgroundWork launches work that outlives this prompt response.
+// It is intentionally different from /background, whose foreground prompt stays
+// open for the entire delay, so E2E can cover settled+background explicitly.
+func emitDetachedBackgroundWork(e *emitter, cmd string) {
+	d := parseBackgroundDuration(cmd, 8*time.Second)
+	e.text("Launching detached background work; this foreground turn is complete.")
+
+	taskToolID := nextToolID()
+	e.launchAsyncSubagentTool(taskToolID,
+		"Detached background exploration",
+		"Continue working after the foreground response ends",
+		"general-purpose")
+
+	backgroundEmitter := &emitter{ctx: context.Background(), conn: e.conn, sid: e.sid}
+	go func() {
+		time.Sleep(d)
+		backgroundEmitter.completeDetachedWork()
+	}()
+}
+
 // emitSleep sleeps for the requested duration (default 10s) then responds.
 // Useful for simulating a slow agent turn without any tool calls.
 func emitSleep(e *emitter, cmd string) {
@@ -291,6 +357,59 @@ func emitSleep(e *emitter, cmd string) {
 	e.text(fmt.Sprintf("Slept for %s.", d))
 }
 
+// emitBackgroundWork reproduces the fine-grained busy signal window
+// (ADR-0049): the foreground emits a line, spawns a
+// top-level subagent Task that holds the turn open, then goes IDLE for the
+// requested duration (default 8s) with no foreground output — the exact state
+// where the orchestrator narrows the busy gate so the composer accepts input
+// while the session still reads RUNNING. When the hold elapses the subagent
+// completes, the foreground resumes, and the turn ends (→ done).
+func emitBackgroundWork(e *emitter, cmd string) {
+	d := parseBackgroundDuration(cmd, 8*time.Second)
+
+	e.text("Kicking off background work; I'll keep going in the background.")
+
+	taskToolID := nextToolID()
+	e.startSubagentTool(taskToolID,
+		"Background exploration",
+		"Explore the codebase while the foreground stays idle",
+		"general-purpose")
+
+	// Hold the turn open with NO foreground output so the session stays in the
+	// background-idle substate for the whole window.
+	time.Sleep(d)
+
+	e.completeSubagentTool(taskToolID, "Background work finished", subagentResult{
+		agentID:      "agent_e2e_background",
+		subagentType: "general-purpose",
+		durationMs:   d.Milliseconds(),
+		totalTokens:  4242,
+		toolUseCount: 1,
+	})
+
+	e.text("Background work complete.")
+}
+
+// parseBackgroundDuration reads the optional duration argument of a /background
+// command, returning def when it is absent or unparseable. A value carrying an
+// explicit unit is honored as-is (`1m`, `500ms`, `2h`); a bare number is treated
+// as seconds (`8` → 8s). The explicit-unit parse is tried FIRST: appending "s"
+// to a unit-bearing value like `1m` would otherwise parse as the valid-but-wrong
+// "1ms" (1 millisecond) and never reach the correct interpretation.
+func parseBackgroundDuration(cmd string, def time.Duration) time.Duration {
+	parts := strings.Fields(cmd)
+	if len(parts) < 2 {
+		return def
+	}
+	if parsed, err := time.ParseDuration(parts[1]); err == nil && parsed > 0 {
+		return parsed
+	}
+	if secs, err := time.ParseDuration(parts[1] + "s"); err == nil && secs > 0 {
+		return secs
+	}
+	return def
+}
+
 // emitError emits an error message.
 func emitError(e *emitter, model string) {
 	randomDelay(model)

apps/backend/cmd/mock-agent/main.go

@@ -379,6 +379,10 @@ func mockAvailableCommands() []acp.AvailableCommand {
 	}
 	return []acp.AvailableCommand{
 		{Name: "slow", Description: "Run a slow response (default 5s)", Input: hint("duration (e.g. 10s)")},
+		{Name: "background", Description: "Spawn a subagent and stay foreground-idle (default 8s)", Input: hint("duration (e.g. 8s)")},
+		{Name: "detached-background", Description: "Launch work that outlives the foreground turn (default 8s)", Input: hint("duration (e.g. 8s)")},
+		{Name: "async-subagent-lifecycle", Description: "Replay an async Agent lifecycle (default 20s)", Input: hint("duration (e.g. 20s)")},
+		{Name: "async-subagent-teardown", Description: "Replay async Agent work with a missing completion"},
 		{Name: "error", Description: "Simulate an error"},
 		{Name: "overloaded", Description: "Simulate a transient 529 Overloaded error (fails once, then recovers)"},
 		{Name: "thinking", Description: "Emit thinking/reasoning blocks"},

apps/backend/internal/agent/runtime/lifecycle/event_types.go

@@ -100,16 +100,17 @@ func (p PrepareCompletedEventPayload) GetSessionID() string {
 
 // AgentStreamEventData contains the nested event data within AgentStreamEventPayload.
 type AgentStreamEventData struct {
-	Type          string      `json:"type"`
-	ACPSessionID  string      `json:"acp_session_id,omitempty"`
-	Text          string      `json:"text,omitempty"`
-	ToolCallID    string      `json:"tool_call_id,omitempty"`
-	ToolName      string      `json:"tool_name,omitempty"`
-	ToolTitle     string      `json:"tool_title,omitempty"`
-	ToolStatus    string      `json:"tool_status,omitempty"`
-	Error         string      `json:"error,omitempty"`
-	SessionStatus string      `json:"session_status,omitempty"` // "resumed" or "new" for session_status events
-	Data          interface{} `json:"data,omitempty"`
+	Type             string      `json:"type"`
+	ACPSessionID     string      `json:"acp_session_id,omitempty"`
+	Text             string      `json:"text,omitempty"`
+	ToolCallID       string      `json:"tool_call_id,omitempty"`
+	ToolName         string      `json:"tool_name,omitempty"`
+	ToolTitle        string      `json:"tool_title,omitempty"`
+	ToolStatus       string      `json:"tool_status,omitempty"`
+	Error            string      `json:"error,omitempty"`
+	SessionStatus    string      `json:"session_status,omitempty"` // "resumed" or "new" for session_status events
+	PromptGeneration uint64      `json:"prompt_generation,omitempty"`
+	Data             interface{} `json:"data,omitempty"`
 
 	// ParentToolCallID identifies the parent Task tool call when this event
 	// comes from a subagent. Used for visual nesting in the UI.

apps/backend/internal/agent/runtime/lifecycle/events.go

@@ -152,6 +152,7 @@ func (p *EventPublisher) PublishAgentStreamEvent(execution *AgentExecution, even
 		ToolStatus:              event.ToolStatus,
 		Error:                   event.Error,
 		SessionStatus:           event.SessionStatus,
+		PromptGeneration:        event.PromptGeneration,
 		Data:                    event.Data,
 		Normalized:              event.NormalizedPayload,
 		AvailableCommands:       event.AvailableCommands,