chainlesschain 0.162.31 → 0.162.33

package/src/repl/agent-repl.js

@@ -92,8 +92,18 @@ async function executeTool(name, args) {
  */
 async function agentLoop(messages, options) {
   const usageEvents = [];
-  for await (const event of coreAgentLoop(messages, options)) {
-    if (event.type === "tool-executing") {
+  // The REPL runs its own auto-compaction (after each turn, with metrics +
+  // persisted compact events), so opt out of the agent loop's in-loop
+  // compaction to avoid compacting the same history twice.
+  for await (const event of coreAgentLoop(messages, {
+    autoCompact: false,
+    ...options,
+  })) {
+    if (event.type === "checkpoint") {
+      process.stdout.write(
+        chalk.gray(`  ⎌ checkpoint ${event.id} (before ${event.tool})\n`),
+      );
+    } else if (event.type === "tool-executing") {
       process.stdout.write(
         chalk.gray(
           `  [${event.tool}] ${formatToolArgs(event.tool, event.args)}\n`,
@@ -158,6 +168,9 @@ export async function startAgentRepl(options = {}) {
   const additionalDirectories = Array.isArray(options.additionalDirectories)
     ? options.additionalDirectories
     : [];
+  // Snapshot the work tree before each mutating tool (git engine) so the user
+  // can `cc checkpoint restore` to just before any tool call.
+  const autoCheckpoint = options.autoCheckpoint === true;
 
   // --fallback-model: retry a turn's LLM call once on a backup model when the
   // primary errors out (overload / network). Built once; passed into every
@@ -718,8 +731,10 @@ export async function startAgentRepl(options = {}) {
 
     if (trimmed === "/compact") {
       if (_compressor && messages.length > 3) {
-        const { messages: compacted, stats } =
-          await _compressor.compress(messages);
+        const { messages: compacted, stats } = await _compressor.compress(
+          messages,
+          { preserveToolPairs: true },
+        );
         messages.length = 0;
         messages.push(...compacted);
         recordCompressionMetric(stats, {
@@ -1521,6 +1536,23 @@ export async function startAgentRepl(options = {}) {
     try {
       process.stdout.write("\n");
       const iterationBudget = new IterationBudget({ owner: sessionId });
+      // Bind a cross-session goal (cc goal) into this run, if one resolves.
+      // Composes WITH defaultPrepareCall — never replaces it. Best-effort.
+      let prepareCall = defaultPrepareCall;
+      try {
+        const { resolveActiveGoal } = await import("../lib/goal-store.js");
+        const boundGoal = resolveActiveGoal({ sessionId });
+        if (boundGoal) {
+          const { goalPrepareCall, composePrepareCall } =
+            await import("../lib/goal-context.js");
+          prepareCall = composePrepareCall([
+            defaultPrepareCall,
+            goalPrepareCall(boundGoal),
+          ]);
+        }
+      } catch (_e) {
+        /* goal binding is best-effort — fall back to defaultPrepareCall */
+      }
       const { content: response, usageEvents } = await agentLoop(messages, {
         provider,
         model: activeModel,
@@ -1531,7 +1563,9 @@ export async function startAgentRepl(options = {}) {
         sessionId,
         cwd: process.cwd(),
         additionalDirectories,
-        prepareCall: defaultPrepareCall,
+        autoCheckpoint,
+        checkpointSession: sessionId,
+        prepareCall,
         approvalGate: _approvalGate,
         mcpClient: _bundleMcpClient || undefined,
         chatFn: _fallbackChatFn,
@@ -1613,8 +1647,10 @@ export async function startAgentRepl(options = {}) {
         _compressor.shouldAutoCompact(messages)
       ) {
         try {
-          const { messages: compacted, stats } =
-            await _compressor.compress(messages);
+          const { messages: compacted, stats } = await _compressor.compress(
+            messages,
+            { preserveToolPairs: true },
+          );
           messages.length = 0;
           messages.push(...compacted);
           recordCompressionMetric(stats, {

package/src/runtime/agent-core.js

@@ -1663,7 +1663,21 @@ export async function chatWithTools(rawMessages, options) {
   throwIfAborted(signal);
 
   if (provider === "ollama") {
-    const response = await fetch(`${baseUrl}/api/chat`, {
+    const apiUrl = `${baseUrl}/api/chat`;
+    // Real-time token deltas (Claude-Code `--include-partial-messages`): when
+    // the caller supplies an onToken hook, stream the response and forward each
+    // content chunk as it arrives. Tool calls + usage are accumulated and the
+    // same {message, usage} shape is returned, so the agent loop is unchanged.
+    // Without onToken we keep the cheaper single-shot non-streaming request.
+    if (typeof options.onToken === "function") {
+      return await _chatOllamaStreaming(
+        apiUrl,
+        { model, messages, tools },
+        options.onToken,
+        signal,
+      );
+    }
+    const response = await fetch(apiUrl, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       signal,
@@ -1817,6 +1831,109 @@ export async function chatWithTools(rawMessages, options) {
   return out;
 }
 
+// ─── Ollama streaming (token deltas for --include-partial-messages) ─────────
+//
+// Ollama `/api/chat` with `stream:true` returns NDJSON: one JSON object per
+// line, each carrying an incremental `message.content` chunk, optional
+// `message.tool_calls` (emitted whole, not byte-streamed), and a final line
+// with `done:true` + `prompt_eval_count`/`eval_count` token totals. We reduce
+// the stream line-by-line so onToken fires live, then finalize into the same
+// {message, usage} shape the non-streaming branch returns.
+
+function _ollamaInitState() {
+  return {
+    role: "assistant",
+    content: "",
+    toolCalls: null,
+    promptEval: 0,
+    evalCount: 0,
+  };
+}
+
+function _ollamaReduceLine(state, line, onToken) {
+  const s = (line || "").trim();
+  if (!s) return state;
+  let obj;
+  try {
+    obj = JSON.parse(s);
+  } catch {
+    return state; // tolerate partial/garbage lines mid-stream
+  }
+  const msg = obj.message;
+  if (msg) {
+    if (msg.role) state.role = msg.role;
+    if (typeof msg.content === "string" && msg.content) {
+      state.content += msg.content;
+      if (typeof onToken === "function") {
+        try {
+          onToken(msg.content);
+        } catch {
+          // A failing UI hook must never break the agent run.
+        }
+      }
+    }
+    if (Array.isArray(msg.tool_calls) && msg.tool_calls.length) {
+      state.toolCalls = (state.toolCalls || []).concat(msg.tool_calls);
+    }
+  }
+  if (obj.prompt_eval_count) state.promptEval = obj.prompt_eval_count;
+  if (obj.eval_count) state.evalCount = obj.eval_count;
+  return state;
+}
+
+function _ollamaFinalize(state) {
+  const message = { role: state.role, content: state.content };
+  if (state.toolCalls && state.toolCalls.length) {
+    message.tool_calls = state.toolCalls;
+  }
+  const data = { message };
+  if (state.promptEval || state.evalCount) {
+    data.usage = {
+      input_tokens: state.promptEval,
+      output_tokens: state.evalCount,
+    };
+  }
+  return data;
+}
+
+/**
+ * Pure reducer over an iterable of Ollama NDJSON lines. Exported for tests so
+ * the parse/accumulate logic can be exercised without a live HTTP stream.
+ */
+export function _accumulateOllamaStream(lines, onToken) {
+  const state = _ollamaInitState();
+  for (const line of lines) _ollamaReduceLine(state, line, onToken);
+  return _ollamaFinalize(state);
+}
+
+async function _chatOllamaStreaming(apiUrl, body, onToken, signal) {
+  const response = await fetch(apiUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    signal,
+    body: JSON.stringify({ ...body, stream: true }),
+  });
+  if (!response.ok) {
+    throw new Error(`Ollama error: ${response.status}`);
+  }
+  const state = _ollamaInitState();
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buf = "";
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buf += decoder.decode(value, { stream: true });
+    let idx;
+    while ((idx = buf.indexOf("\n")) >= 0) {
+      _ollamaReduceLine(state, buf.slice(0, idx), onToken);
+      buf = buf.slice(idx + 1);
+    }
+  }
+  if (buf.trim()) _ollamaReduceLine(state, buf, onToken);
+  return _ollamaFinalize(state);
+}
+
 function _normalizeAnthropicResponse(data) {
   const content = data.content || [];
   const textBlocks = content.filter((b) => b.type === "text");
@@ -1843,11 +1960,58 @@ function _normalizeAnthropicResponse(data) {
 
 // ─── Agent loop (async generator) ─────────────────────────────────────────
 
+// Tools that never mutate the workspace — auto-checkpoint skips these.
+const _CHECKPOINT_READ_ONLY = new Set([
+  "read_file",
+  "search_files",
+  "list_dir",
+  "list_skills",
+  "search_sessions",
+]);
+
+let _checkpointStoreP = null;
+function _loadCheckpointStore() {
+  if (!_checkpointStoreP) {
+    _checkpointStoreP = import("../lib/checkpoint-store.js");
+  }
+  return _checkpointStoreP;
+}
+
+/**
+ * Best-effort auto-checkpoint of the working tree BEFORE a mutating tool runs,
+ * so a later `cc checkpoint restore` can roll back to just before that tool.
+ * Enabled via toolContext.autoCheckpoint; uses the git engine only (no-op
+ * outside a git work tree). Never throws — checkpointing must not block a tool.
+ *
+ * @returns {Promise<string|null>} the checkpoint id, or null when skipped
+ */
+async function _autoCheckpointBeforeTool(toolContext, toolName, toolArgs) {
+  if (!toolContext?.autoCheckpoint) return null;
+  if (_CHECKPOINT_READ_ONLY.has(toolName)) return null;
+  const cwd = toolContext.cwd || process.cwd();
+  try {
+    const store = await _loadCheckpointStore();
+    if (!store.isCheckpointAvailable(cwd)) return null;
+    const res = store.createCheckpoint(cwd, {
+      session: toolContext.checkpointSession || "agent",
+      label: `before ${toolName}: ${formatToolArgs(toolName, toolArgs)}`.slice(
+        0,
+        120,
+      ),
+      skipIfUnchanged: true,
+    });
+    return res?.id || null;
+  } catch {
+    return null; // checkpoint failure must never block the tool
+  }
+}
+
 /**
  * Async generator that drives the agentic tool-use loop.
  *
  * Yields events:
  *   { type: "slot-filling", slot, question }  — when asking user for missing info
+ *   { type: "checkpoint", id, tool }          — auto-checkpoint before a mutating tool
  *   { type: "tool-executing", tool, args }
  *   { type: "tool-result", tool, result, error }
  *   { type: "response-complete", content }
@@ -1855,6 +2019,38 @@ function _normalizeAnthropicResponse(data) {
  * @param {Array} messages - mutable messages array (will be appended to)
  * @param {object} options - provider, model, baseUrl, apiKey, contextEngine, hookDb, skillLoader, cwd, slotFiller, interaction
  */
+/**
+ * Lazily build (and cache on `options`) the PromptCompressor used for in-loop
+ * auto-compaction. Returns null when the feature is off or the module can't be
+ * loaded — callers treat that as "don't compact". Cached (including null) so we
+ * import once per run, not once per iteration.
+ */
+async function _getAutoCompactor(options) {
+  if (Object.prototype.hasOwnProperty.call(options, "_autoCompactor")) {
+    return options._autoCompactor;
+  }
+  let compressor = null;
+  try {
+    const { feature } = await import("../lib/feature-flags.js");
+    if (feature("PROMPT_COMPRESSOR")) {
+      const { PromptCompressor } =
+        await import("../harness/prompt-compressor.js");
+      compressor = new PromptCompressor({
+        model: options.model,
+        provider: options.provider,
+      });
+    }
+  } catch {
+    compressor = null;
+  }
+  try {
+    options._autoCompactor = compressor;
+  } catch {
+    // options may be frozen — fine, we just re-import next iteration
+  }
+  return compressor;
+}
+
 export async function* agentLoop(messages, options) {
   // Shared iteration budget — replaces hardcoded MAX_ITERATIONS.
   // When options.iterationBudget is provided (e.g. from parent agent),
@@ -1879,6 +2075,9 @@ export async function* agentLoop(messages, options) {
     approvalGate: options.approvalGate || null,
     shellConfirm: options.shellConfirm || null,
     additionalDirectories: options.additionalDirectories || null,
+    autoCheckpoint: options.autoCheckpoint || false,
+    checkpointSession:
+      options.checkpointSession || options.sessionId || "agent",
   };
 
   throwIfAborted(signal);
@@ -1979,6 +2178,64 @@ export async function* agentLoop(messages, options) {
       };
     }
 
+    // Headless auto-compaction (Claude-Code `--print` parity). Keeps long
+    // `-p` / `--resume` runs under the model's context window instead of
+    // growing until the provider rejects the request. Opt-out with
+    // `autoCompact: false` (the interactive REPL does this — it compacts on its
+    // own schedule). Default-on, gated by the PROMPT_COMPRESSOR flag + a size
+    // threshold inside the compressor, so it only fires for genuinely large
+    // contexts. Safe to compact here: the previous iteration always finishes
+    // its full tool_call→tool_result cycle before we loop, so `messages` has no
+    // dangling call; `preserveToolPairs` then guarantees compaction never
+    // orphans a tool result. Best-effort — a failure never aborts the run.
+    if (options.autoCompact !== false && messages.length > 4) {
+      try {
+        const compactor = await _getAutoCompactor(options);
+        if (compactor && compactor.shouldAutoCompact(messages)) {
+          const { messages: compacted, stats } = await compactor.compress(
+            messages,
+            { preserveToolPairs: true },
+          );
+          if (stats.saved > 0 && compacted.length < messages.length) {
+            messages.splice(0, messages.length, ...compacted);
+            // Persist the compaction so a later --resume rebuilds from the
+            // shortened history. An explicit `onCompaction` hook (if a caller
+            // provides one) takes precedence; otherwise self-persist a `compact`
+            // event — but only when the session is already being persisted to
+            // disk (the JSONL file exists), so a one-shot `cc agent -p` (which
+            // never creates a session file) writes nothing. Opt out with
+            // `persistCompaction: false`. Best-effort throughout.
+            if (typeof options.onCompaction === "function") {
+              try {
+                options.onCompaction(stats, compacted);
+              } catch {
+                // persistence is best-effort
+              }
+            } else if (
+              options.sessionId &&
+              options.persistCompaction !== false
+            ) {
+              try {
+                const store = await import("../harness/jsonl-session-store.js");
+                if (store.sessionExists(options.sessionId)) {
+                  store.appendCompactEvent(options.sessionId, {
+                    ...stats,
+                    messages: compacted,
+                  });
+                }
+              } catch {
+                // self-persist is best-effort
+              }
+            }
+            yield { type: "compaction", stats, runId };
+          }
+        }
+      } catch (_e) {
+        if (isAbortError(_e) || signal?.aborted) throw _e;
+        // Compaction is best-effort — proceed with the uncompacted messages.
+      }
+    }
+
     // Turn-scoped context injection (open-agents prepareCall parity).
     // prepareCall runs fresh each iteration and returns an ephemeral
     // system-message supplement that is NOT persisted to messages history.
@@ -2050,6 +2307,15 @@ export async function* agentLoop(messages, options) {
         toolArgs = {};
       }
 
+      // Auto-checkpoint the work tree before a mutating tool (opt-in), so the
+      // user can `cc checkpoint restore` back to just before this call.
+      const cpId = await _autoCheckpointBeforeTool(
+        toolContext,
+        toolName,
+        toolArgs,
+      );
+      if (cpId) yield { type: "checkpoint", id: cpId, tool: toolName };
+
       yield { type: "tool-executing", tool: toolName, args: toolArgs };
 
       let toolResult;

package/src/runtime/headless-runner.js

@@ -26,12 +26,14 @@ import {
   agentLoop as coreAgentLoop,
   formatToolArgs,
 } from "./agent-core.js";
+import { loadMcpConfig } from "./mcp-config.js";
 import { IterationBudget } from "../lib/iteration-budget.js";
 import {
   startSession as jsonlStartSession,
   appendUserMessage as jsonlAppendUserMessage,
   appendAssistantMessage as jsonlAppendAssistantMessage,
   appendTokenUsage as jsonlAppendTokenUsage,
+  appendCompactEvent as jsonlAppendCompactEvent,
   rebuildMessages as jsonlRebuildMessages,
   sessionExists as jsonlSessionExists,
   getLastSessionId as jsonlGetLastSessionId,
@@ -190,6 +192,8 @@ export function resolveHeadlessSession(options = {}, store = {}, fallbackId) {
  *                                             (no id) → most-recent session.
  * @param {boolean} [options.continueSession]  Resume the most-recent session.
  * @param {boolean} [options.persistSession]   Force persistence without resume.
+ * @param {boolean} [options.autoCheckpoint]   Snapshot the work tree before each
+ *                                             mutating tool (git engine only).
  * @param {boolean} [options.expandFileRefs=true] Expand `@path` file references
  *                                             in the prompt into context blocks.
  * @param {object} [deps]                       Injection seam for tests.
@@ -243,6 +247,7 @@ export async function runAgentHeadless(options = {}, deps = {}) {
     appendAssistantMessage:
       deps.appendAssistantMessage || jsonlAppendAssistantMessage,
     appendTokenUsage: deps.appendTokenUsage || jsonlAppendTokenUsage,
+    appendCompactEvent: deps.appendCompactEvent || jsonlAppendCompactEvent,
     getLastSessionId: deps.getLastSessionId || jsonlGetLastSessionId,
   };
   const isStream = outputFormat === "stream-json";
@@ -365,6 +370,26 @@ export async function runAgentHeadless(options = {}, deps = {}) {
     }
   }
 
+  // --mcp-config: connect ad-hoc MCP servers for this run and expose their
+  // tools to the LLM (Claude-Code parity). Connection is best-effort — a server
+  // that fails to connect is logged to stderr and contributes no tools; a
+  // missing/empty config file fails fast (the user explicitly asked for MCP).
+  let mcp = null;
+  if (options.mcpConfig) {
+    const doLoadMcp = deps.loadMcpConfig || loadMcpConfig;
+    try {
+      mcp = await doLoadMcp(options.mcpConfig, { writeErr });
+      if (isText) {
+        for (const c of mcp.connected) {
+          writeErr(`  mcp: ${c.server} (${c.tools} tools)\n`);
+        }
+      }
+    } catch (err) {
+      writeErr(`Error: ${err.message}\n`);
+      return { exitCode: 1, result: err.message, isError: true };
+    }
+  }
+
   const loopOptions = {
     model,
     provider,
@@ -373,16 +398,55 @@ export async function runAgentHeadless(options = {}, deps = {}) {
     cwd,
     additionalDirectories,
     sessionId,
+    autoCheckpoint: options.autoCheckpoint || false,
+    checkpointSession: options.checkpointSession || sessionId,
     hookDb: db,
     approvalGate,
     enabledToolNames,
     disabledTools,
     iterationBudget: budget,
+    // --mcp-config wiring: tool defs for the LLM + dispatch map + live client.
+    mcpClient: mcp?.mcpClient || null,
+    extraToolDefinitions: mcp?.extraToolDefinitions || undefined,
+    externalToolExecutors: mcp?.externalToolExecutors || undefined,
+    externalToolDescriptors: mcp?.externalToolDescriptors || undefined,
     // chatFn passthrough lets tests drive the loop deterministically.
     chatFn: deps.chatFn || options.chatFn || undefined,
     signal: options.signal || undefined,
   };
 
+  // Goal binding (cc goal, Phase 1). `--goal <id>` binds explicitly; `--goal`
+  // with no value (options.goal === true) auto-resolves from active/session.
+  // When omitted, headless stays goal-free (no behavior change). Best-effort:
+  // a failure here must never fail the run.
+  let boundGoalId = null;
+  if (options.goal !== undefined && options.goal !== false) {
+    try {
+      const explicitId = typeof options.goal === "string" ? options.goal : null;
+      const { resolveActiveGoal, linkSession } =
+        await import("../lib/goal-store.js");
+      const goal = (deps.resolveActiveGoal || resolveActiveGoal)({
+        explicitId,
+        sessionId,
+      });
+      if (goal) {
+        const { goalPrepareCall } = await import("../lib/goal-context.js");
+        loopOptions.prepareCall = goalPrepareCall(goal);
+        boundGoalId = goal.id;
+        // Link the session so a later `--continue`/`--resume` keeps this goal.
+        if (explicitId && persist !== false) {
+          try {
+            linkSession(goal.id, sessionId);
+          } catch {
+            /* linking is optional polish — never fatal */
+          }
+        }
+      }
+    } catch {
+      /* goal binding is best-effort — proceed without it */
+    }
+  }
+
   const startedAt = deps.now ? deps.now() : Date.now();
   const toolCalls = [];
   const usage = { input_tokens: 0, output_tokens: 0 };
@@ -393,6 +457,21 @@ export async function runAgentHeadless(options = {}, deps = {}) {
     if (isStream) writeOut(JSON.stringify(obj) + "\n");
   };
 
+  // --include-partial-messages: forward live assistant-text deltas as
+  // `stream_event` NDJSON lines (Claude-Code parity). Only meaningful for
+  // stream-json output, where the agent loop's onToken hook feeds chunks as
+  // they arrive from a streaming provider.
+  if (isStream && options.includePartialMessages) {
+    loopOptions.onToken = (text) =>
+      emitStream({
+        type: "stream_event",
+        event: {
+          type: "content_block_delta",
+          delta: { type: "text_delta", text },
+        },
+      });
+  }
+
   emitStream({
     type: "system",
     subtype: "init",
@@ -405,11 +484,18 @@ export async function runAgentHeadless(options = {}, deps = {}) {
     resumed_from: resumeId,
     history_messages: history.length,
     additional_directories: additionalDirectories,
+    goal_id: boundGoalId,
   });
 
   try {
     for await (const event of runLoop(messages, loopOptions)) {
       switch (event.type) {
+        case "checkpoint": {
+          if (isText)
+            writeErr(`  ⎌ checkpoint ${event.id} (before ${event.tool})\n`);
+          emitStream({ type: "checkpoint", id: event.id, tool: event.tool });
+          break;
+        }
         case "tool-executing": {
           const line = `  [${event.tool}] ${formatToolArgs(event.tool, event.args)}`;
           if (isText) writeErr(line + "\n");
@@ -497,6 +583,17 @@ export async function runAgentHeadless(options = {}, deps = {}) {
       writeErr(`Error: ${message}\n`);
     }
     return { exitCode: 1, result: message, isError: true };
+  } finally {
+    // Tear down ad-hoc MCP servers (--mcp-config) before returning, whether the
+    // loop completed or threw. Best-effort: a failed disconnect never masks the
+    // run's own outcome.
+    if (mcp?.mcpClient) {
+      try {
+        await mcp.mcpClient.disconnectAll();
+      } catch {
+        // ignore — disconnect is best-effort
+      }
+    }
   }
 
   // coreAgentLoop emits run-ended reason "budget-exhausted" when the iteration
@@ -518,6 +615,56 @@ export async function runAgentHeadless(options = {}, deps = {}) {
     }
   }
 
+  // Run-end goal self-assessment (cc goal Phase 2, opt-in via --goal-assess).
+  // Spends one extra completion to judge whether the run advanced the bound
+  // goal, then persists progress / key-result / drift updates. Best-effort: it
+  // must never change the run's own outcome.
+  if (options.goalAssess && boundGoalId && !isError) {
+    try {
+      const { getGoal } = await import("../lib/goal-store.js");
+      const goal = (deps.getGoal || getGoal)(boundGoalId);
+      if (goal) {
+        const { assessGoalProgress } = await import("../lib/goal-assess.js");
+        const doAssess = deps.assessGoalProgress || assessGoalProgress;
+        const assessChat =
+          deps.assessChat ||
+          (async (assessPrompt) => {
+            const { chatWithTools } = await import("./agent-core.js");
+            const r = await chatWithTools(
+              [{ role: "user", content: assessPrompt }],
+              { model, provider, baseUrl, apiKey, enabledToolNames: [] },
+            );
+            return r?.message?.content || "";
+          });
+        const { assessment } = await doAssess({
+          goal,
+          transcript: { prompt: options.prompt, finalText, toolCalls },
+          chat: assessChat,
+        });
+        if (assessment) {
+          if (isText) {
+            writeErr(
+              `  ◎ goal ${boundGoalId}: ${assessment.advanced ? "advanced" : "no progress"}` +
+                (assessment.progress != null
+                  ? ` (${assessment.progress}%)`
+                  : "") +
+                "\n",
+            );
+          }
+          emitStream({
+            type: "goal_assessment",
+            goal_id: boundGoalId,
+            advanced: assessment.advanced,
+            progress: assessment.progress,
+            note: assessment.note,
+          });
+        }
+      }
+    } catch {
+      /* assessment is best-effort — never affect the run outcome */
+    }
+  }
+
   if (isStream) {
     emitStream({
       type: "result",

package/src/runtime/headless-stream.js

@@ -207,6 +207,26 @@ export async function runAgentHeadlessStream(options = {}, deps = {}) {
     additional_directories: additionalDirectories,
   });
 
+  // Goal binding (cc goal, Phase 1) — resolved once and injected on every turn.
+  // `--goal <id>` binds explicitly; `--goal` with no value auto-resolves.
+  let goalPrepareCallFn;
+  if (options.goal !== undefined && options.goal !== false) {
+    try {
+      const explicitId = typeof options.goal === "string" ? options.goal : null;
+      const { resolveActiveGoal } = await import("../lib/goal-store.js");
+      const goal = (deps.resolveActiveGoal || resolveActiveGoal)({
+        explicitId,
+        sessionId,
+      });
+      if (goal) {
+        const { goalPrepareCall } = await import("../lib/goal-context.js");
+        goalPrepareCallFn = goalPrepareCall(goal);
+      }
+    } catch {
+      /* goal binding is best-effort — proceed without it */
+    }
+  }
+
   const loopOptionsBase = {
     model,
     provider,
@@ -219,8 +239,22 @@ export async function runAgentHeadlessStream(options = {}, deps = {}) {
     approvalGate,
     enabledToolNames,
     disabledTools,
+    prepareCall: goalPrepareCallFn,
     chatFn: deps.chatFn || options.chatFn || undefined,
     signal: options.signal || undefined,
+    // --include-partial-messages: stream live assistant-text deltas as
+    // `stream_event` lines. Output here is always NDJSON, so gating on the
+    // flag alone suffices.
+    onToken: options.includePartialMessages
+      ? (text) =>
+          emit({
+            type: "stream_event",
+            event: {
+              type: "content_block_delta",
+              delta: { type: "text_delta", text },
+            },
+          })
+      : undefined,
   };
 
   let turns = 0;