@kjerneverk/agentic 1.0.5-dev.0

package/output/kodrdriv/agentic-reflection-commit-2026-01-14T14-55-10-122Z.md

@@ -0,0 +1,177 @@
+# Agentic Workflow - Self-Reflection Report
+
+Generated: 2026-01-14T14:55:10.122Z
+
+## Execution Summary
+
+- **Iterations**: 2
+- **Tool Calls**: 3
+- **Unique Tools**: 3
+
+## Tool Effectiveness Analysis
+
+| Tool | Calls | Success | Failures | Success Rate | Avg Duration |
+|------|-------|---------|----------|--------------|--------------|
+| get_file_modification_times | 1 | 1 | 0 | 100.0% | 2ms |
+| group_files_by_concern | 1 | 1 | 0 | 100.0% | 1ms |
+| get_recent_commits | 1 | 1 | 0 | 100.0% | 21ms |
+
+### Tool Performance Insights
+
+**Most Frequently Used:**
+- get_file_modification_times: 1 calls
+- group_files_by_concern: 1 calls
+- get_recent_commits: 1 calls
+
+## Recommendations for Improvement
+
+*No specific recommendations at this time. Execution appears optimal.*
+
+## Detailed Execution Timeline
+
+| Time | Iteration | Tool | Result | Duration |
+|------|-----------|------|--------|----------|
+| 6:54:04 AM | 1 | get_file_modification_times | ✅ Success | 2ms |
+| 6:54:04 AM | 1 | group_files_by_concern | ✅ Success | 1ms |
+| 6:54:04 AM | 1 | get_recent_commits | ✅ Success | 21ms |
+
+## Conversation History
+
+<details>
+<summary>Click to expand full agentic interaction</summary>
+
+```json
+[
+  {
+    "role": "system",
+    "content": "You are a professional software engineer writing commit messages for your team.\n\n## Available Tools\n\n### Understanding\n\n**get_file_history** _(cheap)_\nGet git commit history for one or more files to understand their evolution and past changes\n\nParameters:\n- `filePaths` (required): Array of file paths to get history for\n- `limit`: Maximum number of commits to return (default: 10)\n- `format`: Output format: \"summary\" for brief or \"detailed\" for full messages\n\n**When to use:** Get git commit history for one or more files to understand their evolution and past changes\n\n**Examples:**\n- Check if file has recent refactoring: `get_file_history({\"filePaths\":[\"src/auth.ts\"],\"limit\":5})`\n- Understand evolution of multiple related files: `get_file_history({\"filePaths\":[\"src/user.ts\",\"src/auth.ts\"],\"limit\":10,\"format\":\"detailed\"})`\n\n---\n\n**get_file_content** _(moderate)_\nGet the complete current content of a file to understand context around changes. Returns a message if the file does not exist (e.g., if it was deleted).\n\nParameters:\n- `filePath` (required): Path to the file\n- `includeLineNumbers`: Include line numbers in output (default: false)\n\n**When to use:** Get the complete current content of a file to understand context around changes. Returns a message if the file does not exist (e.g., if it was deleted).\n\n**Examples:**\n- See full class definition for modified method: `get_file_content({\"filePath\":\"src/services/auth.ts\",\"includeLineNumbers\":true})`\n- Check imports and structure: `get_file_content({\"filePath\":\"src/utils/helpers.ts\"})`\n\n---\n\n**get_related_tests** _(cheap)_\nFind test files related to production files to understand what the code is supposed to do\n\nParameters:\n- `filePaths` (required): Production file paths\n\n**When to use:** Find test files related to production files to understand what the code is supposed to do\n\n**Examples:**\n- Find tests for modified service: `get_related_tests({\"filePaths\":[\"src/services/auth.ts\"]})`\n\n---\n\n**analyze_diff_section** _(cheap)_\nGet expanded context around specific lines in a file to better understand changes\n\nParameters:\n- `filePath` (required): File containing the section to analyze\n- `startLine` (required): Starting line number\n- `endLine` (required): Ending line number\n- `contextLines`: Number of additional context lines to show before and after (default: 10)\n\n**When to use:** Get expanded context around specific lines in a file to better understand changes\n\n**Examples:**\n- See context around confusing change: `analyze_diff_section({\"filePath\":\"src/auth.ts\",\"startLine\":45,\"endLine\":52,\"contextLines\":15})`\n\n---\n\n**get_recent_commits** _(cheap)_\nGet recent commits that modified the same files to understand recent work in this area\n\nParameters:\n- `filePaths` (required): Files to check for recent commits\n- `since`: Time period to look back (e.g., \"1 week ago\", \"2 days ago\")\n- `limit`: Maximum number of commits to return (default: 5)\n\n**When to use:** Get recent commits that modified the same files to understand recent work in this area\n\n**Examples:**\n- Check for duplicate commit messages: `get_recent_commits({\"filePaths\":[\"src/auth.ts\"],\"since\":\"1 week ago\",\"limit\":5})`\n\n---\n\n### Analysis\n\n**search_codebase** _(moderate)_\nSearch for code patterns, function names, or text across the codebase using git grep\n\nParameters:\n- `query` (required): Search pattern (can be plain text or regex)\n- `fileTypes`: Limit search to specific file extensions (e.g., [\"ts\", \"js\"])\n- `contextLines`: Number of context lines to show around matches (default: 2)\n\n**When to use:** Search for code patterns, function names, or text across the codebase using git grep\n\n**Examples:**\n- Find all uses of a renamed function: `search_codebase({\"query\":\"oldFunctionName\",\"fileTypes\":[\"ts\",\"tsx\"]})`\n- Check if pattern exists elsewhere: `search_codebase({\"query\":\"pattern.*string\",\"contextLines\":3})`\n\n---\n\n**get_file_dependencies** _(moderate)_\nFind which files import or depend on the changed files to assess change impact\n\nParameters:\n- `filePaths` (required): Files to analyze dependencies for\n\n**When to use:** Find which files import or depend on the changed files to assess change impact\n\n**Examples:**\n- Check impact of util function change: `get_file_dependencies({\"filePaths\":[\"src/utils/format.ts\"]})`\n\n---\n\n### Organization\n\n**group_files_by_concern** _(cheap)_\nAnalyze changed files and suggest logical groupings that might represent separate commits\n\nParameters:\n- `filePaths` (required): All changed files to analyze\n\n**When to use:** Analyze changed files and suggest logical groupings that might represent separate commits\n\n**Examples:**\n- Check if multiple unrelated changes should be split: `group_files_by_concern({\"filePaths\":[\"src/auth.ts\",\"README.md\",\"tests/auth.test.ts\",\"package.json\"]})`\n\n---\n\n**get_file_modification_times** _(cheap)_\nGet modification timestamps for changed files. Temporal proximity is one signal (among others) that can help identify related changes. Files modified close together MAY be part of the same logical change, but this is not guaranteed - always cross-reference with logical groupings.\n\nParameters:\n- `filePaths` (required): All changed files to analyze\n\n**When to use:** Get modification timestamps for changed files. Temporal proximity is one signal (among others) that can help identify related changes. Files modified close together MAY be part of the same logical change, but this is not guaranteed - always cross-reference with logical groupings.\n\n**Examples:**\n- Identify files modified together vs at different times: `get_file_modification_times({\"filePaths\":[\"src/auth.ts\",\"src/user.ts\",\"README.md\",\"tests/auth.test.ts\"]})`\n\n---\n\n\n\n## Your Task\n\nAnalyze the staged changes and determine the best way to commit them. Your primary goal is to create **meaningful, atomic commits** that each represent a single logical change.\n\n**CRITICAL**: When there are many changed files, especially after a long work session (multiple hours), you should almost always split them into multiple commits. A single commit with 10+ files usually indicates multiple distinct changes that should be separated.\n\nThink about:\n- What distinct features, fixes, or improvements are represented?\n- Are there natural groupings by functionality, module, or purpose?\n- When were files modified relative to each other?\n- What should reviewers focus on in each commit?\n\n## Investigation Strategy\n\nFor any non-trivial set of changes, gather multiple signals to understand how to group commits:\n\n1. **Check file modification times** using `get_file_modification_times`\n   - This reveals *when* files were changed relative to each other\n   - Files modified close together *may* be part of the same logical change\n   - Large temporal gaps *can* indicate separate work sessions\n   - Note: temporal proximity is one signal, not a guarantee of relatedness\n\n2. **Understand logical relationships** using `group_files_by_concern`\n   - Groups by module, type (tests, docs, source), and directory structure\n   - Reveals which files are functionally related regardless of when they were modified\n\n3. **Cross-reference both signals** to make informed decisions:\n   - Files modified together AND logically related → strong candidate for same commit\n   - Files modified apart BUT logically related → might still belong together\n   - Files modified together BUT logically unrelated → consider splitting\n   - Use your judgment - neither signal is definitive on its own\n\n4. **Investigate further** as needed:\n   - get_file_content - see full context when diffs are unclear\n   - get_file_history - understand how code evolved\n   - get_file_dependencies - assess impact of changes\n   - get_recent_commits - avoid duplicate messages\n   - get_related_tests - understand behavior changes\n   - search_codebase - find usage patterns\n\n## When to Split Commits\n\n**Prefer multiple commits when:**\n- Changes span multiple hours of work (check modification times!)\n- Different logical features or fixes are included\n- Test changes could be separated from production code changes\n- Documentation updates are unrelated to code changes\n- Refactoring is mixed with feature work\n- Configuration changes are mixed with implementation changes\n- Files in different modules/packages are changed for different reasons\n\n**Keep as one commit when:**\n- All changes are part of a single, cohesive feature\n- Files were modified together in a focused work session\n- Test changes directly test the production code changes\n- The changes tell a single coherent story\n\n**Default bias**: When in doubt about whether to split, **prefer splitting**. It's better to have too many focused commits than too few bloated ones. A good commit should be understandable and reviewable in isolation.\n\n## Important Context Guidelines\n\nIf additional context is provided (from context files or other sources), use your judgment:\n- If the context is relevant to these specific changes, incorporate it\n- If the context describes unrelated changes or other packages, ignore it\n- Don't force connections between unrelated information\n- Focus on accurately describing what actually changed\n\n## Writing Style\n\nWrite naturally and directly:\n- Use plain language, not corporate speak\n- Be specific and concrete\n- Avoid buzzwords and jargon\n- No emojis or excessive punctuation\n- No phrases like \"this commit\" or \"this PR\"\n- No meta-commentary about the commit itself\n\nFollow conventional commit format when appropriate (feat:, fix:, refactor:, docs:, test:, chore:), but prioritize clarity over formality.\n\n## Output Format\n\nWhen ready, format your response as:\n\nCOMMIT_MESSAGE:\n[Your commit message here - only for the FIRST group of changes if splitting]\n\nIf changes should be split into multiple commits (which is often the case with large changesets):\n\nSUGGESTED_SPLITS:\nSplit 1:\nFiles: [list of files]\nRationale: [why these belong together - mention temporal clustering and/or logical relationship]\nMessage: [commit message for this split]\n\nSplit 2:\nFiles: [list of files]\nRationale: [why these belong together]\nMessage: [commit message for this split]\n\nSplit 3:\n...\n\nOutput only the commit message and splits. No conversational remarks or follow-up offers."
+  },
+  {
+    "role": "user",
+    "content": "I have staged changes that need a commit message.\n\nChanged files (12):\n  - SECURITY.md\n  - package.json\n  - src/context-manager.ts\n  - src/index.ts\n  - src/logger.ts\n  - src/tool-guard.ts\n  - src/tool-sandbox.ts\n  - src/tools.ts\n  - tests/tool-guard.test.ts\n  - tests/tool-sandbox.test.ts\n  - vite.config.ts\n  - vitest.config.ts\n\nDiff:\ndiff --git a/SECURITY.md b/SECURITY.md\nnew file mode 100644\nindex 0000000..2fd4bf2\n--- /dev/null\n+++ b/SECURITY.md\n@@ -0,0 +1,94 @@\n+# Security Policy\n+\n+## Supported Versions\n+\n+| Version | Supported          |\n+| ------- | ------------------ |\n+| 0.x.x   | :white_check_mark: |\n+\n+## Reporting a Vulnerability\n+\n+If you discover a security vulnerability, please report it responsibly.\n+\n+**Do not open a public GitHub issue for security vulnerabilities.**\n+\n+## Security Features\n+\n+The agentic package includes security features for tool execution:\n+\n+### Tool Validation (ToolGuard)\n+\n+```typescript\n+import { ToolGuard } from '@theunwalked/agentic';\n+import { z } from 'zod';\n+\n+const guard = new ToolGuard({\n+  enabled: true,\n+  validateParams: true,\n+  detectPrototypePollution: true,\n+});\n+\n+// Register tool schemas\n+guard.registerSchema('read_file', z.object({\n+  path: z.string().max(1000),\n+  encoding: z.enum(['utf8', 'base64']).optional(),\n+}));\n+\n+// Validate before execution\n+const result = guard.validate('read_file', params);\n+if (!result.valid) {\n+  // Handle validation failure\n+}\n+```\n+\n+### Tool Sandboxing (ToolSandbox)\n+\n+```typescript\n+import { ToolSandbox } from '@theunwalked/agentic';\n+\n+const sandbox = new ToolSandbox({\n+  enabled: true,\n+  maxExecutionTime: 30000,\n+  maxConcurrent: 5,\n+  maxOutputSize: 1024 * 1024, // 1MB\n+});\n+\n+// Execute with sandboxing\n+const result = await sandbox.execute(\n+  'my_tool',\n+  async (signal) => {\n+    // Tool implementation\n+    // Check signal.aborted for cancellation\n+  }\n+);\n+```\n+\n+### Security Features\n+\n+- **Parameter Validation**: Zod schema validation for all tool parameters\n+- **Prototype Pollution Prevention**: Blocks `__proto__`, `constructor`, `prototype`\n+- **Execution Timeouts**: Configurable timeouts for tool execution\n+- **Concurrency Limits**: Limit concurrent tool executions\n+- **Output Size Limits**: Prevent memory exhaustion from large outputs\n+- **Allow/Deny Lists**: Control which tools can be executed\n+- **Silent Logging**: Library logging disabled by default\n+\n+## Environment Variables\n+\n+```bash\n+# Enable agentic logging\n+AGENTIC_LOGGING=true\n+\n+# Or use DEBUG pattern\n+DEBUG=*agentic*\n+```\n+\n+## Security Checklist\n+\n+- [ ] Define Zod schemas for all tool parameters\n+- [ ] Enable prototype pollution detection\n+- [ ] Set appropriate execution timeouts\n+- [ ] Configure concurrency limits\n+- [ ] Use allow/deny lists for tools in production\n+- [ ] Monitor tool execution metrics\n+\ndiff --git a/package.json b/package.json\nindex 6a72bec..7e0933c 100644\n--- a/package.json\n+++ b/package.json\n@@ -39,6 +39,7 @@\n     \"url\": \"https://github.com/kjerneverk/agentic\"\n   },\n   \"dependencies\": {\n+    \"@fjell/logging\": \"^4.4.68\",\n     \"zod\": \"^4.3.5\"\n   },\n   \"devDependencies\": {\ndiff --git a/src/context-manager.ts b/src/context-manager.ts\nindex 4f487cb..7aa5979 100644\n--- a/src/context-manager.ts\n+++ b/src/context-manager.ts\n@@ -251,11 +251,12 @@ export class ContextManager {\n     }\n \n     private hashContent(content: string): string {\n+        // Use 32 characters (128 bits) for sufficient collision resistance\n         return crypto\n             .createHash('sha256')\n             .update(content)\n             .digest('hex')\n-            .substring(0, 16);\n+            .substring(0, 32);\n     }\n \n     private normalizeContent(content: string): string {\ndiff --git a/src/index.ts b/src/index.ts\nindex a7ac357..fc7c436 100644\n--- a/src/index.ts\n+++ b/src/index.ts\n@@ -52,6 +52,22 @@ export type {\n } from './tools';\n export { ToolRegistry } from './tools';\n \n+// Tool Security\n+export type {\n+    ToolSecurityConfig,\n+    ToolValidationResult,\n+    ToolGuardEvents,\n+} from './tool-guard';\n+export { ToolGuard } from './tool-guard';\n+\n+// Tool Sandboxing\n+export type {\n+    SandboxedContext,\n+    SandboxOptions,\n+    ToolSandboxEvents,\n+} from './tool-sandbox';\n+export { ToolSandbox, createSecureTool } from './tool-sandbox';\n+\n // Context Manager\n export type { ContextStats } from './context-manager';\n export { ContextManager } from './context-manager';\ndiff --git a/src/logger.ts b/src/logger.ts\nindex 4c823b5..8e42c21 100644\n--- a/src/logger.ts\n+++ b/src/logger.ts\n@@ -1,41 +1,110 @@\n /**\n  * Agentic Package - Logger\n  *\n- * Shared logging infrastructure for agentic components.\n+ * Shared logging infrastructure backed by @fjell/logging for\n+ * comprehensive sensitive data masking and structured logging.\n  */\n \n-/* eslint-disable no-var */\n-declare var console: {\n-    debug: (message: string, ...args: any[]) => void;\n-    info: (message: string, ...args: any[]) => void;\n-    warn: (message: string, ...args: any[]) => void;\n-    error: (message: string, ...args: any[]) => void;\n-};\n-/* eslint-enable no-var */\n+import Logging from '@fjell/logging';\n \n export const LIBRARY_NAME = 'agentic';\n \n+// Get the library-level logger from Fjell\n+const LibLogger = Logging.getLogger('@theunwalked/agentic');\n+\n+/**\n+ * Create a silent logger with the given name\n+ */\n+function createSilentLogger(name: string): Logger {\n+    return {\n+        name,\n+        debug: () => {},\n+        info: () => {},\n+        warn: () => {},\n+        error: () => {},\n+        verbose: () => {},\n+        silly: () => {},\n+        get: (...components: string[]) => createSilentLogger(`${name}:${components.join(':')}`),\n+    };\n+}\n+\n+/**\n+ * Silent logger that discards all output\n+ * Use this as default to prevent accidental information disclosure\n+ */\n+export const SILENT_LOGGER: Logger = createSilentLogger('silent');\n+\n+/**\n+ * Check if logging is explicitly enabled via environment variable\n+ */\n+const isLoggingEnabled = (): boolean => {\n+    return process.env.AGENTIC_LOGGING === 'true' ||\n+           process.env.DEBUG?.includes('agentic') ||\n+           process.env.NODE_ENV === 'development';\n+};\n+\n export interface Logger {\n-    name: string;\n-    debug: (message: string, ...args: any[]) => void;\n-    info: (message: string, ...args: any[]) => void;\n-    warn: (message: string, ...args: any[]) => void;\n-    error: (message: string, ...args: any[]) => void;\n-    verbose: (message: string, ...args: any[]) => void;\n-    silly: (message: string, ...args: any[]) => void;\n+  name: string;\n+  debug: (message: string, ...args: any[]) => void;\n+  info: (message: string, ...args: any[]) => void;\n+  warn: (message: string, ...args: any[]) => void;\n+  error: (message: string, ...args: any[]) => void;\n+  verbose: (message: string, ...args: any[]) => void;\n+  silly: (message: string, ...args: any[]) => void;\n+  /** Get a child logger for a component */\n+  get?: (...components: string[]) => Logger;\n+}\n+\n+/**\n+ * Create a Logger from a Fjell logger instance\n+ */\n+function createLoggerFromFjell(fjellLogger: ReturnType<typeof LibLogger.get>, name: string): Logger {\n+    return {\n+        name,\n+        debug: (message: string, ...args: any[]) => fjellLogger.debug(message, ...args),\n+        info: (message: string, ...args: any[]) => fjellLogger.info(message, ...args),\n+        warn: (message: string, ...args: any[]) => fjellLogger.warning(message, ...args),\n+        error: (message: string, ...args: any[]) => fjellLogger.error(message, ...args),\n+        verbose: (message: string, ...args: any[]) => fjellLogger.debug(message, ...args),\n+        silly: (message: string, ...args: any[]) => fjellLogger.debug(message, ...args),\n+        get: (...components: string[]) => {\n+            const childLogger = fjellLogger.get(...components);\n+            return createLoggerFromFjell(childLogger, `${name}:${components.join(':')}`);\n+        },\n+    };\n }\n \n- \n-export const DEFAULT_LOGGER: Logger = {\n-    name: 'default',\n-    debug: (message: string, ...args: any[]) => console.debug(message, ...args),\n-    info: (message: string, ...args: any[]) => console.info(message, ...args),\n-    warn: (message: string, ...args: any[]) => console.warn(message, ...args),\n-    error: (message: string, ...args: any[]) => console.error(message, ...args),\n-    verbose: () => {},\n-    silly: () => {},\n+/**\n+ * Fjell-backed logger with sensitive data masking\n+ * \n+ * Features:\n+ * - Automatic sensitive data masking (API keys, passwords, etc.)\n+ * - Circular reference protection\n+ * - Hierarchical component logging\n+ */\n+const FJELL_LOGGER: Logger = {\n+    name: 'fjell',\n+    debug: (message: string, ...args: any[]) => LibLogger.debug(message, ...args),\n+    info: (message: string, ...args: any[]) => LibLogger.info(message, ...args),\n+    warn: (message: string, ...args: any[]) => LibLogger.warning(message, ...args),\n+    error: (message: string, ...args: any[]) => LibLogger.error(message, ...args),\n+    verbose: (message: string, ...args: any[]) => LibLogger.debug(message, ...args),\n+    silly: (message: string, ...args: any[]) => LibLogger.debug(message, ...args),\n+    get: (...components: string[]) => {\n+        const childLogger = LibLogger.get(...components);\n+        return createLoggerFromFjell(childLogger, components.join(':'));\n+    },\n };\n- \n+\n+/**\n+ * Default logger - silent by default to prevent information disclosure\n+ * \n+ * Enable logging by setting one of:\n+ * - AGENTIC_LOGGING=true\n+ * - DEBUG=*agentic*\n+ * - NODE_ENV=development\n+ */\n+export const DEFAULT_LOGGER: Logger = isLoggingEnabled() ? FJELL_LOGGER : SILENT_LOGGER;\n \n export function wrapLogger(toWrap: Logger, name?: string): Logger {\n     const requiredMethods: (keyof Logger)[] = [\n@@ -68,7 +137,7 @@ export function wrapLogger(toWrap: Logger, name?: string): Logger {\n     };\n \n     return {\n-        name: 'wrapped',\n+        name: name || 'wrapped',\n         debug: (message: string, ...args: any[]) => log('debug', message, ...args),\n         info: (message: string, ...args: any[]) => log('info', message, ...args),\n         warn: (message: string, ...args: any[]) => log('warn', message, ...args),\n@@ -76,6 +145,6 @@ export function wrapLogger(toWrap: Logger, name?: string): Logger {\n         verbose: (message: string, ...args: any[]) =>\n             log('verbose', message, ...args),\n         silly: (message: string, ...args: any[]) => log('silly', message, ...args),\n+        get: (...components: string[]) => wrapLogger(toWrap, name ? `${name}:${components.join(':')}` : components.join(':')),\n     };\n }\n-\ndiff --git a/src/tool-guard.ts b/src/tool-guard.ts\nnew file mode 100644\nindex 0000000..0c8afc1\n--- /dev/null\n+++ b/src/tool-guard.ts\n@@ -0,0 +1,293 @@\n+/**\n+ * Agentic Package - Tool Guard\n+ *\n+ * Security layer for tool parameter validation and access control.\n+ */\n+\n+import { ZodSchema, ZodError } from 'zod';\n+import { DEFAULT_LOGGER, wrapLogger, type Logger } from './logger';\n+\n+/**\n+ * Configuration for tool security\n+ */\n+export interface ToolSecurityConfig {\n+    enabled: boolean;\n+    validateParams: boolean;\n+    sandboxExecution: boolean;\n+    maxExecutionTime: number;\n+    maxConcurrentCalls: number;\n+    deniedTools: string[];\n+    allowedTools?: string[];\n+}\n+\n+/**\n+ * Result of tool parameter validation\n+ */\n+export interface ToolValidationResult<T> {\n+    success: boolean;\n+    data?: T;\n+    error?: string;\n+    violations?: string[];\n+}\n+\n+/**\n+ * Event handlers for security events\n+ */\n+export interface ToolGuardEvents {\n+    onValidationFailed?: (toolName: string, message: string) => void;\n+    onExecutionBlocked?: (toolName: string, reason: string) => void;\n+    onPrototypePollution?: (toolName: string) => void;\n+}\n+\n+const DEFAULT_CONFIG: ToolSecurityConfig = {\n+    enabled: true,\n+    validateParams: true,\n+    sandboxExecution: false,\n+    maxExecutionTime: 30000,\n+    maxConcurrentCalls: 10,\n+    deniedTools: [],\n+};\n+\n+/**\n+ * ToolGuard provides security validation for tool execution.\n+ *\n+ * Features:\n+ * - Schema-based parameter validation with Zod\n+ * - Prototype pollution detection\n+ * - Tool allow/deny lists\n+ * - Event callbacks for security monitoring\n+ *\n+ * @example\n+ * ```typescript\n+ * const guard = new ToolGuard({ deniedTools: ['dangerous_tool'] });\n+ *\n+ * // Validate parameters\n+ * const schema = z.object({ path: z.string() });\n+ * const result = guard.validateParams('read_file', { path: '/test' }, schema);\n+ *\n+ * // Check if tool is allowed\n+ * if (guard.isToolAllowed('my_tool')) {\n+ *   // execute tool\n+ * }\n+ * ```\n+ */\n+export class ToolGuard {\n+    private config: ToolSecurityConfig;\n+    private logger: Logger;\n+    private events: ToolGuardEvents;\n+\n+    constructor(\n+        config: Partial<ToolSecurityConfig> = {},\n+        logger?: Logger,\n+        events: ToolGuardEvents = {}\n+    ) {\n+        this.config = { ...DEFAULT_CONFIG, ...config };\n+        this.logger = wrapLogger(logger || DEFAULT_LOGGER, 'ToolGuard');\n+        this.events = events;\n+    }\n+\n+    /**\n+     * Validate tool parameters against a Zod schema\n+     */\n+    validateParams<T>(\n+        toolName: string,\n+        params: unknown,\n+        schema: ZodSchema<T>\n+    ): ToolValidationResult<T> {\n+        if (!this.config.enabled || !this.config.validateParams) {\n+            // Bypass validation if disabled\n+            return { success: true, data: params as T };\n+        }\n+\n+        try {\n+            const data = schema.parse(params);\n+            return { success: true, data };\n+        } catch (error) {\n+            if (error instanceof ZodError) {\n+                // Zod 4 uses 'issues' instead of 'errors'\n+                const issues = error.issues || [];\n+                const violations = issues.map(\n+                    (e) => `${e.path.join('.')}: ${e.message}`\n+                );\n+                const message = `Schema validation failed: ${violations.join('; ')}`;\n+\n+                this.logger.warn(`Tool validation failed for \"${toolName}\"`, {\n+                    violations,\n+                });\n+                this.events.onValidationFailed?.(toolName, message);\n+\n+                return {\n+                    success: false,\n+                    error: 'Parameter validation failed',\n+                    violations,\n+                };\n+            }\n+            throw error;\n+        }\n+    }\n+\n+    /**\n+     * Safely parse JSON tool arguments\n+     */\n+    parseToolArguments(\n+        toolName: string,\n+        jsonString: string\n+    ): ToolValidationResult<Record<string, unknown>> {\n+        if (!this.config.enabled) {\n+            return { success: true, data: JSON.parse(jsonString) };\n+        }\n+\n+        try {\n+            // First, try to parse as JSON\n+            const parsed = JSON.parse(jsonString);\n+\n+            // Check for prototype pollution attempts\n+            if (this.hasPrototypePollution(parsed)) {\n+                this.logger.error(\n+                    `Prototype pollution attempt detected for tool \"${toolName}\"`\n+                );\n+                this.events.onPrototypePollution?.(toolName);\n+                return {\n+                    success: false,\n+                    error: 'Invalid tool arguments: potentially malicious content detected',\n+                };\n+            }\n+\n+            // Ensure it's an object\n+            if (\n+                typeof parsed !== 'object' ||\n+                parsed === null ||\n+                Array.isArray(parsed)\n+            ) {\n+                return {\n+                    success: false,\n+                    error: 'Tool arguments must be a JSON object',\n+                };\n+            }\n+\n+            return { success: true, data: parsed };\n+        } catch (error) {\n+            const errorMsg =\n+                error instanceof Error ? error.message : 'Unknown error';\n+            this.logger.warn(`JSON parsing failed for tool \"${toolName}\"`, {\n+                error: errorMsg,\n+            });\n+            this.events.onValidationFailed?.(\n+                toolName,\n+                `JSON parsing failed: ${errorMsg}`\n+            );\n+            return {\n+                success: false,\n+                error: 'Invalid JSON in tool arguments',\n+            };\n+        }\n+    }\n+\n+    /**\n+     * Check if a tool is allowed to execute\n+     */\n+    isToolAllowed(toolName: string): boolean {\n+        if (!this.config.enabled) return true;\n+\n+        // Check deny list\n+        if (this.config.deniedTools.includes(toolName)) {\n+            this.logger.warn(`Tool \"${toolName}\" blocked by deny list`);\n+            this.events.onExecutionBlocked?.(toolName, 'Tool is in deny list');\n+            return false;\n+        }\n+\n+        // Check allow list if specified\n+        if (\n+            this.config.allowedTools &&\n+            !this.config.allowedTools.includes(toolName)\n+        ) {\n+            this.logger.warn(`Tool \"${toolName}\" not in allow list`);\n+            this.events.onExecutionBlocked?.(\n+                toolName,\n+                'Tool is not in allow list'\n+            );\n+            return false;\n+        }\n+\n+        return true;\n+    }\n+\n+    /**\n+     * Get current configuration\n+     */\n+    getConfig(): Readonly<ToolSecurityConfig> {\n+        return { ...this.config };\n+    }\n+\n+    /**\n+     * Update configuration\n+     */\n+    updateConfig(config: Partial<ToolSecurityConfig>): void {\n+        this.config = { ...this.config, ...config };\n+    }\n+\n+    /**\n+     * Add a tool to the deny list\n+     */\n+    denyTool(toolName: string): void {\n+        if (!this.config.deniedTools.includes(toolName)) {\n+            this.config.deniedTools.push(toolName);\n+        }\n+    }\n+\n+    /**\n+     * Remove a tool from the deny list\n+     */\n+    allowTool(toolName: string): void {\n+        const index = this.config.deniedTools.indexOf(toolName);\n+        if (index !== -1) {\n+            this.config.deniedTools.splice(index, 1);\n+        }\n+    }\n+\n+    /**\n+     * Check if security is enabled\n+     */\n+    isEnabled(): boolean {\n+        return this.config.enabled;\n+    }\n+\n+    /**\n+     * Enable or disable security\n+     */\n+    setEnabled(enabled: boolean): void {\n+        this.config.enabled = enabled;\n+    }\n+\n+    /**\n+     * Detect prototype pollution attempts\n+     */\n+    private hasPrototypePollution(obj: unknown, depth: number = 0): boolean {\n+        if (depth > 10) return false; // Prevent stack overflow\n+        if (typeof obj !== 'object' || obj === null) return false;\n+\n+        const dangerousKeys = ['__proto__', 'constructor', 'prototype'];\n+\n+        for (const key of Object.keys(obj)) {\n+            if (dangerousKeys.includes(key)) {\n+                return true;\n+            }\n+\n+            if (typeof (obj as Record<string, unknown>)[key] === 'object') {\n+                if (\n+                    this.hasPrototypePollution(\n+                        (obj as Record<string, unknown>)[key],\n+                        depth + 1\n+                    )\n+                ) {\n+                    return true;\n+                }\n+            }\n+        }\n+\n+        return false;\n+    }\n+}\n+\n+export default ToolGuard;\n+\ndiff --git a/src/tool-sandbox.ts b/src/tool-sandbox.ts\nnew file mode 100644\nindex 0000000..1e05b9d\n--- /dev/null\n+++ b/src/tool-sandbox.ts\n@@ -0,0 +1,336 @@\n+/**\n+ * Agentic Package - Tool Sandbox\n+ *\n+ * Capability-based sandboxing for tool execution with timeout,\n+ * concurrency limits, and output size restrictions.\n+ */\n+\n+import { ToolContext, Tool } from './tools';\n+import { ToolSecurityConfig, ToolGuard } from './tool-guard';\n+import { DEFAULT_LOGGER, wrapLogger, type Logger } from './logger';\n+\n+/**\n+ * Extended context with sandbox restrictions\n+ */\n+export interface SandboxedContext extends ToolContext {\n+    readonly sandbox: {\n+        allowedOperations: Set<string>;\n+        maxOutputSize: number;\n+        executionId: string;\n+    };\n+}\n+\n+/**\n+ * Options for sandbox execution\n+ */\n+export interface SandboxOptions {\n+    maxExecutionTime: number;\n+    maxOutputSize: number;\n+    allowedOperations?: string[];\n+    onBeforeExecution?: (\n+        tool: Tool,\n+        params: unknown\n+    ) => void | Promise<void>;\n+    onAfterExecution?: (\n+        tool: Tool,\n+        result: unknown,\n+        error?: Error\n+    ) => void | Promise<void>;\n+}\n+\n+/**\n+ * Event handlers for sandbox events\n+ */\n+export interface ToolSandboxEvents {\n+    onConcurrencyExceeded?: (toolName: string, activeCount: number) => void;\n+    onTimeout?: (toolName: string, timeoutMs: number) => void;\n+    onOutputSizeExceeded?: (\n+        toolName: string,\n+        size: number,\n+        maxSize: number\n+    ) => void;\n+    onCancelled?: (executionId: string) => void;\n+}\n+\n+/**\n+ * ToolSandbox provides capability-based sandboxing for tool execution.\n+ *\n+ * Features:\n+ * - Execution timeout enforcement\n+ * - Concurrent execution limits\n+ * - Output size limits\n+ * - Pre/post execution hooks\n+ * - Cancellation support\n+ *\n+ * Note: This provides capability-based restrictions, not true process isolation.\n+ * For maximum security, consider running untrusted tools in separate processes.\n+ *\n+ * @example\n+ * ```typescript\n+ * const sandbox = new ToolSandbox({\n+ *   maxExecutionTime: 5000,\n+ *   maxConcurrentCalls: 5,\n+ * });\n+ *\n+ * const result = await sandbox.execute(tool, params, context);\n+ * ```\n+ */\n+export class ToolSandbox {\n+    private config: ToolSecurityConfig;\n+    private logger: Logger;\n+    private events: ToolSandboxEvents;\n+    private activeExecutions: Map<string, AbortController> = new Map();\n+    private executionCount: number = 0;\n+\n+    constructor(\n+        config: Partial<ToolSecurityConfig> = {},\n+        logger?: Logger,\n+        events: ToolSandboxEvents = {}\n+    ) {\n+        this.config = {\n+            enabled: true,\n+            validateParams: true,\n+            sandboxExecution: true,\n+            maxExecutionTime: 30000,\n+            maxConcurrentCalls: 10,\n+            deniedTools: [],\n+            ...config,\n+        };\n+        this.logger = wrapLogger(logger || DEFAULT_LOGGER, 'ToolSandbox');\n+        this.events = events;\n+    }\n+\n+    /**\n+     * Execute a tool with sandbox restrictions\n+     */\n+    async execute<T>(\n+        tool: Tool,\n+        params: unknown,\n+        baseContext: ToolContext,\n+        options: Partial<SandboxOptions> = {}\n+    ): Promise<T> {\n+        if (!this.config.enabled || !this.config.sandboxExecution) {\n+            // Bypass sandboxing if disabled\n+            return tool.execute(params, baseContext);\n+        }\n+\n+        // Check concurrent execution limit\n+        if (this.activeExecutions.size >= this.config.maxConcurrentCalls) {\n+            this.logger.warn('Max concurrent executions reached', {\n+                toolName: tool.name,\n+                activeCount: this.activeExecutions.size,\n+                limit: this.config.maxConcurrentCalls,\n+            });\n+            this.events.onConcurrencyExceeded?.(\n+                tool.name,\n+                this.activeExecutions.size\n+            );\n+            throw new Error('Too many concurrent tool executions');\n+        }\n+\n+        const executionId = `exec-${++this.executionCount}-${Date.now()}`;\n+        const controller = new AbortController();\n+        this.activeExecutions.set(executionId, controller);\n+\n+        const sandboxedContext: SandboxedContext = {\n+            ...baseContext,\n+            sandbox: {\n+                allowedOperations: new Set(options.allowedOperations || []),\n+                maxOutputSize: options.maxOutputSize || 1024 * 1024, // 1MB default\n+                executionId,\n+            },\n+        };\n+\n+        const timeout = options.maxExecutionTime || this.config.maxExecutionTime;\n+\n+        try {\n+            // Pre-execution hook\n+            await options.onBeforeExecution?.(tool, params);\n+\n+            // Execute with timeout\n+            const result = await this.executeWithTimeout(\n+                () => tool.execute(params, sandboxedContext),\n+                timeout,\n+                controller.signal,\n+                tool.name\n+            );\n+\n+            // Check output size\n+            const outputSize = this.estimateSize(result);\n+            if (outputSize > sandboxedContext.sandbox.maxOutputSize) {\n+                this.logger.warn('Tool output exceeded max size', {\n+                    toolName: tool.name,\n+                    outputSize,\n+                    maxSize: sandboxedContext.sandbox.maxOutputSize,\n+                });\n+                this.events.onOutputSizeExceeded?.(\n+                    tool.name,\n+                    outputSize,\n+                    sandboxedContext.sandbox.maxOutputSize\n+                );\n+                throw new Error('Tool output exceeded maximum size limit');\n+            }\n+\n+            // Post-execution hook\n+            await options.onAfterExecution?.(tool, result);\n+\n+            return result as T;\n+        } catch (error) {\n+            await options.onAfterExecution?.(tool, undefined, error as Error);\n+            throw error;\n+        } finally {\n+            this.activeExecutions.delete(executionId);\n+        }\n+    }\n+\n+    /**\n+     * Cancel all active executions\n+     */\n+    cancelAll(): void {\n+        for (const [id, controller] of this.activeExecutions) {\n+            controller.abort();\n+            this.logger.info('Execution cancelled', { executionId: id });\n+            this.events.onCancelled?.(id);\n+        }\n+        this.activeExecutions.clear();\n+    }\n+\n+    /**\n+     * Cancel a specific execution by ID\n+     */\n+    cancel(executionId: string): boolean {\n+        const controller = this.activeExecutions.get(executionId);\n+        if (controller) {\n+            controller.abort();\n+            this.activeExecutions.delete(executionId);\n+            this.logger.info('Execution cancelled', { executionId });\n+            this.events.onCancelled?.(executionId);\n+            return true;\n+        }\n+        return false;\n+    }\n+\n+    /**\n+     * Get active execution count\n+     */\n+    getActiveCount(): number {\n+        return this.activeExecutions.size;\n+    }\n+\n+    /**\n+     * Get list of active execution IDs\n+     */\n+    getActiveExecutionIds(): string[] {\n+        return Array.from(this.activeExecutions.keys());\n+    }\n+\n+    /**\n+     * Check if sandbox is enabled\n+     */\n+    isEnabled(): boolean {\n+        return this.config.enabled && this.config.sandboxExecution;\n+    }\n+\n+    /**\n+     * Get current configuration\n+     */\n+    getConfig(): Readonly<ToolSecurityConfig> {\n+        return { ...this.config };\n+    }\n+\n+    /**\n+     * Update configuration\n+     */\n+    updateConfig(config: Partial<ToolSecurityConfig>): void {\n+        this.config = { ...this.config, ...config };\n+    }\n+\n+    private async executeWithTimeout<T>(\n+        fn: () => Promise<T>,\n+        timeoutMs: number,\n+        signal: AbortSignal,\n+        toolName: string\n+    ): Promise<T> {\n+        return new Promise<T>((resolve, reject) => {\n+            const timeoutId = setTimeout(() => {\n+                this.logger.warn('Tool execution timed out', {\n+                    toolName,\n+                    timeoutMs,\n+                });\n+                this.events.onTimeout?.(toolName, timeoutMs);\n+                reject(\n+                    new Error(`Tool execution timed out after ${timeoutMs}ms`)\n+                );\n+            }, timeoutMs);\n+\n+            const abortHandler = () => {\n+                clearTimeout(timeoutId);\n+                reject(new Error('Tool execution was cancelled'));\n+            };\n+            signal.addEventListener('abort', abortHandler, { once: true });\n+\n+            fn()\n+                .then((result) => {\n+                    clearTimeout(timeoutId);\n+                    signal.removeEventListener('abort', abortHandler);\n+                    resolve(result);\n+                })\n+                .catch((error) => {\n+                    clearTimeout(timeoutId);\n+                    signal.removeEventListener('abort', abortHandler);\n+                    reject(error);\n+                });\n+        });\n+    }\n+\n+    private estimateSize(value: unknown): number {\n+        if (value === null || value === undefined) return 0;\n+        if (typeof value === 'string') return value.length * 2; // UTF-16\n+        if (typeof value === 'number') return 8;\n+        if (typeof value === 'boolean') return 4;\n+        if (Buffer.isBuffer(value)) return value.length;\n+        try {\n+            return JSON.stringify(value).length * 2;\n+        } catch {\n+            return 0;\n+        }\n+    }\n+}\n+\n+/**\n+ * Create a security-wrapped version of a tool\n+ */\n+export function createSecureTool(\n+    tool: Tool,\n+    sandbox: ToolSandbox,\n+    guard: ToolGuard\n+): Tool {\n+    return {\n+        ...tool,\n+        execute: async (params, context) => {\n+            // Check if tool is allowed\n+            if (!guard.isToolAllowed(tool.name)) {\n+                throw new Error(`Tool \"${tool.name}\" is not allowed`);\n+            }\n+\n+            // Validate params if schema exists\n+            if (tool.schema) {\n+                const validation = guard.validateParams(\n+                    tool.name,\n+                    params,\n+                    tool.schema\n+                );\n+                if (!validation.success) {\n+                    throw new Error(`Validation failed: ${validation.error}`);\n+                }\n+                params = validation.data;\n+            }\n+\n+            // Execute in sandbox\n+            return sandbox.execute(tool, params, context || {});\n+        },\n+    };\n+}\n+\n+export default ToolSandbox;\n+\ndiff --git a/src/tools.ts b/src/tools.ts\nindex 7bf98bc..f048d07 100644\n--- a/src/tools.ts\n+++ b/src/tools.ts\n@@ -4,8 +4,10 @@\n  * Manages tool definitions and execution for agentic workflows.\n  */\n \n-import { z } from 'zod';\n+import { z, ZodSchema } from 'zod';\n import { DEFAULT_LOGGER, wrapLogger, type Logger } from './logger';\n+import { ToolGuard } from './tool-guard';\n+import { ToolSandbox } from './tool-sandbox';\n \n // ===== TYPE DEFINITIONS =====\n \n@@ -62,6 +64,8 @@ export interface Tool {\n     category?: string;\n     cost?: ToolCost;\n     examples?: ToolExample[];\n+    /** Optional Zod schema for parameter validation */\n+    schema?: ZodSchema<any>;\n }\n \n /**\n@@ -123,6 +127,7 @@ export interface ToolDefinition {\n     category?: string;\n     cost?: ToolCost;\n     examples?: ToolExample[];\n+    schema?: ZodSchema<any>;\n }\n \n // ===== VALIDATION SCHEMAS =====\n@@ -169,6 +174,8 @@ export class ToolRegistry {\n         string,\n         { calls: number; failures: number; totalDuration: number }\n     >;\n+    private toolGuard?: ToolGuard;\n+    private toolSandbox?: ToolSandbox;\n \n     private constructor(context: ToolContext = {}, logger?: Logger) {\n         this.tools = new Map();\n@@ -186,6 +193,38 @@ export class ToolRegistry {\n         return new ToolRegistry(context, logger);\n     }\n \n+    /**\n+     * Configure security guard for tool execution\n+     */\n+    withSecurity(guard: ToolGuard): this {\n+        this.toolGuard = guard;\n+        this.logger.debug('Security guard configured');\n+        return this;\n+    }\n+\n+    /**\n+     * Get the configured security guard\n+     */\n+    getSecurityGuard(): ToolGuard | undefined {\n+        return this.toolGuard;\n+    }\n+\n+    /**\n+     * Configure sandbox for tool execution\n+     */\n+    withSandbox(sandbox: ToolSandbox): this {\n+        this.toolSandbox = sandbox;\n+        this.logger.debug('Sandbox configured');\n+        return this;\n+    }\n+\n+    /**\n+     * Get the configured sandbox\n+     */\n+    getSandbox(): ToolSandbox | undefined {\n+        return this.toolSandbox;\n+    }\n+\n     /**\n      * Register a single tool\n      */\n@@ -262,6 +301,24 @@ export class ToolRegistry {\n             throw new Error(`Tool \"${name}\" not found`);\n         }\n \n+        // Security check: is tool allowed?\n+        if (this.toolGuard && !this.toolGuard.isToolAllowed(name)) {\n+            throw new Error(`Tool \"${name}\" is not allowed`);\n+        }\n+\n+        // Security check: validate parameters if schema exists\n+        if (this.toolGuard && tool.schema) {\n+            const validation = this.toolGuard.validateParams(\n+                name,\n+                params,\n+                tool.schema\n+            );\n+            if (!validation.success) {\n+                throw new Error(`Tool \"${name}\": ${validation.error}`);\n+            }\n+            params = validation.data;\n+        }\n+\n         this.logger.debug('Executing tool', { name, params });\n \n         const startTime = Date.now();\n@@ -269,7 +326,18 @@ export class ToolRegistry {\n         stats.calls++;\n \n         try {\n-            const result = await tool.execute(params, this.context);\n+            let result;\n+            \n+            // Execute with sandbox if configured\n+            if (this.toolSandbox) {\n+                result = await this.toolSandbox.execute(\n+                    tool,\n+                    params,\n+                    this.context\n+                );\n+            } else {\n+                result = await tool.execute(params, this.context);\n+            }\n \n             const duration = Date.now() - startTime;\n             stats.totalDuration += duration;\n@@ -286,6 +354,23 @@ export class ToolRegistry {\n         }\n     }\n \n+    /**\n+     * Safely parse and execute a tool from JSON arguments\n+     */\n+    async executeFromJSON(name: string, jsonArgs: string): Promise<any> {\n+        if (this.toolGuard) {\n+            const parseResult = this.toolGuard.parseToolArguments(name, jsonArgs);\n+            if (!parseResult.success) {\n+                throw new Error(`Tool \"${name}\": ${parseResult.error}`);\n+            }\n+            return this.execute(name, parseResult.data);\n+        }\n+\n+        // No guard, parse directly\n+        const params = JSON.parse(jsonArgs);\n+        return this.execute(name, params);\n+    }\n+\n     /**\n      * Execute multiple tools in sequence\n      */\n@@ -352,6 +437,7 @@ export class ToolRegistry {\n             category: tool.category,\n             cost: tool.cost,\n             examples: tool.examples,\n+            schema: tool.schema,\n         }));\n     }\n \ndiff --git a/tests/tool-guard.test.ts b/tests/tool-guard.test.ts\nnew file mode 100644\nindex 0000000..c04412d\n--- /dev/null\n+++ b/tests/tool-guard.test.ts\n@@ -0,0 +1,358 @@\n+import { describe, it, expect, beforeEach, vi } from 'vitest';\n+import { z } from 'zod';\n+import { ToolGuard, ToolGuardEvents } from '../src/tool-guard';\n+import { ToolRegistry, Tool } from '../src/tools';\n+\n+describe('ToolGuard', () => {\n+    let guard: ToolGuard;\n+    let events: {\n+        validationFailed: { toolName: string; message: string }[];\n+        executionBlocked: { toolName: string; reason: string }[];\n+        prototypePollution: string[];\n+    };\n+\n+    beforeEach(() => {\n+        events = {\n+            validationFailed: [],\n+            executionBlocked: [],\n+            prototypePollution: [],\n+        };\n+\n+        const eventHandlers: ToolGuardEvents = {\n+            onValidationFailed: (toolName, message) =>\n+                events.validationFailed.push({ toolName, message }),\n+            onExecutionBlocked: (toolName, reason) =>\n+                events.executionBlocked.push({ toolName, reason }),\n+            onPrototypePollution: (toolName) =>\n+                events.prototypePollution.push(toolName),\n+        };\n+\n+        guard = new ToolGuard({}, undefined, eventHandlers);\n+    });\n+\n+    describe('validateParams', () => {\n+        it('should validate params against schema', () => {\n+            const schema = z.object({\n+                path: z.string(),\n+                recursive: z.boolean().optional(),\n+            });\n+\n+            const result = guard.validateParams('read_file', { path: '/test' }, schema);\n+            expect(result.success).toBe(true);\n+            expect(result.data).toEqual({ path: '/test' });\n+        });\n+\n+        it('should reject invalid params', () => {\n+            const schema = z.object({ path: z.string() });\n+\n+            const result = guard.validateParams('read_file', { path: 123 }, schema);\n+            expect(result.success).toBe(false);\n+            expect(result.error).toBe('Parameter validation failed');\n+            expect(result.violations).toBeDefined();\n+            expect(result.violations!.length).toBeGreaterThan(0);\n+        });\n+\n+        it('should call onValidationFailed event', () => {\n+            const schema = z.object({ path: z.string() });\n+\n+            guard.validateParams('read_file', { path: 123 }, schema);\n+\n+            expect(events.validationFailed).toHaveLength(1);\n+            expect(events.validationFailed[0].toolName).toBe('read_file');\n+        });\n+\n+        it('should bypass validation when disabled', () => {\n+            const disabledGuard = new ToolGuard({ validateParams: false });\n+            const schema = z.object({ path: z.string() });\n+\n+            const result = disabledGuard.validateParams(\n+                'read_file',\n+                { path: 123 },\n+                schema\n+            );\n+            expect(result.success).toBe(true);\n+            expect(result.data).toEqual({ path: 123 });\n+        });\n+\n+        it('should bypass validation when guard is disabled', () => {\n+            const disabledGuard = new ToolGuard({ enabled: false });\n+            const schema = z.object({ path: z.string() });\n+\n+            const result = disabledGuard.validateParams(\n+                'read_file',\n+                { path: 123 },\n+                schema\n+            );\n+            expect(result.success).toBe(true);\n+        });\n+\n+        it('should handle complex schemas', () => {\n+            const schema = z.object({\n+                files: z.array(z.string()),\n+                options: z.object({\n+                    recursive: z.boolean(),\n+                    maxDepth: z.number().optional(),\n+                }),\n+            });\n+\n+            const result = guard.validateParams('process_files', {\n+                files: ['a.txt', 'b.txt'],\n+                options: { recursive: true },\n+            }, schema);\n+\n+            expect(result.success).toBe(true);\n+        });\n+    });\n+\n+    describe('parseToolArguments', () => {\n+        it('should parse valid JSON', () => {\n+            const result = guard.parseToolArguments(\n+                'test',\n+                '{\"path\": \"/test\", \"recursive\": true}'\n+            );\n+\n+            expect(result.success).toBe(true);\n+            expect(result.data).toEqual({ path: '/test', recursive: true });\n+        });\n+\n+        it('should reject invalid JSON', () => {\n+            const result = guard.parseToolArguments('test', 'not valid json');\n+\n+            expect(result.success).toBe(false);\n+            expect(result.error).toBe('Invalid JSON in tool arguments');\n+        });\n+\n+        it('should detect prototype pollution - __proto__', () => {\n+            const result = guard.parseToolArguments(\n+                'test',\n+                '{\"__proto__\": {\"polluted\": true}}'\n+            );\n+\n+            expect(result.success).toBe(false);\n+            expect(result.error).toContain('malicious content');\n+            expect(events.prototypePollution).toContain('test');\n+        });\n+\n+        it('should detect prototype pollution - constructor', () => {\n+            const result = guard.parseToolArguments(\n+                'test',\n+                '{\"constructor\": {\"prototype\": {\"polluted\": true}}}'\n+            );\n+\n+            expect(result.success).toBe(false);\n+        });\n+\n+        it('should detect nested prototype pollution', () => {\n+            const result = guard.parseToolArguments(\n+                'test',\n+                '{\"a\": {\"b\": {\"__proto__\": {\"polluted\": true}}}}'\n+            );\n+\n+            expect(result.success).toBe(false);\n+        });\n+\n+        it('should reject non-object JSON', () => {\n+            const result = guard.parseToolArguments('test', '\"just a string\"');\n+            expect(result.success).toBe(false);\n+            expect(result.error).toBe('Tool arguments must be a JSON object');\n+        });\n+\n+        it('should reject array JSON', () => {\n+            const result = guard.parseToolArguments('test', '[1, 2, 3]');\n+            expect(result.success).toBe(false);\n+            expect(result.error).toBe('Tool arguments must be a JSON object');\n+        });\n+\n+        it('should reject null JSON', () => {\n+            const result = guard.parseToolArguments('test', 'null');\n+            expect(result.success).toBe(false);\n+        });\n+\n+        it('should bypass checks when disabled', () => {\n+            const disabledGuard = new ToolGuard({ enabled: false });\n+            const result = disabledGuard.parseToolArguments(\n+                'test',\n+                '{\"__proto__\": {\"polluted\": true}}'\n+            );\n+\n+            expect(result.success).toBe(true);\n+        });\n+    });\n+\n+    describe('isToolAllowed', () => {\n+        it('should allow tools not in deny list', () => {\n+            const guardWithDeny = new ToolGuard({ deniedTools: ['dangerous_tool'] });\n+\n+            expect(guardWithDeny.isToolAllowed('safe_tool')).toBe(true);\n+            expect(guardWithDeny.isToolAllowed('dangerous_tool')).toBe(false);\n+        });\n+\n+        it('should enforce allow list when specified', () => {\n+            const guardWithAllow = new ToolGuard({\n+                allowedTools: ['read_file', 'write_file'],\n+            });\n+\n+            expect(guardWithAllow.isToolAllowed('read_file')).toBe(true);\n+            expect(guardWithAllow.isToolAllowed('delete_file')).toBe(false);\n+        });\n+\n+        it('should call onExecutionBlocked for denied tools', () => {\n+            guard = new ToolGuard(\n+                { deniedTools: ['blocked_tool'] },\n+                undefined,\n+                {\n+                    onExecutionBlocked: (toolName, reason) =>\n+                        events.executionBlocked.push({ toolName, reason }),\n+                }\n+            );\n+\n+            guard.isToolAllowed('blocked_tool');\n+\n+            expect(events.executionBlocked).toHaveLength(1);\n+            expect(events.executionBlocked[0].toolName).toBe('blocked_tool');\n+        });\n+\n+        it('should allow all tools when disabled', () => {\n+            const disabledGuard = new ToolGuard({ enabled: false, deniedTools: ['blocked'] });\n+\n+            expect(disabledGuard.isToolAllowed('blocked')).toBe(true);\n+        });\n+    });\n+\n+    describe('configuration', () => {\n+        it('should return config copy', () => {\n+            const config = guard.getConfig();\n+            expect(config.enabled).toBe(true);\n+            expect(config.validateParams).toBe(true);\n+        });\n+\n+        it('should update config', () => {\n+            guard.updateConfig({ maxExecutionTime: 60000 });\n+            expect(guard.getConfig().maxExecutionTime).toBe(60000);\n+        });\n+\n+        it('should add tool to deny list', () => {\n+            guard.denyTool('new_blocked_tool');\n+            expect(guard.isToolAllowed('new_blocked_tool')).toBe(false);\n+        });\n+\n+        it('should remove tool from deny list', () => {\n+            guard = new ToolGuard({ deniedTools: ['blocked'] });\n+            guard.allowTool('blocked');\n+            expect(guard.isToolAllowed('blocked')).toBe(true);\n+        });\n+\n+        it('should check enabled status', () => {\n+            expect(guard.isEnabled()).toBe(true);\n+            guard.setEnabled(false);\n+            expect(guard.isEnabled()).toBe(false);\n+        });\n+    });\n+});\n+\n+describe('ToolRegistry with ToolGuard', () => {\n+    let registry: ToolRegistry;\n+    let guard: ToolGuard;\n+\n+    const createTestTool = (name: string, schema?: z.ZodSchema<any>): Tool => ({\n+        name,\n+        description: `Test tool ${name}`,\n+        parameters: {\n+            type: 'object',\n+            properties: {\n+                input: { type: 'string', description: 'Input value' },\n+            },\n+        },\n+        execute: async (params) => ({ result: params.input }),\n+        schema,\n+    });\n+\n+    beforeEach(() => {\n+        guard = new ToolGuard({ deniedTools: ['blocked_tool'] });\n+        registry = ToolRegistry.create().withSecurity(guard);\n+    });\n+\n+    it('should configure security guard', () => {\n+        expect(registry.getSecurityGuard()).toBe(guard);\n+    });\n+\n+    it('should block denied tools', async () => {\n+        registry.register(createTestTool('blocked_tool'));\n+\n+        await expect(\n+            registry.execute('blocked_tool', { input: 'test' })\n+        ).rejects.toThrow('Tool \"blocked_tool\" is not allowed');\n+    });\n+\n+    it('should allow non-denied tools', async () => {\n+        registry.register(createTestTool('allowed_tool'));\n+\n+        const result = await registry.execute('allowed_tool', { input: 'test' });\n+        expect(result).toEqual({ result: 'test' });\n+    });\n+\n+    it('should validate params with schema', async () => {\n+        const schema = z.object({ input: z.string() });\n+        registry.register(createTestTool('validated_tool', schema));\n+\n+        // Valid params\n+        const result = await registry.execute('validated_tool', { input: 'test' });\n+        expect(result).toEqual({ result: 'test' });\n+\n+        // Invalid params\n+        await expect(\n+            registry.execute('validated_tool', { input: 123 })\n+        ).rejects.toThrow('Parameter validation failed');\n+    });\n+\n+    it('should work without guard', async () => {\n+        const noGuardRegistry = ToolRegistry.create();\n+        noGuardRegistry.register(createTestTool('test_tool'));\n+\n+        const result = await noGuardRegistry.execute('test_tool', { input: 'test' });\n+        expect(result).toEqual({ result: 'test' });\n+    });\n+\n+    describe('executeFromJSON', () => {\n+        it('should parse and execute from JSON', async () => {\n+            registry.register(createTestTool('json_tool'));\n+\n+            const result = await registry.executeFromJSON(\n+                'json_tool',\n+                '{\"input\": \"test\"}'\n+            );\n+            expect(result).toEqual({ result: 'test' });\n+        });\n+\n+        it('should reject malicious JSON', async () => {\n+            registry.register(createTestTool('json_tool'));\n+\n+            await expect(\n+                registry.executeFromJSON(\n+                    'json_tool',\n+                    '{\"__proto__\": {\"polluted\": true}}'\n+                )\n+            ).rejects.toThrow('malicious content');\n+        });\n+\n+        it('should reject invalid JSON', async () => {\n+            registry.register(createTestTool('json_tool'));\n+\n+            await expect(\n+                registry.executeFromJSON('json_tool', 'not json')\n+            ).rejects.toThrow('Invalid JSON');\n+        });\n+\n+        it('should work without guard', async () => {\n+            const noGuardRegistry = ToolRegistry.create();\n+            noGuardRegistry.register(createTestTool('json_tool'));\n+\n+            const result = await noGuardRegistry.executeFromJSON(\n+                'json_tool',\n+                '{\"input\": \"test\"}'\n+            );\n+            expect(result).toEqual({ result: 'test' });\n+        });\n+    });\n+});\n+\ndiff --git a/tests/tool-sandbox.test.ts b/tests/tool-sandbox.test.ts\nnew file mode 100644\nindex 0000000..ab1c50e\n--- /dev/null\n+++ b/tests/tool-sandbox.test.ts\n@@ -0,0 +1,478 @@\n+import { describe, it, expect, beforeEach, vi } from 'vitest';\n+import { z } from 'zod';\n+import {\n+    ToolSandbox,\n+    ToolSandboxEvents,\n+    createSecureTool,\n+} from '../src/tool-sandbox';\n+import { ToolGuard } from '../src/tool-guard';\n+import { ToolRegistry, Tool } from '../src/tools';\n+\n+describe('ToolSandbox', () => {\n+    let sandbox: ToolSandbox;\n+    let events: {\n+        concurrencyExceeded: { toolName: string; activeCount: number }[];\n+        timeout: { toolName: string; timeoutMs: number }[];\n+        outputSizeExceeded: { toolName: string; size: number; maxSize: number }[];\n+        cancelled: string[];\n+    };\n+\n+    const createTestTool = (\n+        name: string,\n+        executeFn?: (params: any, context?: any) => Promise<any>\n+    ): Tool => ({\n+        name,\n+        description: `Test tool ${name}`,\n+        parameters: {\n+            type: 'object',\n+            properties: {\n+                input: { type: 'string', description: 'Input value' },\n+            },\n+        },\n+        execute: executeFn || (async (params) => ({ result: params.input })),\n+    });\n+\n+    beforeEach(() => {\n+        events = {\n+            concurrencyExceeded: [],\n+            timeout: [],\n+            outputSizeExceeded: [],\n+            cancelled: [],\n+        };\n+\n+        const eventHandlers: ToolSandboxEvents = {\n+            onConcurrencyExceeded: (toolName, activeCount) =>\n+                events.concurrencyExceeded.push({ toolName, activeCount }),\n+            onTimeout: (toolName, timeoutMs) =>\n+                events.timeout.push({ toolName, timeoutMs }),\n+            onOutputSizeExceeded: (toolName, size, maxSize) =>\n+                events.outputSizeExceeded.push({ toolName, size, maxSize }),\n+            onCancelled: (executionId) => events.cancelled.push(executionId),\n+        };\n+\n+        sandbox = new ToolSandbox({}, undefined, eventHandlers);\n+    });\n+\n+    describe('basic execution', () => {\n+        it('should execute a tool successfully', async () => {\n+            const tool = createTestTool('test_tool');\n+            const result = await sandbox.execute(tool, { input: 'hello' }, {});\n+            expect(result).toEqual({ result: 'hello' });\n+        });\n+\n+        it('should pass context to tool', async () => {\n+            const tool = createTestTool('context_tool', async (params, context) => ({\n+                input: params.input,\n+                workingDir: context?.workingDirectory,\n+            }));\n+\n+            const result = await sandbox.execute(\n+                tool,\n+                { input: 'test' },\n+                { workingDirectory: '/test' }\n+            );\n+\n+            expect(result.workingDir).toBe('/test');\n+        });\n+\n+        it('should provide sandbox context', async () => {\n+            const tool = createTestTool('sandbox_tool', async (params, context) => ({\n+                hasSandbox: !!context?.sandbox,\n+                executionId: context?.sandbox?.executionId,\n+            }));\n+\n+            const result = await sandbox.execute(tool, {}, {});\n+\n+            expect(result.hasSandbox).toBe(true);\n+            expect(result.executionId).toMatch(/^exec-\\d+-\\d+$/);\n+        });\n+\n+        it('should bypass sandbox when disabled', async () => {\n+            const disabledSandbox = new ToolSandbox({ sandboxExecution: false });\n+            const tool = createTestTool('test_tool', async (params, context) => ({\n+                hasSandbox: !!context?.sandbox,\n+            }));\n+\n+            const result = await disabledSandbox.execute(tool, {}, {});\n+            expect(result.hasSandbox).toBe(false);\n+        });\n+    });\n+\n+    describe('timeout enforcement', () => {\n+        it('should timeout long-running tools', async () => {\n+            const timeoutSandbox = new ToolSandbox(\n+                { maxExecutionTime: 100 },\n+                undefined,\n+                {\n+                    onTimeout: (toolName, timeoutMs) =>\n+                        events.timeout.push({ toolName, timeoutMs }),\n+                }\n+            );\n+\n+            const slowTool = createTestTool(\n+                'slow_tool',\n+                async () => new Promise((r) => setTimeout(r, 5000))\n+            );\n+\n+            await expect(\n+                timeoutSandbox.execute(slowTool, {}, {})\n+            ).rejects.toThrow('timed out');\n+\n+            expect(events.timeout).toHaveLength(1);\n+            expect(events.timeout[0].toolName).toBe('slow_tool');\n+        });\n+\n+        it('should allow custom timeout per execution', async () => {\n+            const tool = createTestTool(\n+                'slow_tool',\n+                async () => new Promise((r) => setTimeout(r, 200))\n+            );\n+\n+            // Should succeed with longer timeout\n+            const result = await sandbox.execute(tool, {}, {}, {\n+                maxExecutionTime: 500,\n+            });\n+            expect(result).toBeUndefined(); // setTimeout resolves with undefined\n+        });\n+    });\n+\n+    describe('concurrency limits', () => {\n+        it('should limit concurrent executions', async () => {\n+            const limitedSandbox = new ToolSandbox(\n+                { maxConcurrentCalls: 2 },\n+                undefined,\n+                {\n+                    onConcurrencyExceeded: (toolName, activeCount) =>\n+                        events.concurrencyExceeded.push({ toolName, activeCount }),\n+                }\n+            );\n+\n+            const slowTool = createTestTool(\n+                'slow_tool',\n+                async () => new Promise((r) => setTimeout(r, 500))\n+            );\n+\n+            // Start two executions\n+            const p1 = limitedSandbox.execute(slowTool, {}, {});\n+            const p2 = limitedSandbox.execute(slowTool, {}, {});\n+\n+            // Third should fail\n+            await expect(\n+                limitedSandbox.execute(slowTool, {}, {})\n+            ).rejects.toThrow('Too many concurrent');\n+\n+            expect(events.concurrencyExceeded).toHaveLength(1);\n+\n+            // Wait for others to complete\n+            await Promise.all([p1, p2]);\n+        });\n+\n+        it('should track active execution count', async () => {\n+            const slowTool = createTestTool(\n+                'slow_tool',\n+                async () => new Promise((r) => setTimeout(r, 100))\n+            );\n+\n+            expect(sandbox.getActiveCount()).toBe(0);\n+\n+            const p = sandbox.execute(slowTool, {}, {});\n+            expect(sandbox.getActiveCount()).toBe(1);\n+\n+            await p;\n+            expect(sandbox.getActiveCount()).toBe(0);\n+        });\n+    });\n+\n+    describe('output size limits', () => {\n+        it('should reject oversized output', async () => {\n+            const largeTool = createTestTool('large_tool', async () => ({\n+                data: 'x'.repeat(1024 * 1024 * 2), // 2MB string\n+            }));\n+\n+            await expect(\n+                sandbox.execute(largeTool, {}, {}, { maxOutputSize: 1024 * 100 })\n+            ).rejects.toThrow('exceeded maximum size');\n+\n+            expect(events.outputSizeExceeded).toHaveLength(1);\n+        });\n+\n+        it('should allow output within limits', async () => {\n+            const smallTool = createTestTool('small_tool', async () => ({\n+                data: 'small output',\n+            }));\n+\n+            const result = await sandbox.execute(smallTool, {}, {});\n+            expect(result.data).toBe('small output');\n+        });\n+    });\n+\n+    describe('execution hooks', () => {\n+        it('should call onBeforeExecution', async () => {\n+            const beforeCalls: { tool: string; params: any }[] = [];\n+            const tool = createTestTool('test_tool');\n+\n+            await sandbox.execute(tool, { input: 'test' }, {}, {\n+                onBeforeExecution: async (t, params) => {\n+                    beforeCalls.push({ tool: t.name, params });\n+                },\n+            });\n+\n+            expect(beforeCalls).toHaveLength(1);\n+            expect(beforeCalls[0].tool).toBe('test_tool');\n+        });\n+\n+        it('should call onAfterExecution on success', async () => {\n+            const afterCalls: { tool: string; result: any; error?: Error }[] = [];\n+            const tool = createTestTool('test_tool');\n+\n+            await sandbox.execute(tool, { input: 'test' }, {}, {\n+                onAfterExecution: async (t, result, error) => {\n+                    afterCalls.push({ tool: t.name, result, error });\n+                },\n+            });\n+\n+            expect(afterCalls).toHaveLength(1);\n+            expect(afterCalls[0].result).toEqual({ result: 'test' });\n+            expect(afterCalls[0].error).toBeUndefined();\n+        });\n+\n+        it('should call onAfterExecution on error', async () => {\n+            const afterCalls: { tool: string; result: any; error?: Error }[] = [];\n+            const failingTool = createTestTool('failing_tool', async () => {\n+                throw new Error('Tool failed');\n+            });\n+\n+            await expect(\n+                sandbox.execute(failingTool, {}, {}, {\n+                    onAfterExecution: async (t, result, error) => {\n+                        afterCalls.push({ tool: t.name, result, error });\n+                    },\n+                })\n+            ).rejects.toThrow('Tool failed');\n+\n+            expect(afterCalls).toHaveLength(1);\n+            expect(afterCalls[0].error?.message).toBe('Tool failed');\n+        });\n+    });\n+\n+    describe('cancellation', () => {\n+        it('should track active execution IDs', async () => {\n+            const tool = createTestTool('fast_tool');\n+            \n+            // Before execution\n+            expect(sandbox.getActiveExecutionIds()).toHaveLength(0);\n+            \n+            // During execution (use a slightly slow tool)\n+            const slowTool = createTestTool(\n+                'slow_tool',\n+                async () => {\n+                    await new Promise((r) => setTimeout(r, 50));\n+                    return { done: true };\n+                }\n+            );\n+            \n+            const p = sandbox.execute(slowTool, {}, {});\n+            expect(sandbox.getActiveExecutionIds()).toHaveLength(1);\n+            expect(sandbox.getActiveExecutionIds()[0]).toMatch(/^exec-\\d+-\\d+$/);\n+            \n+            await p;\n+            expect(sandbox.getActiveExecutionIds()).toHaveLength(0);\n+        });\n+\n+        it('should clear active executions on cancelAll', async () => {\n+            const slowTool = createTestTool(\n+                'slow_tool',\n+                async () => new Promise((r) => setTimeout(r, 100))\n+            );\n+\n+            // Start execution\n+            sandbox.execute(slowTool, {}, {}).catch(() => {}); // Ignore rejection\n+            sandbox.execute(slowTool, {}, {}).catch(() => {}); // Ignore rejection\n+\n+            expect(sandbox.getActiveCount()).toBe(2);\n+\n+            // Cancel all\n+            sandbox.cancelAll();\n+\n+            // Active count should be 0 immediately after cancelAll\n+            expect(sandbox.getActiveCount()).toBe(0);\n+            expect(events.cancelled).toHaveLength(2);\n+        });\n+\n+        it('should cancel specific execution by ID', async () => {\n+            const slowTool = createTestTool(\n+                'slow_tool',\n+                async () => new Promise((r) => setTimeout(r, 100))\n+            );\n+\n+            // Start execution\n+            sandbox.execute(slowTool, {}, {}).catch(() => {}); // Ignore rejection\n+            const ids = sandbox.getActiveExecutionIds();\n+\n+            expect(ids).toHaveLength(1);\n+\n+            // Cancel specific\n+            const cancelled = sandbox.cancel(ids[0]);\n+            expect(cancelled).toBe(true);\n+            expect(sandbox.getActiveCount()).toBe(0);\n+            expect(events.cancelled).toContain(ids[0]);\n+        });\n+\n+        it('should return false when cancelling non-existent execution', () => {\n+            const cancelled = sandbox.cancel('non-existent-id');\n+            expect(cancelled).toBe(false);\n+        });\n+    });\n+\n+    describe('configuration', () => {\n+        it('should check enabled status', () => {\n+            expect(sandbox.isEnabled()).toBe(true);\n+\n+            const disabledSandbox = new ToolSandbox({\n+                enabled: false,\n+                sandboxExecution: true,\n+            });\n+            expect(disabledSandbox.isEnabled()).toBe(false);\n+        });\n+\n+        it('should return config copy', () => {\n+            const config = sandbox.getConfig();\n+            expect(config.maxExecutionTime).toBe(30000);\n+            expect(config.maxConcurrentCalls).toBe(10);\n+        });\n+\n+        it('should update config', () => {\n+            sandbox.updateConfig({ maxExecutionTime: 60000 });\n+            expect(sandbox.getConfig().maxExecutionTime).toBe(60000);\n+        });\n+    });\n+});\n+\n+describe('createSecureTool', () => {\n+    it('should wrap tool with security checks', async () => {\n+        const guard = new ToolGuard({ deniedTools: ['blocked'] });\n+        const sandbox = new ToolSandbox();\n+\n+        const tool: Tool = {\n+            name: 'test_tool',\n+            description: 'Test',\n+            parameters: { type: 'object', properties: {} },\n+            execute: async () => ({ success: true }),\n+        };\n+\n+        const secureTool = createSecureTool(tool, sandbox, guard);\n+\n+        const result = await secureTool.execute({}, {});\n+        expect(result).toEqual({ success: true });\n+    });\n+\n+    it('should block denied tools', async () => {\n+        const guard = new ToolGuard({ deniedTools: ['blocked_tool'] });\n+        const sandbox = new ToolSandbox();\n+\n+        const tool: Tool = {\n+            name: 'blocked_tool',\n+            description: 'Blocked',\n+            parameters: { type: 'object', properties: {} },\n+            execute: async () => ({ success: true }),\n+        };\n+\n+        const secureTool = createSecureTool(tool, sandbox, guard);\n+\n+        await expect(secureTool.execute({}, {})).rejects.toThrow('not allowed');\n+    });\n+\n+    it('should validate params with schema', async () => {\n+        const guard = new ToolGuard();\n+        const sandbox = new ToolSandbox();\n+\n+        const tool: Tool = {\n+            name: 'validated_tool',\n+            description: 'Validated',\n+            parameters: { type: 'object', properties: {} },\n+            execute: async (params) => ({ input: params.input }),\n+            schema: z.object({ input: z.string() }),\n+        };\n+\n+        const secureTool = createSecureTool(tool, sandbox, guard);\n+\n+        // Valid params\n+        const result = await secureTool.execute({ input: 'test' }, {});\n+        expect(result.input).toBe('test');\n+\n+        // Invalid params\n+        await expect(\n+            secureTool.execute({ input: 123 }, {})\n+        ).rejects.toThrow('Validation failed');\n+    });\n+});\n+\n+describe('ToolRegistry with ToolSandbox', () => {\n+    it('should configure sandbox', () => {\n+        const sandbox = new ToolSandbox();\n+        const registry = ToolRegistry.create().withSandbox(sandbox);\n+\n+        expect(registry.getSandbox()).toBe(sandbox);\n+    });\n+\n+    it('should execute tools through sandbox', async () => {\n+        const sandbox = new ToolSandbox();\n+        const registry = ToolRegistry.create().withSandbox(sandbox);\n+\n+        const tool: Tool = {\n+            name: 'sandboxed_tool',\n+            description: 'Test',\n+            parameters: { type: 'object', properties: {} },\n+            execute: async (params, context) => ({\n+                hasSandbox: !!context?.sandbox,\n+            }),\n+        };\n+\n+        registry.register(tool);\n+\n+        const result = await registry.execute('sandboxed_tool', {});\n+        expect(result.hasSandbox).toBe(true);\n+    });\n+\n+    it('should enforce sandbox timeout', async () => {\n+        const sandbox = new ToolSandbox({ maxExecutionTime: 100 });\n+        const registry = ToolRegistry.create().withSandbox(sandbox);\n+\n+        const slowTool: Tool = {\n+            name: 'slow_tool',\n+            description: 'Slow',\n+            parameters: { type: 'object', properties: {} },\n+            execute: async () => new Promise((r) => setTimeout(r, 5000)),\n+        };\n+\n+        registry.register(slowTool);\n+\n+        await expect(registry.execute('slow_tool', {})).rejects.toThrow(\n+            'timed out'\n+        );\n+    });\n+\n+    it('should work with both guard and sandbox', async () => {\n+        const guard = new ToolGuard({ deniedTools: ['blocked'] });\n+        const sandbox = new ToolSandbox();\n+        const registry = ToolRegistry.create()\n+            .withSecurity(guard)\n+            .withSandbox(sandbox);\n+\n+        const tool: Tool = {\n+            name: 'secure_tool',\n+            description: 'Secure',\n+            parameters: { type: 'object', properties: {} },\n+            execute: async (params, context) => ({\n+                hasSandbox: !!context?.sandbox,\n+            }),\n+            schema: z.object({ input: z.string().optional() }),\n+        };\n+\n+        registry.register(tool);\n+\n+        const result = await registry.execute('secure_tool', {});\n+        expect(result.hasSandbox).toBe(true);\n+    });\n+});\n+\ndiff --git a/vite.config.ts b/vite.config.ts\nindex f9a5289..4548d8f 100644\n--- a/vite.config.ts\n+++ b/vite.config.ts\n@@ -2,18 +2,18 @@ import { defineConfig } from \"vite\";\n import dts from \"vite-plugin-dts\";\n \n export default defineConfig({\n-  build: {\n-    lib: {\n-      entry: \"src/index.ts\",\n-      name: \"agentic\",\n-      fileName: () => \"index.js\",\n-      formats: [\"es\"],\n+    build: {\n+        lib: {\n+            entry: \"src/index.ts\",\n+            name: \"agentic\",\n+            fileName: () => \"index.js\",\n+            formats: [\"es\"],\n+        },\n+        rollupOptions: {\n+            external: [\"zod\", \"execution\"],\n+        },\n+        sourcemap: true,\n+        minify: false,\n     },\n-    rollupOptions: {\n-      external: [\"zod\", \"execution\"],\n-    },\n-    sourcemap: true,\n-    minify: false,\n-  },\n-  plugins: [dts({ rollupTypes: true })],\n+    plugins: [dts({ rollupTypes: true })],\n });\ndiff --git a/vitest.config.ts b/vitest.config.ts\nindex c48ee66..101993b 100644\n--- a/vitest.config.ts\n+++ b/vitest.config.ts\n@@ -1,22 +1,22 @@\n import { defineConfig } from \"vitest/config\";\n \n export default defineConfig({\n-  test: {\n-    include: [\"tests/**/*.test.ts\"],\n-    globals: true,\n-    coverage: {\n-      provider: \"v8\",\n-      reporter: [\"text\", \"json\", \"html\"],\n-      include: [\"src/**/*.ts\"],\n-      exclude: [\n-        \"src/**/*.test.ts\",\n-        \"node_modules/\",\n-        \"dist/**\",\n-        \"vitest.config.ts\",\n-        \"vite.config.ts\",\n-        \"eslint.config.mjs\",\n-      ],\n+    test: {\n+        include: [\"tests/**/*.test.ts\"],\n+        globals: true,\n+        coverage: {\n+            provider: \"v8\",\n+            reporter: [\"text\", \"json\", \"html\"],\n+            include: [\"src/**/*.ts\"],\n+            exclude: [\n+                \"src/**/*.test.ts\",\n+                \"node_modules/\",\n+                \"dist/**\",\n+                \"vitest.config.ts\",\n+                \"vite.config.ts\",\n+                \"eslint.config.mjs\",\n+            ],\n+        },\n     },\n-  },\n });\n \n\n\nUser direction: --model\n\nRecent commit history for context:\ncommit ea597566aac59c252fdfa9505dbf880ee7b19e0d\nAuthor: Tim O'Brien <tobrien@discursive.com>\nDate:   Tue Jan 13 00:19:39 2026 -0800\n\n    chore: bump to 0.0.5-dev.0\n\ncommit 65fae30192c12c15269730a8d413e379f440607f\nAuthor: Tim O'Brien <tobrien@discursive.com>\nDate:   Tue Jan 13 00:18:46 2026 -0800\n\n    chore(release): bump version to 0.0.5 (#8)\n    \n    * chore: bump to v0.0.5-dev.0\n    \n    * chore(build): ship ESM-only bundle and target Node 24 / ES2024\n    \n    * chore(release): bump version to 0.0.5\n\ncommit 48006d517f8c6f86fc4f7d92806ed7234f025504\nAuthor: Tim O'Brien <tobrien@discursive.com>\nDate:   Mon Jan 12 21:56:42 2026 -0800\n\n    chore(release): bump version to 0.0.4 (#7)\n    \n    * 0.0.4-dev.0\n    \n    * chore(ci): bump GitHub Actions Node version to 24 and use npm install\n    \n    * chore(release): bump version to 0.0.4\n\n\n## Your Analysis Task\n\nWith 12 files changed, consider whether these represent multiple distinct changes that should be split into separate commits.\n\nGather signals to understand the changes:\n1. Use `get_file_modification_times` to see when files were modified relative to each other\n2. Use `group_files_by_concern` to understand how files relate by type/purpose\n3. Cross-reference both signals - temporal proximity and logical relatedness - to determine the best commit structure\n\nConsider:\n- What distinct features, fixes, or improvements are included?\n- Are files that were modified together also logically related?\n- Would separate commits make the history more understandable?\n\nWith many files, consider whether multiple focused commits would be clearer than one large commit.\n\nIf context information is provided, use it only if relevant to these specific changes.\nDon't force connections that don't exist - focus on what actually changed."
+  },
+  {
+    "role": "assistant",
+    "content": null,
+    "tool_calls": [
+      {
+        "id": "call_6QjVX0tqTbpnsf6DbuIt7ORr",
+        "type": "function",
+        "function": {
+          "name": "get_file_modification_times",
+          "arguments": "{\"filePaths\": [\"SECURITY.md\", \"package.json\", \"src/context-manager.ts\", \"src/index.ts\", \"src/logger.ts\", \"src/tool-guard.ts\", \"src/tool-sandbox.ts\", \"src/tools.ts\", \"tests/tool-guard.test.ts\", \"tests/tool-sandbox.test.ts\", \"vite.config.ts\", \"vitest.config.ts\"]}"
+        }
+      },
+      {
+        "id": "call_zneMlje1opMU19dKTCAKkNre",
+        "type": "function",
+        "function": {
+          "name": "group_files_by_concern",
+          "arguments": "{\"filePaths\": [\"SECURITY.md\", \"package.json\", \"src/context-manager.ts\", \"src/index.ts\", \"src/logger.ts\", \"src/tool-guard.ts\", \"src/tool-sandbox.ts\", \"src/tools.ts\", \"tests/tool-guard.test.ts\", \"tests/tool-sandbox.test.ts\", \"vite.config.ts\", \"vitest.config.ts\"]}"
+        }
+      },
+      {
+        "id": "call_m6g335r1N15cKpXHgcNNhFCn",
+        "type": "function",
+        "function": {
+          "name": "get_recent_commits",
+          "arguments": "{\"filePaths\": [\"src/logger.ts\", \"src/tools.ts\", \"src/index.ts\"], \"since\": \"2 weeks ago\", \"limit\": 5}"
+        }
+      }
+    ]
+  },
+  {
+    "role": "tool",
+    "tool_call_id": "call_6QjVX0tqTbpnsf6DbuIt7ORr",
+    "content": "## File Modification Times (sorted oldest to newest)\n\n2026-01-14 05:44:54  package.json\n2026-01-14 05:50:01  vite.config.ts\n2026-01-14 05:50:01  vitest.config.ts\n2026-01-14 06:04:33  src/tool-guard.ts\n2026-01-14 06:04:33  src/index.ts\n2026-01-14 06:04:33  src/tools.ts\n2026-01-14 06:04:33  tests/tool-guard.test.ts\n2026-01-14 06:04:33  src/tool-sandbox.ts\n2026-01-14 06:04:33  tests/tool-sandbox.test.ts\n2026-01-14 06:29:13  src/context-manager.ts\n2026-01-14 06:29:13  SECURITY.md\n2026-01-14 06:29:13  src/logger.ts\n\n\n## Temporal Clusters (files modified within 10 minutes of each other)\n\nFound 3 distinct work sessions:\n\n### Session 1 (3 files, 5 min span)\nTime: 2026-01-14 05:44:54 to 2026-01-14 05:50:01\nFiles:\n  - package.json\n  - vite.config.ts\n  - vitest.config.ts\n\n### Session 2 (6 files, 0 min span)\nTime: 2026-01-14 06:04:33 to 2026-01-14 06:04:33\nFiles:\n  - src/tool-guard.ts\n  - src/index.ts\n  - src/tools.ts\n  - tests/tool-guard.test.ts\n  - src/tool-sandbox.ts\n  - tests/tool-sandbox.test.ts\n\n### Session 3 (3 files, 0 min span)\nTime: 2026-01-14 06:29:13 to 2026-01-14 06:29:13\nFiles:\n  - src/context-manager.ts\n  - SECURITY.md\n  - src/logger.ts\n\n\n**Note**: These 3 temporal clusters may indicate separate work sessions. Cross-reference with logical groupings to determine if they represent distinct changes worth splitting.",
+    "name": "get_file_modification_times"
+  },
+  {
+    "role": "tool",
+    "tool_call_id": "call_zneMlje1opMU19dKTCAKkNre",
+    "content": "documentation (1 files):\n  - SECURITY.md\n\ndependencies (1 files):\n  - package.json\n\nsource:src (6 files):\n  - src/context-manager.ts\n  - src/index.ts\n  - src/logger.ts\n  - src/tool-guard.ts\n  - src/tool-sandbox.ts\n  - src/tools.ts\n\ntests (2 files):\n  - tests/tool-guard.test.ts\n  - tests/tool-sandbox.test.ts\n\nother (2 files):\n  - vite.config.ts\n  - vitest.config.ts\n\nSuggestion: These 5 groups might be better as separate commits if they represent different concerns.",
+    "name": "group_files_by_concern"
+  },
+  {
+    "role": "tool",
+    "tool_call_id": "call_m6g335r1N15cKpXHgcNNhFCn",
+    "content": "c679b20 - Initial commit (Tim O'Brien, 4 days ago)\n",
+    "name": "get_recent_commits"
+  },
+  {
+    "role": "assistant",
+    "content": "COMMIT_MESSAGE:\nfeat(security): add ToolGuard/ToolSandbox and secure ToolRegistry execution\n\n- Add ToolGuard for schema-based param validation, allow/deny lists, and prototype-pollution-safe JSON parsing\n- Add ToolSandbox for timeouts, concurrency limits, output size limits, cancellation, and execution hooks\n- Extend ToolRegistry with optional per-tool `schema`, `executeFromJSON()`, and guard/sandbox integration\n- Export new security APIs from `src/index.ts`\n- Add Vitest coverage for ToolGuard, ToolSandbox, and ToolRegistry integration\n\nSUGGESTED_SPLITS:\nSplit 1:\nFiles: [src/tool-guard.ts, src/tool-sandbox.ts, src/tools.ts, src/index.ts, tests/tool-guard.test.ts, tests/tool-sandbox.test.ts]\nRationale: Single cohesive feature: tool execution hardening (validation + sandboxing) plus ToolRegistry integration and tests. These files were also modified in the same temporal cluster.\nMessage: feat(security): add ToolGuard/ToolSandbox and secure ToolRegistry execution\n\nSplit 2:\nFiles: [src/logger.ts, package.json]\nRationale: Logger implementation change + new dependency (@fjell/logging). Logically separable from tool security behavior, and modified in a later work session.\nMessage: refactor(logger): use @fjell/logging and default to silent output unless enabled\n\nSplit 3:\nFiles: [SECURITY.md]\nRationale: Documentation-only addition describing security posture and usage; best reviewed separately. Modified alongside logger/context tweaks but stands on its own.\nMessage: docs(security): add SECURITY.md with tool execution hardening guidance\n\nSplit 4:\nFiles: [src/context-manager.ts]\nRationale: Small, isolated behavior change (hash prefix length) unrelated to tool security and logging. Modified in a later session.\nMessage: fix(context-manager): increase content hash prefix to 32 hex chars\n\nSplit 5:\nFiles: [vite.config.ts, vitest.config.ts]\nRationale: Formatting/indentation-only config changes; no functional changes apparent. Keep separate to avoid noise in feature/fix reviews.\nMessage: chore(config): reformat Vite/Vitest config files"
+  }
+]
+```
+
+</details>
+
+## Generated Commit Message
+
+```
+feat(security): add ToolGuard/ToolSandbox and secure ToolRegistry execution
+
+- Add ToolGuard for schema-based param validation, allow/deny lists, and prototype-pollution-safe JSON parsing
+- Add ToolSandbox for timeouts, concurrency limits, output size limits, cancellation, and execution hooks
+- Extend ToolRegistry with optional per-tool `schema`, `executeFromJSON()`, and guard/sandbox integration
+- Export new security APIs from `src/index.ts`
+- Add Vitest coverage for ToolGuard, ToolSandbox, and ToolRegistry integration
+```
+
+## Suggested Commit Splits
+
+### Split 1
+
+**Files**: src/tool-guard.ts, src/tool-sandbox.ts, src/tools.ts, src/index.ts, tests/tool-guard.test.ts, tests/tool-sandbox.test.ts
+
+**Rationale**: Single cohesive feature: tool execution hardening (validation + sandboxing) plus ToolRegistry integration and tests. These files were also modified in the same temporal cluster.
+
+**Message**:
+```
+feat(security): add ToolGuard/ToolSandbox and secure ToolRegistry execution
+```
+
+### Split 2
+
+**Files**: src/logger.ts, package.json
+
+**Rationale**: Logger implementation change + new dependency (@fjell/logging). Logically separable from tool security behavior, and modified in a later work session.
+
+**Message**:
+```
+refactor(logger): use @fjell/logging and default to silent output unless enabled
+```
+
+### Split 3
+
+**Files**: SECURITY.md
+
+**Rationale**: Documentation-only addition describing security posture and usage; best reviewed separately. Modified alongside logger/context tweaks but stands on its own.
+
+**Message**:
+```
+docs(security): add SECURITY.md with tool execution hardening guidance
+```
+
+### Split 4
+
+**Files**: src/context-manager.ts
+
+**Rationale**: Small, isolated behavior change (hash prefix length) unrelated to tool security and logging. Modified in a later session.
+
+**Message**:
+```
+fix(context-manager): increase content hash prefix to 32 hex chars
+```
+
+### Split 5
+
+**Files**: vite.config.ts, vitest.config.ts
+
+**Rationale**: Formatting/indentation-only config changes; no functional changes apparent. Keep separate to avoid noise in feature/fix reviews.
+
+**Message**:
+```
+chore(config): reformat Vite/Vitest config files
+```

package/output/kodrdriv/agentic-reflection-commit-2026-01-15T14-16-05-605Z.md

@@ -0,0 +1,100 @@
+# Agentic Workflow - Self-Reflection Report
+
+Generated: 2026-01-15T14:16:05.605Z
+
+## Execution Summary
+
+- **Iterations**: 2
+- **Tool Calls**: 2
+- **Unique Tools**: 2
+
+## Tool Effectiveness Analysis
+
+| Tool | Calls | Success | Failures | Success Rate | Avg Duration |
+|------|-------|---------|----------|--------------|--------------|
+| get_file_modification_times | 1 | 1 | 0 | 100.0% | 1ms |
+| group_files_by_concern | 1 | 1 | 0 | 100.0% | 1ms |
+
+### Tool Performance Insights
+
+**Most Frequently Used:**
+- get_file_modification_times: 1 calls
+- group_files_by_concern: 1 calls
+
+## Recommendations for Improvement
+
+*No specific recommendations at this time. Execution appears optimal.*
+
+## Detailed Execution Timeline
+
+| Time | Iteration | Tool | Result | Duration |
+|------|-----------|------|--------|----------|
+| 6:16:00 AM | 1 | get_file_modification_times | ✅ Success | 1ms |
+| 6:16:00 AM | 1 | group_files_by_concern | ✅ Success | 1ms |
+
+## Conversation History
+
+<details>
+<summary>Click to expand full agentic interaction</summary>
+
+```json
+[
+  {
+    "role": "system",
+    "content": "You are a professional software engineer writing commit messages for your team.\n\n## Available Tools\n\n### Understanding\n\n**get_file_history** _(cheap)_\nGet git commit history for one or more files to understand their evolution and past changes\n\nParameters:\n- `filePaths` (required): Array of file paths to get history for\n- `limit`: Maximum number of commits to return (default: 10)\n- `format`: Output format: \"summary\" for brief or \"detailed\" for full messages\n\n**When to use:** Get git commit history for one or more files to understand their evolution and past changes\n\n**Examples:**\n- Check if file has recent refactoring: `get_file_history({\"filePaths\":[\"src/auth.ts\"],\"limit\":5})`\n- Understand evolution of multiple related files: `get_file_history({\"filePaths\":[\"src/user.ts\",\"src/auth.ts\"],\"limit\":10,\"format\":\"detailed\"})`\n\n---\n\n**get_file_content** _(moderate)_\nGet the complete current content of a file to understand context around changes. Returns a message if the file does not exist (e.g., if it was deleted).\n\nParameters:\n- `filePath` (required): Path to the file\n- `includeLineNumbers`: Include line numbers in output (default: false)\n\n**When to use:** Get the complete current content of a file to understand context around changes. Returns a message if the file does not exist (e.g., if it was deleted).\n\n**Examples:**\n- See full class definition for modified method: `get_file_content({\"filePath\":\"src/services/auth.ts\",\"includeLineNumbers\":true})`\n- Check imports and structure: `get_file_content({\"filePath\":\"src/utils/helpers.ts\"})`\n\n---\n\n**get_related_tests** _(cheap)_\nFind test files related to production files to understand what the code is supposed to do\n\nParameters:\n- `filePaths` (required): Production file paths\n\n**When to use:** Find test files related to production files to understand what the code is supposed to do\n\n**Examples:**\n- Find tests for modified service: `get_related_tests({\"filePaths\":[\"src/services/auth.ts\"]})`\n\n---\n\n**analyze_diff_section** _(cheap)_\nGet expanded context around specific lines in a file to better understand changes\n\nParameters:\n- `filePath` (required): File containing the section to analyze\n- `startLine` (required): Starting line number\n- `endLine` (required): Ending line number\n- `contextLines`: Number of additional context lines to show before and after (default: 10)\n\n**When to use:** Get expanded context around specific lines in a file to better understand changes\n\n**Examples:**\n- See context around confusing change: `analyze_diff_section({\"filePath\":\"src/auth.ts\",\"startLine\":45,\"endLine\":52,\"contextLines\":15})`\n\n---\n\n**get_recent_commits** _(cheap)_\nGet recent commits that modified the same files to understand recent work in this area\n\nParameters:\n- `filePaths` (required): Files to check for recent commits\n- `since`: Time period to look back (e.g., \"1 week ago\", \"2 days ago\")\n- `limit`: Maximum number of commits to return (default: 5)\n\n**When to use:** Get recent commits that modified the same files to understand recent work in this area\n\n**Examples:**\n- Check for duplicate commit messages: `get_recent_commits({\"filePaths\":[\"src/auth.ts\"],\"since\":\"1 week ago\",\"limit\":5})`\n\n---\n\n### Analysis\n\n**search_codebase** _(moderate)_\nSearch for code patterns, function names, or text across the codebase using git grep\n\nParameters:\n- `query` (required): Search pattern (can be plain text or regex)\n- `fileTypes`: Limit search to specific file extensions (e.g., [\"ts\", \"js\"])\n- `contextLines`: Number of context lines to show around matches (default: 2)\n\n**When to use:** Search for code patterns, function names, or text across the codebase using git grep\n\n**Examples:**\n- Find all uses of a renamed function: `search_codebase({\"query\":\"oldFunctionName\",\"fileTypes\":[\"ts\",\"tsx\"]})`\n- Check if pattern exists elsewhere: `search_codebase({\"query\":\"pattern.*string\",\"contextLines\":3})`\n\n---\n\n**get_file_dependencies** _(moderate)_\nFind which files import or depend on the changed files to assess change impact\n\nParameters:\n- `filePaths` (required): Files to analyze dependencies for\n\n**When to use:** Find which files import or depend on the changed files to assess change impact\n\n**Examples:**\n- Check impact of util function change: `get_file_dependencies({\"filePaths\":[\"src/utils/format.ts\"]})`\n\n---\n\n### Organization\n\n**group_files_by_concern** _(cheap)_\nAnalyze changed files and suggest logical groupings that might represent separate commits\n\nParameters:\n- `filePaths` (required): All changed files to analyze\n\n**When to use:** Analyze changed files and suggest logical groupings that might represent separate commits\n\n**Examples:**\n- Check if multiple unrelated changes should be split: `group_files_by_concern({\"filePaths\":[\"src/auth.ts\",\"README.md\",\"tests/auth.test.ts\",\"package.json\"]})`\n\n---\n\n**get_file_modification_times** _(cheap)_\nGet modification timestamps for changed files. Temporal proximity is one signal (among others) that can help identify related changes. Files modified close together MAY be part of the same logical change, but this is not guaranteed - always cross-reference with logical groupings.\n\nParameters:\n- `filePaths` (required): All changed files to analyze\n\n**When to use:** Get modification timestamps for changed files. Temporal proximity is one signal (among others) that can help identify related changes. Files modified close together MAY be part of the same logical change, but this is not guaranteed - always cross-reference with logical groupings.\n\n**Examples:**\n- Identify files modified together vs at different times: `get_file_modification_times({\"filePaths\":[\"src/auth.ts\",\"src/user.ts\",\"README.md\",\"tests/auth.test.ts\"]})`\n\n---\n\n\n\n## Your Task\n\nAnalyze the staged changes and determine the best way to commit them. Your primary goal is to create **meaningful, atomic commits** that each represent a single logical change.\n\n**CRITICAL**: When there are many changed files, especially after a long work session (multiple hours), you should almost always split them into multiple commits. A single commit with 10+ files usually indicates multiple distinct changes that should be separated.\n\nThink about:\n- What distinct features, fixes, or improvements are represented?\n- Are there natural groupings by functionality, module, or purpose?\n- When were files modified relative to each other?\n- What should reviewers focus on in each commit?\n\n## Investigation Strategy\n\nFor any non-trivial set of changes, gather multiple signals to understand how to group commits:\n\n1. **Check file modification times** using `get_file_modification_times`\n   - This reveals *when* files were changed relative to each other\n   - Files modified close together *may* be part of the same logical change\n   - Large temporal gaps *can* indicate separate work sessions\n   - Note: temporal proximity is one signal, not a guarantee of relatedness\n\n2. **Understand logical relationships** using `group_files_by_concern`\n   - Groups by module, type (tests, docs, source), and directory structure\n   - Reveals which files are functionally related regardless of when they were modified\n\n3. **Cross-reference both signals** to make informed decisions:\n   - Files modified together AND logically related → strong candidate for same commit\n   - Files modified apart BUT logically related → might still belong together\n   - Files modified together BUT logically unrelated → consider splitting\n   - Use your judgment - neither signal is definitive on its own\n\n4. **Investigate further** as needed:\n   - get_file_content - see full context when diffs are unclear\n   - get_file_history - understand how code evolved\n   - get_file_dependencies - assess impact of changes\n   - get_recent_commits - avoid duplicate messages\n   - get_related_tests - understand behavior changes\n   - search_codebase - find usage patterns\n\n## When to Split Commits\n\n**Prefer multiple commits when:**\n- Changes span multiple hours of work (check modification times!)\n- Different logical features or fixes are included\n- Test changes could be separated from production code changes\n- Documentation updates are unrelated to code changes\n- Refactoring is mixed with feature work\n- Configuration changes are mixed with implementation changes\n- Files in different modules/packages are changed for different reasons\n\n**Keep as one commit when:**\n- All changes are part of a single, cohesive feature\n- Files were modified together in a focused work session\n- Test changes directly test the production code changes\n- The changes tell a single coherent story\n\n**Default bias**: When in doubt about whether to split, **prefer splitting**. It's better to have too many focused commits than too few bloated ones. A good commit should be understandable and reviewable in isolation.\n\n## Important Context Guidelines\n\nIf additional context is provided (from context files or other sources), use your judgment:\n- If the context is relevant to these specific changes, incorporate it\n- If the context describes unrelated changes or other packages, ignore it\n- Don't force connections between unrelated information\n- Focus on accurately describing what actually changed\n\n## Writing Style\n\nWrite naturally and directly:\n- Use plain language, not corporate speak\n- Be specific and concrete\n- Avoid buzzwords and jargon\n- No emojis or excessive punctuation\n- No phrases like \"this commit\" or \"this PR\"\n- No meta-commentary about the commit itself\n\nFollow conventional commit format when appropriate (feat:, fix:, refactor:, docs:, test:, chore:), but prioritize clarity over formality.\n\n## Output Format\n\nWhen ready, format your response as:\n\nCOMMIT_MESSAGE:\n[Your commit message here - only for the FIRST group of changes if splitting]\n\nIf changes should be split into multiple commits (which is often the case with large changesets):\n\nSUGGESTED_SPLITS:\nSplit 1:\nFiles: [list of files]\nRationale: [why these belong together - mention temporal clustering and/or logical relationship]\nMessage: [commit message for this split]\n\nSplit 2:\nFiles: [list of files]\nRationale: [why these belong together]\nMessage: [commit message for this split]\n\nSplit 3:\n...\n\nOutput only the commit message and splits. No conversational remarks or follow-up offers."
+  },
+  {
+    "role": "user",
+    "content": "I have staged changes that need a commit message.\n\nChanged files (2):\n  - README.md\n  - package.json\n\nDiff:\ndiff --git a/README.md b/README.md\nindex f6a5308..6d6889d 100644\n--- a/README.md\n+++ b/README.md\n@@ -163,3 +163,5 @@ interface DynamicContentItem {\n ## License\n \n Apache-2.0\n+\n+<!-- v1.0.0 -->\ndiff --git a/package.json b/package.json\nindex 7e0933c..551d97a 100644\n--- a/package.json\n+++ b/package.json\n@@ -1,6 +1,7 @@\n {\n   \"name\": \"@riotprompt/agentic\",\n-  \"version\": \"0.0.5-dev.0\",\n+  \"version\": \"1.0.0-dev.0\",\n+  \"_versionReset\": \"2026-01-15\",\n   \"description\": \"Shared agentic framework for multi-turn AI conversations and tool orchestration\",\n   \"type\": \"module\",\n   \"main\": \"./dist/index.js\",\n\n\nUser direction: --model\n\nRecent commit history for context:\ncommit 5d1004530c53a05b6e40a11591ac3fc63044cdd8\nAuthor: Tim O'Brien <tobrien@discursive.com>\nDate:   Wed Jan 14 06:55:10 2026 -0800\n\n    chore(config): reformat Vite/Vitest config files\n\ncommit 868ebfd2d325ea2b580271684770a272c6ab060b\nAuthor: Tim O'Brien <tobrien@discursive.com>\nDate:   Wed Jan 14 06:55:10 2026 -0800\n\n    fix(context-manager): increase content hash prefix to 32 hex chars\n\ncommit e5730b2798c7ab7736c9233a43c98837abd737de\nAuthor: Tim O'Brien <tobrien@discursive.com>\nDate:   Wed Jan 14 06:55:10 2026 -0800\n\n    docs(security): add SECURITY.md with tool execution hardening guidance\n\n\n## Your Analysis Task\n\nGather signals to understand the changes:\n1. Use `get_file_modification_times` to see when files were modified relative to each other\n2. Use `group_files_by_concern` to understand how files relate by type/purpose\n3. Cross-reference both signals - temporal proximity and logical relatedness - to determine the best commit structure\n\nConsider:\n- What distinct features, fixes, or improvements are included?\n- Are files that were modified together also logically related?\n- Would separate commits make the history more understandable?\n\nIf changes represent multiple logical concerns, suggest splits.\n\nIf context information is provided, use it only if relevant to these specific changes.\nDon't force connections that don't exist - focus on what actually changed."
+  },
+  {
+    "role": "assistant",
+    "content": null,
+    "tool_calls": [
+      {
+        "id": "call_YZ6b7SnXwG2PQ682TsTLWxEA",
+        "type": "function",
+        "function": {
+          "name": "get_file_modification_times",
+          "arguments": "{\"filePaths\": [\"README.md\", \"package.json\"]}"
+        }
+      },
+      {
+        "id": "call_MvnyMqYyK33uwduIr0oHDMfd",
+        "type": "function",
+        "function": {
+          "name": "group_files_by_concern",
+          "arguments": "{\"filePaths\": [\"README.md\", \"package.json\"]}"
+        }
+      }
+    ]
+  },
+  {
+    "role": "tool",
+    "tool_call_id": "call_YZ6b7SnXwG2PQ682TsTLWxEA",
+    "content": "## File Modification Times (sorted oldest to newest)\n\n2026-01-15 13:41:18  package.json\n2026-01-15 13:46:30  README.md\n\n\n## Temporal Clusters (files modified within 10 minutes of each other)\n\nAll 2 files were modified in a single work session.\n",
+    "name": "get_file_modification_times"
+  },
+  {
+    "role": "tool",
+    "tool_call_id": "call_MvnyMqYyK33uwduIr0oHDMfd",
+    "content": "documentation (1 files):\n  - README.md\n\ndependencies (1 files):\n  - package.json\n\nSuggestion: These 2 groups might be better as separate commits if they represent different concerns.",
+    "name": "group_files_by_concern"
+  },
+  {
+    "role": "assistant",
+    "content": "COMMIT_MESSAGE:\nchore(release): reset package version to 1.0.0-dev.0\n\n- Add `_versionReset` marker in package.json\n- Add v1.0.0 marker comment to README"
+  }
+]
+```
+
+</details>
+
+## Generated Commit Message
+
+```
+chore(release): reset package version to 1.0.0-dev.0
+
+- Add `_versionReset` marker in package.json
+- Add v1.0.0 marker comment to README
+```

package/output/kodrdriv/agentic-reflection-commit-2026-01-15T15-39-32-200Z.md

@@ -0,0 +1,97 @@
+# Agentic Workflow - Self-Reflection Report
+
+Generated: 2026-01-15T15:39:32.200Z
+
+## Execution Summary
+
+- **Iterations**: 2
+- **Tool Calls**: 2
+- **Unique Tools**: 2
+
+## Tool Effectiveness Analysis
+
+| Tool | Calls | Success | Failures | Success Rate | Avg Duration |
+|------|-------|---------|----------|--------------|--------------|
+| get_file_modification_times | 1 | 1 | 0 | 100.0% | 1ms |
+| group_files_by_concern | 1 | 1 | 0 | 100.0% | 0ms |
+
+### Tool Performance Insights
+
+**Most Frequently Used:**
+- get_file_modification_times: 1 calls
+- group_files_by_concern: 1 calls
+
+## Recommendations for Improvement
+
+*No specific recommendations at this time. Execution appears optimal.*
+
+## Detailed Execution Timeline
+
+| Time | Iteration | Tool | Result | Duration |
+|------|-----------|------|--------|----------|
+| 7:39:31 AM | 1 | get_file_modification_times | ✅ Success | 1ms |
+| 7:39:31 AM | 1 | group_files_by_concern | ✅ Success | 0ms |
+
+## Conversation History
+
+<details>
+<summary>Click to expand full agentic interaction</summary>
+
+```json
+[
+  {
+    "role": "system",
+    "content": "You are a professional software engineer writing commit messages for your team.\n\n## Available Tools\n\n### Understanding\n\n**get_file_history** _(cheap)_\nGet git commit history for one or more files to understand their evolution and past changes\n\nParameters:\n- `filePaths` (required): Array of file paths to get history for\n- `limit`: Maximum number of commits to return (default: 10)\n- `format`: Output format: \"summary\" for brief or \"detailed\" for full messages\n\n**When to use:** Get git commit history for one or more files to understand their evolution and past changes\n\n**Examples:**\n- Check if file has recent refactoring: `get_file_history({\"filePaths\":[\"src/auth.ts\"],\"limit\":5})`\n- Understand evolution of multiple related files: `get_file_history({\"filePaths\":[\"src/user.ts\",\"src/auth.ts\"],\"limit\":10,\"format\":\"detailed\"})`\n\n---\n\n**get_file_content** _(moderate)_\nGet the complete current content of a file to understand context around changes. Returns a message if the file does not exist (e.g., if it was deleted).\n\nParameters:\n- `filePath` (required): Path to the file\n- `includeLineNumbers`: Include line numbers in output (default: false)\n\n**When to use:** Get the complete current content of a file to understand context around changes. Returns a message if the file does not exist (e.g., if it was deleted).\n\n**Examples:**\n- See full class definition for modified method: `get_file_content({\"filePath\":\"src/services/auth.ts\",\"includeLineNumbers\":true})`\n- Check imports and structure: `get_file_content({\"filePath\":\"src/utils/helpers.ts\"})`\n\n---\n\n**get_related_tests** _(cheap)_\nFind test files related to production files to understand what the code is supposed to do\n\nParameters:\n- `filePaths` (required): Production file paths\n\n**When to use:** Find test files related to production files to understand what the code is supposed to do\n\n**Examples:**\n- Find tests for modified service: `get_related_tests({\"filePaths\":[\"src/services/auth.ts\"]})`\n\n---\n\n**analyze_diff_section** _(cheap)_\nGet expanded context around specific lines in a file to better understand changes\n\nParameters:\n- `filePath` (required): File containing the section to analyze\n- `startLine` (required): Starting line number\n- `endLine` (required): Ending line number\n- `contextLines`: Number of additional context lines to show before and after (default: 10)\n\n**When to use:** Get expanded context around specific lines in a file to better understand changes\n\n**Examples:**\n- See context around confusing change: `analyze_diff_section({\"filePath\":\"src/auth.ts\",\"startLine\":45,\"endLine\":52,\"contextLines\":15})`\n\n---\n\n**get_recent_commits** _(cheap)_\nGet recent commits that modified the same files to understand recent work in this area\n\nParameters:\n- `filePaths` (required): Files to check for recent commits\n- `since`: Time period to look back (e.g., \"1 week ago\", \"2 days ago\")\n- `limit`: Maximum number of commits to return (default: 5)\n\n**When to use:** Get recent commits that modified the same files to understand recent work in this area\n\n**Examples:**\n- Check for duplicate commit messages: `get_recent_commits({\"filePaths\":[\"src/auth.ts\"],\"since\":\"1 week ago\",\"limit\":5})`\n\n---\n\n### Analysis\n\n**search_codebase** _(moderate)_\nSearch for code patterns, function names, or text across the codebase using git grep\n\nParameters:\n- `query` (required): Search pattern (can be plain text or regex)\n- `fileTypes`: Limit search to specific file extensions (e.g., [\"ts\", \"js\"])\n- `contextLines`: Number of context lines to show around matches (default: 2)\n\n**When to use:** Search for code patterns, function names, or text across the codebase using git grep\n\n**Examples:**\n- Find all uses of a renamed function: `search_codebase({\"query\":\"oldFunctionName\",\"fileTypes\":[\"ts\",\"tsx\"]})`\n- Check if pattern exists elsewhere: `search_codebase({\"query\":\"pattern.*string\",\"contextLines\":3})`\n\n---\n\n**get_file_dependencies** _(moderate)_\nFind which files import or depend on the changed files to assess change impact\n\nParameters:\n- `filePaths` (required): Files to analyze dependencies for\n\n**When to use:** Find which files import or depend on the changed files to assess change impact\n\n**Examples:**\n- Check impact of util function change: `get_file_dependencies({\"filePaths\":[\"src/utils/format.ts\"]})`\n\n---\n\n### Organization\n\n**group_files_by_concern** _(cheap)_\nAnalyze changed files and suggest logical groupings that might represent separate commits\n\nParameters:\n- `filePaths` (required): All changed files to analyze\n\n**When to use:** Analyze changed files and suggest logical groupings that might represent separate commits\n\n**Examples:**\n- Check if multiple unrelated changes should be split: `group_files_by_concern({\"filePaths\":[\"src/auth.ts\",\"README.md\",\"tests/auth.test.ts\",\"package.json\"]})`\n\n---\n\n**get_file_modification_times** _(cheap)_\nGet modification timestamps for changed files. Temporal proximity is one signal (among others) that can help identify related changes. Files modified close together MAY be part of the same logical change, but this is not guaranteed - always cross-reference with logical groupings.\n\nParameters:\n- `filePaths` (required): All changed files to analyze\n\n**When to use:** Get modification timestamps for changed files. Temporal proximity is one signal (among others) that can help identify related changes. Files modified close together MAY be part of the same logical change, but this is not guaranteed - always cross-reference with logical groupings.\n\n**Examples:**\n- Identify files modified together vs at different times: `get_file_modification_times({\"filePaths\":[\"src/auth.ts\",\"src/user.ts\",\"README.md\",\"tests/auth.test.ts\"]})`\n\n---\n\n\n\n## Your Task\n\nAnalyze the staged changes and determine the best way to commit them. Your primary goal is to create **meaningful, atomic commits** that each represent a single logical change.\n\n**CRITICAL**: When there are many changed files, especially after a long work session (multiple hours), you should almost always split them into multiple commits. A single commit with 10+ files usually indicates multiple distinct changes that should be separated.\n\nThink about:\n- What distinct features, fixes, or improvements are represented?\n- Are there natural groupings by functionality, module, or purpose?\n- When were files modified relative to each other?\n- What should reviewers focus on in each commit?\n\n## Investigation Strategy\n\nFor any non-trivial set of changes, gather multiple signals to understand how to group commits:\n\n1. **Check file modification times** using `get_file_modification_times`\n   - This reveals *when* files were changed relative to each other\n   - Files modified close together *may* be part of the same logical change\n   - Large temporal gaps *can* indicate separate work sessions\n   - Note: temporal proximity is one signal, not a guarantee of relatedness\n\n2. **Understand logical relationships** using `group_files_by_concern`\n   - Groups by module, type (tests, docs, source), and directory structure\n   - Reveals which files are functionally related regardless of when they were modified\n\n3. **Cross-reference both signals** to make informed decisions:\n   - Files modified together AND logically related → strong candidate for same commit\n   - Files modified apart BUT logically related → might still belong together\n   - Files modified together BUT logically unrelated → consider splitting\n   - Use your judgment - neither signal is definitive on its own\n\n4. **Investigate further** as needed:\n   - get_file_content - see full context when diffs are unclear\n   - get_file_history - understand how code evolved\n   - get_file_dependencies - assess impact of changes\n   - get_recent_commits - avoid duplicate messages\n   - get_related_tests - understand behavior changes\n   - search_codebase - find usage patterns\n\n## When to Split Commits\n\n**Prefer multiple commits when:**\n- Changes span multiple hours of work (check modification times!)\n- Different logical features or fixes are included\n- Test changes could be separated from production code changes\n- Documentation updates are unrelated to code changes\n- Refactoring is mixed with feature work\n- Configuration changes are mixed with implementation changes\n- Files in different modules/packages are changed for different reasons\n\n**Keep as one commit when:**\n- All changes are part of a single, cohesive feature\n- Files were modified together in a focused work session\n- Test changes directly test the production code changes\n- The changes tell a single coherent story\n\n**Default bias**: When in doubt about whether to split, **prefer splitting**. It's better to have too many focused commits than too few bloated ones. A good commit should be understandable and reviewable in isolation.\n\n## Important Context Guidelines\n\nIf additional context is provided (from context files or other sources), use your judgment:\n- If the context is relevant to these specific changes, incorporate it\n- If the context describes unrelated changes or other packages, ignore it\n- Don't force connections between unrelated information\n- Focus on accurately describing what actually changed\n\n## Writing Style\n\nWrite naturally and directly:\n- Use plain language, not corporate speak\n- Be specific and concrete\n- Avoid buzzwords and jargon\n- No emojis or excessive punctuation\n- No phrases like \"this commit\" or \"this PR\"\n- No meta-commentary about the commit itself\n\nFollow conventional commit format when appropriate (feat:, fix:, refactor:, docs:, test:, chore:), but prioritize clarity over formality.\n\n## Output Format\n\nWhen ready, format your response as:\n\nCOMMIT_MESSAGE:\n[Your commit message here - only for the FIRST group of changes if splitting]\n\nIf changes should be split into multiple commits (which is often the case with large changesets):\n\nSUGGESTED_SPLITS:\nSplit 1:\nFiles: [list of files]\nRationale: [why these belong together - mention temporal clustering and/or logical relationship]\nMessage: [commit message for this split]\n\nSplit 2:\nFiles: [list of files]\nRationale: [why these belong together]\nMessage: [commit message for this split]\n\nSplit 3:\n...\n\nOutput only the commit message and splits. No conversational remarks or follow-up offers."
+  },
+  {
+    "role": "user",
+    "content": "I have staged changes that need a commit message.\n\nChanged files (1):\n  - package.json\n\nDiff:\ndiff --git a/package.json b/package.json\nindex 551d97a..19015fa 100644\n--- a/package.json\n+++ b/package.json\n@@ -21,7 +21,7 @@\n     \"test\": \"vitest run --coverage\",\n     \"test:coverage\": \"vitest run --coverage\",\n     \"lint\": \"eslint src\",\n-    \"precommit\": \"npm run lint && npm run test\",\n+    \"precommit\": \"npm run build && npm run lint && npm run test\",\n     \"prepublishOnly\": \"npm run clean && npm run build\"\n   },\n   \"keywords\": [\n\n\nUser direction: --model\n\nRecent commit history for context:\ncommit 41c0890ac6e9ad78d158bac9c7e69873bc95709c\nAuthor: Tim O'Brien <tobrien@discursive.com>\nDate:   Thu Jan 15 06:16:05 2026 -0800\n\n    chore(release): reset package version to 1.0.0-dev.0\n    \n    - Add `_versionReset` marker in package.json\n    - Add v1.0.0 marker comment to README\n\ncommit 5d1004530c53a05b6e40a11591ac3fc63044cdd8\nAuthor: Tim O'Brien <tobrien@discursive.com>\nDate:   Wed Jan 14 06:55:10 2026 -0800\n\n    chore(config): reformat Vite/Vitest config files\n\ncommit 868ebfd2d325ea2b580271684770a272c6ab060b\nAuthor: Tim O'Brien <tobrien@discursive.com>\nDate:   Wed Jan 14 06:55:10 2026 -0800\n\n    fix(context-manager): increase content hash prefix to 32 hex chars\n\n\n## Your Analysis Task\n\nGather signals to understand the changes:\n1. Use `get_file_modification_times` to see when files were modified relative to each other\n2. Use `group_files_by_concern` to understand how files relate by type/purpose\n3. Cross-reference both signals - temporal proximity and logical relatedness - to determine the best commit structure\n\nConsider:\n- What distinct features, fixes, or improvements are included?\n- Are files that were modified together also logically related?\n- Would separate commits make the history more understandable?\n\nIf changes represent multiple logical concerns, suggest splits.\n\nIf context information is provided, use it only if relevant to these specific changes.\nDon't force connections that don't exist - focus on what actually changed."
+  },
+  {
+    "role": "assistant",
+    "content": null,
+    "tool_calls": [
+      {
+        "id": "call_GHsSxYR1xlLujz5lXCXHHCS6",
+        "type": "function",
+        "function": {
+          "name": "get_file_modification_times",
+          "arguments": "{\"filePaths\": [\"package.json\"]}"
+        }
+      },
+      {
+        "id": "call_CKlbh4svAS0iGisoqgW7SPsA",
+        "type": "function",
+        "function": {
+          "name": "group_files_by_concern",
+          "arguments": "{\"filePaths\": [\"package.json\"]}"
+        }
+      }
+    ]
+  },
+  {
+    "role": "tool",
+    "tool_call_id": "call_GHsSxYR1xlLujz5lXCXHHCS6",
+    "content": "## File Modification Times (sorted oldest to newest)\n\n2026-01-15 14:24:01  package.json\n\n\n## Temporal Clusters (files modified within 10 minutes of each other)\n\nAll 1 files were modified in a single work session.\n",
+    "name": "get_file_modification_times"
+  },
+  {
+    "role": "tool",
+    "tool_call_id": "call_CKlbh4svAS0iGisoqgW7SPsA",
+    "content": "dependencies (1 files):\n  - package.json\n\nSuggestion: All files appear to be related and should be in a single commit.",
+    "name": "group_files_by_concern"
+  },
+  {
+    "role": "assistant",
+    "content": "COMMIT_MESSAGE:\nchore(git-hooks): run build in precommit script"
+  }
+]
+```
+
+</details>
+
+## Generated Commit Message
+
+```
+chore(git-hooks): run build in precommit script
+```