fix(agent-core-v2): keep background questions open past turn end (#308)

## Related Issue

No tracked issue — internal reconciliation pass. Stacked on #307; review
that one first (and #306 under it).

## Problem

A background `AskUserQuestion` (asked with `background: true`) was bound
to the asking turn: the moment the agent finished its turn, the question
was cancelled and the user never got to answer it. When a background
question *was* answered, the agent received only the path of a saved
output file, not the answer itself.

## What changed

- Detached question requests no longer carry the asking turn's id, and
turn-end cancellation leaves them pending; the question stays open until
the user answers or dismisses it.
- The answer is now delivered to the agent inline in the task
notification — bounded to 16 KB and XML-escaped inside an `<answer>`
block — instead of only a saved output path. Answered and dismissed
outcomes get distinct notification text, and the transcript projection
keeps background-question answers grouped with their turn.
- `docs/reference/tools.md` documents the `background` behaviour on
`AskUserQuestion`; two patch changesets included.
- `dist-web` manifest restaged in the same commit (`packages/transcript`
is a web build input; only `.web-bundle-manifest.json` changed).

Verification on this commit: full pre-push gate (597s, all checks
passed), agent-core-v2 suite green, typecheck 0, lint 0, leak-check A–G
PASS.

## Checklist

- [x] I have read the
[CONTRIBUTING](https://github.com/PyModel/pythinker-code/blob/main/CONTRIBUTING.md)
document.
- [ ] I have linked a related issue (external PRs: the issue must have a
maintainer's `/approve`).
- [x] I have added tests that prove my feature works.
- [x] Ran `gen-changesets` skill, or this PR needs no changeset.
- [x] Ran `gen-docs` skill, or this PR needs no doc update.

Author: elkaix

.changeset/background-question-inline-answer.md

@@ -0,0 +1,5 @@
+---
+"@pymodel/pythinker-code": patch
+---
+
+Deliver background question answers to the agent directly instead of via a saved output file.

.changeset/background-question-survives-turn-end.md

@@ -0,0 +1,5 @@
+---
+"@pymodel/pythinker-code": patch
+---
+
+Fix background questions being cancelled as soon as the agent finishes its turn.

apps/pythinker-code/dist-web/.web-bundle-manifest.json

@@ -1,4 +1,4 @@
 {
-  "sourceHash": "0670132fd6ebf38fbe6620f3f406ab07bcd253ce8fe8c89e34558d03fd2a4d0f",
+  "sourceHash": "60e31323838a7481743f77ddfb9d3e4ed318a1f3b46e1ebf55cb27305899b535",
   "sourceFileCount": 493
 }

docs/reference/tools.md

@@ -95,13 +95,13 @@ Collaboration tools handle inter-Agent coordination, user interaction, and Skill
 
 **`AgentDynamicWorkflow`** launches subagents from a shared `prompt_template` and an `items` array, resumes existing subagents through `resume_agent_ids`, or combines both in one call. The template must contain the `{{item}}` placeholder; each item replaces that placeholder and launches one new subagent. Pass `subagent_type` to choose the profile used by every spawned subagent in the dynamic_workflow, or omit it to use `coder`. Pass `model` (available when [secondary-model routing](../configuration/config-files.md#subagent-model-pool) is enabled and a pool is configured — a `[secondary_model.models]` table or a lone `default_model`) to run item-spawned subagents on a pool alias or on the caller's own model (`"primary"`). Without it, item-spawned subagents bind the pool's `default_model`; without a configured pool, they inherit the caller's model. Resumed subagents keep their own model. Without `resume_agent_ids`, the tool requires at least 2 items; with `resume_agent_ids`, it can resume one or more existing subagents. The tool supports up to 128 total subagents, waits for all subagents to finish, and returns an aggregated report. Each subagent times out after 2 hours by default; configure the limit with [`[dynamic_workflow] timeout_ms`](../configuration/config-files.md#dynamic-workflow) in `config.toml` (`0` means no timeout) or the `PYTHINKER_CODE_AGENT_DYNAMIC_WORKFLOW_TIMEOUT_MS` environment variable. Print mode (`pythinker -p`) defaults to no timeout. A timed-out subagent is aborted and marked as failed in the aggregated report. In the TUI, foreground dynamicWorkflows show a live `Agent dynamic_workflow` progress panel above the input box. If a model response calls `AgentDynamicWorkflow`, that call must be the only tool call in the response; to run multiple dynamicWorkflows, call one `AgentDynamicWorkflow`, wait for its result, then call the next, or combine the work into one dynamic_workflow when a single template can cover it. In `manual` permission mode, `AgentDynamicWorkflow` calls outside active dynamic_workflow mode request approval unless a permission rule allows them; while dynamic_workflow mode is active, `AgentDynamicWorkflow` itself is auto-approved. Permission rules match `AgentDynamicWorkflow` by tool name only — argument patterns such as `AgentDynamicWorkflow(dynamic_workflow)` are not supported. By default the tool ramps up concurrency without an upper limit (5 subagents start immediately, then 1 more every 700 ms); set `[dynamic_workflow] max_concurrency` or `PYTHINKER_CODE_AGENT_DYNAMIC_WORKFLOW_MAX_CONCURRENCY` to a positive integer to cap how many subagents run at the same time across all execution phases. An invalid environment value makes the call fail fast.
 
-**`AskUserQuestion`** asks the user a structured multiple-choice question — useful for disambiguation or option selection. The `questions` parameter accepts 1–4 questions; each question requires `question` (ending with `?`), `options` (2–4 choices, each with a `label` and `description`), and optional `header` (max 12 characters) and `multi_select` (defaults to false). An "Other" option is appended automatically. Setting `background` to true starts a background question task and returns a task ID immediately. When the host does not support interactive questioning, a failure message is returned and the Agent should ask the user directly in a text reply instead.
+**`AskUserQuestion`** asks the user a structured multiple-choice question — useful for disambiguation or option selection. The `questions` parameter accepts 1–4 questions; each question requires `question` (ending with `?`), `options` (2–4 choices, each with a `label` and `description`), and optional `header` (max 12 characters) and `multi_select` (defaults to false). An "Other" option is appended automatically. Setting `background` to true starts a background question task and returns a task ID immediately; the question stays open after the turn ends, and the answer is delivered to the Agent as a notification once the user responds. When the host does not support interactive questioning, a failure message is returned and the Agent should ask the user directly in a text reply instead.
 
 **`Skill`** allows the Agent to actively invoke a registered inline-type Skill. Accepts `skill` (the Skill name) and optional `args` (additional argument text). Only `type = "inline"` Skills can be called via this tool; Skills with `disableModelInvocation: true` are rejected. Maximum nesting depth is 3 levels. See [Agent Skills](../customization/skills.md) for details.
 
 ## Background Tasks
 
-Background task tools manage tasks started via `Bash`, `Agent`, or `AskUserQuestion`. When a task reaches a terminal state, its status and saved output path are automatically delivered back to the Agent; use `TaskOutput` to check progress early, or `WaitFor` to wait for a result inside the current turn.
+Background task tools manage tasks started via `Bash`, `Agent`, or `AskUserQuestion`. When a task reaches a terminal state, its status and saved output path (or, for questions, the answer itself) are automatically delivered back to the Agent; use `TaskOutput` to check progress early, or `WaitFor` to wait for a result inside the current turn.
 
 | Tool | Default Approval | Description |
 | --- | --- | --- |

packages/agent-core-v2/src/agent/task/taskService.ts

@@ -13,7 +13,7 @@ import {
   userCancellationReason,
 } from '#/_base/utils/abort';
 import { setClampedTimeout } from '#/_base/utils/timer';
-import { escapeXml, escapeXmlAttr } from '#/_base/utils/xml-escape';
+import { escapeXml, escapeXmlAttr, escapeXmlTags } from '#/_base/utils/xml-escape';
 import { IEventBus, ISessionEventBus } from '#/app/event/eventBus';
 import { Error2, ErrorCodes } from '#/errors';
 import { z } from 'zod';
@@ -166,6 +166,7 @@ const SIGTERM_GRACE_MS = 5_000;
 const TASK_ID_ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz';
 const SESSION_CLOSED_REASON = 'Session closed';
 const NOTIFICATION_FALLBACK_PREVIEW_BYTES = 3_000;
+const QUESTION_ANSWER_INLINE_BYTES = 16_000;
 const ACTIVE_BACKGROUND_TASK_INJECTION_VARIANT = 'background_task_status';
 const TASK_RESUME_TERMINATION_VARIANT = 'task_resume_termination';
 const ACTIVE_BACKGROUND_TASK_GUIDANCE = [
@@ -1286,10 +1287,7 @@ export class AgentTaskService extends Disposable implements IAgentTaskService {
     try {
       let output = emptyOutputSnapshot();
       try {
-        output = await this.getOutputSnapshot(info.taskId, 0);
-        if (!output.fullOutputAvailable) {
-          output = await this.getOutputSnapshot(info.taskId, NOTIFICATION_FALLBACK_PREVIEW_BYTES);
-        }
+        output = await this.notificationOutputSnapshot(info);
       } catch (error) {
         this.log.error('task notification output read failed; delivering without output', {
           taskId: info.taskId,
@@ -1301,10 +1299,7 @@ export class AgentTaskService extends Disposable implements IAgentTaskService {
       if (this.deliveredNotificationKeys.has(key)) return undefined;
       if (this.hasDeliveredNotification(key)) return undefined;
       this.scheduledNotificationKeys.add(key);
-      const notification = buildAgentTaskNotification(
-        info,
-        agentTaskNotificationChildren(output),
-      );
+      const notification = buildAgentTaskNotification(info, output);
       const content = [
         {
           type: 'text',
@@ -1317,6 +1312,15 @@ export class AgentTaskService extends Disposable implements IAgentTaskService {
     }
   }
 
+  private async notificationOutputSnapshot(info: AgentTaskInfo): Promise<AgentTaskOutputSnapshot> {
+    if (info.kind === 'question') {
+      return this.getOutputSnapshot(info.taskId, QUESTION_ANSWER_INLINE_BYTES);
+    }
+    const persisted = await this.getOutputSnapshot(info.taskId, 0);
+    if (persisted.fullOutputAvailable) return persisted;
+    return this.getOutputSnapshot(info.taskId, NOTIFICATION_FALLBACK_PREVIEW_BYTES);
+  }
+
   private fireNotificationHook(notification: AgentTaskNotification): void {
     if (!this.lifecycleActive()) return;
     void this.dispatcher.dispatch(
@@ -1417,15 +1421,64 @@ function emptyOutputSnapshot(): AgentTaskOutputSnapshot {
 }
 
 function agentTaskNotificationChildren(
-  output: AgentTaskOutputSnapshot,
+  info: AgentTaskInfo,
+  output: AgentTaskOutputSnapshot | undefined,
 ): readonly string[] | undefined {
+  if (output === undefined) return undefined;
+  if (inlinesQuestionAnswer(info, output)) {
+    return output.preview.length === 0 ? undefined : [renderAnswerBlock(output.preview)];
+  }
   if (output.fullOutputAvailable && output.outputPath !== undefined) {
     return [renderOutputFileBlock(output.outputPath, output.outputSizeBytes)];
   }
   if (output.preview.length === 0) return undefined;
   return [renderOutputPreviewBlock(output)];
 }
 
+function inlinesQuestionAnswer(info: AgentTaskInfo, output: AgentTaskOutputSnapshot): boolean {
+  return info.kind === 'question' && !output.truncated;
+}
+
+function renderAnswerBlock(answer: string): string {
+  return ['<answer>', escapeXmlTags(answer), '</answer>'].join('\n');
+}
+
+function questionNotificationText(
+  info: AgentTaskInfo,
+  output: AgentTaskOutputSnapshot | undefined,
+): { readonly title: string; readonly body: string } | undefined {
+  if (info.status !== 'completed' || output === undefined || !inlinesQuestionAnswer(info, output)) {
+    return undefined;
+  }
+  const outcome = questionOutcome(output.preview);
+  if (outcome === 'answered') {
+    return {
+      title: 'Background question answered',
+      body: `The user answered "${info.description}".`,
+    };
+  }
+  if (outcome === 'dismissed') {
+    return {
+      title: 'Background question dismissed',
+      body: `The user dismissed "${info.description}" without answering.`,
+    };
+  }
+  return undefined;
+}
+
+function questionOutcome(output: string): 'answered' | 'dismissed' | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(output);
+  } catch {
+    return undefined;
+  }
+  if (typeof parsed !== 'object' || parsed === null) return undefined;
+  const answers = (parsed as { readonly answers?: unknown }).answers;
+  if (typeof answers !== 'object' || answers === null || Array.isArray(answers)) return undefined;
+  return Object.keys(answers).length > 0 ? 'answered' : 'dismissed';
+}
+
 function renderOutputFileBlock(outputPath: string, outputSizeBytes: number): string {
   return [
     `<output-file path="${escapeXmlAttr(outputPath)}" bytes="${String(outputSizeBytes)}">`,
@@ -1532,19 +1585,20 @@ function buildAgentTaskNotificationBody(info: AgentTaskInfo): string {
 
 function buildAgentTaskNotification(
   info: AgentTaskInfo,
-  children?: readonly string[],
+  output?: AgentTaskOutputSnapshot,
 ): AgentTaskNotification {
+  const question = questionNotificationText(info, output);
   return {
     id: taskNotificationId(info.taskId, info.status),
     category: 'task',
     type: `task.${info.status}`,
     source_kind: 'background_task',
     source_id: info.taskId,
     agent_id: info.kind === 'agent' ? info.agentId : undefined,
-    title: `Background ${info.kind} ${info.status}`,
+    title: question?.title ?? `Background ${info.kind} ${info.status}`,
     severity: info.status === 'completed' ? 'info' : 'warning',
-    body: buildAgentTaskNotificationBody(info),
-    children,
+    body: question?.body ?? buildAgentTaskNotificationBody(info),
+    children: agentTaskNotificationChildren(info, output),
   };
 }
 

packages/agent-core-v2/src/agent/tools/ask-user-question/askUserQuestionTool.ts

@@ -140,13 +140,8 @@ export class AskUserQuestionTool implements IAskUserQuestionTool {
       isError: false,
       output:
         `task_id: ${taskId}\n` +
-        `description: ${description}\n` +
         `status: ${status}\n` +
-        `automatic_notification: true\n` +
-        'next_step: Continue your current work; the answer will arrive automatically when the user responds.\n' +
-        'next_step: Use TaskOutput with this task_id for a non-blocking status/answer snapshot.\n' +
-        'next_step: Use TaskStop only if the question should be cancelled.\n' +
-        'human_shell_hint: The pending question is also visible in the client UI.',
+        'next_step: Continue your work; the answer arrives automatically in a later message. Use TaskStop only to cancel the question.',
     };
   }
 
@@ -174,7 +169,7 @@ export class AskUserQuestionTool implements IAskUserQuestionTool {
             multiSelect: q.multi_select,
           })),
         },
-        { signal, agentId: this.scopeContext.agentId },
+        { signal, agentId: this.scopeContext.agentId, detached: args.background === true },
       );
 
       const normalized = normalizeQuestionResult(result);

packages/agent-core-v2/src/agent/tools/ask-user-question/question-background-task.ts

@@ -42,6 +42,10 @@ export class QuestionBackgroundTask implements AgentTask {
       const result = await this.run(sink.signal);
       const output =
         typeof result.output === 'string' ? result.output : JSON.stringify(result.output);
+      if (result.isError === true) {
+        await sink.settle({ status: 'failed', stopReason: output });
+        return;
+      }
       sink.appendOutput(output);
       await sink.settle({ status: 'completed' });
     } catch (error: unknown) {

packages/agent-core-v2/src/features/interaction/interaction.ts

@@ -20,6 +20,19 @@ export interface Interaction<TPayload = unknown> {
   readonly createdAt: number;
 }
 
+export type InteractionCancellationReason = 'turn_ended' | 'agent_closed';
+
+export interface InteractionCancellation {
+  readonly cancelled: true;
+  readonly reason: InteractionCancellationReason;
+}
+
+export function isInteractionCancellation(response: unknown): response is InteractionCancellation {
+  if (typeof response !== 'object' || response === null) return false;
+  const value = response as { readonly cancelled?: unknown; readonly reason?: unknown };
+  return value.cancelled === true && (value.reason === 'turn_ended' || value.reason === 'agent_closed');
+}
+
 export interface InteractionResolution {
   readonly id: string;
   readonly response: unknown;

packages/agent-core-v2/src/session/question/question.ts

@@ -38,7 +38,7 @@ export interface ISessionQuestionService {
 
   request(
     req: QuestionRequest,
-    options?: { signal?: AbortSignal; agentId?: string },
+    options?: { signal?: AbortSignal; agentId?: string; detached?: boolean },
   ): Promise<QuestionResult>;
   enqueue(req: QuestionRequest): QuestionRequest & { readonly id: string };
   answer(id: string, result: QuestionResult): void;

packages/agent-core-v2/src/session/question/questionService.ts

@@ -4,6 +4,7 @@ import { LifecycleScope } from '#/app/scopes';
 
 import { ScopeActivation, registerScopedService } from '#/_base/di/scope';
 import { IAgentLifecycleService } from '#/session/agentLifecycle/agentLifecycle';
+import { isInteractionCancellation } from '#/features/interaction/interaction';
 import {
   enqueueSessionInteraction,
   listSessionPendingInteractions,
@@ -22,14 +23,20 @@ export class SessionQuestionService implements ISessionQuestionService {
 
   constructor(@IAgentLifecycleService private readonly agents: IAgentLifecycleService) {}
 
-  request(req: QuestionRequest, options?: { signal?: AbortSignal; agentId?: string }): Promise<QuestionResult> {
+  request(
+    req: QuestionRequest,
+    options?: { signal?: AbortSignal; agentId?: string; detached?: boolean },
+  ): Promise<QuestionResult> {
     const id = requestId(req);
-    const pending = requestSessionInteraction<QuestionRequest, QuestionResult>(this.agents, {
+    const pending = requestSessionInteraction<QuestionRequest, unknown>(this.agents, {
       id,
       kind: 'question',
       payload: req,
-      origin: { turnId: req.turnId, agentId: options?.agentId },
-    });
+      origin: {
+        turnId: options?.detached === true ? undefined : req.turnId,
+        agentId: options?.agentId,
+      },
+    }).then((response) => (isInteractionCancellation(response) ? null : (response as QuestionResult)));
 
     const signal = options?.signal;
     if (signal !== undefined) {