@osama.ansar/agent-loopguard 0.1.0 → 0.2.0

package/dist/index.js

@@ -36,8 +36,18 @@ var BudgetDetector = class {
   startedAt;
   lastUsed = zeroUsed();
   observe(_record, ctx) {
-    const recorded = this.recorded(ctx);
+    const recorded = this.recorded(ctx.totals);
     this.lastUsed = recorded;
+    return this.evaluate(recorded);
+  }
+  /**
+   * Where the totals stand right now, without recording anything: the stop verdict if a limit has
+   * already been reached, and any warnings. Reads the clock when a duration limit exists.
+   */
+  peek(totals) {
+    return this.evaluate(this.recorded(totals));
+  }
+  evaluate(recorded) {
     const used = this.withWallClock(recorded);
     let stop;
     const warnings = [];
@@ -72,13 +82,13 @@ var BudgetDetector = class {
     if (warnings.length > 0) result.warnings = warnings;
     return result;
   }
-  recorded(ctx) {
+  recorded(totals) {
     return {
-      totalTokens: ctx.totals.totalTokens,
-      inputTokens: ctx.totals.inputTokens,
-      outputTokens: ctx.totals.outputTokens,
-      costUsd: ctx.totals.costUsd,
-      durationMs: ctx.totals.durationMs
+      totalTokens: totals.totalTokens,
+      inputTokens: totals.inputTokens,
+      outputTokens: totals.outputTokens,
+      costUsd: totals.costUsd,
+      durationMs: totals.durationMs
     };
   }
   withWallClock(recorded) {
@@ -87,6 +97,21 @@ var BudgetDetector = class {
     if (!Number.isFinite(elapsed) || elapsed <= recorded.durationMs) return recorded;
     return { ...recorded, durationMs: elapsed };
   }
+  /** The resolved limits, for the snapshot fingerprint. */
+  config() {
+    return this.limits.map(({ metric, limit, warnAt }) => ({ metric, limit, warnAt: warnAt ?? null }));
+  }
+  /** Wall-clock time since the run started, or `null` when no duration limit makes it matter. */
+  elapsedMs() {
+    if (!this.limits.some((l) => l.metric === "durationMs")) return null;
+    const elapsed = this.now() - this.startedAt;
+    return Number.isFinite(elapsed) && elapsed > 0 ? elapsed : 0;
+  }
+  /** Continue a run whose totals were `totals` and which had been running for `elapsedMs`. */
+  restore(totals, elapsedMs) {
+    this.lastUsed = this.recorded(totals);
+    this.startedAt = this.now() - (elapsedMs ?? 0);
+  }
   state() {
     const limits = {};
     for (const l of this.limits) limits[l.metric] = l.limit;
@@ -319,17 +344,17 @@ function buildCall(raw) {
   const error = get(raw, "error");
   const result = get(raw, "result");
   const failed = error !== void 0 && error !== null;
-  const callSig = `${JSON.stringify(name)}(${args.signature})`;
+  const callSig = hashString(`${JSON.stringify(name)}(${args.signature})`);
   let resultSig;
-  if (failed) resultSig = `error:${describe(error).signature}`;
-  else if (result !== void 0) resultSig = `ok:${describe(result).signature}`;
+  if (failed) resultSig = hashString(`error:${describe(error).signature}`);
+  else if (result !== void 0) resultSig = hashString(`ok:${describe(result).signature}`);
   return {
     name,
     label: `${name}(${args.preview})`,
     callSig,
     resultSig,
     // With no result supplied the call itself stands in as "the evidence".
-    outcomeSig: resultSig === void 0 ? callSig : `${callSig}=>${resultSig}`,
+    outcomeSig: resultSig === void 0 ? callSig : hashString(`${callSig}=>${resultSig}`),
     failed,
     argsPreview: args.preview
   };
@@ -347,6 +372,19 @@ function buildCalls(step) {
   }
   return calls;
 }
+function buildPendingCalls(input) {
+  const raw = isArray(input) ? input : [input];
+  const calls = [];
+  try {
+    for (const item of raw) {
+      if (!isObject(item)) continue;
+      const call = buildCall({ name: get(item, "name"), args: get(item, "args") });
+      if (call !== void 0) calls.push(call);
+    }
+  } catch {
+  }
+  return calls;
+}
 function buildRecord(step, index) {
   const s = isObject(step) ? step : {};
   const rawUsage = get(s, "usage");
@@ -374,6 +412,67 @@ function buildRecord(step, index) {
   };
 }
 
+// src/snapshot.ts
+var SNAPSHOT_VERSION = 1;
+var MAX_NAME_LENGTH = 256;
+var MAX_LABEL_LENGTH = 1024;
+var MAX_PREVIEW_LENGTH = 128;
+var MAX_FINISH_REASON_LENGTH = 256;
+var REDACTED = "[redacted]";
+var HASH = /^[0-9a-f]{28}$/;
+function fail(path, problem) {
+  throw new TypeError(`agent-loopguard: invalid snapshot: ${path} ${problem}`);
+}
+function clip(text, max) {
+  return text.length <= max ? text : text.slice(0, max);
+}
+function fingerprint(config) {
+  return hashString(canonicalize(config));
+}
+function asRecord(value, path) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) fail(path, "must be an object");
+  return value;
+}
+function field(obj, key, path) {
+  if (!Object.prototype.hasOwnProperty.call(obj, key)) fail(`${path}.${key}`, "is missing");
+  return obj[key];
+}
+function asInt(value, path) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+    fail(path, `must be a non-negative integer, got ${String(value)}`);
+  }
+  return value;
+}
+function asAmount(value, path) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    fail(path, `must be a finite number >= 0, got ${String(value)}`);
+  }
+  return value;
+}
+function asString(value, path, maxLength) {
+  if (typeof value !== "string") fail(path, "must be a string");
+  if (value.length > maxLength) fail(path, `must be at most ${maxLength} characters`);
+  return value;
+}
+function asHash(value, path) {
+  if (typeof value !== "string" || !HASH.test(value)) fail(path, "must be a 28-character hex hash");
+  return value;
+}
+function asList(value, path, maxLength) {
+  if (!Array.isArray(value)) fail(path, "must be an array");
+  if (value.length > maxLength) fail(path, `must have at most ${maxLength} entries`);
+  return Array.from(value);
+}
+function asNullable(value, read) {
+  return value === null ? null : read(value);
+}
+function section(detectors, key, enabled) {
+  const value = field(detectors, key, "detectors");
+  if (enabled && value === null) fail(`detectors.${key}`, "is null, but that detector is enabled in the options");
+  if (!enabled && value !== null) fail(`detectors.${key}`, "has state, but that detector is disabled in the options");
+  return value;
+}
+
 // src/detectors/finishReason.ts
 var DEFAULT_TERMINAL_FINISH_REASONS = ["stop", "length", "content-filter", "error"];
 var OTHER_POLICIES = ["stop", "continue", "stop-if-text-only"];
@@ -444,6 +543,21 @@ var FinishReasonDetector = class {
   state() {
     return { lastFinishReason: this.last };
   }
+  /** The resolved options, for the snapshot fingerprint. */
+  config() {
+    return { terminal: [...this.terminal].sort(), otherPolicy: this.otherPolicy };
+  }
+  snapshot() {
+    return { lastFinishReason: this.last === null ? null : clip(this.last, MAX_FINISH_REASON_LENGTH) };
+  }
+  restore(raw) {
+    const path = "detectors.finishReason";
+    const state = asRecord(raw, path);
+    this.last = asNullable(
+      field(state, "lastFinishReason", path),
+      (v) => asString(v, `${path}.lastFinishReason`, MAX_FINISH_REASON_LENGTH)
+    );
+  }
   reset() {
     this.last = null;
   }
@@ -477,6 +591,25 @@ var MaxStepsDetector = class {
       }
     };
   }
+  /** What a call made now would run into: the verdict if the limit has already been reached. */
+  peek() {
+    if (this.steps < this.limit) return void 0;
+    return {
+      stop: true,
+      reason: "max-steps",
+      code: "MAX_STEPS",
+      detail: `The limit of ${this.limit} steps has already been reached.`,
+      evidence: { steps: this.steps, limit: this.limit }
+    };
+  }
+  /** The resolved options, for the snapshot fingerprint. */
+  config() {
+    return { limit: this.limit };
+  }
+  /** Continue from a run that had already recorded `steps` steps. */
+  restore(steps) {
+    this.steps = steps;
+  }
   remaining() {
     return Math.max(0, this.limit - this.steps);
   }
@@ -486,11 +619,16 @@ var MaxStepsDetector = class {
 };
 
 // src/detectors/noProgress.ts
+var MAX_REMEMBERED_OUTCOMES = 1024;
+var PREVIEW_LIMIT2 = 80;
 var NoProgressDetector = class {
   threshold;
   seen = /* @__PURE__ */ new Set();
   streak = 0;
-  streakText = "";
+  /** Hash of the normalised text the current streak shares. */
+  streakKey = "";
+  /** Shortened text of the current streak, for messages. Empty exactly when the text is empty. */
+  streakPreview = "";
   constructor(options = {}) {
     this.threshold = assertInteger("noProgress.threshold", options.threshold ?? 3, 2);
   }
@@ -499,61 +637,100 @@ var NoProgressDetector = class {
     for (const call of record.calls) {
       if (!this.seen.has(call.outcomeSig)) {
         hasNew = true;
-        this.seen.add(call.outcomeSig);
+        this.remember(call.outcomeSig);
       }
     }
+    const textKey = hashString(record.text);
     if (hasNew) {
       this.streak = 0;
-    } else if (this.streak > 0 && record.text === this.streakText) {
+    } else if (this.streak > 0 && textKey === this.streakKey) {
       this.streak += 1;
     } else {
       this.streak = 1;
-      this.streakText = record.text;
+      this.streakKey = textKey;
+      this.streakPreview = truncate(record.text, PREVIEW_LIMIT2);
     }
     if (this.streak < this.threshold) return void 0;
-    const preview = truncate(this.streakText, 80);
+    const preview = this.streakPreview;
     return {
       stop: {
         stop: true,
         reason: "no-progress",
         code: "NO_PROGRESS",
-        detail: this.streakText === "" ? `No progress: ${this.streak} consecutive steps produced no new tool results and no text.` : `No progress: ${this.streak} consecutive steps repeated the same text and produced no new tool results ("${preview}").`,
+        detail: preview === "" ? `No progress: ${this.streak} consecutive steps produced no new tool results and no text.` : `No progress: ${this.streak} consecutive steps repeated the same text and produced no new tool results ("${preview}").`,
         evidence: { steps: this.streak, threshold: this.threshold, textPreview: preview }
       }
     };
   }
+  remember(outcome) {
+    this.seen.add(outcome);
+    if (this.seen.size > MAX_REMEMBERED_OUTCOMES) {
+      for (const oldest of this.seen) {
+        this.seen.delete(oldest);
+        break;
+      }
+    }
+  }
+  /** The resolved options, for the snapshot fingerprint. */
+  config() {
+    return { threshold: this.threshold };
+  }
+  snapshot(redact) {
+    const idle = this.streak === 0;
+    const preview = redact && this.streakPreview !== "" ? REDACTED : clip(this.streakPreview, MAX_PREVIEW_LENGTH);
+    return {
+      seen: [...this.seen],
+      streak: this.streak,
+      textKey: idle ? null : this.streakKey,
+      textPreview: idle ? "" : preview
+    };
+  }
+  restore(raw) {
+    const path = "detectors.noProgress";
+    const state = asRecord(raw, path);
+    const seen = asList(field(state, "seen", path), `${path}.seen`, MAX_REMEMBERED_OUTCOMES).map(
+      (v, i) => asHash(v, `${path}.seen[${i}]`)
+    );
+    const streak = asInt(field(state, "streak", path), `${path}.streak`);
+    const textKey = asNullable(field(state, "textKey", path), (v) => asHash(v, `${path}.textKey`));
+    const textPreview = asString(field(state, "textPreview", path), `${path}.textPreview`, MAX_PREVIEW_LENGTH);
+    const outcomes = new Set(seen);
+    if (outcomes.size !== seen.length) fail(`${path}.seen`, "must not repeat an outcome");
+    if (streak === 0 ? textKey !== null || textPreview !== "" : textKey === null) {
+      fail(path, "has a streak and a text that disagree");
+    }
+    this.seen = outcomes;
+    this.streak = streak;
+    this.streakKey = textKey ?? "";
+    this.streakPreview = textPreview;
+  }
   state() {
     return { threshold: this.threshold, streak: this.streak };
   }
   reset() {
     this.seen.clear();
     this.streak = 0;
-    this.streakText = "";
+    this.streakKey = "";
+    this.streakPreview = "";
   }
 };
 
 // src/detectors/oscillation.ts
-var WINDOW = 4096;
 var OscillationDetector = class {
   maxPeriod;
   repeats;
-  sigs = [];
-  labels = [];
+  ring;
   current = null;
   constructor(options = {}) {
     this.maxPeriod = assertInteger("oscillation.maxPeriod", options.maxPeriod ?? 3, 2);
     this.repeats = assertInteger("oscillation.repeats", options.repeats ?? 3, 2);
+    this.ring = this.emptyRing();
   }
   observe(record) {
     let found;
     for (const call of record.calls) {
-      this.sigs.push(call.callSig);
-      this.labels.push(call.label);
-      if (this.sigs.length > WINDOW) {
-        this.sigs.splice(0, WINDOW / 2);
-        this.labels.splice(0, WINDOW / 2);
-      }
-      found = this.detect() ?? found;
+      this.push(this.ring, call);
+      found = this.detect(this.ring) ?? found;
     }
     this.current = found ? { period: found.period, repeats: found.repeats } : null;
     if (!found) return void 0;
@@ -567,56 +744,153 @@ var OscillationDetector = class {
       }
     };
   }
+  /**
+   * What `observe` would report if these calls (not yet made) were the next ones, without recording
+   * them. Results are not part of the rule, so nothing is lost by not having them yet.
+   */
+  peek(calls) {
+    const ring = {
+      sigs: [...this.ring.sigs],
+      labels: [...this.ring.labels],
+      names: [...this.ring.names],
+      matches: [...this.ring.matches]
+    };
+    let found;
+    for (const call of calls) {
+      this.push(ring, call);
+      found = this.detect(ring) ?? found;
+    }
+    if (found === void 0) return void 0;
+    return {
+      stop: true,
+      reason: "oscillation",
+      code: "OSCILLATION",
+      detail: `Calling now would complete a cycle of ${found.period} calls (${found.cycle.join(" -> ")}) repeated ${found.repeats} times in a row.`,
+      evidence: found
+    };
+  }
+  emptyRing() {
+    return { sigs: [], labels: [], names: [], matches: new Array(this.maxPeriod - 1).fill(0) };
+  }
+  push(ring, call) {
+    const n = ring.sigs.length;
+    for (let period = 2; period <= this.maxPeriod; period += 1) {
+      const slot = period - 2;
+      const matched = n >= period && call.callSig === ring.sigs[n - period];
+      ring.matches[slot] = matched ? ring.matches[slot] + 1 : 0;
+    }
+    ring.sigs.push(call.callSig);
+    ring.labels.push(call.label);
+    ring.names.push(call.name);
+    if (n >= this.maxPeriod) {
+      ring.sigs.shift();
+      ring.labels.shift();
+      ring.names.shift();
+    }
+  }
   /** Look for a repeating cycle at the very end of the sequence. */
-  detect() {
-    const n = this.sigs.length;
+  detect(ring) {
+    const n = ring.sigs.length;
     for (let period = 2; period <= this.maxPeriod; period += 1) {
-      if (n < period * this.repeats) continue;
-      let matching = 0;
-      for (let i = n - 1; i >= period && this.sigs[i] === this.sigs[i - period]; i -= 1) matching += 1;
-      const cycles = Math.floor(matching / period) + 1;
+      const cycles = Math.floor(ring.matches[period - 2] / period) + 1;
       if (cycles < this.repeats) continue;
-      const cycle = this.sigs.slice(n - period);
+      const cycle = ring.sigs.slice(n - period);
       if (new Set(cycle).size < 2) continue;
       return {
         period,
         repeats: cycles,
         threshold: this.repeats,
-        cycle: this.labels.slice(n - period)
+        cycle: ring.labels.slice(n - period),
+        tools: ring.names.slice(n - period)
       };
     }
     return void 0;
   }
+  /** The resolved options, for the snapshot fingerprint. */
+  config() {
+    return { maxPeriod: this.maxPeriod, repeats: this.repeats };
+  }
+  snapshot(redact) {
+    const ring = this.ring;
+    return {
+      sigs: [...ring.sigs],
+      labels: ring.labels.map(
+        (label, i) => redact ? `${ring.names[i]}(${REDACTED})` : clip(label, MAX_LABEL_LENGTH)
+      ),
+      names: ring.names.map((name) => clip(name, MAX_NAME_LENGTH)),
+      matches: [...ring.matches],
+      current: this.current === null ? null : { ...this.current }
+    };
+  }
+  restore(raw) {
+    const path = "detectors.oscillation";
+    const state = asRecord(raw, path);
+    const sigs = asList(field(state, "sigs", path), `${path}.sigs`, this.maxPeriod).map(
+      (v, i) => asHash(v, `${path}.sigs[${i}]`)
+    );
+    const labels = asList(field(state, "labels", path), `${path}.labels`, this.maxPeriod).map(
+      (v, i) => asString(v, `${path}.labels[${i}]`, MAX_LABEL_LENGTH)
+    );
+    const names = asList(field(state, "names", path), `${path}.names`, this.maxPeriod).map(
+      (v, i) => asString(v, `${path}.names[${i}]`, MAX_NAME_LENGTH)
+    );
+    const matches = asList(field(state, "matches", path), `${path}.matches`, this.maxPeriod - 1).map(
+      (v, i) => asInt(v, `${path}.matches[${i}]`)
+    );
+    const current = asNullable(field(state, "current", path), (v) => {
+      const where = `${path}.current`;
+      const c = asRecord(v, where);
+      const period = asInt(field(c, "period", where), `${where}.period`);
+      const repeats = asInt(field(c, "repeats", where), `${where}.repeats`);
+      if (period < 2 || period > this.maxPeriod) fail(`${where}.period`, "must be between 2 and maxPeriod");
+      return { period, repeats };
+    });
+    if (labels.length !== sigs.length || names.length !== sigs.length) fail(path, "has rings of different lengths");
+    if (matches.length !== this.maxPeriod - 1) {
+      fail(`${path}.matches`, `must have exactly ${this.maxPeriod - 1} entries`);
+    }
+    if (matches.some((m, i) => m > 0 && sigs.length < i + 2)) {
+      fail(`${path}.matches`, "counts calls that are not in the ring");
+    }
+    this.ring = { sigs, labels, names, matches };
+    this.current = current;
+  }
   state() {
     return { maxPeriod: this.maxPeriod, repeats: this.repeats, current: this.current };
   }
   reset() {
-    this.sigs = [];
-    this.labels = [];
+    this.ring = this.emptyRing();
     this.current = null;
   }
 };
+
+// src/detectors/repeatedToolCall.ts
+var MAX_STEP_INDEXES = 10;
+function emptyRun() {
+  return { key: void 0, tool: "", preview: "", length: 0, steps: [], threshold: 0, identicalResults: false };
+}
 var RepeatedToolCallDetector = class {
-  threshold;
-  requireIdenticalResults;
-  ignoreErrors;
-  runKey;
-  runTool = "";
-  runPreview = "";
-  runLength = 0;
-  runSteps = [];
-  longest = 0;
-  constructor(options = {}) {
+  constructor(options = {}, policies) {
+    this.policies = policies;
     this.threshold = assertInteger("repeatedToolCall.threshold", options.threshold ?? 3, 2);
     this.requireIdenticalResults = options.requireIdenticalResults ?? false;
     this.ignoreErrors = options.ignoreErrors ?? false;
   }
+  policies;
+  threshold;
+  requireIdenticalResults;
+  ignoreErrors;
+  run = emptyRun();
+  longest = 0;
   observe(record) {
     let hit;
     for (const call of record.calls) {
       if (this.ignoreErrors && call.failed) continue;
-      this.extendRun(call, record.index);
-      if (this.runLength >= this.threshold) hit = this.evidence();
+      const rule = this.ruleFor(call.name);
+      const key = rule.identicalResults ? call.outcomeSig : call.callSig;
+      this.run = advance(this.run, key, call, record.index, rule);
+      if (this.run.length > this.longest) this.longest = this.run.length;
+      if (this.run.length >= this.run.threshold) hit = evidenceOf(this.run);
     }
     if (hit === void 0) return void 0;
     const results = hit.identicalResults ? " and identical results" : "";
@@ -630,46 +904,388 @@ var RepeatedToolCallDetector = class {
       }
     };
   }
-  extendRun(call, stepIndex) {
-    const key = this.requireIdenticalResults ? call.outcomeSig : call.callSig;
-    if (key === this.runKey) {
-      this.runLength += 1;
-      if (this.runSteps[this.runSteps.length - 1] !== stepIndex) this.runSteps.push(stepIndex);
-    } else {
-      this.runKey = key;
-      this.runTool = call.name;
-      this.runPreview = call.argsPreview;
-      this.runLength = 1;
-      this.runSteps = [stepIndex];
+  /**
+   * What `observe` would report if these calls (not yet made, so without results) were the next
+   * ones, without recording them. `stepIndex` is the index the step would get.
+   *
+   * A rule that needs results to call two calls identical (`requireIdenticalResults`, a `polling`
+   * tool) cannot be judged before the call runs, so such a call never trips it here; it counts as
+   * a run of one.
+   */
+  peek(calls, stepIndex) {
+    let run = { ...this.run, steps: [...this.run.steps] };
+    let hit;
+    for (const [i, call] of calls.entries()) {
+      const rule = this.ruleFor(call.name);
+      const key = rule.identicalResults ? `pending#${i}` : call.callSig;
+      run = advance(run, key, call, stepIndex, rule);
+      if (run.length >= run.threshold) hit = evidenceOf(run);
+    }
+    if (hit === void 0) return void 0;
+    return {
+      stop: true,
+      reason: "repeated-tool-call",
+      code: "REPEATED_TOOL_CALL",
+      detail: `Calling tool "${hit.tool}" now would be call ${hit.count} in a row with identical arguments (the limit is ${hit.threshold}): ${hit.tool}(${hit.argsPreview}).`,
+      evidence: hit
+    };
+  }
+  /** The threshold and result-matching mode that apply to calls of `tool`. */
+  ruleFor(tool) {
+    const policy = this.policies?.get(tool);
+    if (policy?.polling === true) {
+      return { threshold: policy.pollingThreshold ?? policy.repeatThreshold ?? this.threshold, identicalResults: true };
     }
-    if (this.runLength > this.longest) this.longest = this.runLength;
+    return { threshold: policy?.repeatThreshold ?? this.threshold, identicalResults: this.requireIdenticalResults };
   }
-  evidence() {
+  /** The resolved options, for the snapshot fingerprint. */
+  config() {
     return {
-      tool: this.runTool,
-      argsPreview: this.runPreview,
-      count: this.runLength,
       threshold: this.threshold,
-      stepIndexes: this.runSteps.slice(-10),
-      identicalResults: this.requireIdenticalResults
+      requireIdenticalResults: this.requireIdenticalResults,
+      ignoreErrors: this.ignoreErrors
     };
   }
+  snapshot(redact) {
+    const run = this.run;
+    return {
+      key: run.length === 0 ? null : run.key ?? null,
+      tool: clip(run.tool, MAX_NAME_LENGTH),
+      preview: redact && run.preview !== "" ? REDACTED : clip(run.preview, MAX_PREVIEW_LENGTH),
+      length: run.length,
+      steps: [...run.steps],
+      longest: this.longest
+    };
+  }
+  restore(raw) {
+    const path = "detectors.repeatedToolCall";
+    const state = asRecord(raw, path);
+    const key = asNullable(field(state, "key", path), (v) => asHash(v, `${path}.key`));
+    const tool = asString(field(state, "tool", path), `${path}.tool`, MAX_NAME_LENGTH);
+    const preview = asString(field(state, "preview", path), `${path}.preview`, MAX_PREVIEW_LENGTH);
+    const length = asInt(field(state, "length", path), `${path}.length`);
+    const steps = asList(field(state, "steps", path), `${path}.steps`, MAX_STEP_INDEXES).map(
+      (v, i) => asInt(v, `${path}.steps[${i}]`)
+    );
+    const longest = asInt(field(state, "longest", path), `${path}.longest`);
+    if (length === 0 ? key !== null || steps.length !== 0 : key === null || steps.length === 0 || steps.length > length) {
+      fail(path, "has a run whose key, length and steps disagree");
+    }
+    if (steps.some((v, i) => i > 0 && v <= steps[i - 1])) {
+      fail(`${path}.steps`, "must be strictly increasing");
+    }
+    if (longest < length) fail(`${path}.longest`, "must be at least the length of the current run");
+    this.run = length === 0 || key === null ? emptyRun() : { key, tool, preview, length, steps, ...this.ruleFor(tool) };
+    this.longest = longest;
+  }
   state() {
     return {
       threshold: this.threshold,
-      currentRun: this.runLength > 0 ? { tool: this.runTool, length: this.runLength } : null,
+      currentRun: this.run.length > 0 ? { tool: this.run.tool, length: this.run.length } : null,
       longestRun: this.longest
     };
   }
   reset() {
-    this.runKey = void 0;
-    this.runTool = "";
-    this.runPreview = "";
-    this.runLength = 0;
-    this.runSteps = [];
+    this.run = emptyRun();
     this.longest = 0;
   }
 };
+function advance(run, key, call, stepIndex, rule) {
+  if (key !== run.key) {
+    return { key, tool: call.name, preview: call.argsPreview, length: 1, steps: [stepIndex], ...rule };
+  }
+  run.length += 1;
+  if (run.steps[run.steps.length - 1] !== stepIndex) {
+    run.steps.push(stepIndex);
+    if (run.steps.length > MAX_STEP_INDEXES) run.steps.shift();
+  }
+  return run;
+}
+function evidenceOf(run) {
+  return {
+    tool: run.tool,
+    argsPreview: run.preview,
+    count: run.length,
+    threshold: run.threshold,
+    stepIndexes: [...run.steps],
+    identicalResults: run.identicalResults
+  };
+}
+
+// src/detectors/toolLimit.ts
+var ToolLimitDetector = class {
+  limits = /* @__PURE__ */ new Map();
+  counts = /* @__PURE__ */ new Map();
+  constructor(policies) {
+    for (const { tool, limit } of policies.capped) this.limits.set(tool, limit);
+  }
+  observe(record) {
+    let evidence;
+    for (const call of record.calls) {
+      const limit = this.limits.get(call.name);
+      if (limit === void 0) continue;
+      const calls = (this.counts.get(call.name) ?? 0) + 1;
+      this.counts.set(call.name, calls);
+      if (calls > limit && evidence === void 0) evidence = { tool: call.name, calls, limit };
+    }
+    if (evidence === void 0) return void 0;
+    const stop = {
+      stop: true,
+      reason: "tool-limit",
+      code: "TOOL_CALL_CAP",
+      detail: `Tool "${evidence.tool}" was called ${evidence.calls} times; its limit is ${evidence.limit}.`,
+      evidence
+    };
+    return { stop };
+  }
+  /**
+   * What `observe` would report if these calls ran next, without counting them. `calls` in the
+   * evidence is the number the first over-limit call would be.
+   */
+  peek(calls) {
+    const pending = /* @__PURE__ */ new Map();
+    for (const call of calls) {
+      const limit = this.limits.get(call.name);
+      if (limit === void 0) continue;
+      const n = (pending.get(call.name) ?? this.counts.get(call.name) ?? 0) + 1;
+      pending.set(call.name, n);
+      if (n > limit) {
+        return {
+          stop: true,
+          reason: "tool-limit",
+          code: "TOOL_CALL_CAP",
+          detail: `Calling tool "${call.name}" now would be call ${n}; its limit is ${limit}.`,
+          evidence: { tool: call.name, calls: n, limit }
+        };
+      }
+    }
+    return void 0;
+  }
+  snapshot() {
+    return [...this.limits.keys()].map((tool) => ({ tool, calls: this.counts.get(tool) ?? 0 }));
+  }
+  restore(raw) {
+    const path = "detectors.toolLimits";
+    const tools = [...this.limits.keys()];
+    const entries = asList(raw, path, tools.length);
+    if (entries.length !== tools.length) fail(path, `must have one entry for each of the ${tools.length} capped tools`);
+    const counts = /* @__PURE__ */ new Map();
+    entries.forEach((entry, i) => {
+      const where = `${path}[${i}]`;
+      const record = asRecord(entry, where);
+      const tool = asString(field(record, "tool", where), `${where}.tool`, MAX_NAME_LENGTH);
+      if (tool !== tools[i]) fail(`${where}.tool`, "is not the tool capped at that position in the options");
+      counts.set(tool, asInt(field(record, "calls", where), `${where}.calls`));
+    });
+    this.counts.clear();
+    for (const [tool, calls] of counts) this.counts.set(tool, calls);
+  }
+  state() {
+    return [...this.limits].map(([tool, limit]) => ({ tool, limit, calls: this.counts.get(tool) ?? 0 }));
+  }
+  reset() {
+    this.counts.clear();
+  }
+};
+
+// src/explain.ts
+function hint(verdict) {
+  switch (verdict.reason) {
+    case "max-steps":
+      return "Raise maxSteps if the task really needs more steps; otherwise find out why the agent is not converging.";
+    case "tool-limit":
+      return "The model called a tool more often than its maxCalls allows. Raise the limit if the task needs it, or look at why the model keeps going back to this tool.";
+    case "repeated-tool-call":
+      return "The model keeps issuing the same call. Check that the tool result gives it something to act on, and that the prompt says what to do when a tool fails.";
+    case "oscillation":
+      return "The model is flipping between the same calls. Look for two tools whose results send the model back to each other.";
+    case "no-progress":
+      return "Nothing new is coming back and the model is not saying anything new. Retrying the same request will not help.";
+    case "finish-reason":
+      return verdict.evidence.normalized === "stop" ? "This is the normal end of a run, not a fault." : 'The provider ended this step in a way the loop does not treat as "keep going". Inspect the raw response.';
+    case "budget":
+      return "Raise the limit, shorten the context, or split the task.";
+    case "custom":
+      return "Stopped by a custom detector.";
+  }
+}
+function isFault(verdict) {
+  if (!verdict.stop) return false;
+  return !(verdict.reason === "finish-reason" && verdict.evidence.normalized === "stop");
+}
+function explain(verdict) {
+  const lines = [];
+  if (verdict.stop) {
+    lines.push(`Stop [${verdict.code}] ${verdict.detail}`);
+    lines.push(`Hint: ${hint(verdict)}`);
+  } else {
+    lines.push("Continue.");
+  }
+  for (const warning of verdict.warnings ?? []) lines.push(`Warning [${warning.code}] ${warning.detail}`);
+  return lines.join("\n");
+}
+
+// src/feedback.ts
+var SAFE_TOOL_NAME = /^[A-Za-z0-9_.:/-]{1,64}$/;
+function isSafeName(name) {
+  return typeof name === "string" && SAFE_TOOL_NAME.test(name);
+}
+function toolRef(name) {
+  return isSafeName(name) ? `\`${name}\`` : "that tool";
+}
+function times(n) {
+  return `${n} time${n === 1 ? "" : "s"}`;
+}
+function toolList(names) {
+  const unique = [...new Set(names)];
+  if (unique.length === 0 || !unique.every(isSafeName)) return "the same few tools";
+  const refs = unique.map((n) => `\`${n}\``);
+  return refs.length === 1 ? refs[0] : `${refs.slice(0, -1).join(", ")} and ${refs[refs.length - 1]}`;
+}
+var BUDGET_LABEL = {
+  totalTokens: "token",
+  inputTokens: "input token",
+  outputTokens: "output token",
+  costUsd: "cost",
+  durationMs: "time"
+};
+var ELSE = "Try a different tool or different arguments, or answer with what you have.";
+function feedbackFor(verdict, phase = "check") {
+  const before = phase === "preflight";
+  switch (verdict.reason) {
+    case "max-steps":
+      return before ? "That call was not run because the step limit for this task has been reached. Do not call any more tools; answer with what you have so far." : "You have reached the limit on how many steps this task may take. Do not call any more tools; answer with what you have so far.";
+    case "tool-limit": {
+      const { tool, calls, limit } = verdict.evidence;
+      if (limit === 0) {
+        return before ? `That call was not run: you may not use ${toolRef(tool)} in this task. Use a different tool, or answer with what you have.` : `You may not use ${toolRef(tool)} in this task. Use a different tool, or answer with what you have.`;
+      }
+      return before ? `That call was not run: you have already used ${toolRef(tool)} ${times(limit)}, the most allowed for it in this task. Use a different tool, or answer with what you have.` : `You have called ${toolRef(tool)} ${times(calls)}, more than the ${limit} allowed for it in this task. Do not call it again; use a different tool, or answer with what you have.`;
+    }
+    case "repeated-tool-call": {
+      const { tool, count, identicalResults } = verdict.evidence;
+      const same = identicalResults ? " and got the same result each time" : "";
+      if (before) {
+        return `That call was not run: you have already called ${toolRef(tool)} ${times(count - 1)} in a row with the same arguments${same}, and repeating it is unlikely to give you anything new. ${ELSE}`;
+      }
+      return `You have called ${toolRef(tool)} ${times(count)} in a row with the same arguments${same}. Repeating it is unlikely to give you anything new. ${ELSE}`;
+    }
+    case "oscillation": {
+      const list = toolList(verdict.evidence.tools);
+      return before ? `That call was not run because it would continue a cycle you are stuck in (${list}). Try a different approach, or answer with what you have.` : `You are going round in a cycle of calls (${list}) without getting anywhere. Stop repeating it: try a different approach, or answer with what you have.`;
+    }
+    case "no-progress":
+      return `Your last ${verdict.evidence.steps} steps added nothing new: no new tool results and the same text. Do something different, such as using another tool or approach, or answer with what you have.`;
+    case "finish-reason":
+      return finishReasonFeedback(verdict);
+    case "budget": {
+      const label = BUDGET_LABEL[verdict.evidence.metric];
+      return before ? `That call was not run because the ${label} budget for this task has been used up. Answer with what you have.` : `The ${label} budget for this task has been used up. Do not start any new work; answer with what you have.`;
+    }
+    case "custom":
+      return verdict.feedback;
+  }
+}
+function finishReasonFeedback(verdict) {
+  if (verdict.code === "FINISH_OTHER") {
+    return "Your last step ended without a clear signal that you were finished. If you are done, give your final answer; otherwise continue with a tool call.";
+  }
+  if (verdict.code === "FINISH_OTHER_TEXT_ONLY") {
+    return "Your last step was a text answer with no clear signal that you were finished. If that was your final answer, you are done; otherwise call a tool to continue.";
+  }
+  switch (verdict.evidence.normalized) {
+    case "stop":
+      return void 0;
+    // the model finished normally: nothing went wrong
+    case "length":
+      return "Your last response was cut off because it reached the length limit. Continue more briefly, or give a short answer with what you have.";
+    case "content-filter":
+      return "Your last response was blocked by a content filter. Rephrase it or take a different approach.";
+    case "error":
+      return "The last step ended with an error from the provider. Try again, or answer with what you have.";
+    default:
+      return "The last step ended in a way that ends this run. Give your final answer with what you have.";
+  }
+}
+
+// src/toolPolicy.ts
+var POLICY_KEYS = ["polling", "maxCalls", "repeatThreshold", "ignore"];
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function resolve(tool, raw) {
+  const where = `tools[${JSON.stringify(tool)}]`;
+  if (!isPlainObject(raw)) throw new TypeError(`agent-loopguard: ${where} must be an object, got ${String(raw)}`);
+  for (const key of Object.keys(raw)) {
+    if (!POLICY_KEYS.includes(key)) {
+      throw new TypeError(`agent-loopguard: ${where} has an unknown option "${key}" (known: ${POLICY_KEYS.join(", ")})`);
+    }
+  }
+  const ignore = raw["ignore"];
+  if (ignore !== void 0 && typeof ignore !== "boolean") {
+    throw new TypeError(`agent-loopguard: ${where}.ignore must be a boolean, got ${String(ignore)}`);
+  }
+  let polling = false;
+  let pollingThreshold;
+  const rawPolling = raw["polling"];
+  if (typeof rawPolling === "boolean") {
+    polling = rawPolling;
+  } else if (rawPolling !== void 0) {
+    if (!isPlainObject(rawPolling)) {
+      throw new TypeError(`agent-loopguard: ${where}.polling must be a boolean or an object, got ${String(rawPolling)}`);
+    }
+    for (const key of Object.keys(rawPolling)) {
+      if (key !== "maxIdenticalResults") {
+        throw new TypeError(`agent-loopguard: ${where}.polling has an unknown option "${key}" (known: maxIdenticalResults)`);
+      }
+    }
+    polling = true;
+    const limit = rawPolling["maxIdenticalResults"];
+    if (limit !== void 0) pollingThreshold = assertInteger(`${where}.polling.maxIdenticalResults`, limit, 2);
+  }
+  const repeat = raw["repeatThreshold"];
+  const repeatThreshold = repeat === void 0 ? void 0 : assertInteger(`${where}.repeatThreshold`, repeat, 2);
+  const cap = raw["maxCalls"];
+  const maxCalls = cap === void 0 ? void 0 : assertInteger(`${where}.maxCalls`, cap, 0);
+  return {
+    ignore: ignore === true,
+    polling,
+    pollingThreshold,
+    repeatThreshold,
+    maxCalls: ignore === true ? void 0 : maxCalls
+  };
+}
+var ToolPolicies = class {
+  byName = /* @__PURE__ */ new Map();
+  /** Tools that have a call cap, in the order they were configured. */
+  capped;
+  hasIgnored;
+  constructor(tools) {
+    if (tools !== void 0 && !isPlainObject(tools)) {
+      throw new TypeError(`agent-loopguard: tools must be an object keyed by tool name, got ${String(tools)}`);
+    }
+    const capped = [];
+    let hasIgnored = false;
+    for (const [tool, raw] of Object.entries(tools ?? {})) {
+      const policy = resolve(tool, raw);
+      this.byName.set(tool, policy);
+      if (policy.maxCalls !== void 0) capped.push({ tool, limit: policy.maxCalls });
+      if (policy.ignore) hasIgnored = true;
+    }
+    this.capped = capped;
+    this.hasIgnored = hasIgnored;
+  }
+  get(name) {
+    return this.byName.get(name);
+  }
+  isIgnored(name) {
+    return this.byName.get(name)?.ignore === true;
+  }
+  /** Plain, order-independent description of the resolved rules (used for the snapshot fingerprint). */
+  config() {
+    return [...this.byName].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+  }
+};
 
 // src/guard.ts
 var DEFAULT_MAX_STEPS = 50;
@@ -688,6 +1304,7 @@ var CustomRunner = class {
       detail: typeof out.detail === "string" ? out.detail : "Stopped by a custom detector.",
       evidence: out.evidence === void 0 ? null : out.evidence
     };
+    if (typeof out.feedback === "string" && out.feedback !== "") stop.feedback = out.feedback;
     return { stop };
   }
   reset() {
@@ -696,26 +1313,45 @@ var CustomRunner = class {
 function zeroTotals() {
   return { inputTokens: 0, outputTokens: 0, totalTokens: 0, costUsd: 0, durationMs: 0 };
 }
-function createGuard(options = {}) {
+function buildGuard(options, restored) {
   const now = options.now ?? Date.now;
+  const policies = new ToolPolicies(options.tools);
   const maxSteps = options.maxSteps === false ? void 0 : new MaxStepsDetector(options.maxSteps ?? DEFAULT_MAX_STEPS);
-  const repeated = options.repeatedToolCall === false ? void 0 : new RepeatedToolCallDetector(options.repeatedToolCall);
+  const repeated = options.repeatedToolCall === false ? void 0 : new RepeatedToolCallDetector(options.repeatedToolCall, policies);
   const oscillation = options.oscillation === false ? void 0 : new OscillationDetector(options.oscillation);
   const noProgress = options.noProgress === false ? void 0 : new NoProgressDetector(options.noProgress);
   const finish = options.finishReason === false ? void 0 : new FinishReasonDetector(options.finishReason);
+  const toolLimit = policies.capped.length > 0 ? new ToolLimitDetector(policies) : void 0;
   const budget = options.budget === void 0 || options.budget === false ? void 0 : new BudgetDetector(options.budget, now);
   const customFns = options.custom === void 0 ? [] : typeof options.custom === "function" ? [options.custom] : options.custom;
   const custom = customFns.map((fn) => new CustomRunner(fn));
-  const optional = [finish, budget, maxSteps, repeated, oscillation, noProgress, ...custom];
-  const detectors = optional.filter((d) => d !== void 0);
+  const optional = [
+    { detector: finish, scoped: false },
+    { detector: budget, scoped: false },
+    { detector: maxSteps, scoped: false },
+    { detector: toolLimit, scoped: true },
+    { detector: repeated, scoped: true },
+    { detector: oscillation, scoped: true },
+    { detector: noProgress, scoped: true },
+    ...custom.map((detector) => ({ detector, scoped: false }))
+  ];
+  const detectors = optional.filter((d) => d.detector !== void 0);
   let history = [];
+  let stepCount = 0;
   let totals = zeroTotals();
   let toolCalls = 0;
   let failedToolCalls = 0;
   let lastVerdict = null;
+  function withFeedback(stop) {
+    if (!isFault(stop)) return stop;
+    const override = options.feedback?.(stop, { phase: "check" });
+    const text = typeof override === "string" ? override : feedbackFor(stop, "check");
+    return text === void 0 ? stop : { ...stop, feedback: text };
+  }
   function check(step) {
     const safe = typeof step === "object" && step !== null ? step : {};
-    const record = buildRecord(safe, history.length);
+    const record = buildRecord(safe, stepCount);
+    stepCount += 1;
     history.push(safe);
     totals.inputTokens += record.inputTokens ?? 0;
     totals.outputTokens += record.outputTokens ?? 0;
@@ -724,32 +1360,52 @@ function createGuard(options = {}) {
     totals.durationMs += record.durationMs ?? 0;
     toolCalls += record.calls.length;
     failedToolCalls += record.calls.filter((c) => c.failed).length;
+    const scopedRecord = policies.hasIgnored ? { ...record, calls: record.calls.filter((c) => !policies.isIgnored(c.name)) } : record;
     const ctx = { totals, step: safe, history };
     let stop;
     const warnings = [];
-    for (const detector of detectors) {
-      const result = detector.observe(record, ctx);
+    for (const { detector, scoped } of detectors) {
+      const result = detector.observe(scoped ? scopedRecord : record, ctx);
       if (result === void 0) continue;
       if (result.stop !== void 0 && stop === void 0) stop = result.stop;
       if (result.warnings !== void 0) warnings.push(...result.warnings);
     }
     let verdict;
-    if (stop !== void 0) verdict = warnings.length > 0 ? { ...stop, warnings } : stop;
-    else verdict = warnings.length > 0 ? { stop: false, warnings } : { stop: false };
+    if (stop !== void 0) {
+      const full = withFeedback(stop);
+      verdict = warnings.length > 0 ? { ...full, warnings } : full;
+    } else {
+      verdict = warnings.length > 0 ? { stop: false, warnings } : { stop: false };
+    }
     lastVerdict = verdict;
     return verdict;
   }
+  function preflight(input) {
+    const pending = buildPendingCalls(input);
+    const scoped = policies.hasIgnored ? pending.filter((c) => !policies.isIgnored(c.name)) : pending;
+    const budgetNow = budget?.peek(totals);
+    const found = budgetNow?.stop ?? maxSteps?.peek() ?? toolLimit?.peek(scoped) ?? repeated?.peek(scoped, stepCount) ?? oscillation?.peek(scoped);
+    if (found === void 0) {
+      const warnings = budgetNow?.warnings;
+      return warnings === void 0 ? { allow: true } : { allow: true, warnings };
+    }
+    const override = options.feedback?.(found, { phase: "preflight" });
+    const feedback = typeof override === "string" ? override : feedbackFor(found, "preflight");
+    const { stop: _stop, feedback: _feedback, warnings: _warnings, ...rest } = found;
+    return { allow: false, ...rest, feedback };
+  }
   function reset() {
     history = [];
+    stepCount = 0;
     totals = zeroTotals();
     toolCalls = 0;
     failedToolCalls = 0;
     lastVerdict = null;
-    for (const detector of detectors) detector.reset();
+    for (const { detector } of detectors) detector.reset();
   }
   function summary() {
     return {
-      steps: history.length,
+      steps: stepCount,
       toolCalls,
       failedToolCalls,
       totals: { ...totals },
@@ -759,55 +1415,118 @@ function createGuard(options = {}) {
         oscillation: oscillation ? oscillation.state() : null,
         noProgress: noProgress ? noProgress.state() : null,
         finishReason: finish ? finish.state() : null,
-        budget: budget ? budget.state() : null
+        budget: budget ? budget.state() : null,
+        ...toolLimit ? { toolLimits: toolLimit.state() } : {}
       },
       lastVerdict
     };
   }
+  function fingerprints() {
+    return {
+      maxSteps: fingerprint(maxSteps ? maxSteps.config() : false),
+      repeatedToolCall: fingerprint(repeated ? repeated.config() : false),
+      oscillation: fingerprint(oscillation ? oscillation.config() : false),
+      noProgress: fingerprint(noProgress ? noProgress.config() : false),
+      finishReason: fingerprint(finish ? finish.config() : false),
+      budget: fingerprint(budget ? budget.config() : false),
+      tools: fingerprint(policies.config()),
+      custom: fingerprint(customFns.length)
+    };
+  }
+  function snapshot(snapshotOptions) {
+    const redact = typeof snapshotOptions === "object" && snapshotOptions !== null && snapshotOptions.redact === true;
+    return {
+      version: SNAPSHOT_VERSION,
+      steps: stepCount,
+      toolCalls,
+      failedToolCalls,
+      totals: { ...totals },
+      wallClockMs: budget ? budget.elapsedMs() : null,
+      options: fingerprints(),
+      detectors: {
+        repeatedToolCall: repeated ? repeated.snapshot(redact) : null,
+        oscillation: oscillation ? oscillation.snapshot(redact) : null,
+        noProgress: noProgress ? noProgress.snapshot(redact) : null,
+        finishReason: finish ? finish.snapshot() : null,
+        toolLimits: toolLimit ? toolLimit.snapshot() : null
+      }
+    };
+  }
+  function applySnapshot(raw, allowLimitChanges) {
+    const top = asRecord(raw, "snapshot");
+    const version = field(top, "version", "snapshot");
+    if (version !== SNAPSHOT_VERSION) {
+      const shown = typeof version === "number" || typeof version === "string" ? JSON.stringify(version) : typeof version;
+      fail("snapshot.version", `is ${shown}, but this version of agent-loopguard reads version ${SNAPSHOT_VERSION}`);
+    }
+    const steps = asInt(field(top, "steps", "snapshot"), "snapshot.steps");
+    const calls = asInt(field(top, "toolCalls", "snapshot"), "snapshot.toolCalls");
+    const failed = asInt(field(top, "failedToolCalls", "snapshot"), "snapshot.failedToolCalls");
+    if (failed > calls) fail("snapshot.failedToolCalls", "cannot exceed toolCalls");
+    const rawTotals = asRecord(field(top, "totals", "snapshot"), "snapshot.totals");
+    const restoredTotals = {
+      inputTokens: asAmount(field(rawTotals, "inputTokens", "snapshot.totals"), "snapshot.totals.inputTokens"),
+      outputTokens: asAmount(field(rawTotals, "outputTokens", "snapshot.totals"), "snapshot.totals.outputTokens"),
+      totalTokens: asAmount(field(rawTotals, "totalTokens", "snapshot.totals"), "snapshot.totals.totalTokens"),
+      costUsd: asAmount(field(rawTotals, "costUsd", "snapshot.totals"), "snapshot.totals.costUsd"),
+      durationMs: asAmount(field(rawTotals, "durationMs", "snapshot.totals"), "snapshot.totals.durationMs")
+    };
+    const wallClockMs = asNullable(field(top, "wallClockMs", "snapshot"), (v) => asAmount(v, "snapshot.wallClockMs"));
+    const stored = asRecord(field(top, "options", "snapshot"), "snapshot.options");
+    const current = fingerprints();
+    const relaxed = allowLimitChanges ? ["maxSteps", "budget"] : [];
+    const changed = Object.keys(current).filter(
+      (key) => !relaxed.includes(key) && asString(field(stored, key, "snapshot.options"), `snapshot.options.${key}`, 64) !== current[key]
+    );
+    if (changed.length > 0) {
+      throw new TypeError(
+        `agent-loopguard: this snapshot was taken with different options (${changed.join(", ")}); restore it with the options it was taken with`
+      );
+    }
+    const states = asRecord(field(top, "detectors", "snapshot"), "snapshot.detectors");
+    const load = (key, detector) => {
+      const state = section(states, key, detector !== void 0);
+      detector?.restore(state);
+    };
+    load("repeatedToolCall", repeated);
+    load("oscillation", oscillation);
+    load("noProgress", noProgress);
+    load("finishReason", finish);
+    load("toolLimits", toolLimit);
+    stepCount = steps;
+    toolCalls = calls;
+    failedToolCalls = failed;
+    totals = restoredTotals;
+    maxSteps?.restore(steps);
+    budget?.restore(restoredTotals, wallClockMs);
+  }
+  if (restored !== void 0) {
+    try {
+      applySnapshot(restored.snapshot, restored.allowLimitChanges);
+    } catch (error) {
+      if (error instanceof TypeError) throw error;
+      throw new TypeError("agent-loopguard: invalid snapshot: it could not be read");
+    }
+  }
   return {
     check,
+    preflight,
     reset,
+    toJSON: () => snapshot(),
+    snapshot,
     summary,
     get history() {
       return Object.freeze([...history]);
     }
   };
 }
-
-// src/explain.ts
-function hint(verdict) {
-  switch (verdict.reason) {
-    case "max-steps":
-      return "Raise maxSteps if the task really needs more steps; otherwise find out why the agent is not converging.";
-    case "repeated-tool-call":
-      return "The model keeps issuing the same call. Check that the tool result gives it something to act on, and that the prompt says what to do when a tool fails.";
-    case "oscillation":
-      return "The model is flipping between the same calls. Look for two tools whose results send the model back to each other.";
-    case "no-progress":
-      return "Nothing new is coming back and the model is not saying anything new. Retrying the same request will not help.";
-    case "finish-reason":
-      return verdict.evidence.normalized === "stop" ? "This is the normal end of a run, not a fault." : 'The provider ended this step in a way the loop does not treat as "keep going". Inspect the raw response.';
-    case "budget":
-      return "Raise the limit, shorten the context, or split the task.";
-    case "custom":
-      return "Stopped by a custom detector.";
-  }
-}
-function isFault(verdict) {
-  if (!verdict.stop) return false;
-  return !(verdict.reason === "finish-reason" && verdict.evidence.normalized === "stop");
+function createGuard(options = {}) {
+  return buildGuard(options, void 0);
 }
-function explain(verdict) {
-  const lines = [];
-  if (verdict.stop) {
-    lines.push(`Stop [${verdict.code}] ${verdict.detail}`);
-    lines.push(`Hint: ${hint(verdict)}`);
-  } else {
-    lines.push("Continue.");
-  }
-  for (const warning of verdict.warnings ?? []) lines.push(`Warning [${warning.code}] ${warning.detail}`);
-  return lines.join("\n");
+function restoreGuard(snapshot, options = {}, restoreOptions = {}) {
+  return buildGuard(options, { snapshot, allowLimitChanges: restoreOptions?.allowLimitChanges === true });
 }
+createGuard.fromJSON = restoreGuard;
 
 // src/adapters/aiSdk.ts
 function isRecord(value) {
@@ -918,4 +1637,4 @@ function withGuard(source, guard) {
   };
 }
 
-export { DEFAULT_MAX_STEPS, canonicalize, createGuard, explain, isFault, runAgentLoop, stableHash, toGuardStep, toStopWhen, withGuard };
+export { DEFAULT_MAX_STEPS, canonicalize, createGuard, explain, feedbackFor, isFault, restoreGuard, runAgentLoop, stableHash, toGuardStep, toStopWhen, withGuard };