mcp-codex-worker 1.0.5 → 1.0.6

package/src/config/question-guidance.ts

@@ -0,0 +1,77 @@
+/**
+ * Provider-specific question guidance appended to sub-agent prompts at spawn time.
+ *
+ * Codex uses `request_user_input` for gathering user preferences. Command and
+ * file approvals are auto-approved by our pause-flow, so the guidance focuses
+ * on the user_input question type only.
+ *
+ * Policy: ASK when the brief is ambiguous about user-facing choices. The
+ * orchestrator answers promptly. Decide yourself for implementation details.
+ */
+
+const CODEX_GUIDANCE = `
+--- QUESTION POLICY (IMPORTANT — READ BEFORE STARTING) ---
+
+You have access to \`request_user_input\` for gathering user preferences.
+
+**WHEN TO ASK:** The brief is ambiguous about design preferences, visual style, branding,
+colors, naming, scope, content tone, or any user-facing choice where guessing wrong wastes
+significant rework. Ask early — before you start building — so you build the right thing.
+
+**WHEN TO DECIDE YOURSELF:** Implementation details, internal architecture, code patterns,
+folder structure, library choices, refactoring approach, or anything the brief and codebase
+already specify. For these, decide and document your assumption.
+
+**IF YOU DECIDE WITHOUT ASKING:** Document your choice clearly in output
+(e.g. "Assumed modern blue theme since brief didn't specify").
+
+Use \`request_user_input\` with this exact schema:
+
+\`\`\`
+request_user_input({
+  questions: [
+    {
+      header: "Brand",
+      id: "brand_direction",
+      question: "What branding direction should I use?",
+      options: [
+        {
+          label: "Modern Care (Recommended)",
+          description: "Clean, trustworthy clinic branding."
+        },
+        {
+          label: "Luxury Smile",
+          description: "Upscale positioning with premium feel."
+        }
+      ]
+    }
+  ]
+})
+\`\`\`
+
+**Rules:**
+- Recommended option goes FIRST with "(Recommended)" in label
+- Do NOT add an "Other" option — the client adds freeform input automatically
+- Max 3 options per question. Keep labels 1-5 words. Keep descriptions one sentence.
+- Ask ALL ambiguous design questions in one call (batch them), then build.
+`;
+
+const FALLBACK_GUIDANCE = `
+--- QUESTION POLICY ---
+When the brief is ambiguous about design preferences, branding, colors, naming, or scope —
+ask using the question tool if available. The orchestrator answers promptly.
+For implementation details — decide yourself and document your assumption.
+`;
+
+/**
+ * Returns provider-specific question guidance to append to the sub-agent prompt.
+ * Includes full tool schema details so the agent knows the exact format.
+ */
+export function getQuestionGuidance(provider: string): string {
+  switch (provider) {
+    case 'codex':
+      return CODEX_GUIDANCE;
+    default:
+      return FALLBACK_GUIDANCE;
+  }
+}

package/src/execution/base-adapter.ts

@@ -21,6 +21,7 @@ export interface ProviderSpawnOptions {
   timeout: number;
   model?: string;
   effort?: 'low' | 'medium' | 'high' | 'xhigh';
+  developerInstructions?: string;
 }
 
 /**

package/src/execution/codex-adapter.ts

@@ -94,6 +94,7 @@ export class CodexAdapter extends BaseProviderAdapter {
         model: options.model,
         effort: options.effort,
         cwd: options.cwd,
+        developerInstructions: options.developerInstructions,
       });
       const threadResult = await runtime.request('thread/start', threadParams) as {
         thread?: { id?: string };

package/src/index.ts

@@ -95,11 +95,25 @@ async function main(): Promise<void> {
   });
 
   // --- Status changes: task completed, failed, etc. ---
+  // Debounced tool list refresh — dynamic banners in tool descriptions
+  // need to update when tasks enter/leave running/waiting_answer/terminal states.
+  let toolListTimer: ReturnType<typeof setTimeout> | null = null;
+  const scheduleToolListChanged = (): void => {
+    if (toolListTimer) return;
+    toolListTimer = setTimeout(() => {
+      toolListTimer = null;
+      server.sendToolListChanged().catch(() => {});
+    }, 1000);
+    toolListTimer.unref?.();
+  };
+
   taskManager.onStatusChange((task) => {
     const uris = subscriptions.getMatchingSubscriptions(task.id);
     for (const uri of uris) {
       server.sendResourceUpdated({ uri }).catch(() => {});
     }
+    // Refresh tool descriptions so dynamic banners reflect the new state
+    scheduleToolListChanged();
   });
 
   // --- Output changes: new agent messages, command output, diffs ---
@@ -124,6 +138,7 @@ async function main(): Promise<void> {
   process.stdin.resume();
 
   const shutdown = async () => {
+    if (toolListTimer) clearTimeout(toolListTimer);
     await app.shutdown().catch(() => {});
     process.exit(0);
   };

package/src/mcp/next-action-guidance.ts

@@ -1,11 +1,35 @@
 import { TaskStatus, isTerminalStatus } from '../task/task-state.js';
 import type { TaskState, PendingQuestion } from '../task/task-state.js';
 
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function outputPath(task: TaskState): string {
+  return task.outputFilePath ?? `~/.mcp-codex-worker/tasks/${task.id}/summary.log`;
+}
+
+function sleepEscalation(): string {
+  return 'If the agent is still running after your first check, escalate wait times: `sleep 60`, then `sleep 90`, `sleep 120`, `sleep 150`, up to `sleep 180` max.';
+}
+
+function wcHint(task: TaskState): string {
+  return `Quick progress check: \`wc -l ${outputPath(task)}\` — a growing line count means the agent is still working.`;
+}
+
+function catHint(task: TaskState): string {
+  return `Read the full output: \`cat -n ${outputPath(task)}\` (use \`tail -n +<N>\` on subsequent reads to skip already-read lines).`;
+}
+
+// ---------------------------------------------------------------------------
+// Per-tool guidance builders
+// ---------------------------------------------------------------------------
+
 /**
- * Generate context-aware "what to do next" guidance based on task state.
- * Returned as markdown lines that get appended to tool response text.
+ * Guidance appended to spawn-task responses.
+ * Goal: tell the orchestrator to launch more tasks, then wait, use wc -l.
  */
-export function buildNextActionGuidance(task: TaskState): string[] {
+export function buildSpawnGuidance(task: TaskState): string[] {
   const lines: string[] = ['', '---', '**What to do next:**'];
 
   switch (task.status) {
@@ -13,18 +37,19 @@ export function buildNextActionGuidance(task: TaskState): string[] {
     case TaskStatus.RUNNING:
     case TaskStatus.RATE_LIMITED:
       lines.push(
-        `- Call \`wait-task\` with \`task_id: "${task.id}"\` to block until the agent finishes, fails, or needs input.`,
-        '- If you have more tasks to launch, launch them now — all agents run in parallel.',
-        `- To check progress mid-flight: read MCP resource \`task:///${task.id}\` or run \`wc -l ${task.outputFilePath ?? '~/.mcp-codex-worker/tasks/' + task.id + '/summary.log'}\`.`,
+        '- If you still have more agents to launch, launch them now — all agents run in parallel.',
+        `- Once all agents are launched, call \`wait-task\` with \`task_id: "${task.id}"\` (or run \`sleep 30\` then read \`task:///${task.id}\`).`,
+        `- ${wcHint(task)}`,
         '- Read `task:///all` for a scoreboard of all tasks.',
+        `- \`waiting_answer\` → agent needs input — answer via \`respond-task\`.`,
+        `- ${sleepEscalation()}`,
       );
       break;
 
     case TaskStatus.WAITING_ANSWER:
-      lines.push('- **ACTION REQUIRED** — the agent is paused and waiting for your input.');
+      lines.push('- **ACTION REQUIRED** — the agent paused immediately and is waiting for your input.');
       if (task.pendingQuestions.length > 0) {
-        const pq = task.pendingQuestions[0]!;
-        lines.push(...formatPendingQuestionGuidance(task.id, pq));
+        lines.push(...formatPendingQuestionGuidance(task.id, task.pendingQuestions[0]!));
       }
       lines.push(`- After responding, call \`wait-task\` with \`task_id: "${task.id}"\` to resume monitoring.`);
       break;
@@ -32,8 +57,8 @@ export function buildNextActionGuidance(task: TaskState): string[] {
     case TaskStatus.COMPLETED:
       lines.push(
         '- The agent finished successfully.',
+        `- ${catHint(task)}`,
         `- Read \`task:///${task.id}\` for the full result detail.`,
-        `- Read \`task:///${task.id}/log\` for the execution summary.`,
         `- Use \`message-task\` with \`task_id: "${task.id}"\` to send follow-up instructions on the same session.`,
       );
       break;
@@ -42,8 +67,8 @@ export function buildNextActionGuidance(task: TaskState): string[] {
     case TaskStatus.TIMED_OUT:
       lines.push(
         `- The agent failed: ${task.error ?? 'unknown error'}`,
+        `- ${catHint(task)}`,
         `- Read \`task:///${task.id}/events\` for the raw event trace to diagnose the failure.`,
-        `- Read \`task:///${task.id}/log\` for the execution summary up to the failure point.`,
         '- To retry: spawn a new task with the same prompt. The failed task\'s logs are preserved on disk.',
       );
       if (task.error?.includes('AUTH_TOKEN_EXPIRED')) {
@@ -51,28 +76,141 @@ export function buildNextActionGuidance(task: TaskState): string[] {
       }
       break;
 
-    case TaskStatus.CANCELLED:
-      lines.push(
-        '- The task was cancelled.',
-        `- Read \`task:///${task.id}/log\` to see what was accomplished before cancellation.`,
-      );
+    default:
       break;
+  }
 
-    case TaskStatus.UNKNOWN:
-      lines.push(
-        '- This task was recovered after a server restart. The original session is lost.',
-        `- Read \`task:///${task.id}/log\` to see what was accomplished before the restart.`,
-        '- To continue the work: spawn a new task with the same prompt.',
-      );
-      break;
+  return lines;
+}
 
-    default:
-      break;
+/**
+ * Guidance appended to wait-task responses.
+ * Three branches: terminal, waiting_answer, still working.
+ */
+export function buildWaitGuidance(task: TaskState): string[] {
+  const lines: string[] = ['', '---'];
+
+  if (isTerminalStatus(task.status)) {
+    // Terminal state — task is done
+    const statusLabel = task.status === TaskStatus.COMPLETED ? 'completed successfully'
+      : task.status === TaskStatus.CANCELLED ? 'was cancelled'
+      : `failed: ${task.error ?? 'unknown error'}`;
+    lines.push(`**Task ${statusLabel}.**`);
+    lines.push(
+      `- ${catHint(task)}`,
+      `- Read \`task:///${task.id}\` for the full result detail.`,
+      `- Read \`task:///${task.id}/log\` for the execution summary.`,
+    );
+    if (task.status === TaskStatus.COMPLETED) {
+      lines.push(`- Use \`message-task\` with \`task_id: "${task.id}"\` to send follow-up instructions on the same session.`);
+    } else {
+      lines.push('- To retry: spawn a new task with the same prompt.');
+      if (task.status === TaskStatus.FAILED || task.status === TaskStatus.TIMED_OUT) {
+        lines.push(`- Read \`task:///${task.id}/events\` for the raw event trace to diagnose the failure.`);
+      }
+    }
+    if (task.error?.includes('AUTH_TOKEN_EXPIRED')) {
+      lines.push('- **Auth fix required:** run `codex auth login` to refresh your token, then retry.');
+    }
+    return lines;
+  }
+
+  if (task.status === TaskStatus.WAITING_ANSWER) {
+    lines.push('**ACTION REQUIRED** — the agent is paused and waiting for your input.');
+    if (task.pendingQuestions.length > 0) {
+      lines.push(...formatPendingQuestionGuidance(task.id, task.pendingQuestions[0]!));
+    }
+    lines.push(`- After responding, call \`wait-task\` with \`task_id: "${task.id}"\` to resume monitoring.`);
+    return lines;
   }
 
+  // Still working — wait timed out
+  lines.push('**Task is still working.**');
+  lines.push(
+    `- Call \`wait-task\` again with \`task_id: "${task.id}"\` and a longer \`timeout_ms\`.`,
+    `- ${wcHint(task)}`,
+    '- If you have other tasks to check, check them now and come back to this one.',
+    '- Read `task:///all` for the full scoreboard.',
+    `- ${sleepEscalation()}`,
+  );
+
+  return lines;
+}
+
+/**
+ * Guidance appended to respond-task responses.
+ * Two branches: task resumed (working), task already terminal.
+ */
+export function buildRespondGuidance(task: TaskState): string[] {
+  const lines: string[] = ['', '---'];
+
+  if (isTerminalStatus(task.status)) {
+    lines.push(`**Task is no longer running** (status: ${task.status}).`);
+    lines.push(
+      '- The task reached a terminal state. The response could not be delivered.',
+      `- ${catHint(task)}`,
+      `- Read \`task:///${task.id}/log\` to see what was accomplished.`,
+      '- To retry: spawn a new task with the same prompt.',
+    );
+    return lines;
+  }
+
+  lines.push('**Answer submitted — the agent is resuming work.**');
+  lines.push(
+    '- Run `sleep 30` and then check status.',
+    `- To check: call \`wait-task\` with \`task_id: "${task.id}"\`, or read \`task:///${task.id}\`.`,
+    `- ${wcHint(task)}`,
+    `- ${sleepEscalation()}`,
+  );
+
+  return lines;
+}
+
+/**
+ * Guidance appended to message-task responses.
+ * The task just received a follow-up turn and is back to RUNNING.
+ */
+export function buildMessageGuidance(task: TaskState): string[] {
+  return [
+    '', '---',
+    '**Message sent — the agent is resuming work.**',
+    `- Call \`wait-task\` with \`task_id: "${task.id}"\` to block until the agent finishes or needs input.`,
+    `- ${wcHint(task)}`,
+    `- ${sleepEscalation()}`,
+  ];
+}
+
+/**
+ * Guidance appended to cancel-task responses.
+ */
+export function buildCancelGuidance(summary: {
+  cancelled: string[];
+  alreadyTerminal: string[];
+  notFound: string[];
+}): string[] {
+  const lines: string[] = ['', '---', '**What to do next:**'];
+
+  if (summary.cancelled.length > 0) {
+    lines.push(`- Cancelled ${summary.cancelled.length} task(s). Read \`task:///{id}/log\` for partial output of each.`);
+  }
+  if (summary.alreadyTerminal.length > 0) {
+    lines.push(`- ${summary.alreadyTerminal.length} task(s) were already in a terminal state.`);
+  }
+  if (summary.notFound.length > 0) {
+    lines.push(`- ${summary.notFound.length} task ID(s) not found: ${summary.notFound.join(', ')}`);
+  }
+  lines.push(
+    '- Read `task:///all` for the updated scoreboard.',
+    '- To resume cancelled work, spawn new tasks with the same prompts.',
+  );
+
   return lines;
 }
 
+// ---------------------------------------------------------------------------
+// Pending question formatting (shared helper)
+// ---------------------------------------------------------------------------
+
 function formatPendingQuestionGuidance(taskId: string, pq: PendingQuestion): string[] {
   const lines: string[] = [];
 

package/src/mcp/resource-renderers.ts

@@ -98,6 +98,42 @@ export function renderScoreboard(tasks: TaskState[]): string {
     lines.push(`${badge} ${task.id} -- "${prompt}" (${elapsed})`);
   }
 
+  // Footer with quick-reference instructions
+  lines.push('');
+  lines.push('> Details: `task:///{id}` · Logs: `cat -n <output_file>` · Poll: read `task:///all` every ~30s');
+
+  // Pending Questions section
+  const tasksWithQuestions = tasks.filter(t => t.pendingQuestions.length > 0);
+  if (tasksWithQuestions.length > 0) {
+    lines.push('');
+    lines.push(`## Pending Questions (${tasksWithQuestions.length})`);
+
+    for (const task of tasksWithQuestions) {
+      const pq = task.pendingQuestions[0]!;
+      lines.push('');
+      lines.push(`### ${task.id}`);
+      lines.push('');
+
+      if (pq.type === 'user_input') {
+        for (const q of pq.questions) {
+          lines.push(`**Q:** ${q.text}`);
+          if (q.options && q.options.length > 0) {
+            for (let i = 0; i < q.options.length; i++) {
+              lines.push(`  ${i + 1}. ${q.options[i]}`);
+            }
+          }
+        }
+        const firstId = pq.questions[0]?.id ?? 'q';
+        lines.push('');
+        lines.push(`Answer: \`respond-task { "task_id": "${task.id}", "type": "user_input", "answers": {"${firstId}": "1"} }\``);
+      } else {
+        lines.push(formatPendingQuestion(pq));
+        lines.push('');
+        lines.push(`Answer: \`respond-task { "task_id": "${task.id}", "type": "${pq.type}", ... }\``);
+      }
+    }
+  }
+
   return lines.join('\n');
 }
 
@@ -147,13 +183,57 @@ export function renderTaskDetail(task: TaskState): string {
   lines.push(`| **Updated** | ${task.updatedAt} |`);
   lines.push('');
 
-  // Pending questions
+  // Pending questions — enhanced ACTION REQUIRED block with exact JSON examples
   if (task.pendingQuestions.length > 0) {
-    lines.push('## Pending Question', '');
-    for (const q of task.pendingQuestions) {
-      lines.push(formatPendingQuestion(q));
+    lines.push('## ACTION REQUIRED — Agent is paused', '');
+
+    for (const pq of task.pendingQuestions) {
+      if (pq.type === 'user_input') {
+        for (let i = 0; i < pq.questions.length; i++) {
+          const q = pq.questions[i]!;
+          lines.push(`### Q${i + 1} [${q.id}] — ${q.text}`);
+          if (q.options && q.options.length > 0) {
+            for (let j = 0; j < q.options.length; j++) {
+              lines.push(`  ${j + 1}. **${q.options[j]}**`);
+            }
+          }
+          lines.push('');
+        }
+
+        // Build concrete call example
+        const answersExample: Record<string, string> = {};
+        for (const q of pq.questions) {
+          answersExample[q.id] = q.options?.length ? '1' : 'YOUR_ANSWER';
+        }
+
+        lines.push('### How to answer', '');
+        lines.push('You **MUST** call the `respond-task` tool now:', '');
+        lines.push('```json');
+        lines.push(JSON.stringify({ task_id: task.id, type: 'user_input', answers: answersExample }, null, 2));
+        lines.push('```', '');
+        lines.push('Answer formats: `"N"` select by number · `"N: detail"` select + context · `"OTHER: text"` freeform', '');
+      } else if (pq.type === 'command_approval') {
+        lines.push(`**Command approval:** \`${pq.command}\``, '');
+        lines.push('```json');
+        lines.push(JSON.stringify({ task_id: task.id, type: 'command_approval', decision: 'accept' }, null, 2));
+        lines.push('```', '');
+      } else if (pq.type === 'file_approval') {
+        lines.push(`**File approval:** ${pq.fileChanges.map(f => f.path).join(', ')}`, '');
+        lines.push('```json');
+        lines.push(JSON.stringify({ task_id: task.id, type: 'file_approval', decision: 'accept' }, null, 2));
+        lines.push('```', '');
+      } else if (pq.type === 'elicitation') {
+        lines.push(`**Elicitation from "${pq.serverName ?? 'unknown'}":** ${pq.message}`, '');
+        lines.push('```json');
+        lines.push(JSON.stringify({ task_id: task.id, type: 'elicitation', action: 'accept' }, null, 2));
+        lines.push('```', '');
+      } else if (pq.type === 'dynamic_tool') {
+        lines.push(`**Dynamic tool:** \`${pq.toolName}\``, '');
+        lines.push('```json');
+        lines.push(JSON.stringify({ task_id: task.id, type: 'dynamic_tool', result: 'your result' }, null, 2));
+        lines.push('```', '');
+      }
     }
-    lines.push('');
   }
 
   // Error

package/src/mcp/tool-definitions.ts

@@ -1,6 +1,8 @@
 import { z } from 'zod';
 
 import { REASONING_OPTIONS } from '../services/reasoning-options.js';
+import type { TaskManager } from '../task/task-manager.js';
+import { buildStatusBanner, buildRespondBanner } from '../services/tool-description-banner.js';
 
 // ---------------------------------------------------------------------------
 // Unified task tool schemas (provider-agnostic)
@@ -105,8 +107,11 @@ const REASONING_DESCRIPTION = [
   'Omit to use the server default from config.',
 ].join('\n');
 
-export function createToolDefinitions(serverVersion?: string): ToolDefinition[] {
+export function createToolDefinitions(serverVersion?: string, taskManager?: TaskManager): ToolDefinition[] {
   const versionTag = serverVersion ? ` (v${serverVersion})` : '';
+  // Compute banners once per tool-list request
+  const statusBanner = taskManager ? buildStatusBanner(taskManager) : '';
+  const respondBanner = taskManager ? buildRespondBanner(taskManager) : '';
   return [
     {
       name: 'spawn-task',
@@ -227,7 +232,7 @@ export function createToolDefinitions(serverVersion?: string): ToolDefinition[]
         '- `dynamic_tool` — return a tool call result via `result`, or an `error` string on failure.',
         '',
         'After responding the task resumes automatically. Follow up with `wait-task` to track the next step.',
-      ].join('\n'),
+      ].join('\n') + (respondBanner ? `\n\n${respondBanner}` : ''),
       inputSchema: objectSchema({
         task_id: { type: 'string', minLength: 1, description: 'ID of the paused task. Must currently be in `waiting_answer`.' },
         type: {
@@ -272,7 +277,7 @@ export function createToolDefinitions(serverVersion?: string): ToolDefinition[]
         'Use this to add instructions to a still-running task, ask a completed task to refine or extend its work, or steer the agent after reviewing partial results. If the task is idle, the session is resumed first; if it is actively running, the message is queued as the next turn.',
         '',
         'After calling, follow up with `wait-task` exactly like after `spawn-task`.',
-      ].join('\n'),
+      ].join('\n') + (statusBanner ? `\n\n${statusBanner}` : ''),
       inputSchema: objectSchema({
         task_id: { type: 'string', minLength: 1, description: 'ID of the task whose session should receive the follow-up.' },
         message: { type: 'string', minLength: 1, description: 'The follow-up instruction or question. Be as specific as the original prompt — reference files and expected behavior.' },
@@ -290,7 +295,7 @@ export function createToolDefinitions(serverVersion?: string): ToolDefinition[]
         'Cancel one or more running tasks.',
         '',
         'Accepts a single task_id or an array. For each running task, asks the provider to abort execution and marks the task `cancelled`. Tasks already in a terminal state are returned under `already_terminal`; unknown ids are returned under `not_found`. Safe to call on a batch — each id is handled independently.',
-      ].join('\n'),
+      ].join('\n') + (statusBanner ? `\n\n${statusBanner}` : ''),
       inputSchema: objectSchema({
         task_id: {
           oneOf: [

package/src/services/fleet-mode.ts

@@ -1,4 +1,5 @@
 import { CODEX_ENABLE_FLEET_ENV } from '../config/defaults.js';
+import { getQuestionGuidance } from '../config/question-guidance.js';
 
 const TRUTHY_VALUES = new Set(['1', 'true', 'yes', 'on']);
 
@@ -27,3 +28,24 @@ export function appendFleetDeveloperInstructions(
   return `${base}\n${FLEET_DEVELOPER_INSTRUCTIONS_SUFFIX}`;
 }
 
+/**
+ * Build the full developerInstructions string for a thread/start call.
+ * Composes: user instructions → question guidance → fleet sentinel.
+ */
+export function buildDeveloperInstructions(
+  userInstructions: string | undefined,
+  provider: string,
+): string | undefined {
+  let base = userInstructions?.trim() ?? '';
+
+  // Append provider-specific question guidance
+  const questionGuidance = getQuestionGuidance(provider);
+  base = base ? `${base}\n${questionGuidance}` : questionGuidance.trim();
+
+  // Append fleet sentinel if enabled
+  if (isFleetModeEnabled()) {
+    base = `${base}\n${FLEET_DEVELOPER_INSTRUCTIONS_SUFFIX}`;
+  }
+
+  return base || undefined;
+}

package/src/services/tool-description-banner.ts

@@ -0,0 +1,116 @@
+/**
+ * Tool Description Banner — embeds live task status into tool descriptions.
+ *
+ * When the orchestrating LLM re-fetches the tool list (via
+ * notifications/tools/list_changed), the description for respond-task,
+ * message-task, and cancel-task includes a compact status footer showing
+ * running/completed/question-pending tasks.
+ *
+ * Hard cap: 500 chars max for the banner to stay within tool description limits.
+ */
+
+import type { TaskManager } from '../task/task-manager.js';
+import { TaskStatus, isTerminalStatus } from '../task/task-state.js';
+
+const BANNER_MAX_CHARS = 500;
+const RECENTLY_TERMINAL_WINDOW_MS = 5 * 60 * 1000; // 5 minutes
+
+/**
+ * Build a compact status banner for message-task and cancel-task descriptions.
+ * Shows: running count, recently completed tasks, tasks needing answers.
+ * Returns '' when nothing to report.
+ */
+export function buildStatusBanner(taskManager: TaskManager): string {
+  const allTasks = taskManager.getAllTasks();
+  if (allTasks.length === 0) return '';
+
+  const now = Date.now();
+  const running: string[] = [];
+  const needsAnswer: string[] = [];
+  const recentlyDone: { id: string; status: string; agoMs: number }[] = [];
+
+  for (const task of allTasks) {
+    if (task.status === TaskStatus.WAITING_ANSWER) {
+      needsAnswer.push(task.id);
+    } else if (task.status === TaskStatus.RUNNING || task.status === TaskStatus.PENDING) {
+      running.push(task.id);
+    } else if (isTerminalStatus(task.status)) {
+      const updatedMs = new Date(task.updatedAt).getTime();
+      const agoMs = now - updatedMs;
+      if (agoMs <= RECENTLY_TERMINAL_WINDOW_MS) {
+        recentlyDone.push({ id: task.id, status: task.status, agoMs });
+      }
+    }
+  }
+
+  if (running.length === 0 && needsAnswer.length === 0 && recentlyDone.length === 0) {
+    return '';
+  }
+
+  const parts: string[] = ['---'];
+
+  // Summary line
+  const summaryParts: string[] = [];
+  if (running.length > 0) summaryParts.push(`${running.length} running`);
+  if (needsAnswer.length > 0) summaryParts.push(`${needsAnswer.length} needs answer`);
+  if (recentlyDone.length > 0) summaryParts.push(`${recentlyDone.length} recently finished`);
+  parts.push(`AGENT STATUS: ${summaryParts.join(' | ')}`);
+
+  // Tasks needing answers
+  for (const id of needsAnswer) {
+    parts.push(`- ${id} [waiting_answer] — use respond-task`);
+  }
+
+  // Recently terminal tasks (most recent first, limit 3)
+  const sorted = recentlyDone.sort((a, b) => a.agoMs - b.agoMs).slice(0, 3);
+  for (const t of sorted) {
+    const ago = t.agoMs < 60_000 ? `${Math.round(t.agoMs / 1000)}s ago` : `${Math.round(t.agoMs / 60_000)}min ago`;
+    parts.push(`- ${t.id} [${t.status}] (${ago})`);
+  }
+
+  parts.push('Read task:///all for full details.');
+
+  let banner = parts.join('\n');
+  if (banner.length > BANNER_MAX_CHARS) {
+    banner = banner.slice(0, BANNER_MAX_CHARS - 3) + '...';
+  }
+  return banner;
+}
+
+/**
+ * Build a status banner specifically for respond-task.
+ * Focuses on tasks with pending questions, showing question text and answer format.
+ * Returns '' when no questions are pending.
+ */
+export function buildRespondBanner(taskManager: TaskManager): string {
+  const tasksWithQuestions = taskManager.getAllTasks()
+    .filter(t => t.status === TaskStatus.WAITING_ANSWER && t.pendingQuestions.length > 0);
+
+  if (tasksWithQuestions.length === 0) return '';
+
+  const parts: string[] = ['---'];
+  parts.push(`ACTION REQUIRED — ${tasksWithQuestions.length} task(s) waiting for your answer:`);
+
+  for (const task of tasksWithQuestions) {
+    const pq = task.pendingQuestions[0]!;
+    if (pq.type === 'user_input' && pq.questions.length > 0) {
+      const firstQ = pq.questions[0]!;
+      let line = `- ${task.id}: "${firstQ.text}"`;
+      if (firstQ.options && firstQ.options.length > 0) {
+        const choiceStr = firstQ.options.map((c, i) => `${i + 1}) ${c}`).join(' ');
+        line += ` Options: ${choiceStr}`;
+      }
+      parts.push(line);
+    } else {
+      parts.push(`- ${task.id}: [${pq.type}]`);
+    }
+  }
+
+  parts.push('Use respond-task { "task_id": "<id>", ... }');
+
+  let banner = parts.join('\n');
+  if (banner.length > BANNER_MAX_CHARS) {
+    banner = banner.slice(0, BANNER_MAX_CHARS - 3) + '...';
+  }
+  return banner;
+}