@miphamai/cli 0.33.0 → 0.33.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miphamai/cli",
-  "version": "0.33.0",
+  "version": "0.33.1",
   "description": "Mipham Code — Multi-model open-core intelligent coding terminal by MiphamAI",
   "keywords": [
     "ai",

package/src/core/engine.ts

@@ -55,6 +55,8 @@ export class QueryEngine {
   private _preflightChecker?: PreFlightChecker
   private _autoCorrector?: AutoCorrector
   private _metaRuleEngine?: MetaRuleEngine
+  /** Files read this session — tracks what the Read tool has loaded */
+  private readFiles = new Set<string>()
   private goal?: string
   private maxGoalLoops = 20
   private lastAssistantContent?: string
@@ -943,6 +945,7 @@ export class QueryEngine {
         backgroundAgentRegistry: getBackgroundAgentRegistry(),
         permissionSystem: this.permission,
         ruleEngine: this.ruleEngine,
+        readFiles: this.readFiles,
       })
 
       // Track touched files for rules matching

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}` }
   },
 }