@wrongstack/core 0.2.0 → 0.3.2

package/dist/index.js

@@ -395,6 +395,7 @@ var Pipeline = class {
 // src/kernel/events.ts
 var EventBus = class {
   listeners = /* @__PURE__ */ new Map();
+  wildcards = [];
   logger;
   setLogger(logger) {
     this.logger = logger;
@@ -421,24 +422,73 @@ var EventBus = class {
       this.off(event, wrapper);
     };
   }
+  /**
+   * Subscribe to all events whose name matches a glob-style prefix.
+   * `'tool.*'` matches `tool.started`, `tool.executed`, `tool.progress`, etc.
+   * `'*'` matches every event.
+   *
+   * The handler receives `(eventName, payload)` with the event name as a
+   * string and the payload as `unknown`. Use for logging, debugging, or
+   * metrics collection across a family of events.
+   *
+   * Returns an unsubscribe function.
+   */
+  onPattern(pattern, fn) {
+    const match = makePatternMatcher(pattern);
+    const entry = { match, fn };
+    this.wildcards.push(entry);
+    return () => {
+      const idx = this.wildcards.indexOf(entry);
+      if (idx >= 0) this.wildcards.splice(idx, 1);
+    };
+  }
+  /**
+   * Subscribe to all events whose name matches a RegExp.
+   * More flexible than `onPattern` — use when you need regex features
+   * (alternation, character classes, capture groups).
+   *
+   * Returns an unsubscribe function.
+   */
+  onRegex(regex, fn) {
+    const entry = { match: (e) => regex.test(e), fn };
+    this.wildcards.push(entry);
+    return () => {
+      const idx = this.wildcards.indexOf(entry);
+      if (idx >= 0) this.wildcards.splice(idx, 1);
+    };
+  }
   emit(event, payload) {
     const set = this.listeners.get(event);
-    if (!set) return;
-    for (const fn of set) {
-      try {
-        fn(payload);
-      } catch (err) {
-        this.logger?.error(`EventBus listener for "${event}" threw`, err);
+    if (set) {
+      for (const fn of set) {
+        try {
+          fn(payload);
+        } catch (err) {
+          this.logger?.error(`EventBus listener for "${event}" threw`, err);
+        }
+      }
+    }
+    if (this.wildcards.length > 0) {
+      const name = event;
+      for (const { match, fn } of this.wildcards) {
+        if (!match(name)) continue;
+        try {
+          fn(name, payload);
+        } catch (err) {
+          this.logger?.error(`EventBus wildcard listener for "${name}" threw`, err);
+        }
       }
     }
   }
   clear() {
     this.listeners.clear();
+    this.wildcards.length = 0;
   }
   /**
    * V2-D: introspection helper. Pass an `event` to count handlers for a
    * single key, or omit to get the total across every event. Used by the
    * leak-detection smoke test to flag handler accumulation across runs.
+   * Does NOT include wildcard listeners.
    */
   listenerCount(event) {
     if (event !== void 0) return this.listeners.get(event)?.size ?? 0;
@@ -446,7 +496,21 @@ var EventBus = class {
     for (const set of this.listeners.values()) total += set.size;
     return total;
   }
+  /**
+   * Number of wildcard listeners currently registered.
+   */
+  wildcardCount() {
+    return this.wildcards.length;
+  }
 };
+function makePatternMatcher(pattern) {
+  if (pattern === "*") return () => true;
+  if (pattern.endsWith(".*")) {
+    const prefix = pattern.slice(0, -2);
+    return (e) => e.startsWith(`${prefix}.`);
+  }
+  return (e) => e === pattern;
+}
 
 // src/kernel/tokens.ts
 var t = (name) => Symbol(name);
@@ -468,7 +532,9 @@ var TOKENS = {
   SystemPromptBuilder: t("SystemPromptBuilder"),
   SecretScrubber: t("SecretScrubber"),
   ModelsRegistry: t("ModelsRegistry"),
-  ModeStore: t("ModeStore")
+  ModeStore: t("ModeStore"),
+  /** Replaces the entire provider call layer — retry, streaming, tracing. */
+  ProviderRunner: t("ProviderRunner")
 };
 
 // src/kernel/run-controller.ts
@@ -1100,6 +1166,98 @@ function estimateTextTokens(text) {
   return RoughTokenEstimate(text);
 }
 
+// src/utils/message-invariants.ts
+function repairToolUseAdjacency(messages) {
+  const removedToolUses = [];
+  const removedToolResults = [];
+  let removedMessages = 0;
+  let changed = false;
+  const out = [];
+  for (let i = 0; i < messages.length; i++) {
+    const original = messages[i];
+    let msg = original;
+    if (hasToolUse(msg)) {
+      const nextIds = toolResultIds(messages[i + 1]);
+      const filtered = mapContent(msg, (blocks) => {
+        const next = [];
+        for (const block of blocks) {
+          if (block.type === "tool_use" && !nextIds.has(block.id)) {
+            removedToolUses.push(block.id);
+            changed = true;
+            continue;
+          }
+          next.push(block);
+        }
+        return next;
+      });
+      msg = filtered ?? msg;
+    }
+    if (hasToolResult(msg)) {
+      const allowed = toolUseIds(out[out.length - 1]);
+      const filtered = mapContent(msg, (blocks) => {
+        const next = [];
+        for (const block of blocks) {
+          if (block.type === "tool_result" && !allowed.has(block.tool_use_id)) {
+            removedToolResults.push(block.tool_use_id);
+            changed = true;
+            continue;
+          }
+          next.push(block);
+        }
+        return next;
+      });
+      msg = filtered ?? msg;
+    }
+    if (isEmptyMessage(msg)) {
+      removedMessages++;
+      changed = true;
+      continue;
+    }
+    out.push(msg);
+  }
+  return {
+    messages: changed ? out : messages,
+    report: { changed, removedToolUses, removedToolResults, removedMessages }
+  };
+}
+function hasToolUse(msg) {
+  return contentBlocks(msg).some((b) => b.type === "tool_use");
+}
+function hasToolResult(msg) {
+  return contentBlocks(msg).some((b) => b.type === "tool_result");
+}
+function toolUseIds(msg) {
+  const ids = /* @__PURE__ */ new Set();
+  if (!msg || msg.role !== "assistant") return ids;
+  for (const block of contentBlocks(msg)) {
+    if (block.type === "tool_use") ids.add(block.id);
+  }
+  return ids;
+}
+function toolResultIds(msg) {
+  const ids = /* @__PURE__ */ new Set();
+  if (!msg || msg.role !== "user") return ids;
+  for (const block of contentBlocks(msg)) {
+    if (block.type === "tool_result") ids.add(block.tool_use_id);
+  }
+  return ids;
+}
+function contentBlocks(msg) {
+  return msg && Array.isArray(msg.content) ? msg.content : [];
+}
+function mapContent(msg, fn) {
+  if (!Array.isArray(msg.content)) return msg;
+  const next = fn(msg.content);
+  if (next.length === msg.content.length && next.every((b, idx) => b === msg.content[idx])) {
+    return msg;
+  }
+  return { ...msg, content: next };
+}
+function isEmptyMessage(msg) {
+  if (typeof msg.content === "string") return msg.content.trim().length === 0;
+  return msg.content.length === 0;
+}
+
 // src/execution/compactor.ts
 var HybridCompactor = class {
   preserveK;
@@ -1113,20 +1271,36 @@ var HybridCompactor = class {
   async compact(ctx, opts = {}) {
     const beforeTokens = this.estimateMessages(ctx.messages);
     const reductions = [];
-    const phase1Saved = this.eliseOldToolResults(ctx);
+    const policy = readContextWindowPolicy(ctx);
+    const preserveK = policy?.preserveK ?? this.preserveK;
+    const eliseThreshold = policy?.eliseThreshold ?? this.eliseThreshold;
+    const phase1Saved = this.eliseOldToolResults(ctx, preserveK, eliseThreshold);
     if (phase1Saved > 0) reductions.push({ phase: "elision", saved: phase1Saved });
     if (opts.aggressive) {
-      const phase2Saved = this.collapseAncientTurns(ctx);
+      const phase2Saved = this.collapseAncientTurns(ctx, preserveK);
       if (phase2Saved > 0) reductions.push({ phase: "summary", saved: phase2Saved });
     }
+    const repaired = repairToolUseAdjacency(ctx.messages);
+    if (repaired.report.changed) {
+      ctx.state.replaceMessages(repaired.messages);
+    }
     const afterTokens = this.estimateMessages(ctx.messages);
-    return { before: beforeTokens, after: afterTokens, reductions };
+    return {
+      before: beforeTokens,
+      after: afterTokens,
+      reductions,
+      repaired: repaired.report.changed ? {
+        removedToolUses: repaired.report.removedToolUses,
+        removedToolResults: repaired.report.removedToolResults,
+        removedMessages: repaired.report.removedMessages
+      } : void 0
+    };
   }
-  eliseOldToolResults(ctx) {
+  eliseOldToolResults(ctx, preserveK = this.preserveK, eliseThreshold = this.eliseThreshold) {
     const messages = ctx.messages;
     let pairCount = 0;
     let preserveStart = messages.length;
-    for (let i = messages.length - 1; i >= 0 && pairCount < this.preserveK; i--) {
+    for (let i = messages.length - 1; i >= 0 && pairCount < preserveK; i--) {
       const m = messages[i];
       if (!m) continue;
       if (m.role === "user" || m.role === "assistant") {
@@ -1150,7 +1324,7 @@ var HybridCompactor = class {
       const newContent = msg.content.map((b) => {
         if (b.type !== "tool_result") return b;
         const tokens = estimateToolResultTokens(b.content);
-        if (tokens < this.eliseThreshold) return b;
+        if (tokens < eliseThreshold) return b;
         saved += tokens;
         const elided = {
           type: "tool_result",
@@ -1170,9 +1344,9 @@ var HybridCompactor = class {
     if (changed) ctx.state.replaceMessages(nextMessages);
     return saved;
   }
-  collapseAncientTurns(ctx) {
+  collapseAncientTurns(ctx, preserveK = this.preserveK) {
     const messages = ctx.messages;
-    const cutTarget = Math.max(0, messages.length - this.preserveK * 2);
+    const cutTarget = Math.max(0, messages.length - preserveK * 2);
     if (cutTarget <= 0) return 0;
     let boundary = -1;
     for (let i = cutTarget; i < messages.length; i++) {
@@ -1213,6 +1387,15 @@ var HybridCompactor = class {
     return total;
   }
 };
+function readContextWindowPolicy(ctx) {
+  const policy = ctx.meta?.["contextWindowPolicy"];
+  if (!policy || typeof policy !== "object") return null;
+  const candidate = policy;
+  if (typeof candidate.preserveK !== "number" || typeof candidate.eliseThreshold !== "number") {
+    return null;
+  }
+  return candidate;
+}
 function hasTextContent(m) {
   if (typeof m.content === "string") return m.content.trim().length > 0;
   return m.content.some((b) => b.type === "text" && b.text.trim().length > 0);
@@ -1539,7 +1722,7 @@ async function atomicWrite(targetPath, content, opts = {}) {
     if (mode !== void 0) {
       await fsp2.chmod(tmp, mode);
     }
-    await fsp2.rename(tmp, targetPath);
+    await renameWithRetry(tmp, targetPath);
   } catch (err) {
     try {
       await fsp2.unlink(tmp);
@@ -1551,6 +1734,29 @@ async function atomicWrite(targetPath, content, opts = {}) {
 async function ensureDir(dir) {
   await fsp2.mkdir(dir, { recursive: true });
 }
+var TRANSIENT_RENAME_CODES = /* @__PURE__ */ new Set(["EPERM", "EBUSY", "EACCES", "ENOTEMPTY"]);
+async function renameWithRetry(from, to) {
+  if (process.platform !== "win32") {
+    await fsp2.rename(from, to);
+    return;
+  }
+  const delays = [10, 25, 60, 120, 250];
+  let lastErr;
+  for (let i = 0; i <= delays.length; i++) {
+    try {
+      await fsp2.rename(from, to);
+      return;
+    } catch (err) {
+      lastErr = err;
+      const code = err?.code;
+      if (!code || !TRANSIENT_RENAME_CODES.has(code) || i === delays.length) {
+        throw err;
+      }
+      await new Promise((resolve4) => setTimeout(resolve4, delays[i]));
+    }
+  }
+  throw lastErr;
+}
 
 // src/models/models-registry.ts
 var DEFAULT_URL = "https://models.dev/api.json";
@@ -1855,6 +2061,85 @@ When refactoring code:
   }
 ];
 
+// src/types/context-window.ts
+var DEFAULT_CONTEXT_WINDOW_MODE_ID = "balanced";
+var CONTEXT_WINDOW_MODES = Object.freeze([
+  {
+    id: "balanced",
+    name: "Balanced",
+    description: "Default rolling compaction: recent work stays verbatim, old tool output is trimmed.",
+    thresholds: { warn: 0.6, soft: 0.75, hard: 0.9 },
+    aggressiveOn: "soft",
+    preserveK: 10,
+    eliseThreshold: 2e3,
+    targetLoad: 0.65
+  },
+  {
+    id: "frugal",
+    name: "Frugal",
+    description: "Token-saver mode: compacts early and keeps a tighter verbatim tail.",
+    thresholds: { warn: 0.45, soft: 0.6, hard: 0.75 },
+    aggressiveOn: "warn",
+    preserveK: 6,
+    eliseThreshold: 700,
+    targetLoad: 0.5
+  },
+  {
+    id: "deep",
+    name: "Deep",
+    description: "Long-reasoning mode: delays compaction and keeps more recent turns intact.",
+    thresholds: { warn: 0.72, soft: 0.86, hard: 0.96 },
+    aggressiveOn: "hard",
+    preserveK: 18,
+    eliseThreshold: 5e3,
+    targetLoad: 0.78
+  },
+  {
+    id: "archival",
+    name: "Archival",
+    description: "Decision-preserving mode: compacts steadily while keeping summaries prominent.",
+    thresholds: { warn: 0.55, soft: 0.7, hard: 0.84 },
+    aggressiveOn: "soft",
+    preserveK: 8,
+    eliseThreshold: 1200,
+    targetLoad: 0.58
+  }
+]);
+function listContextWindowModes() {
+  return CONTEXT_WINDOW_MODES.map((m) => ({ ...m, thresholds: { ...m.thresholds } }));
+}
+function getContextWindowMode(id) {
+  if (!id) return null;
+  const mode = CONTEXT_WINDOW_MODES.find((m) => m.id === id);
+  return mode ? { ...mode, thresholds: { ...mode.thresholds } } : null;
+}
+function isContextWindowModeId(id) {
+  return CONTEXT_WINDOW_MODES.some((m) => m.id === id);
+}
+function resolveContextWindowPolicy(config = {}, overrideMode) {
+  const requested = overrideMode ?? config.mode ?? DEFAULT_CONTEXT_WINDOW_MODE_ID;
+  const mode = getContextWindowMode(requested) ?? getContextWindowMode(DEFAULT_CONTEXT_WINDOW_MODE_ID);
+  if (mode.id !== DEFAULT_CONTEXT_WINDOW_MODE_ID) {
+    return mode;
+  }
+  return {
+    ...mode,
+    thresholds: {
+      warn: config.warnThreshold ?? mode.thresholds.warn,
+      soft: config.softThreshold ?? mode.thresholds.soft,
+      hard: config.hardThreshold ?? mode.thresholds.hard
+    },
+    preserveK: config.preserveK ?? mode.preserveK,
+    eliseThreshold: config.eliseThreshold ?? mode.eliseThreshold
+  };
+}
+function formatContextWindowModeList(activeId) {
+  return CONTEXT_WINDOW_MODES.map((m) => {
+    const marker = m.id === activeId ? "*" : " ";
+    return `${marker} ${m.id.padEnd(9)} ${m.name} - ${m.description}`;
+  }).join("\n");
+}
+
 // src/coordination/in-memory-transport.ts
 var InMemoryBridgeTransport = class {
   subs = /* @__PURE__ */ new Map();
@@ -1974,6 +2259,7 @@ var InMemoryAgentBridge = class {
     this.stopped = true;
     for (const [, p] of this.pendingRequests) {
       clearTimeout(p.timer);
+      p.reject(new Error("Bridge stopped"));
     }
     this.pendingRequests.clear();
     this.inflightGuards.clear();
@@ -3404,11 +3690,17 @@ var DefaultSessionStore = class {
     if (openToolUses.size > 0) {
       this.events?.emit("session.damaged", {
         sessionId,
-        detail: `${openToolUses.size} tool_use blocks without matching results \u2014 replay truncated`
+        detail: `${openToolUses.size} tool_use blocks without matching results - replay repaired`
+      });
+    }
+    const repaired = repairToolUseAdjacency(messages);
+    if (repaired.report.changed) {
+      this.events?.emit("session.damaged", {
+        sessionId,
+        detail: `Repaired replay adjacency: removed ${repaired.report.removedToolUses.length} tool_use, ${repaired.report.removedToolResults.length} tool_result, ${repaired.report.removedMessages} empty messages`
       });
-      return { messages, usage };
     }
-    return { messages, usage };
+    return { messages: repaired.messages, usage };
   }
 };
 var FileSessionWriter = class {
@@ -3434,6 +3726,7 @@ var FileSessionWriter = class {
   startedAt;
   meta;
   closed = false;
+  closing = false;
   manifestFile;
   summary;
   tokenIn = 0;
@@ -3449,9 +3742,7 @@ var FileSessionWriter = class {
   resumed;
   appendFailCount = 0;
   lastAppendWarnAt = 0;
-  async writeSessionStart() {
-    if (this.initDone || this.closed) return;
-    this.initDone = true;
+  async writeSessionStartLazy() {
     const record = `${JSON.stringify({
       type: this.resumed ? "session_resumed" : "session_start",
       ts: this.startedAt,
@@ -3470,7 +3761,8 @@ var FileSessionWriter = class {
   async append(event) {
     if (this.closed) return;
     if (!this.initDone) {
-      await this.writeSessionStart();
+      this.initDone = true;
+      await this.writeSessionStartLazy();
     }
     this.observeForSummary(event);
     try {
@@ -3511,7 +3803,8 @@ var FileSessionWriter = class {
     }
   }
   async close() {
-    if (this.closed) return;
+    if (this.closing) return;
+    this.closing = true;
     this.closed = true;
     if (this.manifestFile) {
       try {
@@ -3913,9 +4206,52 @@ function deepFreeze(obj) {
   }
   return Object.freeze(obj);
 }
+
+// src/security/config-secrets.ts
+function decryptConfigSecrets2(cfg, vault) {
+  return walk3(cfg, vault, (v, key) => {
+    try {
+      return vault.decrypt(v);
+    } catch (err) {
+      console.warn(
+        `[secret-vault] Failed to decrypt "${key}":`,
+        err instanceof Error ? err.message : err
+      );
+      return "";
+    }
+  });
+}
+function walk3(node, vault, transform) {
+  if (node === null || node === void 0) return node;
+  if (typeof node !== "object") return node;
+  if (Array.isArray(node)) {
+    return node.map((item) => walk3(item, vault, transform));
+  }
+  const out = {};
+  for (const [k, v] of Object.entries(node)) {
+    if (typeof v === "string" && isSecretField2(k)) {
+      out[k] = transform(v, k);
+    } else if (typeof v === "object" && v !== null) {
+      out[k] = walk3(v, vault, transform);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+var SECRET_KEY_PATTERN2 = /(?:apikey|api_key|authtoken|auth_token|bearer|secret|password|passwd|pwd|refreshtoken|refresh_token|sessionkey|session_key|access[_-]?token|private[_-]?key)/i;
+var NON_SECRET_OVERRIDES2 = /* @__PURE__ */ new Set(["publickey", "public_key"]);
+function isSecretField2(name) {
+  const lc = name.toLowerCase();
+  if (NON_SECRET_OVERRIDES2.has(lc)) return false;
+  return SECRET_KEY_PATTERN2.test(lc);
+}
+
+// src/storage/config-loader.ts
 var BEHAVIOR_DEFAULTS = {
   version: 1,
   context: {
+    mode: DEFAULT_CONTEXT_WINDOW_MODE_ID,
     warnThreshold: 0.6,
     softThreshold: 0.75,
     hardThreshold: 0.9,
@@ -4030,7 +4366,7 @@ var DefaultConfigLoader = class {
       cfg = deepMerge2(cfg, opts.cliFlags);
     }
     if (this.vault) {
-      cfg = decryptConfigSecrets(cfg, this.vault);
+      cfg = decryptConfigSecrets2(cfg, this.vault);
     }
     if (cfg.providers) {
       for (const pcfg of Object.values(cfg.providers)) {
@@ -4090,6 +4426,10 @@ var DefaultConfigLoader = class {
     if (c.warnThreshold >= c.softThreshold || c.softThreshold >= c.hardThreshold) {
       throw new Error("Config: context thresholds must satisfy warn < soft < hard");
     }
+    if (c.mode !== void 0 && !isContextWindowModeId(c.mode)) {
+      const known = listContextWindowModes().map((m) => m.id).join(", ");
+      throw new Error(`Config: context.mode must be one of: ${known}`);
+    }
   }
   validateIdentity(cfg) {
     if (!cfg.provider) {
@@ -4410,24 +4750,35 @@ async function saveTodosCheckpoint(filePath, sessionId, todos) {
 function attachTodosCheckpoint(state, filePath, sessionId) {
   let timer = null;
   let pending = null;
+  let writeChain = Promise.resolve();
+  const enqueueWrite = (todos) => {
+    writeChain = writeChain.then(() => saveTodosCheckpoint(filePath, sessionId, todos));
+    return writeChain;
+  };
   const flush = () => {
     timer = null;
     if (pending) {
-      void saveTodosCheckpoint(filePath, sessionId, pending);
+      const todos = pending;
       pending = null;
+      return enqueueWrite(todos);
     }
+    return writeChain;
   };
   const unsubscribe = state.onChange((change) => {
     if (change.kind !== "todos_replaced") return;
     pending = change.todos;
     if (timer) clearTimeout(timer);
-    timer = setTimeout(flush, 150);
+    timer = setTimeout(() => {
+      void flush();
+    }, 150);
   });
-  return () => {
+  return async () => {
     unsubscribe();
     if (timer) {
       clearTimeout(timer);
-      flush();
+      await flush();
+    } else {
+      await writeChain;
     }
   };
 }
@@ -4889,112 +5240,419 @@ function parseDescription(raw) {
   return { trigger, scope };
 }
 
-// src/execution/intelligent-compactor.ts
-var IntelligentCompactor = class {
-  provider;
-  warnThreshold;
-  softThreshold;
-  hardThreshold;
-  maxContext;
-  preserveK;
-  eliseThreshold;
-  summarizerPrompt;
-  summarizerModel;
-  constructor(opts) {
-    this.provider = opts.provider;
-    this.warnThreshold = opts.warnThreshold ?? 0.6;
-    this.softThreshold = opts.softThreshold ?? 0.75;
-    this.hardThreshold = opts.hardThreshold ?? 0.9;
-    this.maxContext = opts.maxContext ?? 128e3;
-    this.preserveK = opts.preserveK ?? 4;
-    this.eliseThreshold = opts.eliseThreshold ?? 500;
-    this.summarizerPrompt = opts.summarizerPrompt ?? "You are a context summarizer. Given a list of conversation messages, produce a concise but complete summary that preserves all factual information, decisions made, and any state changes (e.g. file edits, todo updates). Do not add commentary. Output only the summary.";
-    this.summarizerModel = opts.summarizerModel;
-  }
-  async compact(ctx, opts = {}) {
-    const beforeTokens = this.estimateTokens(ctx.messages);
-    const reductions = [];
-    const load = beforeTokens / this.maxContext;
-    const aggressive = load >= this.hardThreshold ? true : opts.aggressive ?? load >= this.softThreshold;
-    const saved1 = this.eliseOldToolResults(ctx);
-    if (saved1 > 0) reductions.push({ phase: "elision", saved: saved1 });
-    if (aggressive) {
-      const saved2 = await this.summarizeAncientTurns(ctx);
-      if (saved2 > 0) reductions.push({ phase: "summary", saved: saved2 });
-    } else if (load >= this.warnThreshold) {
-      const saved2 = this.lightweightCompact(ctx);
-      if (saved2 > 0) reductions.push({ phase: "elision", saved: saved2 });
-    }
-    const afterTokens = this.estimateTokens(ctx.messages);
-    return { before: beforeTokens, after: afterTokens, reductions };
-  }
-  async summarizeAncientTurns(ctx) {
-    const messages = ctx.messages;
-    const cutoff = Math.max(0, messages.length - this.preserveK * 2);
-    if (cutoff <= 2) return 0;
-    const boundary = this.findSafeBoundary(messages, 0, cutoff);
-    if (boundary <= 1) return 0;
-    const toSummarize = messages.slice(0, boundary);
-    const removedTokens = this.estimateTokens(toSummarize);
-    let summaryText;
-    try {
-      summaryText = await this.callSummarizer(toSummarize, ctx);
-    } catch {
-      summaryText = `[${toSummarize.length} earlier turns omitted \u2014 key decisions and file states preserved in context]`;
-    }
-    const summaryMsg = {
-      role: "system",
-      content: `[prior_turns_summary: ${summaryText}]`
-    };
-    const summaryTokens = this.estimateTokens([summaryMsg]);
-    const tail = ctx.messages.slice(boundary);
-    ctx.state.replaceMessages([summaryMsg, ...tail]);
-    return Math.max(0, removedTokens - summaryTokens);
-  }
-  findSafeBoundary(messages, from, to) {
-    for (let i = to; i >= from; i--) {
-      const m = messages[i];
-      if (!m) continue;
-      if (m.role === "user" && this.hasTextContent(m)) {
-        return this.findExchangeStart(messages, i);
+// src/core/streaming-response-builder.ts
+function buildResponse(state) {
+  const content = [];
+  for (const b of state.blockOrder) {
+    if (b.kind === "text") {
+      const txt = state.textBuffers[b.idx] ?? "";
+      if (txt) content.push({ type: "text", text: txt });
+    } else if (b.kind === "thinking") {
+      const t2 = state.thinking[b.idx];
+      if (!t2) continue;
+      if (!t2.textBuf && !t2.signature) continue;
+      const block = { type: "thinking", thinking: t2.textBuf };
+      if (t2.signature) block.signature = t2.signature;
+      if (t2.providerMeta && Object.keys(t2.providerMeta).length > 0) {
+        block.providerMeta = t2.providerMeta;
       }
-    }
-    return -1;
-  }
-  findExchangeStart(messages, userIndex) {
-    for (let i = userIndex - 1; i >= 0; i--) {
-      const m = messages[i];
-      if (!m) continue;
-      if (m.role === "assistant") {
-        const hasToolUse = Array.isArray(m.content) ? m.content.some((b) => b.type === "tool_use") : false;
-        if (!hasToolUse) {
-          return i + 1;
+      content.push(block);
+    } else {
+      const tb = state.tools.get(b.id);
+      if (tb) {
+        const block = {
+          type: "tool_use",
+          id: b.id,
+          name: tb.name,
+          input: tb.input ?? {}
+        };
+        if (tb.providerMeta && Object.keys(tb.providerMeta).length > 0) {
+          block.providerMeta = tb.providerMeta;
         }
-      } else if (m.role !== "user") ; else {
-        return i;
+        content.push(block);
       }
     }
-    return 0;
-  }
-  async callSummarizer(messages, ctx) {
-    const prompt = [
-      { type: "text", text: this.summarizerPrompt },
-      { type: "text", text: "\n\nConversation to summarize:\n" },
-      ...this.messagesToText(messages)
-    ];
-    const req = {
-      model: this.summarizerModel ?? ctx.model,
-      system: prompt,
-      messages: [],
-      maxTokens: 1024
-    };
-    const ac = ctx.signal ? void 0 : new AbortController();
-    const signal = ctx.signal ?? ac.signal;
-    const res = await this.provider.complete(req, { signal });
-    const textBlocks = res.content.filter(isTextBlock);
-    return textBlocks.map((b) => b.text).join("\n").trim() || "(empty summary)";
   }
-  messagesToText(messages) {
+  if (content.length === 0) content.push({ type: "text", text: "" });
+  return { content, stopReason: state.stopReason, usage: state.usage, model: state.model };
+}
+function createStreamingState(model) {
+  return {
+    model,
+    stopReason: "end_turn",
+    usage: { input: 0, output: 0 },
+    textBuffers: [],
+    currentTextIndex: -1,
+    tools: /* @__PURE__ */ new Map(),
+    thinking: [],
+    currentThinkingIndex: -1,
+    blockOrder: []
+  };
+}
+function handleMessageStart(state, model) {
+  state.model = model;
+}
+function handleContentBlockStart(state, ev) {
+  const kind = ev.kind ?? "text";
+  if (kind === "text") {
+    state.currentTextIndex = state.textBuffers.length;
+    state.textBuffers.push("");
+    state.blockOrder.push({ kind: "text", idx: state.currentTextIndex });
+  } else if (kind === "tool_use") {
+    const id = ev.id ?? crypto.randomUUID();
+    state.tools.set(id, { name: ev.name ?? "unknown", partial: "" });
+    state.blockOrder.push({ kind: "tool", id });
+    state.currentTextIndex = -1;
+  } else if (kind === "thinking") {
+    state.currentThinkingIndex = state.thinking.length;
+    state.thinking.push({
+      textBuf: "",
+      ...ev.providerMeta ? { providerMeta: ev.providerMeta } : {}
+    });
+    state.blockOrder.push({ kind: "thinking", idx: state.currentThinkingIndex });
+    state.currentTextIndex = -1;
+  }
+}
+function handleContentBlockStop(state, ev) {
+}
+function handleTextDelta(state, text) {
+  if (state.currentTextIndex === -1) {
+    state.currentTextIndex = state.textBuffers.length;
+    state.textBuffers.push("");
+    state.blockOrder.push({ kind: "text", idx: state.currentTextIndex });
+  }
+  state.textBuffers[state.currentTextIndex] = (state.textBuffers[state.currentTextIndex] ?? "") + text;
+}
+function handleToolUseStart(state, ev) {
+  state.currentTextIndex = -1;
+  state.tools.set(ev.id, { name: ev.name, partial: "" });
+  state.blockOrder.push({ kind: "tool", id: ev.id });
+}
+function handleToolUseInputDelta(state, ev) {
+  const t2 = state.tools.get(ev.id);
+  if (t2) t2.partial += ev.partial;
+}
+function safeJsonOrRaw(s) {
+  if (!s) return {};
+  try {
+    return JSON.parse(s);
+  } catch {
+    return { _raw: s };
+  }
+}
+function handleToolUseStop(state, ev) {
+  const t2 = state.tools.get(ev.id);
+  if (t2) {
+    t2.input = ev.input !== void 0 ? ev.input : safeJsonOrRaw(t2.partial);
+    if (ev.providerMeta) t2.providerMeta = ev.providerMeta;
+  }
+  state.currentTextIndex = -1;
+}
+function handleThinkingStart(state, ev) {
+  state.currentThinkingIndex = state.thinking.length;
+  state.thinking.push({
+    textBuf: "",
+    ...ev.providerMeta ? { providerMeta: ev.providerMeta } : {}
+  });
+  state.blockOrder.push({ kind: "thinking", idx: state.currentThinkingIndex });
+  state.currentTextIndex = -1;
+}
+function handleThinkingDelta(state, text) {
+  if (state.currentThinkingIndex === -1) {
+    handleThinkingStart(state, {});
+  }
+  const t2 = state.thinking[state.currentThinkingIndex];
+  if (t2) t2.textBuf += text;
+}
+function handleThinkingSignature(state, signature) {
+  if (state.currentThinkingIndex === -1) {
+    handleThinkingStart(state, {});
+  }
+  const t2 = state.thinking[state.currentThinkingIndex];
+  if (t2) t2.signature = signature;
+}
+function handleThinkingStop(state) {
+  state.currentThinkingIndex = -1;
+}
+function handleMessageStop(state, ev) {
+  state.stopReason = ev.stopReason ?? "end_turn";
+  state.usage = ev.usage ?? { input: 0, output: 0 };
+}
+async function streamProviderToResponse(provider, req, signal, ctx, events) {
+  const state = createStreamingState(req.model);
+  const iter = provider.stream(req, { signal })[Symbol.asyncIterator]();
+  try {
+    for (; ; ) {
+      const next = await iter.next();
+      if (next.done) break;
+      const ev = next.value;
+      switch (ev.type) {
+        case "message_start":
+          handleMessageStart(state, ev.model);
+          break;
+        case "content_block_start":
+          handleContentBlockStart(state, ev);
+          break;
+        case "content_block_stop":
+          handleContentBlockStop(state, ev);
+          break;
+        case "text_delta":
+          handleTextDelta(state, ev.text);
+          events.emit("provider.text_delta", { ctx, text: ev.text });
+          break;
+        case "tool_use_start":
+          handleToolUseStart(state, ev);
+          events.emit("provider.tool_use_start", { ctx, id: ev.id, name: ev.name });
+          break;
+        case "tool_use_input_delta":
+          handleToolUseInputDelta(state, ev);
+          break;
+        case "tool_use_stop":
+          handleToolUseStop(state, ev);
+          events.emit("provider.tool_use_stop", { ctx, id: ev.id });
+          break;
+        case "thinking_start":
+          handleThinkingStart(state, ev);
+          break;
+        case "thinking_delta":
+          handleThinkingDelta(state, ev.text);
+          events.emit("provider.thinking_delta", { ctx, text: ev.text });
+          break;
+        case "thinking_signature":
+          handleThinkingSignature(state, ev.signature);
+          break;
+        case "thinking_stop":
+          handleThinkingStop(state);
+          break;
+        case "message_stop":
+          handleMessageStop(state, ev);
+          break;
+      }
+    }
+  } catch (err) {
+    if (signal.aborted) {
+      state.stopReason = "end_turn";
+      return buildResponse(state);
+    }
+    throw err;
+  } finally {
+    try {
+      let drainTimer = null;
+      try {
+        await Promise.race([
+          Promise.resolve(iter.return?.()),
+          new Promise((resolve4) => {
+            drainTimer = setTimeout(resolve4, 500);
+          })
+        ]);
+      } finally {
+        if (drainTimer) clearTimeout(drainTimer);
+      }
+    } catch {
+    }
+  }
+  return buildResponse(state);
+}
+
+// src/core/provider-runner.ts
+async function runProviderWithRetry(opts) {
+  const { provider, request, signal, ctx, events, retry, logger, tracer } = opts;
+  let attempt = 0;
+  for (; ; ) {
+    const span = tracer?.startSpan("provider.complete", {
+      "provider.id": provider.id,
+      "provider.model": request.model,
+      "provider.streaming": provider.capabilities.streaming,
+      "provider.attempt": attempt
+    });
+    try {
+      const res = provider.capabilities.streaming ? await streamProviderToResponse(provider, request, signal, ctx, events) : await provider.complete(request, { signal });
+      span?.setAttribute("provider.stopReason", res.stopReason);
+      span?.setAttribute("provider.usage_in", res.usage.input);
+      span?.setAttribute("provider.usage_out", res.usage.output);
+      span?.end();
+      return res;
+    } catch (err) {
+      if (err instanceof Error) span?.recordError(err);
+      span?.end();
+      if (signal.aborted) throw err;
+      const isProviderErr = err instanceof ProviderError;
+      const errAsErr = err instanceof Error ? err : new Error(String(err));
+      const canRetry = retry.shouldRetry(isProviderErr ? err : errAsErr, attempt);
+      const description = isProviderErr ? err.describe() : errAsErr.message;
+      if (!canRetry) {
+        if (isProviderErr) {
+          events.emit("provider.error", {
+            providerId: err.providerId,
+            status: err.status,
+            description,
+            retryable: false
+          });
+        }
+        throw err;
+      }
+      const delay = Math.round(retry.delayMs(attempt));
+      const attemptNum = attempt + 1;
+      logger.warn(`Provider retry ${attemptNum} in ${delay}ms \u2014 ${description}`);
+      if (isProviderErr) {
+        events.emit("provider.retry", {
+          providerId: err.providerId,
+          attempt: attemptNum,
+          delayMs: delay,
+          status: err.status,
+          description
+        });
+      }
+      await new Promise((resolve4, reject) => {
+        let settled = false;
+        const onAbort = () => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(t2);
+          reject(new Error("aborted"));
+        };
+        const t2 = setTimeout(() => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(t2);
+          signal.removeEventListener("abort", onAbort);
+          resolve4();
+        }, delay);
+        if (signal.aborted) {
+          onAbort();
+          return;
+        }
+        signal.addEventListener("abort", onAbort, { once: true });
+      });
+      attempt++;
+    }
+  }
+}
+
+// src/execution/provider-runner-impl.ts
+var DefaultProviderRunner = class {
+  async run(opts) {
+    return runProviderWithRetry(opts);
+  }
+};
+
+// src/execution/intelligent-compactor.ts
+var IntelligentCompactor = class {
+  provider;
+  warnThreshold;
+  softThreshold;
+  hardThreshold;
+  maxContext;
+  preserveK;
+  eliseThreshold;
+  summarizerPrompt;
+  summarizerModel;
+  constructor(opts) {
+    this.provider = opts.provider;
+    this.warnThreshold = opts.warnThreshold ?? 0.6;
+    this.softThreshold = opts.softThreshold ?? 0.75;
+    this.hardThreshold = opts.hardThreshold ?? 0.9;
+    this.maxContext = opts.maxContext ?? 128e3;
+    this.preserveK = opts.preserveK ?? 4;
+    this.eliseThreshold = opts.eliseThreshold ?? 500;
+    this.summarizerPrompt = opts.summarizerPrompt ?? "You are a context summarizer. Given a list of conversation messages, produce a concise but complete summary that preserves all factual information, decisions made, and any state changes (e.g. file edits, todo updates). Do not add commentary. Output only the summary.";
+    this.summarizerModel = opts.summarizerModel;
+  }
+  async compact(ctx, opts = {}) {
+    const beforeTokens = this.estimateTokens(ctx.messages);
+    const reductions = [];
+    const load = beforeTokens / this.maxContext;
+    const aggressive = load >= this.hardThreshold ? true : opts.aggressive ?? load >= this.softThreshold;
+    const saved1 = this.eliseOldToolResults(ctx);
+    if (saved1 > 0) reductions.push({ phase: "elision", saved: saved1 });
+    if (aggressive) {
+      const saved2 = await this.summarizeAncientTurns(ctx);
+      if (saved2 > 0) reductions.push({ phase: "summary", saved: saved2 });
+    } else if (load >= this.warnThreshold) {
+      const saved2 = this.lightweightCompact(ctx);
+      if (saved2 > 0) reductions.push({ phase: "elision", saved: saved2 });
+    }
+    const repaired = repairToolUseAdjacency(ctx.messages);
+    if (repaired.report.changed) ctx.state.replaceMessages(repaired.messages);
+    const afterTokens = this.estimateTokens(ctx.messages);
+    return {
+      before: beforeTokens,
+      after: afterTokens,
+      reductions,
+      repaired: repaired.report.changed ? {
+        removedToolUses: repaired.report.removedToolUses,
+        removedToolResults: repaired.report.removedToolResults,
+        removedMessages: repaired.report.removedMessages
+      } : void 0
+    };
+  }
+  async summarizeAncientTurns(ctx) {
+    const messages = ctx.messages;
+    const cutoff = Math.max(0, messages.length - this.preserveK * 2);
+    if (cutoff <= 2) return 0;
+    const boundary = this.findSafeBoundary(messages, 0, cutoff);
+    if (boundary <= 1) return 0;
+    const toSummarize = messages.slice(0, boundary);
+    const removedTokens = this.estimateTokens(toSummarize);
+    let summaryText;
+    try {
+      summaryText = await this.callSummarizer(toSummarize, ctx);
+    } catch {
+      summaryText = `[${toSummarize.length} earlier turns omitted \u2014 key decisions and file states preserved in context]`;
+    }
+    const summaryMsg = {
+      role: "system",
+      content: `[prior_turns_summary: ${summaryText}]`
+    };
+    const summaryTokens = this.estimateTokens([summaryMsg]);
+    const tail = ctx.messages.slice(boundary);
+    ctx.state.replaceMessages([summaryMsg, ...tail]);
+    return Math.max(0, removedTokens - summaryTokens);
+  }
+  findSafeBoundary(messages, from, to) {
+    for (let i = to; i >= from; i--) {
+      const m = messages[i];
+      if (!m) continue;
+      if (m.role === "user" && this.hasTextContent(m)) {
+        return this.findExchangeStart(messages, i);
+      }
+    }
+    return -1;
+  }
+  findExchangeStart(messages, userIndex) {
+    for (let i = userIndex - 1; i >= 0; i--) {
+      const m = messages[i];
+      if (!m) continue;
+      if (m.role === "assistant") {
+        const hasToolUse2 = Array.isArray(m.content) ? m.content.some((b) => b.type === "tool_use") : false;
+        if (!hasToolUse2) {
+          return i + 1;
+        }
+      } else if (m.role !== "user") ; else {
+        return i;
+      }
+    }
+    return 0;
+  }
+  async callSummarizer(messages, ctx) {
+    const prompt = [
+      { type: "text", text: this.summarizerPrompt },
+      { type: "text", text: "\n\nConversation to summarize:\n" },
+      ...this.messagesToText(messages)
+    ];
+    const req = {
+      model: this.summarizerModel ?? ctx.model,
+      system: prompt,
+      messages: [],
+      maxTokens: 1024
+    };
+    const ac = ctx.signal ? void 0 : new AbortController();
+    const signal = ctx.signal ?? ac.signal;
+    const res = await this.provider.complete(req, { signal });
+    const textBlocks = res.content.filter(isTextBlock);
+    return textBlocks.map((b) => b.text).join("\n").trim() || "(empty summary)";
+  }
+  messagesToText(messages) {
     const lines = [];
     for (const m of messages) {
       const role = m.role.padEnd(10, " ");
@@ -5273,8 +5931,9 @@ var SelectiveCompactor = class {
     if (!shouldCompact) {
       const saved = this.eliseOldToolResults(ctx);
       if (saved > 0) reductions.push({ phase: "elision", saved });
+      const repair2 = this.repairProtocolAdjacency(ctx);
       const afterTokens2 = this.estimateTokens(ctx.messages);
-      return { before: beforeTokens, after: afterTokens2, reductions };
+      return { before: beforeTokens, after: afterTokens2, reductions, repaired: repair2 };
     }
     const savedElision = this.eliseOldToolResults(ctx);
     if (savedElision > 0) reductions.push({ phase: "elision", saved: savedElision });
@@ -5284,8 +5943,18 @@ var SelectiveCompactor = class {
       const savedSelective = await this.runSelector(ctx, targetBudget);
       if (savedSelective > 0) reductions.push({ phase: "selective", saved: savedSelective });
     }
+    const repair = this.repairProtocolAdjacency(ctx);
     const afterTokens = this.estimateTokens(ctx.messages);
-    return { before: beforeTokens, after: afterTokens, reductions };
+    return { before: beforeTokens, after: afterTokens, reductions, repaired: repair };
+  }
+  repairProtocolAdjacency(ctx) {
+    const repaired = repairToolUseAdjacency(ctx.messages);
+    if (repaired.report.changed) ctx.state.replaceMessages(repaired.messages);
+    return repaired.report.changed ? {
+      removedToolUses: repaired.report.removedToolUses,
+      removedToolResults: repaired.report.removedToolResults,
+      removedMessages: repaired.report.removedMessages
+    } : void 0;
   }
   /**
    * Run the LLM selector to decide what to keep vs collapse.
@@ -5473,6 +6142,7 @@ var AutoCompactionMiddleware = class {
   aggressiveOn;
   events;
   failureMode;
+  policyProvider;
   /**
    * @param compactor        Compactor to use for compaction.
    * @param maxContext       Provider's max context window in tokens.
@@ -5495,17 +6165,25 @@ var AutoCompactionMiddleware = class {
     this.aggressiveOn = opts.aggressiveOn ?? "soft";
     this.events = opts.events;
     this.failureMode = opts.failureMode ?? "throw_on_hard";
+    this.policyProvider = opts.policyProvider;
   }
   handler() {
     return async (ctx, next) => {
       const tokens = this.estimator(ctx);
       const load = tokens / this.maxContext;
-      if (load >= this.hardThreshold) {
+      const policy = this.policyProvider?.(ctx);
+      const thresholds = policy?.thresholds ?? {
+        warn: this.warnThreshold,
+        soft: this.softThreshold,
+        hard: this.hardThreshold
+      };
+      const aggressiveOn = policy?.aggressiveOn ?? this.aggressiveOn;
+      if (load >= thresholds.hard) {
         await this.compact(ctx, true, { level: "hard", tokens, load });
-      } else if (load >= this.softThreshold) {
-        await this.compact(ctx, this.aggressiveOn !== "hard", { level: "soft", tokens, load });
-      } else if (load >= this.warnThreshold) {
-        await this.compact(ctx, false, { level: "warn", tokens, load });
+      } else if (load >= thresholds.soft) {
+        await this.compact(ctx, aggressiveOn !== "hard", { level: "soft", tokens, load });
+      } else if (load >= thresholds.warn) {
+        await this.compact(ctx, aggressiveOn === "warn", { level: "warn", tokens, load });
       }
       return next(ctx);
     };
@@ -6473,6 +7151,179 @@ function providerErrorToSubagentError(err, message, cause) {
   }
   return { kind: "unknown", message, retryable: err.retryable, cause };
 }
+function makeSpawnTool(director, roster) {
+  const inputSchema = {
+    type: "object",
+    properties: {
+      role: { type: "string", description: "Roster role id (preferred). When set, the spawn uses the matching config from the roster and ignores other fields." },
+      name: { type: "string", description: "Display name for the subagent. Required when not using roster." },
+      provider: { type: "string", description: 'Provider id (e.g. "anthropic", "openai"). Defaults to the leader provider when omitted.' },
+      model: { type: "string", description: "Model id within the provider. Defaults to the leader model when omitted." },
+      systemPromptOverride: { type: "string", description: "Extra prompt text appended after the role-base prompt." },
+      maxIterations: { type: "number" },
+      maxToolCalls: { type: "number" },
+      maxCostUsd: { type: "number" }
+    },
+    required: []
+  };
+  return {
+    name: "spawn_subagent",
+    description: "Create a new subagent under this director. Returns the subagent id.",
+    usageHint: "Either pass `role` (matches the roster) OR pass `name` + optional `provider`/`model`. Returns `{ subagentId }`.",
+    permission: "auto",
+    mutating: false,
+    inputSchema,
+    async execute(input) {
+      const i = input ?? {};
+      const role = typeof i.role === "string" ? i.role : void 0;
+      const base = role && roster ? roster[role] : void 0;
+      if (role && !base) {
+        return { error: `unknown role "${role}". roster has: ${roster ? Object.keys(roster).join(", ") : "(empty)"}` };
+      }
+      const cfg = { ...base ?? { name: i.name ?? "subagent" } };
+      if (typeof i.name === "string") cfg.name = i.name;
+      if (typeof i.provider === "string") cfg.provider = i.provider;
+      if (typeof i.model === "string") cfg.model = i.model;
+      if (typeof i.systemPromptOverride === "string") cfg.systemPromptOverride = i.systemPromptOverride;
+      if (typeof i.maxIterations === "number") cfg.maxIterations = i.maxIterations;
+      if (typeof i.maxToolCalls === "number") cfg.maxToolCalls = i.maxToolCalls;
+      if (typeof i.maxCostUsd === "number") cfg.maxCostUsd = i.maxCostUsd;
+      try {
+        const subagentId = await director.spawn(cfg);
+        return { subagentId, provider: cfg.provider, model: cfg.model, name: cfg.name };
+      } catch (err) {
+        if (err instanceof DirectorBudgetError) {
+          return { error: err.message, kind: err.kind, limit: err.limit, observed: err.observed };
+        }
+        return { error: err instanceof Error ? err.message : String(err) };
+      }
+    }
+  };
+}
+function makeAssignTool(director) {
+  const inputSchema = {
+    type: "object",
+    properties: {
+      subagentId: { type: "string", description: "Target subagent id. Required." },
+      description: { type: "string", description: "The task in natural language \u2014 what you want this subagent to do." },
+      maxToolCalls: { type: "number", description: "Optional per-task tool-call budget override." },
+      timeoutMs: { type: "number", description: "Optional per-task timeout in ms." }
+    },
+    required: ["subagentId", "description"]
+  };
+  return {
+    name: "assign_task",
+    description: "Hand a task to a previously spawned subagent. Returns the task id.",
+    permission: "auto",
+    mutating: false,
+    inputSchema,
+    async execute(input) {
+      const i = input;
+      const task = { id: randomUUID(), description: i.description, subagentId: i.subagentId, maxToolCalls: i.maxToolCalls, timeoutMs: i.timeoutMs };
+      const taskId = await director.assign(task);
+      return { taskId, subagentId: i.subagentId };
+    }
+  };
+}
+function makeAwaitTasksTool(director) {
+  return {
+    name: "await_tasks",
+    description: "Block until every named task completes. Returns the array of TaskResult.",
+    permission: "auto",
+    mutating: false,
+    inputSchema: { type: "object", properties: { taskIds: { type: "array", items: { type: "string" }, description: "One or more task ids returned by `assign_task`." } }, required: ["taskIds"] },
+    async execute(input) {
+      const i = input;
+      const results = await director.awaitTasks(i.taskIds);
+      return { results };
+    }
+  };
+}
+function makeAskTool(director) {
+  return {
+    name: "ask_subagent",
+    description: "Synchronously ask a subagent a question. Blocks until the subagent replies via the bridge.",
+    permission: "auto",
+    mutating: false,
+    inputSchema: {
+      type: "object",
+      properties: {
+        subagentId: { type: "string", description: "Subagent to ask. Must be a previously spawned id." },
+        question: { type: "string", description: "The question or instruction." },
+        timeoutMs: { type: "number", description: "Optional timeout in ms (default 30s)." }
+      },
+      required: ["subagentId", "question"]
+    },
+    async execute(input) {
+      const i = input;
+      try {
+        const answer = await director.ask(i.subagentId, { question: i.question }, i.timeoutMs);
+        return { ok: true, answer };
+      } catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+      }
+    }
+  };
+}
+function makeRollUpTool(director) {
+  return {
+    name: "roll_up",
+    description: "Aggregate completed task results into a single formatted summary.",
+    permission: "auto",
+    mutating: false,
+    inputSchema: {
+      type: "object",
+      properties: {
+        taskIds: { type: "array", items: { type: "string" }, description: "Completed task ids to aggregate." },
+        style: { type: "string", enum: ["markdown", "json"], description: "Output flavor \u2014 markdown (default) or json." }
+      },
+      required: ["taskIds"]
+    },
+    async execute(input) {
+      const i = input;
+      const summary = director.rollUp(i.taskIds, i.style ?? "markdown");
+      return { summary, count: i.taskIds.length };
+    }
+  };
+}
+function makeTerminateTool(director) {
+  return {
+    name: "terminate_subagent",
+    description: "Forcibly abort a subagent.",
+    permission: "auto",
+    mutating: true,
+    inputSchema: { type: "object", properties: { subagentId: { type: "string", description: "Subagent to abort." } }, required: ["subagentId"] },
+    async execute(input) {
+      const i = input;
+      await director.terminate(i.subagentId);
+      return { ok: true };
+    }
+  };
+}
+function makeFleetStatusTool(director) {
+  return {
+    name: "fleet_status",
+    description: "Snapshot of the fleet \u2014 every subagent's current status, pending vs. completed task counts.",
+    permission: "auto",
+    mutating: false,
+    inputSchema: { type: "object", properties: {}, required: [] },
+    async execute() {
+      return director.status();
+    }
+  };
+}
+function makeFleetUsageTool(director) {
+  return {
+    name: "fleet_usage",
+    description: "Token + cost breakdown across the fleet, per-subagent and totals.",
+    permission: "auto",
+    mutating: false,
+    inputSchema: { type: "object", properties: {}, required: [] },
+    async execute() {
+      return director.snapshot();
+    }
+  };
+}
 
 // src/coordination/director.ts
 var DirectorBudgetError = class extends Error {
@@ -7031,242 +7882,6 @@ var Director = class {
     return t2;
   }
 };
-function makeSpawnTool(director, roster) {
-  const inputSchema = {
-    type: "object",
-    properties: {
-      role: {
-        type: "string",
-        description: "Roster role id (preferred). When set, the spawn uses the matching config from the roster and ignores other fields."
-      },
-      name: {
-        type: "string",
-        description: "Display name for the subagent. Required when not using roster."
-      },
-      provider: {
-        type: "string",
-        description: 'Provider id (e.g. "anthropic", "openai"). Defaults to the leader provider when omitted.'
-      },
-      model: {
-        type: "string",
-        description: "Model id within the provider. Defaults to the leader model when omitted."
-      },
-      systemPromptOverride: {
-        type: "string",
-        description: "Extra prompt text appended after the role-base prompt."
-      },
-      maxIterations: { type: "number" },
-      maxToolCalls: { type: "number" },
-      maxCostUsd: { type: "number" }
-    },
-    required: []
-  };
-  return {
-    name: "spawn_subagent",
-    description: "Create a new subagent under this director. Returns the subagent id. Use this when you need a worker with a specific provider, model, or role to handle a piece of the plan.",
-    usageHint: "Either pass `role` (matches the roster) OR pass `name` + optional `provider`/`model`. Returns `{ subagentId }`.",
-    permission: "auto",
-    mutating: false,
-    inputSchema,
-    async execute(input) {
-      const i = input ?? {};
-      const role = typeof i.role === "string" ? i.role : void 0;
-      const base = role && roster ? roster[role] : void 0;
-      if (role && !base) {
-        return {
-          error: `unknown role "${role}". roster has: ${roster ? Object.keys(roster).join(", ") : "(empty)"}`
-        };
-      }
-      const cfg = {
-        ...base ?? { name: i.name ?? "subagent" }
-      };
-      if (typeof i.name === "string") cfg.name = i.name;
-      if (typeof i.provider === "string") cfg.provider = i.provider;
-      if (typeof i.model === "string") cfg.model = i.model;
-      if (typeof i.systemPromptOverride === "string")
-        cfg.systemPromptOverride = i.systemPromptOverride;
-      if (typeof i.maxIterations === "number") cfg.maxIterations = i.maxIterations;
-      if (typeof i.maxToolCalls === "number") cfg.maxToolCalls = i.maxToolCalls;
-      if (typeof i.maxCostUsd === "number") cfg.maxCostUsd = i.maxCostUsd;
-      try {
-        const subagentId = await director.spawn(cfg);
-        return { subagentId, provider: cfg.provider, model: cfg.model, name: cfg.name };
-      } catch (err) {
-        if (err instanceof DirectorBudgetError) {
-          return { error: err.message, kind: err.kind, limit: err.limit, observed: err.observed };
-        }
-        return { error: err instanceof Error ? err.message : String(err) };
-      }
-    }
-  };
-}
-function makeAssignTool(director) {
-  const inputSchema = {
-    type: "object",
-    properties: {
-      subagentId: { type: "string", description: "Target subagent id. Required." },
-      description: {
-        type: "string",
-        description: "The task in natural language \u2014 what you want this subagent to do."
-      },
-      maxToolCalls: { type: "number", description: "Optional per-task tool-call budget override." },
-      timeoutMs: { type: "number", description: "Optional per-task timeout in ms." }
-    },
-    required: ["subagentId", "description"]
-  };
-  return {
-    name: "assign_task",
-    description: "Hand a task to a previously spawned subagent. Returns the task id \u2014 pass it to `await_tasks` to block on completion.",
-    permission: "auto",
-    mutating: false,
-    inputSchema,
-    async execute(input) {
-      const i = input;
-      const task = {
-        id: randomUUID(),
-        description: i.description,
-        subagentId: i.subagentId,
-        maxToolCalls: i.maxToolCalls,
-        timeoutMs: i.timeoutMs
-      };
-      const taskId = await director.assign(task);
-      return { taskId, subagentId: i.subagentId };
-    }
-  };
-}
-function makeAwaitTasksTool(director) {
-  const inputSchema = {
-    type: "object",
-    properties: {
-      taskIds: {
-        type: "array",
-        items: { type: "string" },
-        description: "One or more task ids returned by `assign_task`. The call blocks until every id resolves."
-      }
-    },
-    required: ["taskIds"]
-  };
-  return {
-    name: "await_tasks",
-    description: "Block until every named task completes. Returns the array of TaskResult \u2014 use this to gather subagent output before deciding the next step.",
-    permission: "auto",
-    mutating: false,
-    inputSchema,
-    async execute(input) {
-      const i = input;
-      const results = await director.awaitTasks(i.taskIds);
-      return { results };
-    }
-  };
-}
-function makeAskTool(director) {
-  const inputSchema = {
-    type: "object",
-    properties: {
-      subagentId: {
-        type: "string",
-        description: "Subagent to ask. Must be a previously spawned id."
-      },
-      question: {
-        type: "string",
-        description: "The question or instruction. Sent as the bridge message payload."
-      },
-      timeoutMs: { type: "number", description: "Optional timeout in ms (default 30s)." }
-    },
-    required: ["subagentId", "question"]
-  };
-  return {
-    name: "ask_subagent",
-    description: "Synchronously ask a subagent a question. Blocks until the subagent replies via the bridge (or the timeout fires). Use this when you need a one-shot answer without spawning a fresh task.",
-    permission: "auto",
-    mutating: false,
-    inputSchema,
-    async execute(input) {
-      const i = input;
-      try {
-        const answer = await director.ask(i.subagentId, { question: i.question }, i.timeoutMs);
-        return { ok: true, answer };
-      } catch (err) {
-        return { ok: false, error: err instanceof Error ? err.message : String(err) };
-      }
-    }
-  };
-}
-function makeRollUpTool(director) {
-  const inputSchema = {
-    type: "object",
-    properties: {
-      taskIds: {
-        type: "array",
-        items: { type: "string" },
-        description: "Completed task ids to aggregate. Pass the ids returned by previous `assign_task` calls."
-      },
-      style: {
-        type: "string",
-        enum: ["markdown", "json"],
-        description: "Output flavor \u2014 markdown (default) for in-prompt summarization, json for structured downstream processing."
-      }
-    },
-    required: ["taskIds"]
-  };
-  return {
-    name: "roll_up",
-    description: "Aggregate completed task results into a single formatted summary. Use this after `await_tasks` to fold subagent outputs back into the director's context before deciding the next step.",
-    permission: "auto",
-    mutating: false,
-    inputSchema,
-    async execute(input) {
-      const i = input;
-      const summary = director.rollUp(i.taskIds, i.style ?? "markdown");
-      return { summary, count: i.taskIds.length };
-    }
-  };
-}
-function makeTerminateTool(director) {
-  const inputSchema = {
-    type: "object",
-    properties: {
-      subagentId: { type: "string", description: "Subagent to abort." }
-    },
-    required: ["subagentId"]
-  };
-  return {
-    name: "terminate_subagent",
-    description: 'Forcibly abort a subagent. Use sparingly \u2014 prefer waiting on the natural budget to expire. The current task (if any) ends with status "stopped".',
-    permission: "auto",
-    mutating: true,
-    inputSchema,
-    async execute(input) {
-      const i = input;
-      await director.terminate(i.subagentId);
-      return { ok: true };
-    }
-  };
-}
-function makeFleetStatusTool(director) {
-  return {
-    name: "fleet_status",
-    description: "Snapshot of the fleet \u2014 every subagent's current status, pending vs. completed task counts, and the running total iteration count. Cheap; call freely.",
-    permission: "auto",
-    mutating: false,
-    inputSchema: { type: "object", properties: {}, required: [] },
-    async execute() {
-      return director.status();
-    }
-  };
-}
-function makeFleetUsageTool(director) {
-  return {
-    name: "fleet_usage",
-    description: "Token + cost breakdown across the fleet, per-subagent and totals. Use this to reason about which workers to assign costly tasks to or when to wrap up to stay within budget.",
-    permission: "auto",
-    mutating: false,
-    inputSchema: { type: "object", properties: {}, required: [] },
-    async execute() {
-      return director.snapshot();
-    }
-  };
-}
 function createDelegateTool(opts) {
   const defaultTimeoutMs = opts.defaultTimeoutMs ?? 4 * 60 * 60 * 1e3;
   const rosterIds = opts.roster ? Object.keys(opts.roster) : [];
@@ -9452,13 +10067,13 @@ function roughEstimate(messages) {
 function createContextManagerTool(opts = {}) {
   return {
     name: CONTEXT_MANAGER_TOOL_NAME,
-    description: 'Inspect or reorganize the conversation context window. Use "check" to see token budget. Use "summary" to collapse a message range into a concise note (provide "text" for custom summary). Use "prune" to remove specific messages by index. Use "add_note" to inject a summary note. Use "compact" to run aggressive compaction.',
+    description: 'Inspect or reorganize the conversation context window. Use "check" to see token budget. Use "summary" to collapse a message range into a concise note (provide "text" for custom summary). Use "prune" to remove specific messages by index. Use "add_note" to inject a summary note. Use "compact" to run aggressive compaction. Use "repair" to remove orphan tool_use/tool_result blocks after manual context surgery.',
     inputSchema: {
       type: "object",
       properties: {
         action: {
           type: "string",
-          enum: ["check", "summary", "prune", "add_note", "compact"],
+          enum: ["check", "summary", "prune", "add_note", "compact", "repair"],
           description: "The context operation to perform."
         },
         from: {
@@ -9486,12 +10101,15 @@ function createContextManagerTool(opts = {}) {
       const messages = ctx.messages;
       const beforeTokens = roughEstimate(messages);
       const applyMessages = (next) => {
+        const repaired = repairToolUseAdjacency(next);
+        const finalMessages = repaired.messages;
         if (ctx.state) {
-          ctx.state.replaceMessages(next);
+          ctx.state.replaceMessages(finalMessages);
         } else {
           messages.length = 0;
-          messages.splice(0, 0, ...next);
+          messages.splice(0, 0, ...finalMessages);
         }
+        return repaired.report;
       };
       switch (input.action) {
         case "check": {
@@ -9508,6 +10126,22 @@ function createContextManagerTool(opts = {}) {
             })
           };
         }
+        case "repair": {
+          const repair = applyMessages([...messages]);
+          const afterTokens = roughEstimate(ctx.messages);
+          return {
+            action: "repair",
+            beforeTokens,
+            afterTokens,
+            messageCount: ctx.messages.length,
+            repaired: repair.changed ? {
+              removedToolUses: repair.removedToolUses,
+              removedToolResults: repair.removedToolResults,
+              removedMessages: repair.removedMessages
+            } : void 0,
+            notes: repair.changed ? "Context tool-call adjacency repaired." : "Context tool-call adjacency already valid."
+          };
+        }
         case "compact": {
           if (!opts.compactor) {
             return {
@@ -9518,11 +10152,19 @@ function createContextManagerTool(opts = {}) {
             };
           }
           const report = await opts.compactor.compact(ctx);
+          const repair = applyMessages([...ctx.messages]);
+          const afterTokens = repair.changed ? roughEstimate(ctx.messages) : report.after;
+          const repaired = report.repaired ?? (repair.changed ? repair : void 0);
           return {
             action: "compact",
             beforeTokens,
-            afterTokens: report.after,
-            messageCount: messages.length
+            afterTokens,
+            messageCount: ctx.messages.length,
+            repaired: repaired ? {
+              removedToolUses: repaired.removedToolUses,
+              removedToolResults: repaired.removedToolResults,
+              removedMessages: repaired.removedMessages
+            } : void 0
           };
         }
         case "prune": {
@@ -9538,14 +10180,19 @@ function createContextManagerTool(opts = {}) {
           }
           const copy = [...messages];
           const removed = copy.splice(from, to - from + 1);
-          applyMessages(copy);
-          const afterTokens = roughEstimate(copy);
+          const repair = applyMessages(copy);
+          const afterTokens = roughEstimate(ctx.messages);
           return {
             action: "prune",
             beforeTokens,
             afterTokens,
-            messageCount: copy.length,
-            removedCount: removed.length
+            messageCount: ctx.messages.length,
+            removedCount: removed.length,
+            repaired: repair.changed ? {
+              removedToolUses: repair.removedToolUses,
+              removedToolResults: repair.removedToolResults,
+              removedMessages: repair.removedMessages
+            } : void 0
           };
         }
         case "add_note": {
@@ -9557,14 +10204,19 @@ function createContextManagerTool(opts = {}) {
           };
           const copy = [...messages];
           copy.splice(afterIdx, 0, noteMsg);
-          applyMessages(copy);
-          const afterTokens = roughEstimate(copy);
+          const repair = applyMessages(copy);
+          const afterTokens = roughEstimate(ctx.messages);
           return {
             action: "add_note",
             beforeTokens,
             afterTokens,
-            messageCount: copy.length,
-            summary: noteText
+            messageCount: ctx.messages.length,
+            summary: noteText,
+            repaired: repair.changed ? {
+              removedToolUses: repair.removedToolUses,
+              removedToolResults: repair.removedToolResults,
+              removedMessages: repair.removedMessages
+            } : void 0
           };
         }
         case "summary": {
@@ -9585,14 +10237,19 @@ function createContextManagerTool(opts = {}) {
           };
           const copy = [...messages];
           copy.splice(from, to - from + 1, summaryMsg);
-          applyMessages(copy);
-          const afterTokens = roughEstimate(copy);
+          const repair = applyMessages(copy);
+          const afterTokens = roughEstimate(ctx.messages);
           return {
             action: "summary",
             beforeTokens,
             afterTokens,
-            messageCount: copy.length,
-            summary: summaryText
+            messageCount: ctx.messages.length,
+            summary: summaryText,
+            repaired: repair.changed ? {
+              removedToolUses: repair.removedToolUses,
+              removedToolResults: repair.removedToolResults,
+              removedMessages: repair.removedMessages
+            } : void 0
           };
         }
         default:
@@ -9696,349 +10353,305 @@ var sentinelServer = () => ({
   permission: "deny"
   // security tool — require explicit confirmation
 });
+var zaiVisionServer = () => ({
+  name: "zai-vision",
+  description: "Z.AI Vision MCP \u2014 image analysis and screenshot understanding",
+  transport: "stdio",
+  command: "npx",
+  args: ["-y", "@z_ai/mcp-server@latest"],
+  env: {
+    Z_AI_API_KEY: process.env.Z_AI_API_KEY ?? "",
+    Z_AI_MODE: process.env.Z_AI_MODE ?? "ZAI"
+  },
+  allowedTools: [
+    "image_analysis",
+    "extract_text_from_screenshot",
+    "diagnose_error_screenshot",
+    "understand_technical_diagram",
+    "analyze_data_visualization",
+    "ui_diff_check"
+  ],
+  permission: "auto"
+});
+var miniMaxVisionServer = () => ({
+  name: "minimax-vision",
+  description: "MiniMax MCP \u2014 image understanding via understand_image",
+  transport: "stdio",
+  command: "uvx",
+  args: ["minimax-coding-plan-mcp", "-y"],
+  env: {
+    MINIMAX_API_KEY: process.env.MINIMAX_API_KEY ?? "",
+    MINIMAX_MCP_BASE_PATH: process.env.MINIMAX_MCP_BASE_PATH ?? "./.wrongstack/minimax-output",
+    MINIMAX_API_HOST: process.env.MINIMAX_API_HOST ?? "https://api.minimax.io",
+    MINIMAX_API_RESOURCE_MODE: process.env.MINIMAX_API_RESOURCE_MODE ?? "url"
+  },
+  allowedTools: ["understand_image"],
+  permission: "auto"
+});
 var allServers = () => ({
   filesystem: { ...filesystemServer(), enabled: false },
   github: { ...githubServer(), enabled: false },
-  context7: { ...context7Server(), enabled: false },
-  "brave-search": { ...braveSearchServer(), enabled: false },
-  block: { ...blockServer(), enabled: false },
-  everart: { ...everArtServer(), enabled: false },
-  slack: { ...slackServer(), enabled: false },
-  aws: { ...awsServer(), enabled: false },
-  "google-maps": { ...googleMapsServer(), enabled: false },
-  sentinel: { ...sentinelServer(), enabled: false }
-});
-
-// src/core/iteration-limit.ts
-function requestLimitExtension(opts) {
-  const { events, currentIterations, currentLimit, autoExtend, timeoutMs = 3e4 } = opts;
-  return new Promise((resolve4) => {
-    let resolved = false;
-    const timer = setTimeout(() => {
-      if (!resolved) {
-        resolved = true;
-        resolve4(0);
-      }
-    }, timeoutMs);
-    const deny = () => {
-      if (!resolved) {
-        resolved = true;
-        clearTimeout(timer);
-        resolve4(0);
-      }
+  context7: { ...context7Server(), enabled: false },
+  "brave-search": { ...braveSearchServer(), enabled: false },
+  block: { ...blockServer(), enabled: false },
+  everart: { ...everArtServer(), enabled: false },
+  slack: { ...slackServer(), enabled: false },
+  aws: { ...awsServer(), enabled: false },
+  "google-maps": { ...googleMapsServer(), enabled: false },
+  sentinel: { ...sentinelServer(), enabled: false },
+  "zai-vision": { ...zaiVisionServer(), enabled: false },
+  "minimax-vision": { ...miniMaxVisionServer(), enabled: false }
+});
+
+// src/extension/registry.ts
+var ExtensionRegistry = class {
+  extensions = [];
+  promptContributors = [];
+  log;
+  setLogger(log) {
+    this.log = log;
+  }
+  /**
+   * Register a system prompt contributor. Returns an unregister function.
+   * Contributors are called on every system prompt build in registration
+   * order. Their output blocks are inserted after the core environment
+   * block, before the mode and plan blocks.
+   */
+  registerSystemPromptContributor(c) {
+    this.promptContributors.push(c);
+    return () => {
+      const idx = this.promptContributors.indexOf(c);
+      if (idx >= 0) this.promptContributors.splice(idx, 1);
     };
-    const grant = (extra) => {
-      if (!resolved) {
-        resolved = true;
-        clearTimeout(timer);
-        resolve4(Math.max(0, extra));
+  }
+  /**
+   * Build all registered system prompt contributions.
+   * Failures are caught and logged — one bad contributor doesn't
+   * break the prompt assembly.
+   */
+  async buildSystemPromptContributions(ctx) {
+    const blocks = [];
+    for (const c of this.promptContributors) {
+      try {
+        const contributed = await c(ctx);
+        blocks.push(...contributed);
+      } catch (err) {
+        this.log?.error("SystemPromptContributor failed", err);
       }
-    };
-    events.emit("iteration.limit_reached", {
-      currentIterations,
-      currentLimit,
-      grant,
-      deny
-    });
-    if (autoExtend) {
-      setImmediate(() => {
-        if (!resolved) {
-          resolved = true;
-          clearTimeout(timer);
-          resolve4(100);
-        }
-      });
     }
-  });
-}
-
-// src/core/streaming-response-builder.ts
-function buildResponse(state) {
-  const content = [];
-  for (const b of state.blockOrder) {
-    if (b.kind === "text") {
-      const txt = state.textBuffers[b.idx] ?? "";
-      if (txt) content.push({ type: "text", text: txt });
-    } else if (b.kind === "thinking") {
-      const t2 = state.thinking[b.idx];
-      if (!t2) continue;
-      if (!t2.textBuf && !t2.signature) continue;
-      const block = { type: "thinking", thinking: t2.textBuf };
-      if (t2.signature) block.signature = t2.signature;
-      if (t2.providerMeta && Object.keys(t2.providerMeta).length > 0) {
-        block.providerMeta = t2.providerMeta;
-      }
-      content.push(block);
-    } else {
-      const tb = state.tools.get(b.id);
-      if (tb) {
-        const block = {
-          type: "tool_use",
-          id: b.id,
-          name: tb.name,
-          input: tb.input ?? {}
-        };
-        if (tb.providerMeta && Object.keys(tb.providerMeta).length > 0) {
-          block.providerMeta = tb.providerMeta;
-        }
-        content.push(block);
-      }
+    return blocks;
+  }
+  /**
+   * Returns the live array of contributors (readonly snapshot for
+   * passing to DefaultSystemPromptBuilder at build time).
+   */
+  listSystemPromptContributors() {
+    return this.promptContributors;
+  }
+  /**
+   * Register an extension. Duplicate names are rejected.
+   * Returns an unregister function.
+   */
+  register(ext) {
+    if (this.extensions.some((e) => e.name === ext.name)) {
+      throw new WrongStackError({
+        message: `Extension "${ext.name}" already registered`,
+        code: "REGISTRY_DUPLICATE",
+        subsystem: "container",
+        context: { extension: ext.name }
+      });
     }
+    this.extensions.push(ext);
+    return () => this.unregister(ext.name);
   }
-  if (content.length === 0) content.push({ type: "text", text: "" });
-  return { content, stopReason: state.stopReason, usage: state.usage, model: state.model };
-}
-function createStreamingState(model) {
-  return {
-    model,
-    stopReason: "end_turn",
-    usage: { input: 0, output: 0 },
-    textBuffers: [],
-    currentTextIndex: -1,
-    tools: /* @__PURE__ */ new Map(),
-    thinking: [],
-    currentThinkingIndex: -1,
-    blockOrder: []
-  };
-}
-function handleMessageStart(state, model) {
-  state.model = model;
-}
-function handleContentBlockStart(state, ev) {
-  const kind = ev.kind ?? "text";
-  if (kind === "text") {
-    state.currentTextIndex = state.textBuffers.length;
-    state.textBuffers.push("");
-    state.blockOrder.push({ kind: "text", idx: state.currentTextIndex });
-  } else if (kind === "tool_use") {
-    const id = ev.id ?? crypto.randomUUID();
-    state.tools.set(id, { name: ev.name ?? "unknown", partial: "" });
-    state.blockOrder.push({ kind: "tool", id });
-    state.currentTextIndex = -1;
-  } else if (kind === "thinking") {
-    state.currentThinkingIndex = state.thinking.length;
-    state.thinking.push({
-      textBuf: "",
-      ...ev.providerMeta ? { providerMeta: ev.providerMeta } : {}
-    });
-    state.blockOrder.push({ kind: "thinking", idx: state.currentThinkingIndex });
-    state.currentTextIndex = -1;
+  /**
+   * Register an extension, silently replacing any previous registration
+   * with the same name. Use this when overriding a default extension.
+   */
+  registerOrReplace(ext) {
+    const idx = this.extensions.findIndex((e) => e.name === ext.name);
+    if (idx >= 0) this.extensions.splice(idx, 1);
+    return this.register(ext);
   }
-}
-function handleContentBlockStop(state, ev) {
-}
-function handleTextDelta(state, text) {
-  if (state.currentTextIndex === -1) {
-    state.currentTextIndex = state.textBuffers.length;
-    state.textBuffers.push("");
-    state.blockOrder.push({ kind: "text", idx: state.currentTextIndex });
+  /**
+   * Unregister an extension by name. Returns true if found.
+   */
+  unregister(name) {
+    const idx = this.extensions.findIndex((e) => e.name === name);
+    if (idx === -1) return false;
+    this.extensions.splice(idx, 1);
+    return true;
   }
-  state.textBuffers[state.currentTextIndex] = (state.textBuffers[state.currentTextIndex] ?? "") + text;
-}
-function handleToolUseStart(state, ev) {
-  state.currentTextIndex = -1;
-  state.tools.set(ev.id, { name: ev.name, partial: "" });
-  state.blockOrder.push({ kind: "tool", id: ev.id });
-}
-function handleToolUseInputDelta(state, ev) {
-  const t2 = state.tools.get(ev.id);
-  if (t2) t2.partial += ev.partial;
-}
-function safeJsonOrRaw(s) {
-  if (!s) return {};
-  try {
-    return JSON.parse(s);
-  } catch {
-    return { _raw: s };
+  /**
+   * List registered extension names in order.
+   */
+  list() {
+    return this.extensions.map((e) => e.name);
   }
-}
-function handleToolUseStop(state, ev) {
-  const t2 = state.tools.get(ev.id);
-  if (t2) {
-    t2.input = ev.input !== void 0 ? ev.input : safeJsonOrRaw(t2.partial);
-    if (ev.providerMeta) t2.providerMeta = ev.providerMeta;
+  /**
+   * Check if an extension with the given name is registered.
+   */
+  has(name) {
+    return this.extensions.some((e) => e.name === name);
   }
-  state.currentTextIndex = -1;
-}
-function handleThinkingStart(state, ev) {
-  state.currentThinkingIndex = state.thinking.length;
-  state.thinking.push({
-    textBuf: "",
-    ...ev.providerMeta ? { providerMeta: ev.providerMeta } : {}
-  });
-  state.blockOrder.push({ kind: "thinking", idx: state.currentThinkingIndex });
-  state.currentTextIndex = -1;
-}
-function handleThinkingDelta(state, text) {
-  if (state.currentThinkingIndex === -1) {
-    handleThinkingStart(state, {});
+  /**
+   * Remove all registered extensions and contributors.
+   */
+  clear() {
+    this.extensions.length = 0;
+    this.promptContributors.length = 0;
+  }
+  // ── Hook runners ─────────────────────────────────────────────────
+  async runBeforeRun(...args) {
+    const snapshot = [...this.extensions];
+    for (const ext of snapshot) {
+      if (!ext.beforeRun) continue;
+      try {
+        await ext.beforeRun(...args);
+      } catch (err) {
+        this.log?.error(`Extension "${ext.name}" beforeRun hook failed`, err);
+      }
+    }
   }
-  const t2 = state.thinking[state.currentThinkingIndex];
-  if (t2) t2.textBuf += text;
-}
-function handleThinkingSignature(state, signature) {
-  if (state.currentThinkingIndex === -1) {
-    handleThinkingStart(state, {});
+  async runAfterRun(...args) {
+    const snapshot = [...this.extensions];
+    for (const ext of snapshot) {
+      if (!ext.afterRun) continue;
+      try {
+        await ext.afterRun(...args);
+      } catch (err) {
+        this.log?.error(`Extension "${ext.name}" afterRun hook failed`, err);
+      }
+    }
   }
-  const t2 = state.thinking[state.currentThinkingIndex];
-  if (t2) t2.signature = signature;
-}
-function handleThinkingStop(state) {
-  state.currentThinkingIndex = -1;
-}
-function handleMessageStop(state, ev) {
-  state.stopReason = ev.stopReason ?? "end_turn";
-  state.usage = ev.usage ?? { input: 0, output: 0 };
-}
-async function streamProviderToResponse(provider, req, signal, ctx, events) {
-  const state = createStreamingState(req.model);
-  const iter = provider.stream(req, { signal })[Symbol.asyncIterator]();
-  try {
-    for (; ; ) {
-      const next = await iter.next();
-      if (next.done) break;
-      const ev = next.value;
-      switch (ev.type) {
-        case "message_start":
-          handleMessageStart(state, ev.model);
-          break;
-        case "content_block_start":
-          handleContentBlockStart(state, ev);
-          break;
-        case "content_block_stop":
-          handleContentBlockStop(state, ev);
-          break;
-        case "text_delta":
-          handleTextDelta(state, ev.text);
-          events.emit("provider.text_delta", { ctx, text: ev.text });
-          break;
-        case "tool_use_start":
-          handleToolUseStart(state, ev);
-          events.emit("provider.tool_use_start", { ctx, id: ev.id, name: ev.name });
-          break;
-        case "tool_use_input_delta":
-          handleToolUseInputDelta(state, ev);
-          break;
-        case "tool_use_stop":
-          handleToolUseStop(state, ev);
-          events.emit("provider.tool_use_stop", { ctx, id: ev.id });
-          break;
-        case "thinking_start":
-          handleThinkingStart(state, ev);
-          break;
-        case "thinking_delta":
-          handleThinkingDelta(state, ev.text);
-          events.emit("provider.thinking_delta", { ctx, text: ev.text });
-          break;
-        case "thinking_signature":
-          handleThinkingSignature(state, ev.signature);
-          break;
-        case "thinking_stop":
-          handleThinkingStop(state);
-          break;
-        case "message_stop":
-          handleMessageStop(state, ev);
-          break;
+  async runBeforeIteration(...args) {
+    const snapshot = [...this.extensions];
+    for (const ext of snapshot) {
+      if (!ext.beforeIteration) continue;
+      try {
+        await ext.beforeIteration(...args);
+      } catch (err) {
+        this.log?.error(`Extension "${ext.name}" beforeIteration hook failed`, err);
       }
     }
-  } catch (err) {
-    if (signal.aborted) {
-      state.stopReason = "end_turn";
-      return buildResponse(state);
+  }
+  async runAfterIteration(...args) {
+    const snapshot = [...this.extensions];
+    for (const ext of snapshot) {
+      if (!ext.afterIteration) continue;
+      try {
+        await ext.afterIteration(...args);
+      } catch (err) {
+        this.log?.error(`Extension "${ext.name}" afterIteration hook failed`, err);
+      }
     }
-    throw err;
-  } finally {
-    try {
-      let drainTimer = null;
+  }
+  /**
+   * Run onError hooks in order. The first hook that returns a non-void
+   * result wins; subsequent hooks are skipped.
+   */
+  async runOnError(...args) {
+    const snapshot = [...this.extensions];
+    for (const ext of snapshot) {
+      if (!ext.onError) continue;
       try {
-        await Promise.race([
-          Promise.resolve(iter.return?.()),
-          new Promise((resolve4) => {
-            drainTimer = setTimeout(resolve4, 500);
-          })
-        ]);
-      } finally {
-        if (drainTimer) clearTimeout(drainTimer);
+        const result = await ext.onError(...args);
+        if (result) return result;
+      } catch (err) {
+        this.log?.error(`Extension "${ext.name}" onError hook failed`, err);
       }
-    } catch {
     }
   }
-  return buildResponse(state);
-}
-
-// src/core/provider-runner.ts
-async function runProviderWithRetry(opts) {
-  const { provider, request, signal, ctx, events, retry, logger, tracer } = opts;
-  let attempt = 0;
-  for (; ; ) {
-    const span = tracer?.startSpan("provider.complete", {
-      "provider.id": provider.id,
-      "provider.model": request.model,
-      "provider.streaming": provider.capabilities.streaming,
-      "provider.attempt": attempt
-    });
-    try {
-      const res = provider.capabilities.streaming ? await streamProviderToResponse(provider, request, signal, ctx, events) : await provider.complete(request, { signal });
-      span?.setAttribute("provider.stopReason", res.stopReason);
-      span?.setAttribute("provider.usage_in", res.usage.input);
-      span?.setAttribute("provider.usage_out", res.usage.output);
-      span?.end();
-      return res;
-    } catch (err) {
-      if (err instanceof Error) span?.recordError(err);
-      span?.end();
-      if (signal.aborted) throw err;
-      const isProviderErr = err instanceof ProviderError;
-      const errAsErr = err instanceof Error ? err : new Error(String(err));
-      const canRetry = retry.shouldRetry(isProviderErr ? err : errAsErr, attempt);
-      const description = isProviderErr ? err.describe() : errAsErr.message;
-      if (!canRetry) {
-        if (isProviderErr) {
-          events.emit("provider.error", {
-            providerId: err.providerId,
-            status: err.status,
-            description,
-            retryable: false
-          });
+  /**
+   * Build a composed provider runner. Extensions with `wrapProviderRunner`
+   * form a middleware-style chain: the innermost extension wraps the
+   * default runner, each subsequent wrapper wraps the previous.
+   */
+  wrapProviderRunner(inner) {
+    const wrappers = this.extensions.filter((e) => e.wrapProviderRunner).map((e) => ({ name: e.name, wrap: e.wrapProviderRunner }));
+    if (wrappers.length === 0) return inner;
+    let composed = inner;
+    for (let i = wrappers.length - 1; i >= 0; i--) {
+      const wrapper = wrappers[i];
+      const next = composed;
+      composed = async (ctx, req) => {
+        try {
+          return await wrapper.wrap(ctx, req, next);
+        } catch (err) {
+          this.log?.error(`Extension "${wrapper.name}" wrapProviderRunner failed`, err);
+          throw err;
         }
-        throw err;
+      };
+    }
+    return composed;
+  }
+  async runBeforeToolExecution(...args) {
+    let toolUses = args[1];
+    const snapshot = [...this.extensions];
+    for (const ext of snapshot) {
+      if (!ext.beforeToolExecution) continue;
+      try {
+        toolUses = await ext.beforeToolExecution(args[0], toolUses);
+      } catch (err) {
+        this.log?.error(`Extension "${ext.name}" beforeToolExecution hook failed`, err);
       }
-      const delay = Math.round(retry.delayMs(attempt));
-      const attemptNum = attempt + 1;
-      logger.warn(`Provider retry ${attemptNum} in ${delay}ms \u2014 ${description}`);
-      if (isProviderErr) {
-        events.emit("provider.retry", {
-          providerId: err.providerId,
-          attempt: attemptNum,
-          delayMs: delay,
-          status: err.status,
-          description
-        });
+    }
+    return toolUses;
+  }
+  async runAfterToolExecution(...args) {
+    const snapshot = [...this.extensions];
+    for (const ext of snapshot) {
+      if (!ext.afterToolExecution) continue;
+      try {
+        await ext.afterToolExecution(...args);
+      } catch (err) {
+        this.log?.error(`Extension "${ext.name}" afterToolExecution hook failed`, err);
       }
-      await new Promise((resolve4, reject) => {
-        let settled = false;
-        const onAbort = () => {
-          if (settled) return;
-          settled = true;
-          clearTimeout(t2);
-          reject(new Error("aborted"));
-        };
-        const t2 = setTimeout(() => {
-          if (settled) return;
-          settled = true;
-          clearTimeout(t2);
-          signal.removeEventListener("abort", onAbort);
-          resolve4();
-        }, delay);
-        if (signal.aborted) {
-          onAbort();
-          return;
+    }
+  }
+};
+
+// src/core/iteration-limit.ts
+function requestLimitExtension(opts) {
+  const { events, currentIterations, currentLimit, autoExtend, timeoutMs = 3e4 } = opts;
+  return new Promise((resolve4) => {
+    let resolved = false;
+    const timer = setTimeout(() => {
+      if (!resolved) {
+        resolved = true;
+        resolve4(0);
+      }
+    }, timeoutMs);
+    const deny = () => {
+      if (!resolved) {
+        resolved = true;
+        clearTimeout(timer);
+        resolve4(0);
+      }
+    };
+    const grant = (extra) => {
+      if (!resolved) {
+        resolved = true;
+        clearTimeout(timer);
+        resolve4(Math.max(0, extra));
+      }
+    };
+    events.emit("iteration.limit_reached", {
+      currentIterations,
+      currentLimit,
+      grant,
+      deny
+    });
+    if (autoExtend) {
+      setImmediate(() => {
+        if (!resolved) {
+          resolved = true;
+          clearTimeout(timer);
+          resolve4(100);
         }
-        signal.addEventListener("abort", onAbort, { once: true });
       });
-      attempt++;
     }
-  }
+  });
 }
 
 // src/core/agent.ts
@@ -10075,6 +10688,7 @@ var Agent = class {
   toolExecutor;
   autoExtendLimit;
   tracer;
+  extensions;
   constructor(init) {
     this.container = init.container;
     this.tools = init.tools;
@@ -10088,6 +10702,8 @@ var Agent = class {
     this.perIterationOutputCapBytes = init.perIterationOutputCapBytes ?? 1e5;
     this.autoExtendLimit = init.autoExtendLimit ?? true;
     this.tracer = init.tracer;
+    this.extensions = init.extensions ?? new ExtensionRegistry();
+    this.extensions.setLogger(this.container.resolve(TOKENS.Logger));
     this.toolExecutor = new ToolExecutor(this.tools, {
       permissionPolicy: init.permissionPolicy ?? this.permission,
       secretScrubber: this.scrubber,
@@ -10133,33 +10749,66 @@ var Agent = class {
       "agent.model": opts.model ?? this.ctx.model,
       "agent.executionStrategy": opts.executionStrategy ?? this.executionStrategy
     });
+    const { blocks, text } = normalizeInput(userInput);
+    const inputPayload = { content: blocks, text, ctx: this.ctx };
+    await this.extensions.runBeforeRun(this.ctx, inputPayload);
     try {
-      const result = await this.runInner(userInput, opts, controller);
+      const result = await this.runInner(inputPayload, opts, controller);
       span?.setAttribute("agent.status", result.status);
       span?.setAttribute("agent.iterations", result.iterations);
+      await this.extensions.runAfterRun(this.ctx, result);
       return result;
     } catch (err) {
       const wse = err instanceof AgentError ? err : toWrongStackError(err);
       this.events.emit("error", { err: toError(err), phase: "agent" });
       if (err instanceof Error) span?.recordError(err);
       span?.setAttribute("agent.status", "failed");
-      return {
+      const result = {
         status: signal.aborted ? "aborted" : "failed",
         iterations: 0,
         error: wse
       };
+      await this.extensions.runAfterRun(this.ctx, result);
+      return result;
     } finally {
       span?.end();
       await controller.dispose();
     }
   }
-  async runInner(userInput, opts, controller) {
-    await this.normalizeAndEmitUserInput(userInput);
+  async runInner(inputPayload, opts, controller) {
+    await this.pipelines.userInput.run(inputPayload);
+    this.ctx.state.appendMessage({ role: "user", content: inputPayload.content });
+    await this.ctx.session.append({
+      type: "user_input",
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      content: inputPayload.content
+    });
     let finalText = "";
     let iterations = 0;
     let effectiveLimit = opts.maxIterations ?? this.maxIterations;
     const hasHardLimit = effectiveLimit > 0 && Number.isFinite(effectiveLimit);
     let recoveryRetries = 0;
+    const diRunner = this.container.has(TOKENS.ProviderRunner) ? this.container.resolve(TOKENS.ProviderRunner) : null;
+    const baseRunner = diRunner ? (ctx, req) => diRunner.run({
+      provider: ctx.provider,
+      request: req,
+      signal: controller.signal,
+      ctx,
+      events: this.events,
+      retry: this.retry,
+      logger: this.logger,
+      tracer: this.tracer
+    }) : async (ctx, req) => runProviderWithRetry({
+      provider: ctx.provider,
+      request: req,
+      signal: controller.signal,
+      ctx,
+      events: this.events,
+      retry: this.retry,
+      logger: this.logger,
+      tracer: this.tracer
+    });
+    const customRunner = this.extensions.wrapProviderRunner(baseRunner);
     for (let i = 0; ; i++) {
       iterations = i + 1;
       if (controller.signal.aborted) {
@@ -10175,26 +10824,39 @@ var Agent = class {
       if (limitCheck.exit) {
         return { ...limitCheck.exit, finalText };
       }
+      await this.extensions.runBeforeIteration(this.ctx, i);
       this.events.emit("iteration.started", { ctx: this.ctx, index: i });
       const req = await this.buildAndRunRequestPipeline(opts);
       let res;
       try {
-        res = await runProviderWithRetry({
-          provider: this.ctx.provider,
-          request: req,
-          signal: controller.signal,
-          ctx: this.ctx,
-          events: this.events,
-          retry: this.retry,
-          logger: this.logger,
-          tracer: this.tracer
-        });
+        res = await customRunner(this.ctx, req);
         recoveryRetries = 0;
       } catch (err) {
         if (controller.signal.aborted) {
           this.events.emit("error", { err: toError(err), phase: "provider" });
           return { status: "aborted", iterations, error: toWrongStackError(err, "AGENT_ABORTED") };
         }
+        const extDecision = await this.extensions.runOnError(this.ctx, err, "provider", i);
+        if (extDecision) {
+          if (extDecision.action === "fail") {
+            this.events.emit("error", { err: toError(err), phase: "provider" });
+            return { status: "failed", iterations, error: toWrongStackError(err) };
+          }
+          if (extDecision.action === "continue") {
+            await this.extensions.runAfterIteration(this.ctx, i);
+            continue;
+          }
+          if (extDecision.action === "retry") {
+            recoveryRetries++;
+            if (recoveryRetries > 2) {
+              this.events.emit("error", { err: toError(err), phase: "provider" });
+              return { status: "failed", iterations, error: toWrongStackError(err) };
+            }
+            if (extDecision.model) this.ctx.model = extDecision.model;
+            this.logger.info("Extension requested retry; retrying turn");
+            continue;
+          }
+        }
         const recovered = await this.errorHandler.recover(err, this.ctx);
         if (!recovered || recovered.action === "fail") {
           this.events.emit("error", { err: toError(err), phase: "provider" });
@@ -10233,21 +10895,9 @@ var Agent = class {
       await this.executeTools(toolUses);
       this.events.emit("iteration.completed", { ctx: this.ctx, index: i });
       await this.compactContextIfNeeded();
+      await this.extensions.runAfterIteration(this.ctx, i);
     }
   }
-  /**
-   * Normalize user input and emit through userInput pipeline + session append.
-   */
-  async normalizeAndEmitUserInput(userInput) {
-    const { blocks, text } = normalizeInput(userInput);
-    await this.pipelines.userInput.run({ content: blocks, text, ctx: this.ctx });
-    this.ctx.state.appendMessage({ role: "user", content: blocks });
-    await this.ctx.session.append({
-      type: "user_input",
-      ts: (/* @__PURE__ */ new Date()).toISOString(),
-      content: blocks
-    });
-  }
   /**
    * Check if iteration limit has been reached and request extension if needed.
    * Returns the new effective limit (possibly extended) and a RunResult if
@@ -10275,6 +10925,17 @@ var Agent = class {
    * Build request and run through request pipeline.
    */
   async buildAndRunRequestPipeline(opts) {
+    const repaired = repairToolUseAdjacency(this.ctx.messages);
+    if (repaired.report.changed) {
+      this.ctx.state.replaceMessages(repaired.messages);
+      this.events.emit("context.repaired", {
+        ctx: this.ctx,
+        ...repaired.report
+      });
+      this.logger.warn(
+        `Repaired context tool adjacency: removed ${repaired.report.removedToolUses.length} tool_use block(s), ${repaired.report.removedToolResults.length} tool_result block(s), ${repaired.report.removedMessages} empty message(s)`
+      );
+    }
     const baseReq = {
       model: opts.model ?? this.ctx.model,
       system: this.ctx.systemPrompt,
@@ -10331,12 +10992,13 @@ var Agent = class {
    * single tool.
    */
   async executeTools(toolUses) {
+    const selectedToolUses = await this.extensions.runBeforeToolExecution(this.ctx, toolUses);
     const { outputs } = await this.toolExecutor.executeBatch(
-      toolUses,
+      selectedToolUses,
       this.ctx,
       this.executionStrategy
     );
-    const useById = new Map(toolUses.map((u) => [u.id, u]));
+    const useById = new Map(selectedToolUses.map((u) => [u.id, u]));
     for (const { result, tool, durationMs } of outputs) {
       if (result.type === "tool_confirm_pending") {
         const decision = await this.waitForConfirm({
@@ -10416,6 +11078,7 @@ var Agent = class {
       role: "user",
       content: outputs.map((o) => o.result)
     });
+    await this.extensions.runAfterToolExecution(this.ctx, outputs);
   }
   waitForConfirm(info) {
     return new Promise((resolve4) => {
@@ -10870,6 +11533,15 @@ var DefaultSystemPromptBuilder = class {
         cache_control: { type: "ephemeral" }
       });
     }
+    if (this.opts.contributors && this.opts.contributors.length > 0) {
+      for (const c of this.opts.contributors) {
+        try {
+          const contributed = await c(ctx);
+          blocks.push(...contributed);
+        } catch {
+        }
+      }
+    }
     return blocks;
   }
   /**
@@ -10911,12 +11583,38 @@ var DefaultSystemPromptBuilder = class {
   }
   buildToolUsage(tools) {
     if (tools.length === 0) return "## Tool usage\n\nNo tools registered.";
-    const lines = ["## Tool usage"];
+    const byCat = /* @__PURE__ */ new Map();
+    const uncategorized = [];
     for (const t2 of tools) {
-      const hint = t2.usageHint ?? t2.description;
+      if (t2.category) {
+        let group = byCat.get(t2.category);
+        if (!group) {
+          group = [];
+          byCat.set(t2.category, group);
+        }
+        group.push(t2);
+      } else {
+        uncategorized.push(t2);
+      }
+    }
+    const lines = ["## Tool usage"];
+    for (const [cat, catTools] of byCat) {
       lines.push(`
+### ${cat}`);
+      for (const t2 of catTools) {
+        const hint = t2.usageHint ?? t2.description;
+        const desc = hint.length > 80 ? `${hint.slice(0, 77)}...` : hint.trim();
+        lines.push(`- **${t2.name}** \u2014 ${desc}`);
+      }
+    }
+    if (uncategorized.length > 0) {
+      if (byCat.size > 0) lines.push("");
+      for (const t2 of uncategorized) {
+        const hint = t2.usageHint ?? t2.description;
+        lines.push(`
 ### ${t2.name}
 ${hint.trim()}`);
+      }
     }
     lines.push(`
 ## Common patterns
@@ -11188,6 +11886,21 @@ var ToolRegistry = class {
     this.tools.set(tool.name, { tool, owner });
     return true;
   }
+  /**
+   * Bulk-register multiple tools at once. Each tool that conflicts with an
+   * existing registration is silently skipped — use `registerAllOrThrow`
+   * if you want it to throw on conflicts.
+   */
+  registerAll(tools, owner = "core") {
+    for (const tool of tools) this.tryRegister(tool, owner);
+  }
+  /**
+   * Bulk-register and throw on the first conflict. Use when you need
+   * strict registration (e.g. at boot time).
+   */
+  registerAllOrThrow(tools, owner = "core") {
+    for (const tool of tools) this.register(tool, owner);
+  }
   /**
    * Register a tool as a default. If the tool name is already registered,
    * this is a no-op — the existing registration (from core or another
@@ -11215,6 +11928,30 @@ var ToolRegistry = class {
     }
     this.tools.set(name, { tool, owner });
   }
+  /**
+   * Wrap (decorate) an existing tool. The wrapper receives the current
+   * tool and must return a new tool — typically the same tool with a
+   * wrapped `execute` or `executeStream`. Throws if the tool is not
+   * registered.
+   *
+   * Multiple wraps stack: each wrapper gets the output of the previous.
+   *
+   * @example
+   * registry.wrap('bash', (t) => ({ ...t, permission: 'confirm' }));
+   */
+  wrap(name, wrapper, owner = "core") {
+    const entry = this.tools.get(name);
+    if (!entry) {
+      throw new WrongStackError({
+        message: `Tool "${name}" not registered; cannot wrap`,
+        code: "REGISTRY_NOT_FOUND",
+        subsystem: "container",
+        context: { tool: name }
+      });
+    }
+    const wrapped = wrapper(entry.tool);
+    this.tools.set(name, { tool: wrapped, owner: `${entry.owner}+${owner}` });
+  }
   get(name) {
     return this.tools.get(name)?.tool;
   }
@@ -11224,6 +11961,24 @@ var ToolRegistry = class {
   list() {
     return Array.from(this.tools.values()).map((e) => e.tool);
   }
+  /**
+   * Group tools by their `category` field. Tools without a category
+   * are placed under the key `""` (empty string). Returns a Map of
+   * category → tools, sorted by registration order within each category.
+   */
+  listByCategory() {
+    const map = /* @__PURE__ */ new Map();
+    for (const { tool } of this.tools.values()) {
+      const cat = tool.category ?? "";
+      let group = map.get(cat);
+      if (!group) {
+        group = [];
+        map.set(cat, group);
+      }
+      group.push(tool);
+    }
+    return map;
+  }
   listWithOwner() {
     return Array.from(this.tools.values());
   }
@@ -11243,6 +11998,12 @@ var ProviderRegistry = class {
   register(f) {
     this.factories.set(f.type, f);
   }
+  /**
+   * Bulk-register multiple provider factories at once.
+   */
+  registerAll(factories) {
+    for (const f of factories) this.register(f);
+  }
   /**
    * Override an existing factory. Throws if no factory is registered
    * for the given type. Use this to safely replace a provider at runtime
@@ -11311,6 +12072,12 @@ var SlashCommandRegistry = class {
     }
     return this.cmds.delete(name);
   }
+  /**
+   * Bulk-register multiple slash commands at once.
+   */
+  registerAll(cmds, owner = "core") {
+    for (const cmd of cmds) this.register(cmd, owner);
+  }
   get(name) {
     return this.cmds.get(name)?.cmd;
   }
@@ -11383,15 +12150,23 @@ var DefaultPluginAPI = class {
   providers;
   mcp;
   slashCommands;
+  extensions;
+  session;
+  metrics;
   config;
   log;
+  configStore;
   pluginCleanupFns = [];
   constructor(init) {
     const owner = init.ownerName;
     this.container = init.container;
     this.events = init.events;
     this.config = init.config;
+    this.configStore = init.configStore;
     this.log = init.log.child({ plugin: owner });
+    this.extensions = init.extensions ?? new ExtensionRegistry();
+    this.session = init.sessionWriter ?? noopSession;
+    this.metrics = init.metricsSink ? scopedMetrics(init.metricsSink, owner) : noopMetrics;
     const pipelines = init.pipelines;
     const readonlyPipelines = {};
     for (const [key, pipeline] of Object.entries(pipelines)) {
@@ -11402,6 +12177,7 @@ var DefaultPluginAPI = class {
     this.tools = {
       register: (t2) => tr.register(t2, owner),
       unregister: (name) => tr.unregister(name),
+      wrap: (name, wrapper) => tr.wrap(name, wrapper, owner),
       get: (name) => tr.get(name),
       list: () => tr.list()
     };
@@ -11421,10 +12197,23 @@ var DefaultPluginAPI = class {
     } : noopSlashCommands;
   }
   onEvent(event, handler) {
-    const off = this.events.once(event, handler);
+    const off = this.events.on(event, handler);
     this.pluginCleanupFns.push(off);
     return off;
   }
+  onPattern(pattern, handler) {
+    const off = this.events.onPattern(pattern, handler);
+    this.pluginCleanupFns.push(off);
+    return off;
+  }
+  emitCustom(event, payload) {
+    this.events.emit(event, payload);
+  }
+  onConfigChange(handler) {
+    if (!this.configStore) return () => {
+    };
+    return this.configStore.watch(handler);
+  }
   /** Called by the plugin loader when uninstalling the plugin. */
   drainCleanup() {
     for (const fn of this.pluginCleanupFns.splice(0)) {
@@ -11434,6 +12223,9 @@ var DefaultPluginAPI = class {
       }
     }
   }
+  registerSystemPromptContributor(c) {
+    return this.extensions.registerSystemPromptContributor(c);
+  }
 };
 var noopMcp = {
   start: async () => void 0,
@@ -11454,8 +12246,35 @@ var noopSlashCommands = {
     return [];
   }
 };
+var noopSession = {
+  append: async () => {
+  }
+};
+var noopMetrics = {
+  counter() {
+  },
+  histogram() {
+  },
+  gauge() {
+  }
+};
+function scopedMetrics(sink, pluginName) {
+  const prefix = `plugin.${pluginName}.`;
+  return {
+    counter(name, value, labels) {
+      sink.counter(`${prefix}${name}`, value, labels);
+    },
+    histogram(name, value, labels) {
+      sink.histogram(`${prefix}${name}`, value, labels);
+    },
+    gauge(name, value, labels) {
+      sink.gauge(`${prefix}${name}`, value, labels);
+    }
+  };
+}
 
 // src/plugin/loader.ts
+var pluginApiMap = /* @__PURE__ */ new WeakMap();
 var KERNEL_API_VERSION = "0.1.10";
 function parseSemver(v) {
   const parts = v.replace(/^[^0-9]*/, "").split(".").map((s) => Number.parseInt(s, 10) || 0);
@@ -11479,6 +12298,16 @@ function satisfies(range, version) {
 function normalizeDep(d) {
   return typeof d === "string" ? { name: d } : d;
 }
+function shallowMerge(defaults, overrides) {
+  if (overrides === void 0 || overrides === null) return { ...defaults };
+  if (typeof overrides !== "object") return { ...defaults };
+  const ov = overrides;
+  const out = { ...defaults };
+  for (const key of Object.keys(ov)) {
+    out[key] = ov[key];
+  }
+  return out;
+}
 function topoSort(plugins) {
   const map = /* @__PURE__ */ new Map();
   for (const p of plugins) map.set(p.name, p);
@@ -11574,6 +12403,11 @@ async function loadPlugins(plugins, opts) {
       failed.push({ plugin, err });
       continue;
     }
+    if (plugin.defaultConfig && opts.pluginOptions) {
+      const userOpts = opts.pluginOptions[plugin.name];
+      const merged = shallowMerge(plugin.defaultConfig, userOpts);
+      opts.pluginOptions[plugin.name] = merged;
+    }
     if (plugin.configSchema && opts.pluginOptions) {
       const pluginOpts = opts.pluginOptions[plugin.name];
       if (pluginOpts !== void 0) {
@@ -11595,8 +12429,9 @@ async function loadPlugins(plugins, opts) {
     }
     try {
       const rawApi = opts.apiFactory(plugin);
-      const api = plugin.capabilities ? wrapApiForCapabilityCheck(plugin, rawApi, opts.log) : rawApi;
+      const api = plugin.capabilities ? wrapApiForCapabilityCheck(plugin, rawApi, opts.log, opts.enforceCapabilities) : rawApi;
       await plugin.setup(api);
+      pluginApiMap.set(plugin, api);
       loaded.push(plugin);
       opts.log.info(`Plugin "${plugin.name}" loaded`);
     } catch (err) {
@@ -11611,18 +12446,27 @@ async function unloadPlugins(loadedPlugins, opts) {
   for (const plugin of ordered) {
     if (typeof plugin.teardown !== "function") continue;
     try {
-      const api = opts.apiFactory(plugin);
+      const api = pluginApiMap.get(plugin) ?? opts.apiFactory(plugin);
       await plugin.teardown(api);
+      pluginApiMap.delete(plugin);
       opts.log.info(`Plugin "${plugin.name}" torn down`);
     } catch (err) {
       opts.log.error(`Plugin "${plugin.name}" teardown failed`, err);
     }
   }
 }
-function wrapApiForCapabilityCheck(plugin, api, log) {
+function wrapApiForCapabilityCheck(plugin, api, log, enforce = false) {
   const caps = plugin.capabilities ?? {};
-  const warn = (subsystem, detail) => {
+  const violate = (subsystem, detail) => {
     const msg = `Plugin "${plugin.name}" used ${subsystem} without declaring capabilities.${subsystem} \u2014 ${detail}`;
+    if (enforce) {
+      throw new PluginError({
+        message: msg,
+        code: "PLUGIN_LOAD_FAILED",
+        pluginName: plugin.name,
+        context: { subsystem, detail }
+      });
+    }
     if (typeof log.warn === "function") log.warn(msg);
     else log.error(msg);
   };
@@ -11630,7 +12474,7 @@ function wrapApiForCapabilityCheck(plugin, api, log) {
     get(target, prop, receiver) {
       if (prop === "register") {
         return (t2) => {
-          warn("tools", `register(${t2?.name ?? "<unknown>"})`);
+          violate("tools", `register(${t2?.name ?? "<unknown>"})`);
           return target.register(t2);
         };
       }
@@ -11641,7 +12485,7 @@ function wrapApiForCapabilityCheck(plugin, api, log) {
     get(target, prop, receiver) {
       if (prop === "register") {
         return (f) => {
-          warn("providers", `register(${f?.type ?? "<unknown>"})`);
+          violate("providers", `register(${f?.type ?? "<unknown>"})`);
           return target.register(f);
         };
       }
@@ -11652,7 +12496,10 @@ function wrapApiForCapabilityCheck(plugin, api, log) {
     get(target, prop, receiver) {
       if (prop === "register") {
         return (c) => {
-          warn("slashCommands", `register(${c?.name ?? "<unknown>"})`);
+          violate(
+            "slashCommands",
+            `register(${c?.name ?? "<unknown>"})`
+          );
           return target.register(c);
         };
       }
@@ -11663,7 +12510,7 @@ function wrapApiForCapabilityCheck(plugin, api, log) {
     get(target, prop, receiver) {
       if (prop === "start") {
         return (cfg) => {
-          warn("mcp", `start(${cfg?.name ?? "<unknown>"})`);
+          violate("mcp", `start(${cfg?.name ?? "<unknown>"})`);
           return target.start(cfg);
         };
       }
@@ -11688,6 +12535,6 @@ function wrapApiForCapabilityCheck(plugin, api, log) {
   });
 }
 
-export { ALL_FLEET_AGENTS, AUDIT_LOG_AGENT, Agent, AgentError, AutoApprovePermissionPolicy, AutoCompactionMiddleware, AutonomousRunner, BUG_HUNTER_AGENT, BudgetExceededError, ConfigError, ConfigMigrationError, Container, Context, ConversationState, DEFAULT_CONFIG_MIGRATIONS, DEFAULT_DIRECTOR_PREAMBLE, DEFAULT_MAX_ITERATIONS, DEFAULT_MODES, DEFAULT_RECOVERY_STRATEGIES, DEFAULT_SPEC_TEMPLATE, DEFAULT_SUBAGENT_BASELINE, DefaultAttachmentStore, DefaultConfigLoader, DefaultConfigStore, DefaultErrorHandler, DefaultHealthRegistry, DefaultLogger, DefaultMemoryStore, DefaultModeStore, DefaultModelsRegistry, DefaultMultiAgentCoordinator, DefaultPathResolver, DefaultPermissionPolicy, DefaultPluginAPI, DefaultRetryPolicy, DefaultSecretScrubber, DefaultSecretVault, DefaultSessionReader, DefaultSessionStore, DefaultSkillLoader, DefaultSystemPromptBuilder, DefaultTaskStore, DefaultTokenCounter, Director, DirectorBudgetError, DirectorStateCheckpoint, DoneConditionChecker, EventBus, FLEET_ROSTER, FleetBus, FleetUsageAggregator, HybridCompactor, InMemoryAgentBridge, InMemoryBridgeTransport, InMemoryMetricsSink, InputBuilder, IntelligentCompactor, KERNEL_API_VERSION, LAYER_1_IDENTITY, LLMSelector, NoopMetricsSink, NoopTracer, OTelTracer, PROMETHEUS_CONTENT_TYPE, Pipeline, PluginError, ProviderError, ProviderRegistry, QueueStore, REFACTOR_PLANNER_AGENT, RecoveryLock, RunController, SECURITY_SCANNER_AGENT, SelectiveCompactor, SessionAnalyzer, SessionError, SlashCommandRegistry, SpecDrivenDev, SpecParser, SubagentBudget, TOKENS, TaskFlow, TaskGenerator, TaskTracker, ToolError, ToolExecutor, ToolRegistry, WrongStackError, addPlanItem, allServers, asBlocks, asText, atomicWrite, attachPlanCheckpoint, attachTodosCheckpoint, awsServer, blockServer, braveSearchServer, buildChildEnv, buildOtlpMetricsRequest, buildOtlpTracesRequest, buildRecoveryStrategies, classifyFamily, clearPlan, color, compileGlob, composeDirectorPrompt, composeSubagentPrompt, computeTaskProgress, context7Server, contextManagerTool, createContextManagerTool, createDefaultPipelines, createDelegateTool, createMessage, createToolOutputSerializer, decryptConfigSecrets, detectNewlineStyle, emptyPlan, encryptConfigSecrets, ensureDir, estimateTextTokens, estimateToolInputTokens, estimateToolResultTokens, everArtServer, extractRunEnv, filesystemServer, findCriticalPath, formatPlan, formatTodosList, githubServer, googleMapsServer, isAgentError, isConfigError, isImageBlock, isPluginError, isSessionError, isTextBlock, isThinkingBlock, isToolError, isToolResultBlock, isToolUseBlock, isWrongStackError, loadDirectorState, loadPlan, loadPlugins, loadProjectModes, loadTodosCheckpoint, loadUserModes, makeAgentSubagentRunner, makeDirectorSessionFactory, matchAny, matchGlob, migratePlaintextSecrets, normalizeToLf, projectHash, removePlanItem, renderPrometheus, resolveWstackPaths, rewriteConfigEncrypted, rosterSummaryFromConfigs, runConfigMigrations, safeParse, safeStringify, sanitizeJsonString, savePlan, saveTodosCheckpoint, sentinelServer, setPlanItemStatus, slackServer, startMetricsServer, startOtlpMetricsExporter, startOtlpTraceExporter, stripAnsi, toStyle, toWrongStackError, topologicalSort, unifiedDiff, unloadPlugins, validateAgainstSchema, wireMetricsToEvents, wrapAsState };
+export { ALL_FLEET_AGENTS, AUDIT_LOG_AGENT, Agent, AgentError, AutoApprovePermissionPolicy, AutoCompactionMiddleware, AutonomousRunner, BUG_HUNTER_AGENT, BudgetExceededError, CONTEXT_WINDOW_MODES, ConfigError, ConfigMigrationError, Container, Context, ConversationState, DEFAULT_CONFIG_MIGRATIONS, DEFAULT_CONTEXT_WINDOW_MODE_ID, DEFAULT_DIRECTOR_PREAMBLE, DEFAULT_MAX_ITERATIONS, DEFAULT_MODES, DEFAULT_RECOVERY_STRATEGIES, DEFAULT_SPEC_TEMPLATE, DEFAULT_SUBAGENT_BASELINE, DefaultAttachmentStore, DefaultConfigLoader, DefaultConfigStore, DefaultErrorHandler, DefaultHealthRegistry, DefaultLogger, DefaultMemoryStore, DefaultModeStore, DefaultModelsRegistry, DefaultMultiAgentCoordinator, DefaultPathResolver, DefaultPermissionPolicy, DefaultPluginAPI, DefaultProviderRunner, DefaultRetryPolicy, DefaultSecretScrubber, DefaultSecretVault, DefaultSessionReader, DefaultSessionStore, DefaultSkillLoader, DefaultSystemPromptBuilder, DefaultTaskStore, DefaultTokenCounter, Director, DirectorBudgetError, DirectorStateCheckpoint, DoneConditionChecker, EventBus, ExtensionRegistry, FLEET_ROSTER, FleetBus, FleetUsageAggregator, HybridCompactor, InMemoryAgentBridge, InMemoryBridgeTransport, InMemoryMetricsSink, InputBuilder, IntelligentCompactor, KERNEL_API_VERSION, LAYER_1_IDENTITY, LLMSelector, NoopMetricsSink, NoopTracer, OTelTracer, PROMETHEUS_CONTENT_TYPE, Pipeline, PluginError, ProviderError, ProviderRegistry, QueueStore, REFACTOR_PLANNER_AGENT, RecoveryLock, RunController, SECURITY_SCANNER_AGENT, SelectiveCompactor, SessionAnalyzer, SessionError, SlashCommandRegistry, SpecDrivenDev, SpecParser, SubagentBudget, TOKENS, TaskFlow, TaskGenerator, TaskTracker, ToolError, ToolExecutor, ToolRegistry, WrongStackError, addPlanItem, allServers, asBlocks, asText, atomicWrite, attachPlanCheckpoint, attachTodosCheckpoint, awsServer, blockServer, braveSearchServer, buildChildEnv, buildOtlpMetricsRequest, buildOtlpTracesRequest, buildRecoveryStrategies, classifyFamily, clearPlan, color, compileGlob, composeDirectorPrompt, composeSubagentPrompt, computeTaskProgress, context7Server, contextManagerTool, createContextManagerTool, createDefaultPipelines, createDelegateTool, createMessage, createToolOutputSerializer, decryptConfigSecrets, detectNewlineStyle, emptyPlan, encryptConfigSecrets, ensureDir, estimateTextTokens, estimateToolInputTokens, estimateToolResultTokens, everArtServer, extractRunEnv, filesystemServer, findCriticalPath, formatContextWindowModeList, formatPlan, formatTodosList, getContextWindowMode, githubServer, googleMapsServer, isAgentError, isConfigError, isContextWindowModeId, isImageBlock, isPluginError, isSessionError, isTextBlock, isThinkingBlock, isToolError, isToolResultBlock, isToolUseBlock, isWrongStackError, listContextWindowModes, loadDirectorState, loadPlan, loadPlugins, loadProjectModes, loadTodosCheckpoint, loadUserModes, makeAgentSubagentRunner, makeDirectorSessionFactory, matchAny, matchGlob, migratePlaintextSecrets, miniMaxVisionServer, normalizeToLf, projectHash, removePlanItem, renderPrometheus, repairToolUseAdjacency, resolveContextWindowPolicy, resolveWstackPaths, rewriteConfigEncrypted, rosterSummaryFromConfigs, runConfigMigrations, safeParse, safeStringify, sanitizeJsonString, savePlan, saveTodosCheckpoint, sentinelServer, setPlanItemStatus, slackServer, startMetricsServer, startOtlpMetricsExporter, startOtlpTraceExporter, stripAnsi, toStyle, toWrongStackError, topologicalSort, unifiedDiff, unloadPlugins, validateAgainstSchema, wireMetricsToEvents, wrapAsState, zaiVisionServer };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map