@brutalist/mcp 0.5.1 → 0.6.1

package/dist/brutalist-server.js

@@ -6,7 +6,10 @@ import express from "express";
 import { z } from "zod";
 import { CLIAgentOrchestrator } from './cli-agents.js';
 import { logger } from './logger.js';
-import { extractPaginationParams, parseCursor, PAGINATION_DEFAULTS, createPaginationMetadata, formatPaginationStatus, estimateTokenCount } from './utils/pagination.js';
+import { BASE_ROAST_SCHEMA } from './types/tool-config.js';
+import { TOOL_CONFIGS } from './tool-definitions.js';
+import { extractPaginationParams, parseCursor, PAGINATION_DEFAULTS, ResponseChunker, createPaginationMetadata, formatPaginationStatus, estimateTokenCount } from './utils/pagination.js';
+import { ResponseCache } from './utils/response-cache.js';
 // Use environment variable or fallback to manual version
 const PACKAGE_VERSION = process.env.npm_package_version || "0.4.4";
 export class BrutalistServer {
@@ -14,59 +17,120 @@ export class BrutalistServer {
     config;
     cliOrchestrator;
     httpTransport;
+    responseCache;
+    actualPort;
+    shutdownHandler;
+    // Session tracking for security
+    activeSessions = new Map();
     constructor(config = {}) {
         this.config = {
             workingDirectory: process.cwd(),
             defaultTimeout: 1500000, // 25 minutes for thorough CLI analysis
-            enableSandbox: true,
             transport: 'stdio', // Default to stdio for backward compatibility
             httpPort: 3000,
             ...config
         };
         logger.debug("Initializing CLI Agent Orchestrator");
         this.cliOrchestrator = new CLIAgentOrchestrator();
+        // Initialize response cache with configurable TTL
+        const cacheTTLHours = parseInt(process.env.BRUTALIST_CACHE_TTL_HOURS || '2', 10);
+        this.responseCache = new ResponseCache({
+            ttlHours: cacheTTLHours,
+            maxEntries: 50,
+            maxTotalSizeMB: 500,
+            maxEntrySizeMB: 10,
+            compressionThresholdMB: 1
+        });
+        logger.info(`📦 Response cache initialized with ${cacheTTLHours} hour TTL`);
         this.server = new McpServer({
             name: "brutalist-mcp",
             version: PACKAGE_VERSION,
             capabilities: {
-                tools: {}
+                tools: {},
+                logging: {},
+                experimental: {
+                    streaming: true
+                }
             }
         });
         this.registerTools();
     }
     handleStreamingEvent = (event) => {
-        // Send streaming event via MCP server (works for both stdio and HTTP transports)
         try {
-            logger.debug(`🔄 Streaming event: ${event.type} from ${event.agent} - ${event.content?.substring(0, 100)}...`);
-            // Convert streaming event to MCP notification format
-            this.server.sendLoggingMessage({
-                level: 'info',
-                data: event,
-                logger: 'brutalist-mcp-streaming'
-            });
-            logger.debug(`✅ Sent logging message for ${event.type} event`);
+            if (!event.sessionId) {
+                logger.warn("⚠️ Streaming event without session ID - dropping for security");
+                return;
+            }
+            logger.debug(`🔄 Session-scoped streaming: ${event.type} from ${event.agent} to session ${event.sessionId.substring(0, 8)}...`);
+            // For HTTP transport: send session-specific notification
+            if (this.httpTransport) {
+                // Use MCP server's notification system with session context
+                this.server.server.notification({
+                    method: "notifications/message",
+                    params: {
+                        level: 'info',
+                        data: {
+                            type: 'streaming_event',
+                            sessionId: event.sessionId,
+                            agent: event.agent,
+                            eventType: event.type,
+                            content: event.content?.substring(0, 1000), // Truncate for safety
+                            timestamp: event.timestamp
+                        },
+                        logger: 'brutalist-mcp-streaming'
+                    }
+                });
+            }
+            // For STDIO transport: still send but with session info
+            else {
+                this.server.sendLoggingMessage({
+                    level: 'info',
+                    data: {
+                        sessionId: event.sessionId,
+                        agent: event.agent,
+                        type: event.type,
+                        content: event.content?.substring(0, 500) // More restrictive for stdio
+                    },
+                    logger: 'brutalist-mcp-streaming'
+                });
+            }
+            // Update session activity
+            if (this.activeSessions.has(event.sessionId)) {
+                this.activeSessions.get(event.sessionId).lastActivity = Date.now();
+            }
         }
         catch (error) {
-            logger.error("Failed to send streaming event", error);
+            logger.error("💥 Failed to send session-scoped streaming event", {
+                error: error instanceof Error ? error.message : String(error),
+                sessionId: event.sessionId?.substring(0, 8)
+            });
         }
     };
-    handleProgressUpdate = (progressToken, progress, total, message) => {
+    handleProgressUpdate = (progressToken, progress, total, message, sessionId) => {
         try {
-            logger.debug(`📊 Progress update: ${progress}/${total} - ${message}`);
-            // Send progress notification via MCP server
+            if (!sessionId) {
+                logger.warn("⚠️ Progress update without session ID - dropping for security");
+                return;
+            }
+            logger.debug(`📊 Session progress: ${progress}/${total} for session ${sessionId.substring(0, 8)}...`);
+            // Send progress notification with session context
             this.server.server.notification({
                 method: "notifications/progress",
                 params: {
                     progressToken,
                     progress,
                     total,
-                    message
+                    message: `[${sessionId.substring(0, 8)}] ${message}`, // Include session prefix
+                    sessionId // Include in notification data
                 }
             });
-            logger.debug(`✅ Sent progress notification: ${progress}/${total}`);
+            logger.debug(`✅ Sent session-scoped progress notification: ${progress}/${total}`);
         }
         catch (error) {
-            logger.error("Failed to send progress notification", error);
+            logger.error("💥 Failed to send progress notification", {
+                error: error instanceof Error ? error.message : String(error),
+                sessionId: sessionId?.substring(0, 8)
+            });
         }
     };
     async start() {
@@ -104,13 +168,57 @@ export class BrutalistServer {
         // Create Express app for HTTP handling
         const app = express();
         app.use(express.json({ limit: '10mb' })); // Add JSON size limit for security
-        // Enable CORS for development
+        // Secure CORS implementation
         app.use((req, res, next) => {
-            res.header('Access-Control-Allow-Origin', '*');
-            res.header('Access-Control-Allow-Methods', 'GET, POST, OPTIONS, DELETE');
-            res.header('Access-Control-Allow-Headers', 'Content-Type, Authorization, Mcp-Session-Id');
+            const origin = req.headers.origin;
+            const isProduction = process.env.NODE_ENV === 'production';
+            // Define safe default origins for development
+            const defaultDevOrigins = [
+                'http://localhost:3000',
+                'http://127.0.0.1:3000',
+                'http://localhost:8080',
+                'http://127.0.0.1:8080',
+                'http://localhost:3001',
+                'http://127.0.0.1:3001'
+            ];
+            // Get allowed origins from config or use defaults
+            const allowedOrigins = this.config.corsOrigins || defaultDevOrigins;
+            const allowWildcard = this.config.allowCORSWildcard === true && !isProduction;
+            // Determine if origin is allowed
+            let allowedOrigin = null;
+            if (allowWildcard) {
+                // Only in development with explicit opt-in
+                allowedOrigin = '*';
+                logger.warn("⚠️ Using wildcard CORS - only safe in development!");
+            }
+            else if (!origin) {
+                // No origin header (same-origin or direct server access)
+                allowedOrigin = defaultDevOrigins[0]; // Default fallback
+            }
+            else if (allowedOrigins.includes(origin)) {
+                // Explicitly allowed origin
+                allowedOrigin = origin;
+            }
+            else {
+                // Rejected origin
+                logger.warn(`🚫 CORS rejected origin: ${origin}`);
+                allowedOrigin = null;
+            }
+            // Set headers only if origin is allowed
+            if (allowedOrigin) {
+                res.header('Access-Control-Allow-Origin', allowedOrigin);
+                res.header('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+                res.header('Access-Control-Allow-Headers', 'Content-Type, Mcp-Session-Id');
+                // Removed Authorization header for security
+                res.header('Access-Control-Allow-Credentials', 'false'); // Explicit false
+            }
             if (req.method === 'OPTIONS') {
-                res.sendStatus(200);
+                if (allowedOrigin) {
+                    res.sendStatus(200);
+                }
+                else {
+                    res.sendStatus(403); // Forbidden for disallowed origins
+                }
                 return;
             }
             next();
@@ -132,310 +240,63 @@ export class BrutalistServer {
             res.json({ status: 'ok', transport: 'http-streaming', version: PACKAGE_VERSION });
         });
         // Start the HTTP server - bind to localhost only for security
-        const port = this.config.httpPort || 3000;
-        const server = app.listen(port, '127.0.0.1', () => {
-            logger.info(`HTTP server listening on port ${port}`);
-            logger.info(`MCP endpoint: http://localhost:${port}/mcp`);
-            logger.info(`Health check: http://localhost:${port}/health`);
-        });
-        // Handle graceful shutdown
-        process.on('SIGTERM', () => {
-            logger.info('Received SIGTERM, shutting down gracefully');
-            server.close(() => {
-                logger.info('HTTP server closed');
-                process.exit(0);
+        const port = this.config.httpPort ?? 3000;
+        return new Promise((resolve, reject) => {
+            const server = app.listen(port, '127.0.0.1', () => {
+                const actualPort = server.address()?.port || port;
+                this.actualPort = actualPort;
+                logger.info(`HTTP server listening on port ${actualPort}`);
+                logger.info(`MCP endpoint: http://localhost:${actualPort}/mcp`);
+                logger.info(`Health check: http://localhost:${actualPort}/health`);
+                resolve();
             });
+            server.on('error', (error) => {
+                logger.error('HTTP server failed to start', error);
+                reject(error);
+            });
+            // Handle graceful shutdown - avoid duplicate listeners
+            if (!this.shutdownHandler) {
+                this.shutdownHandler = () => {
+                    logger.info('Received SIGTERM, shutting down gracefully');
+                    server.close(() => {
+                        logger.info('HTTP server closed');
+                        process.exit(0);
+                    });
+                };
+                process.on('SIGTERM', this.shutdownHandler);
+            }
         });
     }
+    // Getter for actual listening port (useful for tests)
+    getActualPort() {
+        return this.actualPort;
+    }
+    // Cleanup method for tests - remove event listeners
+    cleanup() {
+        if (this.shutdownHandler) {
+            process.removeListener('SIGTERM', this.shutdownHandler);
+            this.shutdownHandler = undefined;
+        }
+    }
     registerTools() {
-        // ROAST_CODEBASE: Systematic destruction of entire codebase
-        this.server.tool("roast_codebase", "Deploy brutal AI critics to systematically destroy your entire codebase. These AI agents will navigate your directories, read your actual files, and find every architectural disaster, security vulnerability, and maintainability nightmare lurking in your project. They treat this like code that will kill people if it fails.", {
-            targetPath: z.string().describe("Directory path to your codebase (NOT a single file - analyze the entire project)"),
-            context: z.string().optional().describe("Additional context about the codebase purpose"),
-            workingDirectory: z.string().optional().describe("Working directory to execute from"),
-            enableSandbox: z.boolean().optional().describe("Enable sandbox mode for safe analysis (default: true)"),
-            preferredCLI: z.enum(["claude", "codex", "gemini"]).optional().describe("Preferred CLI agent to use (default: use all available CLIs)"),
-            verbose: z.boolean().optional().describe("Include detailed execution information in output (default: false)"),
-            models: z.object({
-                claude: z.string().optional().describe("Claude model: opus, sonnet, or full name like claude-opus-4-1-20250805"),
-                codex: z.string().optional().describe("Codex model: gpt-5, gpt-5-codex, o3, o3-mini, o3-pro, o4-mini"),
-                gemini: z.enum(['gemini-2.5-flash', 'gemini-2.5-pro', 'gemini-2.5-flash-lite']).optional().describe("Gemini model")
-            }).optional().describe("Specific models to use for each CLI agent (defaults: codex=gpt-5, gemini=gemini-2.5-flash)"),
-            // Pagination parameters for large responses
-            offset: z.number().min(0).optional().describe("Character offset for response pagination (default: 0)"),
-            limit: z.number().min(1000).max(100000).optional().describe("Maximum characters per response chunk (default: 25000, max: 100000)"),
-            cursor: z.string().optional().describe("Pagination cursor from previous response (alternative to offset/limit)")
-        }, async (args, extra) => {
-            try {
-                const systemPrompt = `You are a battle-scarred principal engineer who has debugged production disasters for 15 years. Find security holes, performance bottlenecks, and maintainability nightmares in this codebase. Be brutal about what's broken but specific about what would actually work. Treat this like code that will kill people if it fails.`;
-                // Extract progressToken from request metadata for real-time streaming
-                const progressToken = extra._meta?.progressToken;
-                // Extract pagination parameters
-                const paginationParams = extractPaginationParams(args);
-                if (args.cursor) {
-                    const cursorParams = parseCursor(args.cursor);
-                    Object.assign(paginationParams, cursorParams);
-                }
-                const result = await this.executeBrutalistAnalysis("codebase", args.targetPath, systemPrompt, args.context, args.workingDirectory, args.enableSandbox, args.preferredCLI, args.verbose, args.models, progressToken);
-                return this.formatToolResponse(result, args.verbose, paginationParams);
-            }
-            catch (error) {
-                return this.formatErrorResponse(error);
-            }
-        });
-        // ROAST_FILE_STRUCTURE: Directory hierarchy demolition
-        this.server.tool("roast_file_structure", "Deploy brutal AI critics to systematically destroy your file organization. These agents will navigate your actual directory structure and expose every organizational disaster, naming convention failure, and structural nightmare that makes your codebase unmaintainable.", {
-            targetPath: z.string().describe("Directory path to analyze"),
-            depth: z.number().optional().describe("Maximum directory depth to analyze (default: 3)"),
-            context: z.string().optional().describe("Additional context about the project structure"),
-            workingDirectory: z.string().optional().describe("Working directory to execute from"),
-            preferredCLI: z.enum(["claude", "codex", "gemini"]).optional().describe("Preferred CLI agent to use (default: use all available CLIs)"),
-            models: z.object({
-                claude: z.string().optional().describe("Claude model: opus, sonnet, or full name like claude-opus-4-1-20250805"),
-                codex: z.string().optional().describe("Codex model: gpt-5, gpt-5-codex, o3, o3-mini, o3-pro, o4-mini"),
-                gemini: z.enum(['gemini-2.5-flash', 'gemini-2.5-pro', 'gemini-2.5-flash-lite']).optional().describe("Gemini model")
-            }).optional().describe("Specific models to use for each CLI agent")
-        }, async (args) => {
-            try {
-                const systemPrompt = `You are a brutal file organization critic. Your job is to systematically destroy the given directory structure by finding every organizational disaster, naming convention failure, and structural nightmare that makes codebases unmaintainable. Examine folder hierarchies, file naming patterns, separation of concerns, and overall project organization. Be ruthlessly honest about how poor organization will slow development and confuse developers. But after cataloguing this organizational hellscape, sketch out what sanity would actually look like.`;
-                const result = await this.executeBrutalistAnalysis("fileStructure", args.targetPath, systemPrompt, `Project structure analysis (depth: ${args.depth || 3}). ${args.context || ''}`, args.workingDirectory, undefined, // enableSandbox
-                args.preferredCLI, undefined, // verbose
-                args.models);
-                return this.formatToolResponse(result);
-            }
-            catch (error) {
-                return this.formatErrorResponse(error);
-            }
-        });
-        // ROAST_DEPENDENCIES: Package management demolition
-        this.server.tool("roast_dependencies", "Deploy brutal AI critics to systematically destroy your dependency management. These agents will read your actual package files, analyze version conflicts, and expose every security vulnerability and compatibility nightmare in your dependency tree.", {
-            targetPath: z.string().describe("Path to package file (package.json, requirements.txt, Cargo.toml, etc.)"),
-            includeDevDeps: z.boolean().optional().describe("Include development dependencies in analysis (default: true)"),
-            context: z.string().optional().describe("Additional context about the project dependencies"),
-            workingDirectory: z.string().optional().describe("Working directory to execute from"),
-            preferredCLI: z.enum(["claude", "codex", "gemini"]).optional().describe("Preferred CLI agent to use (default: use all available CLIs)"),
-            models: z.object({
-                claude: z.string().optional().describe("Claude model: opus, sonnet, or full name like claude-opus-4-1-20250805"),
-                codex: z.string().optional().describe("Codex model: gpt-5, gpt-5-codex, o3, o3-mini, o3-pro, o4-mini"),
-                gemini: z.enum(['gemini-2.5-flash', 'gemini-2.5-pro', 'gemini-2.5-flash-lite']).optional().describe("Gemini model")
-            }).optional().describe("Specific models to use for each CLI agent")
-        }, async (args) => {
-            try {
-                const systemPrompt = `You are a brutal dependency management critic. Your job is to systematically destroy the given dependency configuration by finding every security vulnerability, version conflict, compatibility nightmare, and bloat that will cause production failures. Examine package versions, security issues, licensing problems, and dependency tree complexity. Be ruthlessly honest about how poor dependency management will cause security breaches and deployment failures. After exposing this dependency dumpster fire, grudgingly admit what competent dependency management would require.`;
-                const result = await this.executeBrutalistAnalysis("dependencies", args.targetPath, systemPrompt, `Dependency analysis (dev deps: ${args.includeDevDeps ?? true}). ${args.context || ''}`, args.workingDirectory, undefined, // enableSandbox
-                args.preferredCLI, undefined, // verbose
-                args.models);
-                return this.formatToolResponse(result);
-            }
-            catch (error) {
-                return this.formatErrorResponse(error);
-            }
-        });
-        // ROAST_GIT_HISTORY: Version control demolition
-        this.server.tool("roast_git_history", "Deploy brutal AI critics to systematically destroy your git history and development practices. These agents will analyze your actual commit history, branching strategy, and code evolution to expose every workflow disaster and collaboration nightmare.", {
-            targetPath: z.string().describe("Git repository path to analyze"),
-            commitRange: z.string().optional().describe("Commit range to analyze (e.g., 'HEAD~10..HEAD', default: last 20 commits)"),
-            context: z.string().optional().describe("Additional context about the development workflow"),
-            workingDirectory: z.string().optional().describe("Working directory to execute from"),
-            preferredCLI: z.enum(["claude", "codex", "gemini"]).optional().describe("Preferred CLI agent to use (default: use all available CLIs)"),
-            models: z.object({
-                claude: z.string().optional().describe("Claude model: opus, sonnet, or full name like claude-opus-4-1-20250805"),
-                codex: z.string().optional().describe("Codex model: gpt-5, gpt-5-codex, o3, o3-mini, o3-pro, o4-mini"),
-                gemini: z.enum(['gemini-2.5-flash', 'gemini-2.5-pro', 'gemini-2.5-flash-lite']).optional().describe("Gemini model")
-            }).optional().describe("Specific models to use for each CLI agent")
-        }, async (args) => {
-            try {
-                const systemPrompt = `You are a brutal git workflow critic. Your job is to systematically destroy the given git history and development practices by finding every workflow disaster, commit quality issue, and collaboration nightmare. Examine commit messages, branching strategies, merge patterns, and code evolution. Be ruthlessly honest about how poor git practices will cause deployment issues, collaboration failures, and development chaos. When you're done cataloguing this version control wasteland, reluctantly outline what professional git hygiene actually demands.`;
-                const result = await this.executeBrutalistAnalysis("gitHistory", args.targetPath, systemPrompt, `Git history analysis (range: ${args.commitRange || 'last 20 commits'}). ${args.context || ''}`, args.workingDirectory, undefined, // enableSandbox
-                args.preferredCLI, undefined, // verbose
-                args.models);
-                return this.formatToolResponse(result);
-            }
-            catch (error) {
-                return this.formatErrorResponse(error);
-            }
-        });
-        // ROAST_TEST_COVERAGE: Testing infrastructure demolition
-        this.server.tool("roast_test_coverage", "Deploy brutal AI critics to systematically destroy your testing strategy. These agents will analyze your actual test files, run coverage reports, and expose every testing gap and quality assurance nightmare that will let bugs slip into production.", {
-            targetPath: z.string().describe("Path to test directory or test configuration file"),
-            runCoverage: z.boolean().optional().describe("Attempt to run coverage analysis (default: true)"),
-            context: z.string().optional().describe("Additional context about the testing strategy"),
-            workingDirectory: z.string().optional().describe("Working directory to execute from"),
-            preferredCLI: z.enum(["claude", "codex", "gemini"]).optional().describe("Preferred CLI agent to use (default: use all available CLIs)"),
-            models: z.object({
-                claude: z.string().optional().describe("Claude model: opus, sonnet, or full name like claude-opus-4-1-20250805"),
-                codex: z.string().optional().describe("Codex model: gpt-5, gpt-5-codex, o3, o3-mini, o3-pro, o4-mini"),
-                gemini: z.enum(['gemini-2.5-flash', 'gemini-2.5-pro', 'gemini-2.5-flash-lite']).optional().describe("Gemini model")
-            }).optional().describe("Specific models to use for each CLI agent")
-        }, async (args) => {
-            try {
-                const systemPrompt = `You are a brutal testing strategy critic. Your job is to systematically destroy the given testing approach by finding every testing gap, quality assurance nightmare, and coverage disaster that will let bugs slip into production. Examine test coverage, test quality, testing patterns, and CI/CD integration. Be ruthlessly honest about how poor testing will cause production failures and user-facing bugs. After dissecting this quality assurance horror show, begrudgingly spell out what it takes to actually catch bugs before users do.`;
-                const result = await this.executeBrutalistAnalysis("testCoverage", args.targetPath, systemPrompt, `Test coverage analysis (run coverage: ${args.runCoverage ?? true}). ${args.context || ''}`, args.workingDirectory, undefined, // enableSandbox
-                args.preferredCLI, undefined, // verbose
-                args.models);
-                return this.formatToolResponse(result);
-            }
-            catch (error) {
-                return this.formatErrorResponse(error);
-            }
-        });
-        // ROAST_IDEA: Any idea destruction
-        this.server.tool("roast_idea", "Deploy brutal AI critics to systematically destroy ANY idea - business, technical, creative, or otherwise. These critics understand the gap between imagination and reality, finding where your concept will encounter the immovable forces of the world. They are harsh about delusions but wise about what might actually survive.", {
-            idea: z.string().describe("ANY idea to analyze and demolish - business, technical, creative, or otherwise"),
-            context: z.string().optional().describe("Additional context about goals, constraints, or background"),
-            timeline: z.string().optional().describe("Expected timeline or deadline"),
-            resources: z.string().optional().describe("Available resources (budget, team, time, skills)"),
-            preferredCLI: z.enum(["claude", "codex", "gemini"]).optional().describe("Preferred CLI agent to use (default: use all available CLIs)"),
-            models: z.object({
-                claude: z.string().optional().describe("Claude model: opus, sonnet, or full name like claude-opus-4-1-20250805"),
-                codex: z.string().optional().describe("Codex model: gpt-5, gpt-5-codex, o3, o3-mini, o3-pro, o4-mini"),
-                gemini: z.enum(['gemini-2.5-flash', 'gemini-2.5-pro', 'gemini-2.5-flash-lite']).optional().describe("Gemini model")
-            }).optional().describe("Specific models to use for each CLI agent")
-        }, async (args) => {
-            try {
-                const systemPrompt = `You are a brutal idea critic who understands the gap between imagination and reality. Your job is to systematically destroy the given idea by finding where it will encounter the immovable forces of the real world. Be ruthlessly honest about why most ideas fail when they meet practical constraints, human nature, physics, logic, or simple implementation reality. After demolishing the delusions, concede what salvage operations might actually work.`;
-                const result = await this.executeBrutalistAnalysis("idea", args.idea, systemPrompt, `Context: ${args.context || 'none'}, Timeline: ${args.timeline || 'unspecified'}, Resources: ${args.resources || 'unknown'}`, undefined, // workingDirectory
-                undefined, // enableSandbox
-                args.preferredCLI, undefined, // verbose
-                args.models);
-                return this.formatToolResponse(result);
-            }
-            catch (error) {
-                return this.formatErrorResponse(error);
-            }
-        });
-        // ROAST_ARCHITECTURE: System design demolition
-        this.server.tool("roast_architecture", "Deploy brutal AI critics to systematically destroy your system architecture. These critics have watched elegant designs collapse under real load, identifying every bottleneck, cost explosion, and scaling failure that will destroy your system. They are ruthless about why this won't survive production.", {
-            architecture: z.string().describe("Architecture description, diagram, or design document"),
-            scale: z.string().optional().describe("Expected scale/load (users, requests, data)"),
-            constraints: z.string().optional().describe("Budget, timeline, or technical constraints"),
-            deployment: z.string().optional().describe("Deployment environment and strategy"),
-            preferredCLI: z.enum(["claude", "codex", "gemini"]).optional().describe("Preferred CLI agent to use (default: use all available CLIs)"),
-            models: z.object({
-                claude: z.string().optional().describe("Claude model: opus, sonnet, or full name like claude-opus-4-1-20250805"),
-                codex: z.string().optional().describe("Codex model: gpt-5, gpt-5-codex, o3, o3-mini, o3-pro, o4-mini"),
-                gemini: z.enum(['gemini-2.5-flash', 'gemini-2.5-pro', 'gemini-2.5-flash-lite']).optional().describe("Gemini model")
-            }).optional().describe("Specific models to use for each CLI agent")
-        }, async (args) => {
-            try {
-                const systemPrompt = `You are a brutal system architecture critic who has watched elegant designs collapse under real load. Your job is to systematically destroy the given architecture by finding every bottleneck, cost explosion, and scaling failure that will destroy the system in production. Examine scalability, reliability, cost, complexity, and operational challenges. Be ruthlessly honest about why this architecture won't survive production load. After crushing these architectural fantasies, reluctantly sketch what would actually scale without bankrupting the company.`;
-                const result = await this.executeBrutalistAnalysis("architecture", args.architecture, systemPrompt, `Scale: ${args.scale || 'unknown'}, Constraints: ${args.constraints || 'none specified'}, Deployment: ${args.deployment || 'unclear'}`, undefined, // workingDirectory
-                undefined, // enableSandbox
-                args.preferredCLI, undefined, // verbose
-                args.models);
-                return this.formatToolResponse(result);
-            }
-            catch (error) {
-                return this.formatErrorResponse(error);
-            }
-        });
-        // ROAST_RESEARCH: Academic project demolition  
-        this.server.tool("roast_research", "Deploy brutal AI critics to systematically demolish your research methodology. These critics are supremely jaded peer reviewers who have rejected thousands of papers and watched countless studies fail to replicate. They find every statistical flaw, sampling bias, and reproducibility nightmare.", {
-            research: z.string().describe("Research description, methodology, or paper draft"),
-            field: z.string().optional().describe("Research field (ML, systems, theory, etc.)"),
-            claims: z.string().optional().describe("Main claims or contributions"),
-            data: z.string().optional().describe("Data sources, datasets, or experimental setup"),
-            preferredCLI: z.enum(["claude", "codex", "gemini"]).optional().describe("Preferred CLI agent to use (default: use all available CLIs)"),
-            models: z.object({
-                claude: z.string().optional().describe("Claude model: opus, sonnet, or full name like claude-opus-4-1-20250805"),
-                codex: z.string().optional().describe("Codex model: gpt-5, gpt-5-codex, o3, o3-mini, o3-pro, o4-mini"),
-                gemini: z.enum(['gemini-2.5-flash', 'gemini-2.5-pro', 'gemini-2.5-flash-lite']).optional().describe("Gemini model")
-            }).optional().describe("Specific models to use for each CLI agent")
-        }, async (args) => {
-            try {
-                const systemPrompt = `You are a brutal research methodology critic - a supremely jaded peer reviewer who has rejected thousands of papers and watched countless studies fail to replicate. Your job is to systematically demolish the given research by finding every statistical flaw, sampling bias, reproducibility nightmare, and methodological disaster. Be ruthlessly honest about research quality, experimental design, and scientific rigor. After eviscerating this methodological train wreck, grudgingly admit what real science would demand.`;
-                const result = await this.executeBrutalistAnalysis("research", args.research, systemPrompt, `Field: ${args.field || 'unspecified'}, Claims: ${args.claims || 'unclear'}, Data: ${args.data || 'not provided'}`, undefined, // workingDirectory
-                undefined, // enableSandbox
-                args.preferredCLI, undefined, // verbose
-                args.models);
-                return this.formatToolResponse(result);
-            }
-            catch (error) {
-                return this.formatErrorResponse(error);
-            }
-        });
-        // ROAST_SECURITY: Security-focused attack vector analysis
-        this.server.tool("roast_security", "Deploy brutal AI critics to systematically annihilate your security design. These critics are battle-hardened penetration testers who find every authentication bypass, injection vulnerability, privilege escalation path, and social engineering opportunity that real attackers will exploit.", {
-            system: z.string().describe("System, application, or security design to analyze"),
-            assets: z.string().optional().describe("Critical assets or data to protect"),
-            threatModel: z.string().optional().describe("Known threats or attack vectors to consider"),
-            compliance: z.string().optional().describe("Compliance requirements (GDPR, HIPAA, etc.)"),
-            preferredCLI: z.enum(["claude", "codex", "gemini"]).optional().describe("Preferred CLI agent to use (default: use all available CLIs)"),
-            models: z.object({
-                claude: z.string().optional().describe("Claude model: opus, sonnet, or full name like claude-opus-4-1-20250805"),
-                codex: z.string().optional().describe("Codex model: gpt-5, gpt-5-codex, o3, o3-mini, o3-pro, o4-mini"),
-                gemini: z.enum(['gemini-2.5-flash', 'gemini-2.5-pro', 'gemini-2.5-flash-lite']).optional().describe("Gemini model")
-            }).optional().describe("Specific models to use for each CLI agent")
-        }, async (args) => {
-            try {
-                const systemPrompt = `You are a brutal security critic - a battle-hardened penetration tester who finds every authentication bypass, injection vulnerability, privilege escalation path, and social engineering opportunity that real attackers will exploit. Your job is to systematically annihilate the given security design by finding every weakness that will lead to data breaches, system compromises, and security incidents. Be ruthlessly honest about security flaws and attack vectors. After obliterating these security delusions, begrudgingly outline what actual defense looks like.`;
-                const result = await this.executeBrutalistAnalysis("security", args.system, systemPrompt, `Assets: ${args.assets || 'unspecified'}, Threats: ${args.threatModel || 'unknown'}, Compliance: ${args.compliance || 'none specified'}`, undefined, // workingDirectory
-                undefined, // enableSandbox
-                args.preferredCLI, undefined, // verbose
-                args.models);
-                return this.formatToolResponse(result);
-            }
-            catch (error) {
-                return this.formatErrorResponse(error);
-            }
-        });
-        // ROAST_PRODUCT: UX and market reality criticism
-        this.server.tool("roast_product", "Deploy brutal AI critics to systematically eviscerate your product concept. These critics are product veterans who understand why users really abandon things, finding every usability disaster, adoption barrier, and workflow failure that will drive users away in seconds.", {
-            product: z.string().describe("Product description, features, or user experience to analyze"),
-            users: z.string().optional().describe("Target users or user personas"),
-            competition: z.string().optional().describe("Competitive landscape or alternatives"),
-            metrics: z.string().optional().describe("Success metrics or KPIs"),
-            preferredCLI: z.enum(["claude", "codex", "gemini"]).optional().describe("Preferred CLI agent to use (default: use all available CLIs)"),
-            models: z.object({
-                claude: z.string().optional().describe("Claude model: opus, sonnet, or full name like claude-opus-4-1-20250805"),
-                codex: z.string().optional().describe("Codex model: gpt-5, gpt-5-codex, o3, o3-mini, o3-pro, o4-mini"),
-                gemini: z.enum(['gemini-2.5-flash', 'gemini-2.5-pro', 'gemini-2.5-flash-lite']).optional().describe("Gemini model")
-            }).optional().describe("Specific models to use for each CLI agent")
-        }, async (args) => {
-            try {
-                const systemPrompt = `You are a brutal product critic - a product veteran who understands why users really abandon things. Your job is to systematically eviscerate the given product concept by finding every usability disaster, adoption barrier, and workflow failure that will drive users away in seconds. Examine user experience, market fit, competitive positioning, and business model viability. Be ruthlessly honest about why most products fail to gain adoption. After torching this product disaster, reluctantly suggest what might actually get users to stick around.`;
-                const result = await this.executeBrutalistAnalysis("product", args.product, systemPrompt, `Users: ${args.users || 'unclear'}, Competition: ${args.competition || 'unknown'}, Metrics: ${args.metrics || 'undefined'}`, undefined, // workingDirectory
-                undefined, // enableSandbox
-                args.preferredCLI, undefined, // verbose
-                args.models);
-                return this.formatToolResponse(result);
-            }
-            catch (error) {
-                return this.formatErrorResponse(error);
-            }
-        });
-        // ROAST_INFRASTRUCTURE: DevOps and operations demolition
-        this.server.tool("roast_infrastructure", "Deploy brutal AI critics to systematically obliterate your infrastructure design. These critics are grizzled site reliability engineers who find every single point of failure, scaling bottleneck, and operational nightmare that will cause outages when you least expect them.", {
-            infrastructure: z.string().describe("Infrastructure setup, deployment strategy, or operations plan"),
-            scale: z.string().optional().describe("Expected scale and load patterns"),
-            budget: z.string().optional().describe("Infrastructure budget or cost constraints"),
-            sla: z.string().optional().describe("SLA requirements or uptime targets"),
-            preferredCLI: z.enum(["claude", "codex", "gemini"]).optional().describe("Preferred CLI agent to use (default: use all available CLIs)"),
-            models: z.object({
-                claude: z.string().optional().describe("Claude model: opus, sonnet, or full name like claude-opus-4-1-20250805"),
-                codex: z.string().optional().describe("Codex model: gpt-5, gpt-5-codex, o3, o3-mini, o3-pro, o4-mini"),
-                gemini: z.enum(['gemini-2.5-flash', 'gemini-2.5-pro', 'gemini-2.5-flash-lite']).optional().describe("Gemini model")
-            }).optional().describe("Specific models to use for each CLI agent")
-        }, async (args) => {
-            try {
-                const systemPrompt = `You are a brutal infrastructure critic - a grizzled site reliability engineer who finds every single point of failure, scaling bottleneck, and operational nightmare that will cause outages when you least expect them. Your job is to systematically obliterate the given infrastructure design by finding every weakness that will lead to downtime, cost overruns, and operational disasters. Be ruthlessly honest about infrastructure fragility and operational complexity. After demolishing this infrastructure fever dream, grudgingly map out what actually stays up at 3 AM.`;
-                const result = await this.executeBrutalistAnalysis("infrastructure", args.infrastructure, systemPrompt, `Scale: ${args.scale || 'unknown'}, Budget: ${args.budget || 'unlimited?'}, SLA: ${args.sla || 'undefined'}`, undefined, // workingDirectory
-                undefined, // enableSandbox
-                args.preferredCLI, undefined, // verbose
-                args.models);
-                return this.formatToolResponse(result);
-            }
-            catch (error) {
-                return this.formatErrorResponse(error);
-            }
+        // Register all roast tools using unified handler - DRY principle
+        TOOL_CONFIGS.forEach(config => {
+            const schema = {
+                ...config.schemaExtensions,
+                ...BASE_ROAST_SCHEMA
+            };
+            this.server.tool(config.name, config.description, schema, async (args, extra) => this.handleRoastTool(config, args, extra));
         });
+        // Register special tools that don't follow the pattern
+        this.registerSpecialTools();
+    }
+    registerSpecialTools() {
         // ROAST_CLI_DEBATE: Adversarial analysis between different CLI agents
         this.server.tool("roast_cli_debate", "Deploy CLI agents in structured adversarial debate. Agents take opposing positions and systematically challenge each other's reasoning. Perfect for exploring complex topics from multiple perspectives and stress-testing ideas through rigorous intellectual discourse.", {
             targetPath: z.string().describe("Topic, question, or concept to debate (NOT a file path - use natural language)"),
             debateRounds: z.number().optional().describe("Number of debate rounds (default: 2, max: 10)"),
             context: z.string().optional().describe("Additional context for the debate"),
             workingDirectory: z.string().optional().describe("Working directory for analysis"),
-            enableSandbox: z.boolean().optional().describe("Enable sandbox mode for security"),
             models: z.object({
                 claude: z.string().optional().describe("Claude model: opus, sonnet, or full name like claude-opus-4-1-20250805"),
                 codex: z.string().optional().describe("Codex model: gpt-5, gpt-5-codex, o3, o3-mini, o3-pro, o4-mini"),
@@ -444,7 +305,7 @@ export class BrutalistServer {
         }, async (args) => {
             return this.handleToolExecution(async () => {
                 const debateRounds = Math.min(args.debateRounds || 2, 10); // Limit to max 10 rounds to prevent DoS
-                const responses = await this.executeCLIDebate(args.targetPath, debateRounds, args.context, args.workingDirectory, args.enableSandbox, args.models);
+                const responses = await this.executeCLIDebate(args.targetPath, debateRounds, args.context, args.workingDirectory, args.models);
                 return responses;
             });
         });
@@ -471,7 +332,7 @@ export class BrutalistServer {
                 roster += "- `cli_agent_roster` - This tool (show capabilities)\n\n";
                 roster += "## CLI Agent Capabilities\n";
                 roster += "**Claude Code** - Advanced analysis with direct system prompt injection\n";
-                roster += "**Codex** - Sandboxed execution with embedded brutal prompts\n";
+                roster += "**Codex** - Secure execution with embedded brutal prompts\n";
                 roster += "**Gemini CLI** - Workspace context with environment variable system prompts\n\n";
                 // Add CLI context information
                 const cliContext = await this.cliOrchestrator.detectCLIContext();
@@ -479,6 +340,12 @@ export class BrutalistServer {
                 roster += `**Available CLIs:** ${cliContext.availableCLIs.join(', ') || 'None detected'}\n`;
                 roster += `**Current CLI:** ${cliContext.currentCLI || 'Unknown'}\n`;
                 roster += `**Smart Routing:** ${cliContext.currentCLI ? `Excludes ${cliContext.currentCLI} for analysis` : 'Uses all available CLIs'}\n\n`;
+                roster += "## Pagination Support (NEW in v0.5.2)\n";
+                roster += "**All tools now support intelligent pagination:**\n";
+                roster += "- Analysis results are cached with 2-hour TTL\n";
+                roster += "- Use `analysis_id` from response to paginate without re-running\n";
+                roster += "- Smart text chunking preserves readability\n";
+                roster += "- Example: `roast_codebase(analysis_id: 'a3f5c2d8', offset: 25000)`\n\n";
                 roster += "## Brutalist Philosophy\n";
                 roster += "*All tools use CLI agents with brutal system prompts for maximum reality-based criticism.*\n";
                 return {
@@ -490,12 +357,132 @@ export class BrutalistServer {
             }
         });
     }
-    async executeCLIDebate(targetPath, debateRounds, context, workingDirectory, enableSandbox, models) {
+    /**
+     * Unified handler for all roast tools - DRY principle
+     */
+    async handleRoastTool(config, args, extra) {
+        try {
+            const progressToken = extra._meta?.progressToken;
+            // Extract session context for security
+            const sessionId = extra?.sessionId ||
+                extra?._meta?.sessionId ||
+                extra?.headers?.['mcp-session-id'] ||
+                `anonymous-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+            const requestId = `${sessionId}-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+            logger.debug(`🔐 Processing request with session: ${sessionId.substring(0, 8)}..., request: ${requestId.substring(0, 12)}...`);
+            // Track session activity
+            if (!this.activeSessions.has(sessionId)) {
+                this.activeSessions.set(sessionId, {
+                    startTime: Date.now(),
+                    requestCount: 0,
+                    lastActivity: Date.now()
+                });
+            }
+            const sessionInfo = this.activeSessions.get(sessionId);
+            sessionInfo.requestCount++;
+            sessionInfo.lastActivity = Date.now();
+            // Debug logging: Log the received arguments to file
+            const fs = require('fs');
+            const debugLog = `/tmp/brutalist-tool-debug-${Date.now()}.log`;
+            const logMessage = (msg) => {
+                try {
+                    fs.appendFileSync(debugLog, `${new Date().toISOString()}: ${msg}\n`);
+                }
+                catch (e) {
+                    // Ignore filesystem errors
+                }
+            };
+            logMessage(`🔧 ROAST TOOL DEBUG: Tool=${config.name}, primaryArgField=${config.primaryArgField}`);
+            logMessage(`🔧 ROAST TOOL DEBUG: args=${JSON.stringify(args, null, 2)}`);
+            logMessage(`🔧 ROAST TOOL DEBUG: extra=${JSON.stringify(extra, null, 2)}`);
+            // Extract pagination parameters
+            const paginationParams = extractPaginationParams(args);
+            if (args.cursor) {
+                const cursorParams = parseCursor(args.cursor);
+                Object.assign(paginationParams, cursorParams);
+            }
+            // Check cache if analysis_id provided
+            if (args.analysis_id && !args.force_refresh) {
+                const cachedContent = await this.responseCache.get(args.analysis_id, sessionId);
+                if (cachedContent) {
+                    logger.info(`🎯 Session-validated cache hit for analysis_id: ${args.analysis_id}`);
+                    const cachedResult = {
+                        success: true,
+                        responses: [{
+                                agent: 'cached',
+                                success: true,
+                                output: cachedContent,
+                                executionTime: 0
+                            }]
+                    };
+                    return this.formatToolResponse(cachedResult, args.verbose, paginationParams, args.analysis_id);
+                }
+                else {
+                    logger.info(`🔍 No valid cache entry for analysis_id: ${args.analysis_id} and session: ${sessionId?.substring(0, 8)}`);
+                }
+            }
+            // Generate cache key for this request
+            const cacheKey = this.responseCache.generateCacheKey(config.cacheKeyFields.reduce((acc, field) => {
+                acc.tool = config.name;
+                if (args[field] !== undefined)
+                    acc[field] = args[field];
+                return acc;
+            }, {}));
+            // Check if we have a cached result (unless forcing refresh)
+            if (!args.force_refresh) {
+                const cachedContent = await this.responseCache.get(cacheKey, sessionId);
+                if (cachedContent) {
+                    const analysisId = this.responseCache.generateAnalysisId(cacheKey);
+                    logger.info(`🎯 Cache hit for new request, using analysis_id: ${analysisId}`);
+                    const cachedResult = {
+                        success: true,
+                        responses: [{
+                                agent: 'cached',
+                                success: true,
+                                output: cachedContent,
+                                executionTime: 0
+                            }]
+                    };
+                    return this.formatToolResponse(cachedResult, args.verbose, paginationParams, analysisId);
+                }
+            }
+            // Build context with custom builder if available
+            const context = config.contextBuilder ? config.contextBuilder(args) : args.context;
+            // Get the primary argument (targetPath, idea, architecture, etc.)
+            const primaryArg = args[config.primaryArgField];
+            logMessage(`🔧 PRIMARY ARG DEBUG: primaryArgField=${config.primaryArgField}, primaryArg="${primaryArg}"`);
+            logMessage(`🔧 PRIMARY ARG DEBUG: config.analysisType="${config.analysisType}"`);
+            // Run the analysis
+            const result = await this.executeBrutalistAnalysis(config.analysisType, primaryArg, config.systemPrompt, context, args.workingDirectory, args.preferredCLI, args.verbose, args.models, progressToken, sessionId, requestId);
+            // Cache the result if successful
+            let analysisId;
+            if (result.success && result.responses.length > 0) {
+                const fullContent = this.extractFullContent(result);
+                if (fullContent) {
+                    const cacheData = config.cacheKeyFields.reduce((acc, field) => {
+                        acc.tool = config.name;
+                        if (args[field] !== undefined)
+                            acc[field] = args[field];
+                        return acc;
+                    }, {});
+                    const { analysisId: newId } = await this.responseCache.set(cacheData, fullContent, cacheKey, sessionId, // NEW: Bind to session
+                    requestId // NEW: Track request
+                    );
+                    analysisId = newId;
+                    logger.info(`✅ Cached analysis result with ID: ${analysisId} for session: ${sessionId?.substring(0, 8)}`);
+                }
+            }
+            return this.formatToolResponse(result, args.verbose, paginationParams, analysisId);
+        }
+        catch (error) {
+            return this.formatErrorResponse(error);
+        }
+    }
+    async executeCLIDebate(targetPath, debateRounds, context, workingDirectory, models) {
         logger.debug("Executing CLI debate", {
             targetPath,
             debateRounds,
             workingDirectory,
-            enableSandbox
         });
         try {
             // Get CLI context
@@ -539,13 +526,14 @@ Remember: You are ${agent.toUpperCase()}, the passionate champion of ${position.
                 logger.info(`🎭 ${agent.toUpperCase()} preparing initial position: ${position.split(':')[0]}`);
                 const response = await this.cliOrchestrator.executeSingleCLI(agent, assignedPrompt, assignedPrompt, {
                     workingDirectory: workingDirectory || this.config.workingDirectory,
-                    sandbox: enableSandbox ?? this.config.enableSandbox,
                     timeout: (this.config.defaultTimeout || 60000) * 2,
                     models: models ? { [agent]: models[agent] } : undefined
                 });
                 if (response.success) {
                     debateContext.push(response);
-                    fullDebateTranscript.get(agent)?.push(response.output);
+                    if (response.output) {
+                        fullDebateTranscript.get(agent)?.push(response.output);
+                    }
                 }
             }
             // Subsequent rounds: Turn-based responses attacking specific arguments
@@ -587,13 +575,14 @@ Remember: You are ${currentAgent.toUpperCase()}, passionate advocate for ${assig
                     logger.info(`🔥 Round ${round}: ${currentAgent.toUpperCase()} responding to opponents (${assignedPosition.split(':')[0]})`);
                     const response = await this.cliOrchestrator.executeSingleCLI(currentAgent, confrontationalPrompt, confrontationalPrompt, {
                         workingDirectory: workingDirectory || this.config.workingDirectory,
-                        sandbox: enableSandbox ?? this.config.enableSandbox,
                         timeout: (this.config.defaultTimeout || 60000) * 2,
                         models: models ? { [currentAgent]: models[currentAgent] } : undefined
                     });
                     if (response.success) {
                         debateContext.push(response);
-                        fullDebateTranscript.get(currentAgent)?.push(response.output);
+                        if (response.output) {
+                            fullDebateTranscript.get(currentAgent)?.push(response.output);
+                        }
                     }
                 }
             }
@@ -636,7 +625,9 @@ Remember: You are ${currentAgent.toUpperCase()}, passionate advocate for ${assig
             if (!agentOutputs.has(response.agent)) {
                 agentOutputs.set(response.agent, []);
             }
-            agentOutputs.get(response.agent)?.push(response.output);
+            if (response.output) {
+                agentOutputs.get(response.agent)?.push(response.output);
+            }
         });
         synthesis += `## Key Points of Conflict\n\n`;
         // Extract disagreements by looking for contradictory keywords
@@ -683,15 +674,14 @@ Remember: You are ${currentAgent.toUpperCase()}, passionate advocate for ${assig
         }
         return synthesis;
     }
-    async executeBrutalistAnalysis(analysisType, targetPath, systemPromptSpec, context, workingDirectory, enableSandbox, preferredCLI, verbose, models, progressToken) {
+    async executeBrutalistAnalysis(analysisType, primaryContent, systemPromptSpec, context, workingDirectory, preferredCLI, verbose, models, progressToken, sessionId, requestId) {
         logger.info(`🏢 Starting brutalist analysis: ${analysisType}`);
-        logger.info(`🔧 DEBUG: preferredCLI=${preferredCLI}, targetPath=${targetPath}`);
+        logger.info(`🔧 DEBUG: preferredCLI=${preferredCLI}, primaryContent=${primaryContent}`);
         logger.debug("Executing brutalist analysis", {
-            targetPath,
+            primaryContent,
             analysisType,
             systemPromptSpec,
             workingDirectory,
-            enableSandbox,
             preferredCLI
         });
         try {
@@ -702,16 +692,18 @@ Remember: You are ${currentAgent.toUpperCase()}, passionate advocate for ${assig
             // Execute CLI agent analysis (single or multi-CLI based on preferences)
             logger.info(`🔍 Executing brutalist analysis with timeout: ${this.config.defaultTimeout}ms`);
             logger.info(`🔧 DEBUG: About to call cliOrchestrator.executeBrutalistAnalysis`);
-            const responses = await this.cliOrchestrator.executeBrutalistAnalysis(analysisType, targetPath, systemPromptSpec, context, {
+            const responses = await this.cliOrchestrator.executeBrutalistAnalysis(analysisType, primaryContent, systemPromptSpec, context, {
                 workingDirectory: workingDirectory || this.config.workingDirectory,
-                sandbox: enableSandbox ?? this.config.enableSandbox,
                 timeout: this.config.defaultTimeout,
                 preferredCLI,
                 analysisType: analysisType,
                 models,
                 onStreamingEvent: this.handleStreamingEvent,
                 progressToken,
-                onProgress: progressToken ? this.handleProgressUpdate.bind(this, progressToken) : undefined
+                onProgress: progressToken && sessionId ?
+                    (progress, total, message) => this.handleProgressUpdate(progressToken, progress, total, message, sessionId) : undefined,
+                sessionId,
+                requestId
             });
             logger.info(`🔧 DEBUG: cliOrchestrator.executeBrutalistAnalysis returned ${responses.length} responses`);
             const successfulResponses = responses.filter(r => r.success);
@@ -725,7 +717,7 @@ Remember: You are ${currentAgent.toUpperCase()}, passionate advocate for ${assig
                 responses,
                 synthesis,
                 analysisType,
-                targetPath,
+                targetPath: primaryContent,
                 executionSummary: {
                     totalCLIs: responses.length,
                     successfulCLIs: successfulResponses.length,
@@ -743,7 +735,32 @@ Remember: You are ${currentAgent.toUpperCase()}, passionate advocate for ${assig
             throw error;
         }
     }
-    formatToolResponse(result, verbose = false, paginationParams) {
+    /**
+     * Extract full content from analysis result for caching
+     */
+    extractFullContent(result) {
+        if (result.synthesis) {
+            return result.synthesis;
+        }
+        else if (result.responses && result.responses.length > 0) {
+            const successfulResponses = result.responses.filter(r => r.success);
+            if (successfulResponses.length > 0) {
+                let output = `${successfulResponses.length} AI critics have systematically demolished your work.\n\n`;
+                successfulResponses.forEach((response, index) => {
+                    output += `## Critic ${index + 1}: ${response.agent.toUpperCase()}\n`;
+                    output += `*Execution time: ${response.executionTime}ms*\n\n`;
+                    output += response.output;
+                    // Only add separator between critics, not after the last one
+                    if (index < successfulResponses.length - 1) {
+                        output += '\n\n---\n\n';
+                    }
+                });
+                return output;
+            }
+        }
+        return null;
+    }
+    formatToolResponse(result, verbose = false, paginationParams, analysisId) {
         logger.info(`🔧 DEBUG: formatToolResponse called with synthesis length: ${result.synthesis?.length || 0}`);
         logger.info(`🔧 DEBUG: result.success=${result.success}, responses.length=${result.responses?.length || 0}`);
         logger.info(`🔧 DEBUG: pagination params:`, paginationParams);
@@ -762,7 +779,7 @@ Remember: You are ${currentAgent.toUpperCase()}, passionate advocate for ${assig
         }
         // Handle pagination if params provided and content is substantial
         if (paginationParams && primaryContent) {
-            return this.formatPaginatedResponse(primaryContent, paginationParams, result, verbose);
+            return this.formatPaginatedResponse(primaryContent, paginationParams, result, verbose, analysisId);
         }
         // Non-paginated response (legacy behavior)
         if (primaryContent) {
@@ -795,41 +812,72 @@ Remember: You are ${currentAgent.toUpperCase()}, passionate advocate for ${assig
                 }]
         };
     }
-    formatPaginatedResponse(content, paginationParams, result, verbose) {
+    formatPaginatedResponse(content, paginationParams, result, verbose, analysisId) {
         // Using imported pagination utilities
         const offset = paginationParams.offset || 0;
         const limit = paginationParams.limit || PAGINATION_DEFAULTS.DEFAULT_LIMIT;
         logger.info(`🔧 DEBUG: Paginating content - offset: ${offset}, limit: ${limit}, total: ${content.length}`);
-        // Simple character-based pagination for immediate Claude Code compatibility
-        const endOffset = Math.min(offset + limit, content.length);
-        const chunk = content.substring(offset, endOffset);
+        // Use ResponseChunker for intelligent boundary detection
+        const chunker = new ResponseChunker(limit, 200); // 200 char overlap
+        const chunks = chunker.chunkText(content);
+        // Find the appropriate chunk based on offset
+        let targetChunk = chunks[0]; // Default to first chunk
+        let currentOffset = 0;
+        for (const chunk of chunks) {
+            if (offset >= chunk.startOffset && offset < chunk.endOffset) {
+                targetChunk = chunk;
+                break;
+            }
+            currentOffset = chunk.endOffset;
+        }
+        const chunkContent = targetChunk.content;
+        const actualOffset = targetChunk.startOffset;
+        const endOffset = targetChunk.endOffset;
         // Create pagination metadata
         const pagination = createPaginationMetadata(content.length, paginationParams, limit);
         const statusLine = formatPaginationStatus(pagination);
         // Estimate token usage for user awareness
-        const chunkTokens = estimateTokenCount(chunk);
+        const chunkTokens = estimateTokenCount(chunkContent);
         const totalTokens = estimateTokenCount(content);
         // Format response with pagination info
         let paginatedText = '';
-        // Add pagination header
+        // Add header
         paginatedText += `# Brutalist Analysis Results\n\n`;
-        paginatedText += `**📊 Pagination Status:** ${statusLine}\n`;
-        paginatedText += `**🔢 Token Estimate:** ~${chunkTokens.toLocaleString()} tokens (chunk) / ~${totalTokens.toLocaleString()} tokens (total)\n\n`;
-        if (pagination.hasMore) {
-            paginatedText += `**⏭️ Continue Reading:** Use \`offset: ${endOffset}\` for next chunk\n\n`;
+        // Only show pagination metadata if pagination is actually needed
+        const needsPagination = pagination.totalChunks > 1 || pagination.hasMore;
+        if (needsPagination) {
+            paginatedText += `**📊 Pagination Status:** ${statusLine}\n`;
+            if (analysisId) {
+                paginatedText += `**🔑 Analysis ID:** ${analysisId}\n`;
+            }
+            paginatedText += `**🔢 Token Estimate:** ~${chunkTokens.toLocaleString()} tokens (chunk) / ~${totalTokens.toLocaleString()} tokens (total)\n\n`;
+            if (pagination.hasMore) {
+                if (analysisId) {
+                    paginatedText += `**⏭️ Continue Reading:** Use \`analysis_id: "${analysisId}", offset: ${endOffset}\`\n\n`;
+                }
+                else {
+                    paginatedText += `**⏭️ Continue Reading:** Use \`offset: ${endOffset}\` for next chunk\n\n`;
+                }
+            }
         }
         paginatedText += `---\n\n`;
         // Add the actual content chunk
-        paginatedText += chunk;
-        // Add footer for continuation
-        if (pagination.hasMore) {
-            paginatedText += `\n\n---\n\n`;
-            paginatedText += `📖 **End of chunk ${pagination.chunkIndex}/${pagination.totalChunks}**\n`;
-            paginatedText += `🔄 To continue: Use same tool with \`offset: ${endOffset}\``;
-        }
-        else {
+        paginatedText += chunkContent;
+        // Add footer
+        if (needsPagination) {
             paginatedText += `\n\n---\n\n`;
-            paginatedText += `✅ **Complete analysis shown** (${content.length.toLocaleString()} characters total)`;
+            if (pagination.hasMore) {
+                paginatedText += `📖 **End of chunk ${pagination.chunkIndex}/${pagination.totalChunks}**\n`;
+                if (analysisId) {
+                    paginatedText += `🔄 To continue: Include \`analysis_id: "${analysisId}"\` with \`offset: ${endOffset}\` in next request`;
+                }
+                else {
+                    paginatedText += `🔄 To continue: Use same tool with \`offset: ${endOffset}\``;
+                }
+            }
+            else {
+                paginatedText += `✅ **Complete analysis shown** (${content.length.toLocaleString()} characters total)`;
+            }
         }
         // Add verbose execution details if requested
         if (verbose && result.executionSummary) {
@@ -840,7 +888,7 @@ Remember: You are ${currentAgent.toUpperCase()}, passionate advocate for ${assig
                 paginatedText += `- **Selected CLI:** ${result.executionSummary.selectedCLI}\n`;
             }
         }
-        logger.info(`🔧 DEBUG: Returning paginated chunk - ${chunk.length} chars (${chunkTokens} tokens)`);
+        logger.info(`🔧 DEBUG: Returning paginated chunk - ${chunkContent.length} chars (${chunkTokens} tokens)`);
         return {
             content: [{
                     type: "text",
@@ -858,7 +906,7 @@ Remember: You are ${currentAgent.toUpperCase()}, passionate advocate for ${assig
                 sanitizedMessage = "Analysis timed out - try reducing scope or increasing timeout";
             }
             else if (error.message.includes('ENOENT') || error.message.includes('no such file')) {
-                sanitizedMessage = "Target path not found";
+                sanitizedMessage = `DEBUG: Target path not found - Original error: ${error.message}`;
             }
             else if (error.message.includes('EACCES') || error.message.includes('permission denied')) {
                 sanitizedMessage = "Permission denied - check file access";