@pensar/apex 2.6.1 → 2.7.0-canary.1572d9a4

package/src/core/agents/offSecAgent/tools/documentFinding.ts

@@ -4,6 +4,7 @@ import { z } from "zod";
 import { AttackPathSchema } from "../../../../lib/attack-path/types";
 import { hasCanonicalName } from "../../../../lib/cwe/types";
 import type { EvidenceFileEntry } from "../../../../lib/evidence/types";
+import { getModelSettings } from "../../../ai";
 import { createLogger } from "../../../logger/structured";
 import { collectCommand } from "../../../tools/backends/collectCommand";
 import {
@@ -11,7 +12,7 @@ import {
   resolveArtifactFs,
   resolveBackends,
   resolveScriptRunner,
-  SANDBOX_ARTIFACTS_ROOT,
+  sandboxArtifactsRoot,
 } from "../../../tools/backends/resolve";
 import type { WriteOpts, WriteResult } from "../../../tools/backends/types";
 import { scopedLogger } from "../../../util/lazyLogger";
@@ -200,18 +201,20 @@ function artifactPath(ctx: ToolContext, ...parts: string[]): string {
 }
 
 function artifactsRoot(ctx: ToolContext): string {
-  return isRealSandbox(ctx) ? SANDBOX_ARTIFACTS_ROOT : ctx.session.rootPath;
+  return isRealSandbox(ctx)
+    ? sandboxArtifactsRoot(ctx.session)
+    : ctx.session.rootPath;
 }
 
 function pocsRoot(ctx: ToolContext): string {
   return isRealSandbox(ctx)
-    ? `${SANDBOX_ARTIFACTS_ROOT}/pocs`
+    ? `${sandboxArtifactsRoot(ctx.session)}/pocs`
     : ctx.session.pocsPath;
 }
 
 function findingsRoot(ctx: ToolContext): string {
   return isRealSandbox(ctx)
-    ? `${SANDBOX_ARTIFACTS_ROOT}/findings`
+    ? `${sandboxArtifactsRoot(ctx.session)}/findings`
     : ctx.session.findingsPath;
 }
 
@@ -497,16 +500,13 @@ CRITICAL RULES — READ BEFORE CALLING:
             spec: { type: "finding-judge", judgeInput, target: ctx.target },
             runtime: {
               session: ctx.session,
-              model: ctx.model!,
-              authConfig: ctx.authConfig,
+              ...getModelSettings(ctx),
               abortSignal: ctx.abortSignal,
               sandbox: ctx.sandbox,
               backends: ctx.backends,
-              enableThinking: ctx.enableThinking,
-              thinkingEffort: ctx.thinkingEffort,
-              openAIReasoningEffort: ctx.openAIReasoningEffort,
               languageModelMiddleware: ctx.languageModelMiddleware,
               usageRecorder: ctx.usageRecorder,
+              toolExecutionContext: ctx.toolExecutionContext,
               streamIdFactory: ctx.streamIdFactory,
             },
             parentBus: ctx.eventBus,
@@ -626,6 +626,7 @@ CRITICAL RULES — READ BEFORE CALLING:
               ctx.abortSignal,
               ctx.session.id,
               {
+                reasoning: ctx.reasoning,
                 languageModelMiddleware: ctx.languageModelMiddleware,
                 usageRecorder: ctx.usageRecorder,
               },

package/src/core/agents/offSecAgent/tools/listMemories.test.ts

@@ -0,0 +1,230 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  type Memory,
+  type MemoryBackend,
+  type MemorySummary,
+  withMemoryBackend,
+} from "../../../memory";
+import { type GetMemoryResult, getMemory } from "./getMemory";
+import { type ListMemoriesResult, listMemories } from "./listMemories";
+import type { ToolContext } from "./types";
+
+const ctx = { session: { id: "synthetic" } } as ToolContext;
+const options = { toolCallId: "synthetic-call", messages: [] };
+const list = listMemories(ctx).execute;
+const get = getMemory(ctx).execute;
+if (!list || !get) throw new Error("Memory tools must be executable");
+
+describe("list_memories pagination", () => {
+  it("continues from the first unreturned summary when the character budget fills", async () => {
+    const summaries: MemorySummary[] = Array.from({ length: 30 }, (_, i) => ({
+      id: `large-${i}`,
+      category: "general",
+      title: "t".repeat(300),
+      tags: Array.from({ length: 8 }, () => "tag".repeat(40)),
+      createdAt: new Date(Date.UTC(2026, 0, 1) - i * 1_000).toISOString(),
+    }));
+    const backend: MemoryBackend = {
+      add: vi.fn(async () => {
+        throw new Error("unexpected add");
+      }),
+      list: vi.fn(async () => summaries),
+      get: vi.fn(async () => null),
+    };
+    await withMemoryBackend(backend, async () => {
+      const first = (await list(
+        { toolCallDescription: "List large synthetic memories" },
+        options,
+      )) as ListMemoriesResult;
+      expect(first.memories.length).toBeLessThan(20);
+      expect(JSON.stringify(first).length).toBeLessThan(12_500);
+      expect(first.nextCursor).toEqual({
+        id: first.memories.at(-1)?.id,
+        category: first.memories.at(-1)?.category,
+        createdAt: first.memories.at(-1)?.createdAt,
+      });
+      const second = (await list(
+        {
+          cursor: first.nextCursor ?? undefined,
+          toolCallDescription: "Continue large synthetic memories",
+        },
+        options,
+      )) as ListMemoriesResult;
+      expect(second.memories[0]?.id).toBe(summaries[first.memories.length]?.id);
+    });
+  });
+
+  it("continues past the last returned memory when a newer one is added", async () => {
+    const original: MemorySummary[] = Array.from({ length: 30 }, (_, i) => ({
+      id: `memory-${i}`,
+      category: "general",
+      title: `Memory ${i}`,
+      tags: [],
+      createdAt: new Date(Date.UTC(2026, 0, 1) - i * 1_000).toISOString(),
+    }));
+    let summaries = original;
+    const backend: MemoryBackend = {
+      add: vi.fn(async () => {
+        throw new Error("unexpected add");
+      }),
+      list: vi.fn(async () => summaries),
+      get: vi.fn(async () => null),
+    };
+    await withMemoryBackend(backend, async () => {
+      const first = (await list(
+        { toolCallDescription: "List first memory page" },
+        options,
+      )) as ListMemoriesResult;
+      summaries = [
+        {
+          ...original[0],
+          id: "memory-new",
+          createdAt: new Date(Date.UTC(2026, 0, 2)).toISOString(),
+        },
+        ...original,
+      ];
+      const second = (await list(
+        {
+          cursor: first.nextCursor ?? undefined,
+          toolCallDescription: "Continue after an insertion",
+        },
+        options,
+      )) as ListMemoriesResult;
+
+      expect(first.memories.map((memory) => memory.id)).toEqual(
+        original.slice(0, 20).map((memory) => memory.id),
+      );
+      expect(second.memories.map((memory) => memory.id)).toEqual(
+        original.slice(20).map((memory) => memory.id),
+      );
+      expect(second.count).toBe(31);
+      expect(second.nextCursor).toBeNull();
+    });
+  });
+
+  it("uses stable tie ordering when the cursor memory is deleted", async () => {
+    const original: MemorySummary[] = Array.from({ length: 25 }, (_, i) => ({
+      id: `memory-${i.toString().padStart(2, "0")}`,
+      category: "general",
+      title: `Memory ${i}`,
+      tags: [],
+      createdAt: "2026-01-01T00:00:00.000Z",
+    }));
+    let summaries = [...original].reverse();
+    const backend: MemoryBackend = {
+      add: vi.fn(async () => {
+        throw new Error("unexpected add");
+      }),
+      list: vi.fn(async () => summaries),
+      get: vi.fn(async () => null),
+    };
+    await withMemoryBackend(backend, async () => {
+      const first = (await list(
+        { toolCallDescription: "List tied memories" },
+        options,
+      )) as ListMemoriesResult;
+      expect(first.memories.map((memory) => memory.id)).toEqual(
+        original.slice(0, 20).map((memory) => memory.id),
+      );
+      summaries = summaries.filter(
+        (memory) => memory.id !== first.nextCursor?.id,
+      );
+      const second = (await list(
+        {
+          cursor: first.nextCursor ?? undefined,
+          toolCallDescription: "Continue after anchor deletion",
+        },
+        options,
+      )) as ListMemoriesResult;
+      expect(second.memories.map((memory) => memory.id)).toEqual(
+        original.slice(20).map((memory) => memory.id),
+      );
+      expect(second.nextCursor).toBeNull();
+    });
+  });
+
+  it("bounds each result while keeping every older memory discoverable", async () => {
+    const summaries: MemorySummary[] = Array.from({ length: 200 }, (_, i) => ({
+      id: `memory-${i}`,
+      category: "general",
+      title: `Memory ${i} ${"x".repeat(480)}`,
+      tags: ["synthetic", "history"],
+      createdAt: new Date(Date.UTC(2026, 0, 1) - i * 1_000).toISOString(),
+    }));
+    const backend: MemoryBackend = {
+      add: vi.fn(async () => {
+        throw new Error("unexpected add");
+      }),
+      list: vi.fn(async () =>
+        summaries.map((summary, index) =>
+          index === 0 ? { ...summary, content: "full-body-marker" } : summary,
+        ),
+      ),
+      get: vi.fn(async (_category, id) => {
+        const summary = summaries.find((item) => item.id === id);
+        return summary
+          ? ({
+              ...summary,
+              content: `Full ${id}`,
+              updatedAt: summary.createdAt,
+            } satisfies Memory)
+          : null;
+      }),
+    };
+
+    await withMemoryBackend(backend, async () => {
+      const allIds: string[] = [];
+      let cursor: ListMemoriesResult["nextCursor"] = null;
+      let firstResultChars = 0;
+      let pages = 0;
+      for (;;) {
+        const result = (await list(
+          {
+            cursor: cursor ?? undefined,
+            toolCallDescription: "List synthetic memories",
+          },
+          options,
+        )) as ListMemoriesResult;
+        expect(result.success).toBe(true);
+        expect(result.count).toBe(200);
+        expect(result.memories.length).toBeGreaterThan(0);
+        expect(result.memories.length).toBeLessThanOrEqual(20);
+        expect(JSON.stringify(result).length).toBeLessThan(12_500);
+        if (pages === 0) {
+          firstResultChars = JSON.stringify(result).length;
+          expect(JSON.stringify(result)).not.toContain("full-body-marker");
+          expect(result.memories[0]?.truncated).toBe(true);
+          expect(result.memories[0]?.title.length).toBe(160);
+        }
+        allIds.push(...result.memories.map((memory) => memory.id));
+        pages++;
+        if (result.nextCursor === null) break;
+        expect(result.nextCursor.id).toBe(result.memories.at(-1)?.id);
+        cursor = result.nextCursor;
+      }
+
+      expect(allIds).toEqual(summaries.map((memory) => memory.id));
+      const oldest = (await get(
+        {
+          category: "general",
+          id: allIds.at(-1) ?? "",
+          toolCallDescription: "Read oldest synthetic memory",
+        },
+        options,
+      )) as GetMemoryResult;
+      expect(oldest.memory?.content).toBe("Full memory-199");
+      if (process.env.APEX_CONTEXT_BENCH === "1") {
+        const previousChars = JSON.stringify({
+          success: true,
+          error: "",
+          memories: summaries,
+          count: summaries.length,
+        }).length;
+        console.log(
+          "MEMORY_LIST_BENCH",
+          JSON.stringify({ previousChars, firstResultChars, pages }),
+        );
+      }
+    });
+  });
+});

package/src/core/agents/offSecAgent/tools/listMemories.ts

@@ -7,6 +7,9 @@ import {
 } from "../../../memory";
 import type { ToolContext } from "./types";
 
+const PAGE_SIZE = 20;
+const PAGE_CHAR_BUDGET = 12_000;
+
 const listMemoriesInputSchema = z.object({
   category: z
     .enum(MEMORY_CATEGORIES)
@@ -19,6 +22,14 @@ const listMemoriesInputSchema = z.object({
     .string()
     .optional()
     .describe("Optional tag to filter memories by (exact match)"),
+  cursor: z
+    .object({
+      createdAt: z.string(),
+      category: z.enum(MEMORY_CATEGORIES),
+      id: z.string(),
+    })
+    .optional()
+    .describe("Pass the previous nextCursor to continue a listing"),
   toolCallDescription: z
     .string()
     .describe(
@@ -27,24 +38,53 @@ const listMemoriesInputSchema = z.object({
 });
 
 type ListMemoriesInput = z.infer<typeof listMemoriesInputSchema>;
+type MemoryCursor = Pick<MemorySummary, "createdAt" | "category" | "id">;
 
 export type ListMemoriesResult = {
   success: boolean;
   error: string;
-  memories: MemorySummary[];
+  memories: Array<MemorySummary & { truncated?: true }>;
   count: number;
+  nextCursor: MemoryCursor | null;
 };
 
+function compareMemories(a: MemoryCursor, b: MemoryCursor): number {
+  const byCreatedAt = Date.parse(b.createdAt) - Date.parse(a.createdAt);
+  if (byCreatedAt > 0 || byCreatedAt < 0) return byCreatedAt;
+  return a.category.localeCompare(b.category) || a.id.localeCompare(b.id);
+}
+
+function previewSummary(memory: MemorySummary) {
+  const title = memory.title.slice(0, 160);
+  const tags = memory.tags.slice(0, 8).map((tag) => tag.slice(0, 48));
+  const truncated =
+    title.length < memory.title.length ||
+    tags.length < memory.tags.length ||
+    tags.some(
+      (tag, index) => tag.length < (memory.tags[index]?.length ?? tag.length),
+    );
+  return {
+    id: memory.id,
+    category: memory.category,
+    title,
+    tags,
+    createdAt: memory.createdAt,
+    ...(truncated ? { truncated: true as const } : {}),
+  };
+}
+
 export function listMemories(ctx: ToolContext) {
   return tool({
     description: `List saved memories, optionally filtered by category and/or tag.
 
-Returns lightweight summaries (id, category, title, tags, createdAt) sorted by
-most recent first. Use the returned category + id with get_memory to retrieve
-full content.`,
+Returns up to 20 lightweight summaries (id, category, title, tags, createdAt)
+sorted by most recent first. Use nextCursor to continue until it is null;
+count is the current total matching memories. A fresh listing includes newer
+memories added ahead of a cursor. Titles and tags may be abbreviated in the
+listing. Use category + id with get_memory to retrieve full content.`,
     inputSchema: listMemoriesInputSchema,
     execute: async (
-      { category, tag },
+      { category, tag, cursor },
       { toolCallId },
     ): Promise<ListMemoriesResult> => {
       try {
@@ -52,11 +92,37 @@ full content.`,
           { category, tag },
           { sessionId: ctx.session.id, toolCallId },
         );
+        const ordered = [...memories].sort(compareMemories);
+        let start = 0;
+        if (cursor) {
+          start = ordered.findIndex(
+            (memory) => compareMemories(memory, cursor) > 0,
+          );
+          if (start < 0) start = ordered.length;
+        }
+        const page: ListMemoriesResult["memories"] = [];
+        let pageChars = 0;
+        for (const memory of ordered.slice(start, start + PAGE_SIZE)) {
+          const summary = previewSummary(memory);
+          const chars = JSON.stringify(summary).length + 1;
+          if (page.length > 0 && pageChars + chars > PAGE_CHAR_BUDGET) break;
+          page.push(summary);
+          pageChars += chars;
+        }
+        const last = page.at(-1);
         return {
           success: true,
           error: "",
-          memories,
+          memories: page,
           count: memories.length,
+          nextCursor:
+            start + page.length < ordered.length && last
+              ? {
+                  createdAt: last.createdAt,
+                  category: last.category,
+                  id: last.id,
+                }
+              : null,
         };
       } catch (err: unknown) {
         return {
@@ -64,6 +130,7 @@ full content.`,
           error: err instanceof Error ? err.message : String(err),
           memories: [],
           count: 0,
+          nextCursor: null,
         };
       }
     },

package/src/core/agents/offSecAgent/tools/reportError.test.ts

@@ -11,6 +11,12 @@ describe("report_error tool", () => {
     expect(REPORT_ERROR_TOOL_NAME).toBe("report_error");
   });
 
+  it("does not name the unavailable finding tool under external grading", () => {
+    const external = createReportErrorTool(vi.fn(), "external");
+    expect(external.description).toContain("final response");
+    expect(external.description).not.toContain("document_vulnerability");
+  });
+
   it("forwards the reason + message to the onError callback", async () => {
     const onError = vi.fn<(error: ReportedError) => void>();
     const tool = createReportErrorTool(onError);

package/src/core/agents/offSecAgent/tools/reportError.ts

@@ -1,5 +1,6 @@
 import { tool } from "ai";
 import { z } from "zod";
+import type { FindingPolicy } from "../types";
 
 export const REPORT_ERROR_TOOL_NAME = "report_error" as const;
 
@@ -22,7 +23,14 @@ export type ReportedError = {
  * of a successful result it surfaces a blocking error so the caller can turn
  * the run into a failure (e.g. mark a scan endpoint failed with this message).
  */
-export function createReportErrorTool(onError: (error: ReportedError) => void) {
+export function createReportErrorTool(
+  onError: (error: ReportedError) => void,
+  findingPolicy: FindingPolicy = "native",
+) {
+  const vulnerabilityGuidance =
+    findingPolicy === "external"
+      ? "Do NOT use this for vulnerabilities (include them in your final response)"
+      : "Do NOT use this for vulnerabilities (use document_vulnerability)";
   return tool({
     description: `Report a blocking error that prevents you from completing the pentest, and END your run.
 
@@ -31,7 +39,7 @@ Call this ONLY when you genuinely cannot continue, for example:
 - The target is unreachable or responds in a way that makes testing impossible.
 - Some other runtime condition blocks you from carrying out the objectives.
 
-Do NOT use this for vulnerabilities (use document_vulnerability) or for normal completion (use response). Provide a clear, specific message describing exactly what blocked you — include the failing URL, status codes, or the auth step that failed where relevant — so it can be surfaced to the operator.`,
+${vulnerabilityGuidance} or for normal completion (use response). Provide a clear, specific message describing exactly what blocked you — include the failing URL, status codes, or the auth step that failed where relevant — so it can be surfaced to the operator.`,
     inputSchema: z.object({
       reason: ReportErrorReasonSchema.describe(
         "Coarse category of the blocking error.",

package/src/core/agents/offSecAgent/tools/runAttackSurface.ts

@@ -1,5 +1,6 @@
 import { tool } from "ai";
 import { z } from "zod";
+import { getModelSettings } from "../../../ai";
 import { createLogger } from "../../../logger/structured";
 import { scopedLogger } from "../../../util/lazyLogger";
 import type { AttackSurfaceResult } from "../../specialized/attackSurface/blackboxAgent";
@@ -74,13 +75,14 @@ should be passed directly to spawn_pentest_swarm for deep testing.`,
               attackSurfaceRegistry: ctx.attackSurfaceRegistry,
             },
             runtime: {
+              findingPolicy: ctx.findingPolicy,
               session: ctx.session,
-              model: ctx.model,
-              authConfig: ctx.authConfig,
+              ...getModelSettings(ctx),
               abortSignal: ctx.abortSignal,
               backends: ctx.backends,
               languageModelMiddleware: ctx.languageModelMiddleware,
               usageRecorder: ctx.usageRecorder,
+              toolExecutionContext: ctx.toolExecutionContext,
               streamIdFactory: ctx.streamIdFactory,
             },
             parentBus: ctx.eventBus,
@@ -144,13 +146,14 @@ should be passed directly to spawn_pentest_swarm for deep testing.`,
             attackSurfaceRegistry: ctx.attackSurfaceRegistry,
           },
           runtime: {
+            findingPolicy: ctx.findingPolicy,
             session: ctx.session,
-            model: ctx.model,
-            authConfig: ctx.authConfig,
+            ...getModelSettings(ctx),
             abortSignal: ctx.abortSignal,
             backends: ctx.backends,
             languageModelMiddleware: ctx.languageModelMiddleware,
             usageRecorder: ctx.usageRecorder,
+            toolExecutionContext: ctx.toolExecutionContext,
             streamIdFactory: ctx.streamIdFactory,
           },
           parentBus: ctx.eventBus,

package/src/core/agents/offSecAgent/tools/runPentestWorkflow.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it, vi } from "vitest";
+
+const workflow = vi.hoisted(() => vi.fn());
+
+vi.mock("../../../workflows/pentest", () => ({
+  runPentestWorkflow: workflow,
+}));
+
+import { runPentestWorkflow } from "./runPentestWorkflow";
+import type { ToolContext } from "./types";
+
+describe("run_pentest_workflow external finding handoff", () => {
+  it("returns reported findings to the parent instead of claiming zero were documented", async () => {
+    workflow.mockResolvedValue({
+      findings: [],
+      reportedFindings: ["Cross-tenant read at GET /private"],
+      objectiveResults: [
+        {
+          objective: "Extract the assigned flag",
+          completed: true,
+          result: "Extracted FLAG{example}",
+        },
+      ],
+      findingsPath: "/session/findings",
+      pocsPath: "/session/pocs",
+      reportPath: null,
+    });
+    const ctx = {
+      findingPolicy: "external",
+      model: "test",
+      session: { id: "ses_external", rootPath: "/session" },
+    } as ToolContext;
+    const agentTool = runPentestWorkflow(ctx);
+    expect(agentTool.description).toContain("caller's evaluation");
+    const result = await agentTool.execute?.(
+      { target: "https://example.com", toolCallDescription: "test" },
+      { toolCallId: "tc_external", messages: [] },
+    );
+
+    expect(workflow).toHaveBeenCalledWith(
+      expect.objectContaining({ findingPolicy: "external" }),
+    );
+    expect(result).toMatchObject({
+      success: true,
+      totalFindings: 1,
+      reportedFindings: ["Cross-tenant read at GET /private"],
+      objectiveResults: [
+        {
+          objective: "Extract the assigned flag",
+          completed: true,
+          result: "Extracted FLAG{example}",
+        },
+      ],
+    });
+    expect((result as { message: string }).message).not.toContain("documented");
+  });
+});

package/src/core/agents/offSecAgent/tools/runPentestWorkflow.ts

@@ -11,13 +11,17 @@ import type { ToolContext } from "./types";
  * need to orchestrate multiple tool calls manually.
  */
 export function runPentestWorkflow(ctx: ToolContext) {
+  const resultStep =
+    ctx.findingPolicy === "external"
+      ? "3. Return evidence-backed findings for the caller's evaluation"
+      : "3. Aggregate findings and generate the final report";
   return tool({
     description: `Run the full autonomous penetration test pipeline against a target.
 
 This single tool call executes the entire pentest workflow:
 1. Attack surface discovery (blackbox or whitebox)
 2. Spawn a swarm of targeted pentest agents
-3. Aggregate findings and generate the final report
+${resultStep}
 
 Use this when you want to run a complete, end-to-end pentest. The workflow
 handles session creation, concurrency, persistence, and reporting automatically.
@@ -54,6 +58,7 @@ Omit \`cwd\` for blackbox mode (live target probing only).`,
 
       try {
         const result = await workflow({
+          findingPolicy: ctx.findingPolicy,
           target,
           cwd,
           model: ctx.model,
@@ -64,12 +69,15 @@ Omit \`cwd\` for blackbox mode (live target probing only).`,
           enableThinking: ctx.enableThinking,
           thinkingEffort: ctx.thinkingEffort,
           openAIReasoningEffort: ctx.openAIReasoningEffort,
+          reasoning: ctx.reasoning,
           surfaceIntegrationEnabled: ctx.surfaceIntegrationEnabled,
           hooks: {
+            findingPolicy: ctx.findingPolicy,
             backends: ctx.backends,
             subagentSpawner: ctx.subagentSpawner,
             languageModelMiddleware: ctx.languageModelMiddleware,
             usageRecorder: ctx.usageRecorder,
+            toolExecutionContext: ctx.toolExecutionContext,
             streamIdFactory: ctx.streamIdFactory,
             smsInbox: ctx.smsInbox,
             emailAdapterFor: ctx.emailAdapterFor,
@@ -81,6 +89,18 @@ Omit \`cwd\` for blackbox mode (live target probing only).`,
         const minutes = Math.floor(elapsedSeconds / 60);
         const seconds = elapsedSeconds % 60;
 
+        if (ctx.findingPolicy === "external") {
+          const reportedFindings = result.reportedFindings ?? [];
+          return {
+            success: true,
+            totalFindings: reportedFindings.length,
+            reportedFindings,
+            objectiveResults: result.objectiveResults ?? [],
+            duration: `${minutes}m ${seconds}s`,
+            message: `Pentest complete. ${reportedFindings.length} finding(s) returned for external evaluation.`,
+          };
+        }
+
         return {
           success: true,
           totalFindings: result.findings.length,

package/src/core/agents/offSecAgent/tools/runWhiteboxScan.ts

@@ -22,13 +22,16 @@ const ScanKindSchema = z.enum([
 ]);
 
 export function runWhiteboxScan(ctx: ToolContext) {
+  const verificationGuidance =
+    ctx.findingPolicy === "external"
+      ? "as recoverable conditions. Static results are candidates only; assess them against the caller's evidence requirements."
+      : "as recoverable conditions. Static results are candidates only; verify before\ncalling document_vulnerability.";
   return tool({
     description: `Run installed whitebox security scanners with bounded output.
 
 The tool detects applicable scanner adapters for the repository and normalizes
 results into concise summaries plus artifact paths. Missing tools are reported
-as recoverable conditions. Static results are candidates only; verify before
-calling document_vulnerability.`,
+${verificationGuidance}`,
     inputSchema: z.object({
       path: z
         .string()