@pentoshi/clai 3.11.7 → 3.11.9

package/README.md

@@ -19,6 +19,7 @@ Two things make it practical for everyday use:
 - **Scope-based pentesting.** Opt-in engagement scope with authorized/excluded targets, allowed phases, rate and concurrency ceilings, redirect and DNS-rebinding escape detection, and out-of-scope flagging — designed for authorized pentests and bug-bounty programs.
 - **Real building & debugging.** Scaffolds apps, edits code surgically, installs packages, runs builds/tests, starts dev servers as background jobs, and probes them before reporting success.
 - **Durable plans.** `plan.create` / `task.update` drive a live checklist that survives context compaction and reloads with `/history` — the agent works task-by-task and won't fake completion.
+- **Persistent interactive terminals.** Conversation-owned PTY or pipe sessions keep REPLs such as Python, Metasploit, Meterpreter, database consoles, and debuggers open across model turns. The agent can send follow-up input, read incremental output, resize, interrupt, and close them without losing state.
 - **Native + text tool calling.** Uses provider-native function calling where available, with a text-fence fallback (`toolCalling: auto|native|text`).
 - **Safety gate you control.** Every action is classified safe / confirm / block; deletes always confirm with a preview; destructive patterns are blocked.
 
@@ -416,6 +417,20 @@ Drop a `.clai/context.md` in a repo and its contents are injected every turn —
 
 ---
 
+## Interactive REPLs and terminals
+
+Ask clai to use an interactive terminal whenever a program needs more than one input step. It keeps the process attached to the current conversation instead of treating it like a one-line shell command:
+
+```text
+Start a Python REPL, inspect the failing parser, make a small change, and show me the result.
+```
+
+The agent uses `terminal.start`, `terminal.send`, `terminal.read`, `terminal.status`, `terminal.list`, `terminal.resize`, and `terminal.close` internally. Sessions are isolated per conversation, capture output as cursor-addressed pages, redact prompted secret input before it reaches transcripts or artifacts, and reliably terminate their process trees on close. In plan mode, starting or sending terminal input waits for plan approval; read, status, list, and close operations remain available.
+
+For authorized security work, interactive effects are re-evaluated against the active engagement scope at the time they are delivered. That includes the target, port, phase, and expiry accumulated from prior REPL commands, so a split sequence cannot bypass scope controls.
+
+---
+
 ## Configuration & privacy
 
 ```sh

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

@@ -29,6 +29,10 @@ export interface ConfirmPort {
  */
 export declare function restoreInteractiveStdin(): void;
 export declare const inquirerConfirmPort: ConfirmPort;
+export declare function inquirerSecretRequester(request: {
+    title: string;
+    prompt: string;
+}): Promise<string | undefined>;
 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, options?: {
     forceConfirm?: boolean | undefined;

package/dist/agent/confirm-port.js

@@ -1,4 +1,4 @@
-import { confirm } from "@inquirer/prompts";
+import { confirm, password } from "@inquirer/prompts";
 import chalk from "chalk";
 import { getConfig } from "../store/config.js";
 import { isPentestToolCall } from "../safety/classifier.js";
@@ -58,6 +58,14 @@ export const inquirerConfirmPort = {
         });
     },
 };
+export async function inquirerSecretRequester(request) {
+    try {
+        return await password({ message: request.prompt || request.title });
+    }
+    finally {
+        restoreInteractiveStdin();
+    }
+}
 export async function ensurePentestAuthorization(call, autoConfirm, session, confirmPort) {
     if (!isPentestToolCall(call))
         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/finalize-gate.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Pure finalize-time gate: pick the recovery nudge that must replace a final
+ * answer, or nothing when the turn may finalize. No I/O, no budget mutation.
+ */
+import { type RecoveryAction, type RecoveryBudgets } from "./must-continue.js";
+/** Task fields the gate reads. */
+export interface FinalizeGatePlanTask {
+    id: string;
+    title: string;
+    state: string;
+    responderOwned?: boolean | undefined;
+}
+/** Plain-data snapshot of the live plan, resolved once by the caller. */
+export interface FinalizeGatePlan {
+    kind: string;
+    hasVerifiedRuntime: boolean;
+    tasks: readonly FinalizeGatePlanTask[];
+}
+/** Everything the finalize cascade reads, as data. */
+export interface FinalizeGateInput {
+    cleaned: string;
+    recovery: RecoveryBudgets;
+    toolsAttached: boolean;
+    productiveSteps: number;
+    planApproved: boolean;
+    planHasOpenWork: boolean;
+    activePlanExists: boolean;
+    wantsAction: boolean;
+    narratedAction: boolean;
+    narratedWebAction: boolean;
+    isPlanMode: boolean;
+    buildLikeTurn: boolean;
+    pentestLikeTurn: boolean;
+    buildLike: boolean;
+    pentestLike: boolean;
+    pentestSession: boolean;
+    informationalQuery: boolean;
+    idleOrSocialPrompt: boolean;
+    freshWebSearchRequired: boolean;
+    freshnessGuardText: string;
+    sawFreshWebSearch: boolean;
+    sawPlanCreateOk: boolean;
+    sawFeatureImplWrite: boolean;
+    sawScaffoldOk: boolean;
+    sawLocalAppMaterialWork: boolean;
+    sawServerStart: boolean;
+    sawServerTail: boolean;
+    sawLocalHttpProbe: boolean;
+    sawFailedLocalHttpProbe: boolean;
+    sawActivePentestTest: boolean;
+    sawSuccessfulMutation: boolean;
+    featureAppAsk: boolean;
+    projectRoot: string | undefined;
+    plan: FinalizeGatePlan | undefined;
+    deferResponderReport: boolean;
+}
+export declare function chooseFinalizeRecovery(input: FinalizeGateInput): RecoveryAction | undefined;

package/dist/agent/finalize-gate.js

@@ -0,0 +1,146 @@
+/**
+ * Pure finalize-time gate: pick the recovery nudge that must replace a final
+ * answer, or nothing when the turn may finalize. No I/O, no budget mutation.
+ */
+import { budgetRemaining, freestyleClaimsAppReady, looksLikeShallowPentestReport, recoveryForErrorDiagnosis, recoveryForFailedProbe, recoveryForFreshness, recoveryForMissingFeature, recoveryForMissingPlan, recoveryForNarration, recoveryForPrematureComplete, recoveryForRuntimeVerify, recoveryForShallowPentest, } from "./must-continue.js";
+import { looksLikeErrorDiagnosisWithFixIntent, looksLikePlanNarration, } from "./tool-call-parser.js";
+export function chooseFinalizeRecovery(input) {
+    const { cleaned, recovery, toolsAttached, productiveSteps, plan } = input;
+    const planNarrated = (input.buildLikeTurn || input.pentestLikeTurn) &&
+        !input.activePlanExists &&
+        looksLikePlanNarration(cleaned);
+    const errorFixNarration = !input.sawSuccessfulMutation &&
+        looksLikeErrorDiagnosisWithFixIntent(cleaned);
+    const shouldRetryBeforeFinalizing = productiveSteps === 0 ||
+        planNarrated ||
+        ((input.narratedAction || input.narratedWebAction) &&
+            !input.informationalQuery) ||
+        (input.planApproved &&
+            input.planHasOpenWork &&
+            (input.narratedAction || errorFixNarration)) ||
+        (input.planApproved && errorFixNarration) ||
+        (input.buildLikeTurn && errorFixNarration);
+    if (input.wantsAction &&
+        cleaned.trim().length > 0 &&
+        shouldRetryBeforeFinalizing) {
+        let action;
+        if (errorFixNarration && budgetRemaining(recovery, "errorFix")) {
+            action = recoveryForErrorDiagnosis(toolsAttached);
+        }
+        else if (budgetRemaining(recovery, "actionIntent") &&
+            input.planHasOpenWork &&
+            input.planApproved) {
+            action = recoveryForNarration(toolsAttached, "plan_open");
+        }
+        else if (budgetRemaining(recovery, "actionIntent") &&
+            input.pentestLikeTurn) {
+            action = recoveryForNarration(toolsAttached, "pentest");
+        }
+        else if (budgetRemaining(recovery, "actionIntent") &&
+            (input.freshWebSearchRequired || input.narratedWebAction)) {
+            action = recoveryForNarration(toolsAttached, "web");
+        }
+        else if (budgetRemaining(recovery, "actionIntent") &&
+            input.buildLikeTurn &&
+            (planNarrated || productiveSteps > 0)) {
+            action = recoveryForNarration(toolsAttached, "build_plan_prose");
+        }
+        else if (budgetRemaining(recovery, "actionIntent") &&
+            input.buildLikeTurn) {
+            action = recoveryForNarration(toolsAttached, "build");
+        }
+        else if (budgetRemaining(recovery, "actionIntent")) {
+            action = recoveryForNarration(toolsAttached, "generic");
+        }
+        if (action)
+            return action;
+    }
+    if (input.freshWebSearchRequired &&
+        !input.sawFreshWebSearch &&
+        budgetRemaining(recovery, "freshnessUsed")) {
+        return recoveryForFreshness(input.freshnessGuardText +
+            (toolsAttached
+                ? " Call the web_search tool now."
+                : " Reply with ONLY a fenced ```tool block for web.search now."));
+    }
+    if (input.isPlanMode &&
+        !input.informationalQuery &&
+        !input.idleOrSocialPrompt &&
+        budgetRemaining(recovery, "forcePlan")) {
+        if (!plan && !input.sawPlanCreateOk) {
+            return recoveryForMissingPlan(toolsAttached);
+        }
+    }
+    if (input.buildLike &&
+        !input.pentestLike &&
+        !input.pentestSession &&
+        input.planApproved &&
+        input.featureAppAsk &&
+        !input.sawFeatureImplWrite &&
+        (input.sawScaffoldOk || input.sawLocalAppMaterialWork) &&
+        productiveSteps > 0 &&
+        budgetRemaining(recovery, "featureImpl")) {
+        return recoveryForMissingFeature(input.projectRoot);
+    }
+    if (input.buildLike &&
+        !input.pentestLike &&
+        !input.pentestSession &&
+        budgetRemaining(recovery, "runtimeVerify") &&
+        (!input.featureAppAsk || input.sawFeatureImplWrite)) {
+        const planRuntimeOk = Boolean(plan && plan.hasVerifiedRuntime);
+        const sessionRuntimeOk = input.sawServerStart &&
+            (input.sawServerTail || input.sawLocalHttpProbe || planRuntimeOk);
+        if (!planRuntimeOk && !sessionRuntimeOk) {
+            const codingPlanFinished = Boolean(plan &&
+                input.planApproved &&
+                plan.kind !== "pentest" &&
+                plan.tasks.length > 0 &&
+                plan.tasks.every((task) => task.state === "done" || task.state === "skipped"));
+            const freestyleLocalAppDone = !input.planApproved &&
+                input.sawLocalAppMaterialWork &&
+                productiveSteps > 0 &&
+                freestyleClaimsAppReady(cleaned) &&
+                (input.projectRoot !== undefined ||
+                    /\b(?:npm|pnpm|yarn|bun)\s+run\s+dev\b/i.test(cleaned) ||
+                    /\bopen\s+http:\/\/localhost\b/i.test(cleaned));
+            if (codingPlanFinished || freestyleLocalAppDone) {
+                return recoveryForRuntimeVerify(input.projectRoot);
+            }
+        }
+    }
+    if (input.buildLike &&
+        !input.pentestLike &&
+        !input.pentestSession &&
+        input.sawFailedLocalHttpProbe &&
+        !input.sawLocalHttpProbe &&
+        budgetRemaining(recovery, "failedProbe") &&
+        cleaned.trim().length > 0) {
+        return recoveryForFailedProbe();
+    }
+    if ((input.pentestLike || input.pentestSession) &&
+        budgetRemaining(recovery, "shallowPentest") &&
+        looksLikeShallowPentestReport(cleaned, {
+            productiveSteps,
+            sawActiveTest: input.sawActivePentestTest,
+        })) {
+        return recoveryForShallowPentest();
+    }
+    if (input.planApproved && budgetRemaining(recovery, "prematureComplete")) {
+        const unfinished = plan?.tasks.filter((task) => !task.responderOwned &&
+            (task.state === "pending" || task.state === "in_progress"));
+        if (plan &&
+            unfinished &&
+            unfinished.length > 0 &&
+            !input.deferResponderReport) {
+            const next = unfinished[0];
+            return recoveryForPrematureComplete({
+                unfinished,
+                next,
+                pentest: plan.kind === "pentest" || input.pentestSession,
+                errorFix: errorFixNarration,
+            });
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=finalize-gate.js.map

package/dist/agent/finalize-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"finalize-gate.js","sourceRoot":"","sources":["../../src/agent/finalize-gate.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,6BAA6B,EAC7B,yBAAyB,EACzB,sBAAsB,EACtB,oBAAoB,EACpB,yBAAyB,EACzB,sBAAsB,EACtB,oBAAoB,EACpB,4BAA4B,EAC5B,wBAAwB,EACxB,yBAAyB,GAG1B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,oCAAoC,EACpC,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AAwD/B,MAAM,UAAU,sBAAsB,CACpC,KAAwB;IAExB,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,eAAe,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC;IAE1E,MAAM,YAAY,GAChB,CAAC,KAAK,CAAC,aAAa,IAAI,KAAK,CAAC,eAAe,CAAC;QAC9C,CAAC,KAAK,CAAC,gBAAgB;QACvB,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAClC,MAAM,iBAAiB,GACrB,CAAC,KAAK,CAAC,qBAAqB;QAC5B,oCAAoC,CAAC,OAAO,CAAC,CAAC;IAEhD,MAAM,2BAA2B,GAC/B,eAAe,KAAK,CAAC;QACrB,YAAY;QACZ,CAAC,CAAC,KAAK,CAAC,cAAc,IAAI,KAAK,CAAC,iBAAiB,CAAC;YAChD,CAAC,KAAK,CAAC,kBAAkB,CAAC;QAC5B,CAAC,KAAK,CAAC,YAAY;YACjB,KAAK,CAAC,eAAe;YACrB,CAAC,KAAK,CAAC,cAAc,IAAI,iBAAiB,CAAC,CAAC;QAC9C,CAAC,KAAK,CAAC,YAAY,IAAI,iBAAiB,CAAC;QACzC,CAAC,KAAK,CAAC,aAAa,IAAI,iBAAiB,CAAC,CAAC;IAC7C,IACE,KAAK,CAAC,WAAW;QACjB,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;QACzB,2BAA2B,EAC3B,CAAC;QACD,IAAI,MAAkC,CAAC;QACvC,IAAI,iBAAiB,IAAI,eAAe,CAAC,QAAQ,EAAE,UAAU,CAAC,EAAE,CAAC;YAC/D,MAAM,GAAG,yBAAyB,CAAC,aAAa,CAAC,CAAC;QACpD,CAAC;aAAM,IACL,eAAe,CAAC,QAAQ,EAAE,cAAc,CAAC;YACzC,KAAK,CAAC,eAAe;YACrB,KAAK,CAAC,YAAY,EAClB,CAAC;YACD,MAAM,GAAG,oBAAoB,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC;QAC5D,CAAC;aAAM,IACL,eAAe,CAAC,QAAQ,EAAE,cAAc,CAAC;YACzC,KAAK,CAAC,eAAe,EACrB,CAAC;YACD,MAAM,GAAG,oBAAoB,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;QAC1D,CAAC;aAAM,IACL,eAAe,CAAC,QAAQ,EAAE,cAAc,CAAC;YACzC,CAAC,KAAK,CAAC,sBAAsB,IAAI,KAAK,CAAC,iBAAiB,CAAC,EACzD,CAAC;YACD,MAAM,GAAG,oBAAoB,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;QACtD,CAAC;aAAM,IACL,eAAe,CAAC,QAAQ,EAAE,cAAc,CAAC;YACzC,KAAK,CAAC,aAAa;YACnB,CAAC,YAAY,IAAI,eAAe,GAAG,CAAC,CAAC,EACrC,CAAC;YACD,MAAM,GAAG,oBAAoB,CAAC,aAAa,EAAE,kBAAkB,CAAC,CAAC;QACnE,CAAC;aAAM,IACL,eAAe,CAAC,QAAQ,EAAE,cAAc,CAAC;YACzC,KAAK,CAAC,aAAa,EACnB,CAAC;YACD,MAAM,GAAG,oBAAoB,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;QACxD,CAAC;aAAM,IAAI,eAAe,CAAC,QAAQ,EAAE,cAAc,CAAC,EAAE,CAAC;YACrD,MAAM,GAAG,oBAAoB,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;QAC1D,CAAC;QACD,IAAI,MAAM;YAAE,OAAO,MAAM,CAAC;IAC5B,CAAC;IAED,IACE,KAAK,CAAC,sBAAsB;QAC5B,CAAC,KAAK,CAAC,iBAAiB;QACxB,eAAe,CAAC,QAAQ,EAAE,eAAe,CAAC,EAC1C,CAAC;QACD,OAAO,oBAAoB,CACzB,KAAK,CAAC,kBAAkB;YACxB,CAAC,aAAa;gBACZ,CAAC,CAAC,gCAAgC;gBAClC,CAAC,CAAC,6DAA6D,CAAC,CACnE,CAAC;IACJ,CAAC;IAED,IACE,KAAK,CAAC,UAAU;QAChB,CAAC,KAAK,CAAC,kBAAkB;QACzB,CAAC,KAAK,CAAC,kBAAkB;QACzB,eAAe,CAAC,QAAQ,EAAE,WAAW,CAAC,EACtC,CAAC;QACD,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,eAAe,EAAE,CAAC;YACpC,OAAO,sBAAsB,CAAC,aAAa,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IAED,IACE,KAAK,CAAC,SAAS;QACf,CAAC,KAAK,CAAC,WAAW;QAClB,CAAC,KAAK,CAAC,cAAc;QACrB,KAAK,CAAC,YAAY;QAClB,KAAK,CAAC,aAAa;QACnB,CAAC,KAAK,CAAC,mBAAmB;QAC1B,CAAC,KAAK,CAAC,aAAa,IAAI,KAAK,CAAC,uBAAuB,CAAC;QACtD,eAAe,GAAG,CAAC;QACnB,eAAe,CAAC,QAAQ,EAAE,aAAa,CAAC,EACxC,CAAC;QACD,OAAO,yBAAyB,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IACtD,CAAC;IAED,IACE,KAAK,CAAC,SAAS;QACf,CAAC,KAAK,CAAC,WAAW;QAClB,CAAC,KAAK,CAAC,cAAc;QACrB,eAAe,CAAC,QAAQ,EAAE,eAAe,CAAC;QAC1C,CAAC,CAAC,KAAK,CAAC,aAAa,IAAI,KAAK,CAAC,mBAAmB,CAAC,EACnD,CAAC;QACD,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC,kBAAkB,CAAC,CAAC;QAC/D,MAAM,gBAAgB,GACpB,KAAK,CAAC,cAAc;YACpB,CAAC,KAAK,CAAC,aAAa,IAAI,KAAK,CAAC,iBAAiB,IAAI,aAAa,CAAC,CAAC;QACpE,IAAI,CAAC,aAAa,IAAI,CAAC,gBAAgB,EAAE,CAAC;YACxC,MAAM,kBAAkB,GAAG,OAAO,CAChC,IAAI;gBACJ,KAAK,CAAC,YAAY;gBAClB,IAAI,CAAC,IAAI,KAAK,SAAS;gBACvB,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;gBACrB,IAAI,CAAC,KAAK,CAAC,KAAK,CACd,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,KAAK,MAAM,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,CAC5D,CACF,CAAC;YACF,MAAM,qBAAqB,GACzB,CAAC,KAAK,CAAC,YAAY;gBACnB,KAAK,CAAC,uBAAuB;gBAC7B,eAAe,GAAG,CAAC;gBACnB,uBAAuB,CAAC,OAAO,CAAC;gBAChC,CAAC,KAAK,CAAC,WAAW,KAAK,SAAS;oBAC9B,wCAAwC,CAAC,IAAI,CAAC,OAAO,CAAC;oBACtD,gCAAgC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;YACpD,IAAI,kBAAkB,IAAI,qBAAqB,EAAE,CAAC;gBAChD,OAAO,wBAAwB,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;YACrD,CAAC;QACH,CAAC;IACH,CAAC;IAED,IACE,KAAK,CAAC,SAAS;QACf,CAAC,KAAK,CAAC,WAAW;QAClB,CAAC,KAAK,CAAC,cAAc;QACrB,KAAK,CAAC,uBAAuB;QAC7B,CAAC,KAAK,CAAC,iBAAiB;QACxB,eAAe,CAAC,QAAQ,EAAE,aAAa,CAAC;QACxC,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EACzB,CAAC;QACD,OAAO,sBAAsB,EAAE,CAAC;IAClC,CAAC;IAED,IACE,CAAC,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC,cAAc,CAAC;QAC3C,eAAe,CAAC,QAAQ,EAAE,gBAAgB,CAAC;QAC3C,6BAA6B,CAAC,OAAO,EAAE;YACrC,eAAe;YACf,aAAa,EAAE,KAAK,CAAC,oBAAoB;SAC1C,CAAC,EACF,CAAC;QACD,OAAO,yBAAyB,EAAE,CAAC;IACrC,CAAC;IAED,IAAI,KAAK,CAAC,YAAY,IAAI,eAAe,CAAC,QAAQ,EAAE,mBAAmB,CAAC,EAAE,CAAC;QACzE,MAAM,UAAU,GAAG,IAAI,EAAE,KAAK,CAAC,MAAM,CACnC,CAAC,IAAI,EAAE,EAAE,CACP,CAAC,IAAI,CAAC,cAAc;YACpB,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,KAAK,aAAa,CAAC,CAC7D,CAAC;QACF,IACE,IAAI;YACJ,UAAU;YACV,UAAU,CAAC,MAAM,GAAG,CAAC;YACrB,CAAC,KAAK,CAAC,oBAAoB,EAC3B,CAAC;YACD,MAAM,IAAI,GAAG,UAAU,CAAC,CAAC,CAAE,CAAC;YAC5B,OAAO,4BAA4B,CAAC;gBAClC,UAAU;gBACV,IAAI;gBACJ,OAAO,EAAE,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,cAAc;gBACxD,QAAQ,EAAE,iBAAiB;aAC5B,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/agent/runner.js

@@ -64,7 +64,7 @@ import { resolveRequestBudget } from "./request-budget.js";
 import { loadPlan, mutatePlan, markTask, appendPlanTask, readyPlanTasks, foregroundRemaining, responderOpenTasks, isPlanTerminal, isPlanSuccessful, } from "../store/plan.js";
 import { stat } from "node:fs/promises";
 import { isOutsideWorkingDirectory, resolveFsToolPath, } from "../tools/fs.js";
-import { stripSentinelTokens, parseToolCall, recognizeBareToolJson, looksLikeTruncatedToolCall, salvageTruncatedWrite, salvageTruncatedWriteFromNative, countToolFences, parseAllToolCalls, groupToolCallsForExecution, buildTurnHistory, collapseRepeatedText, textBeforeToolCall, formatToolArgs, looksLikePentestTask, looksLikeBuildTask, looksLikeInformationalQuery, looksLikeIdleOrSocialPrompt, looksLikeActionNarration, looksLikeWebActionNarration, looksLikePlanNarration, looksLikeErrorDiagnosisWithFixIntent, localHttpProbeIsFailure, localHttpProbeIsSuccess, requiresFreshWebSearch, freshnessGuardMessage, buildWorkflowDirective, narrowNmapOperationDirective, pentestWorkflowDirective, pentestNoLocalServerDirective, shouldDimToolChatter, looksLikePromptLeak, } from "./tool-call-parser.js";
+import { stripSentinelTokens, parseToolCall, recognizeBareToolJson, looksLikeTruncatedToolCall, salvageTruncatedWrite, salvageTruncatedWriteFromNative, countToolFences, parseAllToolCalls, groupToolCallsForExecution, buildTurnHistory, collapseRepeatedText, textBeforeToolCall, formatToolArgs, looksLikePentestTask, looksLikeBuildTask, looksLikeInformationalQuery, looksLikeIdleOrSocialPrompt, looksLikeActionNarration, looksLikeWebActionNarration, localHttpProbeIsFailure, localHttpProbeIsSuccess, requiresFreshWebSearch, freshnessGuardMessage, buildWorkflowDirective, narrowNmapOperationDirective, pentestWorkflowDirective, pentestNoLocalServerDirective, shouldDimToolChatter, looksLikePromptLeak, } from "./tool-call-parser.js";
 import { createSessionPolicy, isPreApprovalAllowedTool, isPlanModeAllowedShellCommand, isPlanModeAllowedTool, isPlanApprovedByStatus, planHasOpenWork, isAbortError, shouldEnableImageOcr, } from "./session-policy.js";
 import { saveToolOutput, summarizeOutput, formatToolContext, } from "./tool-output-formatting.js";
 import { codingSessionFromContext, isProtocolPlaceholderOutput, progressPauseMode, } from "./progress-pause-policy.js";
@@ -75,13 +75,14 @@ import { absorbLooseWorkIntoLedger, applyDestinationCwd, canMarkTaskDone, hasLoc
 import { buildSessionStateBlock, inferNextHint, upsertSessionStateMessage, } from "./session-state.js";
 import { buildContinueOrientation, looksLikeContinueOrResumePrompt, } from "./continue-orient.js";
 import { detectPackageManager } from "./workspace-orient.js";
-import { budgetRemaining, consumeBudget, createRecoveryBudgets, freestyleClaimsAppReady, looksLikeShallowPentestReport, recoveryForErrorDiagnosis, recoveryForFailedProbe, recoveryForFreshness, recoveryForMissingFeature, recoveryForMissingPlan, recoveryForNarration, recoveryForPrematureComplete, recoveryForRuntimeVerify, recoveryForShallowPentest, } from "./must-continue.js";
+import { budgetRemaining, consumeBudget, createRecoveryBudgets, } from "./must-continue.js";
+import { chooseFinalizeRecovery } from "./finalize-gate.js";
 import { outOfScopeToolMessage, scopeContextMessage } from "./scope-context.js";
 import { EngagementPolicyEngine, actionFromUrl, engagementActionsForToolCall, evaluateEngagementAction, } from "../safety/engagement-policy.js";
 import { patchPlanMeta } from "../store/plan.js";
 import { extractProjectRootFromPlan, extractProjectRootFromScaffold, extractProjectRootFromText, getActiveProjectRoot, setActiveProjectRootIfValid, } from "./project-root.js";
 import { buildWorkspaceOrientation, discoverImmediateProjectRoots, guessProjectFolderName, isBareParentDirectory, isScaffoldCancelledOutput, scaffoldLooksMaterialized, scaffoldTargetConflictMessage, resolveScaffoldTargetPath, } from "./workspace-orient.js";
-import { inquirerConfirmPort, restoreInteractiveStdin, ensurePentestAuthorization, confirmToolExecution, } from "./confirm-port.js";
+import { inquirerConfirmPort, inquirerSecretRequester, restoreInteractiveStdin, ensurePentestAuthorization, confirmToolExecution, } from "./confirm-port.js";
 import { buildRichStopSummary } from "./stop-summary.js";
 import { composeAgentSystemPrompt } from "./prompt-composer.js";
 import { createGovernorState, governProgress, } from "./evidence-governor.js";
@@ -543,6 +544,9 @@ export async function runAgentTurn(prompt, options = {}) {
         // Request, project, workspace, recovery, scope, and plan state are appended
         // later as system-marked turns so a changing byte cannot invalidate the
         // constitution (and, on Anthropic, the native tool schemas before it).
+        // The red-team methodology block is ~940 tokens on every request. Attach it
+        // only when this turn is actually a remote-security engagement.
+        const pentestPromptTurn = pentestLikeTurn || activePlan?.kind === "pentest";
         const buildStableSystemContent = (native) => {
             const reliability = getReliabilityPolicy();
             const visionAvailable = modelSupportsVision(provider, model);
@@ -554,6 +558,7 @@ export async function runAgentTurn(prompt, options = {}) {
                 imageView: visionAvailable,
                 // E6: slim native constitution when API tool schemas are attached.
                 ...(native ? { slimNative: reliability.slimNativePrompt } : {}),
+                ...(pentestPromptTurn ? { pentest: true } : {}),
             });
         };
         const systemSections = [renderRequestEnvironmentContext()];
@@ -1633,9 +1638,17 @@ export async function runAgentTurn(prompt, options = {}) {
             if (isPlanMode &&
                 !session.planApproved.value &&
                 !isScratchOnlyWrite(call, scratchDir)) {
-                const cmd = typeof call.args.command === "string" ? call.args.command : "";
-                const shellBlocked = (call.name === "shell.exec" || call.name === "shell.start") &&
-                    !isPlanModeAllowedShellCommand(cmd);
+                const cmd = call.name === "terminal.send"
+                    ? typeof call.args.text === "string"
+                        ? call.args.text
+                        : ""
+                    : typeof call.args.command === "string"
+                        ? call.args.command
+                        : "";
+                const shellBlocked = call.name === "terminal.start" ||
+                    call.name === "terminal.send" ||
+                    ((call.name === "shell.exec" || call.name === "shell.start") &&
+                        !isPlanModeAllowedShellCommand(cmd));
                 const allowed = isPlanModeAllowedTool(call.name) && !shellBlocked;
                 if (!allowed) {
                     const reason = `plan mode — ${call.name} is blocked (gather-only). ` +
@@ -2078,7 +2091,7 @@ export async function runAgentTurn(prompt, options = {}) {
             const runToolWithForcedSettle = () => {
                 const work = runToolCall(call, {
                     signal: toolAc.signal,
-                    requestSecret: options.requestSecret,
+                    requestSecret: options.requestSecret ?? inquirerSecretRequester,
                     onOutput: (chunk) => {
                         if (toolAc.signal.aborted)
                             return;
@@ -4022,182 +4035,61 @@ export async function runAgentTurn(prompt, options = {}) {
                             "If analysis is incomplete, call only the bounded evidence tool needed now. If each result has been analyzed and is satisfactory, you MUST call job.read with its jobId or exact notificationId before giving a final response. job.read does not require an active plan; do not create or update a plan merely to acknowledge a result."));
                         continue;
                     }
-                    const planNarrated = (buildLikeTurn || pentestLikeTurn) &&
-                        !activePlan &&
-                        looksLikePlanNarration(cleaned);
-                    // Only force "diagnosed but not fixed" when the model is still
-                    // narrating a fix without having applied one this turn. Post-fix
-                    // summaries ("I've fixed…", build passed) must never re-enter.
-                    const errorFixNarration = !sawSuccessfulMutation &&
-                        looksLikeErrorDiagnosisWithFixIntent(cleaned);
-                    const shouldRetryBeforeFinalizing = productiveSteps === 0 ||
-                        planNarrated ||
-                        ((narratedAction || narratedWebAction) && !informationalQuery) ||
-                        (session.planApproved.value &&
-                            planHasOpenWorkNow &&
-                            (narratedAction || errorFixNarration)) ||
-                        // errorFix only when no mutation yet (gate is in errorFixNarration)
-                        (session.planApproved.value && errorFixNarration) ||
-                        (buildLikeTurn && errorFixNarration);
-                    if (wantsAction &&
-                        cleaned.trim().length > 0 &&
-                        shouldRetryBeforeFinalizing) {
-                        let action;
-                        if (errorFixNarration && budgetRemaining(recovery, "errorFix")) {
-                            action = recoveryForErrorDiagnosis(toolsAttached);
-                        }
-                        else if (budgetRemaining(recovery, "actionIntent") &&
-                            planHasOpenWorkNow &&
-                            session.planApproved.value) {
-                            action = recoveryForNarration(toolsAttached, "plan_open");
-                        }
-                        else if (budgetRemaining(recovery, "actionIntent") &&
-                            pentestLikeTurn) {
-                            action = recoveryForNarration(toolsAttached, "pentest");
-                        }
-                        else if (budgetRemaining(recovery, "actionIntent") &&
-                            (freshWebSearchRequired || narratedWebAction)) {
-                            action = recoveryForNarration(toolsAttached, "web");
-                        }
-                        else if (budgetRemaining(recovery, "actionIntent") &&
-                            buildLikeTurn &&
-                            (planNarrated || productiveSteps > 0)) {
-                            action = recoveryForNarration(toolsAttached, "build_plan_prose");
-                        }
-                        else if (budgetRemaining(recovery, "actionIntent") &&
-                            buildLikeTurn) {
-                            action = recoveryForNarration(toolsAttached, "build");
-                        }
-                        else if (budgetRemaining(recovery, "actionIntent")) {
-                            action = recoveryForNarration(toolsAttached, "generic");
-                        }
-                        if (action) {
-                            consumeBudget(recovery, action.budgetKey);
-                            commitAssistantRetry(assistantText.visible);
-                            messages.push(recoveryUserMessage(action.message));
-                            continue;
-                        }
-                    }
-                    if (freshWebSearchRequired &&
-                        !sawFreshWebSearch &&
-                        budgetRemaining(recovery, "freshnessUsed")) {
-                        const action = recoveryForFreshness(freshnessGuardMessage() +
-                            (toolsAttached
-                                ? " Call the web_search tool now."
-                                : " Reply with ONLY a fenced ```tool block for web.search now."));
-                        consumeBudget(recovery, action.budgetKey);
-                        commitAssistantRetry(assistantText.visible);
-                        messages.push(recoveryUserMessage(action.message));
-                        continue;
-                    }
-                    if (isPlanMode &&
-                        !informationalQuery &&
-                        !idleOrSocialPrompt &&
-                        budgetRemaining(recovery, "forcePlan")) {
-                        const planAtEnd = await loadPlan(session.sessionId).catch(() => undefined);
-                        if (!planAtEnd && !sawPlanCreateOk) {
-                            const action = recoveryForMissingPlan(toolsAttached);
-                            consumeBudget(recovery, action.budgetKey);
-                            commitAssistantRetry(assistantText.visible);
-                            messages.push(recoveryUserMessage(action.message));
-                            continue;
-                        }
-                    }
-                    if (buildLike &&
-                        !pentestLike &&
-                        !pentestSession &&
-                        session.planApproved.value &&
-                        featureAppAsk &&
-                        !sawFeatureImplWrite &&
-                        (sawScaffoldOk || sawLocalAppMaterialWork) &&
-                        productiveSteps > 0 &&
-                        budgetRemaining(recovery, "featureImpl")) {
-                        const action = recoveryForMissingFeature(getActiveProjectRoot());
-                        consumeBudget(recovery, action.budgetKey);
-                        commitAssistantRetry(assistantText.visible);
-                        messages.push(recoveryUserMessage(action.message));
-                        continue;
-                    }
-                    if (buildLike &&
-                        !pentestLike &&
-                        !pentestSession &&
-                        budgetRemaining(recovery, "runtimeVerify") &&
-                        (!featureAppAsk || sawFeatureImplWrite)) {
-                        const runtimePlan = await loadPlan(session.sessionId).catch(() => undefined);
-                        // Durable plan evidence or multi-signal proof this turn is enough
-                        const planRuntimeOk = Boolean(runtimePlan && planHasVerifiedRuntime(runtimePlan));
-                        const sessionRuntimeOk = sawServerStart &&
-                            (sawServerTail || sawLocalHttpProbe || planRuntimeOk);
-                        if (!planRuntimeOk && !sessionRuntimeOk) {
-                            const codingPlanFinished = Boolean(runtimePlan &&
-                                session.planApproved.value &&
-                                runtimePlan.kind !== "pentest" &&
-                                runtimePlan.tasks.length > 0 &&
-                                runtimePlan.tasks.every((task) => task.state === "done" || task.state === "skipped"));
-                            const freestyleLocalAppDone = !session.planApproved.value &&
-                                sawLocalAppMaterialWork &&
-                                productiveSteps > 0 &&
-                                freestyleClaimsAppReady(cleaned) &&
-                                (getActiveProjectRoot() !== undefined ||
-                                    /\b(?:npm|pnpm|yarn|bun)\s+run\s+dev\b/i.test(cleaned) ||
-                                    /\bopen\s+http:\/\/localhost\b/i.test(cleaned));
-                            if (codingPlanFinished || freestyleLocalAppDone) {
-                                const action = recoveryForRuntimeVerify(getActiveProjectRoot());
-                                consumeBudget(recovery, action.budgetKey);
-                                commitAssistantRetry(assistantText.visible);
-                                messages.push(recoveryUserMessage(action.message));
-                                continue;
+                    const deferResponderReport = session.planApproved.value &&
+                        budgetRemaining(recovery, "prematureComplete")
+                        ? shouldYieldForDeclaredResponderDependency(livePlanAtCompletion, jobManager.getRunningJobs(session.sessionId), jobManager.getPendingNotifications(session.sessionId), responderWakeNotificationId)
+                        : false;
+                    const finalizeRecovery = chooseFinalizeRecovery({
+                        cleaned,
+                        recovery,
+                        toolsAttached,
+                        productiveSteps,
+                        planApproved: session.planApproved.value,
+                        planHasOpenWork: planHasOpenWorkNow,
+                        activePlanExists: Boolean(activePlan),
+                        wantsAction,
+                        narratedAction,
+                        narratedWebAction,
+                        isPlanMode,
+                        buildLikeTurn,
+                        pentestLikeTurn,
+                        buildLike,
+                        pentestLike,
+                        pentestSession,
+                        informationalQuery,
+                        idleOrSocialPrompt,
+                        freshWebSearchRequired,
+                        freshnessGuardText: freshWebSearchRequired
+                            ? freshnessGuardMessage()
+                            : "",
+                        sawFreshWebSearch,
+                        sawPlanCreateOk,
+                        sawFeatureImplWrite,
+                        sawScaffoldOk,
+                        sawLocalAppMaterialWork,
+                        sawServerStart,
+                        sawServerTail,
+                        sawLocalHttpProbe,
+                        sawFailedLocalHttpProbe,
+                        sawActivePentestTest,
+                        sawSuccessfulMutation,
+                        featureAppAsk,
+                        projectRoot: getActiveProjectRoot(),
+                        plan: livePlanAtCompletion
+                            ? {
+                                kind: livePlanAtCompletion.kind,
+                                hasVerifiedRuntime: planHasVerifiedRuntime(livePlanAtCompletion),
+                                tasks: livePlanAtCompletion.tasks,
                             }
-                        }
-                    }
-                    if (buildLike &&
-                        !pentestLike &&
-                        !pentestSession &&
-                        sawFailedLocalHttpProbe &&
-                        !sawLocalHttpProbe &&
-                        budgetRemaining(recovery, "failedProbe") &&
-                        cleaned.trim().length > 0) {
-                        const action = recoveryForFailedProbe();
-                        consumeBudget(recovery, action.budgetKey);
-                        commitAssistantRetry(assistantText.visible);
-                        messages.push(recoveryUserMessage(action.message));
-                        continue;
-                    }
-                    if ((pentestLike || pentestSession) &&
-                        budgetRemaining(recovery, "shallowPentest") &&
-                        looksLikeShallowPentestReport(cleaned, {
-                            productiveSteps,
-                            sawActiveTest: sawActivePentestTest,
-                        })) {
-                        const action = recoveryForShallowPentest();
-                        consumeBudget(recovery, action.budgetKey);
+                            : undefined,
+                        deferResponderReport,
+                    });
+                    if (finalizeRecovery) {
+                        consumeBudget(recovery, finalizeRecovery.budgetKey);
                         commitAssistantRetry(assistantText.visible);
-                        messages.push(recoveryUserMessage(action.message));
+                        messages.push(recoveryUserMessage(finalizeRecovery.message));
                         continue;
                     }
-                    if (session.planApproved.value &&
-                        budgetRemaining(recovery, "prematureComplete")) {
-                        const livePlan = await loadPlan(session.sessionId).catch(() => undefined);
-                        const unfinished = livePlan?.tasks.filter((task) => !task.responderOwned &&
-                            (task.state === "pending" || task.state === "in_progress"));
-                        const deferReport = shouldYieldForDeclaredResponderDependency(livePlan, jobManager.getRunningJobs(session.sessionId), jobManager.getPendingNotifications(session.sessionId), responderWakeNotificationId);
-                        if (livePlan &&
-                            unfinished &&
-                            unfinished.length > 0 &&
-                            !deferReport) {
-                            const next = unfinished[0];
-                            const action = recoveryForPrematureComplete({
-                                unfinished,
-                                next,
-                                pentest: livePlan.kind === "pentest" || pentestSession,
-                                errorFix: errorFixNarration,
-                            });
-                            consumeBudget(recovery, action.budgetKey);
-                            commitAssistantRetry(assistantText.visible);
-                            messages.push(recoveryUserMessage(action.message));
-                            continue;
-                        }
-                    }
                     let outcomeStatus = "succeeded";
                     const remainingCriteria = [];
                     if (session.planApproved.value) {