@asobacloud/nehanda 0.0.0-stage → 0.3.0

package/lib/tools.mjs

@@ -0,0 +1,907 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawn } from 'node:child_process'
+import { randomUUID } from 'node:crypto'
+import { setPhase, getPhase } from './workflow.mjs'
+import { withTransaction } from './store.mjs'
+import { getMcpServer, listMcpServers, mcpListResources, mcpReadResource } from './mcp.mjs'
+import { applyEnergyNormalization } from './energy-middleware.mjs'
+import { runHooks } from './hookplane.mjs'
+import { createWorktree, removeWorktree, getCurrentWorktree } from './worktree.mjs'
+import { addTeammate, setTeammateIdle } from './team.mjs'
+import { validateBashCommand } from './bashguard.mjs'
+
+const BASH_CAP = 1048576
+const TRUNC = '[SDLC_TRUNCATED]'
+const READ_CAP = 1048576
+
+// Dynamically load declarative tools from the 'tools' directory
+const TOOLS_CONFIG_DIR = path.join(path.dirname(new URL(import.meta.url).pathname), 'tools')
+export const dynamicTools = new Map()
+
+export const EXPLORE_ONLY_TOOLS = new Set(['Read', 'Glob', 'Grep'])
+const PLANNING_BLOCKED_TOOLS = new Set(['Write', 'Edit', 'Bash', 'NotebookEdit'])
+
+try {
+  if (fs.existsSync(TOOLS_CONFIG_DIR)) {
+    const files = fs.readdirSync(TOOLS_CONFIG_DIR)
+    for (const file of files) {
+      if (file.endsWith('.json')) {
+        const filePath = path.join(TOOLS_CONFIG_DIR, file)
+        const config = JSON.parse(fs.readFileSync(filePath, 'utf8'))
+        dynamicTools.set(config.name, config)
+
+        if (config.phases?.explore_only) {
+          EXPLORE_ONLY_TOOLS.add(config.name)
+        }
+        if (config.phases?.planning_blocked) {
+          PLANNING_BLOCKED_TOOLS.add(config.name)
+        }
+      }
+    }
+  }
+} catch (err) {
+  console.error('Failed to load declarative tools:', err)
+}
+
+// ─── Tool dispatch ────────────────────────────────────────────
+
+export async function executeBuiltinTool(db, ctx, toolName, toolInput, io) {
+  const { conversationId, cwd } = ctx
+
+  // The harness owns phase-based tool filtering. If a model calls a blocked tool
+  // anyway (e.g. hallucination), enforce it here as a hard stop.
+  const phase = getPhase(db, conversationId)
+  if (phase === 'planning' && PLANNING_BLOCKED_TOOLS.has(toolName)) {
+    return { content: `Tool ${toolName} is not available in planning phase. Use Read, Glob, or Grep to explore the codebase, then write your plan as text.`, is_error: true }
+  }
+
+  // §1 Bug fix: surface JSON parse failures from streaming tool call arguments
+  if (toolInput?._parseError) {
+    const raw = String(toolInput._raw || '').slice(0, 200)
+    return { content: `Tool call arguments could not be parsed (truncated JSON): ${raw}`, is_error: true }
+  }
+
+  try {
+    switch (toolName) {
+      case 'Read': return await toolRead(cwd, toolInput)
+      case 'Write': return toolWrite(cwd, toolInput, db, ctx)
+      case 'Edit': return toolEdit(cwd, toolInput, db, ctx)
+      case 'Glob': return toolGlob(cwd, toolInput)
+      case 'Grep': return toolGrep(cwd, toolInput)
+      case 'Bash': return await toolBash(cwd, toolInput, db, ctx)
+      case 'NotebookEdit': return toolNotebookEdit(cwd, toolInput)
+      case 'WebFetch': return await toolWebFetch(toolInput)
+      case 'WebSearch': return await toolWebSearch(toolInput)
+      case 'AskUserQuestion': return await toolAskUser(io, toolInput)
+      case 'Brief': return toolBrief(io, toolInput)
+      case 'TodoWrite': return toolTodoWrite(db, ctx, toolInput)
+      case 'TaskOutput': return toolTaskOutput(db, ctx, toolInput)
+      case 'TaskStop': return toolTaskStop(toolInput)
+      // Phase transitions are owned by the orchestrator harness, not the model.
+      // If the model somehow calls these, return a clear error.
+      case 'EnterPlanMode':
+      case 'ExitPlanMode':
+      case 'SubmitImplementation':
+      case 'SubmitTest':
+        return { content: `[SDLC] ${toolName} is not a model tool. Phase transitions are managed by the harness.`, is_error: true }
+      case 'Agent': return await toolAgent(db, ctx, toolInput, io)
+      case 'Skill': return toolSkill(cwd, toolInput)
+      case 'ToolSearch': return toolSearchFn(toolInput)
+      case 'EnterWorktree': return await toolEnterWorktree(db, ctx, toolInput)
+      case 'ExitWorktree': return await toolExitWorktree(db, ctx, toolInput)
+      case 'ListMcpResources': return await toolListMcpResources(ctx, toolInput)
+      case 'ReadMcpResource': return await toolReadMcpResource(ctx, toolInput)
+      default:
+        if (dynamicTools.has(toolName)) {
+          return await executeDynamicScriptTool(cwd, toolName, toolInput)
+        }
+        if (toolName.startsWith('mcp__')) return await toolMcpInvoke(ctx, toolName, toolInput)
+        return { content: `Unknown tool: ${toolName}`, is_error: true }
+    }
+  } catch (e) {
+    return { content: `[SDLC_INTERNAL] ${String(e?.message || e)}`, is_error: true }
+  }
+}
+
+// ─── Read ─────────────────────────────────────────────────────
+
+async function toolRead(cwd, input) {
+  const rel = input?.file_path
+  if (!rel || typeof rel !== 'string') return { content: 'Read: missing file_path', is_error: true }
+  const abs = path.isAbsolute(rel) ? path.resolve(rel) : path.resolve(cwd, rel)
+  if (!fs.existsSync(abs)) return { content: `Read: not found: ${rel}`, is_error: true }
+  const stat = fs.statSync(abs)
+  if (stat.isDirectory()) return { content: `Read: ${rel} is a directory`, is_error: true }
+  const buf = fs.readFileSync(abs)
+  if (buf.length > READ_CAP) {
+    return { content: `Read ${rel}: ${buf.length} bytes (truncated to ${READ_CAP})\n---\n${buf.subarray(0, READ_CAP).toString('utf8')}\n${TRUNC}`, is_error: false }
+  }
+  const text = buf.toString('utf8')
+  const lines = text.split('\n')
+  const offset = input?.offset || 0
+  const limit = input?.limit || lines.length
+  const slice = lines.slice(offset, offset + limit)
+  const numbered = slice.map((l, i) => `${offset + i + 1}\t${l}`).join('\n')
+  return { content: `Read ${rel}: ${lines.length} lines.\n---\n${numbered}`, is_error: false }
+}
+
+// ─── Write ────────────────────────────────────────────────────
+
+function toolWrite(cwd, input, db, ctx) {
+  const rel = input?.file_path
+  const content = input?.content
+  if (!rel || typeof rel !== 'string') return { content: 'Write: missing file_path', is_error: true }
+  if (typeof content !== 'string') return { content: 'Write: missing content', is_error: true }
+  const abs = path.isAbsolute(rel) ? path.resolve(rel) : path.resolve(cwd, rel)
+  if (abs !== path.resolve(cwd) && !abs.startsWith(path.resolve(cwd) + path.sep)) {
+    return { content: 'Write: path outside working directory', is_error: true }
+  }
+  const existed = fs.existsSync(abs)
+  fs.mkdirSync(path.dirname(abs), { recursive: true })
+  fs.writeFileSync(abs, content, 'utf8')
+  const lines = content.split('\n').length
+  // §3 FileChanged hook
+  if (process.env.SDLC_DISABLE_ALL_HOOKS !== '1' && db && ctx) {
+    const hookRt = { sessionId: ctx.sessionId, conversationId: ctx.conversationId, runtimeDbPath: process.env.AGENT_SDLC_DB || '', cwd, settings: ctx.settings }
+    runHooks(db, hookRt, 'FileChanged', { file_path: abs, event: existed ? 'change' : 'add' }).catch(() => {})
+  }
+  return { content: `${existed ? 'Updated' : 'Created'} ${rel} (${lines} lines)`, is_error: false }
+}
+
+// ─── Edit ─────────────────────────────────────────────────────
+
+function toolEdit(cwd, input, db, ctx) {
+  const rel = input?.file_path
+  const oldStr = input?.old_string
+  const newStr = input?.new_string
+  if (!rel) return { content: 'Edit: missing file_path', is_error: true }
+  if (typeof oldStr !== 'string') return { content: 'Edit: missing old_string', is_error: true }
+  if (typeof newStr !== 'string') return { content: 'Edit: missing new_string', is_error: true }
+  const abs = path.isAbsolute(rel) ? path.resolve(rel) : path.resolve(cwd, rel)
+  if (abs !== path.resolve(cwd) && !abs.startsWith(path.resolve(cwd) + path.sep)) {
+    return { content: 'Edit: path outside working directory', is_error: true }
+  }
+  if (!fs.existsSync(abs)) return { content: `Edit: not found: ${rel}`, is_error: true }
+  let text = fs.readFileSync(abs, 'utf8')
+  if (input?.replace_all) {
+    if (!text.includes(oldStr)) return { content: `Edit: old_string not found in ${rel}`, is_error: true }
+    text = text.replaceAll(oldStr, newStr)
+  } else {
+    const idx = text.indexOf(oldStr)
+    if (idx === -1) return { content: `Edit: old_string not found in ${rel}`, is_error: true }
+    const count = text.split(oldStr).length - 1
+    if (count > 1) return { content: `Edit: old_string matches ${count} locations in ${rel} — provide more context to make it unique, or use replace_all`, is_error: true }
+    text = text.slice(0, idx) + newStr + text.slice(idx + oldStr.length)
+  }
+  fs.writeFileSync(abs, text, 'utf8')
+  if (process.env.SDLC_DISABLE_ALL_HOOKS !== '1' && db && ctx) {
+    const hookRt = { sessionId: ctx.sessionId, conversationId: ctx.conversationId, runtimeDbPath: process.env.AGENT_SDLC_DB || '', cwd, settings: ctx.settings }
+    runHooks(db, hookRt, 'FileChanged', { file_path: abs, event: 'change' }).catch(() => {})
+  }
+  return { content: `Edited ${rel}`, is_error: false }
+}
+
+// ─── Glob ─────────────────────────────────────────────────────
+
+function toolGlob(cwd, input) {
+  const pattern = input?.pattern
+  if (!pattern) return { content: 'Glob: missing pattern', is_error: true }
+  const searchDir = input?.path ? path.resolve(cwd, input.path) : cwd
+  if (!fs.existsSync(searchDir)) return { content: `Glob: directory not found: ${searchDir}`, is_error: true }
+  const results = []
+  const maxResults = 100
+  globWalk(searchDir, pattern, results, maxResults, searchDir)
+  return { content: results.length ? results.join('\n') : '(no matches)', is_error: false }
+}
+
+function globWalk(dir, pattern, results, max, root) {
+  if (results.length >= max) return
+  let entries
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }) } catch { return }
+  for (const e of entries) {
+    if (results.length >= max) return
+    if (e.name.startsWith('.') && !pattern.startsWith('.')) continue
+    const full = path.join(dir, e.name)
+    const rel = path.relative(root, full)
+    if (e.isDirectory()) {
+      if (e.name === 'node_modules' || e.name === '.git') continue
+      globWalk(full, pattern, results, max, root)
+    } else {
+      if (globMatch(pattern, rel) || globMatch(pattern, e.name)) results.push(rel)
+    }
+  }
+}
+
+function globMatch(pattern, str) {
+  const regex = pattern
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*\*/g, '<<<GLOBSTAR>>>')
+    .replace(/\*/g, '[^/]*')
+    .replace(/<<<GLOBSTAR>>>/g, '.*')
+    .replace(/\?/g, '[^/]')
+  return new RegExp(`^${regex}$`).test(str)
+}
+
+// ─── Grep ─────────────────────────────────────────────────────
+
+function toolGrep(cwd, input) {
+  const pattern = input?.pattern
+  if (!pattern) return { content: 'Grep: missing pattern', is_error: true }
+  const searchPath = input?.path ? path.resolve(cwd, input.path) : cwd
+  const mode = input?.output_mode || 'files_with_matches'
+  const caseI = input?.['-i'] || false
+  const headLimit = input?.head_limit ?? 250
+  const contextLines = input?.['-C'] || input?.context || 0
+  let re
+  try { re = new RegExp(pattern, caseI ? 'i' : '') } catch (e) { return { content: `Grep: invalid regex: ${e.message}`, is_error: true } }
+
+  const stat = fs.existsSync(searchPath) ? fs.statSync(searchPath) : null
+  if (!stat) return { content: `Grep: path not found: ${searchPath}`, is_error: true }
+
+  const matchingFiles = []
+  const contentLines = []
+  let matchCount = 0
+
+  function searchFile(filePath) {
+    if (headLimit > 0 && matchingFiles.length >= headLimit && mode === 'files_with_matches') return
+    let text
+    try { text = fs.readFileSync(filePath, 'utf8') } catch { return }
+    const lines = text.split('\n')
+    let fileMatched = false
+    for (let i = 0; i < lines.length; i++) {
+      if (re.test(lines[i])) {
+        matchCount++
+        if (!fileMatched) { matchingFiles.push(path.relative(cwd, filePath)); fileMatched = true }
+        if (mode === 'content') {
+          if (headLimit > 0 && contentLines.length >= headLimit) return
+          const start = Math.max(0, i - contextLines)
+          const end = Math.min(lines.length - 1, i + contextLines)
+          for (let j = start; j <= end; j++) {
+            const prefix = j === i ? `${j + 1}:` : `${j + 1}-`
+            contentLines.push(`${path.relative(cwd, filePath)}:${prefix}${lines[j]}`)
+          }
+          if (contextLines > 0) contentLines.push('--')
+        }
+      }
+    }
+  }
+
+  function walk(dir) {
+    let entries
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }) } catch { return }
+    for (const e of entries) {
+      if (e.name === 'node_modules' || e.name === '.git' || e.name.startsWith('.')) continue
+      const full = path.join(dir, e.name)
+      if (e.isDirectory()) walk(full)
+      else {
+        if (input?.glob && !globMatch(input.glob, e.name)) continue
+        searchFile(full)
+      }
+    }
+  }
+
+  if (stat.isFile()) searchFile(searchPath)
+  else walk(searchPath)
+
+  if (mode === 'files_with_matches') return { content: matchingFiles.join('\n') || '(no matches)', is_error: false }
+  if (mode === 'count') return { content: `${matchCount} matches in ${matchingFiles.length} files`, is_error: false }
+  return { content: contentLines.join('\n') || '(no matches)', is_error: false }
+}
+
+// ─── Bash ─────────────────────────────────────────────────────
+
+const CWD_MARKER = '___ONA_CWD___'
+
+async function toolBash(cwd, input, db, ctx) {
+  const cmd = input?.command
+  if (!cmd || typeof cmd !== 'string') return { content: 'Bash: missing command', is_error: true }
+  // Validate command safety before execution
+  const guard = validateBashCommand(cmd, cwd)
+  if (!guard.ok) return { content: `[SDLC] Bash command blocked: ${guard.reason}`, is_error: true }
+  const timeoutMs = Math.min(input?.timeout || 120_000, 600_000)
+  // Append cwd detection marker
+  const wrappedCmd = `${cmd} ; echo "${CWD_MARKER}$(pwd)"`
+  return new Promise(resolve => {
+    const child = spawn(resolveBash(), ['-c', wrappedCmd], { cwd, env: { ...process.env }, stdio: ['ignore', 'pipe', 'pipe'] })
+    let out = Buffer.alloc(0), err = Buffer.alloc(0)
+    const push = (b, chunk) => {
+      const n = Buffer.concat([b, chunk])
+      return n.length <= BASH_CAP ? n : Buffer.concat([n.subarray(0, BASH_CAP), Buffer.from(TRUNC)])
+    }
+    child.stdout.on('data', d => { out = push(out, d) })
+    child.stderr.on('data', d => { err = push(err, d) })
+    const t = setTimeout(() => child.kill('SIGKILL'), timeoutMs)
+    child.on('close', code => {
+      clearTimeout(t)
+      let content = out.toString('utf8')
+      // Extract and strip cwd marker
+      const markerIdx = content.lastIndexOf(CWD_MARKER)
+      let newCwd = null
+      if (markerIdx !== -1) {
+        newCwd = content.slice(markerIdx + CWD_MARKER.length).trim()
+        content = content.slice(0, markerIdx).trimEnd()
+      }
+      const se = err.toString('utf8')
+      if (se) content += `\n--- stderr ---\n${se}`
+      // Fire CwdChanged hook if directory changed
+      if (newCwd && newCwd !== cwd && db && ctx && process.env.SDLC_DISABLE_ALL_HOOKS !== '1') {
+        const hookRt = { sessionId: ctx.sessionId, conversationId: ctx.conversationId, runtimeDbPath: process.env.AGENT_SDLC_DB || '', cwd, settings: ctx.settings }
+        process.chdir(newCwd)
+        runHooks(db, hookRt, 'CwdChanged', { old_cwd: cwd, new_cwd: newCwd }).catch(() => {})
+      }
+      resolve({ content, is_error: code !== 0, newCwd: (newCwd && newCwd !== cwd) ? newCwd : null })
+    })
+    child.on('error', e => { clearTimeout(t); resolve({ content: String(e?.message || e), is_error: true }) })
+  })
+}
+
+function resolveBash() {
+  if (fs.existsSync('/bin/bash')) return '/bin/bash'
+  if (fs.existsSync('/usr/bin/bash')) return '/usr/bin/bash'
+  return 'bash'
+}
+
+// ─── Dynamic Script Tool Executor ───────────────────────────────
+
+async function executeDynamicScriptTool(cwd, toolName, input) {
+  const config = dynamicTools.get(toolName)
+  if (!config) return { content: `Tool ${toolName} config not found`, is_error: true }
+
+  let scriptPath = config.execution.script
+  if (!path.isAbsolute(scriptPath)) {
+    scriptPath = path.join(path.dirname(new URL(import.meta.url).pathname), '..', scriptPath)
+  }
+
+  // Override dynamically using environment variable (e.g. AUDIT_CODE_INTEGRITY_SCRIPT for AuditCodeIntegrity)
+  const envKey = `${toolName.replace(/([A-Z])/g, '_$1').toUpperCase()}_SCRIPT`.replace(/^_/, '')
+  const resolvedScriptPath = process.env[envKey] || scriptPath
+
+  if (!fs.existsSync(resolvedScriptPath)) {
+    return { content: `${toolName}: script not found at ${resolvedScriptPath}.`, is_error: true }
+  }
+
+  // Parse arguments template
+  const spawnArgs = []
+  const templateArgs = config.execution.args || []
+  for (let i = 0; i < templateArgs.length; i++) {
+    const arg = templateArgs[i]
+    if (arg.startsWith('{{') && arg.endsWith('}}')) {
+      const key = arg.slice(2, -2)
+      const val = input[key]
+      if (val !== undefined) {
+        spawnArgs.push(String(val))
+      }
+    } else {
+      // Check if next arg is a placeholder, and if its value is undefined, skip both the flag and the placeholder
+      const nextArg = templateArgs[i + 1]
+      if (nextArg && nextArg.startsWith('{{') && nextArg.endsWith('}}')) {
+        const key = nextArg.slice(2, -2)
+        if (input[key] === undefined) {
+          i++ // skip next arg
+          continue
+        }
+      }
+      spawnArgs.push(arg)
+    }
+  }
+
+  const cmd = config.execution.runtime || 'python3'
+  const args = [resolvedScriptPath, ...spawnArgs]
+  const timeoutMs = Math.min(
+    input?.timeout || config.execution.default_timeout || 120_000,
+    config.execution.max_timeout || 600_000
+  )
+
+  return new Promise(resolve => {
+    const child = spawn(cmd, args, { cwd, env: { ...process.env }, stdio: ['ignore', 'pipe', 'pipe'] })
+    let out = Buffer.alloc(0), err = Buffer.alloc(0)
+    const push = (b, chunk) => {
+      const n = Buffer.concat([b, chunk])
+      return n.length <= BASH_CAP ? n : Buffer.concat([n.subarray(0, BASH_CAP), Buffer.from(TRUNC)])
+    }
+    child.stdout.on('data', d => { out = push(out, d) })
+    child.stderr.on('data', d => { err = push(err, d) })
+    const t = setTimeout(() => child.kill('SIGKILL'), timeoutMs)
+    child.on('close', code => {
+      clearTimeout(t)
+      const stdout = out.toString('utf8')
+      const stderr = err.toString('utf8')
+      if (code !== 0 && code !== 1) {
+        resolve({ content: stderr || `${toolName} exited with code ${code}`, is_error: true })
+        return
+      }
+      if (code === 1 && !stdout.trim()) {
+        resolve({ content: stderr || `${toolName} execution error (exited with code 1 and empty output)`, is_error: true })
+        return
+      }
+      resolve({ content: stdout, is_error: code === 1 })
+    })
+    child.on('error', e => { clearTimeout(t); resolve({ content: String(e?.message || e), is_error: true }) })
+  })
+}
+
+// ─── NotebookEdit ─────────────────────────────────────────────
+
+function toolNotebookEdit(cwd, input) {
+  const rel = input?.notebook_path
+  if (!rel) return { content: 'NotebookEdit: missing notebook_path', is_error: true }
+  const abs = path.isAbsolute(rel) ? path.resolve(rel) : path.resolve(cwd, rel)
+  if (!fs.existsSync(abs)) return { content: `NotebookEdit: not found: ${rel}`, is_error: true }
+  let nb
+  try { nb = JSON.parse(fs.readFileSync(abs, 'utf8')) } catch (e) { return { content: `NotebookEdit: parse error: ${e.message}`, is_error: true } }
+  const cells = nb.cells || []
+  const cellId = input?.cell_id
+  const newSource = input?.new_source
+  const cellType = input?.cell_type || 'code'
+  if (typeof newSource !== 'string') return { content: 'NotebookEdit: missing new_source', is_error: true }
+
+  const sourceLines = newSource.split('\n').map((l, i, a) => i < a.length - 1 ? l + '\n' : l)
+
+  if (cellId) {
+    const idx = cells.findIndex(c => c.id === cellId || c.metadata?.id === cellId)
+    if (idx >= 0) {
+      cells[idx].source = sourceLines
+      cells[idx].cell_type = cellType
+    } else {
+      cells.push({ id: cellId, cell_type: cellType, source: sourceLines, metadata: { id: cellId }, outputs: [] })
+    }
+  } else {
+    const id = randomUUID().slice(0, 8)
+    cells.unshift({ id, cell_type: cellType, source: sourceLines, metadata: { id }, outputs: [] })
+  }
+
+  nb.cells = cells
+  fs.writeFileSync(abs, JSON.stringify(nb, null, 1), 'utf8')
+  return { content: `NotebookEdit: updated ${rel} (${cells.length} cells)`, is_error: false }
+}
+
+// ─── WebFetch ─────────────────────────────────────────────────
+
+async function toolWebFetch(input) {
+  const url = input?.url
+  if (!url) return { content: 'WebFetch: missing url', is_error: true }
+  try { new URL(url) } catch { return { content: `WebFetch: invalid url: ${url}`, is_error: true } }
+  const start = Date.now()
+  try {
+    const resp = await fetch(url, { headers: { 'User-Agent': 'ona-sdlc-repl/0.2' }, signal: AbortSignal.timeout(30_000) })
+    const text = await resp.text()
+    const capped = text.length > BASH_CAP ? text.slice(0, BASH_CAP) + `\n${TRUNC}` : text
+    const duration = Date.now() - start
+    if (!resp.ok) return { content: `WebFetch ${resp.status} ${resp.statusText}: ${capped.slice(0, 2000)}`, is_error: true }
+    return { content: `WebFetch ${url} (${resp.status}, ${text.length} bytes, ${duration}ms):\n${capped}`, is_error: false }
+  } catch (e) {
+    return { content: `WebFetch error: ${String(e?.message || e)}`, is_error: true }
+  }
+}
+
+// ─── WebSearch ────────────────────────────────────────────────
+
+async function toolWebSearch(input) {
+  const query = input?.query
+  if (!query || query.length < 2) return { content: 'WebSearch: query must be ≥2 chars', is_error: true }
+  try {
+    const url = `https://lite.duckduckgo.com/lite/?q=${encodeURIComponent(query)}`
+    const resp = await fetch(url, { headers: { 'User-Agent': 'ona-sdlc-repl/0.2' }, signal: AbortSignal.timeout(15_000) })
+    const html = await resp.text()
+    const results = parseDDGLite(html).slice(0, 8)
+    if (!results.length) return { content: `WebSearch: no results for "${query}"`, is_error: false }
+    const text = results.map((r, i) => `${i + 1}. ${r.title}\n   ${r.url}\n   ${r.snippet}`).join('\n\n')
+    return { content: `WebSearch results for "${query}":\n\n${text}`, is_error: false }
+  } catch (e) {
+    return { content: `WebSearch error: ${String(e?.message || e)}`, is_error: true }
+  }
+}
+
+function parseDDGLite(html) {
+  const results = []
+  const linkRe = /<a[^>]+class="result-link"[^>]*href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/gi
+  const snippetRe = /<td[^>]+class="result-snippet"[^>]*>([\s\S]*?)<\/td>/gi
+  const links = [...html.matchAll(linkRe)]
+  const snippets = [...html.matchAll(snippetRe)]
+  for (let i = 0; i < links.length; i++) {
+    const url = links[i][1].replace(/&amp;/g, '&')
+    const title = links[i][2].replace(/<[^>]+>/g, '').trim()
+    const snippet = (snippets[i]?.[1] || '').replace(/<[^>]+>/g, '').trim()
+    if (url && title) results.push({ url, title, snippet })
+  }
+  if (!results.length) {
+    const simpleLinks = [...html.matchAll(/<a[^>]+href="(https?:\/\/[^"]+)"[^>]*>([\s\S]*?)<\/a>/gi)]
+    for (const m of simpleLinks.slice(0, 8)) {
+      const u = m[1]; const t = m[2].replace(/<[^>]+>/g, '').trim()
+      if (t.length > 5 && !u.includes('duckduckgo.com')) results.push({ url: u, title: t, snippet: '' })
+    }
+  }
+  return results
+}
+
+// ─── AskUserQuestion ──────────────────────────────────────────
+
+async function toolAskUser(io, input) {
+  const question = input?.question || input?.prompt || 'Please provide input:'
+  if (!io?.ask) return { content: 'AskUserQuestion: no interactive input available', is_error: true }
+  const answer = await io.ask(`${question}\n> `)
+  return { content: String(answer || '').trim() || '(no response)', is_error: false }
+}
+
+// ─── Brief ────────────────────────────────────────────────────
+
+// Strip BOS/EOS tokens that some models (DeepSeek, Qwen) leak into tool call arguments
+function sanitizeBriefMessage(msg) {
+  return msg
+    .replace(/<[｜|]begin[▁_]of[▁_]sentence[｜|]>/g, '')
+    .replace(/<[｜|]end[▁_]of[▁_]sentence[｜|]>/g, '')
+    .replace(/<\|im_start\|>/g, '')
+    .replace(/<\|im_end\|>/g, '')
+    .trim()
+}
+
+function toolBrief(io, input) {
+  const raw = input?.message || input?.content || ''
+  const msg = sanitizeBriefMessage(raw)
+  if (io?.println) io.println(msg)
+  return { content: 'Message displayed.', is_error: false }
+}
+
+// ─── TodoWrite ────────────────────────────────────────────────
+
+async function toolTodoWrite(db, ctx, input) {
+  const todos = input?.todos
+  if (!Array.isArray(todos)) return { content: 'TodoWrite: missing todos array', is_error: true }
+  const hookRt = { sessionId: ctx.sessionId, conversationId: ctx.conversationId, runtimeDbPath: process.env.AGENT_SDLC_DB || '', cwd: ctx.cwd || process.cwd(), settings: ctx.settings }
+  withTransaction(db, () => {
+    for (const t of todos) {
+      const id = t.id || randomUUID().slice(0, 8)
+      db.prepare(`INSERT OR REPLACE INTO state(conversation_id, key, value) VALUES (?, ?, ?)`).run(ctx.conversationId, `todo:${id}`, JSON.stringify(t))
+    }
+  })
+  for (const t of todos) {
+    const id = t.id || ''
+    if (t.status === 'completed') {
+      await runHooks(db, hookRt, 'TaskCompleted', { task_id: id, task_subject: t.content || t.title || '' })
+    } else {
+      await runHooks(db, hookRt, 'TaskCreated', { task_id: id, task_subject: t.content || t.title || '' })
+    }
+  }
+  return { content: `TodoWrite: ${todos.length} item(s) saved.`, is_error: false }
+}
+
+// ─── TaskOutput ───────────────────────────────────────────────
+
+function toolTaskOutput(db, ctx, input) {
+  const output = input?.output || input?.content || ''
+  withTransaction(db, () => {
+    db.prepare(`INSERT INTO events(conversation_id, session_id, event_type, detail) VALUES (?, ?, 'task_output', ?)`).run(ctx.conversationId, ctx.sessionId, typeof output === 'string' ? output : JSON.stringify(output))
+  })
+  return { content: 'Task output recorded.', is_error: false }
+}
+
+// ─── TaskStop ─────────────────────────────────────────────────
+
+function toolTaskStop(input) {
+  const taskId = input?.task_id || input?.shell_id
+  if (!taskId) return { content: 'TaskStop: missing task_id', is_error: true }
+  // Background tasks tracked by the orchestrator; signal via process group
+  try { process.kill(Number(taskId), 'SIGTERM') } catch {}
+  return { content: `TaskStop: sent SIGTERM to ${taskId}`, is_error: false }
+}
+
+// ─── EnterWorktree ───────────────────────────────────────────
+
+async function toolEnterWorktree(db, ctx, input) {
+  const name = input?.name
+  if (!name) return { content: 'EnterWorktree: missing name', is_error: true }
+  const result = createWorktree(ctx.cwd, name)
+  if (!result.ok) return { content: `EnterWorktree: ${result.error}`, is_error: true }
+  process.chdir(result.worktreePath)
+  const hookRt = { sessionId: ctx.sessionId, conversationId: ctx.conversationId, runtimeDbPath: process.env.AGENT_SDLC_DB || '', cwd: ctx.cwd, settings: ctx.settings }
+  await runHooks(db, hookRt, 'WorktreeCreate', { name })
+  await runHooks(db, hookRt, 'CwdChanged', { old_cwd: ctx.cwd, new_cwd: result.worktreePath })
+  return { content: `Entered worktree: ${result.worktreePath} (branch: ${result.worktreeBranch})`, is_error: false }
+}
+
+// ─── ExitWorktree ────────────────────────────────────────────
+
+async function toolExitWorktree(db, ctx, input) {
+  const wt = getCurrentWorktree()
+  if (!wt) return { content: 'ExitWorktree: not in a worktree', is_error: true }
+  const action = input?.action || 'remove'
+  const hookRt = { sessionId: ctx.sessionId, conversationId: ctx.conversationId, runtimeDbPath: process.env.AGENT_SDLC_DB || '', cwd: ctx.cwd, settings: ctx.settings }
+  if (action === 'remove') {
+    const result = removeWorktree()
+    if (!result.ok) return { content: `ExitWorktree: ${result.error}`, is_error: true }
+    process.chdir(result.originalCwd)
+    await runHooks(db, hookRt, 'WorktreeRemove', { worktree_path: result.removedPath })
+    await runHooks(db, hookRt, 'CwdChanged', { old_cwd: ctx.cwd, new_cwd: result.originalCwd })
+    return { content: `Exited and removed worktree. Restored to ${result.originalCwd}`, is_error: false }
+  }
+  // keep — just chdir back without removing
+  process.chdir(wt.originalCwd)
+  await runHooks(db, hookRt, 'CwdChanged', { old_cwd: ctx.cwd, new_cwd: wt.originalCwd })
+  return { content: `Exited worktree (kept at ${wt.worktreePath}). Restored to ${wt.originalCwd}`, is_error: false }
+}
+
+// ─── Agent ────────────────────────────────────────────────────
+
+async function toolAgent(db, ctx, input, io) {
+  const prompt = input?.prompt
+  if (!prompt) return { content: 'Agent: missing prompt', is_error: true }
+  const desc = input?.description || 'subagent'
+  const subSessionId = randomUUID()
+  const subConvId = ctx.conversationId // same conversation
+
+  db.prepare(`INSERT INTO sessions(session_id, conversation_id) VALUES (?,?)`).run(subSessionId, subConvId)
+  db.prepare(`INSERT INTO events(conversation_id, session_id, event_type, detail) VALUES (?, ?, 'subagent_start', ?)`).run(subConvId, subSessionId, JSON.stringify({ description: desc }))
+  const hookRt = { sessionId: ctx.sessionId, conversationId: ctx.conversationId, runtimeDbPath: process.env.AGENT_SDLC_DB || '', cwd: ctx.cwd, settings: ctx.settings }
+  await runHooks(db, hookRt, 'SubagentStart', { agent_id: subSessionId, agent_type: desc })
+
+  // Run one turn in the sub-session using the same orchestration
+  const { runUserTurn } = await import('./orchestrate.mjs')
+  const subRt = { ...ctx, sessionId: subSessionId }
+  const collected = []
+  const subIo = {
+    write: s => collected.push(s),
+    println: s => collected.push(s + '\n'),
+    ask: io?.ask,
+  }
+
+  await runUserTurn(db, subRt, prompt, subIo)
+
+  const output = collected.join('')
+  db.prepare(`INSERT INTO events(conversation_id, session_id, event_type, detail) VALUES (?, ?, 'subagent_stop', ?)`).run(subConvId, subSessionId, JSON.stringify({ description: desc }))
+  await runHooks(db, hookRt, 'SubagentStop', { stop_hook_active: false, agent_id: subSessionId, agent_transcript_path: '', agent_type: desc, last_assistant_message: output.slice(0, 500) })
+
+  // If this is a team member, fire TeammateIdle
+  const teamName = input?.team_name || ctx.teamName
+  if (teamName) {
+    const agentId = `${desc}@${teamName}`
+    setTeammateIdle(teamName, agentId)
+    await runHooks(db, hookRt, 'TeammateIdle', { teammate_name: desc, team_name: teamName })
+  }
+
+  return { content: output || '(agent produced no output)', is_error: false }
+}
+
+// ─── Skill ────────────────────────────────────────────────────
+
+function toolSkill(cwd, input) {
+  const name = input?.skill
+  if (!name) return { content: 'Skill: missing skill name', is_error: true }
+
+  // Search for skill markdown file in standard locations:
+  // .ona/skills/<name>/SKILL.md, .claude/skills/<name>/SKILL.md,
+  // .ona/skills/<name>.md, .claude/skills/<name>.md
+  const searchDirs = [
+    path.join(cwd, '.ona', 'skills'),
+    path.join(cwd, '.claude', 'skills'),
+    path.join(process.env.HOME || '', '.ona', 'skills'),
+    path.join(process.env.HOME || '', '.claude', 'skills'),
+  ]
+
+  for (const dir of searchDirs) {
+    if (!fs.existsSync(dir)) continue
+    // Directory format: <name>/SKILL.md
+    const dirSkill = path.join(dir, name, 'SKILL.md')
+    if (fs.existsSync(dirSkill)) {
+      try {
+        const content = fs.readFileSync(dirSkill, 'utf8')
+        return { content: `Skill '${name}':\n\n${content}`, is_error: false }
+      } catch (e) {
+        return { content: `Skill: failed to read ${dirSkill}: ${e.message}`, is_error: true }
+      }
+    }
+    // Flat format: <name>.md
+    const flatSkill = path.join(dir, `${name}.md`)
+    if (fs.existsSync(flatSkill)) {
+      try {
+        const content = fs.readFileSync(flatSkill, 'utf8')
+        return { content: `Skill '${name}':\n\n${content}`, is_error: false }
+      } catch (e) {
+        return { content: `Skill: failed to read ${flatSkill}: ${e.message}`, is_error: true }
+      }
+    }
+  }
+
+  // No skill file found — return available skills list
+  const available = []
+  for (const dir of searchDirs) {
+    if (!fs.existsSync(dir)) continue
+    try {
+      const entries = fs.readdirSync(dir, { withFileTypes: true })
+      for (const e of entries) {
+        if (e.isDirectory() && fs.existsSync(path.join(dir, e.name, 'SKILL.md'))) {
+          available.push(e.name)
+        } else if (e.isFile() && e.name.endsWith('.md')) {
+          available.push(e.name.replace(/\.md$/, ''))
+        }
+      }
+    } catch { /* skip unreadable dirs */ }
+  }
+
+  if (available.length) {
+    return { content: `Skill '${name}' not found. Available skills: ${[...new Set(available)].join(', ')}`, is_error: true }
+  }
+  return { content: `Skill '${name}' not found. No skills directory configured. Create .ona/skills/${name}/SKILL.md to define a skill.`, is_error: true }
+}
+
+// ─── ToolSearch ───────────────────────────────────────────────
+
+function toolSearchFn(input) {
+  const query = (input?.query || '').toLowerCase()
+  const max = input?.max_results || 5
+  const defs = anthropicToolDefinitions()
+  const matches = defs.filter(t => t.name.toLowerCase().includes(query) || t.description.toLowerCase().includes(query)).slice(0, max)
+  if (!matches.length) return { content: `ToolSearch: no matches for "${query}"`, is_error: false }
+  const text = matches.map(t => `${t.name}: ${t.description}`).join('\n')
+  return { content: text, is_error: false }
+}
+
+// ─── MCP tools ────────────────────────────────────────────────
+
+async function toolListMcpResources(ctx, input) {
+  const serverName = input?.server
+  const settings = ctx.settings || {}
+  const serverConfigs = settings.mcp_servers || {}
+  if (serverName) {
+    if (!serverConfigs[serverName]) return { content: `MCP server '${serverName}' not configured`, is_error: true }
+    const srv = getMcpServer(serverName, serverConfigs[serverName])
+    return mcpListResources(srv)
+  }
+  const names = Object.keys(serverConfigs)
+  if (!names.length) return { content: 'No MCP servers configured.', is_error: false }
+  const all = []
+  for (const n of names) {
+    const srv = getMcpServer(n, serverConfigs[n])
+    const r = await mcpListResources(srv)
+    all.push(`[${n}]\n${r.content}`)
+  }
+  return { content: all.join('\n\n'), is_error: false }
+}
+
+async function toolReadMcpResource(ctx, input) {
+  const serverName = input?.server
+  const uri = input?.uri
+  if (!serverName || !uri) return { content: 'ReadMcpResource: missing server or uri', is_error: true }
+  const settings = ctx.settings || {}
+  const serverConfigs = settings.mcp_servers || {}
+  if (!serverConfigs[serverName]) return { content: `MCP server '${serverName}' not configured`, is_error: true }
+  const srv = getMcpServer(serverName, serverConfigs[serverName])
+  return mcpReadResource(srv, uri)
+}
+
+async function toolMcpInvoke(ctx, toolName, toolInput) {
+  // mcp__<server>__<tool>
+  const parts = toolName.split('__')
+  if (parts.length < 3) return { content: `Invalid MCP tool name: ${toolName}`, is_error: true }
+  const serverName = parts[1]
+  const mcpToolName = parts.slice(2).join('__')
+  const settings = ctx.settings || {}
+  const serverConfigs = settings.mcp_servers || {}
+  if (!serverConfigs[serverName]) return { content: `MCP server '${serverName}' not configured`, is_error: true }
+  const srv = getMcpServer(serverName, serverConfigs[serverName])
+  const { mcpCallTool: callTool } = await import('./mcp.mjs')
+  const result = await callTool(srv, mcpToolName, toolInput || {})
+
+  // Pass energy payloads through ODSE normalization if OEM is recognized.
+  // On any failure applyEnergyNormalization returns the original content unchanged.
+  if (!result.is_error && result.content) {
+    const { content } = await applyEnergyNormalization(serverName, result.content)
+    return { ...result, content }
+  }
+
+  return result
+}
+
+// ─── Tool definitions ─────────────────────────────────────────
+
+export function anthropicToolDefinitions() {
+  const tools = [
+    { name: 'Read', description: 'Read a file from the filesystem.', input_schema: { type: 'object', properties: { file_path: { type: 'string', description: 'Path to file (absolute or relative to cwd)' }, offset: { type: 'integer', description: 'Start line (0-based)' }, limit: { type: 'integer', description: 'Max lines to read' } }, required: ['file_path'] } },
+    { name: 'Write', description: 'Create or overwrite a file.', input_schema: { type: 'object', properties: { file_path: { type: 'string' }, content: { type: 'string' } }, required: ['file_path', 'content'] } },
+    { name: 'Edit', description: 'Find and replace text in a file.', input_schema: { type: 'object', properties: { file_path: { type: 'string' }, old_string: { type: 'string' }, new_string: { type: 'string' }, replace_all: { type: 'boolean' } }, required: ['file_path', 'old_string', 'new_string'] } },
+    { name: 'Glob', description: 'Find files matching a glob pattern.', input_schema: { type: 'object', properties: { pattern: { type: 'string' }, path: { type: 'string', description: 'Directory to search (default: cwd)' } }, required: ['pattern'] } },
+    { name: 'Grep', description: 'Search file contents with regex.', input_schema: { type: 'object', properties: { pattern: { type: 'string' }, path: { type: 'string' }, output_mode: { type: 'string', enum: ['content', 'files_with_matches', 'count'] }, glob: { type: 'string' }, '-i': { type: 'boolean' }, '-C': { type: 'integer' }, head_limit: { type: 'integer' } }, required: ['pattern'] } },
+    { name: 'Bash', description: 'Run a shell command.', input_schema: { type: 'object', properties: { command: { type: 'string' }, timeout: { type: 'integer', description: 'Timeout in ms (max 600000)' } }, required: ['command'] } },
+    { name: 'NotebookEdit', description: 'Edit a Jupyter notebook cell.', input_schema: { type: 'object', properties: { notebook_path: { type: 'string' }, cell_id: { type: 'string' }, new_source: { type: 'string' }, cell_type: { type: 'string', enum: ['code', 'markdown'] } }, required: ['notebook_path', 'new_source', 'cell_type'] } },
+    { name: 'WebFetch', description: 'Fetch content from a URL.', input_schema: { type: 'object', properties: { url: { type: 'string' }, prompt: { type: 'string' } }, required: ['url'] } },
+    { name: 'WebSearch', description: 'Search the web.', input_schema: { type: 'object', properties: { query: { type: 'string' }, allowed_domains: { type: 'array', items: { type: 'string' } }, blocked_domains: { type: 'array', items: { type: 'string' } } }, required: ['query'] } },
+    { name: 'AskUserQuestion', description: 'Ask the user a question and wait for response.', input_schema: { type: 'object', properties: { question: { type: 'string' } }, required: ['question'] } },
+    { name: 'Brief', description: 'Display a message to the user.', input_schema: { type: 'object', properties: { message: { type: 'string' } }, required: ['message'] } },
+    { name: 'TodoWrite', description: 'Create or update todo items.', input_schema: { type: 'object', properties: { todos: { type: 'array', items: { type: 'object' } } }, required: ['todos'] } },
+    { name: 'TaskOutput', description: 'Record output from a task.', input_schema: { type: 'object', properties: { output: { type: 'string' } } } },
+    { name: 'TaskStop', description: 'Stop a background task.', input_schema: { type: 'object', properties: { task_id: { type: 'string' } } } },
+    { name: 'Agent', description: 'Run a subagent with an isolated session.', input_schema: { type: 'object', properties: { description: { type: 'string' }, prompt: { type: 'string' } }, required: ['prompt'] } },
+    { name: 'Skill', description: 'Invoke a skill or slash command.', input_schema: { type: 'object', properties: { skill: { type: 'string' }, args: { type: 'string' } }, required: ['skill'] } },
+    { name: 'ToolSearch', description: 'Search for available tools.', input_schema: { type: 'object', properties: { query: { type: 'string' }, max_results: { type: 'integer' } }, required: ['query'] } },
+    { name: 'EnterWorktree', description: 'Create a git worktree for isolated work.', input_schema: { type: 'object', properties: { name: { type: 'string', description: 'Worktree name (alphanumeric, max 64 chars)' } }, required: ['name'] } },
+    { name: 'ExitWorktree', description: 'Exit the current worktree.', input_schema: { type: 'object', properties: { action: { type: 'string', enum: ['keep', 'remove'], description: 'Keep or remove the worktree (default: remove)' } } } },
+    { name: 'ListMcpResources', description: 'List MCP server resources.', input_schema: { type: 'object', properties: { server: { type: 'string' } } } },
+    { name: 'ReadMcpResource', description: 'Read a resource from an MCP server.', input_schema: { type: 'object', properties: { server: { type: 'string' }, uri: { type: 'string' } }, required: ['server', 'uri'] } },
+  ]
+  for (const [name, config] of dynamicTools) {
+    tools.push({
+      name: config.name,
+      description: config.description,
+      input_schema: config.input_schema
+    })
+  }
+  return tools
+}
+
+export function openAICompatToolDefinitions() {
+  return anthropicToolDefinitions().map(t => ({
+    type: 'function',
+    function: { name: t.name, description: t.description, parameters: t.input_schema },
+  }))
+}
+
+/** Core tools for local models with limited context (§2.1 lm_studio_local). */
+export const LOCAL_CORE_TOOLS = new Set(['Read', 'Write', 'Edit', 'Bash', 'Glob', 'Grep'])
+
+// ─── MCP tool discovery ───────────────────────────────────────
+
+/** In-memory cache: serverName → { tools, ts } */
+const _mcpToolCache = new Map()
+const MCP_CACHE_TTL_MS = 60_000   // re-discover after 1 minute
+
+/**
+ * Connect to all configured MCP servers, call tools/list on each, and return
+ * tool definitions in Anthropic format.  Results are cached per-server for
+ * MCP_CACHE_TTL_MS to avoid spawning child processes on every turn.
+ *
+ * Tool names are namespaced as  mcp__<server>__<tool>  so they route through
+ * toolMcpInvoke() in executeBuiltinTool() without any extra plumbing.
+ *
+ * @param {object} settings  - Effective settings object (settings.mcp_servers used)
+ * @returns {Promise<Array>}   Anthropic-format tool definitions
+ */
+export async function getMcpToolDefinitions(settings) {
+  const serverConfigs = settings?.mcp_servers
+  if (!serverConfigs || typeof serverConfigs !== 'object') return []
+
+  const names = Object.keys(serverConfigs)
+  if (!names.length) return []
+
+  const allTools = []
+  const now = Date.now()
+
+  for (const name of names) {
+    const config = serverConfigs[name]
+    if (!config?.command) continue
+
+    // Return cached entry if still fresh
+    const cached = _mcpToolCache.get(name)
+    if (cached && now - cached.ts < MCP_CACHE_TTL_MS) {
+      allTools.push(...cached.tools)
+      continue
+    }
+
+    try {
+      const srv = getMcpServer(name, config)
+      const resp = await srv.request('tools/list', {})
+      if (resp.error) continue
+
+      const serverTools = (resp.result?.tools || []).map(t => ({
+        name: `mcp__${name}__${t.name}`,
+        description: `[MCP:${name}] ${t.description || t.name}`,
+        input_schema: t.inputSchema || { type: 'object', properties: {} },
+      }))
+
+      _mcpToolCache.set(name, { tools: serverTools, ts: now })
+      allTools.push(...serverTools)
+    } catch {
+      // Server unreachable — skip silently, don't break the turn
+    }
+  }
+
+  return allTools
+}
+
+/**
+ * Invalidate the MCP tool cache for one server (or all if no name given).
+ * Called by /mcp reload.
+ */
+export function invalidateMcpToolCache(serverName) {
+  if (serverName) _mcpToolCache.delete(serverName)
+  else _mcpToolCache.clear()
+}