@zergai/ztc 0.3.0-beta.1 → 0.4.0-beta.1

package/dist/zlm-embed.mjs

@@ -555,9 +555,9 @@ function incompleteModelResponseMessage(stopReason, maxTokens, outputTokens) {
   const exhausted = reason === "incomplete" && maxTokens !== void 0 && outputTokens !== void 0 && outputTokens >= maxTokens;
   if (limited || exhausted) {
     if (maxTokens === void 0) {
-      return "Model reached the provider's output limit (including reasoning). Set maxTokens within the model's limit or lower reasoning effort, then retry; the incomplete response was not accepted.";
+      return "Model reached the provider's output limit (including reasoning). Use /config max-tokens <number> within the model's limit or lower reasoning effort, then retry; completed tool work is retained and the incomplete response was not accepted.";
     }
-    return `Model reached the output limit (maxTokens: ${maxTokens}, including reasoning). Increase maxTokens and retry; the incomplete response was not accepted.`;
+    return `Model reached the output limit (maxTokens: ${maxTokens}, including reasoning). Set /config max-tokens <number> or /config max-tokens default, then retry. Completed tool work is retained; the incomplete response was not accepted.`;
   }
   return INCOMPLETE_MODEL_RESPONSE_MESSAGE;
 }
@@ -825,7 +825,7 @@ function buildOpenAIMessages(request) {
       } else if (block.type === "tool_use") {
         toolUses.push({ id: block.id, name: block.name, input: block.input });
       } else if (block.type === "tool_result") {
-        toolResults.push({ tool_use_id: block.tool_use_id, content: block.content });
+        toolResults.push({ tool_use_id: block.tool_use_id, content: block.content, is_error: block.is_error });
       } else if (block.type === "image") {
         mediaParts.push({
           type: "image_url",
@@ -863,7 +863,7 @@ function buildOpenAIMessages(request) {
         out.push({
           role: "tool",
           tool_call_id: tr.tool_use_id,
-          content: resultText
+          content: tr.is_error && !/^error\b/i.test(resultText) ? `Error: ${resultText}` : resultText
         });
       }
       if (textParts.length > 0 || mediaParts.length > 0) {
@@ -1385,7 +1385,7 @@ function buildResponsesInput(messages) {
           input.push({
             type: "function_call_output",
             call_id: block.tool_use_id,
-            output: resultText
+            output: block.is_error && !/^error\b/i.test(resultText) ? `Error: ${resultText}` : resultText
           });
           break;
         }
@@ -1808,7 +1808,7 @@ var init_gemini = __esm({
             }
             if (block.type === "tool_result") {
               const resultText = typeof block.content === "string" ? block.content : block.content.map((b) => b.type === "text" ? b.text : "[image]").join("\n");
-              return { text: `Function result: ${resultText}` };
+              return { text: `Function ${block.tool_use_id} ${block.is_error ? "error" : "result"}: ${resultText}` };
             }
             if (block.type === "tool_use") {
               return { functionCall: { name: block.name, args: block.input } };
@@ -5661,6 +5661,8 @@ var init_deferred = __esm({
       "list_directory",
       "search",
       "run_command",
+      "read_command",
+      "stop_command",
       "apply_patch",
       // Emulation compatibility aliases. They only appear in the request when
       // the active emulation adds matching tools to the runtime tool list.
@@ -5917,6 +5919,7 @@ var init_tool_response_store = __esm({
           timestamp: (/* @__PURE__ */ new Date()).toISOString(),
           turn: this.turnCounter++,
           partial,
+          ...context?.isError === void 0 ? {} : { is_error: context.isError },
           preview
         };
         const sourcePath = context?.sourcePath ?? null;
@@ -7235,6 +7238,10 @@ var init_config = __esm({
           ...this.cliOverrides.model !== void 0 ? { model: this.cliOverrides.model } : {}
         };
       }
+      getMaxTokensSource() {
+        if (Object.prototype.hasOwnProperty.call(this.sessionOverrides, "maxTokens")) return "session override";
+        return this.config.maxTokens === void 0 ? "provider default" : `saved profile (${this.getConfigPath()})`;
+      }
       getConfigScope() {
         return this.configScope;
       }
@@ -9308,8 +9315,8 @@ init_backends();
 init_token_usage();
 init_transport_errors();
 init_defaults();
-import { randomUUID as randomUUID5 } from "node:crypto";
-import { existsSync as existsSync5, readFileSync as readFileSync7 } from "fs";
+import { randomUUID as randomUUID6 } from "node:crypto";
+import { existsSync as existsSync5, readFileSync as readFileSync8 } from "fs";
 import { extname } from "path";
 
 // src/config/api_retry.ts
@@ -9348,9 +9355,244 @@ function resolveApiRetrySettings(config) {
   };
 }
 
+// src/config/execution.ts
+function resolveExecutionSettings(settings = {}) {
+  const count = (value, fallback, max, min = 1) => Number.isSafeInteger(value) && value >= min && value <= max ? value : fallback;
+  return {
+    shellPanePolicy: settings.shellPanePolicy === "auto" ? "auto" : "on_request",
+    readConcurrency: count(settings.readConcurrency, 4, 32),
+    maxCallsPerResponse: count(settings.maxCallsPerResponse, 16, 256),
+    recovery: settings.recovery === "pause" ? "pause" : "automatic",
+    repeatedFailureLimit: count(settings.repeatedFailureLimit, 3, 20),
+    recoveryAttempts: count(settings.recoveryAttempts, 1, 5, 0),
+    interruptBackgroundJobs: settings.interruptBackgroundJobs === true,
+    maxBackgroundJobs: count(settings.maxBackgroundJobs, 4, 32)
+  };
+}
+
+// src/agent/runtime/recovery.ts
+function normalizeFailure(content) {
+  const text = content.toLowerCase();
+  if (/not_executed/.test(text)) return "";
+  for (const [pattern, cause] of [
+    [/heredoc|unexpected end of file|unterminated/, "unfinished shell input"],
+    [/permission denied|eacces/, "permission denied"],
+    [/not found|enoent|unknown tool|unavailable/, "capability or file unavailable"],
+    [/timeout|timed out/, "timeout"],
+    [/syntaxerror|syntax error|invalid.*syntax/, "syntax error"]
+  ]) if (pattern.test(text)) return cause;
+  const exit = text.match(/command failed \(exit (\d+)\)/);
+  if (exit) return `command exit ${exit[1]}`;
+  return text.split("\n")[0].replace(/['"`][^'"`]*['"`]/g, "<value>").replace(/\d+/g, "#").trim().slice(0, 240);
+}
+function createRecoveryGuard(settings) {
+  const limits = resolveExecutionSettings(settings);
+  let cause = "";
+  let failures = 0;
+  let attempts = 0;
+  let neutralSteps = 0;
+  const observations = /* @__PURE__ */ new Set();
+  return (results) => {
+    let failed = false;
+    let progress = false;
+    let neutral = false;
+    for (const result of results) {
+      if (result.isError) {
+        const next = normalizeFailure(result.content);
+        if (!next) continue;
+        failed = true;
+        failures = next === cause ? failures + 1 : 1;
+        cause = next;
+      } else {
+        const signature = `${result.name}\0${result.content}`;
+        const acknowledgement = /^(Input (?:delivered|queued|sent)|Sent input|\(Terminal buffer is empty\))/.test(result.content) || /"status":"running"/.test(result.content) && /"output":""/.test(result.content);
+        neutral ||= acknowledgement;
+        if (result.content.trim() && !acknowledgement && !observations.has(signature)) progress = true;
+        observations.add(signature);
+      }
+    }
+    if (progress && !failed) {
+      failures = 0;
+      cause = "";
+      attempts = 0;
+      neutralSteps = 0;
+    }
+    if (failures < limits.repeatedFailureLimit) return "continue";
+    if (!failed && neutral && attempts > 0 && neutralSteps++ < 1) return "continue";
+    if (limits.recovery === "pause" || attempts >= limits.recoveryAttempts) return "stop";
+    attempts++;
+    neutralSteps = 0;
+    return "recover";
+  };
+}
+
+// src/agent/runtime/command_jobs.ts
+import { randomUUID as randomUUID5, createHash as createHash3 } from "node:crypto";
+import { appendFileSync as appendFileSync4, closeSync, mkdirSync as mkdirSync3, openSync, readFileSync as readFileSync6, readSync, readdirSync, rmSync, rmdirSync, statSync, writeFileSync as writeFileSync5 } from "node:fs";
+import { homedir as homedir6 } from "node:os";
+import { join as join11 } from "node:path";
+
+// src/utils/subprocess_env.ts
+var USER_SUBPROCESS_STRIPPED_ZTC_ENV = [
+  "ZERG_ROUTER_BASE_URL",
+  "ZTC_AUTH_TOKEN",
+  "ZTC_CHILD_ENTRYPOINT",
+  "ZTC_COLONY_CHILD",
+  "ZTC_COLONY_PARENT_MIRROR_PORT",
+  "ZTC_COLONY_WORKTREE_ID",
+  "ZTC_MIRROR_PORT",
+  "ZTC_MIRROR_INTERNAL_TOKEN",
+  "ZTC_MIRROR_REQUIRE_AUTH",
+  "ZTC_MIRROR_SHARED_SECRET",
+  "ZTC_NAVIGATOR_GROUP",
+  "ZTC_PANE_ID",
+  "ZTC_PANE_RELAY",
+  "ZTC_PARENT_PID"
+];
+function buildUserSubprocessEnv(source = process.env) {
+  const env = { ...source };
+  for (const key of USER_SUBPROCESS_STRIPPED_ZTC_ENV) {
+    delete env[key];
+  }
+  return env;
+}
+
+// src/utils/shell.ts
+var DOCKER_CONTAINER = process.env.ZTC_DOCKER_CONTAINER;
+var DOCKER_WORKDIR = process.env.ZTC_DOCKER_WORKDIR || "/app";
+
+// src/agent/runtime/command_jobs.ts
+var MAX_LOG_BYTES = 16 * 1024 * 1024;
+var RETENTION_MS = 7 * 24 * 60 * 60 * 1e3;
+var sessions = /* @__PURE__ */ new Map();
+function directory(sessionId) {
+  return join11(
+    process.env.ZTC_CONFIG_DIR || join11(homedir6(), ".ztc"),
+    "command-jobs",
+    createHash3("sha256").update(sessionId).digest("hex").slice(0, 32)
+  );
+}
+function save(sessionId, receipt) {
+  writeFileSync5(join11(directory(sessionId), `${receipt.job_id}.json`), JSON.stringify(receipt), { mode: 384 });
+}
+function resolveJob(sessionId, jobId) {
+  if (!/^[0-9a-f-]{36}$/.test(jobId)) throw new Error("Command job not found in this session");
+  const live = sessions.get(sessionId)?.get(jobId);
+  if (live) return live;
+  let receipt;
+  try {
+    receipt = JSON.parse(readFileSync6(join11(directory(sessionId), `${jobId}.json`), "utf8"));
+  } catch {
+    throw new Error("Command job not found in this session");
+  }
+  if (receipt.status === "running") {
+    receipt = { ...receipt, status: "interrupted", ended_at: (/* @__PURE__ */ new Date()).toISOString(), error: "Owning ZTC process ended; inspect output before retrying." };
+    save(sessionId, receipt);
+  }
+  return { receipt, controller: new AbortController(), done: Promise.resolve(), loggedBytes: statSync(receipt.log_path).size };
+}
+function listCommandJobs(sessionId) {
+  const jobs = [...sessions.get(sessionId)?.values() ?? []];
+  return [...jobs.filter((job) => job.receipt.status === "running"), ...jobs.filter((job) => job.receipt.status !== "running").slice(-28)].map((job) => ({ ...job.receipt }));
+}
+async function stopCommandJob(sessionId, jobId) {
+  const job = resolveJob(sessionId, jobId);
+  if (job.receipt.status === "running") {
+    job.controller.abort();
+    await job.done;
+  }
+  return { ...job.receipt };
+}
+async function interruptCommandJobs(sessionId) {
+  await Promise.all(listCommandJobs(sessionId).filter((job) => job.status === "running").map((job) => stopCommandJob(sessionId, job.job_id)));
+}
+
+// src/agent/runtime/execution_context.ts
+function describeExecutionContext(context) {
+  const names = new Set(context.tools);
+  const shell = ["run_command", "Bash", "exec_command", "shell_command"].filter((name) => names.has(name));
+  const panes = ["create_terminal_pane", "read_terminal_pane", "write_terminal_pane"].filter((name) => names.has(name));
+  return [
+    "## Current execution capabilities (host facts; refreshed each request)",
+    `Mode: ${context.mode}. Cwd: ${context.cwd}. Config write scope: ${context.configScope}.`,
+    `Output cap: ${context.maxTokens ?? "provider default"} (source: ${context.outputLimitSource}). Use /config max-tokens <number|default> to change it.`,
+    `Shell: ${shell.length ? shell.join(", ") : "unavailable in the current tool surface"}.`,
+    `Mux: ${context.mux ? "connected" : "unavailable"}. Pane tools: ${panes.join(", ") || "unavailable in this mode"}.`,
+    `Shell-pane policy: ${context.settings.shellPanePolicy === "on_request" ? "create a shell pane only when the user explicitly requests a visible or interactive shell; otherwise use run_command" : "may create shell panes automatically when useful"}.`,
+    `Registered tools: ${context.tools.slice(0, 80).join(", ")}. Deferred schemas can be discovered with tool_search when available.`,
+    `Batch limit: ${context.settings.maxCallsPerResponse}. Read concurrency: ${context.settings.readConcurrency}. Inspect a failed or running command before submitting dependent work.`,
+    "For multiline scripts use run_command stdin or write_file and execute the file. Pane text supports multiline submission; raw Ctrl+C (U+0003, submit=false) cancels stuck shell input. A write acknowledgement does not prove command success.",
+    `Managed commands: ${context.jobs.length ? JSON.stringify(context.jobs.map(({ job_id, status, cwd, exit_code }) => ({ job_id, status, cwd, exit_code }))) : "none"}. Background commands ${context.settings.interruptBackgroundJobs ? "are cancelled" : "survive"} on turn interruption; application shutdown stops owned local jobs. Remote cleanup belongs to the launched command.`,
+    "If a tool is unavailable, inspect these current facts and mode restrictions. Do not infer that the session never had shell access from a previous mode or a failed invocation."
+  ].join("\n");
+}
+
+// src/agent/runtime/tool_effects.ts
+init_capabilities();
+function resolveToolEffect(tool) {
+  if (tool.effect) return tool.effect;
+  const capabilities = new Set(tool.capabilities ?? []);
+  if (capabilities.has("shell_exec" /* SHELL_EXEC */) || capabilities.has("network" /* NETWORK */) || capabilities.has("computer_control" /* COMPUTER_CONTROL */) || capabilities.has("ml_inference" /* ML_INFERENCE */)) {
+    return "external";
+  }
+  if (capabilities.has("file_write" /* FILE_WRITE */)) return "write";
+  return "read";
+}
+
+// src/agent/runtime/tool_scheduler.ts
+async function scheduleToolBatch(calls, tools, settings, execute, blocksFollowing, signal, exclusiveId) {
+  const limits = resolveExecutionSettings(settings);
+  const registered = new Map(tools.map((tool) => [tool.definition.name, tool]));
+  const parallel = (call) => {
+    const tool = registered.get(call.name);
+    return tool?.parallelSafe === true && resolveToolEffect(tool) === "read";
+  };
+  const results = [];
+  let effectsBlocked = false;
+  let stopped = calls.length > limits.maxCallsPerResponse ? `batch_limit: ${calls.length} calls exceeds ${limits.maxCallsPerResponse}; submit a smaller batch after inspecting results.` : "";
+  for (let index = 0; index < calls.length; ) {
+    const call = calls[index];
+    if (signal?.aborted) stopped = "cancelled: the turn was interrupted.";
+    if (stopped) {
+      results.push(await execute(call, `not_executed: ${stopped}`));
+      index++;
+      continue;
+    }
+    if (effectsBlocked && !parallel(call)) {
+      results.push(await execute(call, "not_executed: a previous call failed or is still running; inspect its result before continuing effects."));
+      index++;
+      continue;
+    }
+    if (exclusiveId && call.id !== exclusiveId) {
+      results.push(await execute(call, "not_executed: exclusive safety transition must run alone."));
+      index++;
+      continue;
+    }
+    let end = index + 1;
+    if (!exclusiveId && parallel(call)) {
+      while (end < calls.length && end - index < limits.readConcurrency && parallel(calls[end])) end++;
+    }
+    const batch = await Promise.all(calls.slice(index, end).map((item) => execute(item)));
+    results.push(...batch);
+    if (batch.some(blocksFollowing)) {
+      effectsBlocked = true;
+    }
+    index = end;
+  }
+  return results;
+}
+function commandStillRunning(content) {
+  try {
+    const result = JSON.parse(content);
+    return result.status === "running" && typeof result.job_id === "string";
+  } catch {
+    return false;
+  }
+}
+
 // src/agent/runtime/policy.ts
 init_capabilities();
-import { homedir as homedir6 } from "os";
+import { homedir as homedir7 } from "os";
 import { resolve as resolve4, isAbsolute as isAbsolute2, sep } from "path";
 var AllowAllPolicy = class {
   evaluateTool() {
@@ -9497,7 +9739,7 @@ function extractPathArgs(args) {
   return paths;
 }
 function normalizeRoot(path, cwd) {
-  const expanded = path === "~" ? homedir6() : path.replace(/^~(?=\/|$)/, homedir6());
+  const expanded = path === "~" ? homedir7() : path.replace(/^~(?=\/|$)/, homedir7());
   return resolve4(isAbsolute2(expanded) ? expanded : resolve4(cwd, expanded));
 }
 function isWithinRoot(path, root) {
@@ -9617,8 +9859,8 @@ init_tool_response_store();
 
 // src/utils/mirror_media.ts
 import { tmpdir as tmpdir2 } from "os";
-import { join as join11, resolve as resolve5, sep as sep2 } from "path";
-var MIRROR_MEDIA_ROOT = join11(tmpdir2(), "ztc-mirror-media");
+import { join as join12, resolve as resolve5, sep as sep2 } from "path";
+var MIRROR_MEDIA_ROOT = join12(tmpdir2(), "ztc-mirror-media");
 function isMirrorMediaPath(localPath) {
   if (!localPath) return false;
   const root = resolve5(MIRROR_MEDIA_ROOT);
@@ -9711,6 +9953,7 @@ var RequestEncoder = class {
         const verdict = this.deps.selectorVerdict;
         const rerendered = toolResults.map((r) => ({
           tool_use_id: r.tool_use_id,
+          ...r.is_error === void 0 ? {} : { is_error: r.is_error },
           // Coerce to '' as a last resort: a tool_result entry that carries a
           // tool_use_id but no content must still encode as a valid tool_result
           // block (content must be a string for the API), not as undefined —
@@ -9807,6 +10050,7 @@ var RequestEncoder = class {
         return {
           type: "tool_result",
           tool_use_id: result.tool_use_id,
+          ...result.is_error === void 0 ? {} : { is_error: result.is_error },
           content: [
             { type: "text", text: parsed.text },
             {
@@ -9830,6 +10074,7 @@ var RequestEncoder = class {
       return {
         type: "tool_result",
         tool_use_id: result.tool_use_id,
+        ...result.is_error === void 0 ? {} : { is_error: result.is_error },
         content
       };
     });
@@ -9844,13 +10089,13 @@ init_tool_compression();
 // src/agent/runtime/tool_runtime.ts
 init_capabilities();
 init_config();
-import { basename as basename3, dirname as dirname6, join as join13, relative as relative2, resolve as resolve7 } from "path";
+import { basename as basename3, dirname as dirname6, join as join14, relative as relative2, resolve as resolve7 } from "path";
 import { realpathSync } from "node:fs";
 import { appendFile } from "node:fs/promises";
 
 // src/context/intents_loader.ts
-import { appendFileSync as appendFileSync4, existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync6, statSync, writeFileSync as writeFileSync5 } from "fs";
-import { basename as basename2, dirname as dirname5, join as join12, relative, resolve as resolve6 } from "path";
+import { appendFileSync as appendFileSync5, existsSync as existsSync4, mkdirSync as mkdirSync4, readFileSync as readFileSync7, statSync as statSync2, writeFileSync as writeFileSync6 } from "fs";
+import { basename as basename2, dirname as dirname5, join as join13, relative, resolve as resolve6 } from "path";
 var DEFAULT_MAX_BYTES = 32 * 1024;
 var DEFAULT_FILE_INTENT_THRESHOLD_LINES = 400;
 function loadIntentsContext(cwd = process.cwd(), settings, options = {}) {
@@ -9910,7 +10155,7 @@ function maybeAutoUpdateIntents(options) {
     const relChanged = relative(options.cwd, absolutePath) || basename2(absolutePath);
     const note = `- ${(/* @__PURE__ */ new Date()).toISOString()}: tool \`${options.toolName}\` changed \`${relChanged}\`. Keep this file's higher-level intent current if behavior changed.
 `;
-    appendFileSync4(target, note, "utf-8");
+    appendFileSync5(target, note, "utf-8");
     updated.add(relative(options.cwd, target) || basename2(target));
   }
   return [...updated];
@@ -9921,7 +10166,7 @@ function buildIntentCandidates(cwd, relatedPaths, includeHierarchy) {
   if (includeHierarchy) {
     const roots = findRootToCwd(resolve6(cwd));
     for (const dir of roots) {
-      pushUnique(candidates, seen, join12(dir, ".ztc-intents.md"));
+      pushUnique(candidates, seen, join13(dir, ".ztc-intents.md"));
     }
   }
   for (const relatedPath of relatedPaths) {
@@ -9935,7 +10180,7 @@ function findRootToCwd(cwd) {
   let current = cwd;
   for (; ; ) {
     chain.push(current);
-    if (existsSync4(join12(current, ".git"))) {
+    if (existsSync4(join13(current, ".git"))) {
       break;
     }
     const parent = dirname5(current);
@@ -9950,21 +10195,21 @@ function selectIntentTarget(cwd, absolutePath, threshold) {
   if (isLargeFile(absolutePath, threshold)) {
     return fileIntentPath(absolutePath);
   }
-  const dir = existsSync4(absolutePath) && statSync(absolutePath).isDirectory() ? absolutePath : dirname5(absolutePath);
+  const dir = existsSync4(absolutePath) && statSync2(absolutePath).isDirectory() ? absolutePath : dirname5(absolutePath);
   const normalizedCwd = resolve6(cwd);
   const normalizedDir = resolve6(dir);
   if (!isInside(normalizedDir, normalizedCwd)) {
-    return join12(normalizedCwd, ".ztc-intents.md");
+    return join13(normalizedCwd, ".ztc-intents.md");
   }
-  return join12(normalizedDir, ".ztc-intents.md");
+  return join13(normalizedDir, ".ztc-intents.md");
 }
 function ensureIntentFile(path) {
-  mkdirSync3(dirname5(path), { recursive: true });
+  mkdirSync4(dirname5(path), { recursive: true });
   if (existsSync4(path)) {
     return;
   }
   const title = basename2(path) === ".ztc-intents.md" ? "ZTC Folder Intents" : `ZTC File Intents for ${basename2(path).replace(/^\.ztc-intents-/, "").replace(/\.md$/, "")}`;
-  writeFileSync5(path, [
+  writeFileSync6(path, [
     `# ${title}`,
     "",
     "Purpose:",
@@ -9974,14 +10219,14 @@ function ensureIntentFile(path) {
   ].join("\n") + "\n", "utf-8");
 }
 function fileIntentPath(absolutePath) {
-  return join12(dirname5(absolutePath), `.ztc-intents-${basename2(absolutePath)}.md`);
+  return join13(dirname5(absolutePath), `.ztc-intents-${basename2(absolutePath)}.md`);
 }
 function isLargeFile(path, threshold) {
   try {
-    if (!existsSync4(path) || statSync(path).isDirectory()) {
+    if (!existsSync4(path) || statSync2(path).isDirectory()) {
       return false;
     }
-    const raw = readFileSync6(path, "utf-8");
+    const raw = readFileSync7(path, "utf-8");
     return raw.split("\n").length >= threshold;
   } catch {
     return false;
@@ -9992,7 +10237,7 @@ function loadBudgetedFile(path, maxBytes) {
     return null;
   }
   try {
-    const raw = readFileSync6(path, "utf-8");
+    const raw = readFileSync7(path, "utf-8");
     const bytes = Buffer.byteLength(raw, "utf-8");
     if (bytes <= maxBytes) {
       return {
@@ -10028,18 +10273,6 @@ function isInside(path, root) {
   return path === root || path.startsWith(`${root}/`);
 }
 
-// src/agent/runtime/tool_effects.ts
-init_capabilities();
-function resolveToolEffect(tool) {
-  if (tool.effect) return tool.effect;
-  const capabilities = new Set(tool.capabilities ?? []);
-  if (capabilities.has("shell_exec" /* SHELL_EXEC */) || capabilities.has("network" /* NETWORK */) || capabilities.has("computer_control" /* COMPUTER_CONTROL */) || capabilities.has("ml_inference" /* ML_INFERENCE */)) {
-    return "external";
-  }
-  if (capabilities.has("file_write" /* FILE_WRITE */)) return "write";
-  return "read";
-}
-
 // src/agent/runtime/tool_runtime.ts
 function getTool(name, tools) {
   return tools.find((t) => t.definition.name === name);
@@ -10049,7 +10282,7 @@ function isHostControlPlaneWrite(tool, args, cwd) {
   try {
     const noFollowLeaf = (path) => {
       const absolute = resolve7(path);
-      return join13(realpathSync(dirname6(absolute)), basename3(absolute));
+      return join14(realpathSync(dirname6(absolute)), basename3(absolute));
     };
     return noFollowLeaf(resolve7(cwd, args.path)) === noFollowLeaf(tool.hostControlPlaneWritePath);
   } catch {
@@ -10058,7 +10291,7 @@ function isHostControlPlaneWrite(tool, args, cwd) {
 }
 async function executeTool(name, args, tools, context) {
   const tool = getTool(name, tools);
-  if (!tool) throw new Error("Unknown tool: " + name);
+  if (!tool) throw new Error(`Unknown tool: ${name}. It is unavailable in the current mode or provider surface. Inspect current execution capabilities and use an available tool; shell execution requires run_command or a registered alias.`);
   return tool.execute(args, context);
 }
 function buildHookText(messages) {
@@ -10117,7 +10350,7 @@ ${intentContext}`;
 async function recordToolTrace(entry) {
   const configured = process.env.ZTC_TOOL_TRACE;
   if (!configured) return;
-  const target = configured === "1" ? join13(process.cwd(), "ztc-tool-trace.jsonl") : configured;
+  const target = configured === "1" ? join14(process.cwd(), "ztc-tool-trace.jsonl") : configured;
   try {
     await appendFile(target, `${JSON.stringify(entry)}
 `, "utf-8");
@@ -10325,6 +10558,7 @@ async function executeToolWithRuntime(name, args, options) {
         if (timer) clearTimeout(timer);
       });
     }
+    if (tool?.isErrorResult?.(output)) throw new Error(output);
     const TOOL_OUTPUT_CAP = 8e4;
     output = augmentReadResultWithIntent(name, effectiveArgs, output, cwd);
     let resultContent = output;
@@ -10399,31 +10633,6 @@ async function executeToolWithRuntime(name, args, options) {
   }
 }
 
-// src/utils/subprocess_env.ts
-var USER_SUBPROCESS_STRIPPED_ZTC_ENV = [
-  "ZERG_ROUTER_BASE_URL",
-  "ZTC_AUTH_TOKEN",
-  "ZTC_CHILD_ENTRYPOINT",
-  "ZTC_COLONY_CHILD",
-  "ZTC_COLONY_PARENT_MIRROR_PORT",
-  "ZTC_COLONY_WORKTREE_ID",
-  "ZTC_MIRROR_PORT",
-  "ZTC_MIRROR_INTERNAL_TOKEN",
-  "ZTC_MIRROR_REQUIRE_AUTH",
-  "ZTC_MIRROR_SHARED_SECRET",
-  "ZTC_NAVIGATOR_GROUP",
-  "ZTC_PANE_ID",
-  "ZTC_PANE_RELAY",
-  "ZTC_PARENT_PID"
-];
-function buildUserSubprocessEnv(source = process.env) {
-  const env = { ...source };
-  for (const key of USER_SUBPROCESS_STRIPPED_ZTC_ENV) {
-    delete env[key];
-  }
-  return env;
-}
-
 // src/utils/compaction.ts
 init_provider_ids();
 init_context();
@@ -10593,6 +10802,9 @@ var Agent = class _Agent {
       maxTokens: config.maxTokens,
       routePlan: config.routePlan,
       maxIterations: config.maxIterations || 10,
+      execution: resolveExecutionSettings(config.execution),
+      sessionId: config.sessionId ?? randomUUID6(),
+      runtimeFacts: config.runtimeFacts ?? {},
       apiRetry: resolveApiRetrySettings({ apiRetry: config.apiRetry }),
       llmRequestTimeoutMs: resolveLlmRequestTimeoutMs(
         config.llmRequestTimeoutMs,
@@ -10821,7 +11033,7 @@ INVESTIGATION STRATEGY \u2014 before making tool calls to explore or debug, foll
       const ext = extname(path).toLowerCase();
       const mediaType = this.getImageMediaType(ext);
       if (!mediaType) return null;
-      const buffer = readFileSync7(path);
+      const buffer = readFileSync8(path);
       return {
         type: "image",
         mediaType,
@@ -10881,7 +11093,7 @@ INVESTIGATION STRATEGY \u2014 before making tool calls to explore or debug, foll
       const ext = extname(path).toLowerCase();
       const mediaType = this.getVideoMediaType(ext);
       if (!mediaType) return null;
-      const buffer = readFileSync7(path);
+      const buffer = readFileSync8(path);
       return {
         type: "video",
         mediaType,
@@ -10915,7 +11127,8 @@ INVESTIGATION STRATEGY \u2014 before making tool calls to explore or debug, foll
         if (!Array.isArray(parsed)) return null;
         return parsed.filter((item) => typeof item.tool_use_id === "string").map((item) => ({
           tool_use_id: item.tool_use_id,
-          content: typeof item.content === "string" ? item.content : String(item.content ?? "")
+          content: typeof item.content === "string" ? item.content : String(item.content ?? ""),
+          is_error: item.is_error
         }));
       } catch {
         return null;
@@ -10996,7 +11209,7 @@ INVESTIGATION STRATEGY \u2014 before making tool calls to explore or debug, foll
 [truncated \u2014 ${content.length} chars total]`;
         }
         emittedToolResultIds.add(tc.id);
-        return { tool_use_id: tc.id, content };
+        return { tool_use_id: tc.id, content, is_error: Boolean(tc.error) || tc.result == null };
       });
       if (toolResults.length === 0) continue;
       const syntheticReason = hasStoredResults ? "synth_tui_tool_results" : "repair_orphaned_tool_use";
@@ -11011,12 +11224,30 @@ INVESTIGATION STRATEGY \u2014 before making tool calls to explore or debug, foll
     return repaired;
   }
   buildRequest(messages, availableTools = this.config.tools) {
+    if (this.config.pinTaskHeader) {
+      const facts = describeExecutionContext({ ...this.getExecutionContext(), tools: availableTools.map((tool) => tool.definition.name) });
+      const latestFacts = [...messages].reverse().find((message) => typeof message.metadata?.executionContext === "string")?.metadata?.executionContext;
+      if (facts !== latestFacts) {
+        const latestUser = [...messages].reverse().find((message) => message.role === "user");
+        if (latestUser) latestUser.metadata = { ...latestUser.metadata, executionContext: facts };
+      }
+    }
     const repairedMessages = this.repairConversationHistory(messages);
+    const contextMessages = this.config.pinTaskHeader ? repairedMessages.flatMap((message) => {
+      const facts = message.metadata?.executionContext;
+      return typeof facts === "string" ? [message, {
+        id: `${message.id}_execution`,
+        role: "user",
+        content: facts,
+        timestamp: message.timestamp,
+        metadata: { synthetic: true }
+      }] : [message];
+    }) : repairedMessages;
     return {
       model: this.config.model,
       maxTokens: this.config.maxTokens,
       system: this.systemWithTaskHeader(messages),
-      messages: this.formatMessages(repairedMessages),
+      messages: this.formatMessages(contextMessages),
       tools: getRequestToolDefinitions(
         availableTools,
         this.discoveredTools,
@@ -11211,11 +11442,9 @@ INVESTIGATION STRATEGY \u2014 before making tool calls to explore or debug, foll
    */
   _taskHeader = null;
   /**
-   * Drop the pinned task so the NEXT conversation re-captures its own first user
-   * message. Wired into the /clear-only path (clearTransientState), never into
+   * Drop the explicitly pinned task for the next conversation. Wired into the /clear-only path (clearTransientState), never into
    * /compact — the pin must survive compaction (that is the whole point of R7).
-   * Null (not '') so systemWithTaskHeader recaptures rather than treating it as
-   * "no task found."
+   * Null represents no explicitly pinned goal.
    */
   clearPinnedTask() {
     this._taskHeader = null;
@@ -11230,23 +11459,28 @@ INVESTIGATION STRATEGY \u2014 before making tool calls to explore or debug, foll
    * for the whole run. A driver that starts or switches a goal calls this so
    * request.system and the goal's per-turn re-injection name the same objective.
    *
-   * A blank value falls back to recapturing, matching clearPinnedTask.
+   * A blank value clears the pin, matching clearPinnedTask.
    */
   setPinnedTask(task) {
     const trimmed = task.trim();
     this._taskHeader = trimmed.length > 0 ? trimmed : null;
   }
   /** Append the pinned task header (R7) to the static system prompt. */
-  systemWithTaskHeader(messages) {
-    if (!this.config.pinTaskHeader) {
-      return this.config.systemPrompt;
-    }
-    if (this._taskHeader === null) {
-      const firstUser = messages.find(
-        (m) => m.role === "user" && !m.metadata?.synthetic && !m.metadata?.toolResult && typeof m.content === "string" && m.content.trim().length > 0
-      );
-      this._taskHeader = firstUser ? firstUser.content.trim().slice(0, 2e3) : "";
-    }
+  getExecutionContext() {
+    return {
+      mode: this.config.runtimeFacts.mode ?? "normal",
+      cwd: this._cwd,
+      tools: this.getConfiguredToolNames(),
+      mux: this.config.runtimeFacts.mux ?? false,
+      configScope: this.config.runtimeFacts.configScope ?? "host configuration",
+      maxTokens: this.config.maxTokens,
+      outputLimitSource: this.config.runtimeFacts.outputLimitSource ?? (this.config.maxTokens === void 0 ? "provider default" : "explicit configuration"),
+      settings: resolveExecutionSettings(this.config.execution),
+      jobs: listCommandJobs(this.config.sessionId)
+    };
+  }
+  systemWithTaskHeader(_messages) {
+    if (!this.config.pinTaskHeader) return this.config.systemPrompt;
     return pinnedTaskSystem(this.config.systemPrompt, this._taskHeader);
   }
   /**
@@ -11255,6 +11489,17 @@ INVESTIGATION STRATEGY \u2014 before making tool calls to explore or debug, foll
    * the same core loop used by unhosted ZTC.
    */
   async run(messages, signal, takeSteering) {
+    const onInterrupt = () => {
+      if (this.config.execution.interruptBackgroundJobs) void interruptCommandJobs(this.config.sessionId);
+    };
+    signal?.addEventListener("abort", onInterrupt, { once: true });
+    try {
+      return await this.runBound(messages, signal, takeSteering);
+    } finally {
+      signal?.removeEventListener("abort", onInterrupt);
+    }
+  }
+  async runBound(messages, signal, takeSteering) {
     const binding = this.#conversationBinding;
     if (!binding) return this.runCore(messages, signal, takeSteering);
     const userMessage = [...messages].reverse().find(
@@ -11293,7 +11538,7 @@ INVESTIGATION STRATEGY \u2014 before making tool calls to explore or debug, foll
       }
       const result = await this.runCore(workingMessages, signal);
       const assistantMessage = {
-        id: `host_assistant_${randomUUID5()}`,
+        id: `host_assistant_${randomUUID6()}`,
         role: "assistant",
         content: result.content,
         timestamp: /* @__PURE__ */ new Date(),
@@ -11334,7 +11579,6 @@ INVESTIGATION STRATEGY \u2014 before making tool calls to explore or debug, foll
     }
     const allToolCalls = [];
     const turnMessages = [];
-    let acceptedSteering = false;
     let iterations = 0;
     this._consecutiveAutoContinues = 0;
     let finalContent = "";
@@ -11344,6 +11588,7 @@ INVESTIGATION STRATEGY \u2014 before making tool calls to explore or debug, foll
     let runError = null;
     let stopReason = "max_iterations";
     const applyRepeatGuard = createRepeatGuard();
+    const recovery = createRecoveryGuard(this.config.execution);
     try {
       while (iterations < this.config.maxIterations) {
         if (signal?.aborted) {
@@ -11445,7 +11690,7 @@ INVESTIGATION STRATEGY \u2014 before making tool calls to explore or debug, foll
               data: { tool: toolBlock.name }
             });
             const guarded = applyRepeatGuard(toolBlock.name, toolBlock.input, content);
-            return { toolCall, toolResult: { tool_use_id: toolBlock.id, content: guarded } };
+            return { toolCall, toolResult: { tool_use_id: toolBlock.id, content: guarded, is_error: false } };
           };
           const recordToolError = (toolBlock, toolCall, error, effectiveArgs) => {
             toolCall.completedAt = /* @__PURE__ */ new Date();
@@ -11462,7 +11707,8 @@ INVESTIGATION STRATEGY \u2014 before making tool calls to explore or debug, foll
               toolCall,
               toolResult: {
                 tool_use_id: toolBlock.id,
-                content: applyRepeatGuard(toolBlock.name, toolBlock.input, `Error: ${error}`)
+                content: applyRepeatGuard(toolBlock.name, toolBlock.input, `Error: ${error}`),
+                is_error: true
               }
             };
           };
@@ -11475,7 +11721,7 @@ INVESTIGATION STRATEGY \u2014 before making tool calls to explore or debug, foll
           const exclusiveTransitionId = toolUseBlocks.find(
             (toolBlock) => toolBlock.name === "plan_mode"
           )?.id ?? null;
-          const toolPromises = toolUseBlocks.map(async (toolBlock) => {
+          const combined = await scheduleToolBatch(toolUseBlocks, this.config.tools, this.config.execution, async (toolBlock, skipReason) => {
             const toolCall = {
               id: toolBlock.id,
               name: toolBlock.name,
@@ -11489,6 +11735,7 @@ INVESTIGATION STRATEGY \u2014 before making tool calls to explore or debug, foll
               data: { tool: toolBlock.name }
             });
             this.emit({ type: "tool_start", tool: toolBlock.name, args: toolBlock.input, toolCallId: toolBlock.id });
+            if (skipReason) return recordToolError(toolBlock, toolCall, skipReason);
             if (exclusiveTransitionId !== null && toolBlock.id !== exclusiveTransitionId) {
               return recordToolError(
                 toolBlock,
@@ -11530,6 +11777,7 @@ INVESTIGATION STRATEGY \u2014 before making tool calls to explore or debug, foll
                       context: {
                         cwd: this._cwd,
                         toolCallId: toolBlock.id,
+                        sessionId: this.config.sessionId,
                         signal,
                         toolResponseStore: this.toolResponseStore,
                         discoveredTools: this.discoveredTools,
@@ -11556,6 +11804,7 @@ INVESTIGATION STRATEGY \u2014 before making tool calls to explore or debug, foll
                     context: {
                       cwd: this._cwd,
                       toolCallId: toolBlock.id,
+                      sessionId: this.config.sessionId,
                       signal,
                       toolResponseStore: this.toolResponseStore,
                       discoveredTools: this.discoveredTools,
@@ -11579,8 +11828,7 @@ INVESTIGATION STRATEGY \u2014 before making tool calls to explore or debug, foll
               const error = err.message;
               return recordToolError(toolBlock, toolCall, error);
             }
-          });
-          const combined = await Promise.all(toolPromises);
+          }, (result) => result.toolCall.status === "error" || commandStillRunning(result.toolResult.content), signal, exclusiveTransitionId);
           allToolCalls.push(...combined.map((r) => r.toolCall));
           const partial = Boolean(signal?.aborted);
           const toolResults = combined.map((r) => {
@@ -11591,20 +11839,14 @@ INVESTIGATION STRATEGY \u2014 before making tool calls to explore or debug, foll
               partial,
               {
                 sourcePath: extractSourcePath(r.toolCall.name, r.toolCall.args),
-                dedupable: r.toolCall.status === "complete"
+                dedupable: r.toolCall.status === "complete",
+                isError: r.toolResult.is_error
               }
             );
-            return { tool_use_id: r.toolResult.tool_use_id, content: rendered };
+            return { tool_use_id: r.toolResult.tool_use_id, content: rendered, is_error: r.toolResult.is_error };
           });
-          if (signal?.aborted) {
-            throw new AgentError("Cancelled", "CANCELLED");
-          }
           this._consecutiveAutoContinues = 0;
           const textContent = response.content.filter(this.isTextBlock).map((b) => b.text).join("\n");
-          if (textContent && textContent.trim()) {
-            if (!this._lastResponseStreamed) await this.emitStreamText(textContent, signal);
-            lastToolTurnText = textContent;
-          }
           const toolUseMessage = {
             id: `assistant_${Date.now()}`,
             role: "assistant",
@@ -11624,6 +11866,30 @@ INVESTIGATION STRATEGY \u2014 before making tool calls to explore or debug, foll
           };
           messages.push(toolResultMessage);
           turnMessages.push(toolResultMessage);
+          this.emit({ type: "history_checkpoint", messages: [...turnMessages] });
+          if (signal?.aborted) throw new AgentError("Cancelled", "CANCELLED");
+          if (textContent && textContent.trim() && !signal?.aborted) {
+            if (!this._lastResponseStreamed) await this.emitStreamText(textContent, signal);
+            lastToolTurnText = textContent;
+          }
+          const recoveryAction = recovery(combined.map((result) => ({
+            name: result.toolCall.name,
+            content: result.toolResult.content,
+            isError: result.toolResult.is_error
+          })));
+          if (recoveryAction === "stop") throw new AgentError("Automatic recovery budget exhausted after repeated tool failures. Inspect the retained results and current capabilities before retrying.", "RECOVERY_EXHAUSTED");
+          if (recoveryAction === "recover") {
+            const recoveryMessage = {
+              id: `recovery_${randomUUID6()}`,
+              role: "user",
+              content: "[Recovery] Repeated failures share the same cause. Stop that sequence. Inspect current capabilities and active jobs, then make one changed recovery attempt. Use file/stdin tools for scripts and raw Ctrl+C for stuck shell input, then read the pane in the same response or immediately afterward. A silent running-job poll allows one further inspection before stopping; do not repeat empty polls. Continue authorized work; use ask_user only for a concrete missing prerequisite. Do not repeat an acknowledgement as proof of success.",
+              metadata: { synthetic: true },
+              timestamp: /* @__PURE__ */ new Date()
+            };
+            messages.push(recoveryMessage);
+            turnMessages.push(recoveryMessage);
+            this.emit({ type: "history_checkpoint", messages: [...turnMessages] });
+          }
           if (combined.length === 1 && combined[0].toolCall.status === "complete") {
             const call = combined[0].toolCall;
             const tool = this.config.tools.find((tool2) => tool2.definition.name === call.name);
@@ -11651,7 +11917,6 @@ INVESTIGATION STRATEGY \u2014 before making tool calls to explore or debug, foll
             if (steering.length > 0) {
               messages.push(...steering);
               turnMessages.push(...steering);
-              acceptedSteering = true;
             }
           }
         } catch (err) {
@@ -11694,7 +11959,7 @@ INVESTIGATION STRATEGY \u2014 before making tool calls to explore or debug, foll
       usage: totalUsage || void 0,
       stopReason,
       ...finalReasoning ? { reasoning: finalReasoning } : {},
-      ...acceptedSteering ? { turnMessages } : {}
+      turnMessages
     };
   }
   /**
@@ -11732,6 +11997,7 @@ INVESTIGATION STRATEGY \u2014 before making tool calls to explore or debug, foll
         context: {
           cwd: this._cwd,
           toolCallId,
+          sessionId: this.config.sessionId,
           signal: options.signal,
           toolResponseStore: this.toolResponseStore,
           discoveredTools: this.discoveredTools,
@@ -11776,7 +12042,7 @@ INVESTIGATION STRATEGY \u2014 before making tool calls to explore or debug, foll
     const { maxAttempts, baseDelayMs: baseDelay } = this.config.apiRetry;
     const timeoutMs = this.config.llmRequestTimeoutMs;
     if (this.backend.handlesTransportRetries?.(request) === true) {
-      request = { ...request, transportTurnId: request.transportTurnId ?? randomUUID5() };
+      request = { ...request, transportTurnId: request.transportTurnId ?? randomUUID6() };
     }
     const useStream = process.env.ZTC_NO_STREAM !== "1" && !this.backend.streamsSyntheticallyFor?.(request);
     let answerOutputEmitted = false;
@@ -12007,20 +12273,20 @@ init_capabilities();
 // src/skills/loader.ts
 init_logger();
 init_extension_discovery();
-import { homedir as homedir7 } from "os";
-import { join as join14, resolve as resolve8, basename as basename4 } from "path";
+import { homedir as homedir8 } from "os";
+import { join as join15, resolve as resolve8, basename as basename4 } from "path";
 import { readdir as readdir2, readFile as readFile4 } from "fs/promises";
 var MAX_DEPTH = 4;
 function defaultMarkdownRoots() {
   const explicitRoots = extensionPathsFromEnvironment("ZTC_SKILL_PATHS");
   if (isExplicitExtensionDiscovery()) return explicitRoots;
-  const home = homedir7();
+  const home = homedir8();
   return [
     ...explicitRoots,
-    join14(process.cwd(), ".ztc", "skills"),
-    join14(process.cwd(), ".claude", "skills"),
-    join14(home, ".ztc", "skills"),
-    join14(home, ".claude", "skills")
+    join15(process.cwd(), ".ztc", "skills"),
+    join15(process.cwd(), ".claude", "skills"),
+    join15(home, ".ztc", "skills"),
+    join15(home, ".claude", "skills")
   ];
 }
 async function walk(dir, depth = 0) {
@@ -12030,7 +12296,7 @@ async function walk(dir, depth = 0) {
     const results = [];
     for (const entry of entries) {
       if (entry.name.startsWith(".")) continue;
-      const full = join14(dir, entry.name);
+      const full = join15(dir, entry.name);
       if (entry.isDirectory()) {
         results.push(...await walk(full, depth + 1));
       } else if (entry.isFile() && entry.name.toLowerCase() === "skill.md") {
@@ -12177,7 +12443,7 @@ import { fileURLToPath as fileURLToPath2 } from "url";
 
 // src/skills/bundled/init-context.ts
 import { readdir as readdir3, readFile as readFile5, stat } from "fs/promises";
-import { join as join15 } from "path";
+import { join as join16 } from "path";
 var MAX_ENTRIES = 60;
 var TOP_LEVEL_DIRS_OF_INTEREST = [
   "src",
@@ -12238,7 +12504,7 @@ async function safeReadDir(path) {
 async function detectManifests(cwd) {
   const found = [];
   for (const { file, label } of MANIFESTS) {
-    if (await fileExists(join15(cwd, file))) {
+    if (await fileExists(join16(cwd, file))) {
       found.push(`- ${file} \u2014 ${label}`);
     }
   }
@@ -12246,7 +12512,7 @@ async function detectManifests(cwd) {
 }
 async function readClaudeMd(cwd) {
   for (const name of CLAUDE_MD_CANDIDATES) {
-    const path = join15(cwd, name);
+    const path = join16(cwd, name);
     if (await fileExists(path)) {
       try {
         const contents = await readFile5(path, "utf-8");
@@ -12505,7 +12771,7 @@ var invokeSkillTool = makeInvokeSkillTool(resolveAmbientSkills);
 // src/zlm.ts
 var ZLM_EMBED_API_VERSION = "zerglang.ztc-embed/1";
 var ZLM_STDIO_PROTOCOL = "zerglang.ztc-host/1";
-var ZLM_ZTC_VERSION = true ? "0.3.0-beta.1" : "development";
+var ZLM_ZTC_VERSION = true ? "0.4.0-beta.1" : "development";
 var ZLM_MAX_HOST_TOOLS = 64;
 var ZLM_MAX_SYSTEM_PROMPT_BYTES = 128 * 1024;
 var ZLM_HOST_APPROVAL_CAPABILITIES = Object.freeze([