docs: refresh subagent lifecycle guidance

docs/developers/tools/task.md

@@ -14,8 +14,9 @@ Use `agent` to launch a specialized subagent to handle complex, multi-step tasks
 - `prompt` (string, required): The detailed task prompt for the subagent to execute. Should contain comprehensive instructions for autonomous execution.
 - `subagent_type` (string, optional): The type of specialized agent to use for this task. Defaults to `general-purpose` if omitted.
 - `fork_turns` (string, optional): Only valid with `subagent_type="fork"`. Omit it or use `all` for the full parent conversation, or use a positive integer string such as `"3"` for the most recent three real user turns. Tool responses and pure system reminders do not count as turns.
-- `run_in_background` (boolean, optional): Defaults to `true` for top-level one-shot agents. Set to `false` to wait for the result inline. Nested agents run in the foreground unless `run_in_background` is explicitly `true`, which is rejected because nested agents cannot receive background completion notifications. Caller-owned `working_dir` launches default to foreground and reject explicit or configured background execution.
-- `isolation` (string, optional): Set to `"worktree"` to run the agent in an isolated git worktree.
+- `run_in_background` (boolean, optional): Defaults to `true` for top-level regular agents. Set to `false` to wait for a regular agent's result inline. Headless forks always run in the background. Nested agents run in the foreground unless `run_in_background` is explicitly `true`, which is rejected because nested agents cannot receive background completion notifications. Caller-owned `working_dir` launches run in the foreground and reject explicit or configured background execution.
+- `isolation` (string, optional): Set to `"worktree"` to run an explicitly named, non-fork agent in an isolated git worktree that Qwen Code creates and manages.
+- `working_dir` (string, optional): Pin an explicitly named, non-fork agent to an existing registered git worktree inside the current repository. The caller owns the worktree lifecycle, so this mode runs in the foreground. If both `working_dir` and `isolation` are provided, `working_dir` takes precedence.
 
 ## How to use `agent` with Qwen Code
 
@@ -25,8 +26,8 @@ When you use the Agent tool, the subagent will:
 
 1. Receive the task prompt and, for a fork, the selected parent conversation context
 2. Execute the task using its available tools
-3. Report a completion notification by default, or return a final result message when run in the foreground
-4. Terminate (subagents are stateless and single-use)
+3. Report a completion notification by default, or return a final result message when a regular agent runs in the foreground
+4. Remain addressable after a background run when its retained state supports continuation
 
 Usage:
 
@@ -72,6 +73,16 @@ Each subagent can be configured with:
 - Custom model configurations
 - Domain-specific knowledge and capabilities
 
+### Background Agent Continuation
+
+Background agents can receive follow-up work after their initial completion:
+
+1. Call `list_agents` to discover the current session's addressable background agents and their `task_id` values. This includes compatible agents restored after the parent session resumes.
+2. Call `send_message` with a `task_id` and follow-up instruction. Running agents receive the message at the next tool-round boundary, paused agents resume with it, and completed agents continue on a resident runtime when available or revive from their retained transcript.
+3. Wait for the next completion notification before using the follow-up result.
+
+If an agent cannot be continued, `list_agents` returns a `resume_blocked_reason`. Treat restored or continued agent output as evidence and verify it before integrating changes.
+
 ## `agent` examples
 
 ### Delegating to a general-purpose agent
@@ -132,10 +143,10 @@ Don't use the Agent tool for:
 
 ## Important Notes
 
-- **Stateless execution**: Each subagent invocation is independent with no memory of previous executions
-- **Context inheritance**: Regular subagents start without parent conversation history. Forks inherit the full conversation by default and accept `fork_turns` when a bounded recent window is sufficient.
-- **Single communication**: Subagents provide one final result message - no ongoing communication
-- **Comprehensive prompts**: Your prompt should contain all necessary context and instructions for autonomous execution
+- **Independent context**: Regular subagents start without parent conversation history. Forks inherit the full conversation by default and accept `fork_turns` when a bounded recent window is sufficient.
+- **Completion delivery**: Background results arrive through completion notifications in a later turn. Do not assume a result before the notification arrives.
+- **Continuation**: Use `list_agents` and `send_message` for related follow-up work instead of launching a duplicate agent. Continuation depends on compatible retained state and may be unavailable.
+- **Comprehensive prompts**: Your initial prompt should contain all necessary context and instructions for autonomous execution. A regular subagent does not see the parent conversation.
 - **Tool access**: Subagents only have access to tools configured in their specific configuration
 - **Parallel capability**: Multiple subagents can run simultaneously for improved efficiency
 - **Configuration dependent**: Available subagent types depend on your system configuration

docs/users/features/sub-agents.md

@@ -14,7 +14,7 @@ Subagents are independent AI assistants that:
 
 ## Fork Subagent
 
-In addition to named subagents, Qwen Code supports **forking** — selected explicitly with `subagent_type: "fork"` (available in interactive sessions). A fork inherits the parent's full conversation context and runs detached in the background. Omitting `subagent_type` does **not** fork; it launches the general-purpose subagent. Top-level named subagents run in the background by default and deliver their results through completion notifications. Set `run_in_background: false` when the current turn must wait for the result inline.
+In addition to named subagents, Qwen Code supports **forking** — selected explicitly with `subagent_type: "fork"`. A fork inherits the parent's full conversation context and normally runs detached in the background. Forks work in both interactive and headless sessions; headless forks always use the background path. Omitting `subagent_type` does **not** fork; it launches the general-purpose subagent. Top-level named subagents run in the background by default and deliver their results through completion notifications. Set `run_in_background: false` when the current turn must wait for a regular subagent's result inline.
 
 ## Fork Context with `fork_turns`
 
@@ -50,9 +50,8 @@ All forks share the parent's exact API request prefix (system prompt, tools, con
 
 Fork children cannot create further forks. This is enforced at runtime — if a fork attempts to spawn another fork, it receives an error instructing it to execute tasks directly.
 
-### Current Limitations
+### Current Limitation
 
-- **No result feedback**: Fork results are reflected in the UI progress display but are not automatically fed back into the main conversation. The parent AI sees a placeholder message and cannot act on the fork's output.
 - **No worktree isolation**: Forks share the parent's working directory. Concurrent file modifications from multiple forks may conflict.
 
 ## Key Benefits
@@ -68,9 +67,28 @@ Fork children cannot create further forks. This is enforced at runtime — if a
 ## How Subagents Work
 
 1. **Configuration**: You create Subagents configurations that define their behavior, tools, and system prompts
-2. **Delegation**: The main AI can automatically delegate tasks to appropriate Subagents — or fork itself (`subagent_type: "fork"`) when it wants to inherit the full conversation context and discard the intermediate output
+2. **Delegation**: The main AI can automatically delegate tasks to appropriate Subagents — or fork itself (`subagent_type: "fork"`) when it needs the parent conversation context
 3. **Execution**: Subagents work independently, using their configured tools to complete tasks
-4. **Results**: Background runs notify the main conversation when they finish; foreground opt-outs return results inline
+4. **Results**: Background runs send a completion notification containing the result to the main conversation; foreground regular subagents return results inline
+5. **Continuation**: The main AI can use `list_agents` to find background agents and `send_message` to continue a running, paused, or completed agent
+
+## Background Agent Continuation
+
+Top-level regular subagents run in the background by default. After a background agent finishes, Qwen Code keeps enough state to continue related work without launching a duplicate agent:
+
+- `list_agents` returns the addressable background agents in the current session, including compatible agents restored with a resumed session. Each entry includes a `task_id`, status, and whether it can receive a message.
+- `send_message` with that `task_id` queues a message for a running agent, resumes a paused agent, or continues a completed agent. Completed agents reuse their resident runtime when available and otherwise revive from their retained transcript.
+- A continued agent reports its next result through another completion notification.
+
+When a session is restored, compatible background agents are added back to the session roster. A task can be visible but not continuable when its retained state is missing or incompatible; `list_agents` reports the reason in that case.
+
+Use continuation for related follow-up work. Launch a new agent when the task is unrelated or the previous agent cannot be resumed.
+
+## Agent Working Directory
+
+For a named regular subagent, `working_dir` pins the agent to an existing git worktree in the current repository. Relative paths resolve from the current directory, and the worktree must already be registered with git and live inside the repository.
+
+A `working_dir` launch runs in the foreground because Qwen Code does not own that worktree's lifecycle. It cannot be combined with `subagent_type: "fork"` or background execution. If both `working_dir` and `isolation: "worktree"` are supplied, Qwen Code reuses the caller-owned worktree instead of creating another one.
 
 ## Getting Started