@miphamai/cli 0.9.0 → 0.10.0

package/src/shared/types.ts

@@ -80,6 +80,7 @@ export interface ToolContext {
   toolRegistry?: Map<string, ToolDefinition>
   artifactServer?: import('../artifacts/server').ArtifactServer
   agentRegistry?: import('../agent/agent-registry').AgentRegistry
+  backgroundAgentRegistry?: import('../agent/background-registry').BackgroundAgentRegistry
 }
 
 // ── Artifact Types ──
@@ -116,9 +117,18 @@ export interface ToolDefinition {
   execute: (params: Record<string, unknown>, ctx: ToolContext) => Promise<ToolResult>
 }
 
+// ── Task Notification Types ──
+export interface TaskNotification {
+  taskId: string
+  status: 'started' | 'completed' | 'failed'
+  description: string
+  content?: string
+  error?: string
+}
+
 // ── Stream Types ──
 export interface StreamChunk {
-  type: 'text' | 'tool_use' | 'tool_result' | 'thinking' | 'stop' | 'error'
+  type: 'text' | 'tool_use' | 'tool_result' | 'thinking' | 'stop' | 'error' | 'task_notification'
   content?: string
   toolUse?: ToolUseContent
   tool_use_id?: string
@@ -127,6 +137,8 @@ export interface StreamChunk {
   reasoning_content?: string
   /** Anthropic thinking block content (DeepSeek Anthropic endpoint). */
   thinking?: string
+  /** Background task notification payload (type: 'task_notification'). */
+  taskNotification?: TaskNotification
 }
 
 // ── Config Types ──
@@ -173,6 +185,7 @@ export interface SkillDefinition {
 export type HookEvent =
   | 'PreToolUse'
   | 'PostToolUse'
+  | 'PostToolUseFailure'
   | 'SessionStart'
   | 'SessionEnd'
   | 'Notification'
@@ -181,6 +194,8 @@ export type HookEvent =
   | 'PreCompact'
   | 'PostCompact'
   | 'ConfigChange'
+  | 'SubagentStart'
+  | 'SubagentStop'
 
 export type HookType = 'command' | 'http' | 'code' | 'mcp_tool'
 

package/src/tools/agent/agent.ts

@@ -1,13 +1,17 @@
 import type { ToolDefinition } from '../../shared/index.ts'
 import { SubAgent } from '../../agent/sub-agent'
 import type { SubAgentType } from '../../agent/types'
+import { getBackgroundAgentRegistry } from '../../agent/background-registry'
 
 const VALID_TYPES: SubAgentType[] = ['general', 'explore', 'plan', 'code-review']
 
 export const agentTool: ToolDefinition = {
   name: 'Agent',
   description:
-    'Launch a sub-agent to handle complex, multi-step tasks independently. Available types: general, explore, plan, code-review.',
+    'Launch a sub-agent to handle complex, multi-step tasks independently. ' +
+    'Available types: general (default), explore (code search), plan (design), code-review. ' +
+    'Set run_in_background: true to execute asynchronously — returns a task ID immediately; ' +
+    'results are retrievable via the Task tool (output action) or Agent View.',
   category: 'agent',
   permission: 'ask',
   parameters: {
@@ -19,6 +23,11 @@ export const agentTool: ToolDefinition = {
         type: 'string',
         description: 'Type: general (default), explore (code search), plan (design), code-review',
       },
+      run_in_background: {
+        type: 'boolean',
+        description:
+          'When true, execute asynchronously and return a task ID immediately. Use Task output to retrieve results. Default: false.',
+      },
     },
     required: ['description', 'prompt'],
   },
@@ -26,6 +35,7 @@ export const agentTool: ToolDefinition = {
     const description = params.description as string
     const prompt = params.prompt as string
     const agentType = (params.subagent_type as SubAgentType) || 'general'
+    const runInBackground = params.run_in_background === true
 
     if (!VALID_TYPES.includes(agentType)) {
       return {
@@ -51,7 +61,36 @@ export const agentTool: ToolDefinition = {
 
     try {
       const sub = new SubAgent(registry, toolRegistry)
-      const result = await sub.execute(prompt, description, { type: agentType, agentDef })
+      const result = await sub.execute(prompt, description, {
+        type: agentType,
+        agentDef,
+        runInBackground,
+      })
+
+      // If background execution, also register in the task system for Task tool integration
+      if (runInBackground) {
+        const bgMatch = result.match(/\[background-task:(.+?)\]/)
+        if (bgMatch) {
+          const bgTaskId = bgMatch[1]!
+          const bgRegistry = getBackgroundAgentRegistry()
+          const bgTask = bgRegistry.get(bgTaskId)
+
+          return {
+            success: true,
+            content:
+              `── Background Agent Started ──\n\n` +
+              `Task ID:   ${bgTaskId}\n` +
+              `Type:      ${agentType}\n` +
+              `Task:      ${description}\n` +
+              `Status:    ${bgTask?.status || 'running'}\n\n` +
+              `The agent is running in the background. You can continue working.\n` +
+              `Use Task output taskId="${bgTaskId}" to check results.\n` +
+              `Use Task stop taskId="${bgTaskId}" to cancel.\n` +
+              `Use /agents to view in Agent View dashboard.`,
+          }
+        }
+      }
+
       return { success: true, content: result }
     } catch (err) {
       return { success: false, content: '', error: String(err) }

package/src/tools/agent/enter-plan.ts

@@ -0,0 +1,92 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import type { ToolDefinition } from '../../shared/index.ts'
+
+export const enterPlanModeTool: ToolDefinition = {
+  name: 'EnterPlanMode',
+  description:
+    'Enter plan mode — a read-only mode for analysis and design. ' +
+    'In plan mode, only Read/Grep/Glob tools are auto-approved; all other tools require confirmation. ' +
+    'Use this before writing code to design an implementation approach, ' +
+    'explore the codebase, and get user approval before executing changes.',
+  category: 'agent',
+  permission: 'auto',
+  parameters: {
+    type: 'object',
+    properties: {
+      description: {
+        type: 'string',
+        description:
+          'Brief description of what you are planning (e.g., "Add user authentication flow")',
+      },
+    },
+    required: [],
+  },
+  async execute(params, ctx) {
+    const description = (params.description as string) || 'Implementation Plan'
+
+    // Create plan file
+    const planDir = join(ctx.cwd, '.mipham', 'plans')
+    mkdirSync(planDir, { recursive: true })
+
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)
+    const filename = `plan-${timestamp}.md`
+    const filepath = join(planDir, filename)
+
+    const content = [
+      `# ${description}`,
+      '',
+      `> Generated: ${new Date().toISOString()}`,
+      `> Status: Draft`,
+      '',
+      '## Overview',
+      '',
+      '[Describe what this plan aims to achieve]',
+      '',
+      '## Files to Modify',
+      '',
+      '| File | Change | Reason |',
+      '|------|--------|--------|',
+      '|      |        |        |',
+      '',
+      '## Implementation Steps',
+      '',
+      '1. ',
+      '2. ',
+      '3. ',
+      '',
+      '## Verification',
+      '',
+      '- [ ] Tests pass',
+      '- [ ] Typecheck passes',
+      '- [ ] Manual verification',
+      '',
+      '## Notes',
+      '',
+      '[Any additional context, risks, or dependencies]',
+    ].join('\n')
+
+    writeFileSync(filepath, content, 'utf-8')
+
+    return {
+      success: true,
+      content: [
+        '── Plan Mode Activated ──',
+        '',
+        `Plan file: ${filepath}`,
+        '',
+        'Plan mode is READ-ONLY:',
+        '  ✅ Read, Grep, Glob — auto-approved',
+        '  ⚠️  All other tools — require confirmation',
+        '',
+        'Design your approach, explore the codebase, then:',
+        '  • Use ExitPlanMode to submit your plan for approval',
+        '  • The user will review and approve before code changes begin',
+        '',
+        'ExitPlanMode parameters:',
+        '  approved: true → switch to acceptEdits mode (code changes allowed)',
+        '  approved: false → revert to default mode',
+      ].join('\n'),
+    }
+  },
+}

package/src/tools/agent/exit-plan.ts

@@ -0,0 +1,54 @@
+import type { ToolDefinition } from '../../shared/index.ts'
+
+export const exitPlanModeTool: ToolDefinition = {
+  name: 'ExitPlanMode',
+  description:
+    'Exit plan mode and submit your plan for approval. ' +
+    'Set approved: true to switch to acceptEdits mode (code changes allowed). ' +
+    'Set approved: false to revert to default mode. ' +
+    'Use this after you have finished designing your approach in plan mode.',
+  category: 'agent',
+  permission: 'auto',
+  parameters: {
+    type: 'object',
+    properties: {
+      approved: {
+        type: 'boolean',
+        description:
+          'Whether the user approved the plan. true → switch to acceptEdits mode. false → revert to default.',
+      },
+    },
+    required: ['approved'],
+  },
+  async execute(params, _ctx) {
+    const approved = params.approved === true
+
+    if (approved) {
+      return {
+        success: true,
+        content: [
+          '── Plan Approved ──',
+          '',
+          '✓ Exiting plan mode.',
+          '✓ Switching to acceptEdits mode — reads and file edits are auto-approved.',
+          '',
+          'You can now implement the plan. The plan file is in .mipham/plans/.',
+          '',
+          'Use Shift+Tab to cycle permission modes if you need to change.',
+        ].join('\n'),
+      }
+    }
+
+    return {
+      success: true,
+      content: [
+        '── Plan Mode Exited ──',
+        '',
+        '✓ Returning to default permission mode.',
+        '',
+        'No code changes were made. The plan file is preserved in .mipham/plans/.',
+        'Use EnterPlanMode again when ready to resume planning.',
+      ].join('\n'),
+    }
+  },
+}

package/src/tools/agent/report-findings.ts

@@ -0,0 +1,186 @@
+import type { ToolDefinition } from '../../shared/index.ts'
+
+export const reportFindingsTool: ToolDefinition = {
+  name: 'ReportFindings',
+  description:
+    'Report code-review findings as a typed list. ' +
+    'Use this to output structured review results with file, line, summary, ' +
+    'failure_scenario, and category. Findings are ranked most-severe first.',
+  category: 'agent',
+  permission: 'auto',
+  parameters: {
+    type: 'object',
+    properties: {
+      level: {
+        type: 'string',
+        enum: ['low', 'medium', 'high', 'xhigh', 'max'],
+        description: 'Effort level the review ran at.',
+      },
+      findings: {
+        type: 'array',
+        description: 'Verified findings, most-severe first; empty if none survived.',
+        minItems: 0,
+        maxItems: 32,
+        items: {
+          type: 'object',
+          properties: {
+            file: {
+              type: 'string',
+              description: 'Repo-relative path of the file the finding is in.',
+            },
+            line: {
+              type: 'integer',
+              description: '1-indexed line the finding anchors to.',
+            },
+            summary: {
+              type: 'string',
+              description: 'One-sentence statement of the defect.',
+            },
+            short_summary: {
+              type: 'string',
+              maxLength: 60,
+              description: 'Compressed label for compact UI (≤60 chars).',
+            },
+            failure_scenario: {
+              type: 'string',
+              description: 'Concrete inputs/state → wrong output/crash.',
+            },
+            category: {
+              type: 'string',
+              maxLength: 40,
+              description:
+                'Short kebab-case slug: correctness, security, performance, simplification, test-coverage, etc.',
+            },
+            verdict: {
+              type: 'string',
+              enum: ['CONFIRMED', 'PLAUSIBLE'],
+              description: 'Set when a verify pass ran; absent on inline-only reviews.',
+            },
+            outcome: {
+              type: 'string',
+              enum: ['fixed', 'skipped', 'no_change_needed'],
+              description:
+                'Set ONLY when re-reporting after applying fixes: what happened to this finding.',
+            },
+          },
+          required: ['file', 'summary', 'failure_scenario'],
+        },
+      },
+    },
+    required: ['findings'],
+  },
+
+  async execute(params, _ctx) {
+    const findings = params.findings as Array<Record<string, unknown>> | undefined
+    const level = (params.level as string) || 'medium'
+
+    if (!Array.isArray(findings)) {
+      return {
+        success: false,
+        content: '',
+        error: 'findings must be an array',
+      }
+    }
+
+    // Validate each finding has required fields
+    const errors: string[] = []
+    for (let i = 0; i < findings.length; i++) {
+      const f = findings[i]!
+      if (!f.file || typeof f.file !== 'string') {
+        errors.push(`findings[${i}]: "file" is required and must be a string`)
+      }
+      if (!f.summary || typeof f.summary !== 'string') {
+        errors.push(`findings[${i}]: "summary" is required and must be a string`)
+      }
+      if (!f.failure_scenario || typeof f.failure_scenario !== 'string') {
+        errors.push(`findings[${i}]: "failure_scenario" is required and must be a string`)
+      }
+      if (f.line !== undefined && typeof f.line !== 'number') {
+        errors.push(`findings[${i}]: "line" must be an integer if provided`)
+      }
+      if (f.verdict && !['CONFIRMED', 'PLAUSIBLE'].includes(f.verdict as string)) {
+        errors.push(`findings[${i}]: "verdict" must be CONFIRMED or PLAUSIBLE`)
+      }
+      if (f.outcome && !['fixed', 'skipped', 'no_change_needed'].includes(f.outcome as string)) {
+        errors.push(`findings[${i}]: "outcome" must be fixed, skipped, or no_change_needed`)
+      }
+    }
+
+    if (errors.length > 0) {
+      return {
+        success: false,
+        content: '',
+        error: `Validation errors:\n${errors.map((e) => `  • ${e}`).join('\n')}`,
+      }
+    }
+
+    if (findings.length === 0) {
+      return {
+        success: true,
+        content: `── Review Findings (${level} effort) ──\n\n✅ No findings to report.\n\nAll checks passed at ${level} effort level.`,
+      }
+    }
+
+    // Format findings as a structured report
+    const lines: string[] = [
+      `── Review Findings (${level} effort) ──`,
+      '',
+      `${findings.length} finding${findings.length === 1 ? '' : 's'}:`,
+      '',
+    ]
+
+    // Group by category for readability
+    const byCategory = new Map<string, Array<Record<string, unknown>>>()
+    for (const f of findings) {
+      const cat = (f.category as string) || 'uncategorized'
+      const list = byCategory.get(cat) || []
+      list.push(f)
+      byCategory.set(cat, list)
+    }
+
+    const CATEGORY_ICONS: Record<string, string> = {
+      correctness: '🔴',
+      security: '🔒',
+      performance: '⚡',
+      simplification: '🧹',
+      efficiency: '⏱️',
+      'test-coverage': '🧪',
+      architecture: '🏗️',
+      maintainability: '🔧',
+    }
+
+    for (const [category, items] of byCategory) {
+      const icon = CATEGORY_ICONS[category] || '📌'
+      lines.push(`${icon} ${category} (${items.length}):`)
+      for (const f of items) {
+        const verdict = f.verdict ? ` [${f.verdict}]` : ''
+        const outcome = f.outcome ? ` → ${f.outcome}` : ''
+        const lineRef = f.line ? `:${f.line}` : ''
+        lines.push(`  • ${f.file}${lineRef}${verdict}${outcome}`)
+        lines.push(`    ${f.summary}`)
+        if (f.failure_scenario) {
+          const scenario =
+            (f.failure_scenario as string).length > 120
+              ? (f.failure_scenario as string).slice(0, 120) + '...'
+              : (f.failure_scenario as string)
+          lines.push(`    💥 ${scenario}`)
+        }
+      }
+      lines.push('')
+    }
+
+    // Severity summary
+    const confirmed = findings.filter((f) => f.verdict === 'CONFIRMED').length
+    const plausible = findings.filter((f) => f.verdict === 'PLAUSIBLE').length
+    if (confirmed > 0 || plausible > 0) {
+      lines.push(
+        `📊 ${confirmed} CONFIRMED · ${plausible} PLAUSIBLE · ${findings.length - confirmed - plausible} unverified`,
+      )
+    }
+
+    return {
+      success: true,
+      content: lines.join('\n'),
+    }
+  },
+}

package/src/tools/agent/send-message.ts

@@ -0,0 +1,67 @@
+import type { ToolDefinition } from '../../shared/index.ts'
+import { getMessageBus } from '../../agent/message-bus'
+
+export const sendMessageTool: ToolDefinition = {
+  name: 'SendMessage',
+  description:
+    'Send a message to another agent or the main conversation. ' +
+    'Use "main" as the recipient to message the parent session, ' +
+    'or a background task ID (e.g., "bg-1-xxx") to message a specific agent. ' +
+    'Messages are stored in the AgentMessageBus and can be polled by the recipient.',
+  category: 'agent',
+  permission: 'auto',
+  parameters: {
+    type: 'object',
+    properties: {
+      to: {
+        type: 'string',
+        description:
+          'Recipient: "main" for the parent conversation, a background task ID, or an agent name.',
+      },
+      summary: {
+        type: 'string',
+        description: 'A 5-10 word summary shown as a one-line preview (max 200 chars).',
+      },
+      message: {
+        type: 'string',
+        description: 'Plain text message content.',
+      },
+    },
+    required: ['to', 'message'],
+  },
+  async execute(params, ctx) {
+    const to = params.to as string
+    const summary = (params.summary as string) || '(no subject)'
+    const message = params.message as string
+
+    // Determine sender: use sessionId or 'main'
+    const from =
+      ctx.sessionId === 'sub-agent'
+        ? `sub-agent-${Date.now().toString(36)}`
+        : ctx.sessionId || 'main'
+
+    try {
+      const bus = getMessageBus()
+      const msgId = bus.post(from, to, summary, message)
+
+      const unreadForRecipient = bus.unreadCount(to)
+
+      return {
+        success: true,
+        content:
+          `── Message Sent ──\n\n` +
+          `ID:      ${msgId}\n` +
+          `From:    ${from}\n` +
+          `To:      ${to}\n` +
+          `Summary: ${summary.slice(0, 100)}\n\n` +
+          `The recipient has ${unreadForRecipient} unread message(s).`,
+      }
+    } catch (err) {
+      return {
+        success: false,
+        content: '',
+        error: `Failed to send message: ${String(err)}`,
+      }
+    }
+  },
+}

package/src/tools/agent/workflow.ts

@@ -5,7 +5,9 @@ import type { QueryEngine } from '../../core/engine'
 export const workflowTool: ToolDefinition = {
   name: 'Workflow',
   description:
-    'Execute a multi-agent workflow script. The script uses agent(), parallel(), pipeline(), phase(), log(), args, budget primitives. Use for complex orchestrated tasks.',
+    'Execute a multi-agent workflow script. The script uses agent(), parallel(), pipeline(), phase(), log(), args, budget primitives. ' +
+    'Pass resumeFromRunId to resume a prior run — cached agent() calls are replayed from the journal, ' +
+    'and only new/changed calls execute live.',
   category: 'agent',
   permission: 'ask',
   parameters: {
@@ -20,12 +22,20 @@ export const workflowTool: ToolDefinition = {
         type: 'object',
         description: 'Arguments to pass to the workflow script as the `args` global',
       },
+      resumeFromRunId: {
+        type: 'string',
+        description:
+          'Run ID of a prior Workflow invocation to resume from. ' +
+          'Completed agent() calls with unchanged (prompt, opts) return cached results; ' +
+          'only edited or new calls re-run.',
+      },
     },
     required: ['script'],
   },
   async execute(params, ctx) {
     const script = params.script as string
     const args = (params.args as Record<string, unknown>) || {}
+    const resumeFromRunId = params.resumeFromRunId as string | undefined
 
     if (!ctx.registry || !ctx.toolRegistry) {
       return {
@@ -42,11 +52,21 @@ export const workflowTool: ToolDefinition = {
     } as QueryEngine
 
     try {
-      const { runId, result } = await runWorkflow(script, engineStub, args)
-      return {
-        success: true,
-        content: `Workflow ${runId} completed.\n\nResult:\n${typeof result === 'string' ? result : JSON.stringify(result, null, 2)}`,
+      const { runId, result, cacheHits, cacheMisses } = await runWorkflow(
+        script,
+        engineStub,
+        args,
+        null,
+        resumeFromRunId,
+      )
+
+      let content = `Workflow ${runId} completed.\n\n`
+      if (resumeFromRunId) {
+        content += `Cache: ${cacheHits} hits · ${cacheMisses} live\n\n`
       }
+      content += `Result:\n${typeof result === 'string' ? result : JSON.stringify(result, null, 2)}`
+
+      return { success: true, content }
     } catch (err) {
       return {
         success: false,