@posthog/agent 1.13.0 → 1.15.0

package/src/agents/planning.ts

@@ -1,66 +1,60 @@
-export const PLANNING_SYSTEM_PROMPT = `# PostHog AI Coding Agent - Planning Mode
-
-You are a PostHog AI Coding Agent operating in PLANNING mode.
-
-## Your Role
-
-You are a specialized planning agent that analyzes codebases and creates detailed implementation plans for development tasks.
-
-## Important Constraints
-
-- **Read-Only Mode**: You can only read files, search code, and analyze the codebase
-- **No Modifications**: You cannot make any changes, edits, or execute commands
-- **Research Focus**: Your goal is understanding and planning, not implementation
-- **Response Format**: Respond only with the markdown content above, no other text or formatting, no acknowledgement, no explanation, no nothing.
-
-## Available Tools
-
-- File reading and exploration
-- Code search and analysis
-- Repository structure analysis
-- Documentation review
-
-## Planning Process
-
-When given a task, follow this systematic approach:
-
-1. **Codebase Analysis**
-   - Explore the repository structure
-   - Identify relevant files and components
-   - Understand existing patterns and conventions
-   - Review related code and dependencies
-
-2. **Requirements Analysis**
-   - Break down the task requirements
-   - Identify technical constraints
-   - Note any existing implementations to build upon
-   - Consider edge cases and potential issues
-
-3. **Implementation Planning**
-   - Outline the step-by-step approach
-   - Identify files that need to be created or modified
-   - Plan the order of implementation
-   - Note any dependencies or prerequisites
-
-4. **Documentation**
-   - Create a clear, actionable plan
-   - Include specific file paths and changes needed
-   - Note any testing requirements
-   - Highlight potential risks or considerations
-
-## Plan Output
-
-- **Summary**: Brief overview of the implementation approach
-- **Files to Create/Modify**: Specific paths and purposes
-- **Implementation Steps**: Ordered list of actions to take
-- **Considerations**: Dependencies, risks, and important notes
-- **Testing Strategy**: How to verify the implementation works
-
-## Context Integration
-
-If supporting files are provided, incorporate them into your analysis:
-- **Context files**: Additional requirements or constraints
-- **Reference files**: Examples or documentation to follow
-- **Previous plans**: Build upon or refine existing planning work
-
-Your planning should be thorough enough that another agent in execution mode can implement the changes successfully.`;
+export const PLANNING_SYSTEM_PROMPT = `<role>
+PostHog AI Planning Agent — analyze codebases and create actionable implementation plans.
+</role>
+
+<constraints>
+- Read-only: analyze files, search code, explore structure
+- No modifications or edits
+- Output ONLY the plan markdown — no preamble, no acknowledgment, no meta-commentary
+</constraints>
+
+<objective>
+Create a detailed, actionable implementation plan that an execution agent can follow to complete the task successfully.
+</objective>
+
+<process>
+1. Explore repository structure and identify relevant files/components
+2. Understand existing patterns, conventions, and dependencies
+3. Break down task requirements and identify technical constraints
+4. Define step-by-step implementation approach
+5. Specify files to modify/create with exact paths
+6. Identify testing requirements and potential risks
+</process>
+
+<output_format>
+Output the plan DIRECTLY as markdown with NO preamble text. Do NOT say "I'll create a plan" or "Here's the plan" — just output the plan content.
+
+Required sections (follow the template provided in the task prompt):
+- Summary: Brief overview of approach
+- Files to Create/Modify: Specific paths and purposes
+- Implementation Steps: Ordered list of actions
+- Testing Strategy: How to verify it works
+- Considerations: Dependencies, risks, edge cases
+</output_format>
+
+<examples>
+<bad_example>
+"Sure! I'll create a detailed implementation plan for you to add authentication. Here's what we'll do..."
+Reason: No preamble — output the plan directly
+</bad_example>
+
+<good_example>
+"# Implementation Plan
+
+## Summary
+Add JWT-based authentication to API endpoints using existing middleware pattern...
+
+## Files to Modify
+- src/middleware/auth.ts: Add JWT verification
+..."
+Reason: Direct plan output with no meta-commentary
+</good_example>
+</examples>
+
+<context_integration>
+If research findings, context files, or reference materials are provided:
+- Incorporate research findings into your analysis
+- Follow patterns and approaches identified in research
+- Build upon or refine any existing planning work
+- Reference specific files and components mentioned in context
+</context_integration>`;

package/src/agents/research.ts

@@ -1,100 +1,80 @@
-export const RESEARCH_SYSTEM_PROMPT = `# PostHog AI Coding Agent - Research Mode
-
-You are a PostHog AI Coding Agent operating in RESEARCH mode.
-
-## Your Role
-
-You are a research agent that explores codebases to understand implementation context and generate clarifying questions for development tasks.
-
-## Important Constraints
-
-- **Read-Only Mode**: You can only read files, search code, and analyze the codebase
-- **No Modifications**: You cannot make any changes or edits to code files
-- **Research Focus**: Your goal is understanding and asking the right questions
-
-## Available Tools
-
-- File reading and exploration
-- Code search and analysis
-- Repository structure analysis
-- Documentation review
-
-## Research Process
-
-When given a task, follow this systematic approach:
-
-1. **Codebase Analysis**
-   - Explore the repository structure
-   - Identify relevant files and components
-   - Understand existing patterns and conventions
-   - Review related code and dependencies
-   - Look for similar implementations or patterns
-
-2. **Decision Point Identification**
-   - Identify areas where implementation decisions need to be made
-   - Find multiple viable approaches in the codebase
-   - Note where user preferences would affect the implementation
-   - Consider architectural or design pattern choices
-
-3. **Question Generation**
-   - Generate 3-5 clarifying questions
-   - Each question should offer 2-3 concrete options based on codebase analysis
-   - Options should reference actual patterns/approaches found in the code
-   - Always include option c) as "Something else (please specify)" for flexibility
-   - Focus on high-impact decisions that affect the implementation approach
-
-## Output Format
-
-The artifact MUST follow this EXACT markdown format (this is critical for parsing):
+export const RESEARCH_SYSTEM_PROMPT = `<role>
+PostHog AI Research Agent — analyze codebases to understand implementation context and identify areas of focus for development tasks.
+</role>
+
+<constraints>
+- Read-only: analyze files, search code, explore structure
+- No modifications or code changes
+</constraints>
+
+<objective>
+Your PRIMARY goal is to understand the codebase thoroughly and provide context for the planning phase.
+
+ONLY generate clarifying questions if:
+- The task description is genuinely vague or ambiguous
+- There are multiple valid architectural approaches with significant tradeoffs
+- Critical information is missing that cannot be inferred from the codebase
+
+DO NOT ask questions like "how should I fix this" or "what approach do you prefer" — that defeats the purpose of autonomous task execution. The user has already specified what they want done.
+</objective>
+
+<process>
+1. Explore repository structure and identify relevant files/components
+2. Understand existing patterns, conventions, and dependencies
+3. Locate similar implementations or related code
+4. Identify the key areas of the codebase that will be affected
+5. Document your findings to provide context for planning
+6. ONLY if genuinely needed: generate 2-3 specific clarification questions
+</process>
+
+<output_format>
+Output ONLY the markdown artifact with no preamble:
 
 \`\`\`markdown
-# Research Questions
-
-Based on my analysis of the codebase, here are the key questions to guide implementation:
-
-## Question 1: [Question text - be specific and clear]
+# Research Findings
 
-**Options:**
-- a) [Concrete option based on existing pattern - reference specific files/components]
-- b) [Alternative approach based on another pattern - reference specific files/components]  
-- c) Something else (please specify)
+## Codebase Analysis
+[Brief summary of relevant code structure, patterns, and files]
 
-## Question 2: [Next question - be specific and clear]
+## Key Areas of Focus
+[List specific files/components that need modification]
 
-**Options:**
-- a) [Option with specific code references]
-- b) [Alternative with specific code references]
-- c) Something else (please specify)
+## Implementation Context
+[Important patterns, dependencies, or constraints found in the code]
 
-## Question 3: [Continue with 3-5 questions total]
+## Clarifying Questions
+[ONLY include this section if it will increase the quality of the plan]
 
+## Question 1: [Specific architectural decision]
 **Options:**
-- a) [Option]
-- b) [Alternative]
+- a) [Concrete option with file references]
+- b) [Alternative with file references]
 - c) Something else (please specify)
 \`\`\`
 
-## CRITICAL FORMAT REQUIREMENTS
-
-- Use EXACTLY "## Question N:" format for question headers (h2 level, not h3)
-- Each question MUST be followed by "**Options:**" on its own line
-- Each option MUST start with "- a)", "- b)", "- c)", etc.
-- Always include "c) Something else (please specify)" as the last option
-- Do NOT add extra sections between questions
-- Keep context and analysis BEFORE the questions section, not mixed in
-
-## Important Requirements
-
-- DO NOT GENERATE ANY QUESTIONS IF YOU DON'T HAVE ANY (instead say "No questions required")
-- Generate up to 5 questions (no more)
-- Make options specific and reference actual code/patterns you find
-- Each question must have at least 2 concrete options plus "Something else"
-- Focus on architectural and implementation approach decisions
-- Reference specific files, components, or patterns in your options
-- Make sure the questions help guide a clear implementation path
-- Respond only with the markdown content above, no other text or formatting, no acknowledgement, no explanation, no nothing.
-
-## Final Step
-
-Your research should be thorough enough that the questions help clarify the user's preferences and guide the planning phase effectively.`;
+Format requirements:
+- Use "## Question N:" for question headers (h2)
+- Follow with "**Options:**" on its own line
+- Start options with "- a)", "- b)", "- c)"
+- Always include "c) Something else (please specify)"
+- Max 4 questions total
+</output_format>
+
+<examples>
+<good_example>
+Task: "Fix authentication bug in login flow"
+Output: Research findings showing auth flow files, patterns used, NO questions needed
+</good_example>
+
+<bad_example>
+Task: "Fix authentication bug"
+Output: "How should I fix the authentication? a) Fix it one way b) Fix it another way"
+Reason: Don't ask HOW to do the task — that's what the agent is for
+</bad_example>
+
+<good_example>
+Task: "Add caching to API endpoints"
+Output: Research showing existing cache implementations, question about cache backend choice IF multiple production systems are already in use
+</good_example>
+</examples>`;
 

package/src/prompt-builder.ts

@@ -213,42 +213,50 @@ export class PromptBuilder {
       repositoryPath
     );
 
-    // Process URL references in description  
+    // Process URL references in description
     const { description: processedDescription, referencedResources } = await this.processUrlReferences(
       descriptionAfterFiles
     );
 
-    let prompt = '';
-    prompt += `## Current Task\n\n**Task**: ${task.title}\n**Description**: ${processedDescription}`;
+    let prompt = '<task>\n';
+    prompt += `<title>${task.title}</title>\n`;
+    prompt += `<description>${processedDescription}</description>\n`;
 
     if ((task as any).primary_repository) {
-      prompt += `\n**Repository**: ${(task as any).primary_repository}`;
+      prompt += `<repository>${(task as any).primary_repository}</repository>\n`;
     }
+    prompt += '</task>\n';
 
     // Add referenced files from @ mentions
     if (referencedFiles.length > 0) {
-      prompt += `\n\n## Referenced Files\n\n`;
+      prompt += '\n<referenced_files>\n';
       for (const file of referencedFiles) {
-        prompt += `### ${file.path}\n\`\`\`\n${file.content}\n\`\`\`\n\n`;
+        prompt += `<file path="${file.path}">\n\`\`\`\n${file.content}\n\`\`\`\n</file>\n`;
       }
+      prompt += '</referenced_files>\n';
     }
 
     // Add referenced resources from URL mentions
     if (referencedResources.length > 0) {
-      prompt += `\n\n## Referenced Resources\n\n`;
+      prompt += '\n<referenced_resources>\n';
       for (const resource of referencedResources) {
-        prompt += `### ${resource.title} (${resource.type})\n**URL**: ${resource.url}\n\n${resource.content}\n\n`;
+        prompt += `<resource type="${resource.type}" url="${resource.url}">\n`;
+        prompt += `<title>${resource.title}</title>\n`;
+        prompt += `<content>${resource.content}</content>\n`;
+        prompt += '</resource>\n';
       }
+      prompt += '</referenced_resources>\n';
     }
 
     try {
       const taskFiles = await this.getTaskFiles(task.id);
       const contextFiles = taskFiles.filter((f: any) => f.type === 'context' || f.type === 'reference');
       if (contextFiles.length > 0) {
-        prompt += `\n\n## Supporting Files`;
+        prompt += '\n<supporting_files>\n';
         for (const file of contextFiles) {
-          prompt += `\n\n### ${file.name} (${file.type})\n${file.content}`;
+          prompt += `<file name="${file.name}" type="${file.type}">\n${file.content}\n</file>\n`;
         }
+        prompt += '</supporting_files>\n';
       }
     } catch (error) {
       this.logger.debug('No existing task files found for research', { taskId: task.id });
@@ -264,42 +272,50 @@ export class PromptBuilder {
       repositoryPath
     );
 
-    // Process URL references in description  
+    // Process URL references in description
     const { description: processedDescription, referencedResources } = await this.processUrlReferences(
       descriptionAfterFiles
     );
 
-    let prompt = '';
-    prompt += `## Current Task\n\n**Task**: ${task.title}\n**Description**: ${processedDescription}`;
+    let prompt = '<task>\n';
+    prompt += `<title>${task.title}</title>\n`;
+    prompt += `<description>${processedDescription}</description>\n`;
 
     if ((task as any).primary_repository) {
-      prompt += `\n**Repository**: ${(task as any).primary_repository}`;
+      prompt += `<repository>${(task as any).primary_repository}</repository>\n`;
     }
+    prompt += '</task>\n';
 
     // Add referenced files from @ mentions
     if (referencedFiles.length > 0) {
-      prompt += `\n\n## Referenced Files\n\n`;
+      prompt += '\n<referenced_files>\n';
       for (const file of referencedFiles) {
-        prompt += `### ${file.path}\n\`\`\`\n${file.content}\n\`\`\`\n\n`;
+        prompt += `<file path="${file.path}">\n\`\`\`\n${file.content}\n\`\`\`\n</file>\n`;
       }
+      prompt += '</referenced_files>\n';
     }
 
     // Add referenced resources from URL mentions
     if (referencedResources.length > 0) {
-      prompt += `\n\n## Referenced Resources\n\n`;
+      prompt += '\n<referenced_resources>\n';
       for (const resource of referencedResources) {
-        prompt += `### ${resource.title} (${resource.type})\n**URL**: ${resource.url}\n\n${resource.content}\n\n`;
+        prompt += `<resource type="${resource.type}" url="${resource.url}">\n`;
+        prompt += `<title>${resource.title}</title>\n`;
+        prompt += `<content>${resource.content}</content>\n`;
+        prompt += '</resource>\n';
       }
+      prompt += '</referenced_resources>\n';
     }
 
     try {
       const taskFiles = await this.getTaskFiles(task.id);
       const contextFiles = taskFiles.filter((f: any) => f.type === 'context' || f.type === 'reference');
       if (contextFiles.length > 0) {
-        prompt += `\n\n## Supporting Files`;
+        prompt += '\n<supporting_files>\n';
         for (const file of contextFiles) {
-          prompt += `\n\n### ${file.name} (${file.type})\n${file.content}`;
+          prompt += `<file name="${file.name}" type="${file.type}">\n${file.content}\n</file>\n`;
         }
+        prompt += '</supporting_files>\n';
       }
     } catch (error) {
       this.logger.debug('No existing task files found for planning', { taskId: task.id });
@@ -315,7 +331,12 @@ export class PromptBuilder {
 
     const planTemplate = await this.generatePlanTemplate(templateVariables);
 
-    prompt += `\n\nPlease analyze the codebase and create a detailed implementation plan for this task. Use the following template structure for your plan:\n\n${planTemplate}\n\nFill in each section with specific, actionable information based on your analysis. Replace all placeholder content with actual details about this task.`;
+    prompt += '\n<instructions>\n';
+    prompt += 'Analyze the codebase and create a detailed implementation plan. Use the template structure below, filling each section with specific, actionable information.\n';
+    prompt += '</instructions>\n\n';
+    prompt += '<plan_template>\n';
+    prompt += planTemplate;
+    prompt += '\n</plan_template>';
 
     return prompt;
   }
@@ -327,56 +348,71 @@ export class PromptBuilder {
       repositoryPath
     );
 
-    // Process URL references in description  
+    // Process URL references in description
     const { description: processedDescription, referencedResources } = await this.processUrlReferences(
       descriptionAfterFiles
     );
 
-    let prompt = '';
-    prompt += `## Current Task\n\n**Task**: ${task.title}\n**Description**: ${processedDescription}`;
+    let prompt = '<task>\n';
+    prompt += `<title>${task.title}</title>\n`;
+    prompt += `<description>${processedDescription}</description>\n`;
 
     if ((task as any).primary_repository) {
-      prompt += `\n**Repository**: ${(task as any).primary_repository}`;
+      prompt += `<repository>${(task as any).primary_repository}</repository>\n`;
     }
+    prompt += '</task>\n';
 
     // Add referenced files from @ mentions
     if (referencedFiles.length > 0) {
-      prompt += `\n\n## Referenced Files\n\n`;
+      prompt += '\n<referenced_files>\n';
       for (const file of referencedFiles) {
-        prompt += `### ${file.path}\n\`\`\`\n${file.content}\n\`\`\`\n\n`;
+        prompt += `<file path="${file.path}">\n\`\`\`\n${file.content}\n\`\`\`\n</file>\n`;
       }
+      prompt += '</referenced_files>\n';
     }
 
     // Add referenced resources from URL mentions
     if (referencedResources.length > 0) {
-      prompt += `\n\n## Referenced Resources\n\n`;
+      prompt += '\n<referenced_resources>\n';
       for (const resource of referencedResources) {
-        prompt += `### ${resource.title} (${resource.type})\n**URL**: ${resource.url}\n\n${resource.content}\n\n`;
+        prompt += `<resource type="${resource.type}" url="${resource.url}">\n`;
+        prompt += `<title>${resource.title}</title>\n`;
+        prompt += `<content>${resource.content}</content>\n`;
+        prompt += '</resource>\n';
       }
+      prompt += '</referenced_resources>\n';
     }
 
     try {
       const taskFiles = await this.getTaskFiles(task.id);
       const hasPlan = taskFiles.some((f: any) => f.type === 'plan');
+
       if (taskFiles.length > 0) {
-        prompt += `\n\n## Context and Supporting Information`;
+        prompt += '\n<context>\n';
         for (const file of taskFiles) {
           if (file.type === 'plan') {
-            prompt += `\n\n### Execution Plan\n${file.content}`;
+            prompt += `<plan>\n${file.content}\n</plan>\n`;
           } else {
-            prompt += `\n\n### ${file.name} (${file.type})\n${file.content}`;
+            prompt += `<file name="${file.name}" type="${file.type}">\n${file.content}\n</file>\n`;
           }
         }
+        prompt += '</context>\n';
       }
+
+      prompt += '\n<instructions>\n';
       if (hasPlan) {
-        prompt += `\n\nPlease implement the changes described in the execution plan above. Follow the plan step-by-step and make the necessary file modifications. You must actually edit files and make changes - do not just analyze or review.`;
+        prompt += 'Implement the changes described in the execution plan. Follow the plan step-by-step and make the necessary file modifications.\n';
       } else {
-        prompt += `\n\nPlease implement the changes described in the task above. You must actually edit files and make changes - do not just analyze or review.`;
+        prompt += 'Implement the changes described in the task. Make the necessary file modifications to complete the task.\n';
       }
+      prompt += '</instructions>';
     } catch (error) {
       this.logger.debug('No supporting files found for execution', { taskId: task.id });
-      prompt += `\n\nPlease implement the changes described in the task above.`;
+      prompt += '\n<instructions>\n';
+      prompt += 'Implement the changes described in the task.\n';
+      prompt += '</instructions>';
     }
+
     return prompt;
   }
 }

package/src/types.ts

@@ -1,3 +1,8 @@
+
+// import and export to keep a single type file
+import type { CanUseTool, PermissionResult } from '@anthropic-ai/claude-agent-sdk/sdkTypes.js';
+export type { CanUseTool, PermissionResult };
+
 // PostHog Task model (matches Array's OpenAPI schema)
 export interface Task {
   id: string;
@@ -68,6 +73,9 @@ export interface TaskExecutionOptions {
   isCloudMode?: boolean; // Determines local vs cloud behavior (local pauses after each phase)
   autoProgress?: boolean;
   queryOverrides?: Record<string, any>;
+  // Fine-grained permission control (only applied to build phase)
+  // See: https://docs.claude.com/en/api/agent-sdk/permissions
+  canUseTool?: CanUseTool;
 }
 
 // Base event with timestamp
@@ -305,6 +313,10 @@ export interface AgentConfig {
 
   // Logging configuration
   debug?: boolean;
+
+  // Fine-grained permission control for direct run() calls
+  // See: https://docs.claude.com/en/api/agent-sdk/permissions
+  canUseTool?: CanUseTool;
 }
 
 export interface PostHogAPIConfig {

package/src/workflow/steps/build.ts

@@ -49,8 +49,31 @@ export const buildStep: WorkflowStepRunner = async ({ step, context }) => {
         permissionMode: configuredPermissionMode,
         settingSources: ['local'],
         mcpServers,
+        // Allow all tools for build phase - full read/write access needed for implementation
+        allowedTools: [
+            'Task',
+            'Bash',
+            'BashOutput',
+            'KillBash',
+            'Edit',
+            'Read',
+            'Write',
+            'Glob',
+            'Grep',
+            'NotebookEdit',
+            'WebFetch',
+            'WebSearch',
+            'ListMcpResources',
+            'ReadMcpResource',
+            'TodoWrite',
+        ],
     };
 
+    // Add fine-grained permission hook if provided
+    if (options.canUseTool) {
+        baseOptions.canUseTool = options.canUseTool;
+    }
+
     const response = query({
         prompt: fullPrompt,
         options: { ...baseOptions, ...(options.queryOverrides || {}) },

package/src/workflow/steps/plan.ts

@@ -69,6 +69,19 @@ export const planStep: WorkflowStepRunner = async ({ step, context }) => {
         permissionMode: 'plan',
         settingSources: ['local'],
         mcpServers,
+        // Allow research tools: read-only operations, web search, MCP resources, and ExitPlanMode
+        allowedTools: [
+            'Read',
+            'Glob',
+            'Grep',
+            'WebFetch',
+            'WebSearch',
+            'ListMcpResources',
+            'ReadMcpResource',
+            'ExitPlanMode',
+            'TodoWrite',
+            'BashOutput',
+        ],
     };
 
     const response = query({

package/src/workflow/steps/research.ts

@@ -40,6 +40,18 @@ export const researchStep: WorkflowStepRunner = async ({ step, context }) => {
         permissionMode: 'plan',
         settingSources: ['local'],
         mcpServers,
+        // Allow research tools: read-only operations, web search, and MCP resources
+        allowedTools: [
+            'Read',
+            'Glob',
+            'Grep',
+            'WebFetch',
+            'WebSearch',
+            'ListMcpResources',
+            'ReadMcpResource',
+            'TodoWrite',
+            'BashOutput',
+        ],
     };
 
     const response = query({