cdsa-harness 0.14.2 → 0.18.0

package/README.md

@@ -9,8 +9,13 @@
 ```
 
 - **의존성 0개** — Node 18+ 내장 기능만(`fetch`/`readline`/`node:test`)
-- **실시간 스트리밍** — 모델 응답이 토큰 단위로 흐름(`/stream` 토글, OpenAI·Claude·mock)
-- **실제 LLM 연결** — OpenAI · Anthropic(Claude) · OpenRouter, 또는 키 없이 `mock`
+- **실시간 스트리밍** — 모델 응답이 토큰 단위로 흐름(`/stream` 토글)
+- **실제 LLM 연결** — OpenAI · Anthropic(Claude) · OpenRouter · **Ollama(로컬·폐쇄망, 키 불필요)** · `mock`
+- **에이전트 도구** — 폴더/파일 읽기 · `edit_file` 부분 수정 · `search_files` 재귀 검색 · 셸(옵션) · HWPX
+- **`@파일명` 멘션** — 입력에 `@memo.txt` 처럼 쓰면 파일 내용 자동 첨부
+- **`/resume`** — 지난 대화 자동 저장·이어가기, ↑↓ 명령 히스토리도 세션 간 유지
+- **서브에이전트** — 모델이 큰 작업을 `spawn_agent` 로 하위 에이전트에 위임(화면엔 `┆` 로 구분, 중첩 위임 차단)
+- **`/update`** — 명령 한 번으로 자기 자신을 최신 버전으로 업데이트(npm 설치본)
 - **교육 모드** — 매 반복마다 모델에 보내는 메시지 구성·추정 토큰·시스템 프롬프트, 실제 토큰 사용량/응답시간까지 그대로 표시
 - **MCP 클라이언트** — Claude Code·Cursor 등과 **공용 표준**. MCP 서버를 그대로 붙여 도구로 사용
 - **플러그인** — npm 으로 설치하거나 `.cdsa/plugins/` 에 JS 파일 → **도구 자동 등록**
@@ -66,8 +71,15 @@ export OPENROUTER_API_KEY=sk-or-...
 
 ## 슬래시 명령
 
+Claude Code·OpenCode 컨벤션을 따릅니다.
+
 | 명령 | 설명 |
 |------|------|
+| `/new` (=`/clear`) · `/compact` · `/resume` | 새 대화 · **모델이 대화를 요약해 압축** · 지난 대화 이어가기 |
+| `/undo` | 마지막 파일 변경 되돌리기 |
+| `/init` · `/memory` | **모델이 폴더를 파악해 AGENT.md 생성** · 규칙 파일 보기 |
+| `/auto` | 자동 수락 토글 (신뢰가 쌓이면 diff 승인 생략) |
+| `/status` (=`/cost`) · `/models` | 상태·세션 누적 토큰 · 모델 목록(ollama 는 설치분 실시간) |
 | `/guide` · `/tutorial` | 빠른 시작 안내 · 단계별 인터랙티브 튜토리얼 |
 | `/workspace <폴더>` | 작업 폴더 보기/변경 (`.` = 현재 폴더) |
 | `/color` | 색상 켜기/끄기(흑백) |
@@ -186,6 +198,14 @@ npm pack cdsa-harness          # → cdsa-harness-x.y.z.tgz 생성
 npm install -g ./cdsa-harness-x.y.z.tgz   # 인터넷 불필요
 ```
 
+**Ollama — 인터넷 없이 로컬 LLM 으로 (가장 쉬움):**
+```bash
+# 폐쇄망 PC 에 Ollama 와 모델(예: qwen2.5:7b, exaone3.5)을 반입·설치한 뒤
+cdsa-harness
+› /setup   → 4) ollama 선택 (키 불필요, 설치된 모델 자동 감지)
+```
+> 원격 Ollama 서버는 주소만 입력(예: `http://10.0.0.5:11434`). `OLLAMA_HOST` 환경변수도 인식.
+
 **사내/폐쇄망 LLM (OpenAI 호환 서버 — vLLM, 내부 게이트웨이 등):**
 `config.json` 의 `base_url` 에 **전체 엔드포인트**를 적으면 그쪽으로 호출합니다.
 ```json
@@ -226,8 +246,12 @@ npm install -g ./cdsa-harness-x.y.z.tgz   # 인터넷 불필요
 |------|------|:----:|
 | `list_dir` | 폴더 나열 | 자동 |
 | `read_file` | 파일 읽기 | 자동 |
-| `write_file` | 파일 생성/수정 | **diff 승인** |
+| `search_files` | 파일명·내용 재귀 검색 | 자동 |
+| `write_file` | 새 파일/전체 덮어쓰기 | **diff 승인** |
+| `edit_file` | **부분 수정**(old→new 치환) | **diff 승인** |
 | `run_shell` | 셸 실행 | **승인**(기본 차단) |
+| `spawn_agent` | 하위 에이전트에 작업 위임(중첩 불가) | 자동 |
+| `hwpx_read` | 한컴 .hwpx 본문 추출 | 자동 |
 
 모든 도구는 작업 폴더 밖으로 나갈 수 없습니다(경로 sandbox).
 
@@ -252,6 +276,13 @@ node-cli/
 └── test/core.test.js     # node --test
 ```
 
+## 설계 철학
+
+1. **모델이 먼저다** — 하드코딩 대신 모델에게 시킨다. `/init`(규칙 파일 생성)·`/compact`(대화 압축)는 로직이 아니라 **모델이 직접 수행**한다. 지금 70% 작동하는 것이 다음 모델에선 90%가 된다.
+2. **단순함이 속도다** — 웹앱이 아닌 CLI. `read + edit + search + shell` 최소 프리미티브 위에 스킬·플러그인·MCP 로 나머지 전부를 쌓는다. 의존성 0개.
+3. **신뢰의 전환** — 처음엔 모든 변경을 diff 로 승인받고, 신뢰가 쌓이면 `/auto` 로 자동 수락. 승인이 반복되면 도구가 먼저 전환을 제안한다.
+4. **접근성의 민주화** — 예산 없는 조직도 쓸 수 있게: 폐쇄망 Ollama·단일 실행파일·공공 업무 스킬 기본 내장.
+
 ## 테스트
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdsa-harness",
-  "version": "0.14.2",
+  "version": "0.18.0",
   "description": "AI 에이전트의 내부 동작을 단계별로 드러내는 교육용 터미널 하네스. 실시간 스트리밍 + OpenAI/Claude/OpenRouter + MCP + npm 플러그인·크로스포맷 스킬.",
   "type": "module",
   "bin": {

package/src/builtins.js

@@ -2,7 +2,7 @@
 // 스킬/플러그인/버전을 바꾼 뒤 `node scripts/gen-builtins.mjs` 로 재생성하세요.
 import p0 from "../plugins/hwpx_read.mjs";
 
-export const VERSION = "0.14.2";
+export const VERSION = "0.18.0";
 
 export const BUILTIN_PLUGINS = [p0];
 

package/src/cli.js

@@ -17,7 +17,7 @@ import {
   loadConfig,
   saveConfig,
 } from "./config.js";
-import { execFileSync } from "node:child_process";
+import { execFileSync, execSync } from "node:child_process";
 
 import { AgentLoop, Step } from "./loop.js";
 import { LLMClient } from "./llm.js";
@@ -26,7 +26,7 @@ import { discoverNpmExtensions, loadPlugins } from "./plugins.js";
 import { SessionLog, sessionsDir } from "./session.js";
 import { loadSkills, renderSkill } from "./skills.js";
 import { Toolbox } from "./tools.js";
-import { c, panel, renderDiff, setColor } from "./ui.js";
+import { c, panel, renderDiff, renderMarkdown, setColor } from "./ui.js";
 
 // VERSION 은 src/builtins.js(생성물)에서 가져온다 — npm/exe 양쪽에서 동일.
 
@@ -87,8 +87,8 @@ function printTeach(ev, stream) {
         lines.push(`  ${roleColor(m.role.padEnd(9))} ${c.grey(`${m.chars}자${m.extra || ""}`)}`);
       }
       lines.push(c.grey(`제공 도구(${d.tools?.length || 0}): ${(d.tools || []).join(", ")}`));
-      console.log(panel(lines, { title: `🧠 ② LLM 호출 — 반복 ${d.iteration}`, color: "magenta" }));
-      if (d.systemPrompt) {
+      console.log(panel(lines, { title: `${d.sub ? "┆ " : ""}🧠 ② LLM 호출 — 반복 ${d.iteration}`, color: "magenta" }));
+      if (d.systemPrompt && !d.sub) {
         console.log(panel(clip(d.systemPrompt, 600).split("\n"), {
           title: "📜 시스템 프롬프트 (규칙+폴더가 여기 주입됨)",
           color: "grey",
@@ -112,14 +112,14 @@ function printTeach(ev, stream) {
         return;
       }
       const lines = [];
-      if (ev.detail && ev.detail !== "(텍스트 없음)") lines.push(...clip(ev.detail, 1200).split("\n"));
+      if (ev.detail && ev.detail !== "(텍스트 없음)") lines.push(...renderMarkdown(clip(ev.detail, 1200)));
       for (const tc of d.toolCalls || []) {
         lines.push(c.yellow(`↳ 도구 호출 요청: ${c.bold(tc.name)}(${clip(JSON.stringify(tc.args), 200)})`));
       }
       const meta = replyMetaLine(d);
       if (meta) lines.push(c.grey("─ " + meta));
       else lines.push(c.dim("(mock: 토큰/지연 측정 없음)"));
-      console.log(panel(lines.length ? lines : ["(빈 응답)"], { title: "🤖 ③ 모델 응답 (원본 판단)", color: "green" }));
+      console.log(panel(lines.length ? lines : ["(빈 응답)"], { title: `${d.sub ? "┆ " : ""}🤖 ③ 모델 응답 (원본 판단)`, color: "green" }));
       return;
     }
 
@@ -145,7 +145,8 @@ function printTeach(ev, stream) {
       return;
 
     case Step.DONE:
-      console.log(panel((ev.detail || "완료").split("\n"), { title: "✅ 완료", color: "green" }));
+      if (d.sub) { console.log(c.grey("┆ ") + c.green("✅ 서브에이전트 완료")); return; }
+      console.log(panel(renderMarkdown(ev.detail || "완료"), { title: "✅ 완료", color: "green" }));
       return;
 
     case Step.ERROR:
@@ -166,10 +167,13 @@ function printCompact(ev, stream) {
       for (const tc of d.toolCalls || []) console.log(c.yellow(`  ↳ ${tc.name}(${clip(JSON.stringify(tc.args), 120)})`));
       return;
     }
-    if (ev.detail && ev.detail !== "(텍스트 없음)") console.log(panel(ev.detail.split("\n"), { title: "🤖 모델", color: "green" }));
+    if (ev.detail && ev.detail !== "(텍스트 없음)") console.log(panel(renderMarkdown(ev.detail), { title: `${d.sub ? "┆ " : ""}🤖 모델`, color: "green" }));
     return;
   }
-  if (ev.step === Step.DONE) return console.log(panel((ev.detail || "완료").split("\n"), { title: "✅ 완료", color: "green" }));
+  if (ev.step === Step.DONE) {
+    if (ev.data && ev.data.sub) return console.log(c.grey("┆ ") + c.green("✅ 서브에이전트 완료"));
+    return console.log(panel(renderMarkdown(ev.detail || "완료"), { title: "✅ 완료", color: "green" }));
+  }
   if (ev.step === Step.ERROR) return console.log(panel((ev.detail || "").split("\n"), { title: `❌ ${ev.title}`, color: "red" }));
   if (ev.step === Step.FEEDBACK) return;
   let detail = clip((ev.detail || "").trim().replace(/\s+/g, " "), 110);
@@ -178,11 +182,14 @@ function printCompact(ev, stream) {
   console.log(line);
 }
 
-function makeApproval(ask) {
+function makeApproval(ask, cfg) {
+  let streak = 0; // 연속 승인 횟수 — 신뢰가 쌓이면 자동 수락을 제안한다
+  let hinted = false;
   return async (req) => {
-    if (req.toolName === "write_file") {
+    if (req.toolName === "write_file" || req.toolName === "edit_file") {
+      const label = req.toolName === "edit_file" ? "부분 수정 제안" : "파일 쓰기 제안";
       console.log(panel(renderDiff(req.diff || "(변경 미리보기 없음)"), {
-        title: `🔐 파일 수정 제안 — ${req.path}`,
+        title: `🔐 ${label} — ${req.path}`,
         color: "yellow",
       }));
     } else if (req.toolName === "run_shell") {
@@ -193,6 +200,11 @@ function makeApproval(ask) {
     const raw = await ask(c.yellow("이 작업을 승인하시겠습니까? [y/N] "));
     const ans = (raw || "").trim().toLowerCase();
     const approved = ans === "y" || ans === "yes";
+    streak = approved ? streak + 1 : 0;
+    if (approved && streak >= 3 && !hinted && cfg.approval_mode === "manual") {
+      hinted = true;
+      console.log(c.dim("💡 계속 승인 중이시네요 — 신뢰가 쌓였다면 ") + c.cyan("/auto") + c.dim(" 로 자동 수락을 켤 수 있어요."));
+    }
     return { approved, reason: approved ? "" : "사용자가 거부했습니다." };
   };
 }
@@ -271,7 +283,11 @@ function printIntro(cfg) {
   console.log(renderBanner());
   console.log(c.dim("AI 에이전트의 내부 동작을 단계별로 드러내는 교육용 하네스") + "  " + c.cyan("· made by CDSA"));
   console.log();
-  const keySource = cfg.provider === "mock" ? "-" : cfg.api_key ? "config.json" : ENV_KEYS[cfg.provider] && process.env[ENV_KEYS[cfg.provider]] ? `환경변수 ${ENV_KEYS[cfg.provider]}` : c.red("없음");
+  const keySource =
+    cfg.provider === "mock" ? "-"
+    : cfg.provider === "ollama" ? "불필요(로컬)"
+    : cfg.api_key ? "config.json"
+    : ENV_KEYS[cfg.provider] && process.env[ENV_KEYS[cfg.provider]] ? `환경변수 ${ENV_KEYS[cfg.provider]}` : c.red("없음");
   const rows = [
     ["버전", `v${VERSION}`],
     ["provider", cfg.provider],
@@ -384,25 +400,26 @@ function printHelp() {
       [
         c.bold("사용법"),
         `시키고 싶은 일을 한국어로 입력하세요. 예) ${c.cyan("notes.txt 맨 아래에 할 일 3개 추가해줘")}`,
+        `${c.cyan("@파일명")} 을 쓰면 그 파일 내용이 자동 첨부됩니다. 예) ${c.cyan("@memo.txt 이거 요약해줘")}`,
+        "",
+        c.bold("대화"),
+        `  ${c.cyan("/new")}(=/clear)  새 대화 · ${c.cyan("/compact")} 대화를 모델이 요약해 압축 · ${c.cyan("/resume")} 지난 대화 이어가기`,
+        `  ${c.cyan("/undo")}  마지막 파일 변경 되돌리기 · ${c.cyan("/context")} 모델에 보내는 컨텍스트 보기`,
         "",
-        c.bold("슬래시 명령"),
-        `  ${c.cyan("/guide")}    처음 사용자용 빠른 시작 안내`,
-        `  ${c.cyan("/tutorial")} 단계별 인터랙티브 튜토리얼`,
-        `  ${c.cyan("/color")}    색상 켜기/끄기(흑백)`,
-        `  ${c.cyan("/about")}    이 도구 정보(made by CDSA)`,
-        `  ${c.cyan("/setup")}    제공자·API 키·모델 연결(대화형)`,
-        `  ${c.cyan("/provider")} <openai|anthropic|openrouter|mock> 제공자 변경`,
-        `  ${c.cyan("/model")} <이름>   모델 변경`,
-        `  ${c.cyan("/teach")}    교육 모드 켜기/끄기(내부 과정 펼쳐보기)`,
-        `  ${c.cyan("/stream")}   실시간 스트리밍 출력 켜기/끄기`,
-        `  ${c.cyan("/context")}  지금 모델에 보내는 컨텍스트 들여다보기`,
+        c.bold("프로젝트"),
+        `  ${c.cyan("/init")}  모델이 폴더를 파악해 AGENT.md(프로젝트 규칙) 생성 · ${c.cyan("/memory")} 규칙 파일 보기`,
         `  ${c.cyan("/workspace")} <폴더>  작업 폴더 보기/변경 ('.' = 현재 폴더)`,
-        `  ${c.cyan("/skills")}   스킬 목록(.cdsa/skills 의 /명령들)`,
-        `  ${c.cyan("/plugins")}  플러그인 목록(파일·npm 추가 도구)`,
-        `  ${c.cyan("/mcp")}      연결된 MCP 서버/도구(다른 에이전트와 공용)`,
-        `  ${c.cyan("/reset")}    대화/컨텍스트 초기화`,
-        `  ${c.cyan("/config")}   현재 설정값`,
-        `  ${c.cyan("/quit")}     종료 (Ctrl+D)`,
+        "",
+        c.bold("모델·설정"),
+        `  ${c.cyan("/setup")} 연결 마법사 · ${c.cyan("/model")} <이름> 변경 · ${c.cyan("/models")} 목록(ollama 는 설치분) · ${c.cyan("/provider")} 전환`,
+        `  ${c.cyan("/auto")} 자동 수락 토글 · ${c.cyan("/status")}(=/cost) 상태·누적 토큰 · ${c.cyan("/update")} 자기 업데이트`,
+        `  ${c.cyan("/teach")} 내부과정 펼치기 · ${c.cyan("/stream")} 실시간 출력 · ${c.cyan("/color")} 색상`,
+        "",
+        c.bold("확장"),
+        `  ${c.cyan("/skills")} 스킬 목록 · ${c.cyan("/plugins")} 플러그인 · ${c.cyan("/mcp")} MCP 서버`,
+        "",
+        c.bold("기타"),
+        `  ${c.cyan("/guide")} 빠른 시작 · ${c.cyan("/tutorial")} 튜토리얼 · ${c.cyan("/about")} 정보 · ${c.cyan("/quit")} 종료(Ctrl+D)`,
         "",
         c.bold("교육 모드에서 보이는 단계"),
         "  ① 입력 → ② LLM 호출(컨텍스트·도구) → ③ 모델 응답(토큰·지연) →",
@@ -427,13 +444,14 @@ async function runSetup(ask, cfg) {
       `  ${c.bold("1")}) openai      (GPT, 키: ${ENV_KEYS.openai})`,
       `  ${c.bold("2")}) anthropic   (Claude, 키: ${ENV_KEYS.anthropic})`,
       `  ${c.bold("3")}) openrouter  (여러 모델 중계, 키: ${ENV_KEYS.openrouter})`,
-      `  ${c.bold("4")}) mock        (키 없이 연습)`,
+      `  ${c.bold("4")}) ollama      (로컬·폐쇄망 LLM, 키 불필요) 🏢`,
+      `  ${c.bold("5")}) mock        (키 없이 연습)`,
     ],
     { title: "🔌 연결 설정 (/setup)", color: "cyan" }
   ));
-  const pickRaw = await ask(c.cyan("제공자 번호 [1-4] (취소: Enter): "));
+  const pickRaw = await ask(c.cyan("제공자 번호 [1-5] (취소: Enter): "));
   if (pickRaw === null) return false;
-  const provider = { "1": "openai", "2": "anthropic", "3": "openrouter", "4": "mock" }[pickRaw.trim()];
+  const provider = { "1": "openai", "2": "anthropic", "3": "openrouter", "4": "ollama", "5": "mock" }[pickRaw.trim()];
   if (!provider) {
     console.log(c.yellow("취소했습니다."));
     return false;
@@ -442,6 +460,29 @@ async function runSetup(ask, cfg) {
 
   if (provider === "mock") {
     cfg.model = "mock-agent";
+  } else if (provider === "ollama") {
+    const hostAns = await ask(c.cyan("Ollama 주소 [http://localhost:11434]: "));
+    if (hostAns === null) return false;
+    const host = (hostAns.trim() || "http://localhost:11434").replace(/\/+$/, "");
+    cfg.base_url = `${host}/v1/chat/completions`;
+    cfg.api_key = "ollama"; // 로컬 LLM 은 키가 필요 없다(호환용 자리표시)
+    // 설치된 모델 자동 감지(/api/tags) — 실패해도 조용히 추천 목록 사용
+    let installed = [];
+    try {
+      const ctrl = new AbortController();
+      const t = setTimeout(() => ctrl.abort(), 2000);
+      const res = await fetch(`${host}/api/tags`, { signal: ctrl.signal });
+      clearTimeout(t);
+      if (res.ok) installed = ((await res.json()).models || []).map((m) => m.name);
+    } catch {
+      console.log(c.yellow("  (Ollama 에 연결하지 못했어요 — `ollama serve` 실행 여부를 확인하세요. 계속 진행합니다.)"));
+    }
+    if (installed.length) console.log(c.green(`  설치된 모델: ${installed.slice(0, 8).join(", ")}`));
+    const sugg = installed.length ? installed : SUGGESTED_MODELS.ollama;
+    const def = sugg[0];
+    const m = await ask(c.cyan(`모델 [${def}]: `));
+    if (m === null) return false;
+    cfg.model = m.trim() || def;
   } else {
     const envName = ENV_KEYS[provider];
     const envVal = (process.env[envName] || "").trim();
@@ -504,7 +545,7 @@ export async function main(argv = []) {
       "CDSA Harness — AI 에이전트 내부를 드러내는 교육용 하네스 (터미널)\n\n" +
         "사용법: cdsa-harness [옵션]\n" +
         "       cdsa-harness add <npm-패키지>   플러그인 설치(이후 자동 로드)\n" +
-        "  --provider <openai|anthropic|openrouter|mock>\n" +
+        "  --provider <openai|anthropic|openrouter|ollama|mock>\n" +
         "  --model <모델명>\n" +
         "  --workspace <폴더경로>\n" +
         "  --setup                대화형 연결 설정 실행\n" +
@@ -546,12 +587,25 @@ export async function main(argv = []) {
   if (args.noColor) cfg.no_color = true;
   if (cfg.no_color) setColor(false); // 색상 끄기(흑백)
 
-  const rl = readline.createInterface({ input: stdin, output: stdout });
+  // 명령 히스토리(↑↓)를 세션 간에도 기억한다.
+  const histPath = path.join(configDir(), "history");
+  let savedHistory = [];
+  try {
+    savedHistory = fs.readFileSync(histPath, "utf8").split("\n").filter(Boolean).slice(0, 200);
+  } catch { /* 첫 실행 */ }
+  const rl = readline.createInterface({ input: stdin, output: stdout, history: savedHistory, historySize: 200 });
+  const saveHistory = () => {
+    try {
+      fs.mkdirSync(configDir(), { recursive: true });
+      fs.writeFileSync(histPath, (rl.history || []).slice(0, 200).join("\n"), "utf8");
+    } catch { /* ignore */ }
+  };
   let session = null;
   let mcp = { tools: [], servers: [], errors: [], closeAll: () => {} };
 
   // Ctrl+C → 깔끔하게 종료(스택트레이스 없이). 어디서 누르든 안전.
   const gracefulExit = () => {
+    saveHistory();
     try { rl.close(); } catch { /* */ }
     try { session && session.close(); } catch { /* */ }
     try { mcp && mcp.closeAll && mcp.closeAll(); } catch { /* */ }
@@ -559,14 +613,50 @@ export async function main(argv = []) {
     process.exit(0);
   };
   rl.on("SIGINT", gracefulExit);
-  // 프롬프트 헬퍼: Ctrl+C(AbortError) 등은 null 로 돌려 호출부가 취소로 처리.
-  const ask = async (q) => {
-    try {
-      return await rl.question(q);
-    } catch {
-      return null;
-    }
-  };
+  // 프롬프트 헬퍼. TTY 면 rl.question 그대로(히스토리·편집 지원).
+  // 파이프/스크립트 입력(non-TTY)은 줄을 큐로 받아 어떤 타이밍에 물어도 유실되지 않게 한다
+  // (모델 호출 중 도착한 승인 답변 줄이 사라지던 문제 해결 — CI/데모 자동화 가능).
+  let ask;
+  if (stdin.isTTY) {
+    ask = async (q) => {
+      try {
+        return await rl.question(q);
+      } catch {
+        return null;
+      }
+    };
+  } else {
+    const lineQueue = [];
+    let pendingResolve = null;
+    let closed = false;
+    rl.on("line", (l) => {
+      if (pendingResolve) {
+        const r = pendingResolve;
+        pendingResolve = null;
+        r(l);
+      } else lineQueue.push(l);
+    });
+    rl.on("close", () => {
+      closed = true;
+      if (pendingResolve) {
+        const r = pendingResolve;
+        pendingResolve = null;
+        r(null);
+      }
+    });
+    ask = (q) => {
+      process.stdout.write(q);
+      if (lineQueue.length) {
+        const l = lineQueue.shift();
+        process.stdout.write(l + "\n");
+        return Promise.resolve(l);
+      }
+      if (closed) return Promise.resolve(null);
+      return new Promise((res) => {
+        pendingResolve = res;
+      });
+    };
+  }
 
   if (args.setup) {
     await runSetup(ask, cfg);
@@ -582,7 +672,7 @@ export async function main(argv = []) {
   if (newer) {
     console.log(
       c.yellow(`⬆️  새 버전 v${newer} 가 나왔어요!`) +
-        c.dim(`  업데이트: npm i -g cdsa-harness@latest  ·  exe 는 Releases 에서 새로 받기`) +
+        c.dim(`  지금 바로: `) + c.cyan("/update") + c.dim(` · exe 는 Releases 에서 새로 받기`) +
         "\n"
     );
   }
@@ -618,7 +708,7 @@ export async function main(argv = []) {
     client: makeClient(cfg),
     toolbox,
     onEvent: makePrinter(cfg, stream),
-    approvalCallback: makeApproval(ask),
+    approvalCallback: makeApproval(ask, cfg),
     session,
     onToken,
   });
@@ -626,6 +716,37 @@ export async function main(argv = []) {
 
   const rule = () => console.log(c.grey("─".repeat(Math.min(80, stdout.columns || 80))));
 
+  // @파일 멘션: 입력 속 @경로 가 작업 폴더의 실제 파일이면 내용을 프롬프트에 첨부한다.
+  const expandMentions = (text) => {
+    const tokens = [...text.matchAll(/@([\w가-힣./\\-]+)/g)].map((m) => m[1]);
+    let out = text;
+    for (const t of [...new Set(tokens)]) {
+      try {
+        const r = toolbox.readFile(t);
+        const clipped = (r.output || "").slice(0, 4000);
+        out += `\n\n[첨부 @${t}]\n${clipped}`;
+        console.log(c.dim(`📎 @${t} 첨부됨 (${clipped.length}자)`));
+      } catch { /* 파일이 아니면 무시(이메일 등) */ }
+    }
+    return out;
+  };
+
+  // 대화 자동저장(/resume 용) + 멘션 확장을 겸하는 실행 헬퍼.
+  const convPath = path.join(configDir(), "last_session.json");
+  const runTurn = async (promptText) => {
+    rule();
+    try {
+      await loop.run(expandMentions(promptText));
+    } catch (e) {
+      console.log(c.red(`실행 오류: ${e?.message || e}`));
+    }
+    rule();
+    try {
+      fs.mkdirSync(configDir(), { recursive: true });
+      fs.writeFileSync(convPath, JSON.stringify({ time: Date.now(), provider: cfg.provider, model: cfg.model, messages: loop.messages }), "utf8");
+    } catch { /* 저장 실패 무시 */ }
+  };
+
   // 첫 실행 온보딩(한 번만 — ~/.cdsa_harness/.welcomed 표시): 작업 폴더 설정 + 튜토리얼
   const markerPath = path.join(configDir(), ".welcomed");
   if (stdin.isTTY && !fs.existsSync(markerPath)) {
@@ -695,7 +816,154 @@ export async function main(argv = []) {
       ], { title: "ℹ️  about", color: "cyan" }));
       continue;
     }
-    if (low === "/reset") { loop.reset(); console.log(c.green("컨텍스트를 초기화했습니다.")); continue; }
+    // /clear·/new — Claude Code·OpenCode 컨벤션(= 기존 /reset)
+    if (low === "/reset" || low === "/clear" || low === "/new") {
+      loop.reset();
+      console.log(c.green("새 대화를 시작합니다(컨텍스트 초기화)."));
+      continue;
+    }
+    // /compact — 대화를 '모델이 직접' 요약해 컨텍스트를 압축 (Claude Code 방식, 모델-퍼스트)
+    if (low === "/compact") {
+      if (loop.messages.length < 4) {
+        console.log(c.dim("아직 압축할 대화가 충분하지 않습니다."));
+        continue;
+      }
+      const before = loop.messages.length;
+      console.log(c.dim("모델에게 대화 요약을 맡겨 컨텍스트를 압축합니다…"));
+      try {
+        const req = [
+          ...loop.messages,
+          {
+            role: "user",
+            content:
+              "지금까지의 대화를 다음 작업에 꼭 필요한 것만 남긴 한국어 요약으로 만들어줘: 확인된 사실, 내린 결정, 파일 변경 내역, 미완료 작업. 요약문만 출력해.",
+          },
+        ];
+        const r = await loop.client.chat(req, []);
+        const summary = (r.content || "").trim();
+        if (!summary) throw new Error("빈 요약");
+        loop.reset();
+        loop.messages.push(
+          { role: "user", content: `[이전 대화 요약]\n${summary}` },
+          { role: "assistant", content: "요약을 확인했습니다. 이어서 진행하겠습니다." }
+        );
+        console.log(c.green(`압축 완료 — 메시지 ${before}개 → ${loop.messages.length}개`));
+      } catch (e) {
+        console.log(c.yellow(`압축 실패: ${e.message}`));
+      }
+      continue;
+    }
+    // /undo — 마지막 파일 변경 1건 되돌리기 (OpenCode 컨벤션)
+    if (low === "/undo") {
+      try {
+        console.log(c.green(toolbox.undoLast().output));
+      } catch (e) {
+        console.log(c.yellow(e.message));
+      }
+      continue;
+    }
+    // /update — 자기 자신을 최신 버전으로 업데이트(npm 설치본). exe 는 다운로드 안내.
+    if (low === "/update") {
+      let isSea = false;
+      try {
+        isSea = (await import("node:sea")).isSea();
+      } catch { /* 구버전 Node — SEA 아님 */ }
+      if (isSea) {
+        console.log(c.yellow("단일 실행파일(exe) 버전은 파일 교체 방식이라 자동 업데이트가 없어요."));
+        console.log(c.dim("최신 exe 다운로드: ") + c.cyan("https://github.com/cdsassj00/miniharness/releases/latest"));
+        continue;
+      }
+      console.log(c.cyan("최신 버전으로 업데이트합니다… (npm i -g cdsa-harness@latest)"));
+      try {
+        execSync("npm i -g cdsa-harness@latest", { stdio: "inherit" });
+        console.log(c.green("✅ 업데이트 완료! /quit 후 다시 실행하면 새 버전이 적용됩니다."));
+      } catch (e) {
+        console.log(c.red(`업데이트 실패: ${e.message}`));
+        console.log(c.dim("직접 실행: npm i -g cdsa-harness@latest"));
+      }
+      continue;
+    }
+    // /auto — 자동 수락 토글(신뢰 전환). Claude Code 의 auto-accept 에 해당.
+    if (low === "/auto") {
+      cfg.approval_mode = cfg.approval_mode === "auto" ? "manual" : "auto";
+      console.log(
+        cfg.approval_mode === "auto"
+          ? c.green("자동 수락 ON — 파일 수정·셸을 묻지 않고 실행합니다. (해제: /auto)")
+          : c.green("자동 수락 OFF — 변경 전 diff 를 보여주고 승인을 받습니다.")
+      );
+      continue;
+    }
+    // /init — '모델에게' 폴더를 파악시켜 AGENT.md 프로젝트 규칙을 만들게 한다 (Claude Code /init)
+    if (low === "/init") {
+      await runTurn(
+        "이 작업 폴더를 list_dir/read_file/search_files 로 파악한 뒤, 앞으로의 에이전트 작업 지침이 될 " +
+          "AGENT.md 파일을 write_file 로 생성해줘. 포함: ①프로젝트/폴더 개요 ②작업 시 지켜야 할 규칙(말투·제약·주의) " +
+          "③자주 할 작업 예시. 이미 AGENT.md 가 있으면 읽고 부족한 부분만 개선해."
+      );
+      continue;
+    }
+    // /status·/cost — 현재 상태 + 세션 누적 토큰 (Claude Code 컨벤션)
+    if (low === "/status" || low === "/cost") {
+      const u = loop.usage;
+      console.log(
+        panel(
+          [
+            `${c.grey("모델".padEnd(6))} ${c.bold(`${cfg.provider} · ${cfg.model}`)}`,
+            `${c.grey("폴더".padEnd(6))} ${cfg.workspacePath()}`,
+            `${c.grey("승인".padEnd(6))} ${cfg.approval_mode === "auto" ? c.yellow("자동 수락") : "수동(diff 확인)"} · 셸 ${cfg.allow_shell ? "허용" : "차단"}`,
+            `${c.grey("대화".padEnd(6))} 메시지 ${loop.messages.length}개 (/compact 로 압축 가능)`,
+            `${c.grey("토큰".padEnd(6))} 입력 ${u.input.toLocaleString()} · 출력 ${u.output.toLocaleString()} · 합계 ${c.bold(u.total.toLocaleString())} (호출 ${u.calls}회)`,
+          ],
+          { title: "📊 상태 (/status)", color: "cyan" }
+        )
+      );
+      continue;
+    }
+    // /models — 쓸 수 있는 모델 나열 (ollama 는 설치된 모델 실시간 조회)
+    if (low === "/models") {
+      if (cfg.provider === "ollama") {
+        const host = (cfg.base_url || "http://localhost:11434/v1/chat/completions").replace(/\/v1\/.*$/, "");
+        try {
+          const ctrl = new AbortController();
+          const t = setTimeout(() => ctrl.abort(), 2000);
+          const res = await fetch(`${host}/api/tags`, { signal: ctrl.signal });
+          clearTimeout(t);
+          const models = ((await res.json()).models || []).map((m) => m.name);
+          console.log(panel(models.length ? models.map((m) => (m === cfg.model ? c.green("● " + m) : "  " + m)) : [c.dim("설치된 모델 없음 — ollama pull <모델>")], { title: `🤖 Ollama 모델 (${host})`, color: "cyan" }));
+        } catch {
+          console.log(c.yellow(`Ollama(${host})에 연결하지 못했습니다 — ollama serve 확인.`));
+        }
+      } else {
+        const sugg = SUGGESTED_MODELS[cfg.provider] || [];
+        console.log(panel(sugg.map((m) => (m === cfg.model ? c.green("● " + m) : "  " + m)), { title: `🤖 추천 모델 (${cfg.provider}) — 변경: /model <이름>`, color: "cyan" }));
+      }
+      continue;
+    }
+    // /memory — 프로젝트 규칙 파일(AGENT.md) 보기 (Claude Code /memory)
+    if (low === "/memory") {
+      const candidates = ["AGENT.md", "AGENTS.md", "CLAUDE.md", "rules.md"].map((n) => path.join(cfg.workspacePath(), n));
+      const found = candidates.find((p) => fs.existsSync(p));
+      if (found) {
+        console.log(panel(fs.readFileSync(found, "utf8").split("\n").slice(0, 40), { title: `🧠 프로젝트 규칙 — ${path.basename(found)}`, color: "cyan" }));
+        console.log(c.dim(`전체 경로: ${found} (매 턴 시스템 프롬프트에 주입됩니다)`));
+      } else {
+        console.log(c.yellow("프로젝트 규칙 파일이 없습니다. ") + c.cyan("/init") + c.dim(" 을 실행하면 모델이 폴더를 파악해 AGENT.md 를 만들어줍니다."));
+      }
+      continue;
+    }
+    if (low === "/resume") {
+      try {
+        const saved = JSON.parse(fs.readFileSync(convPath, "utf8"));
+        if (!Array.isArray(saved.messages) || !saved.messages.length) throw new Error("빈 세션");
+        loop.messages = saved.messages;
+        const when = new Date(saved.time).toLocaleString("ko-KR");
+        console.log(c.green(`지난 대화를 이어갑니다 — ${when} · ${saved.model} · 메시지 ${saved.messages.length}개 복원`));
+        console.log(c.dim("(새로 시작하려면 /reset)"));
+      } catch {
+        console.log(c.yellow("이어갈 지난 대화가 없습니다."));
+      }
+      continue;
+    }
     if (low === "/config") { printIntro(cfg); console.log(c.dim(`config.json: ${configPath()}`)); continue; }
     if (low.startsWith("/workspace") || low.startsWith("/cd")) {
       const arg = user.split(/\s+/).slice(1).join(" ").trim();
@@ -821,26 +1089,14 @@ export async function main(argv = []) {
           continue;
         }
         console.log(c.dim(`(스킬 '/${name}' 실행)`));
-        rule();
-        try {
-          await loop.run(renderSkill(skills[name], argStr));
-        } catch (e) {
-          console.log(c.red(`실행 오류: ${e?.message || e}`));
-        }
-        rule();
+        await runTurn(renderSkill(skills[name], argStr));
       } else {
         console.log(c.yellow(`알 수 없는 명령/스킬: /${name} — ${c.cyan("/help")}, ${c.cyan("/skills")} 참고`));
       }
       continue;
     }
 
-    rule();
-    try {
-      await loop.run(user);
-    } catch (e) {
-      console.log(c.red(`실행 오류: ${e?.message || e}`));
-    }
-    rule();
+    await runTurn(user);
   }
 
   rl.close();

package/src/config.js

@@ -4,7 +4,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
-export const PROVIDERS = ["openai", "anthropic", "openrouter", "mock"];
+export const PROVIDERS = ["openai", "anthropic", "openrouter", "ollama", "mock"];
 
 export const SUGGESTED_MODELS = {
   openai: ["gpt-4o-mini", "gpt-4.1-mini", "gpt-4.1"],
@@ -15,6 +15,8 @@ export const SUGGESTED_MODELS = {
     "anthropic/claude-3.7-sonnet",
     "google/gemini-2.0-flash-001",
   ],
+  // 로컬/폐쇄망(Ollama). 도구 호출(tools) 지원 모델 권장. exaone 은 한국어 특화(LG).
+  ollama: ["qwen2.5:7b", "llama3.1:8b", "exaone3.5:7.8b"],
   mock: ["mock-agent"],
 };
 
@@ -83,6 +85,7 @@ export class Config {
 
   isReady() {
     if (this.provider === "mock") return true;
+    if (this.provider === "ollama") return true; // 로컬 LLM — API 키 불필요
     return Boolean(this.resolvedKey());
   }
 

package/src/llm.js

@@ -11,6 +11,8 @@ const ENDPOINTS = {
   openai: "https://api.openai.com/v1/chat/completions",
   openrouter: "https://openrouter.ai/api/v1/chat/completions",
   anthropic: "https://api.anthropic.com/v1/messages",
+  // Ollama(로컬/폐쇄망)는 OpenAI 호환 API 를 제공한다. OLLAMA_HOST 로 호스트 변경 가능.
+  ollama: `${(process.env.OLLAMA_HOST || "http://localhost:11434").replace(/\/$/, "")}/v1/chat/completions`,
 };
 
 export class LLMClient {
@@ -55,7 +57,7 @@ export class LLMClient {
       res = await fetch(url, { method: "POST", headers, body: json, signal: ctrl.signal });
     } catch (e) {
       clearTimeout(timer);
-      throw new LLMError(`네트워크 오류: ${e.message}`);
+      throw new LLMError(this._netErrorMessage(e));
     }
     if (!res.ok) {
       clearTimeout(timer);
@@ -65,6 +67,14 @@ export class LLMClient {
     return { res, started, timer, bodyBytes: Buffer.byteLength(json, "utf8") };
   }
 
+  _netErrorMessage(e) {
+    let msg = `네트워크 오류: ${e.message}`;
+    if (this.provider === "ollama") {
+      msg += "\n  ↳ Ollama 가 실행 중인지 확인하세요: `ollama serve` (모델 설치: `ollama pull qwen2.5:7b`)";
+    }
+    return msg;
+  }
+
   async _post(url, headers, body) {
     const json = JSON.stringify(body);
     const ctrl = new AbortController();
@@ -74,7 +84,7 @@ export class LLMClient {
     try {
       res = await fetch(url, { method: "POST", headers, body: json, signal: ctrl.signal });
     } catch (e) {
-      throw new LLMError(`네트워크 오류: ${e.message}`);
+      throw new LLMError(this._netErrorMessage(e));
     } finally {
       clearTimeout(timer);
     }

package/src/loop.js

@@ -62,6 +62,24 @@ function summarizeMessages(messages) {
   return { rows, totalChars, estTokens: estimateTokens(messages.map((m) => (m.content || "") + JSON.stringify(m.tool_calls || "")).join("")) };
 }
 
+// 서브에이전트 위임 도구 — 최상위(depth 0)에서만 노출해 중첩 위임을 막는다.
+const SPAWN_AGENT_SCHEMA = {
+  type: "function",
+  function: {
+    name: "spawn_agent",
+    description:
+      "독립적인 하위 작업을 서브에이전트에게 위임한다. 서브에이전트는 같은 도구(읽기/검색/수정)로 작업하고 결과 텍스트를 돌려준다. 크고 스스로 완결되는 작업 덩어리에만 사용하고, 간단한 일은 직접 도구를 호출하라.",
+    parameters: {
+      type: "object",
+      properties: {
+        task: { type: "string", description: "위임할 작업 지시(구체적으로)" },
+        context: { type: "string", description: "작업에 필요한 배경 정보(선택)" },
+      },
+      required: ["task"],
+    },
+  },
+};
+
 const RULES_FILENAMES = ["AGENT.md", "AGENTS.md", "CLAUDE.md", "rules.md", "RULES.md"];
 
 function findRules(workspace) {
@@ -79,7 +97,7 @@ function findRules(workspace) {
 }
 
 export class AgentLoop {
-  constructor({ config, client, toolbox, onEvent, approvalCallback, session = null, onToken = null }) {
+  constructor({ config, client, toolbox, onEvent, approvalCallback, session = null, onToken = null, depth = 0 }) {
     this.config = config;
     this.client = client;
     this.toolbox = toolbox;
@@ -87,7 +105,9 @@ export class AgentLoop {
     this.approvalCallback = approvalCallback;
     this.session = session;
     this.onToken = onToken; // 스트리밍 토큰 콜백(있으면 실시간 출력)
+    this.depth = depth; // 0=최상위, 1=서브에이전트(중첩 위임 불가)
     this.messages = [];
+    this.usage = { input: 0, output: 0, total: 0, calls: 0 }; // 세션 누적 토큰(/status, /cost)
   }
 
   _emit(step, title = "", detail = "", data = {}) {
@@ -99,28 +119,45 @@ export class AgentLoop {
   _systemPrompt() {
     const ws = this.toolbox.workspace;
     const { name: rulesName, text: rulesText } = findRules(ws);
-    let listing;
+    // 폴더 '전체 목록'을 박아넣지 않는다(낡은 정보·토큰 낭비 방지) — 최상위 이름만 참고로 주고
+    // 최신 상태는 도구(list_dir/search_files)로 확인하게 한다. (OpenCode/Claude Code 방식)
+    let topLevel = "";
     try {
-      listing = this.toolbox.listDir(".").output;
+      const names = fs.readdirSync(ws).filter((n) => !n.startsWith(".")).sort();
+      topLevel = names.slice(0, 15).join(", ") + (names.length > 15 ? ` … (총 ${names.length}개)` : "");
     } catch {
-      listing = "(폴더를 읽을 수 없음)";
+      topLevel = "(읽을 수 없음)";
     }
-    const toolNames = ["list_dir", "read_file", "write_file"].concat(
-      this.config.allow_shell ? ["run_shell"] : []
-    );
-    const toolsDesc = toolNames.map((n) => `${n}(${TOOL_LABELS[n]})`).join(", ");
+    const pluginNames = (this.toolbox.plugins || []).map((p) => p.name).join(", ");
+    const now = new Date();
+    const day = ["일", "월", "화", "수", "목", "금", "토"][now.getDay()];
 
     const parts = [
-      "당신은 'CDSA Harness' 안에서 동작하는 소형 코딩 에이전트입니다.",
-      "당신은 직접 파일을 만질 수 없습니다. 반드시 제공된 도구로만 작업 폴더를 다룹니다.",
-      `사용 가능한 도구: ${toolsDesc}.`,
-      "파일을 수정할 때는 write_file 에 '파일 전체 내용'을 담아 호출하세요(부분 패치 아님).",
-      "추측하지 말고, 필요하면 먼저 read_file/list_dir 로 사실을 확인하세요.",
-      "작업이 끝나면 도구를 더 호출하지 말고 한국어로 결과를 요약하세요.",
-      `\n[작업 폴더 루트]\n${ws}`,
-      `\n[현재 폴더 내용]\n${listing}`,
-    ];
-    if (rulesText) parts.push(`\n[규칙 파일 ${rulesName}]\n${rulesText.trim()}`);
+      "# 정체성",
+      "당신은 CDSA Harness(made by CDSA) 안에서 동작하는 코딩·업무 에이전트입니다.",
+      "파일시스템에 직접 접근할 수 없으며, 제공된 도구 호출로만 작업 폴더를 다룹니다.",
+      "",
+      "# 환경",
+      `- 작업 폴더(루트): ${ws}`,
+      `- 최상위 항목(참고용 스냅샷): ${topLevel || "(빈 폴더)"}`,
+      `- 플랫폼: ${process.platform} · Node ${process.versions.node} · 오늘: ${now.toISOString().slice(0, 10)}(${day})`,
+      "- 모든 도구는 작업 폴더 밖으로 나갈 수 없습니다(sandbox). 파일 수정·셸 실행은 사용자 승인 후에만 적용됩니다.",
+      "",
+      "# 도구 사용 원칙",
+      "- 추측 금지: 파일 위치·내용이 불확실하면 먼저 search_files / list_dir / read_file 로 사실을 확인한다.",
+      "- 기존 파일의 일부 수정은 edit_file(old_text 는 파일에서 유일해야 함), 새 파일·전체 교체만 write_file 을 쓴다.",
+      "- 도구가 오류를 돌려주면 같은 호출을 반복하지 말고, 오류 메시지를 읽고 접근을 바꾼다.",
+      "- 사용자가 승인을 거부하면 그 의사를 존중하고 대안을 제시한다.",
+      this.depth === 0
+        ? "- 크고 독립적으로 나눌 수 있는 작업은 spawn_agent 로 서브에이전트에 위임할 수 있다(간단한 일엔 쓰지 말 것)."
+        : "- 당신은 상위 에이전트가 위임한 하위 작업을 수행하는 서브에이전트다. 주어진 작업만 완수하고, 결과를 명확한 텍스트로 보고하라.",
+      pluginNames ? `- 추가 도구: ${pluginNames}` : null,
+      "",
+      "# 응답 스타일",
+      "- 한국어로, 간결하게. 불필요한 서론·사과 없이 핵심부터.",
+      "- 작업이 끝나면 도구를 더 호출하지 말고 무엇을 했는지 요약한다.",
+    ].filter((p) => p !== null);
+    if (rulesText) parts.push("", `# 프로젝트 규칙 (${rulesName})`, rulesText.trim());
     return parts.join("\n");
   }
 
@@ -129,6 +166,16 @@ export class AgentLoop {
     this.messages = [{ role: "system", content: this.systemPromptText }];
   }
 
+  // 매 턴 시작 시 시스템 프롬프트를 신선하게 재구성한다(대화는 유지, 환경·스냅샷만 갱신).
+  refreshSystemPrompt() {
+    this.systemPromptText = this._systemPrompt();
+    if (this.messages.length && this.messages[0].role === "system") {
+      this.messages[0] = { role: "system", content: this.systemPromptText };
+    } else {
+      this.messages.unshift({ role: "system", content: this.systemPromptText });
+    }
+  }
+
   // /context 명령용: 현재 대화 컨텍스트 요약.
   contextSummary() {
     return { ...summarizeMessages(this.messages), systemPrompt: this.systemPromptText };
@@ -136,6 +183,7 @@ export class AgentLoop {
 
   async run(userInput) {
     if (this.messages.length === 0) this.reset();
+    else this.refreshSystemPrompt(); // 환경·규칙·스냅샷을 매 턴 최신으로 (대화 이력은 유지)
 
     this._emit(Step.USER_INPUT, "사용자 입력", userInput);
     this.messages.push({ role: "user", content: userInput });
@@ -143,10 +191,11 @@ export class AgentLoop {
     this._emit(
       Step.BUILD_CONTEXT,
       "컨텍스트 구성",
-      "규칙 파일 + 작업 폴더 내용을 시스템 프롬프트로 묶어 모델에 전달합니다."
+      "정체성·환경·도구원칙·프로젝트규칙(AGENT.md)을 시스템 프롬프트로 묶어 매 턴 신선하게 전달합니다."
     );
 
     const tools = toolSchemas(this.config.allow_shell, this.toolbox.plugins);
+    if (this.depth === 0) tools.push(SPAWN_AGENT_SCHEMA); // 서브에이전트는 재위임 불가
     const toolNames = tools.map((t) => t.function.name);
     let finalText = "";
 
@@ -183,6 +232,13 @@ export class AgentLoop {
 
       // ③ 모델의 원본 판단 + 실측 메타(응답시간/토큰/요청크기)를 드러낸다.
       // streamed=true 면 텍스트는 이미 실시간 출력됨 → UI 는 메타만 덧붙인다.
+      this.usage.calls += 1; // 모든 LLM 호출 횟수(usage 미제공 provider 포함)
+      if (reply.usage) {
+        this.usage.input += reply.usage.input || 0;
+        this.usage.output += reply.usage.output || 0;
+        this.usage.total += reply.usage.total || 0;
+      }
+
       this._emit(Step.MODEL_REPLY, "모델 응답", reply.content || "(텍스트 없음)", {
         toolCalls: reply.toolCalls.map((tc) => ({ name: tc.name, args: tc.args })),
         usage: reply.usage || null,
@@ -230,7 +286,46 @@ export class AgentLoop {
     return finalText;
   }
 
+  // 서브에이전트: 하위 AgentLoop 를 만들어 위임 작업을 수행시키고 결과 텍스트를 회수한다.
+  async _runSubAgent(tc) {
+    const task = (tc.args.task || "").trim();
+    if (!task) return "spawn_agent 오류: task 가 비어 있습니다.";
+    if (this.depth > 0) return "spawn_agent 오류: 서브에이전트는 다시 위임할 수 없습니다.";
+    this._emit(Step.TOOL_RUN, "도구 실행: 서브에이전트 위임", task.slice(0, 300));
+
+    const child = new AgentLoop({
+      config: this.config,
+      client: this.client,
+      toolbox: this.toolbox, // 같은 sandbox·같은 승인 정책 공유
+      session: this.session,
+      approvalCallback: this.approvalCallback,
+      onToken: null, // 하위 스트리밍은 화면 소음 — 패널로만 표시
+      onEvent: (ev) =>
+        this.onEvent({ ...ev, title: `┆ ${ev.title}`, data: { ...(ev.data || {}), sub: 1 } }),
+      depth: this.depth + 1,
+    });
+    child.reset();
+    const prompt = (tc.args.context ? `[배경]\n${tc.args.context}\n\n` : "") + `[위임된 작업]\n${task}`;
+
+    let result = "";
+    try {
+      result = await child.run(prompt);
+    } catch (e) {
+      result = `서브에이전트 실행 오류: ${e?.message || e}`;
+    }
+    // 하위 토큰 사용량을 상위(/status)에 합산
+    this.usage.input += child.usage.input;
+    this.usage.output += child.usage.output;
+    this.usage.total += child.usage.total;
+    this.usage.calls += child.usage.calls;
+
+    const out = (result || "").trim() || "(서브에이전트가 결과 텍스트를 반환하지 않았습니다)";
+    this._emit(Step.TOOL_RESULT, "결과 반영: 서브에이전트", out.slice(0, 4000));
+    return out;
+  }
+
   async _handleToolCall(tc) {
+    if (tc.name === "spawn_agent") return this._runSubAgent(tc);
     const label = this.toolbox.label ? this.toolbox.label(tc.name) : TOOL_LABELS[tc.name] || tc.name;
     const needsApproval = this.toolbox.isMutating(tc.name);
 
@@ -271,6 +366,10 @@ export class AgentLoop {
       const { path: p, diff } = this.toolbox.previewWrite(tc.args.path || "", tc.args.content || "");
       return { toolName: "write_file", toolLabel: TOOL_LABELS.write_file, args: tc.args, path: p, diff };
     }
+    if (tc.name === "edit_file") {
+      const { path: p, diff } = this.toolbox.previewEdit(tc.args.path || "", tc.args.old_text || "", tc.args.new_text ?? "");
+      return { toolName: "edit_file", toolLabel: TOOL_LABELS.edit_file, args: tc.args, path: p, diff };
+    }
     if (tc.name === "run_shell") {
       return {
         toolName: "run_shell",

package/src/tools.js

@@ -7,12 +7,15 @@ import path from "node:path";
 export const TOOL_LABELS = {
   list_dir: "폴더 보기",
   read_file: "파일 읽기",
-  write_file: "파일 수정",
+  write_file: "파일 쓰기",
+  edit_file: "부분 수정",
+  search_files: "파일 검색",
   run_shell: "셸 실행",
+  spawn_agent: "서브에이전트",
 };
 
 // 사용자 승인이 필요한(환경을 바꾸는) 도구
-export const MUTATING_TOOLS = new Set(["write_file", "run_shell"]);
+export const MUTATING_TOOLS = new Set(["write_file", "edit_file", "run_shell"]);
 
 export class ToolError extends Error {}
 
@@ -132,10 +135,32 @@ export class Toolbox {
     return { path: this.rel(target), diff };
   }
 
+  // /undo 용: 마지막 파일 변경 1건을 기억해 되돌릴 수 있게 한다(단순 프리미티브).
+  _backup(target) {
+    this.lastChange = {
+      target,
+      rel: this.rel(target),
+      old: fs.existsSync(target) ? fs.readFileSync(target, "utf8") : null, // null = 새 파일이었음
+    };
+  }
+
+  undoLast() {
+    if (!this.lastChange) throw new ToolError("되돌릴 파일 변경이 없습니다.");
+    const { target, rel, old } = this.lastChange;
+    this.lastChange = null;
+    if (old === null) {
+      fs.rmSync(target, { force: true });
+      return { ok: true, output: `${rel} 생성을 취소했습니다(파일 삭제).` };
+    }
+    fs.writeFileSync(target, old, "utf8");
+    return { ok: true, output: `${rel} 을 마지막 변경 이전 상태로 되돌렸습니다.` };
+  }
+
   writeFile(rel, content) {
     const target = this._resolve(rel);
     fs.mkdirSync(path.dirname(target), { recursive: true });
     const existed = fs.existsSync(target);
+    this._backup(target);
     fs.writeFileSync(target, content || "", "utf8");
     const verb = existed ? "수정" : "생성";
     return {
@@ -145,6 +170,91 @@ export class Toolbox {
     };
   }
 
+  // 부분 수정: old_text 를 딱 한 번 찾아 new_text 로 바꾼다(전체 덮어쓰기 불필요).
+  _computeEdit(rel, oldText, newText) {
+    const target = this._resolve(rel);
+    if (!fs.existsSync(target) || !fs.statSync(target).isFile()) {
+      throw new ToolError(`파일이 없습니다: ${rel}`);
+    }
+    if (!oldText) throw new ToolError("old_text 가 비어 있습니다.");
+    const cur = fs.readFileSync(target, "utf8");
+    const count = cur.split(oldText).length - 1;
+    if (count === 0) throw new ToolError("old_text 를 파일에서 찾지 못했습니다. 파일을 다시 read_file 로 확인하세요.");
+    if (count > 1) throw new ToolError(`old_text 가 ${count}번 일치합니다 — 주변 문맥을 포함해 더 길게 지정하세요.`);
+    return { target, cur, next: cur.replace(oldText, newText ?? "") };
+  }
+
+  previewEdit(rel, oldText, newText) {
+    try {
+      const { target, cur, next } = this._computeEdit(rel, oldText, newText);
+      return { path: this.rel(target), diff: diffLines(cur, next).filter((l) => !l.startsWith(" ")).join("\n") || "(변화 없음)" };
+    } catch (e) {
+      return { path: rel, diff: `(미리보기 불가: ${e.message})` };
+    }
+  }
+
+  editFile(rel, oldText, newText) {
+    const { target, next } = this._computeEdit(rel, oldText, newText);
+    this._backup(target);
+    fs.writeFileSync(target, next, "utf8");
+    return { ok: true, output: `${this.rel(target)} 부분 수정 완료 (old ${oldText.length}자 → new ${(newText ?? "").length}자).` };
+  }
+
+  // 파일명 + 내용 검색(재귀). node_modules/.git 등 노이즈 제외, 대소문자 무시.
+  searchFiles(query, sub = ".") {
+    if (!query || !query.trim()) throw new ToolError("검색어가 비어 있습니다.");
+    const q = query.toLowerCase();
+    const rootDir = this._resolve(sub);
+    const SKIP = new Set(["node_modules", ".git", "dist", "build", "__pycache__", ".venv"]);
+    const nameHits = [];
+    const contentHits = [];
+    let scanned = 0;
+    const walk = (dir) => {
+      let entries = [];
+      try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const e of entries) {
+        if (scanned > 2000 || contentHits.length >= 40) return;
+        const full = path.join(dir, e.name);
+        if (e.isDirectory()) {
+          if (!SKIP.has(e.name) && !e.name.startsWith(".")) walk(full);
+          continue;
+        }
+        scanned++;
+        const rel = this.rel(full);
+        if (e.name.toLowerCase().includes(q)) nameHits.push(rel);
+        let st;
+        try {
+          st = fs.statSync(full);
+        } catch {
+          continue;
+        }
+        if (st.size > 512 * 1024) continue; // 큰 파일 스킵
+        let text;
+        try {
+          text = fs.readFileSync(full, "utf8");
+        } catch {
+          continue;
+        }
+        if (text.includes("")) continue; // 바이너리 스킵
+        const lines = text.split("\n");
+        for (let i = 0; i < lines.length && contentHits.length < 40; i++) {
+          if (lines[i].toLowerCase().includes(q)) {
+            contentHits.push(`${rel}:${i + 1}  ${lines[i].trim().slice(0, 120)}`);
+          }
+        }
+      }
+    };
+    walk(rootDir);
+    const parts = [];
+    if (nameHits.length) parts.push(`[파일명 일치 ${nameHits.length}건]\n` + nameHits.slice(0, 20).join("\n"));
+    if (contentHits.length) parts.push(`[내용 일치]\n` + contentHits.join("\n"));
+    return { ok: true, output: parts.join("\n\n") || `'${query}' 검색 결과가 없습니다.` };
+  }
+
   runShell(command) {
     if (!this.allowShell) {
       throw new ToolError("셸 실행이 설정에서 비활성화되어 있습니다(allow_shell=false).");
@@ -172,6 +282,8 @@ export class Toolbox {
     if (name === "list_dir") return this.listDir(args.path || ".");
     if (name === "read_file") return this.readFile(args.path || "");
     if (name === "write_file") return this.writeFile(args.path || "", args.content || "");
+    if (name === "edit_file") return this.editFile(args.path || "", args.old_text || "", args.new_text ?? "");
+    if (name === "search_files") return this.searchFiles(args.query || "", args.path || ".");
     if (name === "run_shell") return this.runShell(args.command || "");
     const plugin = this._pluginMap.get(name);
     if (plugin) {
@@ -221,7 +333,7 @@ export function toolSchemas(allowShell = false, plugins = []) {
       function: {
         name: "write_file",
         description:
-          "작업 폴더 안의 파일을 새 내용으로 만들거나 덮어쓴다. 전체 파일 내용을 content 로 전달. 사용자 승인 후 적용된다.",
+          "새 파일을 만들거나 파일 전체를 덮어쓴다. 기존 파일의 일부만 고칠 땐 write_file 대신 edit_file 을 써라. 사용자 승인 후 적용된다.",
         parameters: {
           type: "object",
           properties: {
@@ -232,6 +344,38 @@ export function toolSchemas(allowShell = false, plugins = []) {
         },
       },
     },
+    {
+      type: "function",
+      function: {
+        name: "edit_file",
+        description:
+          "기존 파일의 일부만 수정한다(권장). old_text 는 파일 안에서 정확히 한 번만 일치해야 하며 new_text 로 치환된다. 사용자 승인 후 적용된다.",
+        parameters: {
+          type: "object",
+          properties: {
+            path: { type: "string", description: "수정할 파일의 상대 경로" },
+            old_text: { type: "string", description: "바꿀 기존 텍스트(문맥 포함, 파일에서 유일해야 함)" },
+            new_text: { type: "string", description: "새 텍스트" },
+          },
+          required: ["path", "old_text", "new_text"],
+        },
+      },
+    },
+    {
+      type: "function",
+      function: {
+        name: "search_files",
+        description: "작업 폴더에서 파일명·파일내용을 재귀 검색한다(대소문자 무시). 어떤 파일에 뭐가 있는지 찾을 때 사용.",
+        parameters: {
+          type: "object",
+          properties: {
+            query: { type: "string", description: "검색어" },
+            path: { type: "string", description: "검색 시작 폴더(기본 '.')" },
+          },
+          required: ["query"],
+        },
+      },
+    },
   ];
   if (allowShell) {
     schemas.push({

package/src/ui.js

@@ -110,6 +110,57 @@ export function panel(lines, { title = "", color = "cyan" } = {}) {
   return [head, ...mid, bottom].join("\n");
 }
 
+// 모델 응답의 마크다운을 터미널 ANSI 로 렌더한다(OpenCode 류 체감 개선).
+// 지원: #제목 / **굵게** / *기울임* / `코드` / ```펜스``` / -·* 목록 / > 인용 / 표(|) / 구분선
+export function renderMarkdown(text) {
+  const out = [];
+  let inFence = false;
+  for (const raw of String(text ?? "").split("\n")) {
+    // 코드 펜스
+    const fence = /^\s*```(\w*)/.exec(raw);
+    if (fence) {
+      inFence = !inFence;
+      out.push(c.grey("  ┄┄┄" + (inFence && fence[1] ? " " + fence[1] + " " : "") + "┄┄┄"));
+      continue;
+    }
+    if (inFence) {
+      out.push("  " + c.yellow(raw));
+      continue;
+    }
+    let line = raw;
+    // 구분선
+    if (/^\s*(-{3,}|\*{3,}|_{3,})\s*$/.test(line)) {
+      out.push(c.grey("─".repeat(30)));
+      continue;
+    }
+    // 제목
+    const h = /^(#{1,4})\s+(.*)$/.exec(line);
+    if (h) {
+      out.push(c.bold(c.cyan(h[2])));
+      continue;
+    }
+    // 인용
+    line = line.replace(/^(\s*)>\s?/, (_, sp) => sp + c.grey("│ "));
+    // 목록 글머리
+    line = line.replace(/^(\s*)[-*]\s+/, (_, sp) => sp + c.cyan("• "));
+    // 표: | 를 은은한 세로선으로
+    if (/^\s*\|.*\|\s*$/.test(raw)) {
+      if (/^\s*\|[\s:|-]+\|\s*$/.test(raw)) {
+        out.push(c.grey(raw.replace(/[|:-]/g, (m) => (m === "|" ? "┼" : "─")).trim()));
+        continue;
+      }
+      line = line.replace(/\|/g, c.grey("│"));
+    }
+    // 인라인: `코드` → 노랑, **굵게**, *기울임*
+    line = line
+      .replace(/`([^`]+)`/g, (_, s) => c.yellow(s))
+      .replace(/\*\*([^*]+)\*\*/g, (_, s) => c.bold(s))
+      .replace(/(^|\s)\*([^*\s][^*]*)\*(?=\s|$|[.,!?)])/g, (_, pre, s) => pre + c.italic(s));
+    out.push(line);
+  }
+  return out;
+}
+
 // diff 문자열을 색으로 렌더 (+초록 / -빨강 / 그외 흐림)
 export function renderDiff(diff) {
   return diff.split("\n").map((line) => {