@pentoshi/clai 4.11.5 → 4.11.8

package/dist/agent/turn/tool-execution/engagement-gate.js

@@ -0,0 +1,55 @@
+import { outOfScopeToolMessage } from "../../scope-context.js";
+import { evaluateEngagementAction } from "../../../safety/engagement-policy.js";
+import { beginEngagementAction, openEngagement, saveEngagement, } from "../../../store/engagement.js";
+export const evaluateEngagementGate = async (ports, call, actions, scopeTarget) => {
+    const primary = actions[0];
+    let decision;
+    let graph;
+    let record;
+    for (const action of actions) {
+        const actionDecision = evaluateEngagementAction(ports.scope, action);
+        if (!actionDecision)
+            continue;
+        if (action === primary)
+            decision = actionDecision;
+        if (ports.scope) {
+            graph = await openEngagement(ports.scope);
+            record = beginEngagementAction(graph, {
+                tool: call.name,
+                target: actionDecision.normalizedTarget || action.target,
+                phase: actionDecision.phase,
+                capability: actionDecision.capability,
+                authorized: actionDecision.allowed,
+                reason: actionDecision.reason,
+            });
+            await saveEngagement(graph);
+        }
+        await ports.audit("engagement.policy", {
+            ...(graph ? { engagementId: graph.id } : {}),
+            ...(record ? { actionId: record.id } : {}),
+            tool: call.name,
+            target: actionDecision.normalizedTarget,
+            phase: actionDecision.phase,
+            capability: actionDecision.capability,
+            allowed: actionDecision.allowed,
+            reason: actionDecision.reason,
+        });
+        if (actionDecision.allowed)
+            continue;
+        return {
+            blockedReason: outOfScopeToolMessage({
+                target: actionDecision.normalizedTarget ||
+                    action.target ||
+                    scopeTarget ||
+                    "requested target",
+                reason: actionDecision.reason,
+                allowed: ports.scope?.authorizedTargets,
+            }),
+            decision,
+            graph,
+            record,
+        };
+    }
+    return { blockedReason: undefined, decision, graph, record };
+};
+//# sourceMappingURL=engagement-gate.js.map

package/dist/agent/turn/tool-execution/engagement-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engagement-gate.js","sourceRoot":"","sources":["../../../../src/agent/turn/tool-execution/engagement-gate.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,wBAAwB,EAAE,MAAM,sCAAsC,CAAC;AAChF,OAAO,EACL,qBAAqB,EACrB,cAAc,EACd,cAAc,GAGf,MAAM,8BAA8B,CAAC;AAiBtC,MAAM,CAAC,MAAM,sBAAsB,GAAG,KAAK,EACzC,KAA0B,EAC1B,IAAc,EACd,OAAoC,EACpC,WAA+B,EACC,EAAE;IAClC,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3B,IAAI,QAAiE,CAAC;IACtE,IAAI,KAAkC,CAAC;IACvC,IAAI,MAA0C,CAAC;IAE/C,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,cAAc,GAAG,wBAAwB,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QACrE,IAAI,CAAC,cAAc;YAAE,SAAS;QAC9B,IAAI,MAAM,KAAK,OAAO;YAAE,QAAQ,GAAG,cAAc,CAAC;QAClD,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;YAChB,KAAK,GAAG,MAAM,cAAc,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC1C,MAAM,GAAG,qBAAqB,CAAC,KAAK,EAAE;gBACpC,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,MAAM,EAAE,cAAc,CAAC,gBAAgB,IAAI,MAAM,CAAC,MAAM;gBACxD,KAAK,EAAE,cAAc,CAAC,KAAK;gBAC3B,UAAU,EAAE,cAAc,CAAC,UAAU;gBACrC,UAAU,EAAE,cAAc,CAAC,OAAO;gBAClC,MAAM,EAAE,cAAc,CAAC,MAAM;aAC9B,CAAC,CAAC;YACH,MAAM,cAAc,CAAC,KAAK,CAAC,CAAC;QAC9B,CAAC;QACD,MAAM,KAAK,CAAC,KAAK,CAAC,mBAAmB,EAAE;YACrC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5C,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1C,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,MAAM,EAAE,cAAc,CAAC,gBAAgB;YACvC,KAAK,EAAE,cAAc,CAAC,KAAK;YAC3B,UAAU,EAAE,cAAc,CAAC,UAAU;YACrC,OAAO,EAAE,cAAc,CAAC,OAAO;YAC/B,MAAM,EAAE,cAAc,CAAC,MAAM;SAC9B,CAAC,CAAC;QACH,IAAI,cAAc,CAAC,OAAO;YAAE,SAAS;QACrC,OAAO;YACL,aAAa,EAAE,qBAAqB,CAAC;gBACnC,MAAM,EACJ,cAAc,CAAC,gBAAgB;oBAC/B,MAAM,CAAC,MAAM;oBACb,WAAW;oBACX,kBAAkB;gBACpB,MAAM,EAAE,cAAc,CAAC,MAAM;gBAC7B,OAAO,EAAE,KAAK,CAAC,KAAK,EAAE,iBAAiB;aACxC,CAAC;YACF,QAAQ;YACR,KAAK;YACL,MAAM;SACP,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;AAC/D,CAAC,CAAC"}

package/dist/agent/turn/tool-execution/gates.d.ts

@@ -0,0 +1,21 @@
+import type { ToolCall, ToolResult } from "../../../types.js";
+import type { SessionPlan } from "../../../store/plan.js";
+import type { SingleToolResult } from "../contracts.js";
+export interface ToolGateStagePorts {
+    readonly isPlanMode: boolean;
+    readonly planApproved: () => boolean;
+    readonly scratchDir: string;
+    readonly mcpSafe: (call: ToolCall) => boolean;
+    readonly loadPlan: () => Promise<SessionPlan | undefined>;
+    readonly notify: (level: "info" | "warn", message: string) => void;
+    readonly showCall: (call: ToolCall) => void;
+    readonly emitToolResult: (result: ToolResult, contextOutput: string) => void;
+    readonly writeToolOutput: (chunk: string) => void;
+}
+export type ToolGateDecision = {
+    readonly kind: "proceed";
+} | {
+    readonly kind: "stop";
+    readonly result: SingleToolResult;
+};
+export declare const runToolGates: (ports: ToolGateStagePorts, call: ToolCall, level: "safe" | "confirm" | "block", livePlan: SessionPlan | undefined) => Promise<ToolGateDecision>;

package/dist/agent/turn/tool-execution/gates.js

@@ -0,0 +1,45 @@
+import { isPreApprovalAllowedTool, } from "../../session-policy.js";
+import { isScratchOnlyWrite } from "../../scratch-write.js";
+import { decidePlanModeGate } from "../plan-mode-gate.js";
+export const runToolGates = async (ports, call, level, livePlan) => {
+    const planModeGate = decidePlanModeGate({
+        call,
+        isPlanMode: ports.isPlanMode,
+        planApproved: ports.planApproved(),
+        scratchDir: ports.scratchDir,
+        mcpSafe: ports.mcpSafe(call),
+    });
+    if (planModeGate.blocked) {
+        const reason = planModeGate.reason;
+        ports.notify("warn", reason);
+        ports.showCall(call);
+        const result = { ok: false, output: reason, exitCode: 1 };
+        ports.emitToolResult(result, reason);
+        ports.writeToolOutput("failed\n");
+        return {
+            kind: "stop",
+            result: { ok: false, call, result, contextOutput: reason },
+        };
+    }
+    const isMutatingAction = (level === "confirm" || level === "block") &&
+        !isPreApprovalAllowedTool(call.name) &&
+        !isScratchOnlyWrite(call, ports.scratchDir);
+    if (!isMutatingAction)
+        return { kind: "proceed" };
+    const planNow = livePlan ?? (await ports.loadPlan());
+    if (!planNow || ports.planApproved())
+        return { kind: "proceed" };
+    const reason = `plan awaiting approval — ${call.name} is blocked until the plan is accepted (/implement or Accept)`;
+    ports.notify("warn", reason);
+    return {
+        kind: "stop",
+        result: {
+            ok: false,
+            call,
+            result: { ok: false, output: reason, exitCode: 1 },
+            contextOutput: reason,
+            blockOrCancel: true,
+        },
+    };
+};
+//# sourceMappingURL=gates.js.map

package/dist/agent/turn/tool-execution/gates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gates.js","sourceRoot":"","sources":["../../../../src/agent/turn/tool-execution/gates.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,wBAAwB,GACzB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAkB1D,MAAM,CAAC,MAAM,YAAY,GAAG,KAAK,EAC/B,KAAyB,EACzB,IAAc,EACd,KAAmC,EACnC,QAAiC,EACN,EAAE;IAC7B,MAAM,YAAY,GAAG,kBAAkB,CAAC;QACtC,IAAI;QACJ,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,YAAY,EAAE,KAAK,CAAC,YAAY,EAAE;QAClC,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;KAC7B,CAAC,CAAC;IACH,IAAI,YAAY,CAAC,OAAO,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC;QACnC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC7B,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACrB,MAAM,MAAM,GAAe,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;QACtE,KAAK,CAAC,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACrC,KAAK,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC;QAClC,OAAO;YACL,IAAI,EAAE,MAAM;YACZ,MAAM,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE;SAC3D,CAAC;IACJ,CAAC;IAED,MAAM,gBAAgB,GACpB,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,OAAO,CAAC;QAC1C,CAAC,wBAAwB,CAAC,IAAI,CAAC,IAAI,CAAC;QACpC,CAAC,kBAAkB,CAAC,IAAI,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;IAC9C,IAAI,CAAC,gBAAgB;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IAElD,MAAM,OAAO,GAAG,QAAQ,IAAI,CAAC,MAAM,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;IACrD,IAAI,CAAC,OAAO,IAAI,KAAK,CAAC,YAAY,EAAE;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IACjE,MAAM,MAAM,GAAG,4BAA4B,IAAI,CAAC,IAAI,+DAA+D,CAAC;IACpH,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,MAAM,EAAE;YACN,EAAE,EAAE,KAAK;YACT,IAAI;YACJ,MAAM,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE;YAClD,aAAa,EAAE,MAAM;YACrB,aAAa,EAAE,IAAI;SACpB;KACF,CAAC;AACJ,CAAC,CAAC"}

package/dist/agent/turn/tool-execution/guards.d.ts

@@ -0,0 +1,42 @@
+import type { ToolCall } from "../../../types.js";
+export interface LoopGuardVerdict {
+    readonly block: boolean;
+    readonly kind?: string | undefined;
+    readonly reason?: string | undefined;
+}
+export interface ToolGuardInput {
+    readonly call: ToolCall;
+    readonly narrowNmapOperation: boolean;
+    readonly narrowNmapDispatched: number;
+    readonly heldBatchReminder: string | undefined;
+}
+export interface ToolGuardLoopInput {
+    readonly verdict: LoopGuardVerdict;
+    readonly priorObservation: string | undefined;
+}
+export type ToolGuardDecision = {
+    readonly kind: "proceed";
+    readonly consumesNarrowNmapScan: boolean;
+} | {
+    readonly kind: "reject";
+    readonly reason: string;
+} | {
+    readonly kind: "hold";
+    readonly reason: string;
+} | {
+    readonly kind: "reuse";
+    readonly reason: string;
+} | {
+    readonly kind: "warn-reject";
+    readonly reason: string;
+} | {
+    readonly kind: "loop-reset";
+};
+export interface RetryReason {
+    readonly code: string;
+    readonly detail: string;
+}
+export declare const readRetryReason: (args: Record<string, unknown>) => RetryReason | undefined;
+export declare const evaluateToolGuards: (input: ToolGuardInput) => ToolGuardDecision;
+export declare const evaluateLoopGuardBlock: (call: ToolCall, loop: ToolGuardLoopInput) => ToolGuardDecision;
+export declare const LOOP_RESET_OUTPUT = "Loop guard counters reset. You may re-run commands freely.";

package/dist/agent/turn/tool-execution/guards.js

@@ -0,0 +1,62 @@
+const NARROW_NMAP_ALLOWED = new Set([
+    "net.scan",
+    "shell.tail",
+    "shell.jobs",
+    "job.read",
+    "task.read",
+]);
+export const readRetryReason = (args) => {
+    const raw = args._retryReason;
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const record = raw;
+    return {
+        code: String(record.code ?? ""),
+        detail: String(record.detail ?? ""),
+    };
+};
+const narrowNmapRejection = (toolName) => `Narrow nmap request: ${toolName} was not run because the user requested only one nmap operation. ` +
+    `Call net.scan with the requested target/options; do not create a plan or add DNS, WHOIS, HTTP, recon, or vulnerability steps.`;
+const NARROW_NMAP_REPEAT = "Narrow nmap request: a scan has already been dispatched this turn. " +
+    "Do not broaden or retry it automatically; report the existing result/job status and ask before another scan.";
+const checkNarrowNmap = (input) => {
+    if (!NARROW_NMAP_ALLOWED.has(input.call.name)) {
+        return { kind: "reject", reason: narrowNmapRejection(input.call.name) };
+    }
+    if (input.call.name === "net.scan") {
+        if (input.narrowNmapDispatched >= 1) {
+            return { kind: "reject", reason: NARROW_NMAP_REPEAT };
+        }
+        return { kind: "proceed", consumesNarrowNmapScan: true };
+    }
+    return { kind: "proceed", consumesNarrowNmapScan: false };
+};
+export const evaluateToolGuards = (input) => {
+    if (input.narrowNmapOperation) {
+        const narrow = checkNarrowNmap(input);
+        if (narrow.kind !== "proceed")
+            return narrow;
+        if (input.heldBatchReminder !== undefined) {
+            return { kind: "hold", reason: input.heldBatchReminder };
+        }
+        return narrow;
+    }
+    if (input.heldBatchReminder !== undefined) {
+        return { kind: "hold", reason: input.heldBatchReminder };
+    }
+    return { kind: "proceed", consumesNarrowNmapScan: false };
+};
+export const evaluateLoopGuardBlock = (call, loop) => {
+    if (!loop.verdict.block)
+        return { kind: "proceed", consumesNarrowNmapScan: false };
+    const baseReason = loop.verdict.reason ??
+        `${call.name} previously failed with identical arguments. Change the command/args and retry.`;
+    const reason = loop.verdict.kind === "unchanged-success" && loop.priorObservation
+        ? `${baseReason}\n\nPrior successful result (reuse this; it is the result of the requested call):\n${loop.priorObservation}`
+        : baseReason;
+    return loop.verdict.kind === "unchanged-success"
+        ? { kind: "reuse", reason }
+        : { kind: "warn-reject", reason };
+};
+export const LOOP_RESET_OUTPUT = "Loop guard counters reset. You may re-run commands freely.";
+//# sourceMappingURL=guards.js.map

package/dist/agent/turn/tool-execution/guards.js.map

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

package/dist/agent/turn/tool-execution/meta-tools.d.ts

@@ -0,0 +1,50 @@
+import type { ToolCall, ToolResult } from "../../../types.js";
+import type { SessionPlan, TaskEvidence } from "../../../store/plan.js";
+import type { ResponderNotification } from "../../../tools/jobs.js";
+import type { LooseWorkReceipt, TaskWorkLedger } from "../../task-evidence.js";
+import type { SingleToolResult } from "../contracts.js";
+import { type ResponderReadWakeIdentity } from "../responder-read-tool.js";
+import { type TaskUpdateGateResult } from "../task-update-gate.js";
+export interface MetaToolPlanResult {
+    readonly handled: boolean;
+    readonly ok: boolean;
+    readonly reminder?: boolean | undefined;
+    readonly toast?: string | undefined;
+    readonly cleared?: boolean | undefined;
+    readonly modelNote: string;
+    readonly plan?: SessionPlan | undefined;
+}
+export interface MetaToolPorts {
+    readonly step: number;
+    readonly wake: ResponderReadWakeIdentity;
+    readonly pendingNotifications: () => readonly ResponderNotification[];
+    readonly matchesWakeRevision: (notification: ResponderNotification) => boolean;
+    readonly isClaimed: (notificationId: string) => boolean;
+    readonly markRead: (notificationId: string) => boolean;
+    readonly releaseClaim: (notificationId: string) => void;
+    readonly queueResponderLedger: (notification: ResponderNotification) => void;
+    readonly loadPlan: () => Promise<SessionPlan | undefined>;
+    readonly completionGate: (plan: SessionPlan, taskId: string) => TaskUpdateGateResult;
+    readonly handlePlanTool: (call: ToolCall) => Promise<MetaToolPlanResult>;
+    readonly recordAttempt: (call: ToolCall, ok: boolean) => void;
+    readonly showCall: (call: ToolCall) => void;
+    readonly notify: (level: "info" | "warn", message: string) => void;
+    readonly emitToolResult: (result: ToolResult, contextOutput: string) => void;
+    readonly writeToolOutput: (chunk: string) => void;
+    readonly renderPlan: (plan: SessionPlan) => void;
+    readonly adoptProjectRoot: (plan: SessionPlan) => void;
+    readonly setPendingSessionStatePlan: (plan: SessionPlan | null) => void;
+    readonly clearPlanContext: () => void;
+    readonly getLedger: () => TaskWorkLedger | null;
+    readonly setLedger: (ledger: TaskWorkLedger | null) => void;
+    readonly looseWork: () => readonly LooseWorkReceipt[];
+    readonly persistTaskEvidence: (taskId: string, evidence: TaskEvidence) => Promise<void>;
+}
+export type MetaToolOutcome = {
+    readonly kind: "not-meta";
+} | {
+    readonly kind: "handled";
+    readonly result: SingleToolResult;
+};
+export declare const isRunnerMetaTool: (name: string) => boolean;
+export declare const runMetaTool: (ports: MetaToolPorts, call: ToolCall) => Promise<MetaToolOutcome>;

package/dist/agent/turn/tool-execution/meta-tools.js

@@ -0,0 +1,114 @@
+import { RUNNER_META_TOOL_NAMES } from "../../../tools/definitions.js";
+import { resolvePlanTaskId } from "../../plan-tool.js";
+import { decideResponderRead, parseResponderReadRequest, } from "../responder-read-tool.js";
+import { decideTaskUpdateDoneGate, parseTaskUpdateRequest, } from "../task-update-gate.js";
+import { applyTaskUpdateLedgerTransition } from "./plan-tool-ledger.js";
+export const isRunnerMetaTool = (name) => RUNNER_META_TOOL_NAMES.has(name);
+const handleResponderRead = (ports, call) => {
+    const decision = decideResponderRead(parseResponderReadRequest(call.name, call.args), ports.wake, {
+        pendingNotifications: ports.pendingNotifications(),
+        matchesWakeRevision: ports.matchesWakeRevision,
+        isClaimed: ports.isClaimed,
+        markRead: ports.markRead,
+    });
+    if (decision.ledgerNotification) {
+        ports.queueResponderLedger(decision.ledgerNotification);
+    }
+    if (decision.releaseClaimId)
+        ports.releaseClaim(decision.releaseClaimId);
+    ports.showCall(call);
+    const result = {
+        ok: decision.marked,
+        output: decision.output,
+        ...(decision.marked ? {} : { exitCode: 1 }),
+    };
+    ports.recordAttempt(call, decision.marked);
+    ports.emitToolResult(result, decision.output);
+    ports.writeToolOutput(decision.marked ? "read\n" : "failed\n");
+    return {
+        kind: "handled",
+        result: {
+            ok: decision.marked,
+            call,
+            result,
+            contextOutput: decision.output,
+        },
+    };
+};
+const rejectTaskUpdate = (ports, call, reason) => {
+    ports.notify("warn", reason);
+    ports.showCall(call);
+    const result = { ok: false, output: reason, exitCode: 1 };
+    ports.emitToolResult(result, reason);
+    ports.writeToolOutput("failed\n");
+    return {
+        kind: "handled",
+        result: { ok: false, call, result, contextOutput: reason },
+    };
+};
+const checkTaskUpdateGate = async (ports, call) => {
+    const request = parseTaskUpdateRequest(call.args);
+    if (request.state !== "done" || !request.taskId)
+        return { kind: "not-meta" };
+    const live = await ports.loadPlan();
+    const resolved = (live ? resolvePlanTaskId(live, request.taskId) : undefined) ??
+        request.taskId;
+    const gate = decideTaskUpdateDoneGate(live, resolved, ports.completionGate);
+    return gate.ok ? { kind: "not-meta" } : rejectTaskUpdate(ports, call, gate.reason);
+};
+const applyPlanResult = async (ports, call, planResult) => {
+    if (!planResult.reminder)
+        ports.recordAttempt(call, planResult.ok);
+    if (planResult.ok && call.name === "task.update") {
+        await applyTaskUpdateLedgerTransition({
+            getLedger: ports.getLedger,
+            setLedger: ports.setLedger,
+            looseWork: ports.looseWork,
+            persistTaskEvidence: ports.persistTaskEvidence,
+        }, call, planResult.plan);
+    }
+    if (planResult.ok && planResult.plan) {
+        ports.setPendingSessionStatePlan(planResult.plan);
+    }
+    ports.showCall(call);
+    if (planResult.reminder && planResult.toast) {
+        ports.notify("warn", planResult.toast);
+    }
+    if (planResult.plan) {
+        ports.renderPlan(planResult.plan);
+        ports.adoptProjectRoot(planResult.plan);
+    }
+    if (planResult.ok && planResult.cleared) {
+        ports.setPendingSessionStatePlan(null);
+        ports.clearPlanContext();
+    }
+    const result = {
+        ok: planResult.ok,
+        output: planResult.modelNote,
+    };
+    ports.emitToolResult(result, planResult.modelNote);
+    ports.writeToolOutput(result.ok ? "ok\n" : "failed\n");
+    return {
+        ok: planResult.ok,
+        call,
+        result,
+        contextOutput: planResult.modelNote,
+    };
+};
+export const runMetaTool = async (ports, call) => {
+    if (!isRunnerMetaTool(call.name))
+        return { kind: "not-meta" };
+    if (call.name === "job.read" || call.name === "task.read") {
+        return handleResponderRead(ports, call);
+    }
+    if (call.name === "task.update") {
+        const gate = await checkTaskUpdateGate(ports, call);
+        if (gate.kind === "handled")
+            return gate;
+    }
+    const planResult = await ports.handlePlanTool(call);
+    if (!planResult.handled)
+        return { kind: "not-meta" };
+    return { kind: "handled", result: await applyPlanResult(ports, call, planResult) };
+};
+//# sourceMappingURL=meta-tools.js.map

package/dist/agent/turn/tool-execution/meta-tools.js.map

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

package/dist/agent/turn/tool-execution/plan-tool-ledger.d.ts

@@ -0,0 +1,10 @@
+import type { ToolCall } from "../../../types.js";
+import type { SessionPlan, TaskEvidence } from "../../../store/plan.js";
+import { type LooseWorkReceipt, type TaskWorkLedger } from "../../task-evidence.js";
+export interface PlanToolLedgerPorts {
+    readonly getLedger: () => TaskWorkLedger | null;
+    readonly setLedger: (ledger: TaskWorkLedger | null) => void;
+    readonly looseWork: () => readonly LooseWorkReceipt[];
+    readonly persistTaskEvidence: (taskId: string, evidence: TaskEvidence) => Promise<void>;
+}
+export declare const applyTaskUpdateLedgerTransition: (ports: PlanToolLedgerPorts, call: ToolCall, plan: SessionPlan | undefined) => Promise<void>;

package/dist/agent/turn/tool-execution/plan-tool-ledger.js

@@ -0,0 +1,50 @@
+import { absorbLooseWorkIntoLedger, ledgerFromTaskEvidence, taskEvidenceFromLedger, } from "../../task-evidence.js";
+import { resolvePlanTaskId } from "../../plan-tool.js";
+const openTaskLedger = async (ports, plan, taskId) => {
+    const persisted = plan?.tasks.find((task) => task.id === taskId);
+    const live = ports.getLedger();
+    const base = live?.taskId === taskId
+        ? live
+        : ledgerFromTaskEvidence(taskId, persisted?.evidence);
+    const ledger = absorbLooseWorkIntoLedger(base, taskId, persisted?.title ?? "", ports.looseWork(), { planKind: plan?.kind }) ?? base;
+    ports.setLedger(ledger);
+    if (plan && ledger && ledger.successWorkCount > 0 && persisted) {
+        persisted.evidence = taskEvidenceFromLedger(ledger);
+        await ports.persistTaskEvidence(persisted.id, persisted.evidence);
+    }
+};
+const completeTaskLedger = async (ports, plan, taskId) => {
+    const ledger = ports.getLedger();
+    if (plan && ledger?.taskId === taskId) {
+        const task = plan.tasks.find((candidate) => candidate.id === taskId);
+        if (task) {
+            task.evidence = taskEvidenceFromLedger(ledger);
+            await ports.persistTaskEvidence(task.id, task.evidence);
+        }
+    }
+    ports.setLedger(null);
+};
+export const applyTaskUpdateLedgerTransition = async (ports, call, plan) => {
+    const state = typeof call.args.state === "string" ? call.args.state : "";
+    const requested = typeof call.args.taskId === "string"
+        ? call.args.taskId
+        : typeof call.args.id === "string"
+            ? call.args.id
+            : "";
+    const taskId = (plan ? resolvePlanTaskId(plan, requested) : undefined) ?? requested;
+    if (!taskId)
+        return;
+    if (state === "in_progress") {
+        await openTaskLedger(ports, plan, taskId);
+        return;
+    }
+    if (state === "done") {
+        await completeTaskLedger(ports, plan, taskId);
+        return;
+    }
+    if (state !== "failed" && state !== "skipped")
+        return;
+    if (ports.getLedger()?.taskId === taskId)
+        ports.setLedger(null);
+};
+//# sourceMappingURL=plan-tool-ledger.js.map

package/dist/agent/turn/tool-execution/plan-tool-ledger.js.map

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

package/dist/agent/turn/tool-execution/result-framing.d.ts

@@ -0,0 +1,36 @@
+import type { ChatMessage, ToolCall, ToolResult } from "../../../types.js";
+import type { SessionPlan, TaskEvidence } from "../../../store/plan.js";
+import type { LooseWorkReceipt, TaskWorkLedger } from "../../task-evidence.js";
+export interface ResultFramingPorts {
+    readonly step: number;
+    readonly saveArtifact: (call: ToolCall, output: string) => Promise<string | undefined>;
+    readonly setJobArtifact: (path: string) => void;
+    readonly formatContext: (call: ToolCall, result: ToolResult) => string;
+    readonly emitToolResult: (result: ToolResult, contextOutput: string, artifactPath: string | undefined) => void;
+    readonly onToolResult: ((call: ToolCall, result: ToolResult) => void) | undefined;
+    readonly audit: (event: string, payload: Readonly<Record<string, string | number | boolean | ToolCall | undefined>>) => Promise<void>;
+    readonly recordEngagementOutcome: (artifactPath: string | undefined) => Promise<void>;
+    readonly recordLedgerCall: (call: ToolCall, ok: boolean, artifactPath: string | undefined) => void;
+}
+export interface FramedResult {
+    readonly result: ToolResult;
+    readonly contextOutput: string;
+    readonly artifactPath: string | undefined;
+}
+export declare const frameToolResult: (ports: ResultFramingPorts, call: ToolCall, result: ToolResult) => Promise<FramedResult>;
+export interface WorkCreditPorts {
+    readonly getLedger: () => TaskWorkLedger | null;
+    readonly setLedger: (ledger: TaskWorkLedger | null) => void;
+    readonly bankLooseWork: (receipt: LooseWorkReceipt) => void;
+    readonly persistTaskEvidence: (taskId: string, evidence: TaskEvidence) => Promise<void>;
+    readonly loadPlan: () => Promise<SessionPlan | undefined>;
+    readonly creditId: () => string | undefined;
+}
+export declare const creditToolWork: (ports: WorkCreditPorts, call: ToolCall, result: ToolResult) => Promise<SessionPlan | undefined>;
+export interface FailureReflectionPorts {
+    readonly reflection: () => string | null | undefined;
+    readonly failureCount: () => number;
+    readonly deferMessage: (message: ChatMessage) => void;
+    readonly notify: (level: "info" | "warn", message: string) => void;
+}
+export declare const reportToolFailure: (ports: FailureReflectionPorts, ok: boolean) => void;

package/dist/agent/turn/tool-execution/result-framing.js

@@ -0,0 +1,54 @@
+import { isEvidenceWorkTool } from "../../task-evidence.js";
+import { readTaskWorkSignals } from "../task-work-signals.js";
+import { creditSuccessfulWork } from "../task-credit.js";
+export const frameToolResult = async (ports, call, result) => {
+    const output = result.output.trim();
+    const artifactPath = result.outputPath ??
+        (output ? await ports.saveArtifact(call, output) : undefined);
+    const framed = {
+        ...result,
+        outputPath: artifactPath,
+        truncated: result.truncated ?? Boolean(artifactPath),
+    };
+    if (artifactPath)
+        ports.setJobArtifact(artifactPath);
+    const contextOutput = ports.formatContext(call, framed);
+    ports.emitToolResult(framed, contextOutput, artifactPath);
+    ports.onToolResult?.(call, framed);
+    await ports.audit("tool.result", {
+        call,
+        ok: result.ok,
+        exitCode: result.exitCode,
+        output: result.output.slice(0, 4_000),
+    });
+    await ports.recordEngagementOutcome(artifactPath);
+    ports.recordLedgerCall(call, result.ok, artifactPath);
+    return { result: framed, contextOutput, artifactPath };
+};
+export const creditToolWork = async (ports, call, result) => {
+    if (!result.ok || !isEvidenceWorkTool(call.name))
+        return undefined;
+    const plan = await ports.loadPlan();
+    await creditSuccessfulWork({
+        getLedger: ports.getLedger,
+        setLedger: ports.setLedger,
+        bankLooseWork: ports.bankLooseWork,
+        persistTaskEvidence: ports.persistTaskEvidence,
+    }, {
+        call,
+        signals: readTaskWorkSignals(call, result.output ?? ""),
+        creditId: ports.creditId(),
+        plan,
+    });
+    return plan;
+};
+export const reportToolFailure = (ports, ok) => {
+    if (ok)
+        return;
+    const reflection = ports.reflection();
+    if (!reflection)
+        return;
+    ports.deferMessage({ role: "system", content: reflection });
+    ports.notify("warn", `${ports.failureCount()} consecutive failures — model evaluating approach`);
+};
+//# sourceMappingURL=result-framing.js.map

package/dist/agent/turn/tool-execution/result-framing.js.map

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

package/dist/agent/turn/tool-execution/run-setup.d.ts

@@ -0,0 +1,29 @@
+import type { ToolCall } from "../../../types.js";
+import type { BackgroundJob } from "../../../tools/jobs.js";
+import type { EngagementScope } from "../../../store/scope.js";
+import type { EngagementActionRecord, EngagementGraph } from "../../../store/engagement.js";
+import type { EngagementAction } from "../../../safety/engagement-policy.js";
+export interface EphemeralJob {
+    readonly id: string;
+    readonly job: BackgroundJob;
+}
+export declare const createEphemeralToolJob: (call: ToolCall, cwd: string, ownerSessionId: string) => EphemeralJob;
+export interface EngagementRunOptions {
+    readonly engagementAuthorization?: {
+        readonly target: string;
+        readonly expiresAt?: string | undefined;
+    };
+    readonly authorizeNetworkHop?: (url: string, resolvedAddresses: string[]) => Promise<{
+        allowed: boolean;
+        reason: string;
+    }>;
+}
+export interface EngagementRunInput {
+    readonly action: EngagementAction | undefined;
+    readonly scope: EngagementScope | undefined;
+    readonly normalizedTarget: string | undefined;
+    readonly graph: EngagementGraph | undefined;
+    readonly record: EngagementActionRecord | undefined;
+    readonly audit: (event: string, payload: Readonly<Record<string, string | boolean | readonly string[] | undefined>>) => Promise<void>;
+}
+export declare const buildEngagementRunOptions: (input: EngagementRunInput) => EngagementRunOptions;