@pentoshi/clai 3.5.1 → 3.7.2

package/README.md

@@ -2,7 +2,7 @@
 
 > **Offensive-security agent in your terminal** — recon, enumerate, exploit, and report with an approve-before-run plan workflow. Also a strong coding/sysadmin agent for shell and files. Free to build, free to run.
 
-clai is an AI **agent CLI** built for people who break (and fix) systems: authorized pentests, red-team style workflows, CTFs, report verification, and day-to-day security engineering. It runs real tools (`nmap`, `ffuf`, `sqlmap`, `http` evidence capture, …), keeps a **durable engagement plan**, and never pretends a finding is real without tool output to back it up.
+clai is an AI **agent CLI** built for people who break (and fix) systems: authorized pentests, red-team style workflows, CTFs, report verification, and day-to-day security engineering. It runs real tools (`nmap`, `ffuf`, `sqlmap`, `http` evidence capture, …), keeps a **durable engagement plan**, and never pretends a finding is real without tool output to back it up. Providers that support it use **native function/tool calling** (config `toolCalling: auto|native|text`); text-fence tools remain as fallback.
 
 It also builds software and runs shell/file workflows when that is the job — same agent, same safety gate, same UI.
 

package/dist/agent/compaction-summary.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Prompts and helpers for LLM-based context compaction.
+ * The model produces structured continuation memory — not a raw transcript dump.
+ */
+export declare const COMPACTION_SYSTEM_PROMPT = "You are a session-memory compressor for an autonomous coding and security agent.\n\nWrite a dense, accurate CONTINUATION MEMORY for another assistant that will resume this work with no other history.\n\nRules:\n- Fidelity over style. Never invent tool results, file contents, findings, URLs, ports, or completions.\n- Prefer concrete artifacts: absolute paths, commands (short form), exit outcomes, HTTP status, plan task ids/states, job ids, open ports, confirmed vs unconfirmed findings.\n- Omit secrets, API keys, passwords, tokens, and full credential material. Say \"[redacted]\" if present.\n- Omit progress bars, repeated failures, and decorative chatter.\n- Do not wrap the whole answer in markdown code fences.\n- If something is unknown, omit it rather than guessing.";
+export interface CompactionPromptParts {
+    visualTranscript?: string | undefined;
+    messageTranscript: string;
+    /** Optional live plan / session state to prioritize. */
+    durableState?: string | undefined;
+}
+/** User message fed to the summarizer model. */
+export declare function buildCompactionUserPrompt(parts: CompactionPromptParts): string;
+/** Soft cap for transcript fed to the summarizer (chars). */
+export declare const COMPACTION_TRANSCRIPT_CHAR_BUDGET = 48000;
+/** Prefer head goals + tail recency when the transcript is huge. */
+export declare function trimTranscriptForCompaction(transcript: string, budget?: number): string;

package/dist/agent/compaction-summary.js

@@ -0,0 +1,64 @@
+/**
+ * Prompts and helpers for LLM-based context compaction.
+ * The model produces structured continuation memory — not a raw transcript dump.
+ */
+export const COMPACTION_SYSTEM_PROMPT = `You are a session-memory compressor for an autonomous coding and security agent.
+
+Write a dense, accurate CONTINUATION MEMORY for another assistant that will resume this work with no other history.
+
+Rules:
+- Fidelity over style. Never invent tool results, file contents, findings, URLs, ports, or completions.
+- Prefer concrete artifacts: absolute paths, commands (short form), exit outcomes, HTTP status, plan task ids/states, job ids, open ports, confirmed vs unconfirmed findings.
+- Omit secrets, API keys, passwords, tokens, and full credential material. Say "[redacted]" if present.
+- Omit progress bars, repeated failures, and decorative chatter.
+- Do not wrap the whole answer in markdown code fences.
+- If something is unknown, omit it rather than guessing.`;
+/** User message fed to the summarizer model. */
+export function buildCompactionUserPrompt(parts) {
+    const visual = parts.visualTranscript?.trim() ?? "";
+    const fromMessages = parts.messageTranscript.trim();
+    const durable = parts.durableState?.trim() ?? "";
+    let transcript = "";
+    if (visual && fromMessages) {
+        transcript = `${visual}\n\n---\n\nOLDER MODEL TURNS:\n\n${fromMessages}`;
+    }
+    else {
+        transcript = visual || fromMessages;
+    }
+    const sections = [
+        "Create a complete but compact continuation memory of the session below.",
+        "Treat resumed history and newer turns as one continuous conversation.",
+        "",
+        "Organize under these exact section headings (skip a section only if empty):",
+        "## User goals",
+        "## Decisions and constraints",
+        "## Work completed",
+        "## Commands/tools and results",
+        "## Current state",
+        "## Remaining work",
+        "## Open risks / failures",
+        "",
+        "Preserve: user intentions, decisions, constraints, paths, stack/package manager,",
+        "commands and key results, plan task states, errors and failed approaches,",
+        "servers/jobs still running, and exactly what remains.",
+        "Be concise but specific. No secrets. No fabricated successes.",
+    ];
+    if (durable) {
+        sections.push("", "DURABLE STATE (trust this over older chatter):", durable);
+    }
+    sections.push("", "SESSION MATERIAL:", "", transcript);
+    return sections.join("\n");
+}
+/** Soft cap for transcript fed to the summarizer (chars). */
+export const COMPACTION_TRANSCRIPT_CHAR_BUDGET = 48_000;
+/** Prefer head goals + tail recency when the transcript is huge. */
+export function trimTranscriptForCompaction(transcript, budget = COMPACTION_TRANSCRIPT_CHAR_BUDGET) {
+    if (transcript.length <= budget)
+        return transcript;
+    const head = Math.floor(budget * 0.35);
+    const tail = budget - head - 80;
+    return (transcript.slice(0, head) +
+        "\n\n[... middle of session omitted for length ...]\n\n" +
+        transcript.slice(-tail));
+}
+//# sourceMappingURL=compaction-summary.js.map

package/dist/agent/compaction-summary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction-summary.js","sourceRoot":"","sources":["../../src/agent/compaction-summary.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,CAAC,MAAM,wBAAwB,GAAG;;;;;;;;;;yDAUiB,CAAC;AAS1D,gDAAgD;AAChD,MAAM,UAAU,yBAAyB,CAAC,KAA4B;IACpE,MAAM,MAAM,GAAG,KAAK,CAAC,gBAAgB,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IACpD,MAAM,YAAY,GAAG,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,CAAC;IACpD,MAAM,OAAO,GAAG,KAAK,CAAC,YAAY,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAEjD,IAAI,UAAU,GAAG,EAAE,CAAC;IACpB,IAAI,MAAM,IAAI,YAAY,EAAE,CAAC;QAC3B,UAAU,GAAG,GAAG,MAAM,oCAAoC,YAAY,EAAE,CAAC;IAC3E,CAAC;SAAM,CAAC;QACN,UAAU,GAAG,MAAM,IAAI,YAAY,CAAC;IACtC,CAAC;IAED,MAAM,QAAQ,GAAG;QACf,yEAAyE;QACzE,uEAAuE;QACvE,EAAE;QACF,6EAA6E;QAC7E,eAAe;QACf,8BAA8B;QAC9B,mBAAmB;QACnB,+BAA+B;QAC/B,kBAAkB;QAClB,mBAAmB;QACnB,0BAA0B;QAC1B,EAAE;QACF,kFAAkF;QAClF,2EAA2E;QAC3E,uDAAuD;QACvD,+DAA+D;KAChE,CAAC;IAEF,IAAI,OAAO,EAAE,CAAC;QACZ,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,gDAAgD,EAAE,OAAO,CAAC,CAAC;IAC/E,CAAC;IAED,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,mBAAmB,EAAE,EAAE,EAAE,UAAU,CAAC,CAAC;IACvD,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,6DAA6D;AAC7D,MAAM,CAAC,MAAM,iCAAiC,GAAG,MAAM,CAAC;AAExD,oEAAoE;AACpE,MAAM,UAAU,2BAA2B,CACzC,UAAkB,EAClB,MAAM,GAAG,iCAAiC;IAE1C,IAAI,UAAU,CAAC,MAAM,IAAI,MAAM;QAAE,OAAO,UAAU,CAAC;IACnD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACvC,MAAM,IAAI,GAAG,MAAM,GAAG,IAAI,GAAG,EAAE,CAAC;IAChC,OAAO,CACL,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC;QACzB,wDAAwD;QACxD,UAAU,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CACxB,CAAC;AACJ,CAAC"}

package/dist/agent/confirm-port.d.ts

@@ -27,4 +27,6 @@ export interface ConfirmPort {
 export declare function restoreInteractiveStdin(): void;
 export declare const inquirerConfirmPort: ConfirmPort;
 export declare function ensurePentestAuthorization(call: ToolCall, autoConfirm: boolean, session: SessionPolicy, confirmPort: ConfirmPort): Promise<boolean>;
-export declare function confirmToolExecution(call: ToolCall, autoConfirm: boolean, session: SessionPolicy, confirmPort: ConfirmPort): Promise<boolean>;
+export declare function confirmToolExecution(call: ToolCall, autoConfirm: boolean, session: SessionPolicy, confirmPort: ConfirmPort, options?: {
+    forceConfirm?: boolean | undefined;
+}): Promise<boolean>;

package/dist/agent/confirm-port.js

@@ -76,7 +76,11 @@ export async function ensurePentestAuthorization(call, autoConfirm, session, con
     session.pentestAuthorized.value = true;
     return true;
 }
-export async function confirmToolExecution(call, autoConfirm, session, confirmPort) {
+export async function confirmToolExecution(call, autoConfirm, session, confirmPort, options) {
+    // Outside-cwd writes / deletes always prompt — even under allow-all / -y.
+    if (options?.forceConfirm) {
+        return confirmPort.confirmTool(call);
+    }
     const config = getConfig();
     if (config.permissions === "allow-all")
         return true;

package/dist/agent/confirm-port.js.map

@@ -1 +1 @@
-{"version":3,"file":"confirm-port.js","sourceRoot":"","sources":["../../src/agent/confirm-port.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"confirm-port.js","sourceRoot":"","sources":["../../src/agent/confirm-port.ts"],"names":[],"mappings":"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"}

package/dist/agent/context-manager.js

@@ -1,5 +1,7 @@
 import { redactSecrets } from "../llm/provider.js";
 import { stripThinking } from "../ui/thinking.js";
+import { expandKeepStartForToolPairs } from "./tool-history.js";
+import { buildCompactionUserPrompt, trimTranscriptForCompaction, } from "./compaction-summary.js";
 /**
  * Per-char token estimator. Real tokenization varies by provider, but for
  * budgeting a chars/3.3 heuristic is close enough for mixed text/code/JSON
@@ -66,8 +68,10 @@ export function compactMessages(messages, options = {}) {
         head.push(messages[0]);
         start = 1;
     }
-    const tail = messages.slice(Math.max(start, messages.length - keepRecent));
-    const middle = messages.slice(start, messages.length - tail.length);
+    let tailStart = Math.max(start, messages.length - keepRecent);
+    tailStart = expandKeepStartForToolPairs(messages, tailStart);
+    const tail = messages.slice(tailStart);
+    const middle = messages.slice(start, tailStart);
     if (middle.length === 0)
         return messages;
     const bullets = [];
@@ -79,6 +83,9 @@ export function compactMessages(messages, options = {}) {
             const line = oneLine(msg.content, 200);
             if (line)
                 bullets.push(`- assistant: ${line}`);
+            if (msg.toolCalls?.length) {
+                bullets.push(`- assistant tools: ${msg.toolCalls.map((t) => t.name).join(", ")}`);
+            }
         }
         else if (msg.role === "tool") {
             bullets.push(`- tool result: ${oneLine(msg.content, 200)}`);
@@ -106,12 +113,14 @@ export async function compactMessagesWithSummary(messages, summarize, options =
     let keepRecent = Math.max(2, options.keepRecent ?? DEFAULT_KEEP_RECENT);
     const start = messages[0]?.role === "system" ? 1 : 0;
     let tailStart = Math.max(start, messages.length - keepRecent);
+    tailStart = expandKeepStartForToolPairs(messages, tailStart);
     let older = messages.slice(start, tailStart);
     // If forced and the older slice would be empty, try keeping fewer recent
     // messages (minimum 1) so we have something to compact (e.g. the first user prompt).
     if (older.length === 0 && isForced && messages.length >= start + 2) {
         keepRecent = 1;
         tailStart = messages.length - 1;
+        tailStart = expandKeepStartForToolPairs(messages, tailStart);
         older = messages.slice(start, tailStart);
     }
     if (older.length === 0 && !sessionTranscript?.trim()) {
@@ -128,40 +137,60 @@ export async function compactMessagesWithSummary(messages, summarize, options =
     const messageTranscript = older
         .map((message) => {
         let content = redactSecrets(message.content);
-        // Strip <think> tags from assistant messages so thinking content
-        // never leaks into the compaction summary or model context.
         if (message.role === "assistant") {
             content = stripThinking(content).visible;
         }
+        if (message.toolCalls?.length) {
+            content +=
+                "\n[tools: " +
+                    message.toolCalls.map((t) => t.name).join(", ") +
+                    "]";
+        }
         return `${message.role.toUpperCase()}: ${content}`;
     })
         .join("\n\n");
-    // Prefer combining visual session material (tools/prompts) with older model
-    // turns so /compact after /history + new messages never loses either side.
     const visual = sessionTranscript?.trim()
         ? redactSecrets(sessionTranscript.trim())
         : "";
-    const fromMessages = messageTranscript.trim();
-    const transcript = visual && fromMessages
-        ? `${visual}\n\n---\n\nOLDER MODEL TURNS:\n\n${fromMessages}`
-        : visual || fromMessages;
-    const prompt = [
-        "Create a complete but compact continuation memory of the entire session below for another assistant that will continue it.",
-        "The material may include a resumed history session plus newer turns — treat it as one continuous conversation.",
-        "Preserve user intentions and prompts, decisions, constraints, file paths, commands/tools run, steps taken, task states, outputs and results, errors and failed approaches, completed work, and exactly what remains.",
-        "Organize the memory under concise sections: User goals, Decisions and constraints, Work completed, Commands/tools and results, Current state, Remaining work.",
-        "Do not add facts, commentary, or markdown framing. Be concise but specific. Never include secrets or credentials.",
-        "",
-        transcript,
-    ].join("\n");
-    // The summary is the only path. Any failure propagates to the caller —
-    // there is deliberately NO deterministic fallback.
-    // Strip <think> tags from the summary — the summarizer model may itself
-    // produce reasoning tags that would leak into the compacted context.
+    const isDurableSystem = (content) => content.startsWith("ACTIVE PLAN") ||
+        content.startsWith("SESSION STATE") ||
+        content.startsWith("ENGAGEMENT SCOPE") ||
+        content.startsWith("TASK ANALYSIS") ||
+        content.includes("\nACTIVE PLAN") ||
+        content.includes("SESSION STATE / WORKING MEMORY");
+    const durableBits = messages
+        .filter((m) => m.role === "system" && isDurableSystem(m.content))
+        .map((m) => {
+        // Large system prompts: extract only durable subsections when present.
+        if (m.content.length > 4_000) {
+            const chunks = [];
+            for (const marker of [
+                "ACTIVE PLAN",
+                "SESSION STATE / WORKING MEMORY",
+                "ENGAGEMENT SCOPE",
+                "TASK ANALYSIS",
+            ]) {
+                const idx = m.content.indexOf(marker);
+                if (idx >= 0)
+                    chunks.push(m.content.slice(idx, idx + 2_500));
+            }
+            return chunks.join("\n\n") || m.content.slice(0, 2_000);
+        }
+        return m.content;
+    })
+        .filter(Boolean)
+        .join("\n\n");
+    const rawCombined = buildCompactionUserPrompt({
+        visualTranscript: visual || undefined,
+        messageTranscript,
+        durableState: durableBits || undefined,
+    });
+    const prompt = trimTranscriptForCompaction(rawCombined);
     const rawSummary = redactSecrets((await summarize(prompt)).trim());
     const summary = stripThinking(rawSummary).visible.trim();
-    if (!summary)
+    if (!summary) {
         throw new Error("compaction failed: model returned an empty summary");
+    }
     const head = start === 1 ? [messages[0]] : [];
     // Strip <think> tags from tail messages so thinking content never
     // survives compaction into the model's context.

package/dist/agent/context-manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"context-manager.js","sourceRoot":"","sources":["../../src/agent/context-manager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"context-manager.js","sourceRoot":"","sources":["../../src/agent/context-manager.ts"],"names":[],"mappings":"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"}

package/dist/agent/events.d.ts

@@ -1,7 +1,10 @@
 import type { SessionPlan } from "../store/plan.js";
+import type { TurnOutcome } from "./turn-outcome.js";
 export type AgentEvent = {
     type: "turn-start";
     prompt: string;
+    /** Chat YOU bubble text; null/empty = hide system choreography from transcript. */
+    displayPrompt?: string | null;
 } | {
     type: "status";
     text: string;
@@ -45,6 +48,8 @@ export type AgentEvent = {
     exitCode?: number;
     summary: string;
     artifactPath?: string;
+    /** Cursor-style file diffs for fs.* mutation tools. */
+    fileChanges?: import("../tools/file-diff.js").FileChange[] | undefined;
 } | {
     type: "tool-blocked";
     id: string;
@@ -60,6 +65,7 @@ export type AgentEvent = {
     prompt: string;
 } | {
     type: "turn-end";
+    outcome: TurnOutcome;
     finalAnswer: string;
     steps: number;
 } | {

package/dist/agent/evidence-governor.d.ts

@@ -0,0 +1,37 @@
+export type ProgressSignal = "none" | "activity" | "evidence" | "completion";
+export type GovernorRecommendation = "continue" | "reflect" | "paused_budget" | "succeeded";
+export interface GovernorState {
+    readonly schemaVersion: 2;
+    readonly steps: number;
+    readonly evidenceTotal: number;
+    readonly hypothesisTotal: number;
+    readonly consecutiveNoDelta: number;
+    readonly resourcesUsed: number;
+}
+export interface GovernorPolicy {
+    /** Normal operating envelope. Crossing it prompts reflection, not success or an automatic stop. */
+    readonly resourceEnvelope: number;
+    /** Absolute resource limit. Reaching it pauses the turn. */
+    readonly emergencyCeiling: number;
+    readonly reflectionAfterNoDelta: number;
+    readonly pauseAfterNoDelta: number;
+    readonly repetitionThreshold: number;
+}
+export interface ProgressMetrics {
+    readonly evidenceDelta?: number;
+    readonly hypothesisDelta?: number;
+    /** Normalized score from 0 (novel) to 1 (identical repetition). */
+    readonly repetitionScore?: number;
+    readonly resourceCost?: number;
+    readonly policy?: GovernorPolicy;
+}
+export interface GovernorDecision {
+    readonly state: GovernorState;
+    readonly shouldContinue: boolean;
+    readonly requireEvidence: boolean;
+    readonly recommendation: GovernorRecommendation;
+    readonly reason: string;
+}
+export declare const DEFAULT_GOVERNOR_POLICY: GovernorPolicy;
+export declare function createGovernorState(): GovernorState;
+export declare function governProgress(state: GovernorState, signal: ProgressSignal, metrics?: ProgressMetrics): GovernorDecision;

package/dist/agent/evidence-governor.js

@@ -0,0 +1,70 @@
+export const DEFAULT_GOVERNOR_POLICY = {
+    resourceEnvelope: 12,
+    emergencyCeiling: 20,
+    reflectionAfterNoDelta: 2,
+    pauseAfterNoDelta: 4,
+    repetitionThreshold: 0.8,
+};
+export function createGovernorState() {
+    return {
+        schemaVersion: 2,
+        steps: 0,
+        evidenceTotal: 0,
+        hypothesisTotal: 0,
+        consecutiveNoDelta: 0,
+        resourcesUsed: 0,
+    };
+}
+function validatePolicy(policy) {
+    const integers = [policy.resourceEnvelope, policy.emergencyCeiling, policy.reflectionAfterNoDelta, policy.pauseAfterNoDelta];
+    if (integers.some((value) => !Number.isInteger(value) || value < 1))
+        throw new Error("governor limits must be positive integers");
+    if (policy.emergencyCeiling < policy.resourceEnvelope)
+        throw new Error("emergencyCeiling must be at least resourceEnvelope");
+    if (policy.pauseAfterNoDelta < policy.reflectionAfterNoDelta)
+        throw new Error("pauseAfterNoDelta must be at least reflectionAfterNoDelta");
+    if (policy.repetitionThreshold < 0 || policy.repetitionThreshold > 1)
+        throw new Error("repetitionThreshold must be between 0 and 1");
+}
+export function governProgress(state, signal, metrics = {}) {
+    const policy = metrics.policy ?? DEFAULT_GOVERNOR_POLICY;
+    validatePolicy(policy);
+    const evidenceDelta = metrics.evidenceDelta ?? (signal === "evidence" ? 1 : 0);
+    const hypothesisDelta = metrics.hypothesisDelta ?? 0;
+    const repetitionScore = metrics.repetitionScore ?? 0;
+    const resourceCost = metrics.resourceCost ?? 1;
+    if (evidenceDelta < 0 || hypothesisDelta < 0 || resourceCost < 0)
+        throw new Error("progress deltas and resourceCost must be non-negative");
+    if (repetitionScore < 0 || repetitionScore > 1)
+        throw new Error("repetitionScore must be between 0 and 1");
+    const productive = evidenceDelta > 0 || hypothesisDelta > 0;
+    const repetitiveNoDelta = !productive && repetitionScore >= policy.repetitionThreshold;
+    const next = {
+        schemaVersion: 2,
+        steps: state.steps + 1,
+        evidenceTotal: state.evidenceTotal + evidenceDelta,
+        hypothesisTotal: state.hypothesisTotal + hypothesisDelta,
+        consecutiveNoDelta: productive ? 0 : state.consecutiveNoDelta + 1,
+        resourcesUsed: state.resourcesUsed + resourceCost,
+    };
+    if (next.resourcesUsed >= policy.emergencyCeiling) {
+        return { state: next, shouldContinue: false, requireEvidence: true, recommendation: "paused_budget", reason: "emergency resource ceiling reached" };
+    }
+    if (signal === "completion" && evidenceDelta > 0) {
+        return { state: next, shouldContinue: false, requireEvidence: false, recommendation: "succeeded", reason: "completion supported by new evidence" };
+    }
+    if (signal === "completion") {
+        return { state: next, shouldContinue: true, requireEvidence: true, recommendation: "reflect", reason: "completion requires new evidence" };
+    }
+    if (repetitiveNoDelta && next.consecutiveNoDelta >= policy.pauseAfterNoDelta) {
+        return { state: next, shouldContinue: false, requireEvidence: true, recommendation: "paused_budget", reason: "repetitive work produced no evidence or hypothesis progress" };
+    }
+    if (repetitiveNoDelta && next.consecutiveNoDelta >= policy.reflectionAfterNoDelta) {
+        return { state: next, shouldContinue: true, requireEvidence: true, recommendation: "reflect", reason: "repetitive work requires reflection" };
+    }
+    if (next.resourcesUsed >= policy.resourceEnvelope) {
+        return { state: next, shouldContinue: true, requireEvidence: !productive, recommendation: "reflect", reason: "resource envelope reached; reassess before continuing" };
+    }
+    return { state: next, shouldContinue: true, requireEvidence: false, recommendation: "continue", reason: productive ? "productive progress recorded" : "within resource envelope" };
+}
+//# sourceMappingURL=evidence-governor.js.map

package/dist/agent/evidence-governor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence-governor.js","sourceRoot":"","sources":["../../src/agent/evidence-governor.ts"],"names":[],"mappings":"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"}

package/dist/agent/loop-guard.d.ts

@@ -9,10 +9,31 @@ export interface ToolAttempt {
  * Track and detect tool-call repetition patterns so the agent doesn't
  * waste steps in loops.
  */
+export interface LoopGuardOptions {
+    /** @deprecated Retry authorization belongs in RetryContext passed to shouldBlock. */
+    allowUnlimitedFailedRetries?: boolean;
+    /** @deprecated Unchanged failed retries are blocked immediately. */
+    failedRetryLimit?: number;
+}
+export interface RetryContext {
+    /** A dependency changed since the failed attempt. */
+    dependenciesChanged?: boolean;
+    /** The execution environment changed since the failed attempt. */
+    environmentChanged?: boolean;
+    /** Structured justification for retrying without an external change. */
+    retryReason?: {
+        code: string;
+        detail: string;
+    };
+}
 export declare class LoopGuard {
     private attempts;
     private signatureCount;
     private signatureSuccess;
+    /** Failed read-only signatures that already used their one free env-change retry. */
+    private failedReadRetryUsed;
+    private lastSuccessfulNonMetaStep;
+    constructor(_options?: LoopGuardOptions);
     /**
      * Produce a canonical string for a (name, args) pair so that calls
      * with identical semantics match even if arg order differs or
@@ -20,6 +41,9 @@ export declare class LoopGuard {
      */
     canonicalize(name: string, args: Record<string, unknown>): string;
     recordAttempt(step: number, name: string, args: Record<string, unknown>, ok: boolean, exitCode?: number | undefined): void;
+    private isPathMutatingTool;
+    /** Drop list/read signatures that touch paths a successful tool may have created. */
+    private invalidateReadsAfterSuccess;
     /**
      * Check whether the proposed call should be blocked as a repeat.
      *
@@ -27,16 +51,12 @@ export declare class LoopGuard {
      * `{ block: false, reason: "..." }` for a warning (first repeat), or
      * `{ block: true, reason: "..." }` to force summary (second+ repeat).
      *
-     * A call whose every prior attempt FAILED is never blocked — the model is
-     * expected to fix the cause (install a tool, create a dir) and retry. Only
-     * calls that already SUCCEEDED are deduped, since re-running them wastes a
-     * step and risks an infinite summarize loop.
-     *
-     * Read-only tools (web.fetch, fs.read, etc.) get a higher threshold (3)
-     * because they may legitimately need re-calling after context compaction
-     * removes their results.
+     * Failed read-only tools may retry once after any successful intervening
+     * non-meta work (e.g. list missing dir → scaffold → list again). Failed
+     * mutates still need structured retry context or a changed path.
+     * Successful identical mutates are still deduped.
      */
-    shouldBlock(name: string, args: Record<string, unknown>): {
+    shouldBlock(name: string, args: Record<string, unknown>, retryContext?: RetryContext): {
         block: boolean;
         reason?: string | undefined;
     };