byuckchon-frontend-cli 1.4.0 → 1.5.0

package/README.md

@@ -10,11 +10,47 @@ React(Vite) / Next.js(App Router) TypeScript 프로젝트를 만들고, `bc chat
 
 ## 설치
 
+`bc` 는 **CLI 툴** 이라서 프로젝트 의존성으로 설치하면 안 되고, **글로벌**(또는 `npx`)로 써야 합니다.
+
 ```bash
+# 글로벌 설치 (제일 흔한 방식)
 npm install -g byuckchon-frontend-cli
-# 짧은 alias 도 동시에 설치됨: `bc`
+pnpm add -g byuckchon-frontend-cli
+yarn global add byuckchon-frontend-cli
+
+# 또는 설치 없이 일회성
+npx byuckchon-frontend-cli adopt
+pnpm dlx byuckchon-frontend-cli adopt
+```
+
+설치되면 `bc` / `byuckchon-frontend-cli` 두 개 다 PATH 에 깔립니다.
+
+### 모노레포에서 쓰기
+
+`bc` 자체는 **루트에 한 번만** 글로벌 설치하면 충분합니다. 다만 `bc.config.json` 은
+**각 패키지(앱) 디렉터리마다 따로** 두는 걸 권장 — Tailwind 버전, 라우팅, 스타일링이
+앱마다 다르면 `detected.*` 가 달라야 RAG 컨텍스트도 정확해집니다.
+
+```bash
+# 루트에서 한 번만
+npm i -g byuckchon-frontend-cli
+
+# 각 앱마다 따로 셋업
+cd apps/web    && bc adopt    # apps/web/bc.config.json 생성
+cd apps/mobile && bc adopt    # apps/mobile/bc.config.json 생성
+
+# 일할 땐 그 앱 디렉토리에서 실행
+cd apps/web && bc             # apps/web/bc.config.json 을 자동으로 읽어감
 ```
 
+`bc` 는 실행 디렉토리에서 위로 거슬러 올라가며 가장 가까운 `bc.config.json` 을 찾습니다.
+즉 모노레포 루트에 `bc.config.json` 이 없고 `apps/web/bc.config.json` 만 있으면,
+`apps/web/somewhere/deeper/...` 에서 `bc` 를 쳐도 `apps/web/bc.config.json` 이 잡힙니다.
+
+> 만약 `pnpm add byuckchon-frontend-cli` (글로벌 플래그 없이) 한 상태에서 `bc` 가
+> 안 먹는다면, 이건 패키지 의존성으로 박혀서 그래요. `pnpm remove byuckchon-frontend-cli`
+> 후 위처럼 `pnpm add -g` 로 다시 설치해주세요.
+
 ## 명령
 
 ### `bc init` — 새 프로젝트 만들기
@@ -26,6 +62,35 @@ bc init
 프로젝트 이름, 프레임워크, **기본 AI 모델, Figma URL, OpenAPI URL** 을 묻고
 새 폴더에 코드 + `bc.config.json` 까지 만들어 줍니다.
 
+### 에이전트 모드 — AI 가 실제 파일을 만들고 고친다 (v1.5+)
+
+`bc chat` 은 더 이상 채팅창에 코드 블록을 출력만 하지 않습니다. **모델이 직접 툴을 호출해서
+파일을 만들고/고칩니다** (Codex CLI / Cursor agent 와 같은 컨셉).
+
+내장된 툴:
+
+| 툴            | 동작                                                   |
+| ------------- | ------------------------------------------------------ |
+| `read_file`   | 프로젝트 내 파일/디렉터리 내용 읽기                     |
+| `list_files`  | 글롭 패턴으로 파일 나열                                 |
+| `search_code` | RAG 인덱스 의미 기반 검색 (인덱스 있어야 함)             |
+| `write_file`  | 새 파일 생성 또는 통째 덮어쓰기                          |
+| `edit_file`   | 유일한 `old_string → new_string` 으로 부분 수정 (안전)  |
+
+모델은 한 턴 안에서 **최대 12 step** 까지 툴을 자유롭게 호출합니다. 일반적인 흐름:
+1. `list_files` 로 `src/api/` 구조 파악
+2. `read_file` 로 기존 모듈 2~3개 읽고 컨벤션 학습
+3. `search_code` 로 fetch 래퍼 / hook 패턴 검색
+4. `write_file` 로 `api/`, `service/`, `hook/`, `schema/`, `types/` 파일들을 한꺼번에 생성
+5. 마지막에 만든 파일 목록과 import 가이드를 짧게 요약
+
+모든 파일 경로는 `bc.config.json` 이 있는 디렉터리(=프로젝트 루트) 하위로만 강제됩니다.
+`../` 이나 절대경로 탈출은 에러로 거부.
+
+> **승인 게이트 (Phase 4 예정):** 지금은 모델이 write/edit 을 호출하면 즉시 디스크에 반영됩니다.
+> 안전망은 git diff. 매 작업 후 `git status` / `git diff` 로 확인하고, 마음에 안 들면 `git checkout .` 으로 되돌리세요.
+> 다음 버전에서 per-file 승인(`y/n/v`) 옵션 추가 예정.
+
 ### OpenAPI / 코드 컨텍스트 — 자동 주입 (v1.4+)
 
 `bc.config.json` 의 `api.openapi` 와 코드 인덱스는 **chat 시작할 때 알아서 준비됩니다.**
@@ -196,6 +261,9 @@ bc config set-gateway                       # 게이트웨이 해제 (BYOK 모
 - [x] Phase 3a: 코드베이스 RAG (`bc index`, `/rag` 토글, 자동 컨텍스트 주입)
 - [x] Phase 3b: `bc gen api-types` (OpenAPI → TS 타입), `/paste` 클립보드 이미지, 한글 IME 수정
 - [x] Phase 3c-1: chat 시작 시 인덱스 자동 빌드, OpenAPI 자동 fetch+캐시+시스템 프롬프트 주입
+- [x] v1.4.1 — `deepMerge(null, obj)` TypeError 수정 (`bc adopt` 한 프로젝트에서 모든 명령이 터지던 버그)
+- [x] v1.5.0 — 에이전트 모드 (read/list/search/write/edit 툴) — AI 가 실제 파일을 만든다
+- [ ] v1.6.0 — write/edit 승인 게이트 (`y/n/v/q`), diff 미리보기
 - [ ] Phase 3c-2: Figma 실 fetch (URL → 노드 트리 → 컴포넌트 인텐트)
 - [ ] Phase 4: `bc gen component/page` (AST 편집 + 검증 루프), `/apply` diff 미리보기
 

package/bin/index.js

@@ -27,7 +27,7 @@ const program = new Command();
 program
   .name('bc')
   .description('Byuckchon Frontend Workbench — 프로젝트 스타터 + AI 어시스턴트')
-  .version('1.4.0');
+  .version('1.5.0');
 
 program
   .command('init')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "byuckchon-frontend-cli",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Byuckchon Frontend Workbench — project starter + AI chat + codebase RAG + OpenAPI codegen",
   "type": "module",
   "engines": {

package/src/ai/systemPrompt.js

@@ -10,9 +10,32 @@ import { CONFIG_PATHS } from '../config/index.js';
  */
 export function buildSystemPrompt({ effective, paths, project }) {
   const lines = [
-    '너는 Byuckchon 프론트엔드 팀의 페어 프로그래밍 AI 다.',
-    '한국어로 친근하고 간결하게 답한다. 코드 답변은 마크다운 코드블록(언어 태그 포함)으로 준다.',
-    '추측 대신 모르면 모른다고 말한다. 파일 경로를 언급할 때는 백틱으로 감싼다.',
+    '너는 Byuckchon 프론트엔드 팀의 페어 프로그래밍 AI 이자 **에이전트** 다.',
+    '한국어로 친근하고 간결하게 답한다. 파일 경로는 백틱으로 감싼다.',
+    '추측 대신 모르면 모른다고 말한다.',
+    '',
+    '## 작업 방식 (중요)',
+    '너는 채팅에 코드를 출력하는 게 아니라, **툴을 호출해서 실제로 파일을 만들고 고친다.**',
+    '코드를 작성/수정해달라는 요청을 받으면 다음 순서를 지킨다:',
+    '  1) `list_files` / `read_file` / `search_code` 로 **기존 컨벤션을 먼저 학습**한다.',
+    '     - 비슷한 도메인의 폴더 구조, 파일 이름, import 순서, barrel(`index.ts`) 패턴, ',
+    '       에러 처리 방식, 상태관리/쿼리 패턴 등을 그대로 따라간다.',
+    '     - "기존 api 폴더 참고해서" 같은 요청을 받으면 그 폴더를 list_files 로 훑고',
+    '       대표 파일 2~3개를 read_file 로 반드시 읽는다.',
+    '  2) 필요한 파일을 `write_file` (신규/덮어쓰기) 또는 `edit_file` (부분 수정) 로 **직접 만든다**.',
+    '     - 한 번의 요청에 여러 파일(예: api / service / hook / type / zod schema) 이 필요하면',
+    '       모두 차례로 생성한다. 사용자가 명시하지 않아도 같이 만들 때가 적절하면 만든다.',
+    '     - 자동 생성된 `*.gen.ts` 가 있다면 거기서 타입을 import 해서 재정의를 피한다.',
+    '  3) 마지막으로 **만든 파일 목록과 다음 액션(어디서 import 하면 되는지 등)** 을 한국어로 짧게 요약.',
+    '',
+    '"코드 짜줘" 라는 표현은 채팅창에 코드 블록을 출력하라는 의미가 **아니다**.',
+    '항상 툴을 사용해 실제 파일을 만들어라. 채팅에는 진행 상황과 결과 요약만 짧게 적는다.',
+    '',
+    '## 안전 규칙',
+    '- 절대 프로젝트 루트 밖을 읽거나 쓰지 않는다.',
+    '- 기존 파일을 덮어쓸 때는 먼저 `read_file` 로 현재 내용을 보고, 의도된 덮어쓰기인지 확인.',
+    '- 큰 변경은 `edit_file` 여러 번이 안전. 통째 덮어쓰기는 새 파일이거나 작은 파일에만.',
+    '- 코드 컨벤션이 모호하면 사용자에게 한 번 물어볼 것 (툴 호출 멈추고 메시지로).',
   ];
 
   const stack = describeStack(project);

package/src/ai/tools.js

@@ -0,0 +1,236 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import fg from 'fast-glob';
+import { tool } from 'ai';
+
+import { searchIndex } from '../indexer/search.js';
+
+/**
+ * Agentic chat 용 툴 정의.
+ *
+ * 설계 원칙:
+ *  - **모든 파일 경로는 projectRoot 하위로 강제** (탈출 시도는 에러).
+ *  - read/list/search 는 always-allow (안전).
+ *  - write/edit 는 `safeWrite` 가 디스크에 쓰고 onWrite 콜백으로 UI 에 알린다.
+ *    승인 게이트를 추후 끼우려면 onWrite 안에서 await 로 막으면 된다.
+ *  - 모든 결과는 plain JSON 으로 돌려준다 (모델이 다시 추론하기 좋게).
+ *
+ * 사용:
+ *   const tools = buildTools({ projectRoot, effective, onEvent });
+ *   streamText({ tools, stopWhen: stepCountIs(12), ... });
+ */
+export function buildTools({ projectRoot, effective, onEvent = () => {} }) {
+  const root = path.resolve(projectRoot);
+
+  function safePath(p) {
+    if (!p || typeof p !== 'string') {
+      throw new Error('path 가 비어있습니다');
+    }
+    const abs = path.isAbsolute(p) ? path.resolve(p) : path.resolve(root, p);
+    const rel = path.relative(root, abs);
+    if (rel.startsWith('..') || path.isAbsolute(rel)) {
+      throw new Error(`프로젝트 루트(${root}) 밖의 경로는 접근할 수 없습니다: ${p}`);
+    }
+    return { abs, rel: rel || '.' };
+  }
+
+  async function readFile({ path: p }) {
+    const { abs, rel } = safePath(p);
+    let stat;
+    try {
+      stat = await fs.stat(abs);
+    } catch {
+      return { ok: false, error: `파일이 존재하지 않습니다: ${rel}` };
+    }
+    if (stat.isDirectory()) {
+      const entries = await fs.readdir(abs, { withFileTypes: true });
+      return {
+        ok: true,
+        kind: 'directory',
+        path: rel,
+        entries: entries.map((e) => (e.isDirectory() ? e.name + '/' : e.name)),
+      };
+    }
+    if (stat.size > 256 * 1024) {
+      return { ok: false, error: `파일이 너무 큽니다 (${stat.size}B). 256KB 이하만 지원.` };
+    }
+    const content = await fs.readFile(abs, 'utf8');
+    return { ok: true, kind: 'file', path: rel, lines: content.split('\n').length, content };
+  }
+
+  async function listFiles({ pattern = '**/*', limit = 100 }) {
+    const matches = await fg(pattern, {
+      cwd: root,
+      ignore: ['node_modules/**', 'dist/**', 'build/**', '.next/**', '.bc/**', '.git/**'],
+      onlyFiles: false,
+      dot: false,
+      followSymbolicLinks: false,
+    });
+    const truncated = matches.length > limit;
+    return {
+      ok: true,
+      total: matches.length,
+      truncated,
+      matches: matches.slice(0, limit),
+    };
+  }
+
+  async function searchCode({ query, k = 8 }) {
+    try {
+      const res = await searchIndex(query, effective, { topK: Math.min(20, Math.max(1, k)), minScore: 0.15 });
+      if (!res.ok) {
+        return { ok: false, error: res.reason ?? 'index 없음 — /index 로 빌드하라고 안내할 것' };
+      }
+      return {
+        ok: true,
+        hits: res.results.map((r) => ({
+          file: r.chunk.file,
+          range: `${r.chunk.startLine}-${r.chunk.endLine}`,
+          score: Number(r.score.toFixed(3)),
+          snippet: r.chunk.text.slice(0, 1200),
+        })),
+      };
+    } catch (err) {
+      return { ok: false, error: err?.message ?? String(err) };
+    }
+  }
+
+  async function writeFile({ path: p, content }) {
+    const { abs, rel } = safePath(p);
+    let existed = false;
+    let prevContent = '';
+    try {
+      prevContent = await fs.readFile(abs, 'utf8');
+      existed = true;
+    } catch {
+      /* 새 파일 */
+    }
+    if (existed && prevContent === content) {
+      onEvent({ kind: 'write_skipped', path: rel, reason: '동일' });
+      return { ok: true, path: rel, action: 'noop', reason: '내용 동일' };
+    }
+    await fs.mkdir(path.dirname(abs), { recursive: true });
+    await fs.writeFile(abs, content, 'utf8');
+    onEvent({
+      kind: existed ? 'write_overwritten' : 'write_created',
+      path: rel,
+      lines: content.split('\n').length,
+      bytes: Buffer.byteLength(content, 'utf8'),
+    });
+    return {
+      ok: true,
+      path: rel,
+      action: existed ? 'overwritten' : 'created',
+      lines: content.split('\n').length,
+    };
+  }
+
+  async function editFile({ path: p, old_string, new_string }) {
+    const { abs, rel } = safePath(p);
+    let content;
+    try {
+      content = await fs.readFile(abs, 'utf8');
+    } catch {
+      return { ok: false, error: `편집할 파일이 없습니다: ${rel}` };
+    }
+    if (typeof old_string !== 'string' || old_string.length === 0) {
+      return { ok: false, error: 'old_string 이 비어있습니다' };
+    }
+    // 정확 일치 횟수 계산
+    let count = 0;
+    let idx = 0;
+    while ((idx = content.indexOf(old_string, idx)) !== -1) {
+      count++;
+      idx += old_string.length;
+    }
+    if (count === 0) {
+      return { ok: false, error: `old_string 을 ${rel} 에서 찾지 못했습니다. 주변 라인을 더 포함해서 다시 시도.` };
+    }
+    if (count > 1) {
+      return {
+        ok: false,
+        error: `old_string 이 ${rel} 에 ${count}번 등장합니다. 더 많은 컨텍스트로 유일해지게 만들어 주세요.`,
+      };
+    }
+    const updated = content.replace(old_string, new_string);
+    await fs.writeFile(abs, updated, 'utf8');
+    onEvent({
+      kind: 'edit',
+      path: rel,
+      removed: old_string.split('\n').length,
+      added: new_string.split('\n').length,
+    });
+    return { ok: true, path: rel, action: 'edited' };
+  }
+
+  return {
+    read_file: tool({
+      description:
+        '프로젝트 안의 파일이나 디렉터리 내용을 읽는다. 코드 짜기 전에 반드시 기존 코드 컨벤션을 먼저 읽어볼 것.',
+      inputSchema: {
+        type: 'object',
+        properties: { path: { type: 'string', description: '프로젝트 루트 기준 상대 경로' } },
+        required: ['path'],
+        additionalProperties: false,
+      },
+      execute: readFile,
+    }),
+    list_files: tool({
+      description:
+        '글롭 패턴으로 파일을 나열. 폴더 구조 파악, 비슷한 모듈 위치 찾기에 사용. 예: "src/api/**/*.ts"',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          pattern: { type: 'string', default: '**/*' },
+          limit: { type: 'number', default: 100 },
+        },
+        additionalProperties: false,
+      },
+      execute: listFiles,
+    }),
+    search_code: tool({
+      description:
+        '코드베이스를 의미 기반(임베딩)으로 검색. "fetch 래퍼 패턴", "useQuery hook 컨벤션" 같이 자연어로 찾기. 인덱스가 없으면 에러.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          query: { type: 'string' },
+          k: { type: 'number', default: 8 },
+        },
+        required: ['query'],
+        additionalProperties: false,
+      },
+      execute: searchCode,
+    }),
+    write_file: tool({
+      description:
+        '새 파일을 만들거나 기존 파일을 통째로 덮어쓴다. 새 파일을 만들기 전에 반드시 1) 비슷한 기존 파일을 read_file 로 보고 2) 같은 폴더 컨벤션(barrel 파일, 네이밍, import 순서) 을 따른다.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          path: { type: 'string' },
+          content: { type: 'string' },
+        },
+        required: ['path', 'content'],
+        additionalProperties: false,
+      },
+      execute: writeFile,
+    }),
+    edit_file: tool({
+      description:
+        '기존 파일에서 old_string 을 찾아 new_string 으로 정확히 1번 치환. old_string 은 파일 안에서 유일해지도록 충분한 컨텍스트(앞뒤 줄) 를 포함시킬 것. 여러 번 등장하면 에러로 거부.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          path: { type: 'string' },
+          old_string: { type: 'string' },
+          new_string: { type: 'string' },
+        },
+        required: ['path', 'old_string', 'new_string'],
+        additionalProperties: false,
+      },
+      execute: editFile,
+    }),
+  };
+}

package/src/commands/chat.js

@@ -1,13 +1,16 @@
 import process from 'node:process';
 
 import chalk from 'chalk';
-import { streamText } from 'ai';
+import { streamText, stepCountIs } from 'ai';
+
+import path from 'node:path';
 
 import { loadEffectiveConfig } from '../config/index.js';
 import { resolveModel } from '../ai/provider.js';
 import { TokenMeter } from '../ai/tokenMeter.js';
 import { buildSystemPrompt } from '../ai/systemPrompt.js';
 import { findModel } from '../ai/models.js';
+import { buildTools } from '../ai/tools.js';
 import {
   createSession,
   saveSession,
@@ -189,15 +192,39 @@ async function runInkApp({ cfg, resolved, system, session, openapiInfo }) {
 
 async function runOnce({ cfg, resolved, system, prompt }) {
   const meter = new TokenMeter(resolved.meta, cfg.effective.limits);
+  const projectRoot = cfg.paths.projectFile
+    ? path.dirname(cfg.paths.projectFile)
+    : process.cwd();
+  const tools = buildTools({
+    projectRoot,
+    effective: cfg.effective,
+    onEvent: (ev) => {
+      const label =
+        ev.kind === 'write_created'
+          ? '🆕'
+          : ev.kind === 'write_overwritten'
+            ? '✏️ '
+            : ev.kind === 'edit'
+              ? '✏️ '
+              : '·';
+      console.log(chalk.dim(`  ${label} ${ev.path}`));
+    },
+  });
   const result = streamText({
     model: resolved.model,
     system,
     messages: [{ role: 'user', content: prompt }],
+    tools,
+    stopWhen: stepCountIs(12),
     onError: ({ error }) => {
       console.error(chalk.red('\n  AI 호출 에러: ') + (error?.message ?? error));
     },
   });
-  for await (const delta of result.textStream) process.stdout.write(delta);
+  for await (const part of result.fullStream) {
+    if (part.type === 'text-delta') process.stdout.write(part.text);
+    else if (part.type === 'tool-call')
+      process.stdout.write(chalk.dim(`\n  🔧 ${part.toolName}\n`));
+  }
   process.stdout.write('\n');
   try {
     meter.add(await result.usage);
@@ -257,10 +284,30 @@ async function runReadlineFallback({ cfg, resolved, system, session, openapiInfo
     history.push({ role: 'user', content: line });
     rl.pause();
 
+    const projectRoot = cfg.paths.projectFile
+      ? path.dirname(cfg.paths.projectFile)
+      : process.cwd();
+    const tools = buildTools({
+      projectRoot,
+      effective: cfg.effective,
+      onEvent: (ev) => {
+        const label =
+          ev.kind === 'write_created'
+            ? '🆕 생성'
+            : ev.kind === 'write_overwritten'
+              ? '✏️  덮어씀'
+              : ev.kind === 'edit'
+                ? '✏️  편집'
+                : '·';
+        console.log(chalk.dim(`\n  ${label} ${ev.path}`));
+      },
+    });
     const result = streamText({
       model: resolved.model,
       system,
       messages: history,
+      tools,
+      stopWhen: stepCountIs(12),
       onError: ({ error }) => {
         console.error(chalk.red('\n  AI 호출 에러: ') + (error?.message ?? error));
       },
@@ -268,9 +315,13 @@ async function runReadlineFallback({ cfg, resolved, system, session, openapiInfo
     process.stdout.write(chalk.bold.green('\n  bc › '));
     let acc = '';
     try {
-      for await (const delta of result.textStream) {
-        acc += delta;
-        process.stdout.write(delta);
+      for await (const part of result.fullStream) {
+        if (part.type === 'text-delta') {
+          acc += part.text;
+          process.stdout.write(part.text);
+        } else if (part.type === 'tool-call') {
+          process.stdout.write(chalk.dim(`\n  🔧 ${part.toolName}`));
+        }
       }
     } catch (err) {
       console.error('\n' + chalk.red('  스트리밍 중단: ') + (err?.message ?? err));

package/src/config/index.js

@@ -78,6 +78,9 @@ async function writeJson(file, data) {
 
 function deepMerge(base, patch) {
   if (patch == null) return base;
+  // 한쪽이 null/원시값이거나, 한쪽만 배열이면 patch 가 우선.
+  // 특히 base 가 null 인데 patch 가 객체일 때 `k in base` 가 TypeError 던지는 걸 방지.
+  if (base == null) return patch;
   if (typeof base !== 'object' || typeof patch !== 'object') return patch;
   if (Array.isArray(base) || Array.isArray(patch)) return patch;
   const out = { ...base };

package/src/ui/ChatApp.js

@@ -5,17 +5,45 @@ import React, { useEffect, useState, useRef, useCallback } from 'react';
 import { Box, Text, useApp, useInput, useStdout } from 'ink';
 import TextInput from 'ink-text-input';
 import Spinner from 'ink-spinner';
-import { streamText } from 'ai';
+import { streamText, stepCountIs } from 'ai';
 
 import { resolveModel } from '../ai/provider.js';
 import { TokenMeter } from '../ai/tokenMeter.js';
 import { findModel, MODEL_CATALOG } from '../ai/models.js';
 import { toSdkMessages, isImagePath } from '../ai/messageContent.js';
+import { buildTools } from '../ai/tools.js';
 import { searchIndex } from '../indexer/search.js';
 import { loadIndex, buildIndex } from '../indexer/store.js';
 
 const h = React.createElement;
 
+/** 툴 호출의 input 을 채팅 한 줄에 보여줄 수 있게 압축. content 같은 대형 필드는 길이만 표시. */
+function summarizeToolInput(name, input) {
+  if (!input || typeof input !== 'object') return '';
+  switch (name) {
+    case 'read_file':
+    case 'write_file':
+    case 'edit_file':
+      return JSON.stringify(input.path ?? '');
+    case 'list_files':
+      return JSON.stringify(input.pattern ?? '**/*');
+    case 'search_code':
+      return JSON.stringify(input.query ?? '');
+    default:
+      // 일반 케이스 — 너무 긴 필드는 잘라낸다.
+      try {
+        const small = {};
+        for (const [k, v] of Object.entries(input)) {
+          if (typeof v === 'string' && v.length > 60) small[k] = v.slice(0, 60) + '…';
+          else small[k] = v;
+        }
+        return JSON.stringify(small);
+      } catch {
+        return '';
+      }
+  }
+}
+
 /**
  * macOS 클립보드의 이미지(예: 스크린샷)를 임시 파일로 떨궈 절대경로를 돌려준다.
  *
@@ -673,10 +701,45 @@ export function ChatApp({ initialConfig, initialResolved, session, onSessionUpda
 
     try {
       const sdkMessages = await toSdkMessages(newMessages);
+
+      // 프로젝트 루트 결정: bc.config.json 이 있는 디렉터리, 없으면 cwd.
+      const projectRoot = cfg.paths.projectFile
+        ? path.dirname(cfg.paths.projectFile)
+        : process.cwd();
+
+      // 툴 실행 이벤트는 채팅에 시스템 메시지로 표시 (사용자가 무엇이 일어났는지 보게).
+      const onToolEvent = (ev) => {
+        const labels = {
+          write_created: '🆕 생성',
+          write_overwritten: '✏️  덮어씀',
+          write_skipped: '⏭  스킵',
+          edit: '✏️  편집',
+        };
+        const label = labels[ev.kind] ?? ev.kind;
+        const detail =
+          ev.lines != null
+            ? `(${ev.lines} lines)`
+            : ev.added != null
+              ? `(+${ev.added} / -${ev.removed} lines)`
+              : '';
+        setMessages((m) => [
+          ...m,
+          { role: 'system-info', text: `${label} ${ev.path} ${detail}`.trim() },
+        ]);
+      };
+
+      const tools = buildTools({
+        projectRoot,
+        effective: cfg.effective,
+        onEvent: onToolEvent,
+      });
+
       const result = streamText({
         model: resolved.model,
         system: systemWithContext,
         messages: sdkMessages,
+        tools,
+        stopWhen: stepCountIs(12),
         onError: ({ error }) => {
           replaceWithError('AI 호출 에러: ' + (error?.message ?? String(error)));
         },
@@ -685,13 +748,36 @@ export function ChatApp({ initialConfig, initialResolved, session, onSessionUpda
       setState('streaming');
       let acc = '';
       try {
-        for await (const delta of result.textStream) {
-          acc += delta;
-          setMessages((m) => {
-            const next = [...m];
-            next[assistantIdx] = { role: 'assistant', text: acc, streaming: true };
-            return next;
-          });
+        // fullStream 으로 tool-call / tool-result / text-delta 다 다룸.
+        for await (const part of result.fullStream) {
+          if (part.type === 'text-delta') {
+            acc += part.text;
+            setMessages((m) => {
+              const next = [...m];
+              next[assistantIdx] = { role: 'assistant', text: acc, streaming: true };
+              return next;
+            });
+          } else if (part.type === 'tool-call') {
+            // 모델이 툴을 호출하는 순간 — 한 줄로 표시.
+            const argSummary = summarizeToolInput(part.toolName, part.input);
+            setMessages((m) => [
+              ...m,
+              {
+                role: 'system-info',
+                text: `🔧 ${part.toolName}(${argSummary})`,
+              },
+            ]);
+          } else if (part.type === 'tool-error') {
+            setMessages((m) => [
+              ...m,
+              {
+                role: 'system-error',
+                text: `툴 에러 (${part.toolName ?? '?'}): ${part.error?.message ?? part.error}`,
+              },
+            ]);
+          } else if (part.type === 'error') {
+            replaceWithError('스트림 에러: ' + (part.error?.message ?? String(part.error)));
+          }
         }
       } catch (streamErr) {
         replaceWithError('스트리밍 중단: ' + (streamErr?.message ?? String(streamErr)));
@@ -700,14 +786,26 @@ export function ChatApp({ initialConfig, initialResolved, session, onSessionUpda
       // 에러가 안 났을 때만 final assistant 로 마무리.
       if (!errorText) {
         if (acc.length === 0) {
-          // 응답이 아예 비었지만 onError 도 안 떴다 → finishReason 으로 추적.
+          // 텍스트가 없어도 툴만 호출하고 끝났을 수 있음 — 그건 정상.
+          // finishReason 으로 진짜 비정상인지 분기.
           let reason = 'unknown';
           try {
             reason = await result.finishReason;
           } catch {
             /* noop */
           }
-          replaceWithError(`빈 응답 (finishReason=${reason}). API 키/크레딧/모델을 확인하세요.`);
+          if (reason === 'tool-calls' || reason === 'stop') {
+            // 툴만 호출하고 자연스럽게 멈춤 → placeholder 제거.
+            setMessages((m) => {
+              const next = [...m];
+              if (next[assistantIdx]?.role === 'assistant' && !next[assistantIdx].text) {
+                next.splice(assistantIdx, 1);
+              }
+              return next;
+            });
+          } else {
+            replaceWithError(`빈 응답 (finishReason=${reason}). API 키/크레딧/모델을 확인하세요.`);
+          }
         } else {
           setMessages((m) => {
             const next = [...m];