@miphamai/cli 0.9.0 → 0.11.0

package/src/core/engine.ts

@@ -9,6 +9,8 @@ import { analyzeForMemory } from './memory/memory-writer'
 import { getMemoryManager } from './memory/memory-loader'
 import type { AgentViewManager } from '../agent-view/agent-view-manager'
 import type { SkillsLoader } from '../skills/loader'
+import { getBackgroundAgentRegistry } from '../agent/background-registry'
+import { RulesLoader } from './rules-loader'
 
 export class QueryEngine {
   private hookEngine?: HookEngine
@@ -70,6 +72,77 @@ export class QueryEngine {
     this.skillsLoader = loader
   }
 
+  /** Rules loader for path-scoped rules injection. */
+  private rulesLoader?: RulesLoader
+  /** Files touched in the current turn (for rules matching). */
+  private touchedFiles: Set<string> = new Set()
+
+  /** Register the rules loader. */
+  setRulesLoader(loader: RulesLoader): void {
+    this.rulesLoader = loader
+    this.rulesLoader.load()
+  }
+
+  /** Pending task notifications from background agents (cleared after draining). */
+  private pendingTaskNotifications: Array<StreamChunk> = []
+
+  /** Track files touched by tools for rules matching. */
+  private trackTouchedFile(toolName: string, params: Record<string, unknown>): void {
+    const fileTools = ['Read', 'Write', 'Edit', 'Glob', 'Grep']
+    if (!fileTools.includes(toolName)) return
+    const filePath = (params.file_path || params.path || params.file) as string | undefined
+    if (filePath && typeof filePath === 'string') {
+      this.touchedFiles.add(filePath)
+    }
+  }
+
+  /** Inject matching rules as context after tool execution. */
+  private injectRules(): void {
+    if (!this.rulesLoader || this.touchedFiles.size === 0) return
+    const files = Array.from(this.touchedFiles)
+    const block = this.rulesLoader.buildContextBlock(files)
+    if (!block) return
+    this.context.addMessage({ role: 'user', content: block })
+    this.touchedFiles.clear()
+  }
+
+  /**
+   * Drain pending background task notifications.
+   * Call this after tool execution to surface completed/failed background agent results.
+   * Returns an array of StreamChunks that can be yielded in a generator.
+   */
+  drainTaskNotifications(): StreamChunk[] {
+    const bgRegistry = getBackgroundAgentRegistry()
+    const tasks = bgRegistry.list()
+    const chunks: StreamChunk[] = []
+
+    for (const task of tasks) {
+      if (task.status === 'running') continue
+
+      // Check if we've already notified for this task
+      const alreadyNotified = this.pendingTaskNotifications.some(
+        (n) => n.taskNotification?.taskId === task.id,
+      )
+      if (alreadyNotified) continue
+
+      const chunk: StreamChunk = {
+        type: 'task_notification',
+        taskNotification: {
+          taskId: task.id,
+          status: task.status as 'completed' | 'failed',
+          description: task.description,
+          content: task.result,
+          error: task.error,
+        },
+      }
+
+      this.pendingTaskNotifications.push(chunk)
+      chunks.push(chunk)
+    }
+
+    return chunks
+  }
+
   /** Set the session goal for goal-driven execution. */
   setGoal(
     goal: string,
@@ -310,6 +383,14 @@ export class QueryEngine {
       })
     }
 
+    // Inject path-scoped rules for touched files
+    this.injectRules()
+
+    // Drain task notifications after tool execution
+    for (const chunk of this.drainTaskNotifications()) {
+      yield chunk
+    }
+
     // If tools were executed, recursively continue the conversation
     if (toolUses.length > 0) {
       yield* this.continueWithTools(signal)
@@ -318,6 +399,11 @@ export class QueryEngine {
 
     // Fire Stop hooks when AI finishes with no tool calls
     yield* this.checkStopHook(signal)
+
+    // Final drain of task notifications
+    for (const chunk of this.drainTaskNotifications()) {
+      yield chunk
+    }
   }
 
   async *processWithGoal(input: string, signal?: AbortSignal): AsyncGenerator<StreamChunk> {
@@ -579,8 +665,12 @@ export class QueryEngine {
         toolRegistry: this.tools,
         artifactServer: this.artifactServer,
         agentRegistry: this.agentRegistry,
+        backgroundAgentRegistry: getBackgroundAgentRegistry(),
       })
 
+      // Track touched files for rules matching
+      this.trackTouchedFile(name, effectiveParams)
+
       // Run PostToolUse hooks
       if (this.hookEngine) {
         await this.hookEngine.executePostToolUse(name, effectiveParams, result, 'session-1')

package/src/core/hooks.ts

@@ -107,6 +107,54 @@ export class HookEngine {
     return this.runHooks('ConfigChange', undefined, ctx)
   }
 
+  /** SubagentStart: fires when a sub-agent begins execution. */
+  async executeSubagentStart(
+    agentType: string,
+    description: string,
+    sessionId: string,
+  ): Promise<HookResult> {
+    const ctx: HookContext = {
+      event: 'SubagentStart',
+      sessionId,
+      toolInput: { agentType, description },
+    }
+    return this.runHooks('SubagentStart', undefined, ctx)
+  }
+
+  /** SubagentStop: fires when a sub-agent completes (success or failure). */
+  async executeSubagentStop(
+    agentType: string,
+    description: string,
+    sessionId: string,
+    success: boolean,
+    result?: string,
+  ): Promise<HookResult> {
+    const ctx: HookContext = {
+      event: 'SubagentStop',
+      sessionId,
+      toolInput: { agentType, description, success },
+      toolResult: result ? { success, content: result.slice(0, 2000) } : undefined,
+    }
+    return this.runHooks('SubagentStop', undefined, ctx)
+  }
+
+  /** PostToolUseFailure: fires when a tool call fails. */
+  async executePostToolUseFailure(
+    toolName: string,
+    toolInput: Record<string, unknown>,
+    error: string,
+    sessionId: string,
+  ): Promise<HookResult> {
+    const ctx: HookContext = {
+      event: 'PostToolUseFailure',
+      toolName,
+      toolInput,
+      toolResult: { success: false, content: '', error },
+      sessionId,
+    }
+    return this.runHooks('PostToolUseFailure', toolName, ctx)
+  }
+
   // ── Core execution ──
 
   private async runHooks(

package/src/core/output-styles.ts

@@ -0,0 +1,95 @@
+/**
+ * OutputStylesLoader — loads custom response persona styles from .mipham/output-styles/.
+ *
+ * Each .md file in the directory is a named style. The active style's content
+ * is injected into the system prompt to shape the AI's tone and communication style.
+ *
+ * Usage:
+ *   const loader = new OutputStylesLoader(cwd)
+ *   loader.list()               // ['concise', 'academic', ...]
+ *   loader.get('concise')       // style content or undefined
+ *   loader.setActive('concise') // switch active style
+ *   loader.getActiveContent()   // active style content (for system prompt)
+ */
+
+import { readdirSync, readFileSync, existsSync } from 'node:fs'
+import { join, basename, extname } from 'node:path'
+
+export class OutputStylesLoader {
+  private stylesDir: string
+  private activeStyle: string | null = null
+
+  constructor(cwd: string) {
+    this.stylesDir = join(cwd, '.mipham', 'output-styles')
+  }
+
+  /**
+   * List all available style names (filename without .md extension).
+   */
+  list(): string[] {
+    if (!existsSync(this.stylesDir)) return []
+    try {
+      return readdirSync(this.stylesDir)
+        .filter((f) => f.endsWith('.md'))
+        .map((f) => basename(f, extname(f)))
+    } catch {
+      return []
+    }
+  }
+
+  /**
+   * Get the content of a named style. Returns undefined if not found.
+   */
+  get(name: string): string | undefined {
+    if (!existsSync(this.stylesDir)) return undefined
+    const filepath = join(this.stylesDir, `${name}.md`)
+    if (!existsSync(filepath)) return undefined
+    try {
+      return readFileSync(filepath, 'utf-8').trim()
+    } catch {
+      return undefined
+    }
+  }
+
+  /**
+   * Set the active output style.
+   */
+  setActive(name: string): boolean {
+    const content = this.get(name)
+    if (!content) return false
+    this.activeStyle = name
+    return true
+  }
+
+  /**
+   * Clear the active output style (revert to default personality).
+   */
+  clearActive(): void {
+    this.activeStyle = null
+  }
+
+  /**
+   * Get the active style name (null if none selected).
+   */
+  getActiveName(): string | null {
+    return this.activeStyle
+  }
+
+  /**
+   * Get the active style content for system prompt injection.
+   * Returns empty string if no style is active.
+   */
+  getActiveContent(): string {
+    if (!this.activeStyle) return ''
+    const content = this.get(this.activeStyle)
+    if (!content) return ''
+    return [
+      `[Output Style: ${this.activeStyle}]`,
+      'Adopt the following communication style in all your responses:',
+      '',
+      content,
+      '',
+      '---',
+    ].join('\n')
+  }
+}

package/src/core/rules-loader.ts

@@ -0,0 +1,175 @@
+/**
+ * RulesLoader — path-scoped rules from .mipham/rules/.
+ *
+ * Rules are markdown files with YAML frontmatter. They are injected into
+ * the conversation when the AI touches matching files.
+ *
+ * Directory structure:
+ *   .mipham/rules/
+ *     always.md        — always loaded (no paths filter)
+ *     typescript.md    — loaded when touching *.ts files
+ *     security.md      — loaded when touching auth/ or crypto/ paths
+ *
+ * Frontmatter:
+ *   ---
+ *   paths: "apps/cli/src/**\/*.ts"
+ *   description: TypeScript coding standards
+ *   ---
+ */
+
+import { readdirSync, readFileSync, existsSync } from 'node:fs'
+import { join, relative } from 'node:path'
+
+interface RuleFile {
+  name: string
+  paths: string[] // glob patterns, empty = always loaded
+  description: string
+  content: string
+}
+
+export class RulesLoader {
+  private rules: RuleFile[] = []
+  private rulesDir: string
+
+  constructor(cwd: string) {
+    this.rulesDir = join(cwd, '.mipham', 'rules')
+  }
+
+  /**
+   * Load all rules from .mipham/rules/. Call once at startup.
+   */
+  load(): void {
+    this.rules = []
+    if (!existsSync(this.rulesDir)) return
+
+    try {
+      const files = readdirSync(this.rulesDir).filter((f) => f.endsWith('.md'))
+      for (const file of files) {
+        const filepath = join(this.rulesDir, file)
+        try {
+          const raw = readFileSync(filepath, 'utf-8')
+          const { paths, description, content } = this.parseRule(raw, file)
+          this.rules.push({ name: file.replace(/\.md$/, ''), paths, description, content })
+        } catch {
+          // Skip unparseable files
+        }
+      }
+    } catch {
+      // Directory read error — rules unavailable
+    }
+  }
+
+  /**
+   * Get rules that match the given file paths.
+   * Rules with no paths filter ("always") are always included.
+   */
+  getMatchingRules(touchedFiles: string[]): RuleFile[] {
+    const matched: RuleFile[] = []
+
+    for (const rule of this.rules) {
+      // Always rules — no paths filter
+      if (rule.paths.length === 0) {
+        matched.push(rule)
+        continue
+      }
+
+      // Check if any touched file matches any rule path pattern
+      for (const file of touchedFiles) {
+        for (const pattern of rule.paths) {
+          if (this.matchPath(file, pattern)) {
+            matched.push(rule)
+            // Break inner loops — rule already matched
+            break
+          }
+        }
+        if (matched.includes(rule)) break
+      }
+    }
+
+    return matched
+  }
+
+  /**
+   * Build a context block to inject into the conversation.
+   */
+  buildContextBlock(touchedFiles: string[]): string {
+    const matched = this.getMatchingRules(touchedFiles)
+    if (matched.length === 0) return ''
+
+    const blocks = matched.map(
+      (r) => `[Rule: ${r.name}]${r.description ? ` — ${r.description}` : ''}\n${r.content}`,
+    )
+    return `\n<!-- Path-scoped rules matching: ${touchedFiles.join(', ')} -->\n${blocks.join('\n\n')}\n`
+  }
+
+  /**
+   * Count loaded rules.
+   */
+  count(): number {
+    return this.rules.length
+  }
+
+  /**
+   * List loaded rule names.
+   */
+  list(): string[] {
+    return this.rules.map((r) => r.name)
+  }
+
+  /**
+   * Simple glob matching. Supports **, *, and exact file matching.
+   * Returns true if file matches pattern.
+   */
+  private matchPath(file: string, pattern: string): boolean {
+    // Convert glob pattern to regex
+    let regexStr = pattern
+      .replace(/\./g, '\\.')
+      .replace(/\*\*/g, '<<GLOBSTAR>>')
+      .replace(/\*/g, '[^/]*')
+      .replace(/<<GLOBSTAR>>/g, '.*')
+
+    // If pattern doesn't start with ** or *, anchor to be a suffix match
+    if (!pattern.startsWith('**') && !pattern.startsWith('*')) {
+      regexStr = regexStr + '$'
+    }
+
+    try {
+      return new RegExp(regexStr).test(file)
+    } catch {
+      // Invalid pattern — fallback to simple includes
+      return file.includes(pattern.replace(/\*\*/g, '').replace(/\*/g, ''))
+    }
+  }
+
+  /**
+   * Parse a rule file — extract frontmatter and body.
+   */
+  private parseRule(
+    raw: string,
+    filename: string,
+  ): { paths: string[]; description: string; content: string } {
+    const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/)
+    if (!match) {
+      return { paths: [], description: '', content: raw.trim() }
+    }
+
+    const frontmatter = match[1] || ''
+    const body = (match[2] || '').trim()
+
+    const paths: string[] = []
+    let description = ''
+
+    for (const line of frontmatter.split('\n')) {
+      const pathMatch = line.match(/^paths:\s*"(.+)"$/)
+      if (pathMatch) {
+        pathMatch[1]!.split(',').forEach((p) => paths.push(p.trim()))
+      }
+      const descMatch = line.match(/^description:\s*(.+)$/)
+      if (descMatch) {
+        description = descMatch[1]!.trim()
+      }
+    }
+
+    return { paths, description, content: body }
+  }
+}

package/src/mcp/client.ts

@@ -151,6 +151,15 @@ export class McpClient {
     return this.connections.get(name)?.tools || []
   }
 
+  /** List all currently connected MCP server names. */
+  getConnectedServers(): string[] {
+    const names: string[] = []
+    for (const [name, conn] of this.connections) {
+      if (conn.status === 'connected') names.push(name)
+    }
+    return names
+  }
+
   async callTool(
     serverName: string,
     toolName: string,

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'),
+    }
+  },
+}