@miphamai/cli 0.9.0 → 0.11.0

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,

package/src/tools/exec/enter-worktree.ts

@@ -0,0 +1,142 @@
+import type { ToolDefinition } from '../../shared/index.ts'
+
+export const enterWorktreeTool: ToolDefinition = {
+  name: 'EnterWorktree',
+  description:
+    'Create an isolated git worktree for parallel development. ' +
+    'Creates a new worktree at .claude/worktrees/<name> on its own branch. ' +
+    'Use this when you need to work on a separate task without affecting the main workspace. ' +
+    'Pair with ExitWorktree to clean up when done.',
+  category: 'exec',
+  permission: 'ask',
+  parameters: {
+    type: 'object',
+    properties: {
+      name: {
+        type: 'string',
+        description:
+          'Name for the new worktree. Each "/"-separated segment may contain only letters, digits, dots, underscores, and dashes; max 64 chars total.',
+      },
+      baseRef: {
+        type: 'string',
+        description:
+          'Base branch or ref to create from. Default: the current HEAD. Use "origin/main" or a branch name to start from a specific point.',
+      },
+    },
+    required: ['name'],
+  },
+  async execute(params, ctx) {
+    const name = params.name as string
+    const baseRef = (params.baseRef as string) || 'HEAD'
+
+    // Validate name
+    if (name.length > 64) {
+      return {
+        success: false,
+        content: '',
+        error: 'Worktree name must be 64 characters or fewer.',
+      }
+    }
+    if (!/^[a-zA-Z0-9._/-]+$/.test(name)) {
+      return {
+        success: false,
+        content: '',
+        error:
+          'Worktree name may only contain letters, digits, dots, underscores, dashes, and slashes.',
+      }
+    }
+
+    const cwd = ctx.cwd
+    const worktreePath = `${cwd}/.claude/worktrees/${name}`
+
+    try {
+      // Validate we're in a git repo
+      const gitCheck = Bun.spawn(['git', 'rev-parse', '--git-dir'], {
+        cwd,
+        stdout: 'pipe',
+        stderr: 'pipe',
+      })
+      const gitCheckExit = await gitCheck.exited
+      if (gitCheckExit !== 0) {
+        return {
+          success: false,
+          content: '',
+          error: 'Not in a git repository. EnterWorktree requires a git working directory.',
+        }
+      }
+
+      // Check if worktree already exists
+      const checkProc = Bun.spawn(['git', 'worktree', 'list', '--porcelain'], {
+        cwd,
+        stdout: 'pipe',
+        stderr: 'pipe',
+      })
+      const existingWorktrees = await new Response(checkProc.stdout).text()
+      if (existingWorktrees.includes(worktreePath)) {
+        return {
+          success: true,
+          content:
+            `── Worktree Already Exists ──\n\n` +
+            `Path:    ${worktreePath}\n` +
+            `Name:    ${name}\n\n` +
+            `This worktree already exists. To use it:\n` +
+            `  cd ${worktreePath}\n\n` +
+            `To remove it, use ExitWorktree.`,
+        }
+      }
+
+      // Determine base ref
+      let resolvedBaseRef = baseRef
+      if (baseRef === 'HEAD') {
+        try {
+          const branchProc = Bun.spawn(['git', 'rev-parse', '--abbrev-ref', 'HEAD'], {
+            cwd,
+            stdout: 'pipe',
+            stderr: 'pipe',
+          })
+          const branch = (await new Response(branchProc.stdout).text()).trim()
+          resolvedBaseRef = branch || 'HEAD'
+        } catch {
+          resolvedBaseRef = 'HEAD'
+        }
+      }
+
+      // Create worktree with new branch
+      const branchName = `worktree/${name}`
+      const proc = Bun.spawn(
+        ['git', 'worktree', 'add', '-b', branchName, worktreePath, resolvedBaseRef],
+        { cwd, stdout: 'pipe', stderr: 'pipe' },
+      )
+      const stdout = await new Response(proc.stdout).text()
+      const exitCode = await proc.exited
+
+      if (exitCode !== 0) {
+        const stderr = await new Response(proc.stderr).text()
+        return {
+          success: false,
+          content: '',
+          error: `Failed to create worktree: ${stderr.slice(0, 1000)}`,
+        }
+      }
+
+      return {
+        success: true,
+        content:
+          `── Worktree Created ──\n\n` +
+          `Path:      ${worktreePath}\n` +
+          `Branch:    ${branchName}\n` +
+          `Base:      ${resolvedBaseRef}\n\n` +
+          `The worktree is ready. To switch to it:\n` +
+          `  cd ${worktreePath}\n\n` +
+          `Work in the worktree is isolated — changes on "${branchName}" won't affect your main branch.\n` +
+          `When done, use ExitWorktree to clean up.`,
+      }
+    } catch (err) {
+      return {
+        success: false,
+        content: '',
+        error: `Worktree creation failed: ${String(err)}`,
+      }
+    }
+  },
+}

package/src/tools/exec/exit-worktree.ts

@@ -0,0 +1,162 @@
+import type { ToolDefinition } from '../../shared/index.ts'
+
+export const exitWorktreeTool: ToolDefinition = {
+  name: 'ExitWorktree',
+  description:
+    'Remove a git worktree created by EnterWorktree. ' +
+    'Use action "remove" to delete the worktree and its branch, ' +
+    'or "keep" to leave it intact on disk.',
+  category: 'exec',
+  permission: 'ask',
+  parameters: {
+    type: 'object',
+    properties: {
+      path: {
+        type: 'string',
+        description: 'Absolute path to the worktree to exit. Must be under .claude/worktrees/.',
+      },
+      action: {
+        type: 'string',
+        enum: ['keep', 'remove'],
+        description:
+          '"keep" leaves the worktree and branch on disk. "remove" deletes both the worktree directory and its branch.',
+      },
+      discard_changes: {
+        type: 'boolean',
+        description:
+          'Required true when action is "remove" and the worktree has uncommitted files or unmerged commits. The tool will refuse and list them otherwise.',
+      },
+    },
+    required: ['path', 'action'],
+  },
+  async execute(params, ctx) {
+    const worktreePath = params.path as string
+    const action = params.action as string
+    const discardChanges = params.discard_changes === true
+
+    // Validate the path is under .claude/worktrees
+    const cwd = ctx.cwd
+
+    try {
+      // Verify the worktree exists in git's worktree list
+      const listProc = Bun.spawn(['git', 'worktree', 'list', '--porcelain'], {
+        cwd,
+        stdout: 'pipe',
+        stderr: 'pipe',
+      })
+      const listOutput = await new Response(listProc.stdout).text()
+
+      if (!listOutput.includes(worktreePath)) {
+        return {
+          success: false,
+          content: '',
+          error:
+            `Worktree not found: ${worktreePath}\n\n` +
+            `This path is not in git's worktree list. It may have already been removed, ` +
+            `or it was created outside of EnterWorktree.\n\n` +
+            `Use "git worktree list" to see active worktrees.`,
+        }
+      }
+
+      if (action === 'keep') {
+        return {
+          success: true,
+          content:
+            `── Worktree Kept ──\n\n` +
+            `Path:   ${worktreePath}\n\n` +
+            `The worktree and its branch are preserved on disk.\n` +
+            `To remove later: ExitWorktree with action="remove".`,
+        }
+      }
+
+      // action === 'remove' — check for uncommitted changes
+      if (!discardChanges) {
+        const statusProc = Bun.spawn(['git', '-C', worktreePath, 'status', '--porcelain'], {
+          cwd,
+          stdout: 'pipe',
+          stderr: 'pipe',
+        })
+        const statusOutput = await new Response(statusProc.stdout).text()
+        const changedFiles = statusOutput.trim().split('\n').filter(Boolean)
+
+        if (changedFiles.length > 0) {
+          const preview = changedFiles.slice(0, 10).join('\n')
+          const extra =
+            changedFiles.length > 10 ? `\n... and ${changedFiles.length - 10} more files` : ''
+          return {
+            success: false,
+            content: '',
+            error:
+              `Worktree has ${changedFiles.length} uncommitted file(s):\n\n` +
+              `${preview}${extra}\n\n` +
+              `Set discard_changes: true to force removal and discard these changes.\n` +
+              `Or commit the changes first, then retry.`,
+          }
+        }
+      }
+
+      // Get the branch name from worktree metadata
+      let branchName = ''
+      try {
+        const branchProc = Bun.spawn(
+          ['git', '-C', worktreePath, 'rev-parse', '--abbrev-ref', 'HEAD'],
+          { cwd, stdout: 'pipe', stderr: 'pipe' },
+        )
+        branchName = (await new Response(branchProc.stdout).text()).trim()
+      } catch {
+        // Branch detection is best-effort
+      }
+
+      // Remove the worktree
+      const removeArgs = discardChanges
+        ? ['git', 'worktree', 'remove', '--force', worktreePath]
+        : ['git', 'worktree', 'remove', worktreePath]
+
+      const removeProc = Bun.spawn(removeArgs, {
+        cwd,
+        stdout: 'pipe',
+        stderr: 'pipe',
+      })
+      const removeExit = await removeProc.exited
+
+      if (removeExit !== 0) {
+        const stderr = await new Response(removeProc.stderr).text()
+        return {
+          success: false,
+          content: '',
+          error: `Failed to remove worktree: ${stderr.slice(0, 1000)}`,
+        }
+      }
+
+      // Clean up the branch if we have its name
+      if (branchName && branchName !== 'HEAD') {
+        try {
+          const branchProc = Bun.spawn(['git', 'branch', '-D', branchName], {
+            cwd,
+            stdout: 'pipe',
+            stderr: 'pipe',
+          })
+          await branchProc.exited
+          // Best-effort — branch cleanup failure is not fatal
+        } catch {
+          // Ignore branch cleanup failures
+        }
+      }
+
+      return {
+        success: true,
+        content:
+          `── Worktree Removed ──\n\n` +
+          `Path:    ${worktreePath}\n` +
+          (branchName ? `Branch:  ${branchName} (deleted)\n` : '') +
+          `\nThe worktree has been removed.`,
+      }
+    } catch (err) {
+      return {
+        success: false,
+        content: '',
+        error: `Worktree removal failed: ${String(err)}`,
+      }
+    }
+  },
+}