@kiturone/kapibala 0.0.1 → 0.0.2

package/dist/index.js

@@ -14,9 +14,15 @@ function isThinkingBlock(block) {
 
 // src/errors/index.ts
 var KapibalaError = class extends Error {
-  constructor(message) {
+  code;
+  retryPolicy;
+  safeMessage;
+  constructor(message, options) {
     super(message);
     this.name = "KapibalaError";
+    this.code = options?.code ?? "INTERNAL_ERROR";
+    this.retryPolicy = options?.retryPolicy ?? "never";
+    this.safeMessage = options?.safeMessage ?? "Operation failed";
   }
 };
 var ModelError = class extends KapibalaError {
@@ -39,7 +45,11 @@ var TransportError = class extends KapibalaError {
 };
 var ToolError = class extends KapibalaError {
   constructor(message) {
-    super(message);
+    super(message, {
+      code: "TOOL_ERROR",
+      retryPolicy: "never",
+      safeMessage: "Tool execution failed"
+    });
     this.name = "ToolError";
   }
 };
@@ -47,7 +57,11 @@ var ToolNotFound = class extends KapibalaError {
   toolName;
   availableTools;
   constructor(toolName, availableTools = []) {
-    super(`Tool '${toolName}' not found. Available tools: ${availableTools.join(", ") || "none"}`);
+    super(`Tool '${toolName}' not found. Available tools: ${availableTools.join(", ") || "none"}`, {
+      code: "TOOL_NOT_FOUND",
+      retryPolicy: "never",
+      safeMessage: "Requested tool is unavailable"
+    });
     this.name = "ToolNotFound";
     this.toolName = toolName;
     this.availableTools = availableTools;
@@ -55,7 +69,11 @@ var ToolNotFound = class extends KapibalaError {
 };
 var AbortError = class extends KapibalaError {
   constructor(message = "Execution aborted by user") {
-    super(message);
+    super(message, {
+      code: "ABORTED",
+      retryPolicy: "after_user_action",
+      safeMessage: "Operation cancelled"
+    });
     this.name = "AbortError";
   }
 };
@@ -72,12 +90,1028 @@ var SessionBusyError = class extends KapibalaError {
   }
 };
 
-// src/security/sandbox.ts
+// src/logging/index.ts
+import { createHash, randomUUID } from "crypto";
+var SAFE_FIELDS = /* @__PURE__ */ new Set([
+  "mode",
+  "toolName",
+  "durationMs",
+  "decision",
+  "decisionSource",
+  "ruleSource",
+  "approvalChoice",
+  "status",
+  "phase",
+  "errorCode",
+  "retryPolicy",
+  "reason",
+  "shell",
+  "executableDigest",
+  "cwdDigest",
+  "commandDigest",
+  "commandPreview",
+  "commandLength",
+  "argumentCount",
+  "executionFingerprint",
+  "exitCode",
+  "outputBytes",
+  "outputTruncated",
+  "outputFileTruncated",
+  "reclaimed",
+  "modelId",
+  "provider",
+  "promptTokens",
+  "completionTokens",
+  "totalTokens",
+  "attempt",
+  "count",
+  "pathDigest",
+  "source",
+  "sessionMode",
+  "processId"
+]);
+var SENSITIVE_VALUE = /(?:\bBearer\s+\S+|\b(?:sk|api|key)-[A-Za-z0-9_-]{5,}|(?:api[_-]?key|token|password|secret)\s*[:=]\s*\S+)/i;
+function projectSafeFields(fields) {
+  const safe = {};
+  for (const [name, value] of Object.entries(fields)) {
+    if (!SAFE_FIELDS.has(name)) continue;
+    if (value === null || typeof value === "number" || typeof value === "boolean") {
+      safe[name] = value;
+    } else if (typeof value === "string") {
+      const validPreview = name !== "commandPreview" || /^(?:[a-z][a-z0-9-]* \(\d+ args\)|\[redacted\])$/.test(value);
+      const validReason = name !== "reason" || /^[a-z][a-z0-9_.-]{0,80}$/i.test(value);
+      safe[name] = SENSITIVE_VALUE.test(value) || !validPreview || !validReason || value.includes("\n") || value.includes("\r") ? "[redacted]" : value.slice(0, 512);
+    }
+  }
+  return safe;
+}
+function createLogId() {
+  return randomUUID();
+}
+function commandAuditSummary(command) {
+  const parts = command.trim().split(/\s+/).filter(Boolean);
+  const first = parts[0]?.toLowerCase();
+  const category = first && (/* @__PURE__ */ new Set([
+    "git",
+    "pnpm",
+    "npm",
+    "node",
+    "rg",
+    "ls",
+    "pwd",
+    "cat",
+    "get-childitem",
+    "get-content"
+  ])).has(first) ? first : void 0;
+  return {
+    commandDigest: createHash("sha256").update(command, "utf8").digest("hex"),
+    commandPreview: category ? `${category} (${Math.max(0, parts.length - 1)} args)` : "[redacted]",
+    commandLength: Buffer.byteLength(command, "utf8"),
+    argumentCount: Math.max(0, parts.length - 1)
+  };
+}
+function executionFingerprint(input) {
+  return createHash("sha256").update(
+    JSON.stringify([
+      input.command,
+      input.shell,
+      input.executable,
+      input.cwd,
+      input.environmentDigest,
+      input.timeoutMs,
+      input.outputLimitBytes,
+      input.targetDigest ?? null
+    ])
+  ).digest("hex");
+}
+var StructuredLogger = class {
+  operationSink;
+  auditSink;
+  debug;
+  onDiagnostic;
+  constructor(options) {
+    this.operationSink = options.operationSink;
+    this.auditSink = options.auditSink;
+    this.debug = options.debug ?? false;
+    this.onDiagnostic = options.onDiagnostic;
+  }
+  /** 普通日志写入失败不阻断业务，也不声称持久化成功；诊断不携带原始异常内容。 */
+  async record(event) {
+    if (!this.debug && (event.level === "debug" || event.level === "trace")) return;
+    try {
+      await this.operationSink.write(this.format(event, "operation"));
+    } catch {
+      try {
+        this.onDiagnostic?.("Operation log write failed; the event was not persisted");
+      } catch {
+      }
+    }
+  }
+  /** 审计必须成功持久化；异常交由执行器拒绝启动工具或报告已执行操作的结果未知。 */
+  async recordAudit(event) {
+    await this.auditSink.write(this.format(event, "audit"));
+  }
+  format(input, channel) {
+    return {
+      schemaVersion: 1,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      level: input.level,
+      channel,
+      event: input.event,
+      sessionId: input.sessionId,
+      ...input.runId === void 0 ? {} : { runId: input.runId },
+      ...input.operationId === void 0 ? {} : { operationId: input.operationId },
+      ...input.toolUseId === void 0 ? {} : { toolUseId: input.toolUseId },
+      fields: projectSafeFields(input.fields ?? {})
+    };
+  }
+};
+
+// src/logging/file-sink.ts
 import fs from "fs";
+import os from "os";
 import path from "path";
+import readline from "readline";
+var FileLogSink = class {
+  directory;
+  prefix;
+  maxBytes;
+  retentionDays;
+  sync;
+  constructor(options) {
+    this.directory = path.resolve(options.directory);
+    this.prefix = options.prefix;
+    this.maxBytes = options.maxBytes ?? 10 * 1024 * 1024;
+    this.retentionDays = options.prefix === "audit" ? void 0 : options.retentionDays;
+    this.sync = options.prefix === "audit" || (options.sync ?? false);
+  }
+  async write(event) {
+    const line = `${JSON.stringify(event)}
+`;
+    const bytes = Buffer.byteLength(line, "utf8");
+    const date = event.timestamp.slice(0, 10);
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) throw new Error("Invalid log timestamp");
+    fs.mkdirSync(this.directory, { recursive: true, mode: 448 });
+    const filePath = this.chooseFile(date, bytes);
+    const descriptor = fs.openSync(filePath, "a", 384);
+    try {
+      fs.writeSync(descriptor, line, void 0, "utf8");
+      if (this.sync) fs.fsyncSync(descriptor);
+    } finally {
+      fs.closeSync(descriptor);
+    }
+    if (this.retentionDays !== void 0) this.cleanupExpired(date);
+  }
+  /** 返回该通道已占用的字节数，供宿主提示长期保留的审计用量。 */
+  getUsageBytes() {
+    if (!fs.existsSync(this.directory)) return 0;
+    return fs.readdirSync(this.directory).filter((name) => this.isOwnedFile(name)).reduce((total, name) => total + fs.statSync(path.join(this.directory, name)).size, 0);
+  }
+  chooseFile(date, bytes) {
+    const names = fs.readdirSync(this.directory).filter((name) => name.startsWith(`${this.prefix}-${date}-`) && this.isOwnedFile(name)).sort();
+    const lastName = names.at(-1);
+    if (lastName) {
+      const lastPath = path.join(this.directory, lastName);
+      if (fs.statSync(lastPath).size + bytes <= this.maxBytes) return lastPath;
+    }
+    const next = lastName ? Number(lastName.slice(-9, -6)) + 1 : 1;
+    return path.join(
+      this.directory,
+      `${this.prefix}-${date}-${String(next).padStart(3, "0")}.jsonl`
+    );
+  }
+  cleanupExpired(currentDate) {
+    const current = Date.parse(`${currentDate}T00:00:00.000Z`);
+    const cutoff = current - (this.retentionDays ?? 0) * 864e5;
+    for (const name of fs.readdirSync(this.directory)) {
+      if (!this.isOwnedFile(name)) continue;
+      const fileDate = name.slice(this.prefix.length + 1, this.prefix.length + 11);
+      if (Date.parse(`${fileDate}T00:00:00.000Z`) < cutoff) {
+        fs.unlinkSync(path.join(this.directory, name));
+      }
+    }
+  }
+  isOwnedFile(name) {
+    return new RegExp(`^${this.prefix}-\\d{4}-\\d{2}-\\d{2}-\\d{3}\\.jsonl$`).test(name);
+  }
+};
+function createDefaultLogSinks(baseDirectory = path.join(os.homedir(), ".kapibala")) {
+  return {
+    operationSink: new FileLogSink({
+      directory: path.join(baseDirectory, "logs"),
+      prefix: "operation",
+      retentionDays: 30
+    }),
+    auditSink: new FileLogSink({
+      directory: path.join(baseDirectory, "audit"),
+      prefix: "audit",
+      sync: true
+    })
+  };
+}
+async function recoverIncompleteAudit(directory) {
+  if (!fs.existsSync(directory)) return 0;
+  const files = fs.readdirSync(directory).filter((name) => /^audit-\d{4}-\d{2}-\d{2}-\d{3}\.jsonl$/.test(name)).sort();
+  const open = /* @__PURE__ */ new Map();
+  for (const name of files) {
+    const lines = readline.createInterface({
+      input: fs.createReadStream(path.join(directory, name), { encoding: "utf8" }),
+      crlfDelay: Number.POSITIVE_INFINITY
+    });
+    for await (const line of lines) {
+      if (!line) continue;
+      let event;
+      try {
+        event = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (!event.operationId || typeof event.operationId !== "string") continue;
+      if (event.event === "tool.requested") open.set(event.operationId, event);
+      if (event.event === "tool.finished" || event.event === "audit.outcome_unknown") {
+        open.delete(event.operationId);
+      }
+    }
+  }
+  const sink = new FileLogSink({ directory, prefix: "audit" });
+  let recovered = 0;
+  for (const event of open.values()) {
+    const processId = event.fields?.processId;
+    if (typeof processId === "number" && Number.isSafeInteger(processId) && processId > 0) {
+      try {
+        process.kill(processId, 0);
+        continue;
+      } catch (error) {
+        if (error.code === "EPERM") continue;
+      }
+    }
+    await sink.write({
+      schemaVersion: 1,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      channel: "audit",
+      level: "warn",
+      event: "audit.outcome_unknown",
+      sessionId: event.sessionId,
+      runId: event.runId,
+      operationId: event.operationId,
+      toolUseId: event.toolUseId,
+      fields: { status: "unknown_after_restart" }
+    });
+    recovered++;
+  }
+  return recovered;
+}
+
+// src/instructions/index.ts
+import fs2 from "fs";
+import os2 from "os";
+import path2 from "path";
+var MAX_FILE_BYTES = 32 * 1024;
+var MAX_TOTAL_BYTES = 128 * 1024;
+var MAX_LEVELS = 16;
+function loadInstructions(options) {
+  const root = fs2.realpathSync(options.projectRoot);
+  const cwd = fs2.realpathSync(options.cwd);
+  const relative = path2.relative(root, cwd);
+  if (relative === ".." || relative.startsWith(`..${path2.sep}`) || path2.isAbsolute(relative)) {
+    throw new Error("Instruction cwd is outside project root");
+  }
+  const segments = relative ? relative.split(path2.sep) : [];
+  if (segments.length + 1 > MAX_LEVELS)
+    throw new Error(`Instruction directory chain exceeds ${MAX_LEVELS} levels`);
+  const userFile = options.userFile ?? path2.join(os2.homedir(), ".kapibala", "AGENTS.md");
+  const candidates = [userFile];
+  let directory = root;
+  candidates.push(path2.join(directory, "AGENTS.md"));
+  for (const segment of segments) {
+    directory = path2.join(directory, segment);
+    candidates.push(path2.join(directory, "AGENTS.md"));
+  }
+  const seenPaths = /* @__PURE__ */ new Set();
+  const uniqueCandidates = [];
+  for (const file of candidates) {
+    const resolved = path2.resolve(file);
+    const key = process.platform === "win32" ? resolved.toLowerCase() : resolved;
+    if (!seenPaths.has(key)) {
+      seenPaths.add(key);
+      uniqueCandidates.push(file);
+    }
+  }
+  const sources = [];
+  let totalBytes = 0;
+  for (const file of uniqueCandidates) {
+    let stat;
+    try {
+      stat = fs2.lstatSync(file);
+    } catch (error) {
+      if (error.code === "ENOENT") continue;
+      throw new Error(`Cannot inspect instructions at ${file}`, { cause: error });
+    }
+    if (stat.isSymbolicLink())
+      throw new Error(`Instruction symbolic link is not accepted: ${file}`);
+    if (!stat.isFile()) throw new Error(`Instruction source is not a regular file: ${file}`);
+    if (stat.size > MAX_FILE_BYTES) throw new Error(`Instruction ${file} exceeds 32 KiB`);
+    totalBytes += stat.size;
+    if (totalBytes > MAX_TOTAL_BYTES) throw new Error("Instructions exceed 128 KiB total");
+    let bytes;
+    try {
+      bytes = fs2.readFileSync(file);
+    } catch (error) {
+      throw new Error(`Cannot read instructions at ${file}`, { cause: error });
+    }
+    if (bytes.byteLength > MAX_FILE_BYTES) throw new Error(`Instruction ${file} exceeds 32 KiB`);
+    totalBytes += bytes.byteLength - stat.size;
+    if (totalBytes > MAX_TOTAL_BYTES) throw new Error("Instructions exceed 128 KiB total");
+    let content;
+    try {
+      content = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    } catch (error) {
+      throw new Error(`Instruction ${file} is not valid UTF-8`, { cause: error });
+    }
+    sources.push({ path: file, content });
+  }
+  return { sources, totalBytes };
+}
+
+// src/shell/detect.ts
+import { spawnSync } from "child_process";
+import { createHash as createHash2 } from "crypto";
+import fs3 from "fs";
+import os3 from "os";
+import path3 from "path";
+function classifyBashOutput(unameOutput, platform) {
+  const uname = unameOutput.trim().split(/\r?\n/)[0]?.toLowerCase() ?? "";
+  if (platform === "win32") {
+    if (uname.startsWith("mingw") || uname.startsWith("msys") || uname.startsWith("cygwin")) {
+      return "bash";
+    }
+    return uname === "linux" ? "wsl" : void 0;
+  }
+  return uname ? "bash" : void 0;
+}
+function findExecutables(name, pathEnv, platform) {
+  const extension = platform === "win32" && !name.toLowerCase().endsWith(".exe") ? ".exe" : "";
+  const found = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const directory of pathEnv.split(path3.delimiter)) {
+    if (!directory) continue;
+    const candidate = path3.join(directory, name + extension);
+    try {
+      if (!fs3.statSync(candidate).isFile()) continue;
+      const real = fs3.realpathSync(candidate);
+      const key = platform === "win32" ? real.toLowerCase() : real;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      found.push(real);
+    } catch {
+    }
+  }
+  return found;
+}
+function probeBash(executable, cwd, platform) {
+  const result = spawnSync(executable, ["--noprofile", "--norc", "-c", "uname -s; pwd"], {
+    cwd,
+    encoding: "utf8",
+    timeout: 15e3,
+    windowsHide: true
+  });
+  if (result.status !== 0 || !result.stdout?.trim()) return { ok: false };
+  return { ok: true, kind: classifyBashOutput(result.stdout, platform) };
+}
+function probePowerShell(executable, cwd) {
+  const result = spawnSync(executable, ["-NoProfile", "-NonInteractive", "-Command", "$PWD.Path"], {
+    cwd,
+    encoding: "utf8",
+    timeout: 15e3,
+    windowsHide: true
+  });
+  return result.status === 0 && Boolean(result.stdout?.trim());
+}
+function buildEnvironment(executable, kind, cwd) {
+  const stat = fs3.statSync(executable);
+  return {
+    kind,
+    executable,
+    cwd,
+    executableDigest: createHash2("sha256").update(JSON.stringify([executable, stat.size, stat.mtimeMs])).digest("hex")
+  };
+}
+function candidatesFor(kind, platform, pathEnv) {
+  if (kind === "bash" || kind === "wsl") {
+    return findExecutables("bash", pathEnv, platform);
+  }
+  if (platform !== "win32" && kind === "powershell") return [];
+  return findExecutables(kind, pathEnv, platform);
+}
+function tryKind(kind, platform, pathEnv, cwd) {
+  for (const executable of candidatesFor(kind, platform, pathEnv)) {
+    try {
+      if (kind === "bash" || kind === "wsl") {
+        const probe = probeBash(executable, cwd, platform);
+        if (probe.ok && probe.kind === kind) return buildEnvironment(executable, kind, cwd);
+      } else if (probePowerShell(executable, cwd)) {
+        return buildEnvironment(executable, kind, cwd);
+      }
+    } catch {
+    }
+  }
+  return void 0;
+}
+function detectExplicitPath(preference, cwd, platform) {
+  const executable = fs3.realpathSync(preference);
+  if (!fs3.statSync(executable).isFile()) {
+    throw new Error(`Requested interpreter path is not a file: ${preference}`);
+  }
+  const base = path3.basename(executable).toLowerCase();
+  if (/^pwsh(\.exe)?$/.test(base) || /^powershell(_ise)?(\.exe)?$/.test(base)) {
+    const kind = base.startsWith("pwsh") ? "pwsh" : "powershell";
+    if (platform !== "win32" && kind === "powershell") {
+      throw new Error(`Requested ${kind} interpreter is unavailable on this platform`);
+    }
+    if (!probePowerShell(executable, cwd)) {
+      throw new Error(
+        `Requested ${kind} interpreter is unavailable or incompatible with this working directory`
+      );
+    }
+    return buildEnvironment(executable, kind, cwd);
+  }
+  const probe = probeBash(executable, cwd, platform);
+  if (!probe.ok || !probe.kind) {
+    throw new Error(
+      `Requested interpreter is unavailable or incompatible with this working directory: ${preference}`
+    );
+  }
+  return buildEnvironment(executable, probe.kind, cwd);
+}
+function detectShell(options) {
+  const platform = options.platform ?? os3.platform();
+  const cwd = fs3.realpathSync(options.cwd);
+  const pathEnv = options.pathEnv ?? process.env.PATH ?? "";
+  const preference = options.preference ?? "auto";
+  if (/[\\/]/.test(preference) || preference.toLowerCase().endsWith(".exe")) {
+    return detectExplicitPath(preference, cwd, platform);
+  }
+  const kinds = preference === "auto" ? platform === "win32" ? ["bash", "wsl", "pwsh", "powershell"] : ["bash"] : [preference];
+  for (const kind of kinds) {
+    const environment = tryKind(kind, platform, pathEnv, cwd);
+    if (environment) return environment;
+  }
+  throw new Error(
+    preference === "auto" ? "No usable Bash or PowerShell interpreter found" : `Requested ${preference} interpreter is unavailable or incompatible with this working directory`
+  );
+}
+
+// src/shell/tool.ts
+import { spawn, spawnSync as spawnSync2 } from "child_process";
+import { createHash as createHash3, randomUUID as randomUUID2 } from "crypto";
+import fs4 from "fs";
+import path4 from "path";
+import { StringDecoder } from "string_decoder";
+
+// src/tools/index.ts
+function defineTool(tool) {
+  return tool;
+}
+function toToolDefinition(tool) {
+  return {
+    name: tool.name,
+    description: tool.description,
+    parameters: tool.parameters
+  };
+}
+
+// src/shell/tool.ts
+var INLINE_LIMIT = 64 * 1024;
+var FILE_LIMIT = 16 * 1024 * 1024;
+var DEFAULT_TIMEOUT = 12e4;
+var MAX_TIMEOUT = 6e5;
+var MAX_COMMAND_BYTES = 8 * 1024;
+var OWNED_RESULT = /^run-[a-f0-9-]{36}\.txt$/;
+var RESULT_MANIFEST = "managed-results.jsonl";
+function limitedEnvironment(kind) {
+  const allowed = [
+    "PATH",
+    "Path",
+    "SystemRoot",
+    "ComSpec",
+    "TEMP",
+    "TMP",
+    "HOME",
+    "USERPROFILE",
+    "APPDATA",
+    "LOCALAPPDATA",
+    "LANG",
+    "LC_ALL",
+    "TERM"
+  ];
+  const environment = Object.fromEntries(
+    allowed.filter((key) => process.env[key] !== void 0).map((key) => [key, process.env[key]])
+  );
+  if (kind === "wsl") environment.WSL_UTF8 = "1";
+  return environment;
+}
+function utf8Prefix(bytes, limit) {
+  let end = Math.min(bytes.length, limit);
+  let start = end - 1;
+  while (start >= 0 && (bytes[start] & 192) === 128) start--;
+  if (start >= 0) {
+    const lead = bytes[start];
+    const length = lead >= 240 ? 4 : lead >= 224 ? 3 : lead >= 192 ? 2 : 1;
+    if (start + length > end) end = start;
+  }
+  return bytes.subarray(0, end);
+}
+function effectiveCwd(input, rootDir) {
+  const requested = input.cwd ? path4.resolve(rootDir, input.cwd) : rootDir;
+  const real = fs4.realpathSync(requested);
+  if (!fs4.statSync(real).isDirectory())
+    throw new Error("Command working directory is not a directory");
+  return real;
+}
+function effectiveTimeout(input) {
+  const timeout = input.timeout_ms ?? DEFAULT_TIMEOUT;
+  if (!Number.isInteger(timeout) || timeout < 1 || timeout > MAX_TIMEOUT) {
+    throw new Error(`Command timeout must be 1-${MAX_TIMEOUT} ms`);
+  }
+  return timeout;
+}
+function validateCommand(input) {
+  if (typeof input.command !== "string" || input.command.trim().length === 0 || Buffer.byteLength(input.command, "utf8") > MAX_COMMAND_BYTES) {
+    throw new Error(`Command must be nonempty and at most ${MAX_COMMAND_BYTES} bytes`);
+  }
+}
+function directScriptDigest(command, kind, cwd) {
+  const bashLike = kind === "bash" || kind === "wsl";
+  if (bashLike && command.includes("\\")) return void 0;
+  const normalized = command.trim().replaceAll("\\", "/");
+  const match = bashLike ? /^(?:bash )?\.\/([A-Za-z0-9_./-]+\.sh)$/.exec(normalized) : /^\.\/([A-Za-z0-9_./-]+\.ps1)$/i.exec(normalized);
+  if (!match) return void 0;
+  try {
+    const script = fs4.realpathSync(path4.resolve(cwd, match[1]));
+    const relative = path4.relative(cwd, script);
+    if (relative.startsWith("..") || path4.isAbsolute(relative)) return void 0;
+    const stat = fs4.statSync(script);
+    if (!stat.isFile() || stat.size > 1024 * 1024) return void 0;
+    return createHash3("sha256").update(script).update("\0").update(fs4.readFileSync(script)).digest("hex");
+  } catch {
+    return void 0;
+  }
+}
+function interpreterArgs(environment, command) {
+  if (environment.kind === "bash" || environment.kind === "wsl") {
+    return ["--noprofile", "--norc", "-c", command];
+  }
+  const utf8 = "[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false); $OutputEncoding = [Console]::OutputEncoding; ";
+  return ["-NoProfile", "-NonInteractive", "-Command", utf8 + command];
+}
+function getTaskkillPath() {
+  if (process.platform !== "win32") return "taskkill";
+  const systemRoot = process.env.SystemRoot ?? process.env.windir ?? "C:\\Windows";
+  const candidate = path4.join(systemRoot, "System32", "taskkill.exe");
+  try {
+    if (fs4.existsSync(candidate)) return candidate;
+  } catch {
+  }
+  return "taskkill.exe";
+}
+function createNativeBashGroup(environment) {
+  if (process.platform !== "win32" || environment.kind !== "bash") return void 0;
+  let resolveReady = () => {
+  };
+  let pending = "";
+  let accepted = false;
+  const group = {
+    environment,
+    token: randomUUID2(),
+    ready: new Promise((resolve) => {
+      resolveReady = resolve;
+    }),
+    accept(text) {
+      if (accepted) return text;
+      pending += text;
+      const newline = pending.indexOf("\n");
+      if (newline < 0) return "";
+      accepted = true;
+      const prefix = `${group.token}:`;
+      const line = pending.slice(0, newline).trimEnd();
+      const pid = line.startsWith(prefix) ? Number(line.slice(prefix.length)) : Number.NaN;
+      if (Number.isSafeInteger(pid) && pid > 0) group.pid = pid;
+      resolveReady();
+      return group.pid ? pending.slice(newline + 1) : pending;
+    }
+  };
+  return group;
+}
+function signalNativeBashGroup(group, signal) {
+  if (!group.pid) return false;
+  const result = spawnSync2(
+    group.environment.executable,
+    ["--noprofile", "--norc", "-c", `kill -${signal} -- -${group.pid}`],
+    { windowsHide: true, timeout: 3e3, env: limitedEnvironment("bash") }
+  );
+  return result.status === 0;
+}
+function nativeBashGroupStopped(group) {
+  if (!group.pid) return false;
+  const result = spawnSync2(group.environment.executable, ["--noprofile", "--norc", "-c", "ps -l"], {
+    windowsHide: true,
+    timeout: 3e3,
+    encoding: "utf8",
+    env: limitedEnvironment("bash")
+  });
+  if (result.status !== 0 || !result.stdout.includes("PGID")) return false;
+  return !result.stdout.split("\n").some((line) => {
+    const columns = line.trim().split(/\s+/);
+    return /^\d+$/.test(columns[0] ?? "") && Number(columns[2]) === group.pid;
+  });
+}
+function stopProcessTree(child, nativeGroup) {
+  if (!child.pid) return false;
+  if (process.platform === "win32") {
+    const groupStopped = !nativeGroup || signalNativeBashGroup(nativeGroup, "TERM");
+    const result = spawnSync2(getTaskkillPath(), ["/PID", String(child.pid), "/T", "/F"], {
+      windowsHide: true,
+      timeout: 3e3
+    });
+    return groupStopped && (result.status === 0 || Boolean(nativeGroup));
+  }
+  try {
+    process.kill(-child.pid, "SIGTERM");
+    return true;
+  } catch {
+    try {
+      child.kill("SIGTERM");
+    } catch {
+    }
+    return false;
+  }
+}
+function forceProcessTree(child, nativeGroup) {
+  if (!child.pid) return false;
+  if (process.platform === "win32") {
+    const groupStopped = !nativeGroup || signalNativeBashGroup(nativeGroup, "KILL");
+    const result = spawnSync2(getTaskkillPath(), ["/PID", String(child.pid), "/T", "/F"], {
+      windowsHide: true,
+      timeout: 3e3
+    });
+    return groupStopped && (result.status === 0 || Boolean(nativeGroup));
+  }
+  try {
+    process.kill(-child.pid, "SIGKILL");
+    return true;
+  } catch {
+    try {
+      child.kill("SIGKILL");
+    } catch {
+    }
+    return false;
+  }
+}
+async function confirmProcessTreeStopped(child, terminationSucceeded, nativeGroup) {
+  if (!terminationSucceeded || !child.pid) return false;
+  if (nativeGroup) {
+    const deadline2 = Date.now() + 1e3;
+    while (Date.now() < deadline2) {
+      if (nativeBashGroupStopped(nativeGroup)) return true;
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    return false;
+  }
+  if (process.platform === "win32") return true;
+  const deadline = Date.now() + 1e3;
+  while (Date.now() < deadline) {
+    try {
+      process.kill(-child.pid, 0);
+    } catch (error) {
+      if (error.code === "ESRCH") return true;
+      return false;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+  return false;
+}
+function waitForClose(promise, milliseconds) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => resolve(false), milliseconds);
+    void promise.then(
+      () => {
+        clearTimeout(timer);
+        resolve(true);
+      },
+      () => {
+        clearTimeout(timer);
+        resolve(true);
+      }
+    );
+  });
+}
+function resultDirectory(rootDir) {
+  return path4.join(rootDir, ".kapibala", "tool-results");
+}
+function cleanupCommandResults(rootDir, now = Date.now()) {
+  const directory = resultDirectory(rootDir);
+  if (!fs4.existsSync(directory)) return;
+  const manifest = path4.join(directory, RESULT_MANIFEST);
+  if (!fs4.existsSync(manifest) || !fs4.lstatSync(manifest).isFile()) return;
+  const cutoff = now - 7 * 864e5;
+  const retained = [];
+  for (const line of fs4.readFileSync(manifest, "utf8").split("\n")) {
+    if (!line) continue;
+    let record;
+    try {
+      record = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!OWNED_RESULT.test(record.name)) continue;
+    const file = path4.join(directory, record.name);
+    if (!fs4.existsSync(file)) continue;
+    const stat = fs4.lstatSync(file);
+    if (!stat.isFile() || stat.dev !== record.dev || stat.ino !== record.ino) continue;
+    if (stat.mtimeMs < cutoff) fs4.unlinkSync(file);
+    else retained.push(line);
+  }
+  const replacement = path4.join(directory, `.managed-results-${randomUUID2()}.tmp`);
+  fs4.writeFileSync(replacement, retained.length ? `${retained.join("\n")}
+` : "", { mode: 384 });
+  fs4.renameSync(replacement, manifest);
+}
+function recordManagedResult(directory, file, descriptor) {
+  const stat = fs4.fstatSync(descriptor);
+  fs4.appendFileSync(
+    path4.join(directory, RESULT_MANIFEST),
+    `${JSON.stringify({ name: path4.basename(file), dev: stat.dev, ino: stat.ino })}
+`,
+    { mode: 384 }
+  );
+}
+function createRunCommandTool(environment) {
+  return defineTool({
+    name: "run_command",
+    description: `Run a ${environment.kind === "wsl" ? "bash (WSL)" : environment.kind} command as the current OS user. The file tool PathSandbox does not isolate this process or its network access.`,
+    metadata: {
+      source: "builtin",
+      permissions: ["fs:read", "fs:write", "exec", "net:outbound", "env:read"],
+      dangerous: true,
+      managesTimeout: true
+    },
+    parameters: {
+      type: "object",
+      properties: {
+        command: {
+          type: "string",
+          description: `Command using ${environment.kind === "wsl" ? "bash" : environment.kind} syntax.`
+        },
+        cwd: { type: "string", description: "Working directory; defaults to workspace root." },
+        timeout_ms: { type: "integer", description: "Timeout in milliseconds, maximum 600000." }
+      },
+      required: ["command"]
+    },
+    approvalScope(input, rootDir) {
+      validateCommand(input);
+      const cwd = effectiveCwd(input, rootDir);
+      const timeoutMs = effectiveTimeout(input);
+      const scriptDigest = directScriptDigest(input.command, environment.kind, cwd);
+      const stat = fs4.statSync(environment.executable);
+      const executableDigest = createHash3("sha256").update(JSON.stringify([environment.executable, stat.size, stat.mtimeMs])).digest("hex");
+      const environmentDigest = createHash3("sha256").update(JSON.stringify(limitedEnvironment(environment.kind))).digest("hex");
+      return {
+        command: input.command,
+        interpreter: environment.kind,
+        executablePath: environment.executable,
+        cwd,
+        executableDigest,
+        ...scriptDigest ? { scriptDigest } : {},
+        executionFingerprint: executionFingerprint({
+          command: input.command,
+          shell: environment.kind,
+          executable: executableDigest,
+          cwd,
+          environmentDigest,
+          timeoutMs,
+          outputLimitBytes: FILE_LIMIT,
+          targetDigest: scriptDigest
+        })
+      };
+    },
+    async execute(input, ctx) {
+      const startedAt = Date.now();
+      validateCommand(input);
+      if (ctx.signal?.aborted) {
+        throw new KapibalaError("Command aborted before start", {
+          code: "ABORTED",
+          retryPolicy: "after_user_action",
+          safeMessage: "Command was not started because the run was aborted"
+        });
+      }
+      const cwd = effectiveCwd(input, ctx.rootDir);
+      const timeoutMs = effectiveTimeout(input);
+      cleanupCommandResults(ctx.rootDir);
+      const nativeGroup = createNativeBashGroup(environment);
+      const command = nativeGroup ? `printf '${nativeGroup.token}:%s\\n' "$$" >&2
+${input.command}` : input.command;
+      const child = spawn(environment.executable, interpreterArgs(environment, command), {
+        cwd,
+        env: limitedEnvironment(environment.kind),
+        windowsHide: true,
+        detached: process.platform !== "win32",
+        stdio: ["ignore", "pipe", "pipe"]
+      });
+      const inline = [];
+      let inlineBytes = 0;
+      let outputBytes = 0;
+      let fileBytes = 0;
+      let outputFile;
+      let outputFileTruncated = false;
+      let outputFailure = false;
+      let lastProgressAt = startedAt;
+      let descriptor;
+      const collect = (chunk) => {
+        outputBytes += chunk.length;
+        if (outputFailure) return;
+        if (inlineBytes < INLINE_LIMIT) {
+          const part = chunk.subarray(0, INLINE_LIMIT - inlineBytes);
+          inline.push(part);
+          inlineBytes += part.length;
+        }
+        if (outputBytes > INLINE_LIMIT && descriptor === void 0) {
+          const directory = resultDirectory(ctx.rootDir);
+          fs4.mkdirSync(directory, { recursive: true, mode: 448 });
+          outputFile = path4.join(directory, `run-${randomUUID2()}.txt`);
+          descriptor = fs4.openSync(outputFile, "wx", 384);
+          recordManagedResult(directory, outputFile, descriptor);
+          const prefix = Buffer.concat(inline);
+          fs4.writeSync(descriptor, prefix);
+          fileBytes = prefix.length;
+          const remaining = chunk.subarray(
+            Math.max(0, prefix.length - (outputBytes - chunk.length))
+          );
+          const writable = utf8Prefix(remaining, FILE_LIMIT - fileBytes);
+          if (writable.length > 0) fs4.writeSync(descriptor, writable);
+          fileBytes += writable.length;
+          if (writable.length < remaining.length) outputFileTruncated = true;
+        } else if (descriptor !== void 0 && !outputFileTruncated) {
+          const writable = utf8Prefix(chunk, FILE_LIMIT - fileBytes);
+          if (writable.length > 0) fs4.writeSync(descriptor, writable);
+          fileBytes += writable.length;
+          if (writable.length < chunk.length) outputFileTruncated = true;
+        } else if (descriptor !== void 0) {
+          outputFileTruncated = true;
+        }
+      };
+      const onData = (chunk) => {
+        try {
+          collect(chunk);
+        } catch {
+          outputFailure = true;
+          if (descriptor !== void 0) {
+            try {
+              fs4.closeSync(descriptor);
+            } catch {
+            }
+            descriptor = void 0;
+          }
+        }
+        const now = Date.now();
+        if (now - lastProgressAt >= 250) {
+          lastProgressAt = now;
+          ctx.onProgress?.({ elapsedMs: now - startedAt, outputBytes });
+        }
+      };
+      for (const stream of [child.stdout, child.stderr]) {
+        const decoder = new StringDecoder("utf8");
+        stream?.on("data", (chunk) => {
+          let text = decoder.write(chunk);
+          if (stream === child.stderr && nativeGroup) text = nativeGroup.accept(text);
+          if (text) onData(Buffer.from(text, "utf8"));
+        });
+        stream?.once("end", () => {
+          const text = decoder.end();
+          if (text) onData(Buffer.from(text, "utf8"));
+        });
+      }
+      const close = new Promise((resolve, reject) => {
+        child.once("error", reject);
+        child.once("close", (code) => resolve({ code }));
+      });
+      let closed = false;
+      void close.finally(() => {
+        closed = true;
+      }).catch(() => {
+      });
+      try {
+        await ctx.onProcessSpawned?.();
+      } catch {
+        if (nativeGroup) await waitForClose(nativeGroup.ready, 1e3);
+        stopProcessTree(child, nativeGroup);
+        if (!await waitForClose(close, 2e3)) {
+          forceProcessTree(child, nativeGroup);
+          await waitForClose(close, 3e3);
+        }
+        if (descriptor !== void 0) fs4.closeSync(descriptor);
+        throw new KapibalaError("Process started but spawn audit failed", {
+          code: "OUTCOME_UNKNOWN",
+          retryPolicy: "after_user_action",
+          safeMessage: "Command started but audit failed; outcome is unknown"
+        });
+      }
+      let stopReason;
+      let stopPromise;
+      const stop = (reason) => {
+        if (stopPromise) return;
+        stopReason = reason;
+        stopPromise = (async () => {
+          if (nativeGroup) await waitForClose(nativeGroup.ready, 1e3);
+          const stopped = stopProcessTree(child, nativeGroup);
+          if (await waitForClose(close, 2e3)) {
+            if (await confirmProcessTreeStopped(child, stopped, nativeGroup)) return true;
+          }
+          const forced = forceProcessTree(child, nativeGroup);
+          if (!await waitForClose(close, 3e3)) return false;
+          return confirmProcessTreeStopped(child, forced, nativeGroup);
+        })();
+      };
+      const timer = setTimeout(() => stop("timeout"), timeoutMs);
+      const progressTimer = setInterval(() => {
+        const now = Date.now();
+        if (now - lastProgressAt >= 500) {
+          lastProgressAt = now;
+          ctx.onProgress?.({ elapsedMs: now - startedAt, outputBytes });
+        }
+      }, 500);
+      const onAbort = () => stop("aborted");
+      if (ctx.signal?.aborted) onAbort();
+      else ctx.signal?.addEventListener("abort", onAbort, { once: true });
+      try {
+        const outcome = await Promise.race([
+          close.then((value) => ({ kind: "closed", value })),
+          new Promise((resolve) => {
+            const check = () => {
+              if (closed) return;
+              if (stopPromise)
+                void stopPromise.then((confirmed) => {
+                  if (!confirmed) resolve({ kind: "unknown" });
+                });
+              else setTimeout(check, 10);
+            };
+            check();
+          })
+        ]);
+        if (outcome.kind === "unknown") {
+          throw new KapibalaError("Command process tree could not be confirmed stopped", {
+            code: "OUTCOME_UNKNOWN",
+            retryPolicy: "after_user_action",
+            safeMessage: "Command outcome is unknown; inspect the system before retrying"
+          });
+        }
+        if (stopReason) {
+          if (!await stopPromise) {
+            throw new KapibalaError("Command process tree could not be confirmed stopped", {
+              code: "OUTCOME_UNKNOWN",
+              retryPolicy: "after_user_action",
+              safeMessage: "Command outcome is unknown; inspect the system before retrying"
+            });
+          }
+          throw new KapibalaError(`Command ${stopReason}`, {
+            code: stopReason === "timeout" ? "COMMAND_TIMEOUT" : "ABORTED",
+            retryPolicy: "after_user_action",
+            safeMessage: `Command ${stopReason}; process exit was observed`
+          });
+        }
+        if (outputFailure) {
+          throw new KapibalaError("Command output storage failed", {
+            code: "OUTPUT_STORAGE_FAILED",
+            retryPolicy: "after_user_action",
+            safeMessage: "Command finished but its output could not be stored"
+          });
+        }
+        const inlineBuffer = Buffer.concat(inline);
+        const output = utf8Prefix(inlineBuffer, INLINE_LIMIT).toString("utf8");
+        return {
+          exitCode: outcome.value.code,
+          output,
+          outputTruncated: outputBytes > INLINE_LIMIT,
+          ...outputFile ? { outputFile } : {},
+          outputFileTruncated,
+          outputBytes,
+          shell: environment.kind
+        };
+      } finally {
+        clearTimeout(timer);
+        clearInterval(progressTimer);
+        ctx.signal?.removeEventListener("abort", onAbort);
+        if (descriptor !== void 0) fs4.closeSync(descriptor);
+      }
+    }
+  });
+}
+
+// src/security/sandbox.ts
+import fs5 from "fs";
+import path5 from "path";
 function tryRealpath(target) {
   try {
-    return fs.realpathSync(target);
+    return fs5.realpathSync(target);
   } catch {
     return void 0;
   }
@@ -87,7 +1121,7 @@ var PathSandbox = class {
   allowSymlinks;
   cachedRealRootDir;
   constructor(config) {
-    this.rootDir = path.resolve(config.rootDir);
+    this.rootDir = path5.resolve(config.rootDir);
     this.allowSymlinks = config.allowSymlinks ?? false;
   }
   /**
@@ -110,16 +1144,16 @@ var PathSandbox = class {
     if (!targetPath || typeof targetPath !== "string") {
       throw new ToolError("Invalid path: path must be a non-empty string");
     }
-    const resolvedPath = path.isAbsolute(targetPath) ? path.resolve(targetPath) : path.resolve(this.rootDir, targetPath);
-    const relative = path.relative(this.rootDir, resolvedPath);
-    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    const resolvedPath = path5.isAbsolute(targetPath) ? path5.resolve(targetPath) : path5.resolve(this.rootDir, targetPath);
+    const relative = path5.relative(this.rootDir, resolvedPath);
+    if (relative.startsWith("..") || path5.isAbsolute(relative)) {
       throw new ToolError(
         `Access denied: path '${targetPath}' escapes root directory '${this.rootDir}'`
       );
     }
     const physicalPath = this.toPhysicalPath(resolvedPath);
-    const physicalRelative = path.relative(this.realRootDir, physicalPath);
-    if (physicalRelative.startsWith("..") || path.isAbsolute(physicalRelative)) {
+    const physicalRelative = path5.relative(this.realRootDir, physicalPath);
+    if (physicalRelative.startsWith("..") || path5.isAbsolute(physicalRelative)) {
       throw new ToolError(
         `Access denied: path '${targetPath}' resolves outside root directory '${this.rootDir}' (via symlink)`
       );
@@ -141,7 +1175,7 @@ var PathSandbox = class {
     while (true) {
       let stat;
       try {
-        stat = fs.lstatSync(probe);
+        stat = fs5.lstatSync(probe);
       } catch {
         stat = void 0;
       }
@@ -152,30 +1186,146 @@ var PathSandbox = class {
             `Access denied: cannot resolve real path for '${resolvedPath}' (broken or unresolvable symlink)`
           );
         }
-        return pendingSegments.length > 0 ? path.join(real, ...pendingSegments) : real;
+        return pendingSegments.length > 0 ? path5.join(real, ...pendingSegments) : real;
       }
-      const parent = path.dirname(probe);
+      const parent = path5.dirname(probe);
       if (parent === probe) {
         return resolvedPath;
       }
-      pendingSegments.unshift(path.basename(probe));
+      pendingSegments.unshift(path5.basename(probe));
       probe = parent;
     }
   }
 };
 
-// src/tools/index.ts
-function defineTool(tool) {
-  return tool;
+// src/security/permissions.ts
+import path6 from "path";
+var CAPABILITIES = /* @__PURE__ */ new Set([
+  "fs:read",
+  "fs:write",
+  "exec",
+  "net:outbound",
+  "env:read",
+  "agent:spawn"
+]);
+function validatePermissionRules(rules) {
+  for (const [index, rule] of rules.entries()) {
+    const ruleNumber = index + 1;
+    if (!["allow", "ask", "deny"].includes(rule.action)) {
+      throw new Error(`Permission rule ${ruleNumber}: invalid action`);
+    }
+    const scopes = Number(rule.tool !== void 0) + Number(rule.capability !== void 0) + Number(rule.shell !== void 0);
+    if (scopes !== 1)
+      throw new Error(`Permission rule ${ruleNumber}: exactly one scope is required`);
+    if (rule.capability && !CAPABILITIES.has(rule.capability)) {
+      throw new Error(`Permission rule ${ruleNumber}: unknown capability`);
+    }
+    if (rule.tool !== void 0 && (!rule.tool.trim() || /[*?]/.test(rule.tool))) {
+      throw new Error(`Permission rule ${ruleNumber}: tool scope must be an exact name`);
+    }
+    if (rule.shell) {
+      const { command, interpreter, cwd } = rule.shell;
+      if (!command?.trim() || !interpreter?.trim() || !cwd?.trim() || /[*?]/.test(command) || /[*?]/.test(interpreter) || /[*?]/.test(cwd)) {
+        throw new Error(
+          `Permission rule ${ruleNumber}: shell rules require an exact command, interpreter and cwd`
+        );
+      }
+    }
+  }
 }
-function toToolDefinition(tool) {
-  return {
-    name: tool.name,
-    description: tool.description,
-    parameters: tool.parameters
-  };
+function samePath(a, b) {
+  const na = path6.resolve(a);
+  const nb = path6.resolve(b);
+  return process.platform === "win32" ? na.toLowerCase() === nb.toLowerCase() : na === nb;
+}
+var PermissionPolicy = class {
+  decide(request) {
+    if (request.hardDenied) return { decision: "deny", source: "hard_limit" };
+    if (request.mode === "Plan" && (request.dangerous || request.capabilities.length === 0 || request.capabilities.some((capability) => capability !== "fs:read"))) {
+      return { decision: "deny", source: "plan" };
+    }
+    const matches = (rule) => {
+      if (rule.tool !== void 0) return rule.tool === request.toolName;
+      if (rule.capability !== void 0) return request.capabilities.includes(rule.capability);
+      if (!rule.shell || !request.shell) return false;
+      return rule.shell.command === request.shell.command && rule.shell.interpreter === request.shell.interpreter && samePath(rule.shell.cwd, request.shell.cwd);
+    };
+    const rules = request.rules ?? [];
+    for (const action of ["deny", "ask"]) {
+      const ruleIndex = rules.findIndex((rule) => rule.action === action && matches(rule));
+      if (ruleIndex >= 0) return { decision: action, source: "explicit_rule", ruleIndex };
+      if (action === "deny" && request.cachedDenial)
+        return { decision: "deny", source: "session_cache" };
+    }
+    if (request.cachedApproval) return { decision: "allow", source: "session_cache" };
+    if (request.capabilities.length === 0) return { decision: "ask", source: "mode_default" };
+    const allowIndex = rules.findIndex(
+      (rule) => rule.action === "allow" && matches(rule) && (request.toolName !== "run_command" || rule.shell !== void 0)
+    );
+    if (allowIndex >= 0)
+      return { decision: "allow", source: "explicit_rule", ruleIndex: allowIndex };
+    if (request.capabilities.length === 0 || request.dangerous && request.mode !== "FullAccess") {
+      return { decision: "ask", source: "mode_default" };
+    }
+    if (request.mode === "FullAccess") return { decision: "allow", source: "mode_default" };
+    if (request.capabilities.every((capability) => capability === "fs:read")) {
+      return { decision: "allow", source: "mode_default" };
+    }
+    if (request.mode === "Auto" && request.capabilities.every(
+      (capability) => capability === "fs:read" || capability === "fs:write"
+    )) {
+      return { decision: "allow", source: "mode_default" };
+    }
+    return { decision: "ask", source: "mode_default" };
+  }
+};
+function visibleTools(tools, mode, rules = []) {
+  const policy = new PermissionPolicy();
+  return tools.filter(
+    (tool) => policy.decide({
+      mode,
+      toolName: tool.name,
+      capabilities: tool.metadata?.permissions ?? [],
+      dangerous: tool.metadata?.dangerous,
+      rules
+    }).decision !== "deny"
+  );
 }
 
+// src/security/approval.ts
+import { createHash as createHash4 } from "crypto";
+function stableJsonStringify(value) {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(stableJsonStringify).join(",")}]`;
+  }
+  const obj = value;
+  const keys = Object.keys(obj).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${stableJsonStringify(obj[k])}`).join(",")}}`;
+}
+var SessionApprovalCache = class {
+  choices = /* @__PURE__ */ new Map();
+  key(request) {
+    return createHash4("sha256").update(
+      stableJsonStringify([
+        request.toolName,
+        [...request.capabilities].sort(),
+        request.input,
+        request.rootDir,
+        request.shell ?? null
+      ])
+    ).digest("hex");
+  }
+  get(request) {
+    return this.choices.get(this.key(request));
+  }
+  set(request, choice) {
+    this.choices.set(this.key(request), choice);
+  }
+};
+
 // src/tools/registry.ts
 var ToolRegistry = class {
   tools = /* @__PURE__ */ new Map();
@@ -233,8 +1383,8 @@ var ToolRegistry = class {
 };
 
 // src/tools/builtin/fs.ts
-import fs2 from "fs";
-import path2 from "path";
+import fs6 from "fs";
+import path7 from "path";
 var sandboxCache = /* @__PURE__ */ new Map();
 function getSandbox(rootDir) {
   let sandbox = sandboxCache.get(rootDir);
@@ -272,10 +1422,10 @@ var readFileTool = defineTool({
   async execute(input, ctx) {
     const sandbox = getSandbox(ctx.rootDir);
     const safePath = sandbox.resolveSafePath(input.path);
-    if (!fs2.existsSync(safePath)) {
+    if (!fs6.existsSync(safePath)) {
       throw new ToolError(`File not found: ${input.path}`);
     }
-    const stat = fs2.statSync(safePath);
+    const stat = fs6.statSync(safePath);
     if (stat.isDirectory()) {
       throw new ToolError(`Target path is a directory, not a file: ${input.path}`);
     }
@@ -288,11 +1438,11 @@ var readFileTool = defineTool({
     }
     const prefixSize = Math.min(stat.size, 8192);
     const prefix = Buffer.alloc(prefixSize);
-    const fileDescriptor = fs2.openSync(safePath, "r");
+    const fileDescriptor = fs6.openSync(safePath, "r");
     try {
-      fs2.readSync(fileDescriptor, prefix, 0, prefixSize, 0);
+      fs6.readSync(fileDescriptor, prefix, 0, prefixSize, 0);
     } finally {
-      fs2.closeSync(fileDescriptor);
+      fs6.closeSync(fileDescriptor);
     }
     if (prefix.includes(0)) {
       throw new ToolError(`Cannot read binary file: ${input.path}`);
@@ -305,7 +1455,7 @@ var readFileTool = defineTool({
         maxReadBytes
       );
     }
-    return fs2.readFileSync(safePath, "utf-8");
+    return fs6.readFileSync(safePath, "utf-8");
   }
 });
 async function readFileLineRange(filePath, startLine, endLine, maxReadBytes) {
@@ -315,7 +1465,7 @@ async function readFileLineRange(filePath, startLine, endLine, maxReadBytes) {
   let currentLine = 1;
   let pending = "";
   let reachedEnd = false;
-  const stream = fs2.createReadStream(filePath, { encoding: "utf-8" });
+  const stream = fs6.createReadStream(filePath, { encoding: "utf-8" });
   const selectLine = (line) => {
     if (currentLine >= startLine && (endLine === void 0 || currentLine <= endLine)) {
       const addedBytes = Buffer.byteLength(line, "utf-8") + (selectedLines.length > 0 ? 1 : 0);
@@ -378,11 +1528,11 @@ var writeFileTool = defineTool({
   async execute(input, ctx) {
     const sandbox = getSandbox(ctx.rootDir);
     const safePath = sandbox.resolveSafePath(input.path);
-    const dir = path2.dirname(safePath);
-    if (!fs2.existsSync(dir)) {
-      fs2.mkdirSync(dir, { recursive: true });
+    const dir = path7.dirname(safePath);
+    if (!fs6.existsSync(dir)) {
+      fs6.mkdirSync(dir, { recursive: true });
     }
-    fs2.writeFileSync(safePath, input.content, "utf-8");
+    fs6.writeFileSync(safePath, input.content, "utf-8");
     return `Successfully wrote ${Buffer.byteLength(input.content, "utf-8")} bytes to ${input.path}`;
   }
 });
@@ -414,13 +1564,13 @@ var editFileTool = defineTool({
   async execute(input, ctx) {
     const sandbox = getSandbox(ctx.rootDir);
     const safePath = sandbox.resolveSafePath(input.path);
-    if (!fs2.existsSync(safePath)) {
+    if (!fs6.existsSync(safePath)) {
       throw new ToolError(`File not found: ${input.path}`);
     }
     if (!input.targetContent) {
       throw new ToolError("Target content must not be empty");
     }
-    const content = fs2.readFileSync(safePath, "utf-8");
+    const content = fs6.readFileSync(safePath, "utf-8");
     if (!content.includes(input.targetContent)) {
       throw new ToolError(
         `Target content not found in ${input.path}. Ensure exact indentation and characters.`
@@ -433,7 +1583,7 @@ var editFileTool = defineTool({
       );
     }
     const newContent = content.replace(input.targetContent, () => input.replacementContent);
-    fs2.writeFileSync(safePath, newContent, "utf-8");
+    fs6.writeFileSync(safePath, newContent, "utf-8");
     return `Successfully replaced target content in ${input.path}`;
   }
 });
@@ -461,20 +1611,20 @@ var globTool = defineTool({
   async execute(input, ctx) {
     const sandbox = getSandbox(ctx.rootDir);
     const searchRoot = input.subDirectory ? sandbox.resolveSafePath(input.subDirectory) : ctx.rootDir;
-    if (!fs2.existsSync(searchRoot)) {
+    if (!fs6.existsSync(searchRoot)) {
       throw new ToolError(`Directory not found: ${input.subDirectory ?? "."}`);
     }
     const results = [];
     const maxResults = 100;
     function walk(currentDir) {
       if (results.length >= maxResults) return;
-      const entries = fs2.readdirSync(currentDir, { withFileTypes: true });
+      const entries = fs6.readdirSync(currentDir, { withFileTypes: true });
       for (const entry of entries) {
         if (entry.name === "node_modules" || entry.name === ".git" || entry.name === "dist") {
           continue;
         }
-        const fullPath = path2.join(currentDir, entry.name);
-        const relPath = path2.relative(ctx.rootDir, fullPath).replace(/\\/g, "/");
+        const fullPath = path7.join(currentDir, entry.name);
+        const relPath = path7.relative(ctx.rootDir, fullPath).replace(/\\/g, "/");
         if (entry.isDirectory()) {
           walk(fullPath);
         } else {
@@ -514,7 +1664,7 @@ var grepTool = defineTool({
     if (ctx.signal?.aborted) throw new AbortError();
     const sandbox = getSandbox(ctx.rootDir);
     const target = input.path ? sandbox.resolveSafePath(input.path) : ctx.rootDir;
-    if (!fs2.existsSync(target)) {
+    if (!fs6.existsSync(target)) {
       throw new ToolError(`Path not found: ${input.path ?? "."}`);
     }
     if (!input.pattern.trim()) throw new ToolError("Search pattern must not be empty");
@@ -526,8 +1676,8 @@ var grepTool = defineTool({
       if (matches.length >= maxMatches) return;
       const maxLineBytes = 512 * 1024;
       const maxOutputBytes = 512 * 1024;
-      const stream = fs2.createReadStream(filePath, { encoding: "utf-8" });
-      const relPath = path2.relative(ctx.rootDir, filePath).replace(/\\/g, "/");
+      const stream = fs6.createReadStream(filePath, { encoding: "utf-8" });
+      const relPath = path7.relative(ctx.rootDir, filePath).replace(/\\/g, "/");
       let lineNumber = 0;
       let pending = "";
       let skippingLongLine = false;
@@ -577,14 +1727,14 @@ var grepTool = defineTool({
     }
     async function walk(dirPath) {
       if (matches.length >= maxMatches) return;
-      const entries = fs2.readdirSync(dirPath, { withFileTypes: true });
+      const entries = fs6.readdirSync(dirPath, { withFileTypes: true });
       for (const entry of entries) {
         if (ctx.signal?.aborted) throw new AbortError();
         if (entry.name === "node_modules" || entry.name === ".git" || entry.name === "dist") {
           continue;
         }
         if (entry.isSymbolicLink()) continue;
-        const fullPath = path2.join(dirPath, entry.name);
+        const fullPath = path7.join(dirPath, entry.name);
         if (entry.isDirectory()) {
           await walk(fullPath);
         } else {
@@ -593,7 +1743,7 @@ var grepTool = defineTool({
         if (matches.length >= maxMatches) return;
       }
     }
-    const stat = fs2.statSync(target);
+    const stat = fs6.statSync(target);
     if (stat.isFile()) {
       await searchFile(target);
     } else {
@@ -633,6 +1783,7 @@ var HookRegistry = class {
 };
 
 // src/executor/index.ts
+import { createHash as createHash5 } from "crypto";
 var DEFAULT_TOOL_TIMEOUT_MS = 12e4;
 var ToolExecutor = class {
   tools;
@@ -641,54 +1792,310 @@ var ToolExecutor = class {
   signal;
   logger;
   toolTimeoutMs;
+  eventLogger;
+  sessionId;
+  runId;
+  mode;
+  permissionRules;
+  approvalChannel;
+  approvalCache;
+  policy = new PermissionPolicy();
+  neverFailures = /* @__PURE__ */ new Set();
+  cancellation = new AbortController();
   constructor(options) {
     this.tools = options.tools;
     this.hooks = options.hooks;
     this.rootDir = options.rootDir;
-    this.signal = options.signal;
+    this.signal = options.signal ? AbortSignal.any([options.signal, this.cancellation.signal]) : this.cancellation.signal;
     this.logger = options.logger;
     this.toolTimeoutMs = options.toolTimeoutMs ?? DEFAULT_TOOL_TIMEOUT_MS;
-  }
-  async runAll(calls) {
+    this.eventLogger = options.eventLogger;
+    this.sessionId = options.sessionId;
+    this.runId = options.runId;
+    this.mode = options.mode ?? "Approval";
+    this.permissionRules = options.permissionRules ?? [];
+    this.approvalChannel = options.approvalChannel;
+    this.approvalCache = options.approvalCache ?? new SessionApprovalCache();
+  }
+  /** 中止本轮正在等待或执行的工具；调用方仍须等待 runAll 完成资源回收及结果审计。 */
+  cancel() {
+    this.cancellation.abort();
+  }
+  async runAll(calls, onProgress) {
     const results = [];
+    let requiresUserAction = false;
     for (const call of calls) {
-      if (this.signal?.aborted) {
-        results.push({
-          type: "tool_result",
-          toolUseId: call.id,
-          content: "Tool execution aborted",
-          isError: true
-        });
-        continue;
-      }
-      results.push(await this.executeOne(call));
+      const result = await this.executeOne(call, onProgress, requiresUserAction);
+      results.push(result);
+      if (result.retryPolicy === "after_user_action") requiresUserAction = true;
     }
     return results;
   }
-  async executeOne(call) {
+  /** 在最终参数上裁决并审计一次调用，所有拒绝和异常均闭合为工具结果。 */
+  async executeOne(call, onProgress, forcedDeny = false) {
     const startedAt = Date.now();
+    const operationId = createLogId();
+    const failure = (message, errorCode, retryPolicy = "never") => ({
+      type: "tool_result",
+      toolUseId: call.id,
+      content: JSON.stringify({ code: errorCode, retryPolicy, message }),
+      isError: true,
+      errorCode,
+      retryPolicy,
+      durationMs: Math.max(0, Date.now() - startedAt)
+    });
+    const audit = async (event, fields = {}) => {
+      if (!this.eventLogger || !this.sessionId) return;
+      await this.eventLogger.recordAudit({
+        level: "info",
+        event,
+        sessionId: this.sessionId,
+        runId: this.runId,
+        operationId,
+        toolUseId: call.id,
+        fields: { toolName: call.name, ...fields }
+      });
+    };
+    try {
+      await audit("tool.requested", { status: "requested", processId: process.pid });
+    } catch {
+      return failure(
+        "Audit unavailable; tool was not started",
+        "AUDIT_UNAVAILABLE",
+        "after_user_action"
+      );
+    }
+    if (forcedDeny) {
+      try {
+        await audit("tool.decided", { decision: "deny", decisionSource: "prior_user_action" });
+        await audit("tool.finished", { status: "skipped", errorCode: "SKIPPED_AFTER_USER_ACTION" });
+      } catch {
+        return failure(
+          "Audit unavailable; tool was not started",
+          "AUDIT_UNAVAILABLE",
+          "after_user_action"
+        );
+      }
+      return failure(
+        "Earlier tool call requires user action",
+        "SKIPPED_AFTER_USER_ACTION",
+        "after_user_action"
+      );
+    }
     const hookCtx = { signal: this.signal, logger: this.logger };
     let currentInput = call.input;
-    const beforeHooks = this.hooks.get("tool:before");
-    for (const hook of beforeHooks) {
-      const decision = await hook(hookCtx, { id: call.id, name: call.name, input: currentInput });
-      if (decision.action === "skip") {
-        return {
-          type: "tool_result",
-          toolUseId: call.id,
-          content: decision.result,
-          isError: decision.isError ?? false,
-          durationMs: Math.max(0, Date.now() - startedAt)
-        };
+    try {
+      for (const hook of this.hooks.get("tool:before")) {
+        const decision = await hook(hookCtx, { id: call.id, name: call.name, input: currentInput });
+        if (decision.action === "modify") currentInput = decision.input;
+        if (decision.action === "skip") {
+          await audit("tool.decided", { decision: "deny", decisionSource: "hook" });
+          await audit("tool.finished", { status: "skipped" });
+          return {
+            type: "tool_result",
+            toolUseId: call.id,
+            content: decision.result,
+            isError: decision.isError ?? false,
+            durationMs: Math.max(0, Date.now() - startedAt)
+          };
+        }
+      }
+    } catch {
+      try {
+        await audit("tool.decided", { decision: "deny", decisionSource: "hook" });
+        await audit("tool.finished", { status: "failed" });
+      } catch {
+      }
+      return failure("Tool preparation failed", "HOOK_ERROR");
+    }
+    let tool;
+    try {
+      tool = this.tools.resolve(call.name);
+    } catch (error) {
+      const known = error instanceof KapibalaError ? error : void 0;
+      try {
+        await audit("tool.decided", { decision: "deny", decisionSource: "unavailable" });
+        await audit("tool.finished", { status: "failed" });
+      } catch {
+      }
+      return failure(
+        known?.safeMessage ?? "Requested tool is unavailable",
+        known?.code ?? "TOOL_NOT_FOUND"
+      );
+    }
+    try {
+      return await this.executeResolved(
+        call,
+        currentInput,
+        tool,
+        startedAt,
+        audit,
+        failure,
+        hookCtx,
+        onProgress
+      );
+    } catch {
+      try {
+        await audit("tool.finished", { status: "unknown", errorCode: "OUTCOME_UNKNOWN" });
+      } catch {
       }
-      if (decision.action === "modify") {
-        currentInput = decision.input;
+      return failure(
+        "Tool outcome is unknown after an executor failure",
+        "OUTCOME_UNKNOWN",
+        "after_user_action"
+      );
+    }
+  }
+  async executeResolved(call, currentInput, tool, startedAt, audit, failure, hookCtx, onProgress) {
+    let shell;
+    try {
+      shell = tool.approvalScope?.(currentInput, this.rootDir);
+    } catch {
+      try {
+        await audit("tool.decided", { decision: "deny", decisionSource: "invalid_target" });
+        await audit("tool.finished", { status: "failed", errorCode: "INVALID_TARGET" });
+      } catch {
       }
+      return failure("Invalid tool execution target", "INVALID_TARGET");
+    }
+    let auditFields = {};
+    for (let attempt = 0; attempt < 2; attempt++) {
+      const request = {
+        toolName: call.name,
+        capabilities: tool.metadata?.permissions ?? [],
+        input: currentInput,
+        rootDir: this.rootDir,
+        ...shell ? { shell } : {},
+        // 只有无参数的解释器内建查询能确认不依赖外部脚本；其余命令仅允许单次批准。
+        sessionAllowed: !shell || /^(?:pwd|get-location)$/i.test(shell.command.trim()) || shell.scriptDigest !== void 0
+      };
+      const repeatKey = createHash5("sha256").update(stableJsonStringify([call.name, currentInput])).digest("hex");
+      if (this.neverFailures.has(repeatKey)) {
+        try {
+          await audit("tool.decided", { decision: "deny", decisionSource: "repeat_block" });
+          await audit("tool.finished", { status: "blocked", errorCode: "REPEAT_BLOCKED" });
+        } catch {
+          return failure(
+            "Audit unavailable; tool was not started",
+            "AUDIT_UNAVAILABLE",
+            "after_user_action"
+          );
+        }
+        return failure(
+          "Identical failed tool call cannot be repeated in this run",
+          "REPEAT_BLOCKED"
+        );
+      }
+      const cached = this.approvalCache.get(request);
+      const decision = this.policy.decide({
+        mode: typeof this.mode === "function" ? this.mode() : this.mode,
+        toolName: call.name,
+        capabilities: request.capabilities,
+        dangerous: tool.metadata?.dangerous,
+        cachedApproval: cached === "allow",
+        cachedDenial: cached === "deny",
+        rules: this.permissionRules,
+        ...shell ? { shell } : {}
+      });
+      let permitted = decision.decision === "allow";
+      let source = decision.source;
+      let approvalChoice;
+      if (decision.decision === "ask") {
+        let choice = "deny_once";
+        try {
+          choice = await this.approvalChannel?.requestApproval(request, this.signal) ?? "deny_once";
+        } catch {
+          choice = "cancel";
+        }
+        approvalChoice = choice;
+        if (choice === "allow_session" && request.sessionAllowed)
+          this.approvalCache.set(request, "allow");
+        if (choice === "deny_session") this.approvalCache.set(request, "deny");
+        permitted = choice === "allow_once" || choice === "allow_session" && request.sessionAllowed;
+        source = this.approvalChannel ? "human" : "non_interactive";
+      }
+      auditFields = shell ? {
+        shell: shell.interpreter,
+        cwdDigest: createHash5("sha256").update(shell.cwd).digest("hex"),
+        executableDigest: shell.executableDigest,
+        executionFingerprint: shell.executionFingerprint,
+        ...commandAuditSummary(shell.command)
+      } : {};
+      try {
+        await audit("tool.decided", {
+          decision: permitted ? "allow" : "deny",
+          decisionSource: source,
+          ...approvalChoice ? { approvalChoice } : {},
+          ...auditFields
+        });
+      } catch {
+        return failure(
+          "Audit unavailable; tool was not started",
+          "AUDIT_UNAVAILABLE",
+          "after_user_action"
+        );
+      }
+      if (!permitted || this.signal?.aborted) {
+        const code = this.signal?.aborted ? "ABORTED" : "PERMISSION_DENIED";
+        try {
+          await audit("tool.finished", { status: "denied", errorCode: code });
+        } catch {
+          return failure("Audit result unavailable", "AUDIT_UNAVAILABLE", "after_user_action");
+        }
+        return failure(
+          this.signal?.aborted ? "Operation cancelled" : "Tool permission denied",
+          code,
+          "after_user_action"
+        );
+      }
+      if (shell) {
+        try {
+          const next = tool.approvalScope?.(currentInput, this.rootDir);
+          if (next?.executionFingerprint !== shell.executionFingerprint) {
+            if (attempt === 0 && next) {
+              try {
+                await audit("tool.target_changed", { status: "redeciding" });
+              } catch {
+                return failure(
+                  "Audit unavailable; tool was not started",
+                  "AUDIT_UNAVAILABLE",
+                  "after_user_action"
+                );
+              }
+              shell = next;
+              continue;
+            }
+            await audit("tool.finished", { status: "target_changed", errorCode: "TARGET_CHANGED" });
+            return failure(
+              "Execution target changed after approval",
+              "TARGET_CHANGED",
+              "after_user_action"
+            );
+          }
+        } catch {
+          return failure(
+            "Execution target changed after approval",
+            "TARGET_CHANGED",
+            "after_user_action"
+          );
+        }
+      }
+      break;
+    }
+    try {
+      await audit("tool.started", { status: "started", ...auditFields });
+    } catch {
+      return failure(
+        "Audit unavailable; tool was not started",
+        "AUDIT_UNAVAILABLE",
+        "after_user_action"
+      );
     }
     let outputStr;
     let isError = false;
+    let errorCode;
+    let retryPolicy;
     try {
-      const tool = this.tools.resolve(call.name);
       const executionController = new AbortController();
       const abortFromSession = () => executionController.abort();
       if (this.signal?.aborted) {
@@ -699,37 +2106,85 @@ var ToolExecutor = class {
       const toolCtx = {
         rootDir: this.rootDir,
         signal: executionController.signal,
-        logger: this.logger
+        logger: this.logger,
+        onProgress: (progress) => onProgress?.({ id: call.id, name: call.name, ...progress }),
+        ...shell ? {
+          onProcessSpawned: () => audit("process.spawned", { status: "spawned", ...auditFields })
+        } : {}
       };
       try {
-        const rawResult = await this.withTimeout(
+        const rawResult = tool.metadata?.managesTimeout ? await tool.execute(currentInput, toolCtx) : await this.withTimeout(
           tool.execute(currentInput, toolCtx),
           call.name,
           executionController
         );
         outputStr = typeof rawResult === "string" ? rawResult : JSON.stringify(rawResult, null, 2);
+        if (call.name === "run_command" && typeof rawResult === "object" && rawResult !== null && "exitCode" in rawResult && rawResult.exitCode !== 0) {
+          isError = true;
+          errorCode = "COMMAND_EXIT_NONZERO";
+          retryPolicy = "never";
+        }
       } finally {
         this.signal?.removeEventListener("abort", abortFromSession);
       }
     } catch (err) {
       isError = true;
-      outputStr = err instanceof Error ? err.message : String(err);
+      const known = err instanceof KapibalaError ? err : void 0;
+      outputStr = known?.safeMessage ?? "Tool execution failed";
+      errorCode = known?.code ?? "TOOL_FAILED";
+      retryPolicy = known?.retryPolicy ?? "never";
     }
     const resultBlock = {
       type: "tool_result",
       toolUseId: call.id,
       content: outputStr,
-      isError
+      isError,
+      ...errorCode ? { errorCode, retryPolicy } : {}
     };
-    const afterHooks = this.hooks.get("tool:after");
-    for (const hook of afterHooks) {
-      await hook(
-        hookCtx,
-        { id: call.id, name: call.name, input: currentInput },
-        { output: outputStr, isError }
-      );
+    if (resultBlock.isError && resultBlock.errorCode) {
+      resultBlock.content = JSON.stringify({
+        code: resultBlock.errorCode,
+        retryPolicy: resultBlock.retryPolicy,
+        message: outputStr
+      });
+    }
+    try {
+      for (const hook of this.hooks.get("tool:after")) {
+        await hook(
+          hookCtx,
+          { id: call.id, name: call.name, input: currentInput },
+          { output: outputStr, isError }
+        );
+      }
+    } catch {
+      resultBlock.content = JSON.stringify({
+        code: "HOOK_ERROR",
+        retryPolicy: "after_user_action",
+        message: "Tool finished but result processing failed"
+      });
+      resultBlock.isError = true;
+      resultBlock.errorCode = "HOOK_ERROR";
+      resultBlock.retryPolicy = "after_user_action";
     }
     resultBlock.durationMs = Math.max(0, Date.now() - startedAt);
+    if (resultBlock.isError && resultBlock.retryPolicy === "never") {
+      this.neverFailures.add(
+        createHash5("sha256").update(stableJsonStringify([call.name, currentInput])).digest("hex")
+      );
+    }
+    try {
+      await audit("tool.finished", {
+        status: resultBlock.isError ? "failed" : "completed",
+        ...resultBlock.errorCode ? { errorCode: resultBlock.errorCode } : {},
+        durationMs: resultBlock.durationMs
+      });
+    } catch {
+      return failure(
+        "Tool outcome is unknown because the audit result could not be written",
+        "OUTCOME_UNKNOWN",
+        "after_user_action"
+      );
+    }
     return resultBlock;
   }
   /**
@@ -743,7 +2198,14 @@ var ToolExecutor = class {
     let timer;
     const timeout = new Promise((_, reject) => {
       timer = setTimeout(() => {
-        const error = new ToolError(`Tool '${toolName}' timed out after ${this.toolTimeoutMs}ms`);
+        const error = new KapibalaError(
+          `Tool '${toolName}' timed out after ${this.toolTimeoutMs}ms`,
+          {
+            code: "OUTCOME_UNKNOWN",
+            retryPolicy: "after_user_action",
+            safeMessage: "Tool timed out; completion of side effects is unknown"
+          }
+        );
         reject(error);
         executionController.abort(error);
       }, this.toolTimeoutMs);
@@ -1078,15 +2540,15 @@ var OpenAICompatibleProvider = class {
 };
 
 // src/store/jsonl.ts
-import fs3 from "fs";
-import path3 from "path";
+import fs7 from "fs";
+import path8 from "path";
 var JSONLMessageStore = class {
   filePath;
   constructor(filePath) {
-    this.filePath = path3.resolve(filePath);
-    const dir = path3.dirname(this.filePath);
-    if (!fs3.existsSync(dir)) {
-      fs3.mkdirSync(dir, { recursive: true });
+    this.filePath = path8.resolve(filePath);
+    const dir = path8.dirname(this.filePath);
+    if (!fs7.existsSync(dir)) {
+      fs7.mkdirSync(dir, { recursive: true });
     }
   }
   async append(message) {
@@ -1095,14 +2557,14 @@ var JSONLMessageStore = class {
       role: message.role,
       content: message.content
     };
-    fs3.appendFileSync(this.filePath, `${JSON.stringify(record)}
+    fs7.appendFileSync(this.filePath, `${JSON.stringify(record)}
 `, "utf-8");
   }
   async load() {
-    if (!fs3.existsSync(this.filePath)) {
+    if (!fs7.existsSync(this.filePath)) {
       return [];
     }
-    const content = fs3.readFileSync(this.filePath, "utf-8");
+    const content = fs7.readFileSync(this.filePath, "utf-8");
     const lines = content.split("\n");
     const messages = [];
     for (const line of lines) {
@@ -1124,8 +2586,8 @@ var JSONLMessageStore = class {
     return messages;
   }
   async clear() {
-    if (fs3.existsSync(this.filePath)) {
-      fs3.unlinkSync(this.filePath);
+    if (fs7.existsSync(this.filePath)) {
+      fs7.unlinkSync(this.filePath);
     }
   }
   /**
@@ -1148,7 +2610,9 @@ var JSONLMessageStore = class {
             type: "tool_result",
             toolUseId: toolUse.id,
             content: "Tool execution was interrupted or crashed in previous session",
-            isError: true
+            isError: true,
+            errorCode: "OUTCOME_UNKNOWN",
+            retryPolicy: "after_user_action"
           })
         ),
         timestamp: Date.now()
@@ -1180,17 +2644,21 @@ var JSONLMessageStore = class {
 };
 
 // src/prompt/index.ts
-import os from "os";
+import os4 from "os";
 var PromptAssembler = class {
   tools;
   rootDir;
   agentName;
   customInstructions;
+  instructionSources;
+  visibleTools;
   constructor(options) {
     this.tools = options.tools;
     this.rootDir = options.rootDir;
     this.agentName = options.agentName ?? "Kapibala";
     this.customInstructions = options.customInstructions;
+    this.instructionSources = options.instructionSources ?? [];
+    this.visibleTools = options.visibleTools;
   }
   assemble() {
     const sections = [];
@@ -1202,6 +2670,13 @@ var PromptAssembler = class {
     if (this.customInstructions?.trim()) {
       sections.push(this.customInstructions.trim());
     }
+    if (this.instructionSources.length > 0) {
+      sections.push(
+        `# L4 Project Instructions
+${this.instructionSources.map((source, index) => `## ${index + 1}. ${source.path}
+${source.content}`).join("\n\n")}`
+      );
+    }
     return sections.filter(Boolean).join("\n\n---\n\n");
   }
   getL1Behavior() {
@@ -1218,7 +2693,7 @@ Follow these key behavioral rules:
   }
   getL2Tools() {
     if (!this.tools) return "";
-    const tools = this.tools.list();
+    const tools = this.visibleTools ?? this.tools.list();
     if (tools.length === 0) return "";
     const lines = ["# Available Tools:"];
     for (const tool of tools) {
@@ -1228,7 +2703,7 @@ Follow these key behavioral rules:
   }
   getL3Environment() {
     const now = (/* @__PURE__ */ new Date()).toISOString();
-    const platform = os.platform();
+    const platform = os4.platform();
     return `# Environment Context:
 - Current Working Directory (Workspace Root): ${this.rootDir}
 - Operating System: ${platform}
@@ -1246,6 +2721,11 @@ var AgentLoop = class {
   maxSteps;
   maxConsecutiveErrors;
   signal;
+  eventLogger;
+  sessionId;
+  runId;
+  getMode;
+  permissionRules;
   constructor(options) {
     this.provider = options.provider;
     this.executor = options.executor;
@@ -1255,6 +2735,11 @@ var AgentLoop = class {
     this.maxSteps = options.maxSteps ?? 20;
     this.maxConsecutiveErrors = options.maxConsecutiveErrors ?? 3;
     this.signal = options.signal;
+    this.eventLogger = options.eventLogger;
+    this.sessionId = options.sessionId;
+    this.runId = options.runId;
+    this.getMode = options.getMode ?? (() => "Approval");
+    this.permissionRules = options.permissionRules ?? [];
   }
   async *run(history) {
     let step = 0;
@@ -1270,7 +2755,9 @@ var AgentLoop = class {
       let request = {
         systemPrompt: this.systemPrompt,
         messages: history,
-        tools: this.tools.definitions(),
+        tools: visibleTools(this.tools.list(), this.getMode(), this.permissionRules).map(
+          toToolDefinition
+        ),
         signal: this.signal
       };
       const beforeModelHooks = this.hooks.get("model:before");
@@ -1293,6 +2780,15 @@ var AgentLoop = class {
       let turnUsage;
       let turnTtftMs;
       const modelStartTime = Date.now();
+      if (this.eventLogger && this.sessionId) {
+        await this.eventLogger.record({
+          level: "info",
+          event: "model.requested",
+          sessionId: this.sessionId,
+          runId: this.runId,
+          fields: { attempt: step, count: request.messages.length }
+        });
+      }
       let firstTokenReceived = false;
       const buildMetrics = (modelDurationMs2, toolDurationMs2, toolCallsCount) => {
         const endTime = Date.now();
@@ -1353,6 +2849,15 @@ var AgentLoop = class {
           throw new AbortError();
         }
         const modelError = err instanceof Error ? err : new Error(String(err));
+        if (this.eventLogger && this.sessionId) {
+          await this.eventLogger.record({
+            level: "error",
+            event: "model.failed",
+            sessionId: this.sessionId,
+            runId: this.runId,
+            fields: { attempt: step, durationMs: Date.now() - modelStartTime }
+          });
+        }
         await this.hooks.emit("error", hookCtx, modelError);
         yield { type: "error", error: modelError };
         yield {
@@ -1364,6 +2869,20 @@ var AgentLoop = class {
         break;
       }
       const modelDurationMs = Date.now() - modelStartTime;
+      if (this.eventLogger && this.sessionId) {
+        await this.eventLogger.record({
+          level: "info",
+          event: "model.finished",
+          sessionId: this.sessionId,
+          runId: this.runId,
+          fields: {
+            attempt: step,
+            durationMs: modelDurationMs,
+            promptTokens: turnUsage?.promptTokens ?? 0,
+            completionTokens: turnUsage?.completionTokens ?? 0
+          }
+        });
+      }
       yield {
         type: "step_log",
         log: {
@@ -1429,12 +2948,44 @@ var AgentLoop = class {
         yield { type: "tool_start", id: call.id, name: call.name, input: call.input };
       }
       const toolStartTime = Date.now();
-      const toolResults = await this.executor.runAll(toolCalls);
+      const progressQueue = [];
+      let progressWake;
+      let toolsFinished = false;
+      const toolRun = this.executor.runAll(toolCalls, (progress) => {
+        progressQueue.push({ type: "tool_progress", ...progress });
+        progressWake?.();
+      });
+      void toolRun.then(
+        () => {
+          toolsFinished = true;
+          progressWake?.();
+        },
+        () => {
+          toolsFinished = true;
+          progressWake?.();
+        }
+      );
+      let toolResults;
+      let toolMessages;
+      try {
+        while (!toolsFinished || progressQueue.length > 0) {
+          const next = progressQueue.shift();
+          if (next) yield next;
+          else
+            await new Promise((resolve) => {
+              progressWake = resolve;
+            });
+          progressWake = void 0;
+        }
+      } finally {
+        if (!toolsFinished) this.executor.cancel();
+        toolResults = await toolRun;
+        toolMessages = this.provider.assembleToolResults(toolResults);
+        history.push(assistantMessage, ...toolMessages);
+      }
       const toolDurationMs = Date.now() - toolStartTime;
       const hasError = toolResults.some((result) => result.isError);
       const metrics = buildMetrics(modelDurationMs, toolDurationMs, toolCalls.length);
-      const toolMessages = this.provider.assembleToolResults(toolResults);
-      history.push(assistantMessage, ...toolMessages);
       yield {
         type: "message_stop",
         message: assistantMessage,
@@ -1464,6 +3015,19 @@ var AgentLoop = class {
         }
       };
       yield { type: "tool_messages", messages: toolMessages };
+      if (toolResults.some((result) => result.retryPolicy === "after_user_action")) {
+        if (this.signal?.aborted) {
+          yield { type: "turn_finish", turn: step, usage: turnUsage, metrics };
+          throw new AbortError();
+        }
+        yield {
+          type: "error",
+          error: new Error("Tool execution requires user action before continuing")
+        };
+        yield { type: "turn_finish", turn: step, usage: turnUsage, metrics };
+        completed = true;
+        break;
+      }
       if (hasError) {
         consecutiveErrors++;
         if (consecutiveErrors >= this.maxConsecutiveErrors) {
@@ -1513,6 +3077,17 @@ var AgentSession = class {
   customSystemPrompt;
   maxSteps;
   logger;
+  eventLogger;
+  sessionId = createLogId();
+  mode;
+  permissionRules;
+  approvalChannel;
+  approvalCache = new SessionApprovalCache();
+  projectRoot;
+  cwd;
+  userInstructionsPath;
+  instructionSnapshot;
+  auditRecoveryDirectory;
   history = [];
   totalTurns = 0;
   usageStats = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
@@ -1532,13 +3107,49 @@ var AgentSession = class {
     this.customSystemPrompt = config.systemPrompt;
     this.maxSteps = config.maxSteps ?? 20;
     this.logger = config.logger;
+    validatePermissionRules(config.permissionRules ?? []);
+    this.mode = config.mode ?? "Approval";
+    this.permissionRules = config.permissionRules ?? [];
+    this.approvalChannel = config.approvalChannel;
+    this.projectRoot = config.projectRoot ?? this.rootDir;
+    this.cwd = config.cwd ?? this.rootDir;
+    this.userInstructionsPath = config.userInstructionsPath;
+    const sinks = config.eventLogger ? void 0 : createDefaultLogSinks(config.loggingDirectory);
+    this.eventLogger = config.eventLogger ?? new StructuredLogger({
+      operationSink: sinks.operationSink,
+      auditSink: sinks.auditSink,
+      debug: config.logger !== void 0,
+      onDiagnostic: config.onDiagnostic ?? config.logger
+    });
+    this.auditRecoveryDirectory = config.auditRecoveryDirectory ?? sinks?.auditSink.directory;
   }
   async init() {
     if (this.initialized) return;
+    if (this.auditRecoveryDirectory) {
+      const count = await recoverIncompleteAudit(this.auditRecoveryDirectory);
+      if (count > 0)
+        await this.eventLogger.record({
+          level: "warn",
+          event: "audit.recovered_unknown",
+          sessionId: this.sessionId,
+          fields: { count }
+        });
+    }
+    this.instructionSnapshot = loadInstructions({
+      projectRoot: this.projectRoot,
+      cwd: this.cwd,
+      userFile: this.userInstructionsPath
+    });
     if (this.store) {
       this.history = await this.store.load();
     }
     await this.hooks.emit("session:start", { logger: this.logger });
+    await this.eventLogger.record({
+      level: "info",
+      event: "session.started",
+      sessionId: this.sessionId,
+      fields: { modelId: this.router.getProfile("default").id }
+    });
     this.initialized = true;
   }
   async use(plugin) {
@@ -1566,6 +3177,18 @@ var AgentSession = class {
   getActiveProfile(role = "default") {
     return this.router.getProfile(role);
   }
+  /** 只在空闲时切换本次会话模式；宿主负责 FullAccess 的显式选择交互。 */
+  switchMode(mode) {
+    this.assertIdle("switch permission mode");
+    this.mode = mode;
+  }
+  getMode() {
+    return this.mode;
+  }
+  /** 返回最近一次成功装载的来源路径，不暴露指令正文。 */
+  getInstructionSources() {
+    return this.instructionSnapshot?.sources.map((source) => source.path) ?? [];
+  }
   getHistory() {
     return [...this.history];
   }
@@ -1613,6 +3236,7 @@ var AgentSession = class {
     this.assertIdle("start another run");
     resolveContextWindow(this.router.getProfile("default").contextWindow);
     this.activeRun = true;
+    const runId = createLogId();
     const runStartTime = Date.now();
     const aggregate = {
       modelDurationMs: 0,
@@ -1642,6 +3266,28 @@ var AgentSession = class {
       if (!this.initialized) {
         await this.init();
       }
+      await this.eventLogger.record({
+        level: "info",
+        event: "run.started",
+        sessionId: this.sessionId,
+        runId
+      });
+      try {
+        this.instructionSnapshot = loadInstructions({
+          projectRoot: this.projectRoot,
+          cwd: this.cwd,
+          userFile: this.userInstructionsPath
+        });
+      } catch (error) {
+        await this.eventLogger.record({
+          level: "warn",
+          event: "instructions.refresh_failed",
+          sessionId: this.sessionId,
+          runId,
+          fields: { status: "retained_previous_snapshot" }
+        });
+        if (!this.instructionSnapshot) throw error;
+      }
       this.totalTurns++;
       const userMessage = {
         role: "user",
@@ -1655,7 +3301,9 @@ var AgentSession = class {
       const promptAssembler = new PromptAssembler({
         tools: this.tools,
         rootDir: this.rootDir,
-        customInstructions: this.customSystemPrompt
+        customInstructions: this.customSystemPrompt,
+        instructionSources: this.instructionSnapshot.sources,
+        visibleTools: visibleTools(this.tools.list(), this.mode, this.permissionRules)
       });
       const assembledSystemPrompt = promptAssembler.assemble();
       const executor = new ToolExecutor({
@@ -1663,7 +3311,14 @@ var AgentSession = class {
         hooks: this.hooks,
         rootDir: this.rootDir,
         signal: options?.signal,
-        logger: this.logger
+        logger: this.logger,
+        eventLogger: this.eventLogger,
+        sessionId: this.sessionId,
+        runId,
+        mode: () => this.mode,
+        permissionRules: this.permissionRules,
+        approvalChannel: this.approvalChannel,
+        approvalCache: this.approvalCache
       });
       const loop = new AgentLoop({
         provider: this.router.resolve("default"),
@@ -1672,7 +3327,12 @@ var AgentSession = class {
         hooks: this.hooks,
         systemPrompt: assembledSystemPrompt,
         maxSteps: this.maxSteps,
-        signal: options?.signal
+        signal: options?.signal,
+        eventLogger: this.eventLogger,
+        sessionId: this.sessionId,
+        runId,
+        getMode: () => this.mode,
+        permissionRules: this.permissionRules
       });
       let pendingAssistant;
       let pendingEvents = [];
@@ -1680,10 +3340,24 @@ var AgentSession = class {
       let pendingAssistantPersisted = false;
       let pendingPersistenceStarted = false;
       let pendingToolMessages = [];
+      let persistedHistoryLength = this.history.length;
+      let loopCompleted = false;
+      let loopFailed = false;
       try {
         for await (const event of loop.run(this.history)) {
           if (event.type === "step_log") {
             this.logger?.(`[Turn ${event.log.turn} | ${event.log.stage}] ${event.log.message}`);
+            await this.eventLogger.record({
+              level: "debug",
+              event: "diagnostic.step",
+              sessionId: this.sessionId,
+              runId,
+              fields: {
+                phase: event.log.stage,
+                durationMs: event.log.durationMs ?? 0,
+                attempt: event.log.turn
+              }
+            });
           }
           if (event.type === "turn_finish") {
             this.lastMetrics = event.metrics;
@@ -1718,6 +3392,7 @@ var AgentSession = class {
             await this.persistAssistant(pendingAssistant);
             pendingAssistantPersisted = true;
             await this.persistToolMessages(event.messages);
+            persistedHistoryLength = this.history.length;
             const releasable = pendingEvents;
             pendingAssistant = void 0;
             pendingEvents = [];
@@ -1729,9 +3404,14 @@ var AgentSession = class {
           } else if (event.type === "tool_messages") {
             await this.persistToolMessages(event.messages);
           }
+          if (event.type === "message_stop" || event.type === "tool_messages") {
+            persistedHistoryLength = this.history.length;
+          }
           yield event;
         }
+        loopCompleted = true;
       } catch (error) {
+        loopFailed = true;
         if (pendingAssistant && !pendingPersistenceStarted) {
           const interruptedMessages = pendingClosedInMemory ? pendingToolMessages : this.closeInterruptedToolCalls(pendingAssistant, error);
           if (!pendingAssistantPersisted) {
@@ -1742,16 +3422,36 @@ var AgentSession = class {
           yield { type: "tool_messages", messages: interruptedMessages };
         }
         throw error;
+      } finally {
+        if (!loopCompleted && !loopFailed && this.store) {
+          for (const message of this.history.slice(persistedHistoryLength)) {
+            await this.store.append(message);
+          }
+        }
       }
       const metrics = finalizeRun(runStatus);
       this.lastRunMetrics = metrics;
       runFinalized = true;
+      await this.eventLogger.record({
+        level: "info",
+        event: "run.finished",
+        sessionId: this.sessionId,
+        runId,
+        fields: { status: metrics.status, durationMs: metrics.totalDurationMs }
+      });
       yield { type: "run_finish", metrics };
     } catch (error) {
       const status = error instanceof AbortError || options?.signal?.aborted ? "aborted" : "failed";
       const metrics = finalizeRun(status);
       this.lastRunMetrics = metrics;
       runFinalized = true;
+      await this.eventLogger.record({
+        level: "error",
+        event: "run.finished",
+        sessionId: this.sessionId,
+        runId,
+        fields: { status: metrics.status, durationMs: metrics.totalDurationMs }
+      });
       yield { type: "run_finish", metrics };
       throw error;
     } finally {
@@ -1768,8 +3468,8 @@ var AgentSession = class {
     for (const plugin of this.plugins) {
       try {
         await plugin.teardown?.();
-      } catch (err) {
-        this.logger?.(`Plugin '${plugin.name}' teardown failed: ${err.message}`);
+      } catch {
+        this.logger?.("Plugin teardown failed");
       }
     }
     this.plugins.length = 0;
@@ -1809,8 +3509,14 @@ var AgentSession = class {
       content: assistantEvent.message.content.filter((block) => block.type === "tool_use").map((toolUse) => ({
         type: "tool_result",
         toolUseId: toolUse.id,
-        content: `Tool execution interrupted before completion: ${error instanceof Error ? error.message : String(error)}`,
-        isError: true
+        content: JSON.stringify({
+          code: "OUTCOME_UNKNOWN",
+          retryPolicy: "after_user_action",
+          message: "Tool execution was interrupted; outcome is unknown"
+        }),
+        isError: true,
+        errorCode: "OUTCOME_UNKNOWN",
+        retryPolicy: "after_user_action"
       })),
       timestamp: Date.now()
     };
@@ -1841,32 +3547,50 @@ export {
   AgentSession,
   DEFAULT_CONTEXT_WINDOW_TOKENS,
   FatalError,
+  FileLogSink,
   HookRegistry,
   JSONLMessageStore,
   KapibalaError,
   ModelError,
   OpenAICompatibleProvider,
   PathSandbox,
+  PermissionPolicy,
   PromptAssembler,
+  SessionApprovalCache,
   SessionBusyError,
   SimpleModelRouter,
+  StructuredLogger,
   ToolError,
   ToolExecutor,
   ToolNotFound,
   ToolRegistry,
   TransportError,
   builtinTools,
+  classifyBashOutput,
+  cleanupCommandResults,
+  commandAuditSummary,
+  createDefaultLogSinks,
+  createLogId,
+  createRunCommandTool,
   defineTool,
+  detectShell,
   editFileTool,
+  executionFingerprint,
   globTool,
   grepTool,
   isTextBlock,
   isThinkingBlock,
   isToolResultBlock,
   isToolUseBlock,
+  loadInstructions,
+  projectSafeFields,
   readFileTool,
+  recoverIncompleteAudit,
   resolveContextWindow,
+  stableJsonStringify,
   toToolDefinition,
+  validatePermissionRules,
+  visibleTools,
   writeFileTool
 };
 //# sourceMappingURL=index.js.map