nox-qwen-agent-cli 1.1.4 → 1.1.6

package/README.md

@@ -22,10 +22,10 @@ PowerShell can also run `.\install.ps1` directly.
 
 ## Configure
 
-Interactive mode asks for a masked API key on every launch. The key remains in
-memory for that process only and is never stored in source code, settings, or
-chat history. Non-interactive `-p` runs read `NOX_API_KEY`,
-`OPENAI_COMPAT_API_KEY`, or `OPENAI_API_KEY`.
+Runs read `NOX_API_KEY`, `OPENAI_COMPAT_API_KEY`, or `OPENAI_API_KEY` when one
+is configured. If no key is configured and a terminal is available, the CLI asks
+for a masked API key. The key remains in memory for that process only and is
+never stored in source code, settings, or chat history.
 
 Linux, macOS, and Termux:
 
@@ -45,6 +45,7 @@ $env:NOX_API_KEY = "your-key"
 qwen
 qwen -m qwen3.7-plus
 qwen -m gpt-5.5 -p "Inspect and test this project."
+qwen --clarify -p "Add authentication."
 qwen --yes --no-stream
 ```
 
@@ -56,8 +57,13 @@ The interactive composer is multiline:
 - Arrow keys, Home, End, Backspace, and Delete edit the message.
 - Multiline clipboard paste is preserved.
 
-Commands: `/plan TASK`, `/image PATH PROMPT`, `/file PATH PROMPT`, `/new`, `/sessions`,
-`/resume SESSION`, `/approval ask|auto`, `/model`, and `/exit`.
+Commands: `/plan TASK`, `/clarify TASK`, `/image PATH PROMPT`, `/file PATH PROMPT`,
+`/new`, `/sessions`, `/resume SESSION`, `/approval ask|auto`, `/model`, and `/exit`.
+
+Use `/clarify TASK` or `--clarify -p "TASK"` when you want the agent to ask
+precise requirements questions first. In clarification mode the agent should
+not edit files or run side-effecting commands; it returns focused questions and
+safe assumptions before implementation.
 
 Images and files are sent as structured OpenAI attachment parts. Their bytes
 are uploaded through the selected provider's file endpoint and are never
@@ -67,8 +73,9 @@ Streaming is enabled by default. Reasoning is shown in a separate Thinking
 section when the provider returns it, and is never mixed into the final answer.
 
 The agent includes bounded file reads, batch reads and writes, tree and text
-search, path metadata, file operations, Git status/diff, and cross-platform
-shell execution. Mutating actions require approval unless `--yes` is used.
+search, path metadata, file operations, Git status/diff, cross-platform shell
+execution, and background terminals for dev servers and long-running commands.
+Mutating actions require approval unless `--yes` is used.
 For substantial tasks the model can call `update_plan`; plan steps and their
 live status are rendered separately from chat and tool output.
 
@@ -77,12 +84,18 @@ live status are rendered separately from chat and tool output.
 The Agent prompt and file tools are maintained centrally. Available workspace
 tools include `file_info`, `list_files`, `search_files`, `find_in_file`,
 `read_file`, `read_lines`, `update_file`, `apply_patch`, `create_file`,
-`delete_file`, `move_file`, `copy_file`, and `make_directory`.
-
-Every Agent run sends fresh runtime context in the system prompt: OS/version,
-processor, Node.js version, workspace root, top-level workspace entries,
-available tools, and approval mode. The prompt includes an explicit Agent
-reminder at startup.
+`delete_file`, `move_file`, `copy_file`, `make_directory`,
+`start_background_terminal`, `read_background_terminal`, and
+`stop_background_terminal`.
+
+Every Agent run sends fresh runtime context in the first user message:
+OS/version, processor, Node.js version, workspace root, top-level workspace
+entries, available tools, and approval mode. The CLI and VS Code extension
+intentionally transport the full Agent instructions by prefixing the first user
+message with `<agent_instructions>`. Every fourth user turn is prefixed with
+`<agent_reminder>` so the model keeps the active workspace and agent role in
+context. This avoids gateways that drop or weaken `system` messages while still
+sending a SHA-256 prompt proof in request metadata.
 
 The file tools enforce workspace-only paths, reject traversal and symlink
 escapes, deny protected secret-looking files by default, detect binary files,

package/agent-system-prompt.js

@@ -28,9 +28,13 @@ Tool-selection rules:
 - Use create_file only when a new file is genuinely required.
 - Use delete_file only when deletion is explicitly required and safe.
 - Use run_shell_command only for commands relevant to the user's task.
+- Use start_background_terminal for long-running commands such as dev servers, watchers, and commands that need later polling.
+- Use read_background_terminal to inspect background output before claiming a server, watcher, or long task is ready.
+- Use stop_background_terminal when a background process is no longer needed or is producing failures.
 - Run focused tests first, followed by the broader suite when appropriate.
 
 File-access rules:
+- A file may be available through an uploaded file id, an attachment in the current request, a client-provided excerpt, workspace tools, a line-range read, or a search result followed by a targeted read.
 - Do not ask the user to upload a file when it is already available in the workspace.
 - Do not read an entire large file when a targeted range is sufficient.
 - Do not invent missing file contents.
@@ -47,8 +51,16 @@ Editing rules:
 Planning rules:
 Use a plan when the task has multiple steps, affects several files, requires investigation, or requires tests.
 
+Clarification rules:
+- If a request is broad, ambiguous, risky, destructive, or missing acceptance criteria, ask concise clarifying questions before changing files or running commands with side effects.
+- Ask only for details that materially affect the implementation, validation, or safety of the task.
+- Keep clarification questions numbered, specific, and limited to five unless the user explicitly asks for a deeper requirements interview.
+- When a reasonable default is safe, state the assumption and continue instead of blocking.
+- If the user explicitly asks for clarification mode, do not execute the task yet; return the questions and the proposed assumptions only.
+
 Progress rules:
 For longer operations, provide brief progress updates after meaningful milestones. Do not narrate every low-level command.
+When a background terminal is running, summarize only meaningful state changes such as started, ready, failed, or stopped.
 
 Safety rules:
 - Stay inside the configured workspace root.
@@ -57,6 +69,7 @@ Safety rules:
 - Do not read protected secret files unless explicitly authorised.
 - Do not execute destructive commands without explicit permission.
 - Do not install untrusted packages or extensions silently.
+- Do not leave background terminals running after they are no longer needed unless the user asked to keep them running.
 - Do not bypass tests merely to produce a successful-looking result.
 
 Completion rules:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nox-qwen-agent-cli",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "description": "Cross-platform OpenAI-compatible Qwen coding agent CLI",
   "type": "module",
   "license": "UNLICENSED",

package/qwen.js

@@ -19,6 +19,16 @@ const MAX_FILE_BYTES = 20 * 1024 * 1024;
 const MAX_COMMAND_OUTPUT = 128 * 1024;
 const MAX_API_RETRIES = 2;
 const MAX_SHELL_TIMEOUT_MS = 10 * 60 * 1000;
+const MAX_BACKGROUND_OUTPUT = 256 * 1024;
+const MAX_BACKGROUND_TERMINALS = 8;
+const CLARIFY_REQUEST_PROMPT = `Clarify this request before execution.
+Do not modify files, run commands with side effects, or implement the task yet.
+Ask the minimum set of precise questions needed to remove ambiguity, identify acceptance criteria, and confirm risky choices.
+Use no more than five numbered questions unless the user explicitly asks for a deeper requirements interview.
+If the request is already clear enough, say so and list the assumptions you would use before execution.
+
+Request:
+`;
 const SYSTEM_PROMPT_RULES = `The tools attached to the request are authoritative. Use their exact names and JSON schemas.
 Use tools for every local operation. Never claim a command ran or a file changed without a tool result.
 Perform one coherent tool action at a time, inspect its result, and continue until the task is complete.
@@ -32,6 +42,7 @@ When a tool is required, output exactly one block and no other text:
 <NOX_TOOL_CALL>{"id":"short-stable-id","tool":"exact_tool_name","args":{}}</NOX_TOOL_CALL>
 Arguments must match the selected tool schema. Never emit more than one tool call per response.
 After receiving a <tool_result> block, continue the same objective with the next tool call or the final answer.`;
+const AGENT_REMINDER_PROMPT = `Agent reminder: continue following the initial Agent instructions, use the available tools when needed, keep workspace operations inside the active workspace, and finish only after the requested task is handled.`;
 
 const TOOL_DEFINITIONS = [
   tool("update_plan", "Create or update the visible execution plan.", {
@@ -144,6 +155,19 @@ const TOOL_DEFINITIONS = [
     cwd: stringProperty("Relative working directory; defaults to ."),
     timeout_ms: integerProperty("Timeout from 1 to 600000 ms"),
   }, ["command"]),
+  tool("start_background_terminal", "Start a long-running shell command in the background and return a terminal id for later polling.", {
+    command: stringProperty("Shell command"),
+    cwd: stringProperty("Relative working directory; defaults to ."),
+  }, ["command"]),
+  tool("read_background_terminal", "Read buffered output and status from a background terminal.", {
+    terminal_id: stringProperty("Background terminal id returned by start_background_terminal"),
+    max_bytes: integerProperty("Maximum stdout/stderr bytes to return; defaults to 12000"),
+    wait_ms: integerProperty("Optional polling wait from 0 to 10000 ms for new output or process exit"),
+  }, ["terminal_id"]),
+  tool("stop_background_terminal", "Stop a running background terminal.", {
+    terminal_id: stringProperty("Background terminal id returned by start_background_terminal"),
+    signal: stringProperty("Signal name; defaults to SIGTERM"),
+  }, ["terminal_id"]),
 ];
 
 const EFFECTIVE_TOOL_DEFINITIONS = [
@@ -191,6 +215,57 @@ function refreshSystemPrompt(state) {
   else state.messages.unshift({ role: "system", content: prompt });
 }
 
+function prefixTextContent(content, prompt, kind) {
+  const firstTurn = kind === "instructions";
+  return [
+    firstTurn ? "<agent_instructions>" : "<agent_reminder>",
+    prompt,
+    firstTurn ? "</agent_instructions>" : "</agent_reminder>",
+    "<user_message>",
+    String(content ?? ""),
+    "</user_message>",
+  ].join("\n");
+}
+
+function promptForUserTurn(userTurn, prompt) {
+  if (userTurn === 1) return { kind: "instructions", prompt };
+  if (userTurn > 1 && userTurn % 4 === 0) return { kind: "reminder", prompt: AGENT_REMINDER_PROMPT };
+  return null;
+}
+
+function prefixUserContent(content, transport) {
+  if (!transport) return content;
+  if (Array.isArray(content)) {
+    let inserted = false;
+    const parts = content.map((part) => {
+      if (!inserted && part?.type === "text") {
+        inserted = true;
+        return { ...part, text: prefixTextContent(part.text, transport.prompt, transport.kind) };
+      }
+      return part;
+    });
+    if (inserted) return parts;
+    return [{ type: "text", text: prefixTextContent("", transport.prompt, transport.kind) }, ...parts];
+  }
+  return prefixTextContent(content, transport.prompt, transport.kind);
+}
+
+function outboundMessages(state) {
+  const prompt = systemPrompt(state.workspace, state.options);
+  let userTurn = 1;
+  return state.messages
+    .filter((message) => message?.role !== "system" && message?.role !== "developer")
+    .map((message) => {
+      if (message?.role !== "user") return message;
+      const transport = promptForUserTurn(userTurn, prompt);
+      userTurn += 1;
+      return {
+        ...message,
+        content: prefixUserContent(message.content, transport),
+      };
+    });
+}
+
 function tool(name, description, properties, required = []) {
   return {
     type: "function",
@@ -226,6 +301,7 @@ function parseArgs(argv) {
     prompt: "",
     stream: true,
     yes: false,
+    clarify: false,
     approvalMode: "ask",
     history: true,
     resume: "",
@@ -238,6 +314,7 @@ function parseArgs(argv) {
     else if (value === "-p" || value === "--prompt") options.prompt = argv[++index] || "";
     else if (value === "--base-url") options.baseUrl = argv[++index] || options.baseUrl;
     else if (value === "-C" || value === "--workspace") options.workspace = argv[++index] || options.workspace;
+    else if (value === "--clarify") options.clarify = true;
     else if (value === "--no-stream") options.stream = false;
     else if (value === "--stream") options.stream = true;
     else if (value === "--request-timeout") options.requestTimeoutMs = Number.parseInt(argv[++index] || "", 10) * 1000;
@@ -262,11 +339,13 @@ Usage:
   qwen
   qwen install ext
   qwen -m gpt-5.5 -p "inspect this project"
+  qwen --clarify -p "add auth"
   qwen --yes --no-stream
 
 Options:
   -m, --model MODEL       Select model without the menu
   -p, --prompt TEXT       Run one task and exit
+  --clarify              Ask precise clarification questions for --prompt before execution
   -C, --workspace PATH    Active workspace
   --base-url URL          OpenAI-compatible base URL
   --stream / --no-stream  Streaming mode; streaming is default
@@ -287,10 +366,15 @@ Interactive commands:
   /resume SESSION         Resume a saved chat
   /approval ask|auto      Change approval mode for this session
   /plan TASK              Require a visible plan before execution
+  /clarify TASK           Ask precise questions and assumptions before execution
   /clear                  Alias for /new
   /exit                   Exit`;
 }
 
+function clarifyPrompt(request) {
+  return `${CLARIFY_REQUEST_PROMPT}${String(request || "").trim()}`;
+}
+
 function configuredApiKey() {
   return String(
     process.env.NOX_API_KEY
@@ -668,6 +752,9 @@ async function executeToolCall(call, context) {
       }
       return await runShell(String(args.command), cwd, args.timeout_ms);
     }
+    if (name === "start_background_terminal") return await startBackgroundTerminal(context, args);
+    if (name === "read_background_terminal") return await readBackgroundTerminal(context, args);
+    if (name === "stop_background_terminal") return await stopBackgroundTerminal(context, args);
     return { ok: false, error: `Unknown tool: ${name}` };
   } catch (error) {
     return { ok: false, error: String(error?.message || error) };
@@ -764,6 +851,44 @@ function shellQuote(value) {
   return `'${String(value).replace(/'/g, `'\\''`)}'`;
 }
 
+function parseTextToolCall(content) {
+  const text = typeof content === "string" ? content.trim() : "";
+  const match = text.match(/^<NOX_TOOL_CALL>([\s\S]+)<\/NOX_TOOL_CALL>$/);
+  if (!match) return null;
+  let payload;
+  try {
+    payload = JSON.parse(match[1]);
+  } catch {
+    return null;
+  }
+  const name = String(payload?.tool || "");
+  if (!name) return null;
+  const id = String(payload?.id || `text_tool_${crypto.randomUUID().slice(0, 8)}`);
+  const args = payload?.args && typeof payload.args === "object" && !Array.isArray(payload.args)
+    ? payload.args
+    : {};
+  return {
+    id,
+    type: "function",
+    function: {
+      name,
+      arguments: JSON.stringify(args),
+    },
+  };
+}
+
+function normalizeAssistantToolTransport(assistant) {
+  const nativeCalls = Array.isArray(assistant.tool_calls) ? assistant.tool_calls : [];
+  if (nativeCalls.length) return assistant;
+  const textCall = parseTextToolCall(assistant.content);
+  if (!textCall) return assistant;
+  return {
+    ...assistant,
+    content: null,
+    tool_calls: [textCall],
+  };
+}
+
 async function runShell(command, cwd, timeoutValue) {
   const timeoutMs = Math.max(1, Math.min(MAX_SHELL_TIMEOUT_MS, Number(timeoutValue || 120000)));
   return await new Promise((resolvePromise) => {
@@ -798,6 +923,125 @@ async function runShell(command, cwd, timeoutValue) {
   });
 }
 
+function ensureBackgroundTerminals(context) {
+  if (!context.backgroundTerminals) context.backgroundTerminals = new Map();
+  return context.backgroundTerminals;
+}
+
+function backgroundSnapshot(entry, maxBytes = 12000) {
+  const limit = Math.max(1, Math.min(MAX_BACKGROUND_OUTPUT, Number(maxBytes || 12000)));
+  const stdout = entry.stdout.slice(-limit);
+  const stderr = entry.stderr.slice(-limit);
+  return {
+    ok: true,
+    terminal_id: entry.id,
+    command: entry.command,
+    cwd: entry.relativeCwd,
+    running: entry.exit === null,
+    pid: entry.child.pid,
+    started_at: entry.startedAt,
+    exited_at: entry.exitedAt,
+    exit_code: entry.exit?.code ?? null,
+    signal: entry.exit?.signal ?? null,
+    stdout,
+    stderr,
+    truncated: entry.stdout.length > stdout.length || entry.stderr.length > stderr.length || entry.truncated,
+  };
+}
+
+function appendBackgroundOutput(entry, target, chunk) {
+  const text = chunk.toString("utf8");
+  entry[target] += text;
+  if (entry.stdout.length + entry.stderr.length <= MAX_BACKGROUND_OUTPUT) return;
+  const overflow = entry.stdout.length + entry.stderr.length - MAX_BACKGROUND_OUTPUT;
+  if (entry[target].length >= overflow) entry[target] = entry[target].slice(overflow);
+  else {
+    const remaining = overflow - entry[target].length;
+    entry[target] = "";
+    const other = target === "stdout" ? "stderr" : "stdout";
+    entry[other] = entry[other].slice(Math.min(remaining, entry[other].length));
+  }
+  entry.truncated = true;
+}
+
+async function startBackgroundTerminal(context, args) {
+  const terminals = ensureBackgroundTerminals(context);
+  for (const [id, entry] of terminals) {
+    if (entry.exit !== null) terminals.delete(id);
+  }
+  if (terminals.size >= MAX_BACKGROUND_TERMINALS) {
+    throw new Error(`At most ${MAX_BACKGROUND_TERMINALS} background terminals can run at once.`);
+  }
+  const cwd = safeWorkspacePath(context.workspace, args.cwd || ".");
+  const command = String(args.command || "");
+  if (!command.trim()) throw new Error("command must not be empty.");
+  if (!await confirm(context.terminal, context.options, "start background terminal", `$ ${command}\n  cwd: ${path.relative(context.workspace, cwd) || "."}`)) {
+    return { ok: false, error: "User denied background terminal." };
+  }
+  const windows = process.platform === "win32";
+  const executable = windows ? (process.env.ComSpec || "cmd.exe") : "/bin/sh";
+  const shellArgs = windows ? ["/d", "/s", "/c", command] : ["-lc", command];
+  const child = spawn(executable, shellArgs, { cwd, env: process.env, windowsHide: true });
+  const id = `bg_${crypto.randomUUID().slice(0, 8)}`;
+  const entry = {
+    id,
+    command,
+    relativeCwd: path.relative(context.workspace, cwd) || ".",
+    child,
+    stdout: "",
+    stderr: "",
+    truncated: false,
+    startedAt: new Date().toISOString(),
+    exitedAt: null,
+    exit: null,
+  };
+  child.stdout.on("data", (chunk) => appendBackgroundOutput(entry, "stdout", chunk));
+  child.stderr.on("data", (chunk) => appendBackgroundOutput(entry, "stderr", chunk));
+  child.on("error", (error) => {
+    entry.stderr += error.message;
+    entry.exit = { code: null, signal: "ERROR" };
+    entry.exitedAt = new Date().toISOString();
+  });
+  child.on("close", (code, signal) => {
+    entry.exit = { code, signal };
+    entry.exitedAt = new Date().toISOString();
+  });
+  terminals.set(id, entry);
+  return backgroundSnapshot(entry, args.max_bytes);
+}
+
+async function readBackgroundTerminal(context, args) {
+  const terminals = ensureBackgroundTerminals(context);
+  const id = String(args.terminal_id || "");
+  const entry = terminals.get(id);
+  if (!entry) return { ok: false, error: `Unknown background terminal: ${id}` };
+  const waitMs = Math.max(0, Math.min(10000, Number(args.wait_ms || 0)));
+  if (waitMs > 0 && entry.exit === null) {
+    const stdoutLength = entry.stdout.length;
+    const stderrLength = entry.stderr.length;
+    const deadline = Date.now() + waitMs;
+    while (Date.now() < deadline && entry.exit === null && entry.stdout.length === stdoutLength && entry.stderr.length === stderrLength) {
+      await new Promise((resolve) => setTimeout(resolve, Math.min(50, deadline - Date.now())));
+    }
+  }
+  const snapshot = backgroundSnapshot(entry, args.max_bytes);
+  if (!snapshot.running) terminals.delete(id);
+  return snapshot;
+}
+
+async function stopBackgroundTerminal(context, args) {
+  const terminals = ensureBackgroundTerminals(context);
+  const id = String(args.terminal_id || "");
+  const entry = terminals.get(id);
+  if (!entry) return { ok: false, error: `Unknown background terminal: ${id}` };
+  const signal = String(args.signal || "SIGTERM");
+  if (entry.exit === null) entry.child.kill(signal);
+  await new Promise((resolve) => setTimeout(resolve, 25));
+  const snapshot = backgroundSnapshot(entry, args.max_bytes);
+  if (entry.exit !== null) terminals.delete(id);
+  return snapshot;
+}
+
 async function requestCompletion(state) {
   for (let attempt = 0; attempt <= MAX_API_RETRIES; attempt += 1) {
     try {
@@ -817,9 +1061,10 @@ async function requestCompletion(state) {
 
 async function requestCompletionOnce(state) {
   const providerSession = state.providerSessions?.[state.model] || null;
+  const prompt = systemPrompt(state.workspace, state.options);
   const body = {
     model: state.model,
-    messages: state.messages,
+    messages: outboundMessages(state),
     tools: EFFECTIVE_TOOL_DEFINITIONS,
     tool_choice: "auto",
     parallel_tool_calls: false,
@@ -831,6 +1076,8 @@ async function requestCompletionOnce(state) {
       nox_new_provider_chat: !providerSession,
       ...(providerSession ? { nox_provider_session: providerSession } : {}),
       qwen_cli_session_id: state.sessionId,
+      nox_prompt_transport: "user-prefix",
+      nox_system_prompt_sha256: crypto.createHash("sha256").update(prompt).digest("hex"),
       nox_thinking_level: "medium",
     },
   };
@@ -874,9 +1121,26 @@ async function collectChatStream(body, { onText, onThinking }) {
   let buffer = "";
   let content = "";
   let reasoning = "";
+  let pendingText = "";
+  let streamingText = false;
   const toolCalls = [];
   let providerSession = null;
   let completed = false;
+  const maybeTextToolPrefix = (value) => {
+    const trimmed = String(value || "").trimStart();
+    return "<NOX_TOOL_CALL>".startsWith(trimmed) || trimmed.startsWith("<NOX_TOOL_CALL>");
+  };
+  const handleText = (chunk) => {
+    if (streamingText) {
+      onText(chunk);
+      return;
+    }
+    pendingText += chunk;
+    if (maybeTextToolPrefix(pendingText)) return;
+    streamingText = true;
+    onText(pendingText);
+    pendingText = "";
+  };
   while (true) {
     const { value, done } = await reader.read();
     if (done) break;
@@ -911,7 +1175,7 @@ async function collectChatStream(body, { onText, onThinking }) {
       }
       if (typeof delta.content === "string" && delta.content) {
         content += delta.content;
-        onText(delta.content);
+        handleText(delta.content);
       }
       for (const part of delta.tool_calls || []) {
         const index = Number(part.index || 0);
@@ -933,6 +1197,17 @@ async function collectChatStream(body, { onText, onThinking }) {
     error.partialResponse = Boolean(content || toolCalls.length);
     throw error;
   }
+  const textToolCall = parseTextToolCall(content);
+  if (textToolCall && !toolCalls.length) {
+    return {
+      role: "assistant",
+      content: null,
+      ...(reasoning ? { reasoning_content: reasoning } : {}),
+      ...(providerSession ? { provider_session: providerSession } : {}),
+      tool_calls: [textToolCall],
+    };
+  }
+  if (!streamingText && pendingText) onText(pendingText);
   if (content && !onText) process.stdout.write("\n");
   return {
     role: "assistant",
@@ -949,7 +1224,7 @@ async function runAgentTurn(state, userMessage) {
   await persistSession(state);
   for (let step = 0; step < MAX_TOOL_STEPS; step += 1) {
     state.ui?.working(step + 1);
-    const assistant = await requestCompletion(state);
+    const assistant = normalizeAssistantToolTransport(await requestCompletion(state));
     if (assistant.provider_session && typeof assistant.provider_session === "object") {
       state.providerSessions[state.model] = assistant.provider_session;
     }
@@ -1043,7 +1318,7 @@ async function main() {
   }
   const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
   const ui = interactive ? new TerminalUI(process.stdin, process.stdout) : null;
-  const apiKey = ui ? await ui.readApiKey() : configuredApiKey();
+  const apiKey = configuredApiKey() || (ui ? await ui.readApiKey() : "");
   if (!apiKey) {
     throw new Error("Set OPENAI_COMPAT_API_KEY, OPENAI_API_KEY, or NOX_API_KEY before running qwen.");
   }
@@ -1068,6 +1343,7 @@ async function main() {
     workspace,
     sessionId: "",
     providerSessions: {},
+    backgroundTerminals: new Map(),
     messages: [],
     ui,
     historyErrorShown: false,
@@ -1098,7 +1374,7 @@ async function main() {
 
   try {
     if (options.prompt) {
-      await runAgentTurn(state, { role: "user", content: options.prompt });
+      await runAgentTurn(state, { role: "user", content: options.clarify ? clarifyPrompt(options.prompt) : options.prompt });
       return;
     }
     if (!ui) throw new Error("Interactive mode requires a terminal or --prompt.");
@@ -1148,13 +1424,16 @@ async function main() {
       const image = parseImageCommand(input);
       const file = parseFileCommand(input);
       const planTask = input.startsWith("/plan ") ? input.slice(6).trim() : "";
+      const clarifyTask = input.startsWith("/clarify ") ? input.slice(9).trim() : "";
       try {
         await runAgentTurn(state,
           image ? await imageMessage(image.filePath, image.prompt)
             : file ? await fileMessage(file.filePath, file.prompt)
               : {
                   role: "user",
-                  content: planTask
+                  content: clarifyTask
+                    ? clarifyPrompt(clarifyTask)
+                    : planTask
                     ? `Create and show a concrete plan with update_plan before executing this task, then keep it updated:\n\n${planTask}`
                     : input,
                 });

package/terminal-ui.js

@@ -218,7 +218,7 @@ export class TerminalUI {
     if (approvalMode === "auto") {
       this.write(`${this.yellow("  Auto approval is active: model-requested changes and commands run without prompts.")}\n`);
     }
-    this.write(`${this.dim("  /plan   /image   /file   /model   /sessions   /approval   /exit")}\n`);
+    this.write(`${this.dim("  /plan   /clarify   /image   /file   /model   /sessions   /approval   /exit")}\n`);
   }
 
   async readMessage() {