ghost-dragon 4.2.1

package/src/agent/mcp.ts

@@ -0,0 +1,92 @@
+/**
+ * MCP hub — connect ANY Model Context Protocol server (configured via `dragon mcp
+ * add`) and expose its tools to the agent. Dragon inherits the entire MCP ecosystem
+ * without forking: filesystem, GitHub, Postgres, Playwright, your own servers…
+ *
+ * Tools are namespaced `<server>__<tool>` to avoid collisions with built-in tools and
+ * across servers. Everything is bounded (connect + call timeouts) and best-effort — an
+ * unreachable server never blocks the agent.
+ *
+ * Copyright 2026 Ghost Protocol (Pvt) Ltd. All Rights Reserved.
+ */
+
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+import type { ToolSpec } from '../brain/types.js'
+
+export interface McpServerConfig { command: string; args?: string[]; env?: Record<string, string> }
+
+const CONNECT_TIMEOUT = 8_000
+const CALL_TIMEOUT = 30_000
+
+function withTimeout<T>(p: Promise<T>, ms: number, onTimeout?: () => void): Promise<T | null> {
+  return new Promise((resolve) => {
+    let done = false
+    const timer = setTimeout(() => { if (!done) { done = true; onTimeout?.(); resolve(null) } }, ms)
+    p.then((v) => { if (!done) { done = true; clearTimeout(timer); resolve(v) } }, () => { if (!done) { done = true; clearTimeout(timer); resolve(null) } })
+  })
+}
+
+export class McpHub {
+  private clients = new Map<string, Client>()
+  private specs: ToolSpec[] = []
+  private route = new Map<string, { server: string; tool: string }>()
+  connected = false
+
+  /** Connect every configured server (bounded). Never throws. */
+  async connect(servers: Record<string, McpServerConfig>): Promise<void> {
+    for (const [name, cfg] of Object.entries(servers ?? {})) {
+      let transport: StdioClientTransport | null = null
+      try {
+        transport = new StdioClientTransport({ command: cfg.command, args: cfg.args ?? [], env: { ...(process.env as Record<string, string>), ...(cfg.env ?? {}) }, stderr: 'ignore' })
+        const client = new Client({ name: 'dragon-cli', version: '3.6.0' }, { capabilities: {} })
+        const t = transport
+        const ok = await withTimeout(
+          (async () => {
+            await client.connect(t)
+            const { tools } = await client.listTools()
+            for (const tool of tools) {
+              const ns = `${name}__${tool.name}`
+              this.specs.push({ name: ns, description: `[${name}] ${tool.description ?? ''}`.slice(0, 1024), parameters: (tool.inputSchema as Record<string, unknown>) ?? { type: 'object', properties: {} } })
+              this.route.set(ns, { server: name, tool: tool.name })
+            }
+            return true
+          })(),
+          CONNECT_TIMEOUT,
+          () => { try { void transport?.close() } catch { /* ignore */ } },
+        )
+        if (ok) this.clients.set(name, client)
+        else try { await client.close() } catch { /* ignore */ }
+      } catch { /* skip this server */ }
+    }
+    this.connected = this.clients.size > 0
+  }
+
+  get serverCount(): number { return this.clients.size }
+  toolSpecs(): ToolSpec[] { return this.specs }
+  handles(name: string): boolean { return this.route.has(name) }
+
+  async call(name: string, args: Record<string, unknown>): Promise<string> {
+    const r = this.route.get(name)
+    if (!r) return 'error: unknown MCP tool'
+    const client = this.clients.get(r.server)
+    if (!client) return `error: MCP server "${r.server}" not connected`
+    const res = await withTimeout(client.callTool({ name: r.tool, arguments: args }) as Promise<{ content?: { type: string; text?: string }[]; isError?: boolean }>, CALL_TIMEOUT)
+    if (res === null) return `error: ${name} timed out`
+    const text = (res.content ?? []).map((c) => (c.type === 'text' ? c.text ?? '' : `[${c.type}]`)).join('\n').trim()
+    return (res.isError ? 'error: ' : '') + (text || '(no result)')
+  }
+
+  async close(): Promise<void> {
+    for (const c of this.clients.values()) { try { await c.close() } catch { /* ignore */ } }
+    this.connected = false
+  }
+}
+
+/** Build + connect the hub from config (null if no servers configured). */
+export async function loadMcpHub(servers?: Record<string, McpServerConfig>): Promise<McpHub | null> {
+  if (!servers || !Object.keys(servers).length) return null
+  const hub = new McpHub()
+  await hub.connect(servers)
+  return hub.serverCount ? hub : null
+}

package/src/agent/session.ts

@@ -0,0 +1,48 @@
+/**
+ * Session persistence — save the conversation on exit (so `dragon chat --resume`
+ * picks up where you left off) and export a clean markdown transcript (`/save`).
+ * Stored under ~/.dragon/sessions, 0600 (may contain code/context).
+ *
+ * Copyright 2026 Ghost Protocol (Pvt) Ltd. All Rights Reserved.
+ */
+
+import { mkdirSync, writeFileSync, readFileSync, existsSync, chmodSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import type { BrainMessage } from '../brain/types.js'
+
+const DIR = join(homedir(), '.dragon', 'sessions')
+const LAST = join(DIR, 'last.json')
+
+export function saveSession(messages: BrainMessage[], meta: { cwd: string; brain: string }): void {
+  try {
+    if (!messages.length) return
+    mkdirSync(DIR, { recursive: true, mode: 0o700 })
+    writeFileSync(LAST, JSON.stringify({ ts: new Date().toISOString(), ...meta, messages }), { mode: 0o600 })
+    chmodSync(LAST, 0o600)
+  } catch { /* never break exit over a save */ }
+}
+
+export function loadLastSession(): BrainMessage[] | null {
+  try {
+    if (!existsSync(LAST)) return null
+    const o = JSON.parse(readFileSync(LAST, 'utf-8')) as { messages?: BrainMessage[] }
+    return Array.isArray(o.messages) && o.messages.length ? o.messages : null
+  } catch { return null }
+}
+
+/** Export the conversation as markdown (tool results omitted as noise). Returns the path. */
+export function exportMarkdown(messages: BrainMessage[], file?: string): string {
+  const md: string[] = [`# Dragon session — ${new Date().toISOString()}`, '']
+  for (const m of messages) {
+    if (m.role === 'user') md.push(`## You\n\n${m.content}\n`)
+    else if (m.role === 'assistant' && m.content) md.push(`## Dragon\n\n${m.content}\n`)
+    else if (m.role === 'assistant' && m.toolCalls?.length) md.push(`_ran: ${m.toolCalls.map((t) => t.name).join(', ')}_\n`)
+  }
+  const out = md.join('\n')
+  if (file) { writeFileSync(file, out); return file }
+  mkdirSync(DIR, { recursive: true, mode: 0o700 })
+  const f = join(DIR, `transcript-${new Date().toISOString().replace(/[:.]/g, '-')}.md`)
+  writeFileSync(f, out)
+  return f
+}

package/src/agent/skills.ts

@@ -0,0 +1,138 @@
+/**
+ * Skills-as-tools — the moat. Ghost Protocol's skill library (200+ reusable expert
+ * playbooks under ~/.copilot/skills) becomes live agent capability: the agent can
+ * `skill_search` for a relevant playbook and `skill_read` it to apply its guidance
+ * mid-task, instead of solving everything from cold.
+ *
+ * A dedicated, READ-ONLY library reader — deliberately separate from the cwd-confined
+ * file tools (the skill dir lives outside any project cwd, but it's our own curated,
+ * non-secret content, so reading it is safe + intentional).
+ *
+ * Copyright 2026 Ghost Protocol (Pvt) Ltd. All Rights Reserved.
+ */
+
+import { readdirSync, readFileSync, existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import type { ToolSpec } from '../brain/types.js'
+
+const SKILL_DIRS = [process.env.DRAGON_SKILLS_DIR, join(homedir(), '.copilot/skills'), join(homedir(), '.claude/skills')].filter(Boolean) as string[]
+const MAX_SKILL_CHARS = 14_000
+
+export interface SkillMeta { name: string; description: string; path: string }
+
+/** Minimal YAML frontmatter parse (name + description, inline or folded) — no dep. */
+export function parseFrontmatter(text: string): { name?: string; description?: string } {
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---/)
+  if (!m) return {}
+  const lines = m[1].split(/\r?\n/)
+  let name: string | undefined
+  let description: string | undefined
+  const unquote = (s: string) => s.replace(/^["']|["']$/g, '').trim()
+  for (let i = 0; i < lines.length; i++) {
+    let mm: RegExpMatchArray | null
+    if ((mm = lines[i].match(/^name:\s*(.+)$/))) name = unquote(mm[1])
+    else if ((mm = lines[i].match(/^description:\s*(.*)$/))) {
+      let d = mm[1].trim()
+      if (d === '' || d === '>' || d === '|' || d === '>-' || d === '|-') {
+        const cont: string[] = []
+        for (let j = i + 1; j < lines.length; j++) {
+          if (/^\s+\S/.test(lines[j])) cont.push(lines[j].trim())
+          else break
+        }
+        d = cont.join(' ')
+      }
+      description = unquote(d)
+    }
+  }
+  return { name, description }
+}
+
+export class SkillLibrary {
+  private index: SkillMeta[] = []
+
+  load(): void {
+    const seen = new Set<string>()
+    for (const dir of SKILL_DIRS) {
+      if (!existsSync(dir)) continue
+      let entries: string[]
+      try { entries = readdirSync(dir) } catch { continue }
+      for (const entry of entries) {
+        const skillFile = join(dir, entry, 'SKILL.md')
+        if (!existsSync(skillFile)) continue
+        let fm
+        try { fm = parseFrontmatter(readFileSync(skillFile, 'utf-8')) } catch { continue }
+        const name = fm.name || entry
+        if (seen.has(name)) continue // first dir wins (~/.copilot is canonical)
+        seen.add(name)
+        this.index.push({ name, description: fm.description ?? '', path: skillFile })
+      }
+    }
+  }
+
+  get count(): number { return this.index.length }
+
+  search(query: string, limit = 8): SkillMeta[] {
+    const terms = query.toLowerCase().split(/\W+/).filter((t) => t.length > 2)
+    if (!terms.length) return []
+    const scored = this.index.map((s) => {
+      const name = s.name.toLowerCase()
+      const desc = s.description.toLowerCase()
+      let score = 0
+      for (const t of terms) {
+        if (name.includes(t)) score += 5
+        if (desc.includes(t)) score += 1
+      }
+      return { s, score }
+    }).filter((x) => x.score > 0).sort((a, b) => b.score - a.score)
+    return scored.slice(0, limit).map((x) => x.s)
+  }
+
+  read(name: string): string | null {
+    const want = name.toLowerCase().trim()
+    const hit = this.index.find((s) => s.name.toLowerCase() === want) ?? this.index.find((s) => s.name.toLowerCase().includes(want))
+    if (!hit) return null
+    try {
+      const body = readFileSync(hit.path, 'utf-8')
+      return body.length > MAX_SKILL_CHARS ? body.slice(0, MAX_SKILL_CHARS) + '\n… [truncated]' : body
+    } catch { return null }
+  }
+
+  toolSpecs(): ToolSpec[] {
+    if (!this.count) return []
+    return [
+      {
+        name: 'skill_search',
+        description: `Search Ghost Protocol's library of ${this.count} reusable expert skills (playbooks for design, security, infra, brand, specific projects). Use BEFORE solving a non-trivial task from scratch — there's likely a skill for it. Returns matching skill names + summaries; then skill_read one.`,
+        parameters: { type: 'object', properties: { query: { type: 'string', description: 'what you need help with, e.g. "harden a cli" or "premium dark web design"' } }, required: ['query'] },
+      },
+      {
+        name: 'skill_read',
+        description: 'Read the full content of a named skill (from skill_search) and apply its guidance to the task.',
+        parameters: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
+      },
+    ]
+  }
+
+  handles(name: string): boolean { return name === 'skill_search' || name === 'skill_read' }
+
+  call(name: string, args: Record<string, unknown>): string {
+    if (name === 'skill_search') {
+      const hits = this.search(String(args.query ?? ''))
+      if (!hits.length) return 'no matching skills'
+      return hits.map((s) => `• ${s.name} — ${s.description.slice(0, 180)}`).join('\n')
+    }
+    if (name === 'skill_read') {
+      const body = this.read(String(args.name ?? ''))
+      return body ?? `no skill named "${args.name}" (use skill_search first)`
+    }
+    return 'error: unknown skill tool'
+  }
+}
+
+/** Build + load the library (empty + harmless if no skill dirs exist). */
+export function loadSkillLibrary(): SkillLibrary {
+  const lib = new SkillLibrary()
+  try { lib.load() } catch { /* never block the agent over skills */ }
+  return lib
+}

package/src/agent/stack.ts

@@ -0,0 +1,154 @@
+/**
+ * Stack-fused tools — the agent IS the operator console. It can read the live Ghost
+ * Protocol stack state and drive `dragon` subcommands (scale/wyrm/pentest/keep/net…)
+ * as first-class tools, not just guess at bash.
+ *
+ * Safety: read-only verbs run freely; everything else (pentest, deploy, install…) is
+ * `dangerous` → always prompts + shows the full command (never covered by --auto).
+ * Interactive/recursive/long-lived verbs (chat/ask/login/serve/up) are refused.
+ * Each invocation is a fresh subprocess of THIS CLI, time-bounded + output-capped.
+ *
+ * Copyright 2026 Ghost Protocol (Pvt) Ltd. All Rights Reserved.
+ */
+
+import { execFile } from 'node:child_process'
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import type { ToolSpec } from '../brain/types.js'
+import type { ToolContext } from './tools.js'
+import { loadConfig } from '../config.js'
+
+const SELF = process.argv[1] ?? '' // the dragon CLI entry (dist/index.js)
+const SAFE = new Set(['list', 'doctor', 'status', 'brains', 'whoami']) // read-only → no approval
+const BLOCKED = new Set(['chat', 'ask', 'login', 'logout', 'serve', 'up', 'down', 'init']) // interactive / recursive / long-lived
+const MAX_OUT = 20_000
+
+function runDragon(args: string[], cwd: string, timeout: number): Promise<{ out: string; code: number }> {
+  return new Promise((res) => {
+    execFile(process.execPath, [SELF, ...args], { cwd, timeout, maxBuffer: 1 << 20 }, (err, stdout, stderr) => {
+      const out = ((stdout || '') + (stderr || '')).slice(0, MAX_OUT)
+      const code = err && typeof (err as { code?: unknown }).code === 'number' ? (err as { code: number }).code : err ? 1 : 0
+      res({ out, code })
+    })
+  })
+}
+
+/** Run an arbitrary external process (a stack product), bounded + capped.
+ *  Keeps stdout/stderr SEPARATE — products print progress to stderr and the
+ *  machine-readable JSON to stdout, so a parser must read stdout alone. */
+function runProc(cmd: string, args: string[], cwd: string, timeout: number): Promise<{ stdout: string; stderr: string; code: number }> {
+  return new Promise((res) => {
+    execFile(cmd, args, { cwd, timeout, maxBuffer: 8 << 20 }, (err, stdout, stderr) => {
+      const code = err && typeof (err as { code?: unknown }).code === 'number' ? (err as { code: number }).code : err ? 1 : 0
+      res({ stdout: stdout || '', stderr: stderr || '', code })
+    })
+  })
+}
+
+/** Newest reports/<dir>/findings.json under a PhantomDragon repo (the scan output). */
+function newestFindings(pentestRoot: string): string | null {
+  const dir = join(pentestRoot, 'reports')
+  if (!existsSync(dir)) return null
+  const subs = readdirSync(dir).map((d) => join(dir, d)).filter((p) => { try { return statSync(p).isDirectory() } catch { return false } })
+  if (!subs.length) return null
+  subs.sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs)
+  const f = join(subs[0], 'findings.json')
+  return existsSync(f) ? f : null
+}
+
+export interface StackTools {
+  specs: ToolSpec[]
+  handles(name: string): boolean
+  call(name: string, args: Record<string, unknown>, ctx: ToolContext): Promise<string>
+}
+
+export function makeStackTools(): StackTools {
+  const specs: ToolSpec[] = [
+    {
+      name: 'stack_status',
+      description: 'Live state of the Ghost Protocol dragon stack (each product: installed / running / version), as JSON. Read-only — call it to know what is deployed before acting.',
+      parameters: { type: 'object', properties: {}, required: [] },
+    },
+    {
+      name: 'stack_run',
+      description: 'Run a `dragon` stack command for an ops task — e.g. "list", "doctor", "pentest scan <url>", "wyrm <…>", "keep <…>". Read-only verbs run freely; actions require approval. NOT for chat/ask/login/serve.',
+      parameters: { type: 'object', properties: { command: { type: 'string', description: 'the dragon subcommand + args, e.g. "pentest scan https://example.com"' } }, required: ['command'] },
+    },
+    {
+      name: 'stack_pentest',
+      description: 'Run a PhantomDragon web security scan against a URL (AUTHORIZED targets only) and return STRUCTURED findings (severity, category, CVSS, confirmed, remediation) + a risk summary. Long-running; writes a report. Requires PhantomDragon configured.',
+      parameters: { type: 'object', properties: { url: { type: 'string' }, profile: { type: 'string', enum: ['quick', 'standard', 'full', 'api_only', 'auth_only'] }, mode: { type: 'string', enum: ['safe', 'standard', 'aggressive'] } }, required: ['url'] },
+    },
+    {
+      name: 'stack_keep',
+      description: 'Run a DragonKeep system-security scan (READ-ONLY local inspection) and return STRUCTURED findings (severity, CVSS, fix) + a summary. scan_type: full | quick | malware | ransomware | hunt | score.',
+      parameters: { type: 'object', properties: { scan_type: { type: 'string', enum: ['full', 'quick', 'malware', 'ransomware', 'hunt', 'score'] }, profile: { type: 'string' } }, required: [] },
+    },
+  ]
+  return {
+    specs,
+    handles: (name) => ['stack_status', 'stack_run', 'stack_pentest', 'stack_keep'].includes(name),
+    async call(name, args, ctx) {
+      if (name === 'stack_pentest') return runPentest(args, ctx)
+      if (name === 'stack_keep') return runKeep(args, ctx)
+      if (!SELF) return 'error: stack tools unavailable (no CLI entry path)'
+      if (name === 'stack_status') {
+        const r = await runDragon(['list', '--json'], ctx.cwd, 30_000)
+        return r.out || '(no output)'
+      }
+      const command = String((args as { command?: string }).command ?? '').trim()
+      if (!command) return 'error: no command given'
+      const parts = command.split(/\s+/)
+      const verb = parts[0]
+      if (BLOCKED.has(verb)) return `error: "${verb}" can't be run as a tool (interactive / recursive / long-lived)`
+      if (!SAFE.has(verb) && !(await ctx.approve(`dragon ${command.slice(0, 100)}`, { detail: `dragon ${command}`, dangerous: true }))) {
+        return 'error: declined by user'
+      }
+      const r = await runDragon(parts, ctx.cwd, 180_000)
+      return `exit ${r.code}\n${r.out || '(no output)'}`
+    },
+  }
+}
+
+// ── Structured stack actions (typed results, not just passthrough) ──
+
+async function runPentest(args: Record<string, unknown>, ctx: ToolContext): Promise<string> {
+  const root = loadConfig().products?.pentest?.path
+  if (!root || !existsSync(root)) return 'error: PhantomDragon not configured — set products.pentest.path (run `dragon init`).'
+  const script = ['phantom_dragon_ai.py', 'phantomdragon.py'].map((s) => join(root, s)).find(existsSync)
+  if (!script) return `error: PhantomDragon entry script not found in ${root}`
+  const url = String(args.url ?? '').trim()
+  if (!url) return 'error: url is required'
+  const profile = String(args.profile ?? 'standard')
+  const mode = String(args.mode ?? 'safe')
+  if (!(await ctx.approve(`⚠ pentest scan ${url} (profile ${profile}, mode ${mode}) — authorized targets only`, { dangerous: true }))) return 'error: declined by user'
+  const r = await runProc('python3', [script, '-t', url, '--profile', profile, '--mode', mode], root, 600_000)
+  const fj = newestFindings(root)
+  if (!fj) return `scan exited ${r.code}; no findings.json produced.\n${(r.stderr || r.stdout).slice(-1200)}`
+  try {
+    const d = JSON.parse(readFileSync(fj, 'utf-8')) as { meta?: unknown; summary?: unknown; findings?: { id?: string; title?: string; severity?: string; category?: string; url?: string; confirmed?: boolean; cvss_score?: number; remediation?: string }[] }
+    const findings = (d.findings ?? []).slice(0, 15).map((f) => ({ id: f.id, title: f.title, severity: f.severity, category: f.category, url: f.url, confirmed: f.confirmed, cvss: f.cvss_score, remediation: (f.remediation ?? '').slice(0, 160) }))
+    return JSON.stringify({ report: fj, meta: d.meta, summary: d.summary, findings }).slice(0, MAX_OUT)
+  } catch {
+    return `scan complete but findings.json could not be parsed at ${fj}`
+  }
+}
+
+async function runKeep(args: Record<string, unknown>, ctx: ToolContext): Promise<string> {
+  const keepRoot = loadConfig().products?.keep?.path
+  const bin =
+    ([keepRoot && join(keepRoot, 'target/release/dragonkeep'), keepRoot && join(keepRoot, 'target/debug/dragonkeep'), '/usr/local/bin/dragonkeep', '/usr/bin/dragonkeep'].filter(Boolean) as string[]).find((p) => existsSync(p)) ?? 'dragonkeep'
+  const scanType = String(args.scan_type ?? 'quick')
+  const direct = ['malware', 'ransomware', 'hunt', 'score', 'ai', 'supply', 'anomaly']
+  const cmd = ['--quiet', '--format', 'json']
+  if (direct.includes(scanType)) cmd.push(scanType)
+  else cmd.push('scan', '--profile', String(args.profile ?? (scanType === 'full' ? 'standard' : 'quick')))
+  const r = await runProc(bin, cmd, ctx.cwd, 300_000)
+  try {
+    const d = JSON.parse(r.stdout) as { hostname?: string; summary?: unknown; sections?: { name?: string; findings?: { title?: string; severity?: string; cvss?: number; fix?: string }[] }[] }
+    const sections = (d.sections ?? []).map((s) => ({ name: s.name, findings: (s.findings ?? []).filter((f) => f.severity !== 'Pass').slice(0, 8).map((f) => ({ title: f.title, severity: f.severity, cvss: f.cvss, fix: (f.fix ?? '').slice(0, 140) })) }))
+    return JSON.stringify({ hostname: d.hostname, summary: d.summary, sections }).slice(0, MAX_OUT)
+  } catch {
+    return `dragonkeep exited ${r.code}${bin === 'dragonkeep' ? ' (binary not found — build it: cargo build --release in DragonKeep, or `dragon install keep`)' : ''}\n${(r.stderr || r.stdout).slice(0, 1500)}`
+  }
+}

package/src/agent/task.ts

@@ -0,0 +1,55 @@
+/**
+ * Sub-agents — the `task` tool. The agent can spawn a focused, READ-ONLY sub-agent
+ * to research/analyze a sub-problem (audit a file, summarize how something works,
+ * survey a codebase) without polluting the main thread. The sub-agent can read,
+ * grep, glob, list, and use skills — but cannot write, edit, or run shell, and
+ * cannot itself spawn tasks (no recursion / fork-bombs). It returns its findings.
+ *
+ * Copyright 2026 Ghost Protocol (Pvt) Ltd. All Rights Reserved.
+ */
+
+import type { Brain, ToolSpec } from '../brain/types.js'
+import type { SkillLibrary } from './skills.js'
+import type { ToolContext } from './tools.js'
+import { runAgent, buildSystemPrompt, type AgentDeps, type AgentRender } from './loop.js'
+
+export interface TaskTool {
+  spec: ToolSpec
+  call(args: Record<string, unknown>): Promise<string>
+}
+
+export function makeTaskTool(parent: { brain: Brain; skills: SkillLibrary | null; cwd: string }): TaskTool {
+  return {
+    spec: {
+      name: 'task',
+      description: 'Spawn a focused READ-ONLY sub-agent to research or analyze a sub-problem in isolation (e.g. "audit src/auth.ts for security bugs", "summarize how the brain adapter works"). It can read/grep/glob/list + use skills, but CANNOT write, edit, or run shell. Returns its findings. Use it to offload big read-heavy investigations and keep your own context clean.',
+      parameters: { type: 'object', properties: { task: { type: 'string', description: 'the self-contained subtask to investigate' } }, required: ['task'] },
+    },
+    async call(args) {
+      const prompt = String((args as { task?: string }).task ?? '').trim()
+      if (!prompt) return 'error: no task given'
+
+      const denyAll: ToolContext = { cwd: parent.cwd, approve: async () => false } // read-only sub-agent
+      const subDeps: AgentDeps = {
+        brain: parent.brain,
+        wyrm: null, portal: null, stack: null, mcp: null, task: null, // sub-agent: read + skills only, NO recursion
+        skills: parent.skills,
+        cwd: parent.cwd,
+        system:
+          buildSystemPrompt({ cwd: parent.cwd, wyrm: false, portal: false, brainId: `${parent.brain.id}:${parent.brain.model}`, skills: parent.skills?.count || undefined }) +
+          '\n\nYou are a FOCUSED SUB-AGENT spawned for ONE read-only investigation. Use read_file/grep/glob/list_dir/skill_* only — you CANNOT write, edit, or run shell (those are denied). Investigate thoroughly, then return a concise, complete, self-contained answer. Do not ask questions.',
+        toolCtx: denyAll,
+        messages: [],
+      }
+
+      let out = ''
+      const quiet: AgentRender = { onAssistantStart() {}, onDelta(s) { out += s }, onToolStart() {}, onToolEnd() {} }
+      try {
+        await runAgent(subDeps, prompt, quiet, new AbortController().signal)
+        return out.trim() || '(sub-agent returned nothing)'
+      } catch (e) {
+        return `sub-agent error: ${String(e instanceof Error ? e.message : e)}`
+      }
+    },
+  }
+}