mini-coder 0.5.6 → 0.5.8

package/README.md

@@ -39,10 +39,12 @@ $ mc
 
 ## Tools
 
-Two built-in tools, plus a read-only image tool:
+Four built-in tools, plus a read-only image tool:
 
 - **`shell`** — runs commands in the user's shell. Returns stdout, stderr, and exit code. Large output is truncated to protect model context.
 - **`edit`** — exact-text replacement in a single file. Fails deterministically if the target is missing or ambiguous. Creates new files when old text is empty.
+- **`todoWrite`** — creates or updates the session todo list incrementally and returns the full current snapshot.
+- **`todoRead`** — returns the full current session todo list snapshot.
 - **`readImage`** — reads PNG, JPEG, GIF, and WebP files as model input. Only registered when the active model supports images.
 
 Plugins can add more tools, but the core stays intentionally small.
@@ -68,6 +70,7 @@ Plugins can add more tools, but the core stays intentionally small.
 | `/undo`      | Remove the last conversational turn without touching filesystem changes.                               |
 | `/reasoning` | Show or hide model thinking. The setting is saved and restored on launch.                              |
 | `/verbose`   | Expand shell output plus edit previews and edit errors in the conversation log.                        |
+| `/todo`      | Show the current session todo list in the conversation log as a UI-only checklist block.               |
 | `/login`     | Sign in with a supported OAuth provider.                                                               |
 | `/logout`    | Remove saved OAuth credentials for a logged-in provider.                                               |
 | `/effort`    | Choose low, medium, high, or xhigh reasoning effort.                                                   |
@@ -100,7 +103,7 @@ $ printf '%s\n' 'fix the failing tests' | mc
 - Starts when `-p/--prompt` is provided or when stdin or stdout is not a TTY.
 - If stdout is redirected but stdin is still interactive, pass `-p`; headless mode will not fall back to an interactive prompt.
 - Uses the same parser as the TUI for plain text, `/skill:name`, and standalone image paths.
-- Writes raw NDJSON events to stdout for text deltas, tool activity, final messages, and `done` / `error` / `aborted` outcomes.
+- With `--json`, writes NDJSON events for completed assistant/tool-result messages plus `done` / `error` / `aborted` outcomes; streaming deltas are omitted.
 - Headless runs still persist like normal sessions and show up in `/session` history for that working directory.
 - Interactive slash commands such as `/model`, `/session`, and `/help` are not available in headless mode.
 

package/bun.lock

@@ -5,9 +5,9 @@
     "": {
       "name": "mini-coder",
       "dependencies": {
-        "@cel-tui/components": "0.7.2",
-        "@cel-tui/core": "0.7.2",
-        "@cel-tui/types": "0.7.2",
+        "@cel-tui/components": "^0.7.2",
+        "@cel-tui/core": "^0.7.2",
+        "@cel-tui/types": "^0.7.2",
         "@mariozechner/pi-ai": "^0.66.1",
       },
       "devDependencies": {
@@ -90,23 +90,23 @@
 
     "@babel/runtime": ["@babel/runtime@7.29.2", "", {}, "sha512-JiDShH45zKHWyGe4ZNVRrCjBz8Nh9TMmZG1kh4QTK8hCBTWBi8Da+i7s1fJw7/lYpM4ccepSNfqzZ/QvABBi5g=="],
 
-    "@biomejs/biome": ["@biomejs/biome@2.4.11", "", { "optionalDependencies": { "@biomejs/cli-darwin-arm64": "2.4.11", "@biomejs/cli-darwin-x64": "2.4.11", "@biomejs/cli-linux-arm64": "2.4.11", "@biomejs/cli-linux-arm64-musl": "2.4.11", "@biomejs/cli-linux-x64": "2.4.11", "@biomejs/cli-linux-x64-musl": "2.4.11", "@biomejs/cli-win32-arm64": "2.4.11", "@biomejs/cli-win32-x64": "2.4.11" }, "bin": { "biome": "bin/biome" } }, "sha512-nWxHX8tf3Opb/qRgZpBbsTOqOodkbrkJ7S+JxJAruxOReaDPPmPuLBAGQ8vigyUgo0QBB+oQltNEAvalLcjggA=="],
+    "@biomejs/biome": ["@biomejs/biome@2.4.12", "", { "optionalDependencies": { "@biomejs/cli-darwin-arm64": "2.4.12", "@biomejs/cli-darwin-x64": "2.4.12", "@biomejs/cli-linux-arm64": "2.4.12", "@biomejs/cli-linux-arm64-musl": "2.4.12", "@biomejs/cli-linux-x64": "2.4.12", "@biomejs/cli-linux-x64-musl": "2.4.12", "@biomejs/cli-win32-arm64": "2.4.12", "@biomejs/cli-win32-x64": "2.4.12" }, "bin": { "biome": "bin/biome" } }, "sha512-Rro7adQl3NLq/zJCIL98eElXKI8eEiBtoeu5TbXF/U3qbjuSc7Jb5rjUbeHHcquDWeSf3HnGP7XI5qGrlRk/pA=="],
 
-    "@biomejs/cli-darwin-arm64": ["@biomejs/cli-darwin-arm64@2.4.11", "", { "os": "darwin", "cpu": "arm64" }, "sha512-wOt+ed+L2dgZanWyL6i29qlXMc088N11optzpo10peayObBaAshbTcxKUchzEMp9QSY8rh5h6VfAFE3WTS1rqg=="],
+    "@biomejs/cli-darwin-arm64": ["@biomejs/cli-darwin-arm64@2.4.12", "", { "os": "darwin", "cpu": "arm64" }, "sha512-BnMU4Pc3ciEVteVpZ0BK33MLr7X57F5w1dwDLDn+/iy/yTrA4Q/N2yftidFtsA4vrDh0FMXDpacNV/Tl3fbmng=="],
 
-    "@biomejs/cli-darwin-x64": ["@biomejs/cli-darwin-x64@2.4.11", "", { "os": "darwin", "cpu": "x64" }, "sha512-gZ6zR8XmZlExfi/Pz/PffmdpWOQ8Qhy7oBztgkR8/ylSRyLwfRPSadmiVCV8WQ8PoJ2MWUy2fgID9zmtgUUJmw=="],
+    "@biomejs/cli-darwin-x64": ["@biomejs/cli-darwin-x64@2.4.12", "", { "os": "darwin", "cpu": "x64" }, "sha512-x9uJ0bI1rJsWICp3VH8w/5PnAVD3A7SqzDpbrfoUQX1QyWrK5jSU4fRLo/wSgGeplCivbxBRKmt5Xq4/nWvq8A=="],
 
-    "@biomejs/cli-linux-arm64": ["@biomejs/cli-linux-arm64@2.4.11", "", { "os": "linux", "cpu": "arm64" }, "sha512-avdJaEElXrKceK0va9FkJ4P5ci3N01TGkc6ni3P8l3BElqbOz42Wg2IyX3gbh0ZLEd4HVKEIrmuVu/AMuSeFFA=="],
+    "@biomejs/cli-linux-arm64": ["@biomejs/cli-linux-arm64@2.4.12", "", { "os": "linux", "cpu": "arm64" }, "sha512-tOwuCuZZtKi1jVzbk/5nXmIsziOB6yqN8c9r9QM0EJYPU6DpQWf11uBOSCfFKKM4H3d9ZoarvlgMfbcuD051Pw=="],
 
-    "@biomejs/cli-linux-arm64-musl": ["@biomejs/cli-linux-arm64-musl@2.4.11", "", { "os": "linux", "cpu": "arm64" }, "sha512-+Sbo1OAmlegtdwqFE8iOxFIWLh1B3OEgsuZfBpyyN/kWuqZ8dx9ZEes6zVnDMo+zRHF2wLynRVhoQmV7ohxl2Q=="],
+    "@biomejs/cli-linux-arm64-musl": ["@biomejs/cli-linux-arm64-musl@2.4.12", "", { "os": "linux", "cpu": "arm64" }, "sha512-FhfpkAAlKL6kwvcVap0Hgp4AhZmtd3YImg0kK1jd7C/aSoh4SfsB2f++yG1rU0lr8Y5MCFJrcSkmssiL9Xnnig=="],
 
-    "@biomejs/cli-linux-x64": ["@biomejs/cli-linux-x64@2.4.11", "", { "os": "linux", "cpu": "x64" }, "sha512-TagWV0iomp5LnEnxWFg4nQO+e52Fow349vaX0Q/PIcX6Zhk4GGBgp3qqZ8PVkpC+cuehRctMf3+6+FgQ8jCEFQ=="],
+    "@biomejs/cli-linux-x64": ["@biomejs/cli-linux-x64@2.4.12", "", { "os": "linux", "cpu": "x64" }, "sha512-8pFeAnLU9QdW9jCIslB/v82bI0lhBmz2ZAKc8pVMFPO0t0wAHsoEkrUQUbMkIorTRIjbqyNZHA3lEXavsPWYSw=="],
 
-    "@biomejs/cli-linux-x64-musl": ["@biomejs/cli-linux-x64-musl@2.4.11", "", { "os": "linux", "cpu": "x64" }, "sha512-bexd2IklK7ZgPhrz6jXzpIL6dEAH9MlJU1xGTrypx+FICxrXUp4CqtwfiuoDKse+UlgAlWtzML3jrMqeEAHEhA=="],
+    "@biomejs/cli-linux-x64-musl": ["@biomejs/cli-linux-x64-musl@2.4.12", "", { "os": "linux", "cpu": "x64" }, "sha512-dwTIgZrGutzhkQCuvHynCkyW6hJxUuyZqKKO0YNfaS2GUoRO+tOvxXZqZB6SkWAOdfZTzwaw8IEdUnIkHKHoew=="],
 
-    "@biomejs/cli-win32-arm64": ["@biomejs/cli-win32-arm64@2.4.11", "", { "os": "win32", "cpu": "arm64" }, "sha512-RJhaTnY8byzxDt4bDVb7AFPHkPcjOPK3xBip4ZRTrN3TEfyhjLRm3r3mqknqydgVTB74XG8l4jMLwEACEeihVg=="],
+    "@biomejs/cli-win32-arm64": ["@biomejs/cli-win32-arm64@2.4.12", "", { "os": "win32", "cpu": "arm64" }, "sha512-B0DLnx0vA9ya/3v7XyCaP+/lCpnbWbMOfUFFve+xb5OxyYvdHaS55YsSddr228Y+JAFk58agCuZTsqNiw2a6ig=="],
 
-    "@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@2.4.11", "", { "os": "win32", "cpu": "x64" }, "sha512-A8D3JM/00C2KQgUV3oj8Ba15EHEYwebAGCy5Sf9GAjr5Y3+kJIYOiESoqRDeuRZueuMdCsbLZIUqmPhpYXJE9A=="],
+    "@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@2.4.12", "", { "os": "win32", "cpu": "x64" }, "sha512-yMckRzTyZ83hkk8iDFWswqSdU8tvZxspJKnYNh7JZr/zhZNOlzH13k4ecboU6MurKExCe2HUkH75pGI/O2JwGA=="],
 
     "@cel-tui/components": ["@cel-tui/components@0.7.2", "", { "dependencies": { "@cel-tui/core": "0.7.2", "@cel-tui/types": "0.7.2", "lextide": "^0.2.1", "yoctomarkdown": "^0.1.0" }, "peerDependencies": { "typescript": ">=5.0.0" } }, "sha512-RHq7G/lS6A733l534cSStQp+cJECkxZZWrLghbPHwGBsSeDdJ2MkrQm+02roh6EH/N40ZAYjQqplq8acRrnFFQ=="],
 
@@ -368,7 +368,7 @@
 
     "path-expression-matcher": ["path-expression-matcher@1.2.1", "", {}, "sha512-d7gQQmLvAKXKXE2GeP9apIGbMYKz88zWdsn/BN2HRWVQsDFdUY36WSLTY0Jvd4HWi7Fb30gQ62oAOzdgJA6fZw=="],
 
-    "prettier": ["prettier@3.8.2", "", { "bin": { "prettier": "bin/prettier.cjs" } }, "sha512-8c3mgTe0ASwWAJK+78dpviD+A8EqhndQPUBpNUIPt6+xWlIigCwfN01lWr9MAede4uqXGTEKeQWTvzb3vjia0Q=="],
+    "prettier": ["prettier@3.8.3", "", { "bin": { "prettier": "bin/prettier.cjs" } }, "sha512-7igPTM53cGHMW8xWuVTydi2KO233VFiTNyF5hLJqpilHfmn8C8gPf+PS7dUT64YcXFbiMGZxS9pCSxL/Dxm/Jw=="],
 
     "protobufjs": ["protobufjs@7.5.4", "", { "dependencies": { "@protobufjs/aspromise": "^1.1.2", "@protobufjs/base64": "^1.1.2", "@protobufjs/codegen": "^2.0.4", "@protobufjs/eventemitter": "^1.1.0", "@protobufjs/fetch": "^1.1.0", "@protobufjs/float": "^1.0.2", "@protobufjs/inquire": "^1.1.0", "@protobufjs/path": "^1.1.2", "@protobufjs/pool": "^1.1.0", "@protobufjs/utf8": "^1.1.0", "@types/node": ">=13.7.0", "long": "^5.0.0" } }, "sha512-CvexbZtbov6jW2eXAvLukXjXUW1TzFaivC46BpWc/3BpcCysb5Vffu+B3XHMm8lVEuy2Mm4XGex8hBSg1yapPg=="],
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mini-coder",
-  "version": "0.5.6",
+  "version": "0.5.8",
   "description": "A small, fast CLI coding agent",
   "module": "src/index.ts",
   "type": "module",
@@ -24,10 +24,10 @@
     "@mariozechner/pi-ai": "^0.66.1"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.11",
+    "@biomejs/biome": "^2.4.12",
     "@types/bun": "^1.3.12",
     "lefthook": "^2.1.5",
-    "prettier": "^3.8.2",
+    "prettier": "^3.8.3",
     "typescript": "^6.0.2"
   },
   "license": "MIT"

package/src/agent.ts

@@ -18,10 +18,11 @@ import type {
   Tool,
   ToolCall,
   ToolResultMessage,
+  UserMessage,
 } from "@mariozechner/pi-ai";
 import { streamSimple } from "@mariozechner/pi-ai";
 import { appendMessage } from "./session.ts";
-import type { ToolExecResult } from "./tools.ts";
+import { getTodoItems, type ToolExecResult } from "./tools.ts";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -79,6 +80,7 @@ export type AgentEvent =
       args: Record<string, unknown>;
       content: AssistantMessage["content"];
     }
+  | { type: "user_message"; message: UserMessage }
   | { type: "assistant_message"; message: AssistantMessage }
   | {
       type: "tool_start";
@@ -131,6 +133,8 @@ interface RunAgentOpts {
   signal?: AbortSignal;
   /** Callback for UI events. */
   onEvent?: (event: AgentEvent) => void;
+  /** Dequeue the next queued steering message, if one is waiting. */
+  takeQueuedUserMessage?: () => UserMessage | null;
 }
 
 /** Result of the agent loop. */
@@ -462,6 +466,19 @@ async function streamAssistantMessage(
   return mergeAssistantMessage(partialAssistantMessage, finalAssistantMessage);
 }
 
+function appendUserMessage(
+  db: Database,
+  sessionId: string,
+  messages: Message[],
+  userMessage: UserMessage,
+  onEvent: RunAgentOpts["onEvent"],
+): number {
+  messages.push(userMessage);
+  const turn = appendMessage(db, sessionId, userMessage);
+  onEvent?.({ type: "user_message", message: userMessage });
+  return turn;
+}
+
 function appendAssistantMessage(
   db: Database,
   sessionId: string,
@@ -490,15 +507,22 @@ function resolveLoopStopReason(
     return { messages, stopReason: assistantMessage.stopReason };
   }
 
-  if (
-    assistantMessage.stopReason === "stop" ||
-    assistantMessage.stopReason === "length"
-  ) {
-    onEvent?.({ type: "done", message: assistantMessage });
-    return { messages, stopReason: assistantMessage.stopReason };
+  return null;
+}
+
+function consumeQueuedUserMessage(
+  db: Database,
+  sessionId: string,
+  messages: Message[],
+  takeQueuedUserMessage: RunAgentOpts["takeQueuedUserMessage"],
+  onEvent: RunAgentOpts["onEvent"],
+): number | null {
+  const queuedUserMessage = takeQueuedUserMessage?.();
+  if (!queuedUserMessage) {
+    return null;
   }
 
-  return null;
+  return appendUserMessage(db, sessionId, messages, queuedUserMessage, onEvent);
 }
 
 function getAssistantToolCalls(message: AssistantMessage): ToolCall[] {
@@ -581,6 +605,244 @@ function appendToolResultMessage(
   onEvent?.({ type: "tool_result", message: toolResultMessage });
 }
 
+function getIncompleteTodos(messages: readonly Message[]) {
+  return getTodoItems(messages).filter((todo) => todo.status !== "completed");
+}
+
+function getTodoReminderSignature(
+  todos: ReturnType<typeof getIncompleteTodos>,
+): string {
+  return JSON.stringify(
+    [...todos].sort((left, right) => {
+      const contentOrder = left.content.localeCompare(right.content);
+      if (contentOrder !== 0) {
+        return contentOrder;
+      }
+      return left.status.localeCompare(right.status);
+    }),
+  );
+}
+
+function createTodoReminderMessage(
+  messages: readonly Message[],
+  remindedTodoSignatures: Set<string>,
+): UserMessage | null {
+  const incompleteTodos = getIncompleteTodos(messages);
+  if (incompleteTodos.length === 0) {
+    return null;
+  }
+
+  const signature = getTodoReminderSignature(incompleteTodos);
+  if (remindedTodoSignatures.has(signature)) {
+    return null;
+  }
+  remindedTodoSignatures.add(signature);
+
+  const lines = [
+    "You have pending todo items that must be completed before finishing the task:",
+    "",
+    ...incompleteTodos.map((todo) => {
+      const status = todo.status === "in_progress" ? "IN_PROGRESS" : "PENDING";
+      return `- [${status}] ${todo.content}`;
+    }),
+    "",
+    "Please complete all pending items before finishing.",
+  ];
+
+  return {
+    role: "user",
+    content: lines.join("\n"),
+    timestamp: Date.now(),
+  };
+}
+
+interface StoppedAssistantResolution {
+  /** Next turn number when a queued steering message was consumed. */
+  nextTurn: number | null;
+  /** Ephemeral context messages to include on the next model request. */
+  pendingContextMessages: Message[];
+  /** Final loop result when the turn should stop immediately. */
+  finalResult: AgentLoopResult | null;
+}
+
+function resolveStoppedAssistantMessage(
+  assistantMessage: AssistantMessage,
+  stopReason: "stop" | "length",
+  opts: Pick<
+    RunAgentOpts,
+    "db" | "sessionId" | "messages" | "takeQueuedUserMessage" | "onEvent"
+  >,
+  remindedTodoSignatures: Set<string>,
+): StoppedAssistantResolution {
+  const queuedTurn = consumeQueuedUserMessage(
+    opts.db,
+    opts.sessionId,
+    opts.messages,
+    opts.takeQueuedUserMessage,
+    opts.onEvent,
+  );
+  if (queuedTurn !== null) {
+    return {
+      nextTurn: queuedTurn,
+      pendingContextMessages: [],
+      finalResult: null,
+    };
+  }
+
+  const todoReminder = createTodoReminderMessage(
+    opts.messages,
+    remindedTodoSignatures,
+  );
+  if (todoReminder) {
+    return {
+      nextTurn: null,
+      pendingContextMessages: [todoReminder],
+      finalResult: null,
+    };
+  }
+
+  opts.onEvent?.({ type: "done", message: assistantMessage });
+  return {
+    nextTurn: null,
+    pendingContextMessages: [],
+    finalResult: {
+      messages: opts.messages,
+      stopReason,
+    },
+  };
+}
+
+async function executeAssistantToolCalls(
+  assistantMessage: AssistantMessage,
+  opts: Pick<
+    RunAgentOpts,
+    | "db"
+    | "sessionId"
+    | "messages"
+    | "toolHandlers"
+    | "cwd"
+    | "signal"
+    | "onEvent"
+    | "model"
+  >,
+  turn: number,
+): Promise<AgentLoopResult | null> {
+  for (const toolCall of getAssistantToolCalls(assistantMessage)) {
+    const result = await executeToolCall(toolCall, opts);
+    appendToolResultMessage(
+      opts.db,
+      opts.sessionId,
+      opts.messages,
+      toolCall,
+      result,
+      turn,
+      opts.onEvent,
+    );
+
+    if (opts.signal?.aborted) {
+      opts.onEvent?.({
+        type: "aborted",
+        message: buildIncompleteAssistantMessage(
+          { model: opts.model, signal: opts.signal },
+          assistantMessage,
+        ),
+      });
+      return { messages: opts.messages, stopReason: "aborted" };
+    }
+  }
+
+  return null;
+}
+
+interface AgentIterationOutcome {
+  /** Final loop result when the run should stop immediately. */
+  finalResult: AgentLoopResult | null;
+  /** Next turn number when a queued steering message starts a new turn. */
+  nextTurn: number;
+  /** Ephemeral context messages for the next model request. */
+  pendingContextMessages: Message[];
+}
+
+async function resolveAgentIteration(
+  assistantMessage: AssistantMessage,
+  currentTurn: number,
+  remindedTodoSignatures: Set<string>,
+  opts: Pick<
+    RunAgentOpts,
+    | "db"
+    | "sessionId"
+    | "messages"
+    | "toolHandlers"
+    | "cwd"
+    | "signal"
+    | "onEvent"
+    | "model"
+    | "takeQueuedUserMessage"
+  >,
+): Promise<AgentIterationOutcome> {
+  const stopResult = resolveLoopStopReason(
+    assistantMessage,
+    opts.messages,
+    opts.onEvent,
+  );
+  if (stopResult) {
+    return {
+      finalResult: stopResult,
+      nextTurn: currentTurn,
+      pendingContextMessages: [],
+    };
+  }
+
+  if (
+    assistantMessage.stopReason === "stop" ||
+    assistantMessage.stopReason === "length"
+  ) {
+    const stopResolution = resolveStoppedAssistantMessage(
+      assistantMessage,
+      assistantMessage.stopReason,
+      {
+        db: opts.db,
+        sessionId: opts.sessionId,
+        messages: opts.messages,
+        takeQueuedUserMessage: opts.takeQueuedUserMessage,
+        onEvent: opts.onEvent,
+      },
+      remindedTodoSignatures,
+    );
+    return {
+      finalResult: stopResolution.finalResult,
+      nextTurn: stopResolution.nextTurn ?? currentTurn,
+      pendingContextMessages: stopResolution.pendingContextMessages,
+    };
+  }
+
+  const toolStopResult = await executeAssistantToolCalls(
+    assistantMessage,
+    opts,
+    currentTurn,
+  );
+  if (toolStopResult) {
+    return {
+      finalResult: toolStopResult,
+      nextTurn: currentTurn,
+      pendingContextMessages: [],
+    };
+  }
+
+  const queuedTurn = consumeQueuedUserMessage(
+    opts.db,
+    opts.sessionId,
+    opts.messages,
+    opts.takeQueuedUserMessage,
+    opts.onEvent,
+  );
+  return {
+    finalResult: null,
+    nextTurn: queuedTurn ?? currentTurn,
+    pendingContextMessages: [],
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Agent loop
 // ---------------------------------------------------------------------------
@@ -609,55 +871,51 @@ export async function runAgentLoop(
     onEvent,
     toolHandlers,
     cwd,
+    takeQueuedUserMessage,
   } = opts;
+  let currentTurn = turn;
+  let pendingContextMessages: Message[] = [];
+  const remindedTodoSignatures = new Set<string>();
 
   while (true) {
-    const assistantMessage = await streamAssistantMessage(opts);
+    const assistantMessage = await streamAssistantMessage({
+      ...opts,
+      messages:
+        pendingContextMessages.length > 0
+          ? [...messages, ...pendingContextMessages]
+          : messages,
+    });
+    pendingContextMessages = [];
     appendAssistantMessage(
       db,
       sessionId,
       messages,
       assistantMessage,
-      turn,
+      currentTurn,
       onEvent,
     );
 
-    const stopResult = resolveLoopStopReason(
+    const iterationOutcome = await resolveAgentIteration(
       assistantMessage,
-      messages,
-      onEvent,
-    );
-    if (stopResult) {
-      return stopResult;
-    }
-
-    for (const toolCall of getAssistantToolCalls(assistantMessage)) {
-      const result = await executeToolCall(toolCall, {
-        toolHandlers,
-        cwd,
-        signal,
-        onEvent,
-      });
-      appendToolResultMessage(
+      currentTurn,
+      remindedTodoSignatures,
+      {
         db,
         sessionId,
         messages,
-        toolCall,
-        result,
-        turn,
+        toolHandlers,
+        cwd,
+        signal,
         onEvent,
-      );
-
-      if (signal?.aborted) {
-        onEvent?.({
-          type: "aborted",
-          message: buildIncompleteAssistantMessage(
-            { model, signal },
-            assistantMessage,
-          ),
-        });
-        return { messages, stopReason: "aborted" };
-      }
+        model,
+        takeQueuedUserMessage,
+      },
+    );
+    if (iterationOutcome.finalResult) {
+      return iterationOutcome.finalResult;
     }
+
+    currentTurn = iterationOutcome.nextTurn;
+    pendingContextMessages = iterationOutcome.pendingContextMessages;
   }
 }

package/src/cli.ts

@@ -12,6 +12,8 @@
 export interface CliOptions {
   /** One-shot prompt text, or `null` when not provided. */
   prompt: string | null;
+  /** Whether to stream headless output as NDJSON instead of final text. */
+  json: boolean;
 }
 
 /** TTY availability for stdin/stdout. */
@@ -29,7 +31,8 @@ export interface TtyState {
 /**
  * Parse supported CLI arguments.
  *
- * Currently supports only `-p, --prompt <text>` for headless one-shot mode.
+ * Supports `-p, --prompt <text>` for headless one-shot mode and `--json`
+ * to stream NDJSON events instead of the default final-text output.
  * Unknown flags and positional arguments fail eagerly.
  *
  * @param argv - Process arguments excluding the Bun executable and script path.
@@ -37,6 +40,7 @@ export interface TtyState {
  */
 export function parseCliArgs(argv: readonly string[]): CliOptions {
   let prompt: string | null = null;
+  let json = false;
 
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
@@ -59,6 +63,11 @@ export function parseCliArgs(argv: readonly string[]): CliOptions {
       continue;
     }
 
+    if (arg === "--json") {
+      json = true;
+      continue;
+    }
+
     if (arg.startsWith("-")) {
       throw new Error(`Unknown argument: ${arg}`);
     }
@@ -66,7 +75,7 @@ export function parseCliArgs(argv: readonly string[]): CliOptions {
     throw new Error(`Unexpected positional argument: ${arg}`);
   }
 
-  return { prompt };
+  return { prompt, json };
 }
 
 // ---------------------------------------------------------------------------