deel-local-cli 1.0.2 → 1.1.0

package/src/tools/index.js

@@ -5,20 +5,32 @@ import { dirname } from 'node:path';
 import { execFile } from 'node:child_process';
 import { globToRegex, walk, readText, readTextFull, SKIP_DIRS, 내부살림 } from './fsutil.js';
 import { encode, label as encLabel, decode as decodeBytes, consoleCodepage, looksBinary } from './encoding.js';
-import { checkCommand, checkPaths } from '../safety/guard.js';
+import { checkCommand, checkPaths, isMutating } from '../safety/guard.js';
+import { 띄우기, JOBS_TOOL } from './jobs.js';
 import { findMatch, applySpans, reindent, TIER_LABELS } from './edit-match.js';
 import { loadSkill } from '../skills/discover.js';
 import { WEB_FETCH_TOOL } from './webfetch.js';
 import { TODO_TOOL } from './todo.js';
+import { TASK_TOOL } from './task.js';
+import { OUTLINE_TOOL } from './outline.js';
+import { VERIFY_TOOL } from './verify.js';
 import { allow as allowedIn } from '../agent/modes.js';
 import { 도구정의, 이름풀기 } from '../backend/mcp.js';
 import { isExcelPath, readExcel, toText as excelText, summarize as excelSummary } from './excel.js';
 import { diffLines } from '../ui/diff.js';
+import { 읽을줄수, 찾을개수, 찾을줄수, 설명길이 } from '../agent/budget.js';
 
-const MAX_READ_LINES = 2000;
+/*
+ * 한 번에 돌려줄 양은 **모델에 맞춰** 정한다 (agent/budget.js).
+ *
+ * 전에는 못 박혀 있었다 — Read 2,000줄, Glob 200개, Grep 250줄. 그 값이 맞는
+ * 모델은 하나도 없다. 8k 짜리에는 한 번으로 창을 넘기는 양이고, 655k 짜리에는
+ * 있는 자리의 1%도 안 쓰는 양이다. 같은 숫자가 한쪽에선 너무 크고 다른 쪽에선
+ * 너무 작으면, 숫자를 잘못 고른 게 아니라 고정한 것 자체가 틀린 것이다.
+ *
+ * ctx.모델컨텍스트 가 없으면(검사·일회성 호출) budget.js 가 알아서 기본값을 쓴다.
+ */
 const MAX_OUT = 30000;
-// Glob 이 한 번에 돌려줄 최대 개수. 넘으면 잘랐다고 말해 준다.
-const GLOB_MAX = 200;
 // Grep 이 열어 볼 파일 크기 상한. 이보다 크면 글 파일이라도 안 본다 —
 // 한 파일에서 몇십 초를 쓰면 그동안 화면이 멈춘 것처럼 보인다.
 const GREP_MAX_FILE = 2 * 1024 * 1024;
@@ -94,6 +106,70 @@ export function 파일현황(abs) {
   } catch { return { path: abs, missing: true }; }
 }
 
+// Bash 한 번에 이만큼까지만 떠 둔다. `rm` 에 파일 이름 백 개를 늘어놓는 일이
+// 없지는 않은데, 그때 백 벌을 뜨면 되돌리기 이력이 그 한 번으로 밀려난다.
+const 스냅샷상한 = 24;
+
+/**
+ * 명령줄에서 **떠 둘 만한** 낱말을 고른다.
+ *
+ * guard.js 의 경로낱말() 을 안 쓴다. 그쪽은 슬래시가 든 것만 경로로 본다 —
+ * 울타리를 지키는 쪽에서는 그게 맞다. 안 걸린 것을 막아 버리면 멀쩡한 명령이
+ * 막히기 때문이다. 그런데 `del 지울것.txt` 처럼 **슬래시 없는 파일 이름**이
+ * 실제로 제일 흔하고, 그것들이 통째로 빠졌다.
+ *
+ * 여기는 막는 자리가 아니라 **읽는** 자리라 반대로 잡는다. 넓게 훑고,
+ * 실제로 그 자리에 파일이 있을 때만 뜬다. 헛다리를 짚어도 손해가 없다 —
+ * 없는 파일은 그냥 넘어간다.
+ */
+function 뜰만한낱말(cmd) {
+  const out = [];
+  const re = /"([^"]*)"|'([^']*)'|[^\s|;&<>()]+/g;
+  let m;
+  while ((m = re.exec(String(cmd)))) {
+    let t = m[1] ?? m[2] ?? m[0];
+    if (!t) continue;
+    if (t.startsWith('-')) continue;                    // 옵션
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(t)) continue;   // 주소
+    t = t.replace(/^[<>]+/, '');
+    // 셸이 푸는 자리표·와일드카드는 여기서 못 편다. 억지로 풀면 엉뚱한
+    // 파일을 뜨게 되므로 그냥 넘긴다 — 대신 못 떴다는 사실이 결과에 남는다.
+    if (!t || /[$%*?]/.test(t)) continue;
+    out.push(t);
+  }
+  return out;
+}
+
+/**
+ * 파일을 바꾸는 Bash 명령이면, 손대기 전 내용을 떠 둔다.
+ *
+ * 여기가 없으면 `mv`·`rm` 으로 사라진 것을 /undo 가 못 살린다. Write·Edit 만
+ * 지키는 안전망은 절반짜리다 — 모델은 파일을 옮길 때 당연히 Bash 를 쓴다.
+ *
+ * **못 뜨는 것이 있다는 사실을 숨기지 않는다.** 셸이 푸는 와일드카드(`rm *.tmp`),
+ * 스크립트 안에서 지우는 것, 폴더 통째는 여기서 안 보인다. 그래서 결과에
+ * '이건 되돌릴 수 있다' 는 말을 붙이지 않고, 뜬 개수만 사실대로 넘긴다.
+ *
+ * @returns {string[]} 떠 둔 파일들의 보인 이름
+ */
+function 바꾸기전스냅샷(cmd, ctx) {
+  if (!isMutating(cmd)) return [];
+  const 뜬것 = [];
+  for (const t of 뜰만한낱말(cmd)) {
+    if (뜬것.length >= 스냅샷상한) break;
+    let abs;
+    // 범위 밖은 어차피 checkPaths 가 이미 막았다. 여기서 터지면 안 된다 —
+    // 뜨는 데 실패했다고 명령 자체를 막으면 안 되는 명령까지 막힌다.
+    try { abs = ctx.scope.resolve(t); } catch { continue; }
+    try {
+      if (!existsSync(abs) || statSync(abs).isDirectory()) continue;
+      ctx.history.snapshot(abs, 'Bash');
+      뜬것.push(ctx.scope.show(abs));
+    } catch { /* 못 뜨면 그냥 넘어간다. 명령은 돌아야 한다 */ }
+  }
+  return 뜬것;
+}
+
 /** 지금 파일이 몇 줄인가. 붙인 뒤 '얼마나 찼는지' 를 사실로 말해 주려고 센다. */
 function 줄수(abs, 인코딩) {
   try {
@@ -133,6 +209,226 @@ async function 엑셀읽기(abs, args, ctx) {
   };
 }
 
+
+/**
+ * 파일 하나를 쓴다 — Write 의 알맹이.
+ *
+ * 되돌리기 스냅샷을 **여기서** 뜬다. 여러 개를 쓸 때도 파일마다 한 번씩 뜨는
+ * 것이 중요하다. 한 덩이로 뜨면 `/undo` 가 전부-아니면-전무가 되어, 넷 중
+ * 하나만 잘못 만들었을 때 나머지 셋까지 날려야 한다.
+ */
+function 한파일쓰기(args, ctx) {
+  const abs = ctx.scope.resolve(args.file_path);
+    if (typeof args.content !== 'string') return { error: 'content 가 문자열이 아닙니다' };
+    // 읽기만 막고 쓰기를 열어 두면 남의 도구 살림을 덮어쓸 수 있다.
+    // 제 설정(.deel/config.json)을 덮어쓰면 연결이 통째로 날아간다.
+    const 못쓰는이유 = 내부살림(abs);
+    if (못쓰는이유) return { error: 못쓰는이유 };
+    // 엑셀 파일을 통째로 덮어쓰면 xlsx 가 아니라 그냥 글 파일이 된다.
+    // 열리지도 않는 파일이 되고, 원본은 이미 없다. 아예 막는다.
+    if (isExcelPath(abs)) return { error: 엑셀은못고침(args.file_path) };
+    // 엑셀만 막아서는 모자란다. hwp·pdf·png·zip 도 똑같이 그 순간 끝난다.
+    // 게다가 이런 파일은 되돌리기가 내용을 떠 놓지 못하는 종류라 되살릴 길이 없다.
+    // 확장자로 고르지 않고 실제 내용으로 본다 — 사내 파일은 확장자가 제각각이다.
+    const 바이너리막기 = 바이너리인가(abs);
+    if (바이너리막기) return { error: 바이너리막기 };
+    ctx.history.snapshot(abs, 'Write');
+    const existed = existsSync(abs);
+    // 덮어쓰기 전 내용. 바뀐 자리를 보여주려면 지금 떠 놔야 한다.
+    // 읽다 터지는 파일(바이너리 등)이면 그냥 없던 셈 친다 — 쓰는 것 자체는 막지 않는다.
+    let 이전 = null;
+    if (existed) { try { 이전 = readTextFull(abs).text; } catch { 이전 = null; } }
+    mkdirSync(dirname(abs), { recursive: true });
+
+    // 원래 있던 파일이면 그 파일이 쓰던 인코딩으로 되돌려 쓴다.
+    // 새 파일이면 UTF-8 이다 — 요즘 만드는 파일까지 옛 인코딩으로 둘 이유가 없다.
+    const 원래 = existed ? (ctx.enc?.get(abs) ?? 'utf-8') : 'utf-8';
+    const 만든것 = encode(args.content, 원래);
+    if (만든것.lost.length) {
+      return {
+        error: `이 파일은 ${encLabel(원래)} 로 되어 있는데, 그 인코딩에 없는 글자가 있습니다: `
+             + `${만든것.lost.slice(0, 8).join(' ')}\n`
+             + `  그대로 쓰면 그 글자들이 뭉개집니다. 해당 글자를 빼거나, 파일을 UTF-8 로 바꿔도 되는지 사용자에게 물어보세요.`,
+      };
+    }
+    writeFileSync(abs, 만든것.buf);
+    ctx.seen.add(abs);
+    const n = args.content.split('\n').length;
+    const 표기 = 원래 !== 'utf-8' ? ` · ${encLabel(원래)}` : '';
+    return {
+      content: `${existed ? '덮어씀' : '새로 만듦'}: ${ctx.scope.show(abs)} (${n}줄${표기})`,
+      summary: `${n}줄${표기}`,
+      changed: abs,
+      diff: 바뀐자리(이전, args.content),
+    };
+}
+
+/**
+ * 여러 파일을 한 번에.
+ *
+ * 하나가 실패해도 나머지는 간다. 첫 실패에서 통째로 멈추면 모델은 무엇이 되고
+ * 무엇이 안 됐는지 모른 채 여덟 개를 처음부터 다시 보낸다 — 왕복을 줄이려던
+ * 것이 오히려 늘어난다. 그래서 **한 줄씩 다 적어** 돌려준다.
+ */
+function 여러파일쓰기(목록, ctx) {
+  const 결과 = [];
+  for (const x of 목록) {
+    if (typeof x.file_path !== 'string' || !x.file_path) {
+      결과.push({ path: null, ok: false, error: 'file_path 가 없습니다' });
+      continue;
+    }
+    let r;
+    try { r = 한파일쓰기(x, ctx); }
+    catch (err) { r = { error: String(err?.message ?? err) }; }
+    결과.push(r.error
+      ? { path: x.file_path, 보인이름: x.file_path, ok: false, error: r.error }
+      : {
+        path: r.changed,
+        보인이름: ctx.scope.show(r.changed),
+        ok: true,
+        lines: String(x.content ?? '').split('\n').length,
+        diff: r.diff,
+      });
+  }
+
+  const 된것 = 결과.filter((r) => r.ok);
+  const 안된것 = 결과.filter((r) => !r.ok);
+  const 줄들 = 결과.map((r) => (r.ok
+    ? `  ✓ ${r.보인이름} (${r.lines}줄)`
+    : `  ✗ ${r.보인이름} — ${String(r.error).split('\n')[0]}`));
+
+  return {
+    content: `${된것.length}개 만들었습니다${안된것.length ? `, ${안된것.length}개 실패` : ''}.\n`
+      + 줄들.join('\n')
+      + (안된것.length ? '\n\n실패한 것만 다시 보내세요. 된 것은 다시 안 보내도 됩니다.' : ''),
+    summary: `${된것.length}개 · ${된것.reduce((a, r) => a + (r.lines ?? 0), 0)}줄`
+      + (안된것.length ? ` · ${안된것.length}개 실패` : ''),
+    // 화면과 루프가 파일별로 처리하도록 그대로 넘긴다. changed 는 안 넣는다 —
+    // 넣으면 그 한 개만 세어지고 나머지가 조용히 빠진다.
+    여럿: 결과,
+    error: 된것.length ? undefined : (안된것[0]?.error ?? '아무것도 못 만들었습니다'),
+  };
+}
+
+/**
+ * 한 군데를 고친다 — Edit 의 알맹이.
+ *
+ * 결과 모양을 바꾸면 안 된다. changed·diff·tier 를 보고 있는 자리가 셋이다:
+ * loop.js 의 잘린 인자 살려쓰기, repl.js 의 바뀐 자리 그리기, 되돌리기 스냅샷.
+ */
+function 한군데고치기(args, ctx) {
+  const abs = ctx.scope.resolve(args.file_path);
+  if (!existsSync(abs)) return { error: `파일이 없습니다: ${args.file_path}` };
+  const 못고치는이유 = 내부살림(abs);
+  if (못고치는이유) return { error: 못고치는이유 };
+  // 엑셀 파일은 Read 로 읽히긴 하지만 고칠 수 있는 물건이 아니다.
+  // '먼저 Read 로 읽어야 합니다' 라고만 하면 이미 읽은 쪽은 계속 헛돈다.
+  if (isExcelPath(abs)) return { error: 엑셀은못고침(args.file_path) };
+  if (!ctx.seen.has(abs)) return { error: `먼저 Read 로 읽어야 합니다: ${args.file_path}` };
+  if (args.old_string === args.new_string) return { error: 'old_string 과 new_string 이 같습니다' };
+
+  const 읽음 = readTextFull(abs);
+  const text = 읽음.text;
+  const m = findMatch(text, args.old_string, { replaceAll: !!args.replace_all });
+
+  if (!m.ok) {
+    if (m.reason === 'ambiguous') {
+      return { error: `${m.count}군데에서 발견됐습니다 (${TIER_LABELS[m.tier]}). 앞뒤로 더 넓게 잡아 하나만 가리키거나 replace_all 을 쓰세요.` };
+    }
+    const hint = m.near
+      ? `\n  파일의 ${m.near.line}번 줄이 가장 비슷합니다:\n    ${m.near.text.trim().slice(0, 120)}\n  이 줄을 그대로 옮겨 담아 다시 시도하세요.`
+      : '\n  Read 로 다시 읽어 실제 내용을 확인하세요.';
+    return { error: `찾지 못했습니다.${hint}` };
+  }
+
+  ctx.history.snapshot(abs, 'Edit');
+  const next = applySpans(text, m.spans, (matched) =>
+    m.tier === 'exact' ? args.new_string : reindent(args.new_string, matched, args.old_string));
+
+  // 읽은 그 인코딩으로 되돌려 쓴다.
+  const 만든것 = encode(next, 읽음.encoding);
+  if (만든것.lost.length) {
+    return {
+      error: `이 파일은 ${encLabel(읽음.encoding)} 로 되어 있는데, 그 인코딩에 없는 글자를 넣으려 합니다: `
+           + `${만든것.lost.slice(0, 8).join(' ')}\n`
+           + `  그대로 쓰면 그 글자들이 뭉개집니다. 다른 표현을 쓰거나, 파일을 UTF-8 로 바꿔도 되는지 사용자에게 물어보세요.`,
+    };
+  }
+  writeFileSync(abs, 만든것.buf);
+
+  const n = m.spans.length;
+  const how = m.tier === 'exact' ? '' : ` · ${TIER_LABELS[m.tier]}`;
+  const 표기 = 읽음.encoding !== 'utf-8' ? ` · ${encLabel(읽음.encoding)}` : '';
+  return {
+    content: `고침: ${ctx.scope.show(abs)} (${n}군데${how}${표기})`,
+    summary: `${n}군데${how}${표기}`,
+    changed: abs,
+    tier: m.tier,
+    diff: 바뀐자리(text, next),
+  };
+}
+
+/**
+ * 여러 군데를 한 번에.
+ *
+ * **차례로** 적용한다. 같은 파일을 두 번 고치는 경우가 흔한데, 한군데고치기()가
+ * 매번 디스크에서 다시 읽으므로 뒤엣것은 앞엣것이 반영된 글을 보고 찾는다.
+ * 한꺼번에 계산해서 붙이면 두 자리가 겹칠 때 조용히 어긋난다.
+ *
+ * 되돌리기는 그대로 한 턴이다. 스냅샷은 파일마다 그 턴의 첫 번만 뜨므로
+ * (undo.js snapshot 참고), 같은 파일을 여섯 군데 고쳐도 /undo 한 번이면
+ * 여섯 군데 다 손대기 전으로 돌아간다.
+ *
+ * 하나가 실패해도 나머지는 간다 — 여러파일쓰기() 와 같은 이유다.
+ */
+function 여러군데고치기(목록, ctx) {
+  const 결과 = [];
+  for (const x of 목록) {
+    if (typeof x.file_path !== 'string' || !x.file_path) {
+      결과.push({ path: null, 보인이름: '(경로 없음)', ok: false, error: 'file_path 가 없습니다' });
+      continue;
+    }
+    let r;
+    try { r = 한군데고치기(x, ctx); }
+    catch (err) { r = { error: String(err?.message ?? err) }; }
+    결과.push(r.error
+      ? { path: x.file_path, 보인이름: x.file_path, ok: false, error: r.error }
+      : {
+        path: r.changed,
+        보인이름: ctx.scope.show(r.changed),
+        ok: true,
+        군데: Number(String(r.summary).match(/^(\d+)/)?.[1] ?? 1),
+        tier: r.tier,
+        diff: r.diff,
+      });
+  }
+
+  const 된것 = 결과.filter((r) => r.ok);
+  const 안된것 = 결과.filter((r) => !r.ok);
+  const 줄들 = 결과.map((r) => (r.ok
+    ? `  ✓ ${r.보인이름} (${r.군데}군데)`
+    : `  ✗ ${r.보인이름} — ${String(r.error).split('\n')[0]}`));
+
+  // 어느 파일이 몇 번 고쳐졌는지. 같은 파일을 여러 번 고치는 것이 보통이라
+  // '3개 파일' 이 아니라 '2개 파일 · 5군데' 라고 말해야 사실에 맞는다.
+  const 파일수 = new Set(된것.map((r) => r.path)).size;
+  const 군데수 = 된것.reduce((a, r) => a + (r.군데 ?? 0), 0);
+
+  return {
+    content: `${군데수}군데 고쳤습니다${안된것.length ? `, ${안된것.length}군데 실패` : ''}.\n`
+      + 줄들.join('\n')
+      + (안된것.length
+        ? '\n\n실패한 것만 다시 보내세요. 된 것은 다시 안 보내도 됩니다.'
+          + ' 앞엣것이 이미 반영됐으니 **파일을 다시 Read 해서** 지금 내용을 보고 old_string 을 잡으세요.'
+        : ''),
+    summary: `${파일수}개 파일 · ${군데수}군데` + (안된것.length ? ` · ${안된것.length}개 실패` : ''),
+    // 화면과 루프가 자리별로 처리하도록 그대로 넘긴다. changed 는 안 넣는다 —
+    // 넣으면 그 한 개만 세어지고 나머지가 조용히 빠진다 (여러파일쓰기 와 같다).
+    여럿: 결과,
+    error: 된것.length ? undefined : (안된것[0]?.error ?? '아무것도 못 고쳤습니다'),
+  };
+}
+
 export const TOOLS = {
   Read: {
     schema: {
@@ -170,7 +466,8 @@ export const TOOLS = {
       const text = 읽음.text;
       const lines = text.split('\n');
       const start = Math.max(0, (args.offset ?? 1) - 1);
-      const count = Math.min(args.limit ?? MAX_READ_LINES, MAX_READ_LINES);
+      const 줄상한 = 읽을줄수(ctx.모델컨텍스트);
+      const count = Math.min(args.limit ?? 줄상한, 줄상한);
       const slice = lines.slice(start, start + count);
       const body = slice.map((l, i) => `${String(start + i + 1).padStart(6)}\t${l}`).join('\n');
       const more = lines.length > start + count ? `\n… 전체 ${lines.length}줄 중 ${start + count}줄까지` : '';
@@ -186,60 +483,45 @@ export const TOOLS = {
   Write: {
     schema: {
       name: 'Write',
-      description: '파일을 새로 쓰거나 통째로 덮어쓴다. 일부만 고칠 때는 Edit 을 쓴다.',
+      description: '파일을 새로 쓰거나 통째로 덮어쓴다. 일부만 고칠 때는 Edit 을 쓴다.'
+        + ' **여러 파일을 한 번에 만들 수 있다** — files 에 배열로 넣으면 된다.'
+        + ' 폴더 구조를 처음 잡을 때는 그렇게 해라. 한 개씩 부르면 파일 수만큼 모델을'
+        + ' 다시 불러야 해서, 여덟 개짜리 뼈대에 몇 분이 그냥 간다.',
       parameters: {
         type: 'object',
         properties: {
-          file_path: { type: 'string', description: '쓸 파일 경로' },
-          content: { type: 'string', description: '파일 전체 내용' },
+          file_path: { type: 'string', description: '쓸 파일 경로 (한 개일 때)' },
+          content: { type: 'string', description: '파일 전체 내용 (한 개일 때)' },
+          files: {
+            type: 'array',
+            description: '여러 개를 한 번에 만들 때. 이걸 쓰면 file_path·content 는 안 쓴다.',
+            items: {
+              type: 'object',
+              properties: {
+                file_path: { type: 'string', description: '쓸 파일 경로' },
+                content: { type: 'string', description: '파일 전체 내용' },
+              },
+              required: ['file_path', 'content'],
+            },
+          },
         },
-        required: ['file_path', 'content'],
+        required: [],
       },
     },
+    /*
+     * 갈래만 정한다. 알맹이는 아래 한파일쓰기() 에 있다.
+     *
+     * 한 개일 때의 결과 모양은 **한 글자도 안 바꾼다.** 그 모양을 보고 있는
+     * 자리가 여럿이다 — loop.js 의 잘린 것 살려쓰기, repl.js 의 바뀐 자리 그리기,
+     * 되돌리기 스냅샷. 여러 개는 그것과 다른 모양(여럿)으로 따로 돌려준다.
+     */
     run(args, ctx) {
-      const abs = ctx.scope.resolve(args.file_path);
-      if (typeof args.content !== 'string') return { error: 'content 가 문자열이 아닙니다' };
-      // 읽기만 막고 쓰기를 열어 두면 남의 도구 살림을 덮어쓸 수 있다.
-      // 제 설정(.deel/config.json)을 덮어쓰면 연결이 통째로 날아간다.
-      const 못쓰는이유 = 내부살림(abs);
-      if (못쓰는이유) return { error: 못쓰는이유 };
-      // 엑셀 파일을 통째로 덮어쓰면 xlsx 가 아니라 그냥 글 파일이 된다.
-      // 열리지도 않는 파일이 되고, 원본은 이미 없다. 아예 막는다.
-      if (isExcelPath(abs)) return { error: 엑셀은못고침(args.file_path) };
-      // 엑셀만 막아서는 모자란다. hwp·pdf·png·zip 도 똑같이 그 순간 끝난다.
-      // 게다가 이런 파일은 되돌리기가 내용을 떠 놓지 못하는 종류라 되살릴 길이 없다.
-      // 확장자로 고르지 않고 실제 내용으로 본다 — 사내 파일은 확장자가 제각각이다.
-      const 바이너리막기 = 바이너리인가(abs);
-      if (바이너리막기) return { error: 바이너리막기 };
-      ctx.history.snapshot(abs, 'Write');
-      const existed = existsSync(abs);
-      // 덮어쓰기 전 내용. 바뀐 자리를 보여주려면 지금 떠 놔야 한다.
-      // 읽다 터지는 파일(바이너리 등)이면 그냥 없던 셈 친다 — 쓰는 것 자체는 막지 않는다.
-      let 이전 = null;
-      if (existed) { try { 이전 = readTextFull(abs).text; } catch { 이전 = null; } }
-      mkdirSync(dirname(abs), { recursive: true });
-
-      // 원래 있던 파일이면 그 파일이 쓰던 인코딩으로 되돌려 쓴다.
-      // 새 파일이면 UTF-8 이다 — 요즘 만드는 파일까지 옛 인코딩으로 둘 이유가 없다.
-      const 원래 = existed ? (ctx.enc?.get(abs) ?? 'utf-8') : 'utf-8';
-      const 만든것 = encode(args.content, 원래);
-      if (만든것.lost.length) {
-        return {
-          error: `이 파일은 ${encLabel(원래)} 로 되어 있는데, 그 인코딩에 없는 글자가 있습니다: `
-               + `${만든것.lost.slice(0, 8).join(' ')}\n`
-               + `  그대로 쓰면 그 글자들이 뭉개집니다. 해당 글자를 빼거나, 파일을 UTF-8 로 바꿔도 되는지 사용자에게 물어보세요.`,
-        };
+      const 목록 = Array.isArray(args.files) ? args.files.filter((x) => x && typeof x === 'object') : [];
+      if (목록.length) return 여러파일쓰기(목록, ctx);
+      if (typeof args.file_path !== 'string' || !args.file_path) {
+        return { error: 'file_path 가 없습니다. 한 개면 file_path·content 를, 여러 개면 files 배열을 주세요.' };
       }
-      writeFileSync(abs, 만든것.buf);
-      ctx.seen.add(abs);
-      const n = args.content.split('\n').length;
-      const 표기 = 원래 !== 'utf-8' ? ` · ${encLabel(원래)}` : '';
-      return {
-        content: `${existed ? '덮어씀' : '새로 만듦'}: ${ctx.scope.show(abs)} (${n}줄${표기})`,
-        summary: `${n}줄${표기}`,
-        changed: abs,
-        diff: 바뀐자리(이전, args.content),
-      };
+      return 한파일쓰기(args, ctx);
     },
   },
 
@@ -313,68 +595,46 @@ export const TOOLS = {
   Edit: {
     schema: {
       name: 'Edit',
-      description: '파일에서 정확히 일치하는 문자열 하나를 바꾼다. 먼저 Read 로 읽어야 한다.',
+      description: '파일에서 정확히 일치하는 문자열을 바꾼다. 먼저 Read 로 읽어야 한다.'
+        + ' **고칠 자리가 여럿이면 edits 배열로 한 번에 보내라** — 파일이 서로 달라도 된다.'
+        + ' 한 군데씩 부르면 자리 수만큼 모델을 다시 불러야 해서, 여섯 군데짜리 손질에 몇 분이 그냥 간다.',
       parameters: {
         type: 'object',
         properties: {
-          file_path: { type: 'string', description: '고칠 파일 경로' },
+          file_path: { type: 'string', description: '고칠 파일 경로 (한 군데일 때)' },
           old_string: { type: 'string', description: '바꿀 대상. 파일에서 유일해야 한다' },
           new_string: { type: 'string', description: '바꿀 내용' },
           replace_all: { type: 'boolean', description: '모두 바꾸려면 true' },
+          edits: {
+            type: 'array',
+            description: '여러 군데를 한 번에. 적은 순서대로 차례로 적용된다. 이걸 쓰면 위 인자는 안 쓴다.',
+            items: {
+              type: 'object',
+              properties: {
+                file_path: { type: 'string', description: '고칠 파일 경로' },
+                old_string: { type: 'string', description: '바꿀 대상' },
+                new_string: { type: 'string', description: '바꿀 내용' },
+                replace_all: { type: 'boolean', description: '모두 바꾸려면 true' },
+              },
+              required: ['file_path', 'old_string', 'new_string'],
+            },
+          },
         },
-        required: ['file_path', 'old_string', 'new_string'],
+        required: [],
       },
     },
+    /*
+     * 갈래만 정한다. Write 와 같은 모양이다 — 한 군데일 때의 결과는 한 글자도
+     * 안 바뀐다. 그 모양을 보고 있는 자리가 여럿이라서다(loop.js 의 살려쓰기,
+     * repl.js 의 바뀐 자리 그리기, 되돌리기 스냅샷).
+     */
     run(args, ctx) {
-      const abs = ctx.scope.resolve(args.file_path);
-      if (!existsSync(abs)) return { error: `파일이 없습니다: ${args.file_path}` };
-      const 못고치는이유 = 내부살림(abs);
-      if (못고치는이유) return { error: 못고치는이유 };
-      // 엑셀 파일은 Read 로 읽히긴 하지만 고칠 수 있는 물건이 아니다.
-      // '먼저 Read 로 읽어야 합니다' 라고만 하면 이미 읽은 쪽은 계속 헛돈다.
-      if (isExcelPath(abs)) return { error: 엑셀은못고침(args.file_path) };
-      if (!ctx.seen.has(abs)) return { error: `먼저 Read 로 읽어야 합니다: ${args.file_path}` };
-      if (args.old_string === args.new_string) return { error: 'old_string 과 new_string 이 같습니다' };
-
-      const 읽음 = readTextFull(abs);
-      const text = 읽음.text;
-      const m = findMatch(text, args.old_string, { replaceAll: !!args.replace_all });
-
-      if (!m.ok) {
-        if (m.reason === 'ambiguous') {
-          return { error: `${m.count}군데에서 발견됐습니다 (${TIER_LABELS[m.tier]}). 앞뒤로 더 넓게 잡아 하나만 가리키거나 replace_all 을 쓰세요.` };
-        }
-        const hint = m.near
-          ? `\n  파일의 ${m.near.line}번 줄이 가장 비슷합니다:\n    ${m.near.text.trim().slice(0, 120)}\n  이 줄을 그대로 옮겨 담아 다시 시도하세요.`
-          : '\n  Read 로 다시 읽어 실제 내용을 확인하세요.';
-        return { error: `찾지 못했습니다.${hint}` };
+      const 목록 = Array.isArray(args.edits) ? args.edits.filter((x) => x && typeof x === 'object') : [];
+      if (목록.length) return 여러군데고치기(목록, ctx);
+      if (typeof args.file_path !== 'string' || !args.file_path) {
+        return { error: 'file_path 가 없습니다. 한 군데면 file_path·old_string·new_string 을, 여러 군데면 edits 배열을 주세요.' };
       }
-
-      ctx.history.snapshot(abs, 'Edit');
-      const next = applySpans(text, m.spans, (matched) =>
-        m.tier === 'exact' ? args.new_string : reindent(args.new_string, matched, args.old_string));
-
-      // 읽은 그 인코딩으로 되돌려 쓴다.
-      const 만든것 = encode(next, 읽음.encoding);
-      if (만든것.lost.length) {
-        return {
-          error: `이 파일은 ${encLabel(읽음.encoding)} 로 되어 있는데, 그 인코딩에 없는 글자를 넣으려 합니다: `
-               + `${만든것.lost.slice(0, 8).join(' ')}\n`
-               + `  그대로 쓰면 그 글자들이 뭉개집니다. 다른 표현을 쓰거나, 파일을 UTF-8 로 바꿔도 되는지 사용자에게 물어보세요.`,
-        };
-      }
-      writeFileSync(abs, 만든것.buf);
-
-      const n = m.spans.length;
-      const how = m.tier === 'exact' ? '' : ` · ${TIER_LABELS[m.tier]}`;
-      const 표기 = 읽음.encoding !== 'utf-8' ? ` · ${encLabel(읽음.encoding)}` : '';
-      return {
-        content: `고침: ${ctx.scope.show(abs)} (${n}군데${how}${표기})`,
-        summary: `${n}군데${how}${표기}`,
-        changed: abs,
-        tier: m.tier,
-        diff: 바뀐자리(text, next),
-      };
+      return 한군데고치기(args, ctx);
     },
   },
 
@@ -397,7 +657,7 @@ export const TOOLS = {
       const 맞는것 = walk(root)
         .filter((f) => re.test(f.rel) || re.test(f.rel.split('/').pop()))
         .sort((a, b) => b.mtime - a.mtime);
-      const files = 맞는것.slice(0, GLOB_MAX);
+      const files = 맞는것.slice(0, 찾을개수(ctx.모델컨텍스트));
       if (!files.length) return { content: `찾은 파일 없음: ${args.pattern}`, summary: '0개' };
       // 잘랐으면 잘랐다고 말한다. 전에는 '200개' 라고만 해서, 모델이 그게 전부인 줄
       // 알고 "전부 확인했습니다" 로 답을 맺었다. 실제로는 1,400개 중 200개였다.
@@ -445,7 +705,7 @@ export const TOOLS = {
       }
 
       const mode = args.output_mode ?? 'files_with_matches';
-      const limit = args.head_limit ?? 250;
+      const limit = args.head_limit ?? 찾을줄수(ctx.모델컨텍스트);
       const hitFiles = [];
       const lines = [];
       let total = 0;
@@ -536,13 +796,16 @@ export const TOOLS = {
   Bash: {
     schema: {
       name: 'Bash',
-      description: '명령을 실행한다. 되돌릴 수 없는 명령은 막힌다.',
+      description: '명령을 실행한다. 되돌릴 수 없는 명령은 막힌다.'
+        + ' **끝나지 않는 것(dev 서버·watch)은 background: true 로 띄워라** —'
+        + ' 그냥 부르면 시간 초과로 죽는다. 띄운 뒤에는 Jobs 로 출력을 읽는다.',
       parameters: {
         type: 'object',
         properties: {
           command: { type: 'string', description: '실행할 명령' },
           description: { type: 'string', description: '무엇을 하는 명령인지 한 줄' },
           timeout: { type: 'number', description: '제한 시간(ms). 기본 120000' },
+          background: { type: 'boolean', description: '끝나지 않는 명령이면 true. 바로 돌아오고 Jobs 로 읽는다' },
         },
         required: ['command'],
       },
@@ -557,6 +820,46 @@ export const TOOLS = {
       try { checkPaths(cmd, ctx.scope); }
       catch (err) { ctx.audit.blocked(err.message, cmd); return { error: `막힘 — ${err.message}` }; }
 
+      /*
+       * 파일을 바꾸는 명령이면 손대기 전 내용을 떠 둔다.
+       *
+       * 되돌리기는 Write·Edit 만 지키고 있었다. 그런데 `mv 옛것.js 새것.js` 나
+       * `rm 임시.txt` 는 Bash 로 간다 — 그 순간 파일이 사라지는데 /undo 는
+       * 아무것도 못 한다. 안전망에 난 구멍치고는 큰 편이다.
+       *
+       * 명령줄에 적힌 경로 중 **지금 있는 파일**만 뜬다. 완벽하지는 않다 —
+       * 셸이 풀어 주는 와일드카드(`rm *.tmp`)나 스크립트 안에서 지우는 것은
+       * 여기서 안 보인다. 그래서 '전부 되돌아간다' 고 말하지 않는다.
+       * 그래도 손으로 옮기고 지우는 흔한 자리는 이걸로 덮인다.
+       */
+      const 뜬것 = 바꾸기전스냅샷(cmd, ctx);
+
+      // 끝나지 않는 명령은 뒤에서 띄운다. 여기서 기다리면 그 턴이 통째로 멈춘다.
+      if (args.background === true) {
+        const r = await 띄우기(cmd, { cwd: ctx.scope.root, 설명: args.description ?? null });
+        if (r.error) return { error: r.error };
+        if (!r.떴나) {
+          // 지켜보는 사이에 죽었다. 포트가 물려 있거나 명령이 틀린 경우다.
+          // 이걸 '띄웠습니다' 로 넘기면 모델은 다음 단계로 가고, 사람은 안 뜬
+          // 서버를 찾아다닌다. 실패로 못 박고 나온 말을 그대로 준다.
+          return {
+            error: `띄우자마자 끝났습니다 (${r.시그널 ? `${r.시그널} 시그널` : `종료코드 ${r.종료코드}`}).`
+              + ' 뒤에서 돌 명령이 아니거나, 뜨자마자 탈이 난 것입니다.'
+              + (r.출력?.trim() ? `\n\n나온 말:\n${clip(r.출력, 4000)}` : ''),
+            failed: true,
+          };
+        }
+        return {
+          content: `${r.번호}번으로 띄웠습니다: ${cmd}\n`
+            + (r.출력?.trim() ? `\n${clip(r.출력, 4000)}\n` : '')
+            + `\n계속 돌고 있습니다. 새 출력은 Jobs({번호: ${r.번호}}) 로 읽고, 일이 끝나면 Jobs({번호: ${r.번호}, 끝내기: true}) 로 정리해라.`,
+          summary: `${r.번호}번으로 띄움`,
+          일감번호: r.번호,
+          뒤에서: true,
+          되돌릴것: 뜬것,
+        };
+      }
+
       /*
        * 명령을 셸에 넘기는 방법. 윈도우에서 여기가 조용히 틀려 있었다.
        *
@@ -638,6 +941,8 @@ export const TOOLS = {
             failed: !잘됨,
             exitCode: code,
             signal: 시그널,
+            // 무엇을 떠 뒀는지 화면이 알아야 '되돌릴 수 있다' 를 사실대로 적는다.
+            되돌릴것: 뜬것,
           });
         });
 
@@ -794,11 +1099,91 @@ export const TOOLS = {
   },
 
   TodoWrite: TODO_TOOL,
+
+  // 만든 것이 진짜 되는지. 끝맺기 전에 오는 자리다 — verify.js 머리말 참고.
+  Verify: VERIFY_TOOL,
+
+  // 프로젝트 뼈대만 싸게 보기. Read 앞에 오는 자리다 — outline.js 머리말 참고.
+  Outline: OUTLINE_TOOL,
+
+  // 하위 작업. 실행은 loop.js 가 가로채서 한다 — task.js 머리말 참고.
+  Task: TASK_TOOL,
+
+  // 뒤에서 도는 명령 보기·끝내기. Bash(background) 와 짝이다 — jobs.js 머리말 참고.
+  Jobs: JOBS_TOOL,
 };
 
+/**
+ * 도구 설명을 창 크기에 맞게 줄인다.
+ *
+ * 문장 단위로 자른다. 글자 수로 뚝 자르면 "…파일을 통째로 Read 하는 것보다"
+ * 처럼 말이 끊긴 채로 모델에게 간다 — 그건 안 준 것만 못하다.
+ * 첫 문장은 무슨 일이 있어도 남긴다. 그게 이 도구가 무엇인지다.
+ *
+ * 인자 설명도 같이 줄인다. 괄호로 붙인 보충(`(한 개일 때)`)이 먼저 떨어진다.
+ */
+const 뻔한인자 = new Set(['file_path', 'content', 'pattern', 'path', 'command', 'text', 'name']);
+
+export function 설명줄이기(schema, 한도) {
+  if (!Number.isFinite(한도)) return schema;
+
+  const 자르기 = (글, 몫) => {
+    const s = String(글 ?? '');
+    if (s.length <= 몫) return s;
+    // 한국어 문장은 '다.' 로 끝난다. 영문 마침표도 같이 본다.
+    const 조각 = s.split(/(?<=다\.|[.!?])\s+/);
+    let 모은것 = 조각[0] ?? s;
+    for (const 다음 of 조각.slice(1)) {
+      if ((모은것 + ' ' + 다음).length > 몫) break;
+      모은것 += ' ' + 다음;
+    }
+    return 모은것;
+  };
+
+  const p = schema.parameters ?? {};
+  const 인자몫 = Math.max(24, Math.round(한도 / 3));
+  const 새속성 = {};
+  for (const [이름, 값] of Object.entries(p.properties ?? {})) {
+    // 이름만 봐도 아는 인자는 아주 좁은 창에서 설명을 통째로 뺀다.
+    // `file_path` 가 무엇인지 설명하는 데 토큰을 쓰는 것은, 8k 모델에서는
+    // 그 토큰만큼 대화를 잘라먹는 것과 같다. 헷갈릴 만한 것(offset·files·
+    // replace_all·목적·할일)은 그대로 둔다 — 거기서 틀리면 일이 안 된다.
+    if (한도 <= 100 && 뻔한인자.has(이름)) { 새속성[이름] = { type: 값.type }; continue; }
+    /*
+     * 배열 안쪽 설명은 좁은 창에서 통째로 뺀다.
+     *
+     * files·edits 의 items 는 바깥이 이미 한 말을 되풀이한다 — 바깥에서
+     * "여러 파일을 한 번에" 라고 하고, 안쪽에서 다시 "쓸 파일 경로"·"파일 전체
+     * 내용" 이라고 한다. 이름(file_path·content)만 봐도 아는 것이라, 8k 에서는
+     * 그 되풀이가 곧 대화 자리를 먹는 것과 같다.
+     *
+     * **required 와 type 은 안 건드린다.** 그건 설명이 아니라 규격이라,
+     * 빼면 모델이 무엇을 넣어야 하는지를 실제로 모르게 된다.
+     */
+    if (한도 <= 160 && 값?.type === 'array' && 값.items?.properties) {
+      const 안쪽 = {};
+      for (const [n, v] of Object.entries(값.items.properties)) 안쪽[n] = { type: v.type };
+      새속성[이름] = {
+        ...값,
+        description: 값.description ? 자르기(String(값.description), 인자몫) : undefined,
+        items: { ...값.items, properties: 안쪽 },
+      };
+      continue;
+    }
+    새속성[이름] = 값?.description
+      ? { ...값, description: 자르기(String(값.description).replace(/\s*\([^)]*\)\s*$/, ''), 인자몫) }
+      : 값;
+  }
+  return {
+    ...schema,
+    description: 자르기(schema.description, 한도),
+    parameters: { ...p, properties: 새속성 },
+  };
+}
+
 // 모델에게 넘길 도구 정의 목록.
 // 스킬이 없으면 Skill 도구는 빼서 자리를 아낀다.
-export function toolSchemas(names = null, { hasSkills = false, web = true, work = null, mcp = null } = {}) {
+export function toolSchemas(names = null, { hasSkills = false, web = true, work = null, mcp = null, ctx = null } = {}) {
   let list = names ?? Object.keys(TOOLS).filter((n) => {
     if (n === 'Skill') return hasSkills;
     if (n === 'WebFetch') return web;
@@ -809,7 +1194,15 @@ export function toolSchemas(names = null, { hasSkills = false, web = true, work
   // 설계·계획·묻기 모드에서 파일을 바꾸면 안 된다고 프롬프트로 부탁할 수도 있다.
   // 그런데 모델은 부탁을 잊는다. 목록에서 아예 빼면 잊을 것이 없다.
   if (work) list = allowedIn(work, list);
-  const 우리것 = list.map((n) => ({ type: 'function', function: TOOLS[n].schema }));
+  /*
+   * 창이 좁으면 설명을 줄여 싣는다 (budget.js 의 설명길이).
+   *
+   * 도구를 빼지는 않는다. 빼면 작은 모델만 할 수 있는 일이 달라져서
+   * "환경마다 다르게 동작" 하게 되는데, 그건 이 프로그램이 피하려는 것이다.
+   * 이름과 인자는 그대로 남으므로 할 수 있는 일은 똑같다.
+   */
+  const 한도 = 설명길이(ctx);
+  const 우리것 = list.map((n) => ({ type: 'function', function: 설명줄이기(TOOLS[n].schema, 한도) }));
 
   /*
    * 밖에서 붙인 도구(MCP)를 뒤에 붙인다.