@miphamai/cli 0.33.0 → 0.33.2

package/src/core/hooks.ts

@@ -6,6 +6,29 @@ import type {
   ToolResult,
 } from '../shared/index.ts'
 
+// ── Hook resilience types ──
+
+interface HookHealth {
+  /** Consecutive failure count */
+  failures: number
+  /** Timestamp of last failure (ms since epoch) */
+  lastFailureTime: number
+  /** Whether the hook is currently disabled due to repeated failures */
+  disabled: boolean
+  /** Timestamp when disabled (ms since epoch) */
+  disabledAt: number
+  /** Total failure count (lifetime) */
+  totalFailures: number
+}
+
+/** Max consecutive failures before auto-disabling a hook */
+const MAX_CONSECUTIVE_FAILURES = 5
+
+/** Cooldown period in ms before a disabled hook is re-tried (5 minutes) */
+const COOLDOWN_MS = 5 * 60 * 1000
+
+// ── Helpers ──
+
 /**
  * Merge two permission decisions, keeping the more restrictive one.
  * Priority: deny > defer > ask > allow
@@ -22,6 +45,8 @@ export function mergePermissionDecision(
 
 export class HookEngine {
   private hooks: HookDefinition[] = []
+  /** Health tracking per hook key (event[:toolName]) */
+  private health = new Map<string, HookHealth>()
 
   register(hook: HookDefinition): void {
     this.hooks.push(hook)
@@ -71,31 +96,26 @@ export class HookEngine {
 
   // ── NEW event executors ──
 
-  /** Stop hook: fires when AI completes a turn. Can block to force continuation. */
   async executeStop(sessionId: string): Promise<HookResult> {
     const ctx: HookContext = { event: 'Stop', sessionId }
     return this.runHooks('Stop', undefined, ctx)
   }
 
-  /** UserPromptSubmit: fires when user submits input. Can block malicious input. */
   async executeUserPromptSubmit(prompt: string, sessionId: string): Promise<HookResult> {
     const ctx: HookContext = { event: 'UserPromptSubmit', sessionId, userPrompt: prompt }
     return this.runHooks('UserPromptSubmit', undefined, ctx)
   }
 
-  /** PreCompact: fires before context compaction. */
   async executePreCompact(sessionId: string): Promise<HookResult> {
     const ctx: HookContext = { event: 'PreCompact', sessionId }
     return this.runHooks('PreCompact', undefined, ctx)
   }
 
-  /** PostCompact: fires after context compaction. Can inject additional context. */
   async executePostCompact(sessionId: string): Promise<HookResult> {
     const ctx: HookContext = { event: 'PostCompact', sessionId }
     return this.runHooks('PostCompact', undefined, ctx)
   }
 
-  /** ConfigChange: fires when configuration changes. */
   async executeConfigChange(key: string, value: unknown, sessionId: string): Promise<HookResult> {
     const ctx: HookContext = {
       event: 'ConfigChange',
@@ -106,7 +126,6 @@ export class HookEngine {
     return this.runHooks('ConfigChange', undefined, ctx)
   }
 
-  /** SubagentStart: fires when a sub-agent begins execution. */
   async executeSubagentStart(
     agentType: string,
     description: string,
@@ -120,7 +139,6 @@ export class HookEngine {
     return this.runHooks('SubagentStart', undefined, ctx)
   }
 
-  /** SubagentStop: fires when a sub-agent completes (success or failure). */
   async executeSubagentStop(
     agentType: string,
     description: string,
@@ -137,7 +155,6 @@ export class HookEngine {
     return this.runHooks('SubagentStop', undefined, ctx)
   }
 
-  /** PostToolUseFailure: fires when a tool call fails. */
   async executePostToolUseFailure(
     toolName: string,
     toolInput: Record<string, unknown>,
@@ -154,7 +171,6 @@ export class HookEngine {
     return this.runHooks('PostToolUseFailure', toolName, ctx)
   }
 
-  /** PreInference: fires before every model API call for DLP inspection. */
   async executePreInference(
     messages: Array<{ role: string; content: string }>,
     toolCalls: Array<{
@@ -177,6 +193,79 @@ export class HookEngine {
     return this.runHooks('PreInference', undefined, ctx)
   }
 
+  // ── Health & Resilience ──
+
+  /** Get a hook health key for tracking. */
+  private healthKey(hook: HookDefinition): string {
+    return hook.toolName ? `${hook.event}:${hook.toolName}` : hook.event
+  }
+
+  /** Check if a hook should be skipped due to repeated failures. */
+  private shouldSkip(key: string): boolean {
+    const h = this.health.get(key)
+    if (!h) return false
+
+    // If disabled, check cooldown
+    if (h.disabled) {
+      const elapsed = Date.now() - h.disabledAt
+      if (elapsed < COOLDOWN_MS) {
+        return true // still in cooldown
+      }
+      // Cooldown expired — re-enable for a trial
+      h.disabled = false
+      h.failures = 0
+      process.stderr.write(`🔄 Hook "${key}" cooldown expired — re-enabled for trial.\n`)
+      return false
+    }
+
+    return false
+  }
+
+  /** Record a hook success — resets failure counter. */
+  private recordSuccess(key: string): void {
+    const h = this.health.get(key)
+    if (h) {
+      h.failures = 0
+      h.disabled = false
+    }
+  }
+
+  /** Record a hook failure — may trigger auto-disable. */
+  private recordFailure(key: string): void {
+    let h = this.health.get(key)
+    if (!h) {
+      h = { failures: 0, lastFailureTime: 0, disabled: false, disabledAt: 0, totalFailures: 0 }
+      this.health.set(key, h)
+    }
+
+    h.failures++
+    h.totalFailures++
+    h.lastFailureTime = Date.now()
+
+    if (h.failures >= MAX_CONSECUTIVE_FAILURES && !h.disabled) {
+      h.disabled = true
+      h.disabledAt = Date.now()
+      process.stderr.write(
+        `⚠️  Hook "${key}" failed ${MAX_CONSECUTIVE_FAILURES} consecutive times — auto-disabled for ${COOLDOWN_MS / 60_000} minutes.\n` +
+          `   Use /hooks enable "${key}" to re-enable manually.\n`,
+      )
+    }
+  }
+
+  /** Get the health status of all hooks. */
+  getHookHealth(): Array<{ key: string; health: HookHealth }> {
+    return Array.from(this.health.entries()).map(([key, health]) => ({ key, health }))
+  }
+
+  /** Manually re-enable a disabled hook. */
+  reEnableHook(key: string): boolean {
+    const h = this.health.get(key)
+    if (!h || !h.disabled) return false
+    h.disabled = false
+    h.failures = 0
+    return true
+  }
+
   // ── Core execution ──
 
   private async runHooks(
@@ -191,9 +280,23 @@ export class HookEngine {
     const result: HookResult = { allowed: true }
 
     for (const hook of matching) {
+      const key = this.healthKey(hook)
+
+      // ── Resilience: skip disabled hooks ──
+      if (this.shouldSkip(key)) {
+        result.additionalContext = result.additionalContext
+          ? result.additionalContext +
+            `\n[Hook "${key}" skipped — temporarily disabled after repeated failures]`
+          : `[Hook "${key}" skipped — temporarily disabled after repeated failures]`
+        continue
+      }
+
       try {
         const hookResult = await hook.handler(ctx)
 
+        // Record success
+        this.recordSuccess(key)
+
         // Block on first deny — stops further hook execution
         if (!hookResult.allowed) {
           return { ...hookResult }
@@ -233,6 +336,8 @@ export class HookEngine {
           result.updatedOutput = hookResult.updatedOutput
         }
       } catch {
+        // Record failure — may trigger auto-disable
+        this.recordFailure(key)
         // Hook failures do not block execution
       }
     }

package/src/shared/types.ts

@@ -73,6 +73,8 @@ export interface ToolContext {
   backgroundAgentRegistry?: import('../agent/background-registry').BackgroundAgentRegistry
   permissionSystem?: import('../core/permission').PermissionSystem
   ruleEngine?: import('../core/rule-engine').ExperienceRuleEngine
+  /** Files read this session — used by Write tool to check read-before-write */
+  readFiles?: Set<string>
 }
 
 // ── Artifact Types ──

package/src/skills/fork-executor.ts

@@ -3,6 +3,7 @@ import type { ProviderRegistry } from '../providers/registry'
 import type { ToolDefinition, SkillDefinition } from '../shared/index.ts'
 import type { AgentDefinition } from '../agent/types'
 import type { PermissionSystem } from '../core/permission'
+import { sanitizeSkillDescription } from './sanitizer.js'
 
 /**
  * Execute a skill in an isolated subagent context (context: fork).
@@ -10,6 +11,8 @@ import type { PermissionSystem } from '../core/permission'
  * The skill's markdown body becomes the subagent's system prompt.
  * The skill's allowed-tools become the subagent's tool whitelist.
  * Results are returned to the AI as internal context (not shown directly to user).
+ *
+ * Safety: skill description is sanitized before injection into subagent prompt.
  */
 export async function executeForkedSkill(
   skill: SkillDefinition,
@@ -20,7 +23,7 @@ export async function executeForkedSkill(
 ): Promise<string> {
   const agentDef: AgentDefinition = {
     name: `skill:${skill.name}`,
-    description: skill.description,
+    description: sanitizeSkillDescription(skill.description, skill.type),
     systemPrompt: buildSkillSystemPrompt(skill),
     tools: skill.allowedTools?.join(', '),
     model: skill.model || 'inherit',
@@ -38,5 +41,6 @@ export async function executeForkedSkill(
 }
 
 function buildSkillSystemPrompt(skill: SkillDefinition): string {
-  return `You are executing the "${skill.name}" skill (v${skill.version}).\n\n${skill.description}\n\nFollow the skill instructions precisely and return results.`
+  const safeDescription = sanitizeSkillDescription(skill.description, skill.type)
+  return `You are executing the "${skill.name}" skill (v${skill.version}).\n\n${safeDescription}\n\nFollow the skill instructions precisely and return results.`
 }

package/src/skills/loader.ts

@@ -3,6 +3,7 @@ import { join } from 'node:path'
 import { homedir } from 'node:os'
 import { parse as parseYaml } from 'yaml'
 import type { SkillDefinition } from '../shared/index.ts'
+import { sanitizeSkillDescription, sanitizeSkillBody, checkSkillShadow } from './sanitizer.js'
 
 interface FrontmatterResult {
   data: Record<string, unknown>
@@ -100,12 +101,43 @@ export class SkillsLoader {
       const raw = readFileSync(path, 'utf-8')
       const { data, content } = parseFrontmatter(raw)
 
+      const rawDescription = (data.description as string) || ''
+      const rawBody = content.trim() || undefined
+      const skillName = (data.name as string) || this.nameFromPath(path)
+
+      // ── Safety: check for command/MCP shadowing ──
+      const shadowCheck = checkSkillShadow(skillName, rawDescription)
+      if (shadowCheck.shadowed) {
+        process.stderr.write(
+          `⚠️  Skill "${skillName}" shadows ${shadowCheck.conflictType} "${shadowCheck.conflictsWith}" — skipped for safety. Rename the skill and reload.\n`,
+        )
+        return
+      }
+
+      // ── Safety: sanitize description ──
+      const description = sanitizeSkillDescription(
+        rawDescription,
+        type === 'mipham' ? undefined : type,
+      )
+
+      // ── Safety: sanitize body ──
+      let body: string | undefined
+      if (rawBody) {
+        const bodyResult = sanitizeSkillBody(rawBody)
+        body = bodyResult.text
+        if (bodyResult.warnings.length > 0) {
+          process.stderr.write(
+            `⚠️  Skill "${skillName}" body sanitized: ${bodyResult.warnings.join('; ')}\n`,
+          )
+        }
+      }
+
       const skill: SkillDefinition = {
-        name: (data.name as string) || this.nameFromPath(path),
-        description: (data.description as string) || '',
+        name: skillName,
+        description,
         version: (data.version as string) || '0.1.0',
         type,
-        body: content.trim() || undefined,
+        body,
         tools: data.tools as SkillDefinition['tools'],
         hooks: data.hooks as SkillDefinition['hooks'],
         prompts: data.prompts as SkillDefinition['prompts'],
@@ -143,7 +175,8 @@ export class SkillsLoader {
 
     let tokenBudget = 0
     for (const skill of skills) {
-      const entry = `- ${skill.name}: ${skill.description}`
+      const safeDesc = sanitizeSkillDescription(skill.description, skill.type)
+      const entry = `- ${skill.name}: ${safeDesc}`
       const entryTokens = Math.ceil(entry.length / 4) + 1 // rough estimate
       if (tokenBudget + entryTokens > maxTokens) break
 

package/src/skills/sanitizer.ts

@@ -0,0 +1,214 @@
+/**
+ * Skill Safety Sanitizer
+ *
+ * Claude Code v2.1.228 security hardening for skills:
+ *   1. Strip/escape `!` command prefixes from skill body text
+ *   2. Block `@` file expansion references in skill body
+ *   3. Sanitize skill descriptions (strip markdown formatting, shell injection chars)
+ *   4. Tag synced skills with source identifier
+ *   5. Detect shadowing of local commands and MCP tool names
+ *
+ * Applied at skill load time (loader.ts) and execution time (fork-executor.ts, skill.ts).
+ */
+
+// ── Types ──
+
+export interface SanitizeResult {
+  /** Sanitized text */
+  text: string
+  /** Warnings generated during sanitization */
+  warnings: string[]
+  /** Whether the text was modified */
+  modified: boolean
+  /** Whether the text was blocked entirely */
+  blocked: boolean
+}
+
+export interface ShadowCheck {
+  /** Whether a shadowing conflict was detected */
+  shadowed: boolean
+  /** Name of the conflicting command/tool */
+  conflictsWith: string
+  /** Type of conflict: 'command' | 'mcp-tool' */
+  conflictType: 'command' | 'mcp-tool'
+}
+
+// ── Constants ──
+
+/** Known local command names that skills should not shadow */
+const BUILTIN_COMMANDS = new Set([
+  '/help',
+  '/model',
+  '/models',
+  '/switch',
+  '/compact',
+  '/clear',
+  '/resume',
+  '/config',
+  '/skills',
+  '/browse-skills',
+  '/install-skill',
+  '/reload-skills',
+  '/remove-skill',
+  '/crsi',
+  '/sis',
+  '/plan',
+  '/no-plan',
+  '/triage',
+  '/workflows',
+  '/tasks',
+])
+
+/** Source tags for synced skills */
+const SOURCE_TAGS: Record<string, string> = {
+  'claude.ai': '🔗 [claude.ai synced]',
+  community: '📦 [community]',
+  standard: '',
+  mipham: '🏔️ [Mipham]',
+}
+
+// ── Sanitizer ──
+
+/**
+ * Sanitize a skill body (markdown instructions) for safe execution.
+ *
+ * Security measures:
+ *   - `! command` patterns → escaped to `! command` (prevents AI from treating as shell command)
+ *   - `@file` references → prefixed with safety note
+ *   - Trailing backticks that could break markdown fences → escaped
+ *   - Excessively long lines → truncated
+ */
+export function sanitizeSkillBody(body: string): SanitizeResult {
+  const warnings: string[] = []
+  let text = body
+  let modified = false
+
+  // ── 1. Detect and warn about `!` shell command patterns ──
+  // Pattern: line starting with `!` (Bash command marker in some AI contexts)
+  const bangCommandRegex = /^!\s*(\S+)/gm
+  let bangMatch: RegExpExecArray | null
+  const bangCommands: string[] = []
+  while ((bangMatch = bangCommandRegex.exec(text)) !== null) {
+    bangCommands.push(bangMatch[1] || '')
+  }
+  if (bangCommands.length > 0) {
+    // Escape `!` → `! ` (zero-width space after bang to neutralize)
+    text = text.replace(/^!(?=\s*\S)/gm, '! ')
+    modified = true
+    warnings.push(
+      `Skill body contained ${bangCommands.length} shell-command-like patterns (${bangCommands.slice(0, 3).join(', ')}${bangCommands.length > 3 ? '...' : ''}). Escaped to prevent unintended command execution.`,
+    )
+  }
+
+  // ── 2. Detect and warn about `@file` references ──
+  const atFileRegex = /@(\S+\.(?:md|ts|js|json|yml|yaml|txt|csv|py|rs|go|java|html|css|sh))/gi
+  let atMatch: RegExpExecArray | null
+  const atFiles: string[] = []
+  while ((atMatch = atFileRegex.exec(text)) !== null) {
+    atFiles.push(atMatch[0])
+  }
+  if (atFiles.length > 0) {
+    // Replace @file with `@ file` (space after @ to neutralize expansion)
+    text = text.replace(/@(\S+\.\w{1,6})\b/gi, '@ $1')
+    modified = true
+    warnings.push(
+      `Skill body contained ${atFiles.length} file reference patterns (${atFiles.slice(0, 3).join(', ')}${atFiles.length > 3 ? '...' : ''}). Neutralized to prevent unintended file expansion.`,
+    )
+  }
+
+  // ── 3. Sanitize markdown fence break attempts ──
+  // Prevent skills from breaking out of their markdown code block context
+  if (text.includes('```')) {
+    const fenceCount = (text.match(/```/g) || []).length
+    if (fenceCount % 2 !== 0) {
+      // Odd number: append closing fence
+      text += '\n```'
+      modified = true
+      warnings.push('Skill body had unclosed markdown fence — auto-closed for safety.')
+    }
+  }
+
+  return { text, warnings, modified, blocked: false }
+}
+
+/**
+ * Sanitize a skill description for display in system reminders.
+ *
+ * - Strip shell-injection characters ($, `, ;, |, &, <, >)
+ * - Strip markdown links that could be misleading
+ * - Truncate to max length
+ * - Add source tag for synced skills
+ */
+export function sanitizeSkillDescription(
+  description: string,
+  source?: string,
+  maxLength: number = 200,
+): string {
+  let text = description
+
+  // Strip shell injection characters
+  text = text.replace(/[`$;|&<>]/g, '')
+
+  // Strip markdown links — keep text, drop URL
+  text = text.replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+
+  // Strip HTML tags
+  text = text.replace(/<[^>]*>/g, '')
+
+  // Collapse whitespace
+  text = text.replace(/\s+/g, ' ').trim()
+
+  // Truncate
+  if (text.length > maxLength) {
+    text = text.slice(0, maxLength - 3) + '...'
+  }
+
+  // Add source tag
+  if (source && SOURCE_TAGS[source]) {
+    text = `${SOURCE_TAGS[source]} ${text}`
+  }
+
+  return text
+}
+
+/**
+ * Check if a skill name or description shadows a local command or MCP tool.
+ *
+ * @returns ShadowCheck with conflict info, or { shadowed: false }
+ */
+export function checkSkillShadow(
+  skillName: string,
+  description: string,
+  mcpToolNames?: string[],
+): ShadowCheck {
+  // Check against builtin commands
+  if (BUILTIN_COMMANDS.has(skillName)) {
+    return { shadowed: true, conflictsWith: skillName, conflictType: 'command' }
+  }
+
+  // Check description for embedded command names
+  for (const cmd of BUILTIN_COMMANDS) {
+    const cmdPattern = cmd.replace(/\//g, '')
+    if (description.toLowerCase().includes(cmdPattern.toLowerCase())) {
+      // Only flag if the description could be confused as a command invocation
+      if (
+        description.includes(`\`${cmd}\``) ||
+        description.includes(` ${cmd} `) ||
+        description.startsWith(cmd)
+      ) {
+        return { shadowed: true, conflictsWith: cmd, conflictType: 'command' }
+      }
+    }
+  }
+
+  // Check against MCP tool names
+  if (mcpToolNames) {
+    for (const toolName of mcpToolNames) {
+      if (skillName === toolName || description.includes(`\`${toolName}\``)) {
+        return { shadowed: true, conflictsWith: toolName, conflictType: 'mcp-tool' }
+      }
+    }
+  }
+
+  return { shadowed: false, conflictsWith: '', conflictType: 'command' }
+}

package/src/tools/agent/skill.ts

@@ -1,5 +1,6 @@
 import type { ToolDefinition } from '../../shared/index.ts'
 import { executeForkedSkill } from '../../skills/fork-executor'
+import { sanitizeSkillBody } from '../../skills/sanitizer.js'
 
 export const skillTool: ToolDefinition = {
   name: 'Skill',
@@ -66,15 +67,19 @@ export const skillTool: ToolDefinition = {
       }
 
       // Standard inline execution — return skill body for AI to follow
+      const safeBodyResult = skill.body ? sanitizeSkillBody(skill.body) : undefined
+      const bodyText = safeBodyResult?.text || skill.body || '(no instructions body)'
+
       const lines: string[] = [
         `── Skill Invoked: ${skill.name} ──`,
         `Type: ${skill.type} | Version: ${skill.version}`,
         skill.description ? `Description: ${skill.description}` : '',
         args ? `Arguments: ${args}` : '',
+        safeBodyResult?.warnings.length ? `⚠️ Safety: ${safeBodyResult.warnings.join('; ')}` : '',
         '',
         'The AI should now follow these instructions:',
         '',
-        skill.body || '(no instructions body)',
+        bodyText,
       ].filter(Boolean)
 
       return { success: true, content: lines.join('\n') }

package/src/tools/file/edit.ts

@@ -90,6 +90,10 @@ export const editTool: ToolDefinition = {
     }
 
     const content = readFileSync(filePath, 'utf-8')
+
+    // ── Read tracking: mark as read before editing ──
+    ctx.readFiles?.add(filePath)
+
     if (content.length > MAX_FILE_SIZE) {
       return {
         success: false,

package/src/tools/file/read.ts

@@ -45,6 +45,9 @@ export const readTool: ToolDefinition = {
     const limit = (params.limit as number) || 2000
     const content = readFileSync(filePath, 'utf-8')
 
+    // ── Read tracking: mark file as read for Write tool safety ──
+    ctx.readFiles?.add(filePath)
+
     // ── Credential masking ──
     if (credentialConfig) {
       const { matchCredentialFile, maskContent, CREDENTIAL_SENTINEL } =

package/src/tools/file/write.ts

@@ -1,11 +1,12 @@
-import { writeFileSync, mkdirSync } from 'node:fs'
+import { writeFileSync, mkdirSync, existsSync } from 'node:fs'
 import { dirname } from 'node:path'
 import type { ToolDefinition } from '../../shared/index.ts'
 import { resolveSafe } from '../../security/path'
 
 export const writeTool: ToolDefinition = {
   name: 'Write',
-  description: 'Write a file to the local filesystem. Creates parent directories if needed.',
+  description:
+    'Write a file to the local filesystem. Overwrites if one exists. You must have Read the file before overwriting it — this prevents accidental data loss.',
   category: 'file',
   permission: 'ask',
   parameters: {
@@ -29,9 +30,25 @@ export const writeTool: ToolDefinition = {
       }
     }
 
+    // ── Read-before-write safety check ──
+    const fileExists = existsSync(filePath)
+    const wasRead = ctx.readFiles?.has(filePath) ?? true // if no tracking, allow
+    if (fileExists && !wasRead) {
+      return {
+        success: false,
+        content: '',
+        error: `File "${filePath}" already exists but has not been read this session. Read the file first before overwriting it. This prevents accidental data loss.`,
+      }
+    }
+
     mkdirSync(dirname(filePath), { recursive: true })
     writeFileSync(filePath, content, 'utf-8')
+
+    // Track as read since we just wrote it (future writes allowed)
+    ctx.readFiles?.add(filePath)
+
     const lines = content.split('\n').length
-    return { success: true, content: `Wrote ${lines} lines to ${filePath}` }
+    const action = fileExists ? 'Updated' : 'Wrote'
+    return { success: true, content: `${action} ${lines} lines to ${filePath}` }
   },
 }