appsec-agent 2.8.0 → 3.1.0

package/dist/src/agent_options.js

@@ -5,8 +5,7 @@
  * Author: Sam Li
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AgentOptions = exports.MCP_INTERNAL_TOOL_NAMES = exports.MCP_INTERNAL_SERVER_NAME = exports.DEFAULT_MCP_SERVER_NAME = void 0;
-exports.buildMcpInternalToolNames = buildMcpInternalToolNames;
+exports.AgentOptions = exports.buildMcpInternalToolNames = exports.MCP_INTERNAL_TOOL_NAMES = exports.MCP_INTERNAL_SERVER_NAME = exports.DEFAULT_MCP_SERVER_NAME = void 0;
 exports.buildPrReviewerMcpNudgeSystemPromptSuffix = buildPrReviewerMcpNudgeSystemPromptSuffix;
 const security_report_1 = require("./schemas/security_report");
 const threat_model_report_1 = require("./schemas/threat_model_report");
@@ -16,6 +15,12 @@ const finding_validator_1 = require("./schemas/finding_validator");
 const context_extraction_1 = require("./schemas/context_extraction");
 const learned_guidance_1 = require("./schemas/learned_guidance");
 const fp_adversary_pass_1 = require("./schemas/fp_adversary_pass");
+const claude_role_spec_1 = require("./providers/claude_role_spec");
+const mcp_internal_1 = require("./mcp_internal");
+Object.defineProperty(exports, "DEFAULT_MCP_SERVER_NAME", { enumerable: true, get: function () { return mcp_internal_1.DEFAULT_MCP_SERVER_NAME; } });
+Object.defineProperty(exports, "MCP_INTERNAL_SERVER_NAME", { enumerable: true, get: function () { return mcp_internal_1.MCP_INTERNAL_SERVER_NAME; } });
+Object.defineProperty(exports, "MCP_INTERNAL_TOOL_NAMES", { enumerable: true, get: function () { return mcp_internal_1.MCP_INTERNAL_TOOL_NAMES; } });
+Object.defineProperty(exports, "buildMcpInternalToolNames", { enumerable: true, get: function () { return mcp_internal_1.buildMcpInternalToolNames; } });
 const FIX_CODE_VS_OPTIONS_GUIDANCE = `
 
 FIXED CODE vs FIX OPTIONS:
@@ -24,54 +29,6 @@ FIXED CODE vs FIX OPTIONS:
 - Use "fix_options" when the fix requires architectural decisions, domain-specific knowledge,
   or when multiple valid remediation approaches exist. Each option needs an id, title, and description.
 - Provide either fixed_code OR fix_options per finding, not both.`;
-/**
- * Default identifier the agent uses to register a parent-app-managed MCP
- * server with the Claude Agent SDK. The resulting tool names exposed to
- * the LLM follow the SDK convention `mcp__<server>__<tool>`, so this
- * value becomes the literal prefix the model sees on its tool list.
- *
- * The default is intentionally generic (`appsec-internal`) so the
- * `appsec-agent` package is reusable across parent apps. Callers that
- * need a different identifier — e.g. to keep an existing prompt-nudge or
- * counter contract stable — pass `--mcp-server-name <name>` on the CLI
- * (or `mcpServerName` to the role builders directly), and the override
- * threads through to both `Options.mcpServers[<name>]` and the namespaced
- * tool names in the subagent whitelist.
- */
-exports.DEFAULT_MCP_SERVER_NAME = 'appsec-internal';
-/**
- * @deprecated since v2.4.2 — historical alias for the default server name.
- * Kept exported so existing imports keep type-checking; new code should
- * read `DEFAULT_MCP_SERVER_NAME` (and pass an override via
- * `mcpServerName` when a specific identifier is required).
- */
-exports.MCP_INTERNAL_SERVER_NAME = exports.DEFAULT_MCP_SERVER_NAME;
-/**
- * Tools exposed by the per-scan in-process MCP server the parent app
- * stands up. Pinned at this set (`queryFindingsHistory`,
- * `queryImportGraph`, `queryRuntimeEnrichment`, `queryCodebaseGraph`) so
- * the agent's tool whitelist is deterministic at the current version;
- * parent apps that expose a different surface should fork or extend this
- * list rather than rely on dynamic discovery (the SDK would otherwise have
- * to round-trip the server before constructing the whitelist).
- */
-exports.MCP_INTERNAL_TOOL_NAMES = [
-    'queryFindingsHistory',
-    'queryImportGraph',
-    'queryRuntimeEnrichment',
-    'queryCodebaseGraph',
-];
-/**
- * SDK-namespaced tool names the LLM sees on its tool list when the server
- * is wired up. Exposed as a helper rather than a constant so callers in
- * `agent_options.ts` and the test suite share one source of truth.
- *
- * @param serverName - Override for the MCP server identifier. Defaults
- *   to `DEFAULT_MCP_SERVER_NAME` (`appsec-internal`).
- */
-function buildMcpInternalToolNames(serverName = exports.DEFAULT_MCP_SERVER_NAME) {
-    return exports.MCP_INTERNAL_TOOL_NAMES.map((tool) => `mcp__${serverName}__${tool}`);
-}
 /**
  * System-prompt suffix for `pr_reviewer` / `code_reviewer` when
  * `--mcp-server-url` is set. Steers the model toward all live parent-app
@@ -88,8 +45,8 @@ function buildMcpInternalToolNames(serverName = exports.DEFAULT_MCP_SERVER_NAME)
  * @param mcpServerName - Same override as `attachMcpServerToOptions`
  *   (`DEFAULT_MCP_SERVER_NAME` when omitted).
  */
-function buildPrReviewerMcpNudgeSystemPromptSuffix(mcpServerName = exports.DEFAULT_MCP_SERVER_NAME) {
-    const name = mcpServerName || exports.DEFAULT_MCP_SERVER_NAME;
+function buildPrReviewerMcpNudgeSystemPromptSuffix(mcpServerName = mcp_internal_1.DEFAULT_MCP_SERVER_NAME) {
+    const name = mcpServerName || mcp_internal_1.DEFAULT_MCP_SERVER_NAME;
     const findingsTool = `mcp__${name}__queryFindingsHistory`;
     const importGraphTool = `mcp__${name}__queryImportGraph`;
     const runtimeTool = `mcp__${name}__queryRuntimeEnrichment`;
@@ -101,24 +58,13 @@ function buildPrReviewerMcpNudgeSystemPromptSuffix(mcpServerName = exports.DEFAU
 }
 /**
  * Mutate an already-built `Options` object to attach the MCP server config
- * (top-level `mcpServers`) and extend the named subagent's `tools`
- * whitelist with the backend-backed tool surface. No-op when
- * `mcpServerUrl` is falsy — preserves the pre-v2.4.0 behaviour for
- * callers that don't pass the new parameter.
- *
- * Mutating in place (rather than returning a fresh object) keeps the
- * existing role builders' return statements untouched and avoids a deep
- * clone of the (large) `Options` shape.
- *
- * @param mcpServerName - Override for the server identifier. Defaults
- *   to `DEFAULT_MCP_SERVER_NAME` (`appsec-internal`); pass the parent
- *   app's chosen name to keep tool-name contracts stable.
+ * @deprecated Use attachMcpToRoleSpec + roleSpecToClaudeOptions instead.
  */
-function attachMcpServerToOptions(options, mcpServerUrl, agentKey, mcpServerName = exports.DEFAULT_MCP_SERVER_NAME, mcpServerBearer) {
+function attachMcpServerToOptions(options, mcpServerUrl, agentKey, mcpServerName = mcp_internal_1.DEFAULT_MCP_SERVER_NAME, mcpServerBearer) {
     if (!mcpServerUrl) {
         return;
     }
-    const serverName = mcpServerName || exports.DEFAULT_MCP_SERVER_NAME;
+    const serverName = mcpServerName || mcp_internal_1.DEFAULT_MCP_SERVER_NAME;
     const httpEntry = {
         type: 'http',
         url: mcpServerUrl,
@@ -133,7 +79,7 @@ function attachMcpServerToOptions(options, mcpServerUrl, agentKey, mcpServerName
     const agent = options.agents?.[agentKey];
     if (agent) {
         const existingTools = agent.tools ?? [];
-        agent.tools = [...existingTools, ...buildMcpInternalToolNames(serverName)];
+        agent.tools = [...existingTools, ...(0, mcp_internal_1.buildMcpInternalToolNames)(serverName)];
     }
 }
 class AgentOptions {
@@ -181,19 +127,26 @@ class AgentOptions {
     /**
      * Get options for simple query agent
      */
-    getSimpleQueryAgentOptions(role = 'simple_query_agent', srcDir) {
+    getSimpleQueryAgentRoleSpec(role = 'simple_query_agent', srcDir) {
         const roleConfig = this.confDict[this.environment]?.[role];
         let systemPrompt = roleConfig?.options?.system_prompt ||
             'You are an Application Security (AppSec) expert assistant. You are responsible for providing security advice and guidance to the user.';
-        // Add source directory context to system prompt if provided
         if (srcDir) {
             systemPrompt += ` You have access to a source code directory at ${srcDir} that you can search and read files from to answer questions.`;
         }
         return {
-            systemPrompt: systemPrompt,
-            maxTurns: roleConfig?.options?.max_turns || 1
+            roleId: 'simple_query_agent',
+            systemPrompt,
+            maxTurns: roleConfig?.options?.max_turns || 1,
+            capabilities: {},
+            noTools: true,
+            model: this.model,
+            workingDirectory: srcDir ?? undefined,
         };
     }
+    getSimpleQueryAgentOptions(role = 'simple_query_agent', srcDir) {
+        return (0, claude_role_spec_1.roleSpecToClaudeOptions)(this.getSimpleQueryAgentRoleSpec(role, srcDir));
+    }
     /**
      * Get options for security code reviewer
      *
@@ -213,7 +166,7 @@ class AgentOptions {
      * @param mcpServerName - Override for the MCP server identifier
      * @param mcpServerBearer - Bearer token for MCP HTTP requests
      */
-    getCodeReviewerOptions(role = 'code_reviewer', outputFormat, mcpServerUrl, mcpServerName, mcpServerBearer) {
+    getCodeReviewerRoleSpec(role = 'code_reviewer', outputFormat, mcpServerUrl, mcpServerName, mcpServerBearer, workingDirectory) {
         const roleConfig = this.confDict[this.environment]?.[role];
         let systemPrompt = roleConfig?.options?.system_prompt ||
             'You are an Application Security (AppSec) expert assistant. You are responsible for performing a thorough code review. List out all the potential security and privacy issues found in the code.';
@@ -223,59 +176,87 @@ class AgentOptions {
         if (mcpServerUrl) {
             systemPrompt += buildPrReviewerMcpNudgeSystemPromptSuffix(mcpServerName);
         }
-        const resolvedMaxTurns = roleConfig?.options?.max_turns ?? 30;
-        const options = {
-            agents: {
-                'code-reviewer': {
-                    description: 'Reviews code for best practices and potential security issues only',
-                    prompt: systemPrompt,
-                    tools: ['Read', 'Grep', 'Write'],
-                    model: this.model,
-                    maxTurns: resolvedMaxTurns
-                }
-            },
-            permissionMode: 'bypassPermissions'
+        const spec = {
+            roleId: 'code_reviewer',
+            systemPrompt,
+            maxTurns: roleConfig?.options?.max_turns ?? 30,
+            agentName: 'code-reviewer',
+            agentDescription: 'Reviews code for best practices and potential security issues only',
+            capabilities: { read: true, grep: true, write: true },
+            permissionMode: 'bypassPermissions',
+            model: this.model,
+            workingDirectory,
         };
-        // Add JSON schema enforcement when output format is JSON
         if (outputFormat?.toLowerCase() === 'json') {
-            options.outputFormat = {
-                type: 'json_schema',
-                schema: security_report_1.SECURITY_REPORT_SCHEMA
-            };
+            spec.outputSchema = security_report_1.SECURITY_REPORT_SCHEMA;
         }
-        attachMcpServerToOptions(options, mcpServerUrl, 'code-reviewer', mcpServerName, mcpServerBearer);
-        return options;
+        (0, mcp_internal_1.attachMcpToRoleSpec)(spec, mcpServerUrl, mcpServerName, mcpServerBearer);
+        return spec;
+    }
+    getCodeReviewerOptions(role = 'code_reviewer', outputFormat, mcpServerUrl, mcpServerName, mcpServerBearer) {
+        return (0, claude_role_spec_1.roleSpecToClaudeOptions)(this.getCodeReviewerRoleSpec(role, outputFormat, mcpServerUrl, mcpServerName, mcpServerBearer));
     }
     /**
-     * Get options for threat modeler
-     * @param role - The role configuration key
-     * @param outputFormat - Output format (json, markdown, etc.)
+     * Provider-neutral spec for threat modeler (Phase 3 RoleSpec spike).
      */
-    getThreatModelerOptions(role = 'threat_modeler', outputFormat) {
+    getThreatModelerRoleSpec(role = 'threat_modeler', outputFormat, workingDirectory, maxTurnsOverride) {
         const roleConfig = this.confDict[this.environment]?.[role];
         const systemPrompt = roleConfig?.options?.system_prompt ||
             'You are an Application Security (AppSec) expert assistant. You are responsible for performing risk assessment on the source code repository for SOC2 type 2 compliance audit using the STRIDE methodology.';
         const isJson = outputFormat?.toLowerCase() === 'json';
-        const resolvedMaxTurns = roleConfig?.options?.max_turns ?? 20;
-        const options = {
-            agents: {
-                'threat-modeler': {
-                    description: 'Performs threat modeling and risk assessment using STRIDE methodology',
-                    prompt: systemPrompt,
-                    tools: isJson ? ['Read', 'Grep'] : ['Read', 'Grep', 'Write', 'Graphviz'],
-                    model: this.model,
-                    maxTurns: resolvedMaxTurns
-                }
-            },
-            permissionMode: 'bypassPermissions'
+        const resolvedMaxTurns = maxTurnsOverride ?? roleConfig?.options?.max_turns ?? 100;
+        const spec = {
+            roleId: 'threat_modeler',
+            systemPrompt,
+            maxTurns: resolvedMaxTurns,
+            agentName: 'threat-modeler',
+            agentDescription: 'Performs threat modeling and risk assessment using STRIDE methodology',
+            capabilities: isJson
+                ? { read: true, grep: true }
+                : { read: true, grep: true, write: true, graphviz: true },
+            permissionMode: 'bypassPermissions',
+            model: this.model,
+            workingDirectory,
         };
         if (isJson) {
-            options.outputFormat = {
-                type: 'json_schema',
-                schema: threat_model_report_1.THREAT_MODEL_REPORT_SCHEMA
-            };
+            spec.outputSchema = threat_model_report_1.THREAT_MODEL_REPORT_SCHEMA;
         }
-        return options;
+        return spec;
+    }
+    /**
+     * Get options for threat modeler
+     * @param role - The role configuration key
+     * @param outputFormat - Output format (json, markdown, etc.)
+     */
+    getThreatModelerOptions(role = 'threat_modeler', outputFormat, maxTurnsOverride) {
+        return (0, claude_role_spec_1.roleSpecToClaudeOptions)(this.getThreatModelerRoleSpec(role, outputFormat, undefined, maxTurnsOverride));
+    }
+    getThreatAdversaryRoleSpec(role = 'threat_adversary', srcDir, maxTurns) {
+        const roleConfig = this.confDict[this.environment]?.[role];
+        let systemPrompt = roleConfig?.options?.system_prompt ||
+            'You are a senior application security engineer performing an adversarial second pass on a STRIDE threat model. ' +
+                'Skeptically verify each threat against the real codebase using Read and Grep. ' +
+                'Keep only threats with a concrete, demonstrable attack path and confirmed source_locations. ' +
+                'Drop generic, mitigated, or ungrounded threats. Reconcile risks and metadata counts.';
+        if (srcDir) {
+            systemPrompt += `\n\nSource code is available at: ${srcDir}. Use Read and Grep to verify code paths before keeping a threat.`;
+        }
+        const spec = {
+            roleId: 'threat_adversary',
+            systemPrompt,
+            maxTurns: maxTurns ?? roleConfig?.options?.max_turns ?? 100,
+            agentName: 'threat-adversary',
+            agentDescription: 'Adversarial second pass: filters STRIDE threats by concrete code-grounded attack paths',
+            capabilities: { read: true, grep: true },
+            permissionMode: 'bypassPermissions',
+            model: this.model,
+            outputSchema: threat_model_report_1.THREAT_MODEL_REPORT_SCHEMA,
+            workingDirectory: srcDir ?? undefined,
+        };
+        return spec;
+    }
+    getThreatAdversaryOptions(role = 'threat_adversary', srcDir, maxTurns) {
+        return (0, claude_role_spec_1.roleSpecToClaudeOptions)(this.getThreatAdversaryRoleSpec(role, srcDir, maxTurns));
     }
     /**
      * Get options for PR diff-focused code reviewer
@@ -285,7 +266,7 @@ class AgentOptions {
      * @param srcDir - Optional source directory path
      * @param outputFormat - Output format (json, markdown, etc.)
      */
-    getDiffReviewerOptions(role = 'code_reviewer', srcDir, outputFormat, maxTurns, noTools, experimentEnabled, mcpServerUrl, mcpServerName, mcpServerBearer) {
+    getDiffReviewerRoleSpec(role = 'code_reviewer', srcDir, outputFormat, maxTurns, noTools, experimentEnabled, mcpServerUrl, mcpServerName, mcpServerBearer) {
         const roleConfig = this.confDict[this.environment]?.[role];
         let systemPrompt;
         if (noTools) {
@@ -341,7 +322,6 @@ You have access to Read, Grep, and Write tools:
         if (srcDir) {
             systemPrompt += `\n\nSource directory available at: ${srcDir}`;
         }
-        // Allow role config to override the system prompt
         if (roleConfig?.options?.diff_reviewer_system_prompt) {
             systemPrompt = roleConfig.options.diff_reviewer_system_prompt;
         }
@@ -356,76 +336,59 @@ You have access to Read, Grep, and Write tools:
         if (mcpServerUrl && role === 'pr_reviewer') {
             systemPrompt += buildPrReviewerMcpNudgeSystemPromptSuffix(mcpServerName);
         }
-        const resolvedMaxTurns = maxTurns
-            ?? roleConfig?.options?.max_turns
-            ?? 10;
-        const options = {
-            agents: {
-                'diff-reviewer': {
-                    description: 'Reviews PR diff changes for security vulnerabilities',
-                    prompt: systemPrompt,
-                    tools: noTools ? ['Write'] : ['Read', 'Grep', 'Write'],
-                    model: this.model,
-                    maxTurns: resolvedMaxTurns
-                }
-            },
-            permissionMode: 'bypassPermissions'
+        const spec = {
+            roleId: role === 'pr_reviewer' ? 'pr_reviewer' : 'code_reviewer',
+            systemPrompt,
+            maxTurns: maxTurns ?? roleConfig?.options?.max_turns ?? 10,
+            agentName: 'diff-reviewer',
+            agentDescription: 'Reviews PR diff changes for security vulnerabilities',
+            capabilities: noTools ? {} : { read: true, grep: true, write: true },
+            allowedTools: noTools ? ['Write'] : undefined,
+            permissionMode: 'bypassPermissions',
+            model: this.model,
+            workingDirectory: srcDir ?? undefined,
         };
-        // Add JSON schema enforcement when output format is JSON
         if (outputFormat?.toLowerCase() === 'json') {
-            options.outputFormat = {
-                type: 'json_schema',
-                schema: security_report_1.SECURITY_REPORT_SCHEMA
-            };
+            spec.outputSchema = security_report_1.SECURITY_REPORT_SCHEMA;
         }
-        attachMcpServerToOptions(options, mcpServerUrl, 'diff-reviewer', mcpServerName, mcpServerBearer);
-        return options;
+        (0, mcp_internal_1.attachMcpToRoleSpec)(spec, mcpServerUrl, mcpServerName, mcpServerBearer);
+        return spec;
     }
-    /**
-     * Get options for code fixer agent
-     * Uses structured JSON output to guarantee a well-formed fix response.
-     * Has Read and Grep tools to explore the source directory for additional context.
-     * @param role - The role configuration key
-     * @param srcDir - Optional source directory path for additional context
-     */
-    getCodeFixerOptions(role = 'code_fixer', srcDir, mcpServerUrl, mcpServerName, mcpServerBearer) {
+    getDiffReviewerOptions(role = 'code_reviewer', srcDir, outputFormat, maxTurns, noTools, experimentEnabled, mcpServerUrl, mcpServerName, mcpServerBearer) {
+        return (0, claude_role_spec_1.roleSpecToClaudeOptions)(this.getDiffReviewerRoleSpec(role, srcDir, outputFormat, maxTurns, noTools, experimentEnabled, mcpServerUrl, mcpServerName, mcpServerBearer));
+    }
+    getCodeFixerRoleSpec(role = 'code_fixer', srcDir, mcpServerUrl, mcpServerName, mcpServerBearer) {
         const roleConfig = this.confDict[this.environment]?.[role];
         let systemPrompt = roleConfig?.options?.system_prompt ||
             'You are an expert security engineer specializing in fixing vulnerabilities in code. ' +
                 'You receive a finding with code context and must produce a precise, minimal fix that resolves ' +
-                'the security issue while preserving the original code\'s functionality and indentation. ' +
+                "the security issue while preserving the original code's functionality and indentation. " +
                 'Only modify the affected lines. Always use the recommended secure alternatives when applicable.';
         if (srcDir) {
             systemPrompt += `\n\nSource directory available at: ${srcDir}. You may read files for additional context if needed.`;
         }
-        const resolvedMaxTurns = roleConfig?.options?.max_turns ?? 10;
-        const options = {
-            agents: {
-                'code-fixer': {
-                    description: 'Generates precise security fixes for code vulnerabilities',
-                    prompt: systemPrompt,
-                    tools: ['Read', 'Grep'],
-                    model: this.model,
-                    maxTurns: resolvedMaxTurns
-                }
-            },
+        const spec = {
+            roleId: 'code_fixer',
+            systemPrompt,
+            maxTurns: roleConfig?.options?.max_turns ?? 10,
+            agentName: 'code-fixer',
+            agentDescription: 'Generates precise security fixes for code vulnerabilities',
+            capabilities: { read: true, grep: true },
             permissionMode: 'bypassPermissions',
-            outputFormat: {
-                type: 'json_schema',
-                schema: security_fix_1.FIX_OUTPUT_SCHEMA
-            }
+            model: this.model,
+            outputSchema: security_fix_1.FIX_OUTPUT_SCHEMA,
+            workingDirectory: srcDir ?? undefined,
         };
-        attachMcpServerToOptions(options, mcpServerUrl, 'code-fixer', mcpServerName, mcpServerBearer);
-        return options;
+        (0, mcp_internal_1.attachMcpToRoleSpec)(spec, mcpServerUrl, mcpServerName, mcpServerBearer);
+        return spec;
     }
-    /**
-     * Get options for the QA verifier agent
-     * Uses Read, Grep, and Bash tools for test execution and analysis
-     */
-    getQaVerifierOptions(role = 'qa_verifier', srcDir) {
+    getCodeFixerOptions(role = 'code_fixer', srcDir, mcpServerUrl, mcpServerName, mcpServerBearer) {
+        return (0, claude_role_spec_1.roleSpecToClaudeOptions)(this.getCodeFixerRoleSpec(role, srcDir, mcpServerUrl, mcpServerName, mcpServerBearer));
+    }
+    getQaVerifierRoleSpec(role = 'qa_verifier', srcDir) {
         const roleConfig = this.confDict[this.environment]?.[role];
         let systemPrompt = roleConfig?.options?.system_prompt ||
-            'You are a QA verification engineer. Your task is to verify security fixes by running the project\'s test suite ' +
+            "You are a QA verification engineer. Your task is to verify security fixes by running the project's test suite " +
                 'and analyzing the results. You have access to the project source code and can execute shell commands to run tests. ' +
                 'First, set up the environment (install dependencies if needed), then run the test suite. ' +
                 'If tests fail, analyze the failures to determine if they are caused by the security fix or are pre-existing issues. ' +
@@ -433,30 +396,23 @@ You have access to Read, Grep, and Write tools:
         if (srcDir) {
             systemPrompt += `\n\nProject source code is available at: ${srcDir}. Use Read and Grep to inspect files, and Bash to execute commands.`;
         }
-        const resolvedMaxTurns = roleConfig?.options?.max_turns ?? 15;
-        const options = {
-            agents: {
-                'qa-verifier': {
-                    description: 'Verifies security fixes by running project tests and analyzing results',
-                    prompt: systemPrompt,
-                    tools: ['Read', 'Grep', 'Bash'],
-                    model: this.model,
-                    maxTurns: resolvedMaxTurns
-                }
-            },
+        return {
+            roleId: 'qa_verifier',
+            systemPrompt,
+            maxTurns: roleConfig?.options?.max_turns ?? 15,
+            agentName: 'qa-verifier',
+            agentDescription: 'Verifies security fixes by running project tests and analyzing results',
+            capabilities: { read: true, grep: true, shell: true },
             permissionMode: 'bypassPermissions',
-            outputFormat: {
-                type: 'json_schema',
-                schema: qa_context_1.QA_VERDICT_SCHEMA
-            }
+            model: this.model,
+            outputSchema: qa_context_1.QA_VERDICT_SCHEMA,
+            workingDirectory: srcDir ?? undefined,
         };
-        return options;
     }
-    /**
-     * Get options for the finding validator agent
-     * Uses Read and Grep tools (read-only) to analyze code for vulnerability presence.
-     */
-    getContextExtractorOptions(role = 'context_extractor') {
+    getQaVerifierOptions(role = 'qa_verifier', srcDir) {
+        return (0, claude_role_spec_1.roleSpecToClaudeOptions)(this.getQaVerifierRoleSpec(role, srcDir));
+    }
+    getContextExtractorRoleSpec(role = 'context_extractor') {
         const roleConfig = this.confDict[this.environment]?.[role];
         const systemPrompt = roleConfig?.options?.system_prompt ||
             'You are a security-aware software analyst. Your task is to analyze repository files and metadata ' +
@@ -470,25 +426,23 @@ You have access to Read, Grep, and Write tools:
                 '(logs, uploads, work-dir, data), IDE config (.cursor, .vscode), utility scripts, and documentation. Use ' +
                 'specific paths from the tree (e.g., "backend/scripts/**" not just "scripts/**"). Only suggest patterns NOT ' +
                 'already in the standard preset. If a field has no relevant information, return an empty string.';
-        const options = {
-            agents: {
-                'context-extractor': {
-                    description: 'Extracts structured project intelligence from repository files',
-                    prompt: systemPrompt,
-                    tools: [],
-                    model: this.model,
-                    maxTurns: 1,
-                },
-            },
+        return {
+            roleId: 'context_extractor',
+            systemPrompt,
+            maxTurns: 1,
+            agentName: 'context-extractor',
+            agentDescription: 'Extracts structured project intelligence from repository files',
+            capabilities: {},
+            allowedTools: [],
             permissionMode: 'bypassPermissions',
-            outputFormat: {
-                type: 'json_schema',
-                schema: context_extraction_1.CONTEXT_EXTRACTION_SCHEMA,
-            },
+            model: this.model,
+            outputSchema: context_extraction_1.CONTEXT_EXTRACTION_SCHEMA,
         };
-        return options;
     }
-    getFindingValidatorOptions(role = 'finding_validator', srcDir, mcpServerUrl, mcpServerName, mcpServerBearer) {
+    getContextExtractorOptions(role = 'context_extractor') {
+        return (0, claude_role_spec_1.roleSpecToClaudeOptions)(this.getContextExtractorRoleSpec(role));
+    }
+    getFindingValidatorRoleSpec(role = 'finding_validator', srcDir, mcpServerUrl, mcpServerName, mcpServerBearer) {
         const roleConfig = this.confDict[this.environment]?.[role];
         let systemPrompt = roleConfig?.options?.system_prompt ||
             'You are a security expert specializing in vulnerability validation. ' +
@@ -498,45 +452,25 @@ You have access to Read, Grep, and Write tools:
         if (srcDir) {
             systemPrompt += `\n\nSource code is available at: ${srcDir}. Use Read and Grep to inspect files for additional context if needed.`;
         }
-        const resolvedMaxTurns = roleConfig?.options?.max_turns ?? 5;
-        const options = {
-            agents: {
-                'finding-validator': {
-                    description: 'Validates whether a previously detected security vulnerability is still present in code',
-                    prompt: systemPrompt,
-                    tools: ['Read', 'Grep'],
-                    model: this.model,
-                    maxTurns: resolvedMaxTurns
-                }
-            },
+        const spec = {
+            roleId: 'finding_validator',
+            systemPrompt,
+            maxTurns: roleConfig?.options?.max_turns ?? 5,
+            agentName: 'finding-validator',
+            agentDescription: 'Validates whether a previously detected security vulnerability is still present in code',
+            capabilities: { read: true, grep: true },
             permissionMode: 'bypassPermissions',
-            outputFormat: {
-                type: 'json_schema',
-                schema: finding_validator_1.RETEST_VERDICT_SCHEMA
-            }
+            model: this.model,
+            outputSchema: finding_validator_1.RETEST_VERDICT_SCHEMA,
+            workingDirectory: srcDir ?? undefined,
         };
-        attachMcpServerToOptions(options, mcpServerUrl, 'finding-validator', mcpServerName, mcpServerBearer);
-        return options;
+        (0, mcp_internal_1.attachMcpToRoleSpec)(spec, mcpServerUrl, mcpServerName, mcpServerBearer);
+        return spec;
     }
-    /**
-     * learned_guidance_synthesizer (v2.5.0 / parent-app plan §3.8): pure-transform
-     * role that condenses bucketed dismissal/outcome/feedback signals into a short
-     * list of class-level policy bullets the pr_reviewer reads next scan.
-     *
-     * Tools: NONE — the agent must work from the provided buckets only. No
-     * source-tree access, no MCP server. The parent app's `runSynthesizerAgent`
-     * spawns this from a temp working directory anyway, so even if a tool were
-     * attached it would have nothing to read.
-     *
-     * Output schema (LEARNED_GUIDANCE_OUTPUT_SCHEMA):
-     *   { bullets: [{ cwe, bullet (≤300 chars), confidence (0..1) }] }
-     *
-     * Confidence floor and active-bullet cap are enforced by the parent app
-     * (`MIN_CONFIDENCE = 0.6`, `MAX_ACTIVE_BULLETS_PER_PROJECT = 12`); this
-     * role is allowed to return up to 50 bullets and the parent ranks +
-     * truncates.
-     */
-    getLearnedGuidanceSynthesizerOptions(role = 'learned_guidance_synthesizer') {
+    getFindingValidatorOptions(role = 'finding_validator', srcDir, mcpServerUrl, mcpServerName, mcpServerBearer) {
+        return (0, claude_role_spec_1.roleSpecToClaudeOptions)(this.getFindingValidatorRoleSpec(role, srcDir, mcpServerUrl, mcpServerName, mcpServerBearer));
+    }
+    getLearnedGuidanceSynthesizerRoleSpec(role = 'learned_guidance_synthesizer') {
         const roleConfig = this.confDict[this.environment]?.[role];
         const systemPrompt = roleConfig?.options?.system_prompt ||
             'You are a senior application security engineer summarizing patterns from past PR-scan ' +
@@ -548,30 +482,23 @@ You have access to Read, Grep, and Write tools:
                 'vague to ground a specific rule, OMIT that bucket entirely — it is better to return zero ' +
                 'bullets than a bullet the reviewer cannot act on. Output is constrained to the required ' +
                 'JSON schema; emit nothing else.';
-        const resolvedMaxTurns = roleConfig?.options?.max_turns ?? 1;
-        const options = {
-            agents: {
-                'learned-guidance-synthesizer': {
-                    description: 'Synthesizes class-level learned-guidance bullets from per-CWE dismissal-signal buckets',
-                    prompt: systemPrompt,
-                    tools: [],
-                    model: this.model,
-                    maxTurns: resolvedMaxTurns,
-                },
-            },
+        return {
+            roleId: 'learned_guidance_synthesizer',
+            systemPrompt,
+            maxTurns: roleConfig?.options?.max_turns ?? 1,
+            agentName: 'learned-guidance-synthesizer',
+            agentDescription: 'Synthesizes class-level learned-guidance bullets from per-CWE dismissal-signal buckets',
+            capabilities: {},
+            allowedTools: [],
             permissionMode: 'bypassPermissions',
-            outputFormat: {
-                type: 'json_schema',
-                schema: learned_guidance_1.LEARNED_GUIDANCE_OUTPUT_SCHEMA,
-            },
+            model: this.model,
+            outputSchema: learned_guidance_1.LEARNED_GUIDANCE_OUTPUT_SCHEMA,
         };
-        return options;
     }
-    /**
-     * pr_adversary: second pass that filters pr_reviewer findings using failure-path skepticism.
-     * Output: same SECURITY_REPORT_SCHEMA with only surviving findings.
-     */
-    getPrAdversaryOptions(role = 'pr_adversary', srcDir, maxTurns, experimentEnabled, mcpServerUrl, mcpServerName, mcpServerBearer) {
+    getLearnedGuidanceSynthesizerOptions(role = 'learned_guidance_synthesizer') {
+        return (0, claude_role_spec_1.roleSpecToClaudeOptions)(this.getLearnedGuidanceSynthesizerRoleSpec(role));
+    }
+    getPrAdversaryRoleSpec(role = 'pr_adversary', srcDir, maxTurns, experimentEnabled, mcpServerUrl, mcpServerName, mcpServerBearer) {
         const roleConfig = this.confDict[this.environment]?.[role];
         let systemPrompt = roleConfig?.options?.system_prompt ||
             'You are a senior application security engineer performing an adversarial second pass on security findings. ' +
@@ -585,42 +512,25 @@ You have access to Read, Grep, and Write tools:
             systemPrompt +=
                 '\n\n**Experiment (treatment):** Bias toward dropping borderline issues unless the diff plus quick repo checks show a real attack surface.';
         }
-        const resolvedMaxTurns = maxTurns ?? roleConfig?.options?.max_turns ?? 15;
-        const options = {
-            agents: {
-                'pr-adversary': {
-                    description: 'Adversarial second pass: filters PR scan findings by concrete failure paths',
-                    prompt: systemPrompt,
-                    tools: ['Read', 'Grep'],
-                    model: this.model,
-                    maxTurns: resolvedMaxTurns,
-                },
-            },
+        const spec = {
+            roleId: 'pr_adversary',
+            systemPrompt,
+            maxTurns: maxTurns ?? roleConfig?.options?.max_turns ?? 15,
+            agentName: 'pr-adversary',
+            agentDescription: 'Adversarial second pass: filters PR scan findings by concrete failure paths',
+            capabilities: { read: true, grep: true },
             permissionMode: 'bypassPermissions',
-            outputFormat: {
-                type: 'json_schema',
-                schema: security_report_1.SECURITY_REPORT_SCHEMA,
-            },
+            model: this.model,
+            outputSchema: security_report_1.SECURITY_REPORT_SCHEMA,
+            workingDirectory: srcDir ?? undefined,
         };
-        attachMcpServerToOptions(options, mcpServerUrl, 'pr-adversary', mcpServerName, mcpServerBearer);
-        return options;
+        (0, mcp_internal_1.attachMcpToRoleSpec)(spec, mcpServerUrl, mcpServerName, mcpServerBearer);
+        return spec;
     }
-    /**
-     * fp_adversary (v2.8.0 / parent app full-repo Phase 2.5): second pass that
-     * filters first-pass `code_reviewer` findings on full-repo scans by emitting
-     * per-finding `(fingerprint, verdict, confidence, rationale)` verdicts. Output
-     * is constrained to FP_ADVERSARY_REPORT_SCHEMA so the verdict contract stays
-     * model-independent across Claude upgrades.
-     *
-     * Differences from `getPrAdversaryOptions`:
-     * - Output schema is the dedicated `fp_adversary_report` (not
-     *   SECURITY_REPORT_SCHEMA) — verdicts round-trip on `fingerprint`, not `id`.
-     * - No `experiment_enabled` plumbing (Lane-2 deliberately omits A/B per M4).
-     * - System prompt references the four structured posture fields and
-     *   `similar_dismissed` precedent that the parent app threads in via
-     *   `--adversarial-context`.
-     */
-    getFpAdversaryOptions(role = 'fp_adversary', srcDir, maxTurns, mcpServerUrl, mcpServerName, mcpServerBearer) {
+    getPrAdversaryOptions(role = 'pr_adversary', srcDir, maxTurns, experimentEnabled, mcpServerUrl, mcpServerName, mcpServerBearer) {
+        return (0, claude_role_spec_1.roleSpecToClaudeOptions)(this.getPrAdversaryRoleSpec(role, srcDir, maxTurns, experimentEnabled, mcpServerUrl, mcpServerName, mcpServerBearer));
+    }
+    getFpAdversaryRoleSpec(role = 'fp_adversary', srcDir, maxTurns, mcpServerUrl, mcpServerName, mcpServerBearer) {
         const roleConfig = this.confDict[this.environment]?.[role];
         let systemPrompt = roleConfig?.options?.system_prompt ||
             'You are a senior application security engineer performing an adversarial false-positive review on a full-repository security scan. ' +
@@ -636,25 +546,23 @@ You have access to Read, Grep, and Write tools:
         if (mcpServerUrl) {
             systemPrompt += buildPrReviewerMcpNudgeSystemPromptSuffix(mcpServerName);
         }
-        const resolvedMaxTurns = maxTurns ?? roleConfig?.options?.max_turns ?? 15;
-        const options = {
-            agents: {
-                'fp-adversary': {
-                    description: 'Adversarial false-positive filter for full-repo scans: emits per-finding (verdict, confidence, rationale) verdicts',
-                    prompt: systemPrompt,
-                    tools: ['Read', 'Grep'],
-                    model: this.model,
-                    maxTurns: resolvedMaxTurns,
-                },
-            },
+        const spec = {
+            roleId: 'fp_adversary',
+            systemPrompt,
+            maxTurns: maxTurns ?? roleConfig?.options?.max_turns ?? 15,
+            agentName: 'fp-adversary',
+            agentDescription: 'Adversarial false-positive filter for full-repo scans: emits per-finding (verdict, confidence, rationale) verdicts',
+            capabilities: { read: true, grep: true },
             permissionMode: 'bypassPermissions',
-            outputFormat: {
-                type: 'json_schema',
-                schema: fp_adversary_pass_1.FP_ADVERSARY_REPORT_SCHEMA,
-            },
+            model: this.model,
+            outputSchema: fp_adversary_pass_1.FP_ADVERSARY_REPORT_SCHEMA,
+            workingDirectory: srcDir ?? undefined,
         };
-        attachMcpServerToOptions(options, mcpServerUrl, 'fp-adversary', mcpServerName, mcpServerBearer);
-        return options;
+        (0, mcp_internal_1.attachMcpToRoleSpec)(spec, mcpServerUrl, mcpServerName, mcpServerBearer);
+        return spec;
+    }
+    getFpAdversaryOptions(role = 'fp_adversary', srcDir, maxTurns, mcpServerUrl, mcpServerName, mcpServerBearer) {
+        return (0, claude_role_spec_1.roleSpecToClaudeOptions)(this.getFpAdversaryRoleSpec(role, srcDir, maxTurns, mcpServerUrl, mcpServerName, mcpServerBearer));
     }
 }
 exports.AgentOptions = AgentOptions;