feat: use structured outputs for vuln agent exploitation queues (#267)

* feat: add structured outputs for vuln agent exploitation queues

Use Claude Agent SDK's native outputFormat to get schema-validated JSON
queue data from vulnerability analysis agents instead of relying on
save-deliverable tool calls for queue files.

- Add Zod schemas for all 5 vuln types (injection, xss, auth, ssrf, authz)
- Thread outputFormat through SDK call chain (executor → message handlers)
- Write structured_output to disk as queue JSON before validation
- Handle error_max_structured_output_retries as retryable failure
- Update vuln prompts to use structured output for queues
- Keep save-deliverable for markdown deliverables (unchanged)

* fix: correct structured output schema conversion for Claude Agent SDK

Use draft-07 target for z.toJSONSchema() instead of the default
draft-2020-12, which the SDK's AJV validator doesn't support. Update
pipeline-testing prompts to use structured output instead of raw JSON
responses.

* refactor: remove save-deliverable references for queues in vuln prompts

Queues are now captured via structured outputs, so vuln agents no longer
need to use save-deliverable for queue JSON. Removes references to
"structured response/output" phrasing and aligns all prompts to use
consistent "exploitation queue" terminology.

* refactor: remove queue support from save-deliverable

Queues are now produced via structured outputs, so save-deliverable no
longer needs queue-related code. Removes queue enum values, filename
mappings, JSON validation, and updates all prompt tool descriptions to
match the simplified CLI interface.

* fix: instruct vuln agents to save deliverable before exploitation queue

The structured output tool terminates the agent session when called.
Agents were calling it before saving their deliverable markdown,
causing output validation failures and unnecessary retries.

* refactor: remove explicit exploitation queue output instructions from vuln prompts

The Claude Agent SDK automatically captures structured output on the
last turn when outputFormat is set. Prompts explicitly telling agents
to produce the queue caused them to call StructuredOutput mid-session,
conflicting with the SDK mechanism and silently dropping the output.

Removed exploitation_queue_requirements sections and queue references
from conclusion triggers. Added note that the queue is captured
automatically. Updated Your Output to point to the deliverable markdown.

apps/worker/src/ai/claude-executor.ts

@@ -6,7 +6,7 @@
 
 // Production Claude agent execution with retry, git checkpoints, and audit logging
 
-import { query } from '@anthropic-ai/claude-agent-sdk';
+import { type JsonSchemaOutputFormat, query } from '@anthropic-ai/claude-agent-sdk';
 import { fs, path } from 'zx';
 import type { AuditSession } from '../audit/index.js';
 import { isRetryableError, PentestError } from '../services/error-handling.js';
@@ -39,6 +39,7 @@ export interface ClaudePromptResult {
   errorType?: string | undefined;
   prompt?: string | undefined;
   retryable?: boolean | undefined;
+  structuredOutput?: unknown;
 }
 
 function outputLines(lines: string[]): void {
@@ -132,6 +133,7 @@ export async function runClaudePrompt(
   auditSession: AuditSession | null = null,
   logger: ActivityLogger,
   modelTier: ModelTier = 'medium',
+  outputFormat?: JsonSchemaOutputFormat,
 ): Promise<ClaudePromptResult> {
   // 1. Initialize timing and prompt
   const timer = new Timer(`agent-${description.toLowerCase().replace(/\s+/g, '-')}`);
@@ -186,6 +188,7 @@ export async function runClaudePrompt(
     allowDangerouslySkipPermissions: true,
     settingSources: ['user'] as ('user' | 'project' | 'local')[],
     env: sdkEnv,
+    ...(outputFormat && { outputFormat }),
   };
 
   if (!execContext.useCleanOutput) {
@@ -243,6 +246,9 @@ export async function runClaudePrompt(
       model,
       partialCost: totalCost,
       apiErrorDetected,
+      ...(messageLoopResult.structuredOutput !== undefined && {
+        structuredOutput: messageLoopResult.structuredOutput,
+      }),
     };
   } catch (error) {
     // 9. Handle errors — log, write error file, return failure
@@ -273,6 +279,7 @@ interface MessageLoopResult {
   apiErrorDetected: boolean;
   cost: number;
   model?: string | undefined;
+  structuredOutput?: unknown;
 }
 
 interface MessageLoopDeps {
@@ -297,6 +304,7 @@ async function processMessageStream(
   let apiErrorDetected = false;
   let cost = 0;
   let model: string | undefined;
+  let structuredOutput: unknown | undefined;
   let lastHeartbeat = Date.now();
 
   for await (const message of query({ prompt: fullPrompt, options })) {
@@ -327,6 +335,9 @@ async function processMessageStream(
     if (dispatchResult.type === 'complete') {
       result = dispatchResult.result;
       cost = dispatchResult.cost;
+      if (dispatchResult.structuredOutput !== undefined) {
+        structuredOutput = dispatchResult.structuredOutput;
+      }
       break;
     }
 
@@ -341,5 +352,12 @@ async function processMessageStream(
     }
   }
 
-  return { turnCount, result, apiErrorDetected, cost, model };
+  return {
+    turnCount,
+    result,
+    apiErrorDetected,
+    cost,
+    model,
+    ...(structuredOutput !== undefined && { structuredOutput }),
+  };
 }

apps/worker/src/ai/message-handlers.ts

@@ -223,6 +223,10 @@ function handleResultMessage(message: ResultMessage): ResultData {
     }
   }
 
+  if (message.structured_output !== undefined) {
+    result.structuredOutput = message.structured_output;
+  }
+
   return result;
 }
 
@@ -259,7 +263,7 @@ function outputLines(lines: string[]): void {
 
 export type MessageDispatchAction =
   | { type: 'continue'; apiErrorDetected?: boolean | undefined; model?: string | undefined }
-  | { type: 'complete'; result: string | null; cost: number }
+  | { type: 'complete'; result: string | null; cost: number; structuredOutput?: unknown }
   | { type: 'throw'; error: Error };
 
 export interface MessageDispatchDeps {
@@ -338,7 +342,26 @@ export async function dispatchMessage(
     case 'result': {
       const resultData = handleResultMessage(message as ResultMessage);
       outputLines(formatResultOutput(resultData, !execContext.useCleanOutput));
-      return { type: 'complete', result: resultData.result, cost: resultData.cost };
+
+      if (resultData.subtype === 'error_max_structured_output_retries') {
+        return {
+          type: 'throw',
+          error: new PentestError(
+            'Structured output validation failed after max retries',
+            'validation',
+            true,
+            {},
+            ErrorCode.OUTPUT_VALIDATION_FAILED,
+          ),
+        };
+      }
+
+      return {
+        type: 'complete' as const,
+        result: resultData.result,
+        cost: resultData.cost,
+        ...(resultData.structuredOutput !== undefined && { structuredOutput: resultData.structuredOutput }),
+      };
     }
 
     default:

apps/worker/src/ai/queue-schemas.ts

@@ -0,0 +1,124 @@
+// Copyright (C) 2025 Keygraph, Inc.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License version 3
+// as published by the Free Software Foundation.
+
+/**
+ * Zod schema definitions for vulnerability exploitation queue structured outputs.
+ *
+ * Each vuln agent returns a structured JSON response matching its schema.
+ * The SDK validates the output against the JSON Schema generated from these Zod definitions.
+ */
+
+import type { JsonSchemaOutputFormat } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import type { AgentName } from '../types/agents.js';
+
+// === Common Fields ===
+
+const baseVulnerability = z.object({
+  ID: z.string(),
+  vulnerability_type: z.string(),
+  externally_exploitable: z.boolean(),
+  confidence: z.string(),
+  notes: z.string().optional(),
+});
+
+// === Per-Vuln-Type Schemas ===
+
+const InjectionVulnerability = baseVulnerability.extend({
+  source: z.string().optional(),
+  combined_sources: z.string().optional(),
+  path: z.string().optional(),
+  sink_call: z.string().optional(),
+  slot_type: z.string().optional(),
+  sanitization_observed: z.string().optional(),
+  concat_occurrences: z.string().optional(),
+  verdict: z.string().optional(),
+  mismatch_reason: z.string().optional(),
+  witness_payload: z.string().optional(),
+});
+
+const XssVulnerability = baseVulnerability.extend({
+  source: z.string().optional(),
+  source_detail: z.string().optional(),
+  path: z.string().optional(),
+  sink_function: z.string().optional(),
+  render_context: z.string().optional(),
+  encoding_observed: z.string().optional(),
+  verdict: z.string().optional(),
+  mismatch_reason: z.string().optional(),
+  witness_payload: z.string().optional(),
+});
+
+const AuthVulnerability = baseVulnerability.extend({
+  source_endpoint: z.string().optional(),
+  vulnerable_code_location: z.string().optional(),
+  missing_defense: z.string().optional(),
+  exploitation_hypothesis: z.string().optional(),
+  suggested_exploit_technique: z.string().optional(),
+});
+
+const SsrfVulnerability = baseVulnerability.extend({
+  source_endpoint: z.string().optional(),
+  vulnerable_parameter: z.string().optional(),
+  vulnerable_code_location: z.string().optional(),
+  missing_defense: z.string().optional(),
+  exploitation_hypothesis: z.string().optional(),
+  suggested_exploit_technique: z.string().optional(),
+});
+
+const AuthzVulnerability = baseVulnerability.extend({
+  endpoint: z.string().optional(),
+  vulnerable_code_location: z.string().optional(),
+  role_context: z.string().optional(),
+  guard_evidence: z.string().optional(),
+  side_effect: z.string().optional(),
+  reason: z.string().optional(),
+  minimal_witness: z.string().optional(),
+});
+
+// === Queue Wrapper Schemas ===
+
+const InjectionQueueSchema = z.object({ vulnerabilities: z.array(InjectionVulnerability) });
+const XssQueueSchema = z.object({ vulnerabilities: z.array(XssVulnerability) });
+const AuthQueueSchema = z.object({ vulnerabilities: z.array(AuthVulnerability) });
+const SsrfQueueSchema = z.object({ vulnerabilities: z.array(SsrfVulnerability) });
+const AuthzQueueSchema = z.object({ vulnerabilities: z.array(AuthzVulnerability) });
+
+// === Convert to JSON Schema for SDK ===
+
+// NOTE: The SDK's AJV validator expects draft-07. Zod defaults to draft-2020-12 which
+// causes the SDK to silently skip structured output.
+function toOutputFormat(zodSchema: z.ZodType): JsonSchemaOutputFormat {
+  return { type: 'json_schema', schema: z.toJSONSchema(zodSchema, { target: 'draft-07' }) as Record<string, unknown> };
+}
+
+// === Lookup Maps ===
+
+const VULN_AGENT_OUTPUT_FORMAT: Partial<Record<AgentName, JsonSchemaOutputFormat>> = {
+  'injection-vuln': toOutputFormat(InjectionQueueSchema),
+  'xss-vuln': toOutputFormat(XssQueueSchema),
+  'auth-vuln': toOutputFormat(AuthQueueSchema),
+  'ssrf-vuln': toOutputFormat(SsrfQueueSchema),
+  'authz-vuln': toOutputFormat(AuthzQueueSchema),
+};
+
+const VULN_AGENT_QUEUE_FILENAMES: Partial<Record<AgentName, string>> = {
+  'injection-vuln': 'injection_exploitation_queue.json',
+  'xss-vuln': 'xss_exploitation_queue.json',
+  'auth-vuln': 'auth_exploitation_queue.json',
+  'ssrf-vuln': 'ssrf_exploitation_queue.json',
+  'authz-vuln': 'authz_exploitation_queue.json',
+};
+
+/** Returns the structured output format for a vuln agent, or undefined for non-vuln agents. */
+export function getOutputFormat(agentName: AgentName): JsonSchemaOutputFormat | undefined {
+  return VULN_AGENT_OUTPUT_FORMAT[agentName];
+}
+
+/** Returns the queue filename for a vuln agent, or undefined for non-vuln agents. */
+export function getQueueFilename(agentName: AgentName): string | undefined {
+  return VULN_AGENT_QUEUE_FILENAMES[agentName];
+}

apps/worker/src/ai/types.ts

@@ -34,6 +34,7 @@ export interface ResultData {
   subtype?: string;
   stop_reason?: string | null;
   permissionDenials: number;
+  structuredOutput?: unknown;
 }
 
 export interface ToolUseData {
@@ -69,6 +70,7 @@ export interface ResultMessage {
   subtype?: string;
   stop_reason?: string | null;
   permission_denials?: unknown[];
+  structured_output?: unknown;
 }
 
 export interface ToolUseMessage {

apps/worker/src/scripts/save-deliverable.ts

@@ -9,17 +9,15 @@
 /**
  * save-deliverable CLI
  *
- * Standalone script to save deliverable files with validation.
- * Replaces the MCP save_deliverable tool.
+ * Standalone script to save deliverable files.
  *
  * Usage:
- *   node save-deliverable.js --type INJECTION_QUEUE --content '{"vulnerabilities": [...]}'
  *   node save-deliverable.js --type INJECTION_ANALYSIS --file-path deliverables/injection_analysis_deliverable.md
  */
 
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
-import { DELIVERABLE_FILENAMES, type DeliverableType, isQueueType } from '../types/deliverables.js';
+import { DELIVERABLE_FILENAMES, type DeliverableType } from '../types/deliverables.js';
 
 // === Argument Parsing ===
 
@@ -51,49 +49,6 @@ function parseArgs(argv: string[]): ParsedArgs {
   return args;
 }
 
-// === Queue Validation ===
-
-interface ValidationResult {
-  valid: boolean;
-  message?: string;
-}
-
-function validateQueueJson(content: string): ValidationResult {
-  try {
-    const parsed = JSON.parse(content) as unknown;
-
-    if (typeof parsed !== 'object' || parsed === null) {
-      return {
-        valid: false,
-        message: `Invalid queue structure: Expected an object. Got: ${typeof parsed}`,
-      };
-    }
-
-    const obj = parsed as Record<string, unknown>;
-
-    if (!('vulnerabilities' in obj)) {
-      return {
-        valid: false,
-        message: `Invalid queue structure: Missing 'vulnerabilities' property. Expected: {"vulnerabilities": [...]}`,
-      };
-    }
-
-    if (!Array.isArray(obj.vulnerabilities)) {
-      return {
-        valid: false,
-        message: `Invalid queue structure: 'vulnerabilities' must be an array. Expected: {"vulnerabilities": [...]}`,
-      };
-    }
-
-    return { valid: true };
-  } catch (error) {
-    return {
-      valid: false,
-      message: `Invalid JSON: ${error instanceof Error ? error.message : String(error)}`,
-    };
-  }
-}
-
 // === File Operations ===
 
 function saveDeliverableFile(targetDir: string, filename: string, content: string): string {
@@ -165,22 +120,11 @@ function main(): void {
     process.exit(1);
   }
 
-  // 3. Validate queue types
-  let validated = false;
-  if (isQueueType(args.type)) {
-    const validation = validateQueueJson(content);
-    if (!validation.valid) {
-      console.log(JSON.stringify({ status: 'error', message: validation.message, retryable: true }));
-      process.exit(1);
-    }
-    validated = true;
-  }
-
-  // 4. Save the file
+  // 3. Save the file
   try {
     const targetDir = process.cwd();
     const filepath = saveDeliverableFile(targetDir, filename, content);
-    console.log(JSON.stringify({ status: 'success', filepath, validated }));
+    console.log(JSON.stringify({ status: 'success', filepath }));
   } catch (error) {
     const msg = error instanceof Error ? error.message : String(error);
     console.log(JSON.stringify({ status: 'error', message: `Failed to save: ${msg}`, retryable: true }));

apps/worker/src/services/agent-execution.ts

@@ -21,7 +21,9 @@
  * No Temporal dependencies - pure domain logic.
  */
 
+import { fs, path } from 'zx';
 import { type ClaudePromptResult, runClaudePrompt, validateAgentOutput } from '../ai/claude-executor.js';
+import { getOutputFormat, getQueueFilename } from '../ai/queue-schemas.js';
 import type { AuditSession } from '../audit/index.js';
 import { AGENTS } from '../session-manager.js';
 import type { ActivityLogger } from '../types/activity-logger.js';
@@ -134,6 +136,7 @@ export class AgentExecutionService {
     await auditSession.startAgent(agentName, prompt, attemptNumber);
 
     // 5. Execute agent
+    const outputFormat = getOutputFormat(agentName);
     const result: ClaudePromptResult = await runClaudePrompt(
       prompt,
       repoPath,
@@ -143,6 +146,7 @@ export class AgentExecutionService {
       auditSession,
       logger,
       AGENTS[agentName].modelTier,
+      outputFormat,
     );
 
     // 6. Spending cap check - defense-in-depth
@@ -176,7 +180,17 @@ export class AgentExecutionService {
       });
     }
 
-    // 8. Validate output
+    // 8. Write structured output to disk (vuln agents only)
+    const queueFilename = getQueueFilename(agentName);
+    if (result.structuredOutput !== undefined && queueFilename) {
+      const deliverablesDir = path.join(repoPath, 'deliverables');
+      await fs.ensureDir(deliverablesDir);
+      const queuePath = path.join(deliverablesDir, queueFilename);
+      await fs.writeFile(queuePath, JSON.stringify(result.structuredOutput, null, 2), 'utf8');
+      logger.info(`Wrote structured output queue to ${queueFilename}`);
+    }
+
+    // 9. Validate output
     const validationPassed = await validateAgentOutput(result, agentName, repoPath, logger);
     if (!validationPassed) {
       return this.failAgent(agentName, repoPath, auditSession, logger, {
@@ -191,7 +205,7 @@ export class AgentExecutionService {
       });
     }
 
-    // 9. Success - commit deliverables, then capture checkpoint hash
+    // 10. Success - commit deliverables, then capture checkpoint hash
     await commitGitSuccess(repoPath, agentName, logger);
     const commitHash = await getGitCommitHash(repoPath);
 

apps/worker/src/services/queue-validation.ts

@@ -114,12 +114,12 @@ function getExistenceErrorMessage(existence: FileExistence): string {
   const { deliverableExists, queueExists } = existence;
 
   if (!deliverableExists && !queueExists) {
-    return 'Analysis failed: Neither deliverable nor queue file exists. Analysis agent must create both files.';
+    return 'Analysis failed: Neither deliverable nor queue file exists. Both are required.';
   }
   if (!queueExists) {
-    return 'Analysis incomplete: Deliverable exists but queue file missing. Analysis agent must create both files.';
+    return 'Analysis incomplete: Deliverable exists but queue file missing. Both are required.';
   }
-  return 'Analysis incomplete: Queue exists but deliverable file missing. Analysis agent must create both files.';
+  return 'Analysis incomplete: Queue exists but deliverable file missing. Both are required.';
 }
 
 // Pure function to create file paths

apps/worker/src/types/deliverables.ts

@@ -7,7 +7,7 @@
 /**
  * Deliverable Type Definitions
  *
- * Maps deliverable types to their filenames and defines validation requirements.
+ * Maps deliverable types to their filenames for the save-deliverable CLI.
  */
 
 export enum DeliverableType {
@@ -19,19 +19,10 @@ export enum DeliverableType {
 
   // Vulnerability analysis agents
   INJECTION_ANALYSIS = 'INJECTION_ANALYSIS',
-  INJECTION_QUEUE = 'INJECTION_QUEUE',
-
   XSS_ANALYSIS = 'XSS_ANALYSIS',
-  XSS_QUEUE = 'XSS_QUEUE',
-
   AUTH_ANALYSIS = 'AUTH_ANALYSIS',
-  AUTH_QUEUE = 'AUTH_QUEUE',
-
   AUTHZ_ANALYSIS = 'AUTHZ_ANALYSIS',
-  AUTHZ_QUEUE = 'AUTHZ_QUEUE',
-
   SSRF_ANALYSIS = 'SSRF_ANALYSIS',
-  SSRF_QUEUE = 'SSRF_QUEUE',
 
   // Exploitation agents
   INJECTION_EVIDENCE = 'INJECTION_EVIDENCE',
@@ -48,47 +39,13 @@ export const DELIVERABLE_FILENAMES: Record<DeliverableType, string> = {
   [DeliverableType.CODE_ANALYSIS]: 'code_analysis_deliverable.md',
   [DeliverableType.RECON]: 'recon_deliverable.md',
   [DeliverableType.INJECTION_ANALYSIS]: 'injection_analysis_deliverable.md',
-  [DeliverableType.INJECTION_QUEUE]: 'injection_exploitation_queue.json',
   [DeliverableType.XSS_ANALYSIS]: 'xss_analysis_deliverable.md',
-  [DeliverableType.XSS_QUEUE]: 'xss_exploitation_queue.json',
   [DeliverableType.AUTH_ANALYSIS]: 'auth_analysis_deliverable.md',
-  [DeliverableType.AUTH_QUEUE]: 'auth_exploitation_queue.json',
   [DeliverableType.AUTHZ_ANALYSIS]: 'authz_analysis_deliverable.md',
-  [DeliverableType.AUTHZ_QUEUE]: 'authz_exploitation_queue.json',
   [DeliverableType.SSRF_ANALYSIS]: 'ssrf_analysis_deliverable.md',
-  [DeliverableType.SSRF_QUEUE]: 'ssrf_exploitation_queue.json',
   [DeliverableType.INJECTION_EVIDENCE]: 'injection_exploitation_evidence.md',
   [DeliverableType.XSS_EVIDENCE]: 'xss_exploitation_evidence.md',
   [DeliverableType.AUTH_EVIDENCE]: 'auth_exploitation_evidence.md',
   [DeliverableType.AUTHZ_EVIDENCE]: 'authz_exploitation_evidence.md',
   [DeliverableType.SSRF_EVIDENCE]: 'ssrf_exploitation_evidence.md',
 };
-
-/**
- * Queue types that require JSON validation
- */
-export const QUEUE_TYPES: DeliverableType[] = [
-  DeliverableType.INJECTION_QUEUE,
-  DeliverableType.XSS_QUEUE,
-  DeliverableType.AUTH_QUEUE,
-  DeliverableType.AUTHZ_QUEUE,
-  DeliverableType.SSRF_QUEUE,
-];
-
-/**
- * Type guard to check if a deliverable type is a queue
- */
-export function isQueueType(type: string): boolean {
-  return QUEUE_TYPES.includes(type as DeliverableType);
-}
-
-/**
- * Vulnerability queue structure
- */
-export interface VulnerabilityQueue {
-  vulnerabilities: VulnerabilityItem[];
-}
-
-export interface VulnerabilityItem {
-  [key: string]: unknown;
-}