agent-state-machine 2.5.0 → 2.6.0

package/lib/llm.js

@@ -354,15 +354,21 @@ async function executeCLI(command, promptText, options = {}, apiKeys = {}) {
 
     if (baseCmd === 'claude') {
       args.push('--print');
-      args.push('--permission-mode', 'acceptEdits');
+      const permissionMode = options.cliPermissions?.claude || 'acceptEdits';
+      args.push('--permission-mode', permissionMode);
       args.push('--output-format', 'json');
       // Input via stdin
     } else if (baseCmd === 'gemini') {
-      args.push('--approval-mode', 'auto_edit');
+      const approvalMode = options.cliPermissions?.gemini || 'auto_edit';
+      args.push('--approval-mode', approvalMode);
       args.push('--output-format', 'json');
       // Input via stdin
     } else if (baseCmd === 'codex') {
       ensureCodexExec();
+      const bypassMode = options.cliPermissions?.codex;
+      if (bypassMode === 'bypass') {
+        args.push('--dangerously-bypass-approvals-and-sandbox');
+      }
       args.push('--json');
       args.push('-'); // Explicitly read from stdin
     } else {
@@ -581,7 +587,12 @@ export async function llm(context, options) {
     result = await executeAPI(provider, model, fullPrompt, apiKey, options);
   } else {
     // CLI execution - pass fullPrompt string directly
-    result = await executeCLI(modelConfig, fullPrompt, options, apiKeys);
+    // Include cliPermissions from config if available
+    const cliOptions = {
+      ...options,
+      cliPermissions: config.cliPermissions || {}
+    };
+    result = await executeCLI(modelConfig, fullPrompt, cliOptions, apiKeys);
   }
 
   // Record usage in agent tracker (if active)

package/lib/runtime/prompt.js

@@ -105,7 +105,7 @@ export async function askHuman(question, options = {}) {
     await runtime.prependHistory({
       event: 'PROMPT_ANSWERED',
       slug,
-      answer: normalizedAnswer.substring(0, 100) + (normalizedAnswer.length > 100 ? '...' : '')
+      answer: normalizedAnswer
     });
 
     return normalizedAnswer;

package/lib/runtime/runtime.js

@@ -87,7 +87,14 @@ export class WorkflowRuntime {
       // Full-auto mode (auto-select first option for choice interactions)
       fullAuto: false,
       maxQuickFixAttempts: 10,
-      autoSelectDelay: 20  // seconds before auto-selecting in full-auto mode
+      autoSelectDelay: 20,  // seconds before auto-selecting in full-auto mode
+      // CLI permission modes (configurable per tool)
+      cliPermissions: {
+        claude: 'acceptEdits',
+        gemini: 'auto_edit'
+      },
+      // Protected paths - prevents DELETION only (modifications allowed)
+      protectedPaths: []
     };
 
     // Load steering
@@ -384,6 +391,7 @@ export class WorkflowRuntime {
       const cfg = configModule.config || configModule.default || {};
       // Preserve CLI-set fullAuto (it takes precedence over config.js)
       const cliFullAuto = this.workflowConfig.fullAuto;
+      const defaultCliPermissions = { claude: 'acceptEdits', gemini: 'auto_edit' };
       this.workflowConfig = {
         models: cfg.models || {},
         apiKeys: cfg.apiKeys || {},
@@ -396,7 +404,11 @@ export class WorkflowRuntime {
         // Full-auto mode: CLI flag takes precedence, then config.js, then default false
         fullAuto: cliFullAuto || cfg.fullAuto || false,
         maxQuickFixAttempts: cfg.maxQuickFixAttempts ?? 10,
-        autoSelectDelay: cfg.autoSelectDelay ?? this.workflowConfig.autoSelectDelay  // seconds before auto-selecting
+        autoSelectDelay: cfg.autoSelectDelay ?? this.workflowConfig.autoSelectDelay,  // seconds before auto-selecting
+        // CLI permission modes (merge with defaults)
+        cliPermissions: { ...defaultCliPermissions, ...(cfg.cliPermissions || {}) },
+        // Protected paths - prevents DELETION only (modifications allowed)
+        protectedPaths: cfg.protectedPaths || []
       };
 
       // Import workflow module

package/lib/runtime/track-changes.js

@@ -7,6 +7,7 @@
  */
 
 import path from 'path';
+import { execSync } from 'child_process';
 import {
   captureBaseline,
   detectChanges,
@@ -38,9 +39,52 @@ export async function withChangeTracking(runtime, agentName, fn) {
   // Detect changes made during agent execution
   const changes = await detectChanges(projectRoot, baseline, ignorePatterns);
 
+  // Validate protected paths (only checks deletions)
+  const validation = validateProtectedPaths(runtime, changes);
+  if (!validation.valid) {
+    console.warn(`[protected-paths] Violations detected by agent '${agentName}':`);
+    validation.violations.forEach(v => console.warn(`  - ${v}`));
+    throw new Error(`Protected path violations: ${validation.violations.join(', ')}`);
+  }
+
   // Update fileTree with detected changes
   applyChangesToFileTree(runtime, changes, agentName);
 
+  // Log git diff to history when files change
+  if (changes.created.length || changes.modified.length || changes.deleted.length) {
+    try {
+      const diff = execSync('git diff HEAD', {
+        cwd: projectRoot,
+        encoding: 'utf-8',
+        maxBuffer: 1024 * 1024 // 1MB limit
+      }).trim();
+
+      if (diff) {
+        await runtime.prependHistory({
+          type: 'file_changes',
+          agent: agentName,
+          summary: {
+            created: changes.created.length,
+            modified: changes.modified.length,
+            deleted: changes.deleted.length
+          },
+          diff: diff.slice(0, 50000) // Truncate if too large
+        });
+      }
+    } catch (e) {
+      // Git diff failed, log summary only
+      await runtime.prependHistory({
+        type: 'file_changes',
+        agent: agentName,
+        summary: {
+          created: changes.created.length,
+          modified: changes.modified.length,
+          deleted: changes.deleted.length
+        }
+      });
+    }
+  }
+
   // Merge _files annotations if present (preserves existing data unless explicitly overwritten)
   if (result && typeof result === 'object' && Array.isArray(result._files)) {
     mergeAnnotations(runtime, result._files);
@@ -49,6 +93,46 @@ export async function withChangeTracking(runtime, agentName, fn) {
   return result;
 }
 
+/**
+ * Validate that protected paths were not deleted.
+ * Only checks for DELETIONS - modifications are allowed.
+ *
+ * @param {Object} runtime - The workflow runtime instance
+ * @param {Object} changes - Detected changes { created, modified, deleted, renamed }
+ * @returns {{ valid: boolean, violations: string[] }}
+ */
+export function validateProtectedPaths(runtime, changes) {
+  const protectedPaths = runtime.workflowConfig.protectedPaths || [];
+  const violations = [];
+
+  // Only check DELETED files - modifications are allowed
+  for (const deleted of changes.deleted || []) {
+    for (const pattern of protectedPaths) {
+      if (matchesPattern(deleted, pattern)) {
+        violations.push(`Cannot delete protected file: ${deleted}`);
+      }
+    }
+  }
+
+  return { valid: violations.length === 0, violations };
+}
+
+/**
+ * Simple pattern matching for protected paths.
+ * Supports exact match and prefix wildcards (e.g., '.env*' matches '.env', '.env.local')
+ */
+function matchesPattern(filePath, pattern) {
+  // Normalize both for comparison
+  const normalizedPath = filePath.replace(/\\/g, '/');
+  const normalizedPattern = pattern.replace(/\\/g, '/');
+
+  if (normalizedPattern.endsWith('*')) {
+    // Prefix wildcard: '.env*' matches '.env', '.env.local', etc.
+    return normalizedPath.startsWith(normalizedPattern.slice(0, -1));
+  }
+  return normalizedPath === normalizedPattern;
+}
+
 /**
  * Apply detected file changes to the runtime's fileTree.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-state-machine",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "type": "module",
   "description": "A workflow orchestrator for running agents and scripts in sequence with state management",
   "main": "lib/index.js",

package/templates/project-builder/agents/{code-writer.md → code-write.md}

@@ -1,6 +1,7 @@
 ---
 model: high
 format: json
+description: "Code phase: Implements the task by writing production code and tests"
 ---
 
 # Code Writer Agent
@@ -9,6 +10,11 @@ You are a senior software developer. Implement the task according to specificati
 
 ## Instructions
 
+**IMPORTANT: Use your file tools to create and write files directly to disk.** Do not embed code in JSON. Use your native file creation capabilities to:
+1. Create directories as needed
+2. Write each file with full production code
+3. Report what files you created
+
 Implement the task following these principles:
 
 **Code Quality:**
@@ -33,22 +39,14 @@ Implement the task following these principles:
 
 ## Output Format
 
-Return a valid JSON object:
+After writing all files to disk using your file tools, return a valid JSON object:
 
 {
   "implementation": {
     "summary": "Brief description of what was implemented",
-    "files": [
-      {
-        "path": "src/feature.js",
-        "purpose": "Main implementation",
-        "code": "// Full code content here\nfunction example() {\n  return 'hello';\n}"
-      },
-      {
-        "path": "src/feature.test.js",
-        "purpose": "Test file",
-        "code": "// Test code here\ndescribe('feature', () => {\n  it('works', () => {});\n});"
-      }
+    "filesWritten": [
+      {"path": "src/feature.js", "purpose": "Main implementation"},
+      {"path": "src/feature.test.js", "purpose": "Test file"}
     ],
     "dependencies": [
       {"name": "lodash", "version": "^4.17.21", "reason": "Utility functions"}
@@ -65,3 +63,11 @@ Return a valid JSON object:
 }
 
 Write production-quality code. This is not a prototype.
+
+## Safeguards
+
+**NEVER modify or remove:**
+- `.env` or `.env.*` files
+- The `agent-state-machine` dependency in `package.json`
+
+You may add new dependencies but must preserve existing critical ones.

package/templates/project-builder/agents/{assumptions-clarifier.md → intake-assumptions.md}

@@ -3,6 +3,7 @@ model: med
 format: json
 interaction: true
 response: choice
+description: "Intake phase: Validates technical and business assumptions before development"
 ---
 
 # Assumptions Clarifier Agent

package/templates/project-builder/agents/{requirements-clarifier.md → intake-requirements.md}

@@ -3,6 +3,7 @@ model: med
 format: json
 interaction: true
 response: choice
+description: "Intake phase: Gathers functional and non-functional requirements"
 ---
 
 # Requirements Clarifier Agent

package/templates/project-builder/agents/{scope-clarifier.md → intake-scope.md}

@@ -3,6 +3,7 @@ model: med
 format: json
 interaction: true
 response: choice
+description: "Intake phase: Clarifies project boundaries and scope before planning begins"
 ---
 
 # Scope Clarifier Agent

package/templates/project-builder/agents/{security-clarifier.md → intake-security.md}

@@ -3,6 +3,7 @@ model: med
 format: json
 interaction: true
 response: choice
+description: "Intake phase: Identifies security requirements and compliance needs upfront"
 ---
 
 # Security Clarifier Agent

package/templates/project-builder/agents/{roadmap-generator.md → plan-roadmap.md}

@@ -1,6 +1,7 @@
 ---
 model: high
 format: json
+description: "Planning phase: Generates phased development roadmap from gathered requirements"
 ---
 
 # Roadmap Generator Agent

package/templates/project-builder/agents/{task-planner.md → plan-tasks.md}

@@ -1,6 +1,7 @@
 ---
 model: high
 format: json
+description: "Planning phase: Breaks down a roadmap phase into actionable tasks"
 ---
 
 # Task Planner Agent

package/templates/project-builder/agents/post-code-fix.md

@@ -0,0 +1,59 @@
+---
+model: high
+format: json
+description: "Post-code phase: Fixes issues found during review or sanity checks"
+---
+
+# Code Fixer Agent
+
+You fix specific issues in existing code based on sanity check failures.
+
+## How to Fix
+
+**IMPORTANT: Use your file tools to read and write files directly.**
+
+1. Read the file(s) that need fixing using your file tools
+2. Analyze the error and identify the root cause
+3. Apply the fix by writing the corrected file back to disk
+4. Report what you fixed
+
+## Critical Guidelines
+
+**DO NOT** disable, skip, or remove failing tests to make them pass.
+Your fixes must address the actual underlying code issues that cause tests to fail.
+
+- Never add `.skip()`, `.todo()`, or comment out tests
+- Never modify test expectations to match broken behavior
+- Never delete test files or test cases
+- Never wrap tests in `try/catch` to swallow errors
+- Fix the implementation code to pass existing tests
+- Fix test setup/teardown issues if the tests themselves are misconfigured
+- Update tests ONLY if the original requirements were misunderstood
+
+If the issue truly cannot be fixed within the current architecture, set `"confidence": "low"` and explain why in the analysis.
+
+## Input
+- task: Task definition
+- failedChecks: Failed checks with specific errors
+- filePaths: Paths to files that may need fixing
+
+## Output Format
+
+After fixing the files using your file tools, return:
+
+{
+  "analysis": {
+    "rootCauses": ["What caused each failure"],
+    "fixApproach": "Strategy for fixing"
+  },
+  "fixesApplied": [
+    {
+      "path": "src/feature.js",
+      "description": "Fixed the validation logic to handle edge case"
+    }
+  ],
+  "expectedResolutions": ["Which checks should now pass"],
+  "confidence": "high|medium|low"
+}
+
+Focus on minimal, targeted fixes. Don't rewrite entire files unless necessary.

package/templates/project-builder/agents/{code-reviewer.md → post-code-review.md}

@@ -1,12 +1,17 @@
 ---
 model: high
 format: json
+description: "Post-code phase: Reviews implementation for quality and correctness"
 ---
 
 # Code Reviewer Agent
 
 You are a senior code reviewer. Review implementations for quality, correctness, and best practices.
 
+## How to Review
+
+**Use your file tools to read the files that need reviewing.** You will receive a list of file paths to review. Read each file's contents directly from disk to perform your review.
+
 ## Instructions
 
 Perform a thorough code review covering:
@@ -33,6 +38,11 @@ Perform a thorough code review covering:
 - Are tests meaningful (not just coverage padding)?
 - Are edge cases tested?
 
+## Input
+- task: Task definition with title and description
+- filesToReview: Array of file paths to review
+- implementationSummary: Brief description of what was implemented
+
 ## Output Format
 
 Return a valid JSON object:

package/templates/project-builder/agents/post-code-security.md

@@ -0,0 +1,55 @@
+---
+model: med
+format: json
+description: "Post-code phase: Audits implementation for security vulnerabilities"
+---
+
+# Post-Code Security Auditor Agent
+
+You are a security auditor. Review implemented code to identify security vulnerabilities and verify secure coding practices.
+
+## How to Audit
+
+**Use your file tools to read the files that need auditing.** You will receive a list of file paths. Read each file's contents directly from disk to perform your security audit.
+
+## Instructions
+
+Perform a post-implementation security audit:
+
+- Review the implementation for security issues
+- Check for common vulnerabilities (OWASP Top 10)
+- Verify secure coding practices
+- Identify any remaining security debt
+- Verify pre-code security recommendations were followed
+
+## Output Format
+
+Return a valid JSON object:
+
+{
+  "riskLevel": "low",
+  "findings": [
+    {
+      "type": "vulnerability",
+      "severity": "high",
+      "location": "src/auth.js:42",
+      "description": "User input not sanitized before database query",
+      "recommendation": "Use parameterized query instead"
+    }
+  ],
+  "checklistResults": [
+    {"item": "Input validation implemented", "status": "passed"},
+    {"item": "SQL injection prevented", "status": "passed"},
+    {"item": "Authentication tokens secured", "status": "failed"}
+  ],
+  "securityDebt": [
+    "Consider adding rate limiting in future iteration"
+  ],
+  "approved": true,
+  "blockers": []
+}
+
+**Severity levels:** critical, high, medium, low, info
+**Status values:** passed, failed, na
+
+Critical and high severity findings should set approved: false and be listed in blockers.

package/templates/project-builder/agents/{security-reviewer.md → pre-code-security.md}

@@ -1,34 +1,27 @@
 ---
 model: med
 format: json
+description: "Pre-code phase: Analyzes security risks before implementation starts"
 ---
 
-# Security Reviewer Agent
+# Pre-Code Security Reviewer Agent
 
-You are a security review specialist. Review tasks and implementations for security concerns.
+You are a security threat analyst. Analyze tasks BEFORE implementation to identify security risks and recommend secure patterns.
 
 ## Instructions
 
-Perform a security review appropriate to the stage:
+Perform a pre-implementation security analysis:
 
-**Pre-Implementation Review (stage: pre-implementation):**
 - Identify potential security concerns for the task
 - Recommend secure implementation patterns
 - Flag any high-risk areas requiring extra attention
 - Suggest security tests to include
 
-**Post-Implementation Review (stage: post-implementation):**
-- Review the implementation for security issues
-- Check for common vulnerabilities (OWASP Top 10)
-- Verify secure coding practices
-- Identify any remaining security debt
-
 ## Output Format
 
 Return a valid JSON object:
 
 {
-  "stage": "pre-implementation",
   "riskLevel": "low",
   "findings": [
     {
@@ -43,6 +36,10 @@ Return a valid JSON object:
     {"item": "Use parameterized queries", "status": "pending"},
     {"item": "Implement rate limiting", "status": "na"}
   ],
+  "suggestedTests": [
+    "Test for SQL injection with malicious input",
+    "Verify authentication token validation"
+  ],
   "approved": true,
   "blockers": []
 }

package/templates/project-builder/agents/{test-planner.md → pre-code-tests.md}

@@ -1,6 +1,7 @@
 ---
 model: med
 format: json
+description: "Pre-code phase: Creates test plan before implementation begins"
 ---
 
 # Test Planner Agent

package/templates/project-builder/agents/response-interpreter.md

@@ -1,6 +1,7 @@
 ---
 model: fast
 format: json
+description: "Utility: Parses natural language user responses into structured data"
 ---
 
 You are interpreting a user's natural language response against a structured interaction schema.

package/templates/project-builder/agents/verify-commit-msg.md

@@ -0,0 +1,64 @@
+---
+model: fast
+format: json
+description: "Verify phase: Generates conventional commit message after task completion"
+---
+
+# Commit Message Generator Agent
+
+You generate conventional commit messages for completed tasks.
+
+## Input
+- task: { title, description }
+- filesWritten: Array of { path, purpose } for files created/modified
+
+## Output Format
+
+Return a valid JSON object:
+
+{
+  "type": "feat",
+  "scope": "auth",
+  "message": "add user login functionality",
+  "body": "Implements login form with email/password validation.\nAdds JWT token storage and refresh logic."
+}
+
+## Commit Type Guidelines
+
+- **feat**: New feature for the user
+- **fix**: Bug fix for the user
+- **refactor**: Code change that neither fixes a bug nor adds a feature
+- **test**: Adding or updating tests
+- **docs**: Documentation only changes
+- **style**: Formatting, missing semicolons, etc (no code change)
+- **chore**: Updating build tasks, configs, etc
+
+## Message Guidelines
+
+- Use imperative mood ("add" not "added" or "adds")
+- Keep first line under 72 characters
+- Scope is optional but recommended (component/module name)
+- Body should explain what and why, not how
+- Reference file changes in body when helpful
+
+## Examples
+
+Task: "Implement user authentication"
+Files: [{ path: "src/auth.js", purpose: "Auth module" }]
+Output:
+{
+  "type": "feat",
+  "scope": "auth",
+  "message": "implement user authentication",
+  "body": "Adds login/logout functionality with JWT tokens.\n\nFiles:\n- src/auth.js: Core auth module"
+}
+
+Task: "Fix login validation bug"
+Files: [{ path: "src/auth.js", purpose: "Fix validation" }]
+Output:
+{
+  "type": "fix",
+  "scope": "auth",
+  "message": "correct email validation regex",
+  "body": "Email validation was rejecting valid addresses with + symbols."
+}

package/templates/project-builder/agents/{sanity-checker.md → verify-sanity.md}

@@ -1,6 +1,7 @@
 ---
 model: fast
 format: json
+description: "Verify phase: Generates executable sanity checks to validate implementation"
 ---
 
 You generate executable sanity checks for the implemented task.
@@ -37,15 +38,3 @@ Guidelines:
 - Include at least one file_exists or file_contains check when files are created/modified.
 - If tests exist (from testPlan or implementation), include a type "test_suite" check.
 - Use testFramework.command for running tests (optionally target specific files when possible).
-
-Task:
-{{task}}
-
-Implementation:
-{{implementation}}
-
-Test Plan:
-{{testPlan}}
-
-Test Framework:
-{{testFramework}}

package/templates/project-builder/config.js

@@ -1,9 +1,9 @@
 export const config = {
   models: {
-    fast: "gemini -m gemini-2.5-pro",
-    low: "gemini -m gemini-2.5-pro",
-    med: "gemini -m gemini-2.5-pro",
-    high: "gemini -m gemini-2.5-pro",
+    fast: "gemini-2.5-flash",
+    low: "gemini-2.5-flash",
+    med: "gemini-2.5-flash",
+    high: "gemini-2.5-flash",
   },
   apiKeys: {
     gemini: process.env.GEMINI_API_KEY,
@@ -11,6 +11,17 @@ export const config = {
     openai: process.env.OPENAI_API_KEY,
   },
 
+  // CLI permission modes - enables native file access for agents
+  cliPermissions: {
+    claude: 'bypassPermissions',  // --permission-mode bypassPermissions
+    gemini: 'full',               // --approval-mode full
+    codex: 'bypass'               // --dangerously-bypass-approvals-and-sandbox
+  },
+
+  // Protected paths - prevents DELETION only (modifications allowed)
+  // Files matching these patterns cannot be deleted by agents
+  protectedPaths: ['.env', '.env.*', 'package.json'],
+
   // File tracking (all optional - shown with defaults)
   // projectRoot: process.env.PROJECT_ROOT,  // Defaults to ../.. from workflow
   // fileTracking: true,                     // Enable/disable file tracking