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

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

@@ -1,11 +1,12 @@
 import { tool } from "ai";
 import { z } from "zod";
+import { getModelSettings } from "../../../ai";
 import type { AssetRecord } from "../../../findings/attackSurfaceRegistry";
 import {
   resolvePathWithinCodebaseRoot,
   resolveWhiteboxCodebaseRoot,
 } from "../../../whitebox";
-import type { SubagentSpawner } from "../subagentSpawner";
+import { type SpawnOptions, spawnBatch } from "../subagentSpawner";
 import type { ToolContext } from "./types";
 
 /** Default max concurrent coding agents */
@@ -100,49 +101,46 @@ Returns an array of results with the text output from each agent.`,
 
       const spawner = ctx.subagentSpawner;
 
-      // Bounded fan-out via the spawner so each sub-agent inherits the OTel
-      // context. Errors are caught per task and returned inline, so results
-      // never contain null.
-      const settled = await spawner.spawnMany(
-        validatedTasks,
-        async (item, i) => {
-          try {
-            const output = await runSingleCodingAgent(
-              ctx,
-              spawner,
-              item.codebasePath,
-              item.objective,
-              i + 1,
-              item.name,
-              toolCallId,
-            );
-            return {
-              codebasePath: item.codebasePath,
-              objective: item.objective,
-              output,
-            };
-          } catch (err) {
-            return {
-              codebasePath: item.codebasePath,
-              objective: item.objective,
-              output: "",
-              error: err instanceof Error ? err.message : String(err),
-            };
-          }
-        },
+      const textOutputs = validatedTasks.map(() => "");
+      const settled = await spawnBatch(
+        spawner,
+        validatedTasks.map((item, index) =>
+          codingSpawnOptions(
+            ctx,
+            item.codebasePath,
+            item.objective,
+            item.name,
+            toolCallId,
+            (text) => {
+              textOutputs[index] += text;
+            },
+          ),
+        ),
         { concurrency: DEFAULT_CONCURRENCY },
       );
-
-      const results = settled.filter(
-        (
-          r,
-        ): r is {
-          codebasePath: string;
-          objective: string;
-          output: string;
-          error?: string;
-        } => r !== null,
-      );
+      const results = [];
+      for (const [index, item] of validatedTasks.entries()) {
+        const result = settled[index]!;
+        try {
+          if (result.status === "rejected") throw result.reason;
+          if (result.value?.surface?.length && ctx.attackSurfaceRegistry) {
+            for (const asset of result.value.surface) {
+              await ctx.attackSurfaceRegistry.register(asset);
+            }
+          }
+          results.push({
+            ...item,
+            output: result.value?.text ?? textOutputs[index]!,
+            error: undefined,
+          });
+        } catch (error) {
+          results.push({
+            ...item,
+            output: "",
+            error: error instanceof Error ? error.message : String(error),
+          });
+        }
+      }
 
       const failedTasks = results.filter((r) => r.error);
 
@@ -165,7 +163,7 @@ Returns an array of results with the text output from each agent.`,
 }
 
 // ---------------------------------------------------------------------------
-// Internal: run a single CodeAgent
+// Child request
 // ---------------------------------------------------------------------------
 
 /** The slice of a durable CodeAgent child's returned value the parent folds. */
@@ -174,33 +172,28 @@ interface CodingChildResult {
   text?: string;
 }
 
-async function runSingleCodingAgent(
+function codingSpawnOptions(
   ctx: ToolContext,
-  spawner: SubagentSpawner,
   codebasePath: string,
   objective: string,
-  _agentIndex: number,
   name: string,
   parentToolCallId: string,
-): Promise<string> {
-  let textOutput = "";
-
-  const result = await spawner.spawn<CodingChildResult | undefined>({
+  onText: (text: string) => void,
+): SpawnOptions<CodingChildResult | undefined> {
+  return {
     spec: { type: "code", codebasePath, objective },
     runtime: {
+      findingPolicy: ctx.findingPolicy,
       session: ctx.session,
-      model: ctx.model!,
-      authConfig: ctx.authConfig,
+      ...getModelSettings(ctx),
       abortSignal: ctx.abortSignal,
       sandbox: ctx.sandbox,
       backends: ctx.backends,
       environmentVariables: ctx.environmentVariables,
       secretValues: ctx.secretValues,
-      enableThinking: ctx.enableThinking,
-      thinkingEffort: ctx.thinkingEffort,
-      openAIReasoningEffort: ctx.openAIReasoningEffort,
       languageModelMiddleware: ctx.languageModelMiddleware,
       usageRecorder: ctx.usageRecorder,
+      toolExecutionContext: ctx.toolExecutionContext,
       streamIdFactory: ctx.streamIdFactory,
     },
     parentBus: ctx.eventBus,
@@ -212,18 +205,8 @@ async function runSingleCodingAgent(
     stampChildSessionId: true,
     beforeConsume: (childBus) => {
       childBus.on("text-delta", (d) => {
-        textOutput += d.text;
+        onText(d.text);
       });
     },
-  });
-
-  // Durable children return their surface by value (in-process children return
-  // void); fold it into the parent registry so dedup-in-parent closes.
-  if (result?.surface?.length && ctx.attackSurfaceRegistry) {
-    for (const asset of result.surface) {
-      await ctx.attackSurfaceRegistry.register(asset);
-    }
-  }
-
-  return result?.text ?? textOutput;
+  };
 }

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

@@ -23,6 +23,9 @@ const registryCalls: Array<{
   path: string;
   options: Record<string, unknown>;
 }> = [];
+const swarmMock = vi.hoisted(() => ({
+  results: [] as Array<Record<string, unknown>>,
+}));
 
 vi.mock("../../specialized/pentest/agent", () => ({
   TargetedPentestAgent: class {
@@ -46,7 +49,7 @@ vi.mock("../../../findings/registry", () => ({
 
 vi.mock("../../../workflows/pentest", () => ({
   DEFAULT_CONCURRENCY: 10,
-  runPentestSwarm: async () => [],
+  runPentestSwarm: async () => swarmMock.results,
 }));
 
 import type { AIModel } from "../../../ai";
@@ -94,7 +97,12 @@ function makeParentSession(): {
 async function runSpawn(
   ctx: ToolContext,
   inputOverrides: Record<string, unknown> = {},
-): Promise<{ success?: boolean; message?: string }> {
+): Promise<{
+  success?: boolean;
+  message?: string;
+  findingsCount?: number;
+  reportedFindings?: string[];
+}> {
   const tool = spawnPentestAgent(ctx);
   // biome-ignore lint/suspicious/noExplicitAny: ai-sdk tool execute receives an opaque ExecuteContext we don't need to narrow for this test.
   return await (tool as any).execute(
@@ -110,6 +118,31 @@ async function runSpawn(
   );
 }
 
+it("passes external grading to a worker and returns its findings without native documentation", async () => {
+  const spawn = vi.fn().mockResolvedValue({
+    findings: [],
+    reportedFindings: ["Cross-tenant read at GET /private"],
+    objectiveResults: [],
+  });
+  const ctx = buildCtx({
+    findingPolicy: "external",
+    subagentSpawner: { spawn, spawnMany: vi.fn() },
+  });
+  const result = await runSpawn(ctx);
+  expect(spawn).toHaveBeenCalledWith(
+    expect.objectContaining({
+      runtime: expect.objectContaining({ findingPolicy: "external" }),
+    }),
+  );
+  expect(result).toMatchObject({
+    findingsCount: 1,
+    reportedFindings: ["Cross-tenant read at GET /private"],
+  });
+  const description = spawnPentestAgent(ctx).description;
+  expect(description).not.toContain("document_vulnerability");
+  expect(description).not.toContain("ONE MORE TIME");
+});
+
 function makeEventBus(): {
   bus: ToolContext["eventBus"];
   emit: ReturnType<typeof vi.fn>;
@@ -121,6 +154,7 @@ function makeEventBus(): {
 afterEach(() => {
   constructorCalls.length = 0;
   registryCalls.length = 0;
+  swarmMock.results = [];
   vi.restoreAllMocks();
 });
 
@@ -154,16 +188,58 @@ describe("spawn_pentest_agent — usage callbacks", () => {
   it("forwards usage callbacks to the worker", async () => {
     const onStepFinish = vi.fn();
     const onCacheMetrics = vi.fn();
-    const ctx = buildCtx({ onStepFinish, onCacheMetrics });
+    const ctx = buildCtx({
+      model: "gpt-6.1-sol",
+      onStepFinish,
+      onCacheMetrics,
+      reasoning: "low",
+    });
 
     await runSpawn(ctx);
 
     expect(constructorCalls[0]?.onStepFinish).toBe(onStepFinish);
     expect(constructorCalls[0]?.onCacheMetrics).toBe(onCacheMetrics);
+    expect(constructorCalls[0]?.reasoning).toBe("low");
   });
 });
 
 describe("spawn tools — findings session attribution", () => {
+  it("returns each external swarm objective outcome to the parent", async () => {
+    swarmMock.results = [
+      {
+        findings: [],
+        reportedFindings: ["Cross-tenant read"],
+        objectiveResults: [
+          {
+            objective: "Extract the assigned flag",
+            completed: true,
+            result: "Extracted FLAG{example}",
+          },
+        ],
+      },
+    ];
+    const tool = spawnPentestSwarm(buildCtx({ findingPolicy: "external" }));
+    // biome-ignore lint/suspicious/noExplicitAny: ai-sdk tool execute receives an opaque ExecuteContext we don't need to narrow for this test.
+    const output = await (tool as any).execute(
+      {
+        targets: [{ target: "https://example.com/api", objectives: ["Test"] }],
+        toolCallDescription: "spawn swarm",
+      },
+      { toolCallId: "tc_external", messages: [], abortSignal: undefined },
+    );
+
+    expect(output.results[0]).toMatchObject({
+      reportedFindings: ["Cross-tenant read"],
+      objectiveResults: [
+        {
+          objective: "Extract the assigned flag",
+          completed: true,
+          result: "Extracted FLAG{example}",
+        },
+      ],
+    });
+  });
+
   it("attributes the single-agent fallback registry to the root session", async () => {
     await runSpawn(buildCtx());
 

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

@@ -1,6 +1,7 @@
 import { tool } from "ai";
 import { z } from "zod";
 import { parseTargetUrl } from "../../../../util/url";
+import { getModelSettings } from "../../../ai";
 import { FindingsRegistry } from "../../../findings/registry";
 // Type-only (erased) — the value is constructed inside the spawner registry.
 import type { GrpcPentestContext } from "../../specialized/attackSurface/grpcSchema";
@@ -35,6 +36,22 @@ const ORIGIN_AUTH_FAILURE_GUIDANCE = `A 401/403 from one resource does not by it
  *     directly on the parent bus
  */
 export function spawnPentestAgent(ctx: ToolContext) {
+  const externalFindings = ctx.findingPolicy === "external";
+  const findingSteps = externalFindings
+    ? "2. Reports concise evidence-backed findings in its response\n3. Leaves acceptance to the caller's external evaluator"
+    : "2. Confirms vulnerabilities with POC scripts\n3. Documents findings to the shared findings registry only when the exploit path and material security impact are proven";
+  const findingGuidance = externalFindings
+    ? "False-positive discipline: report a security weakness only when observations support a material abuse path. Include the affected target, evidence, and impact; do not add a separate in-run finding review."
+    : "False-positive discipline: workers should not call document_vulnerability for public/unauthenticated behavior, missing best-practice controls, generic errors, local HTTP deployment context, or other low-signal observations unless they prove a material abuse path such as non-public data access, credentialed cross-origin abuse, state change, denial of service, account takeover, or another concrete exploit chain.";
+  const returnGuidance = externalFindings
+    ? "Returns the worker's summary, objective results, and reported findings so the parent can investigate chains."
+    : "Returns the worker's summary, objective results, and finding count — but NOT the findings themselves (those land in the shared registry).";
+  const exploratoryGuidance = externalFindings
+    ? "Spawn a follow-up exploratory worker only when the assigned objective requires broader coverage or a credible untested lead remains. For detection-only work, finish once the requested evidence is sufficient."
+    : 'After fanning out one worker per objective, call this tool ONE MORE TIME for a final "exploratory" worker. Pass it the URLs of any suspicious behaviors discovered by earlier workers and ask it to chain findings together and probe for additional, unspecified vulnerabilities.';
+  const objectiveGuidance = externalFindings
+    ? "Pass one focused objective per worker. A follow-up objective may cover a concrete chain or untested lead when the assignment calls for it."
+    : "For per-objective fan-out, pass exactly one objective. For the final exploratory pass, pass a single composite objective describing chaining + exploration.";
   const targetScopeGuidance =
     ctx.systemScope && ctx.systemScope.memberHosts.length > 0
       ? `For a cross-service follow-up, you may instead use a full URL on one of these authorized System Scope members: ${ctx.systemScope.memberHosts.join(", ")}.`
@@ -51,18 +68,17 @@ Authentication state is origin-specific. Before spawning a cross-service worker
 
 Each spawn produces an independent TargetedPentestAgent that:
 1. Tests the assigned objective(s) deeply (execute_command, http_request, browser tools)
-2. Confirms vulnerabilities with POC scripts
-3. Documents findings to the shared findings registry only when the exploit path and material security impact are proven
+${findingSteps}
 
 Cloned browser session — the worker gets its OWN isolated Chromium instance, but it is seeded at spawn time with a snapshot of your current cookies and localStorage. If you've already authenticated in your browser (or recon set up useful state), the worker starts already authenticated for the same origins. Critically, the worker's browser is a COPY: its navigations, form fills, \`localStorage.setItem\`, alerts, and any other browser-side mutations stay inside the worker's own browser and do NOT leak back to you or to sibling workers. If you want state to be visible to the next worker, set it up in YOUR browser before spawning.
 
 The worker has no further spawn capability — it cannot recursively spawn other pentest agents.
 
-After fanning out one worker per objective, call this tool ONE MORE TIME for a final "exploratory" worker. Pass it the URLs of any suspicious behaviors discovered by earlier workers and ask it to chain findings together and probe for additional, unspecified vulnerabilities.
+${exploratoryGuidance}
 
-False-positive discipline: workers should not call document_vulnerability for public/unauthenticated behavior, missing best-practice controls, generic errors, local HTTP deployment context, or other low-signal observations unless they prove a material abuse path such as non-public data access, credentialed cross-origin abuse, state change, denial of service, account takeover, or another concrete exploit chain.
+${findingGuidance}
 
-Returns the worker's summary, objective results, and finding count — but NOT the findings themselves (those land in the shared registry).`,
+${returnGuidance}`,
     inputSchema: z.object({
       name: z
         .string()
@@ -77,9 +93,7 @@ Returns the worker's summary, objective results, and finding count — but NOT t
       objectives: z
         .array(z.string())
         .min(1)
-        .describe(
-          "Testing objectives for this worker. For per-objective fan-out, pass exactly one objective. For the final exploratory pass, pass a single composite objective describing chaining + exploration.",
-        ),
+        .describe(`Testing objectives for this worker. ${objectiveGuidance}`),
       context: z
         .string()
         .optional()
@@ -130,6 +144,7 @@ Returns the worker's summary, objective results, and finding count — but NOT t
       const findingsRegistry =
         ctx.findingsRegistry ??
         FindingsRegistry.fromDirectory(ctx.session.findingsPath, {
+          reasoning: ctx.reasoning,
           model: ctx.model,
           authConfig: ctx.authConfig,
           abortSignal: ctx.abortSignal,
@@ -151,7 +166,7 @@ Returns the worker's summary, objective results, and finding count — but NOT t
       const spawner = ctx.subagentSpawner;
       let subagentId = "";
       try {
-        const { findings, objectiveResults } =
+        const { findings, reportedFindings, objectiveResults } =
           await spawner.spawn<PentestResult>({
             spec: {
               type: "pentest",
@@ -170,9 +185,9 @@ Returns the worker's summary, objective results, and finding count — but NOT t
               browserSession: sharedBrowserSession,
             },
             runtime: {
+              findingPolicy: ctx.findingPolicy,
               session: ctx.session,
-              model: ctx.model,
-              authConfig: ctx.authConfig,
+              ...getModelSettings(ctx),
               abortSignal: ctx.abortSignal,
               onStepFinish: ctx.onStepFinish,
               onCacheMetrics: ctx.onCacheMetrics,
@@ -180,11 +195,9 @@ Returns the worker's summary, objective results, and finding count — but NOT t
               backends: ctx.backends,
               display: ctx.display,
               secretValues: ctx.secretValues,
-              enableThinking: ctx.enableThinking,
-              thinkingEffort: ctx.thinkingEffort,
-              openAIReasoningEffort: ctx.openAIReasoningEffort,
               languageModelMiddleware: ctx.languageModelMiddleware,
               usageRecorder: ctx.usageRecorder,
+              toolExecutionContext: ctx.toolExecutionContext,
               streamIdFactory: ctx.streamIdFactory,
             },
             parentBus: ctx.eventBus,
@@ -203,9 +216,16 @@ Returns the worker's summary, objective results, and finding count — but NOT t
         return {
           success: true,
           subagentId,
-          findingsCount: findings.length,
+          findingsCount: externalFindings
+            ? (reportedFindings?.length ?? 0)
+            : findings.length,
+          ...(externalFindings
+            ? { reportedFindings: reportedFindings ?? [] }
+            : {}),
           objectiveResults,
-          message: `Worker '${name}' complete. Documented ${findings.length} finding(s).`,
+          message: externalFindings
+            ? `Worker '${name}' complete. Reported ${reportedFindings?.length ?? 0} finding(s) for external evaluation.`
+            : `Worker '${name}' complete. Documented ${findings.length} finding(s).`,
         };
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error);

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

@@ -21,15 +21,21 @@ const log = scopedLogger(() => createLogger("spawn-pentest-swarm"));
  * after recon, it calls this tool to fan-out testing to sub-agents.
  */
 export function spawnPentestSwarm(ctx: ToolContext) {
+  const externalFindings = ctx.findingPolicy === "external";
+  const findingSteps = externalFindings
+    ? "2. Surface concise evidence-backed findings in its response\n3. Leave finding acceptance to the caller's evaluator"
+    : "2. Create POC scripts for confirmed vulnerabilities\n3. Document findings with evidence and remediation";
+  const findingDestination = externalFindings
+    ? "Reported findings are returned to this caller; no native finding review runs."
+    : "All findings are written to the shared session directory.";
   return tool({
     description: `Launch a swarm of targeted pentest sub-agents to test multiple targets in parallel.
 
 Call this AFTER completing attack surface discovery. Each entry in 'targets' spawns an independent TargetedPentestAgent that will:
 1. Test the specified target for the given objectives
-2. Create POC scripts for confirmed vulnerabilities
-3. Document findings with evidence and remediation
+${findingSteps}
 
-All findings are written to the shared session directory.
+${findingDestination}
 
 Pass every target you want tested — the swarm handles concurrency automatically.`,
     inputSchema: z.object({
@@ -79,6 +85,7 @@ Pass every target you want tested — the swarm handles concurrency automaticall
       const findingsRegistry =
         ctx.findingsRegistry ??
         FindingsRegistry.fromDirectory(ctx.session.findingsPath, {
+          reasoning: ctx.reasoning,
           model: ctx.model!,
           authConfig: ctx.authConfig,
           abortSignal: ctx.abortSignal,
@@ -92,6 +99,7 @@ Pass every target you want tested — the swarm handles concurrency automaticall
       );
 
       const swarmResults = await runPentestSwarm({
+        findingPolicy: ctx.findingPolicy,
         targets,
         model: ctx.model!,
         session: ctx.session,
@@ -105,12 +113,15 @@ Pass every target you want tested — the swarm handles concurrency automaticall
         enableThinking: ctx.enableThinking,
         thinkingEffort: ctx.thinkingEffort,
         openAIReasoningEffort: ctx.openAIReasoningEffort,
+        reasoning: ctx.reasoning,
         display: ctx.display,
         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,
@@ -120,7 +131,11 @@ Pass every target you want tested — the swarm handles concurrency automaticall
 
       // Aggregate
       const totalFindings = swarmResults.reduce(
-        (sum, r) => sum + (r?.findings.length ?? 0),
+        (sum, r) =>
+          sum +
+          (externalFindings
+            ? (r?.reportedFindings?.length ?? 0)
+            : (r?.findings.length ?? 0)),
         0,
       );
       const failedCount = swarmResults.filter((r) => r == null).length;
@@ -132,7 +147,15 @@ Pass every target you want tested — the swarm handles concurrency automaticall
         failedTargets: failedCount,
         results: targets.map((t, i) => ({
           target: t.target,
-          findingsCount: swarmResults[i]?.findings.length ?? 0,
+          findingsCount: externalFindings
+            ? (swarmResults[i]?.reportedFindings?.length ?? 0)
+            : (swarmResults[i]?.findings.length ?? 0),
+          ...(externalFindings
+            ? {
+                reportedFindings: swarmResults[i]?.reportedFindings ?? [],
+                objectiveResults: swarmResults[i]?.objectiveResults ?? [],
+              }
+            : {}),
           error: swarmResults[i] == null ? "Agent failed" : undefined,
         })),
         message: `Swarm complete. ${totalFindings} findings across ${total} targets. ${

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

@@ -1,6 +1,7 @@
 import { stepCountIs } from "ai";
 import pLimit from "p-limit";
 import { z } from "zod";
+import { getModelSettings } from "../../../ai";
 import { createLogger } from "../../../logger/structured";
 import { scopedLogger } from "../../../util/lazyLogger";
 import type {
@@ -314,7 +315,6 @@ export async function generateThreatModelForEndpoint(
   input: GenerateThreatModelInput,
 ): Promise<ThreatModelOutput | null> {
   if (!ctx.model) return null;
-  const model = ctx.model;
 
   return threatModelLimiter(async () => {
     if (ctx.abortSignal?.aborted) return null;
@@ -373,13 +373,14 @@ export async function generateThreatModelForEndpoint(
           excludeTools: ["document_endpoint", "document_app"],
         },
         runtime: {
+          findingPolicy: ctx.findingPolicy,
           session: ctx.session,
-          model,
-          authConfig: ctx.authConfig,
+          ...getModelSettings(ctx),
           abortSignal: childAbort.signal,
           backends: ctx.backends,
           languageModelMiddleware: ctx.languageModelMiddleware,
           usageRecorder: ctx.usageRecorder,
+          toolExecutionContext: ctx.toolExecutionContext,
           streamIdFactory: ctx.streamIdFactory,
         },
         parentBus: ctx.eventBus,

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

@@ -8,6 +8,7 @@ import type {
   AIModel,
   CacheMetrics,
   OpenAIReasoningEffort,
+  ReasoningSetting,
   ThinkingEffort,
   UsageRecorder,
 } from "../../../ai";
@@ -22,7 +23,12 @@ import type { ToolBackends } from "../../../tools/backends/types";
 import type { GrpcPentestContext } from "../../specialized/attackSurface/grpcSchema";
 import type { SubagentSpawner } from "../subagentSpawner";
 import type { StepTraceWriter } from "../trace";
-import type { StreamIdFactory, SystemPentestScope } from "../types";
+import type {
+  AgentHooks,
+  FindingPolicy,
+  StreamIdFactory,
+  SystemPentestScope,
+} from "../types";
 import type { CallbackListenerRegistry } from "./callbackListener";
 import type { EmailAdapterResolver } from "./email/adapters";
 import type { PerCommandShell } from "./perCommandShell";
@@ -38,6 +44,7 @@ import type { SmsInbox } from "./smsInbox";
  * session or agent internals directly.
  */
 export type ToolContext = {
+  findingPolicy?: FindingPolicy;
   attackSurfaceArtifactsPath?: string;
 
   /** Session providing paths for findings, POCs, logs, scratchpad, etc. */
@@ -172,6 +179,7 @@ export type ToolContext = {
 
   /** OpenAI reasoning effort for GPT/o-series sub-agents. */
   openAIReasoningEffort?: OpenAIReasoningEffort | null;
+  reasoning?: ReasoningSetting;
 
   /**
    * Whitebox attack surface flag. Forwarded into `runPentestWorkflow` so the
@@ -229,7 +237,7 @@ export type ToolContext = {
    * the agent builds its tools (`OffensiveSecurityAgentInput.subagentSpawner` ??
    * the in-process spawner), so it is always present here and tools never
    * re-default it; a durable runtime injects one that spawns child workflows
-   * instead. The three durable hooks below are inherited by every child the
+   * instead. The durable hooks below are inherited by every child the
    * spawner constructs.
    */
   subagentSpawner: SubagentSpawner;
@@ -256,6 +264,8 @@ export type ToolContext = {
    */
   emailAdapterFor?: EmailAdapterResolver;
 
+  toolExecutionContext?: AgentHooks["toolExecutionContext"];
+
   /** Provider middleware inherited by spawned children. Unset → raw model. */
   languageModelMiddleware?: LanguageModelMiddleware | LanguageModelMiddleware[];
 

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

@@ -34,12 +34,16 @@ type UpdateTaskResult = {
 };
 
 export function updateTask(ctx: ToolContext) {
+  const completedGuidance =
+    ctx.findingPolicy === "external"
+      ? "vulnerability identified with supporting evidence, OR conclusively determined the endpoint is not vulnerable / materiality is not met for this technique."
+      : "vulnerability found and documented via document_vulnerability, OR conclusively determined the endpoint is not vulnerable / materiality is not met for this technique. Documentation is NOT required to complete a non-vulnerable task.";
   return tool({
     description: `Update a task's status and record results.
 
 Status transitions:
 - "in_progress" — Set when you START testing a task. Pick one pending task at a time.
-- "completed" — Set when testing is done: vulnerability found and documented via document_vulnerability, OR conclusively determined the endpoint is not vulnerable / materiality is not met for this technique. Documentation is NOT required to complete a non-vulnerable task.
+- "completed" — Set when testing is done: ${completedGuidance}
 - "failed" — Set when the technique didn't work: rate limited, blocked by WAF, dead end, or approach not applicable. Then create a NEW task with an alternative technique.
 
 Always include a result or observation explaining the outcome.`,

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

@@ -47,12 +47,15 @@ const CandidateStateSchema = z.enum([
 ]);
 
 export function createWhiteboxCandidate(ctx: ToolContext) {
+  const candidateGuidance =
+    ctx.findingPolicy === "external"
+      ? "for the caller's final evaluation. Candidates keep hypotheses, source-to-sink traces, scanner artifacts, fuzzing logs, and verification status separate from reported findings."
+      : "for document_vulnerability. Candidates keep hypotheses, source-to-sink traces,\nscanner artifacts, fuzzing logs, and verification status out of official findings.";
   return tool({
     description: `Create a whitebox vulnerability candidate.
 
 Use this for plausible source-code findings that are not yet confirmed enough
-for document_vulnerability. Candidates keep hypotheses, source-to-sink traces,
-scanner artifacts, fuzzing logs, and verification status out of official findings.`,
+${candidateGuidance}`,
     inputSchema: z.object({
       title: z.string(),
       vulnerabilityClass: z.string(),
@@ -81,7 +84,9 @@ scanner artifacts, fuzzing logs, and verification status out of official finding
         artifactPaths: candidate.artifacts.map((artifact) => artifact.path),
         nextActions: [
           "Move candidate to investigating after reading source context.",
-          "Attempt a reproducer or dynamic verification before document_vulnerability.",
+          ctx.findingPolicy === "external"
+            ? "Gather the evidence required by the caller before reporting this candidate."
+            : "Attempt a reproducer or dynamic verification before document_vulnerability.",
         ],
         truncated: false,
       };
@@ -132,7 +137,9 @@ State machine: hypothesis -> investigating -> repro_attempted -> confirmed (requ
           nextActions:
             candidate.state === "confirmed"
               ? [
-                  "Use document_vulnerability only if the proof demonstrates exploitability.",
+                  ctx.findingPolicy === "external"
+                    ? "Report only the evidence-backed conclusion to the caller."
+                    : "Use document_vulnerability only if the proof demonstrates exploitability.",
                 ]
               : [
                   "Continue tracing or verification based on the candidate state.",