claude-telegram-bot 0.3.33 → 0.3.36

package/README.ko.md

@@ -107,6 +107,10 @@ claude-telegram-bot ~/botconfigs/myproj/mybot.json
 | `appendSystemPrompt` | (선택) 기본 "간결하게 답하기" 지침을 직접 덮어쓸 때 |
 | `env` | (선택) `claude` 프로세스에 넘길 환경 변수 |
 | `schedule` | (선택) 정해진 시각에 프롬프트를 실행하는 cron 작업 — [예약 작업](#예약-작업-cron) 참고 |
+| `commands` | (선택) 쉘 스크립트를 실행하는 커스텀 `/명령어` — [커스텀 명령어](#커스텀-명령어) 참고 |
+| `ollamaFallback` | (선택) `true`로 설정하면 Claude 레이트 리밋·크레딧 부족 시 로컬 Ollama로 자동 대체 |
+| `ollamaModel` | (선택) 폴백에 쓸 Ollama 모델 (기본값: `"phi3:mini"`) |
+| `autoCompactThreshold` | (선택) 캐시된 입력 토큰이 이 값을 초과하면 컨텍스트 자동 압축 (기본값: `100000`). `0`이면 비활성화 |
 
 `state`와 첨부 파일은 config 파일 옆 **`.claude-bot/` 숨김 폴더**에 저장됩니다(프로젝트 격리). 구버전에서 올리면 첫 시작 때 기존 `state.json`·`attachments/`를 `.claude-bot/`로 **자동 이동**합니다(무손실). 로그는 launchd plist가 가리키는 위치 그대로입니다.
 
@@ -118,7 +122,9 @@ claude-telegram-bot ~/botconfigs/myproj/mybot.json
    - `테스트 돌려보고 통과하면 커밋하고 push 해줘`
    - `api.ts 에 에러 핸들링 추가해줘`
 
-명령어: `/new`(맥락 초기화) · `/stop`(작업 중단; `--reset`으로 세션도 롤백) · `/cron`(예약 작업 보기·추가·삭제) · `/reserve`(한도 리셋 시 재시도 예약) · `/restart`(문법 검사 후 재시작) · `/status`(봇 상태·버전) · `/model`(모델 보기·전환) · `/id`(채팅 ID 확인) · `/help`(도움말)
+명령어: `/new`(맥락 초기화) · `/compact`(컨텍스트 압축, 세션 유지) · `/plan <요청>`(계획만 세우고 승인/취소) · `/stop`(작업 중단; `--reset`으로 세션도 롤백) · `/ollama`(Ollama 채팅 모드 토글) · `/cron`(예약 작업 보기·추가·삭제) · `/reserve`(대기 큐 상태 확인 · `/reserve rm`으로 취소) · `/restart`(문법 검사 후 재시작) · `/status`(봇 상태·버전) · `/model`(모델 보기·전환) · `/id`(채팅 ID 확인) · `/help`(도움말)
+
+> **`/plan <요청>`** 은 봇에 설정된 `permissionMode`와 무관하게 강제로 읽기 전용 plan 모드(편집·쉘 없음)로 요청을 실행하고, 계획 내용과 함께 **✅ 진행 / ❌ 취소** 버튼을 보냅니다. **진행**을 누르면 같은 세션을 봇의 실제 `permissionMode`로 이어서 승인된 계획을 실행하고, **취소**를 누르면 세션은 그대로 유지됩니다. `bypassPermissions` 봇이 뭔가 건드리기 전에 검토 단계를 두고 싶을 때 유용합니다. `/new`로 새 세션을 시작하면 대기 중인 승인은 만료됩니다.
 
 > **`/stop`** 은 실행 중인 Claude 프로세스를 즉시 종료하고 대기 중인 메시지 큐도 비웁니다. `--reset`을 붙이면 세션을 작업 시작 이전 상태로 되돌려 중단된 작업이 대화 맥락에 남지 않습니다.
 
@@ -129,12 +135,32 @@ claude-telegram-bot ~/botconfigs/myproj/mybot.json
 - **세션 유지** — 대화는 `--resume`으로 자동으로 이어집니다. 마지막 세션 ID가 `state.json`에 저장되므로 봇을 재시작해도 맥락이 남습니다. 새로 시작하려면 `/new`.
 - **메시지 큐** — 작업 중에 새 메시지가 오면 버리지 않고 큐에 쌓아둡니다. 작업이 끝나면 대기 중인 메시지를 모두 하나의 프롬프트로 합쳐서 처리합니다(예: "A 해줘" → "아니다 B 해줘"를 한 번에 처리). `/stop`으로 실행 중인 작업과 큐를 동시에 취소할 수 있습니다.
 - **모델 권유** — 봇이 Claude에게 현재 모델을 알려줍니다. 질문 난이도가 현재 모델 수준을 넘는다고 판단되면 답변 끝에 전환 권유 한 줄이 붙습니다(예: 💡 `/model sonnet`). `/model <이름>`으로 전환(`haiku`, `sonnet`, `opus`, `fable`, 또는 전체 모델 ID) — `state.json`에 저장돼 재시작 후에도 유지됩니다.
-- **한도 초과 재시도** — Claude Max / API 레이트 리밋 에러에 리셋 시간이 포함되면 `/reserve` 힌트를 표시합니다. `/reserve`를 입력하면 마지막 메시지를 해당 시각에 자동 재전송 예약. `/reserve <다른 메시지>`로 내용 변경, `/reserve rm`으로 취소.
+- **한도 초과 큐** — Claude Max / API 레이트 리밋 에러에 리셋 시간이 포함되면, 해당 메시지를 자동으로 큐에 넣고 리셋 시각에 재시도합니다 — 작업 중 큐와 같은 방식입니다. 한도가 걸린 동안 추가로 보내는 메시지도 자동으로 큐에 쌓입니다. `/reserve`로 대기 현황과 리셋 시각 확인, `/reserve rm`으로 큐 전체 취소.
+- **Ollama 폴백** — `"ollamaFallback": true`로 설정하고 `"ollamaModel"`에 로컬 [Ollama](https://ollama.ai) 모델을 지정하면(기본값: `"phi3:mini"`), Claude 레이트 리밋·크레딧 부족 시 자동으로 Ollama로 대체 응답합니다. `/ollama`로 Claude와 관계없이 Ollama를 기본 채팅 상대로 수동 전환할 수도 있습니다 (가벼운 질문에 유용).
+- **자동 컴팩션** — 세션의 캐시된 입력 토큰이 `autoCompactThreshold`(기본값 100,000)를 초과하면 `/compact`를 자동 실행하고 알림을 보냅니다. config에서 임계값을 조정하거나 `0`으로 비활성화. 수동으로 `/compact`를 써도 됩니다.
 - **간결한 답변** — 텔레그램에 맞게 짧게 답하도록 시스템 프롬프트가 기본으로 붙습니다. 바꾸려면 `appendSystemPrompt`에 직접 넣으세요 (빈 문자열이면 끔).
 - **언어** — 봇 자체 문구(`/help`, 명령 메뉴, 상태 메시지)는 **기본 영어**, 텔레그램이 한국어인 사용자에겐 한국어로 나옵니다. `lang`(`"en"`/`"ko"`)으로 고정할 수 있습니다. Claude의 실제 답변은 **사용자가 쓴 언어**를 따라갑니다. `/` 명령 메뉴는 `setMyCommands`로 언어별 등록됩니다.
 - **서식 변환** — 답변의 마크다운(굵게·코드·표 등)을 텔레그램 HTML로 바꿔 보냅니다. 변환이 깨지는 경우엔 평문으로 다시 보냅니다.
 - **첨부 파일** — 사진·문서·음성·영상을 보내면 `attachments/`에 내려받고, 그 경로를 Claude에게 전달합니다(캡션도 함께). 이미지는 Read로 열어볼 수 있습니다.
 
+## 커스텀 명령어
+
+config에 `commands`를 정의하면 프로젝트별 `/명령어`로 쉘 스크립트를 실행하고 결과를 채팅으로 받을 수 있습니다. 정의한 명령어는 텔레그램 `/` 자동완성 메뉴에 자동 등록됩니다.
+
+```json
+"commands": {
+  "deploy": { "run": "npm run deploy", "description": "프로덕션 배포" },
+  "logs":   { "run": "tail -n 50 ./app.log", "description": "최근 로그" },
+  "status": { "run": "git status && git log --oneline -5", "description": "Git 상태" }
+}
+```
+
+- **`run`** — 실행할 쉘 명령어. `projectDir`에서 실행됩니다.
+- **`description`** — 텔레그램 `/` 자동완성 메뉴에 표시되는 설명
+- **인자 전달**: `/deploy staging`처럼 뒤에 붙이면 명령어에 그대로 추가됩니다 (`npm run deploy staging`)
+- Claude와 독립적으로 실행 — Claude 작업 중에도 동작합니다
+- 출력은 최대 4,000자, 타임아웃 60초
+
 ## 예약 작업 (cron)
 
 config에 `schedule` 배열을 두면 정해진 시각에 프롬프트를 자동 실행합니다 — 아침 브리핑, 주기적 점검, 리마인더 등. 각 항목은 프롬프트를 실행하고 결과를 `allowedChatId`로 보냅니다.

package/README.md

@@ -162,7 +162,14 @@ auth layer.)
 - `run the solver tests and commit + push if they pass`
 - `add an edge case to solve-2nd-floor-edges.ts`
 
-Commands: `/new` (reset context / new session) · `/stop` (stop current task; `--reset` to also roll back the session) · `/cron` (list / add / remove scheduled tasks) · `/reserve` (schedule retry at usage-limit reset) · `/restart` (syntax-check & restart the bot) · `/status` (bot status & version) · `/model` (view / switch the model) · `/id` (show chat ID) · `/help`.
+Commands: `/new` (reset context / new session) · `/compact` (compress context, keep session) · `/plan <request>` (plan only, then approve/cancel) · `/stop` (stop current task; `--reset` to also roll back the session) · `/ollama` (toggle Ollama chat mode) · `/cron` (list / add / remove scheduled tasks) · `/reserve` (show queue status at usage-limit · `/reserve rm` to cancel) · `/restart` (syntax-check & restart the bot) · `/status` (bot status & version) · `/model` (view / switch the model) · `/id` (show chat ID) · `/help`.
+
+> **`/plan <request>`** runs the request in read-only plan mode (no edits, no shell) regardless of
+> the bot's configured `permissionMode`, and replies with the plan plus **✅ Proceed / ❌ Cancel**
+> buttons. Tapping **Proceed** resumes the same session with the bot's normal `permissionMode` and
+> tells Claude to implement the approved plan; **Cancel** leaves the session untouched. This gives
+> you a review step before a `bypassPermissions` bot touches anything. The pending approval expires
+> if you start a new session with `/new` first.
 
 > **`/stop`** kills the running Claude process immediately and clears any queued messages.
 > Add `--reset` to also restore the session to the state it was in *before* the task started,
@@ -203,6 +210,10 @@ Edit `mybot.json`:
 | `appendSystemPrompt` | (optional) Override the default "be concise for Telegram" instruction |
 | `env` | (optional) Extra environment variables passed to the `claude` process |
 | `schedule` | (optional) Cron jobs that run a prompt on a timer — see [Scheduled tasks](#scheduled-tasks-cron) |
+| `commands` | (optional) Custom `/commands` that run shell scripts — see [Custom commands](#custom-commands) |
+| `ollamaFallback` | (optional) `true` to enable Ollama as a fallback when Claude is rate-limited or out of credits |
+| `ollamaModel` | (optional) Ollama model to use for fallback (default: `"phi3:mini"`) |
+| `autoCompactThreshold` | (optional) Auto-compact context when cached input tokens exceed this value (default: `100000`). Set to `0` to disable. |
 
 State and downloaded attachments live in a hidden **`.claude-bot/`** folder next to the config
 file, so projects stay isolated. Upgrading from an older version **auto-moves** an existing
@@ -225,7 +236,27 @@ your launchd plist points them.
   `state.json`, so context survives restarts. Use `/new` to start fresh.
 - **Message queue**: if you send a message while a task is running, it is queued (not dropped). When the task finishes, all queued messages are merged into a single prompt so Claude can resolve corrections and follow-ups in one pass (e.g. "do X" then "never mind, do Y" → handled together). Use `/stop` to cancel the running task and discard the queue.
 - **Model hint**: the bot tells Claude which model it is running as. If Claude judges a question to be beyond its current tier, it appends a one-line suggestion at the end of the reply (e.g. 💡 `/model sonnet`). Switch with `/model <name>` — `haiku`, `sonnet`, `opus`, `fable`, or a full model id. The choice persists in `state.json` across restarts.
-- **Usage-limit retry**: when a Claude Max / API rate-limit error includes a reset time, the bot shows a `/reserve` hint. `/reserve` schedules your last message to be resent automatically at that time. Use `/reserve <different text>` to change what's sent, or `/reserve rm` to cancel.
+- **Usage-limit queue**: when a Claude Max / API rate-limit error includes a reset time, the triggering message is automatically queued and retried at that time — just like messages queued while Claude is busy. Any additional messages you send during the limit window are also added to the queue. Use `/reserve` to check queue status and reset time, `/reserve rm` to cancel and clear the queue.
+- **Ollama fallback**: set `"ollamaFallback": true` and point `"ollamaModel"` at a locally-running [Ollama](https://ollama.ai) model (default: `"phi3:mini"`). When Claude is rate-limited or out of credits, the bot automatically falls back to Ollama and prepends a notice to the reply. Use `/ollama` to toggle Ollama as your primary chat partner at any time, even when Claude is working fine — useful for lightweight queries.
+- **Auto-compact**: the bot tracks how many cached tokens are in the session context. When `cache_read_input_tokens` exceeds `autoCompactThreshold` (default 100 000), it automatically runs `/compact` and notifies you. Tune the threshold in config or set it to `0` to disable. You can also run `/compact` manually at any time.
+
+### Custom commands
+
+Define project-specific `/commands` in config that run shell scripts and return their output to the chat. Commands appear in Telegram's `/` autocomplete menu automatically.
+
+```json
+"commands": {
+  "deploy": { "run": "npm run deploy", "description": "Deploy to production" },
+  "logs":   { "run": "tail -n 50 ./app.log", "description": "Recent logs" },
+  "status": { "run": "git status && git log --oneline -5", "description": "Git status" }
+}
+```
+
+- **`run`** — any shell command, executed in `projectDir`
+- **`description`** — shown in the Telegram `/` autocomplete menu
+- **Arguments**: `/deploy staging` appends `staging` to the command (`npm run deploy staging`)
+- Scripts run independently of Claude — they work even when Claude is busy
+- Output capped at 4 000 characters; 60-second timeout
 
 ### Scheduled tasks (cron)
 

package/bot.mjs

@@ -135,12 +135,13 @@ const STR = {
       "• Just send a message and Claude works in the project.\n" +
       "• /new — reset conversation context (new session)\n" +
       "• /compact — compress context to free up space (keeps the session)\n" +
+      "• /plan <request> — plan only (no edits), then approve/cancel to run for real\n" +
       "• /ollama — toggle Ollama chat mode (bypass Claude, use local LLM)\n" +
       "• /stop — stop the current task · /stop --reset to also roll back the session\n" +
       "• /cron — list tasks · /cron add <natural language> to add · /cron rm <id> to remove\n" +
       "• /remember <text> — save to persistent memory (survives /new)\n" +
       "• /memory — view memory · /memory clear to wipe\n" +
-      "• /reserve — retry at usage-limit reset time · /reserve <msg> for a different message · /reserve rm to cancel\n" +
+      "• /reserve — show retry queue status at usage-limit reset · /reserve rm to cancel\n" +
       "• /restart — restart the bot (after a syntax check)\n" +
       "• /status — bot status & version\n" +
       "• /model — view / switch the model\n" +
@@ -151,6 +152,11 @@ const STR = {
     compactFail: (m) => `⚠️ Compact failed: ${m}`,
     compactNoSession: "No active session to compact. Just send a message to start one.",
     autoCompact: "🗜️ Auto-compacted context (conversation was getting long).",
+    planUsage: "Usage: `/plan <request>` — e.g. `/plan add input validation to the signup form`",
+    planApprove: "✅ Proceed",
+    planCancel: "❌ Cancel",
+    planCancelled: "❌ Plan cancelled. No changes were made.",
+    planNoPending: "No pending plan to approve (it may have expired after /new). Send /plan again.",
     testFallbackDisabled: "⚠️ Ollama fallback is not enabled. Set `\"ollamaFallback\": true` in config.json.",
     testFallbackFail: (m) => `⚠️ Ollama test failed: ${m}`,
     ollamaOn: "🌙 Ollama mode on. Messages will now go to Ollama. Your Claude session is preserved.",
@@ -221,12 +227,13 @@ const STR = {
       "• 그냥 메시지를 보내면 Claude가 프로젝트에서 작업합니다.\n" +
       "• /new — 대화 맥락 초기화 (새 세션)\n" +
       "• /compact — 컨텍스트 압축 (세션 유지, 공간 확보)\n" +
+      "• /plan <요청> — 계획만 세우기 (편집 없음) → 승인/취소로 실제 실행\n" +
       "• /ollama — Ollama 채팅 모드 토글 (Claude 우회, 로컬 LLM 사용)\n" +
       "• /stop — 진행 중인 작업 중단 · /stop --reset 으로 세션도 되돌리기\n" +
       "• /cron — 예약 작업 보기 · /cron add <자연어>로 추가 · /cron rm <번호>로 삭제\n" +
       "• /remember <내용> — 퍼시스턴트 메모리에 저장 (/new 로 초기화해도 유지)\n" +
       "• /memory — 메모리 보기 · /memory clear 로 삭제\n" +
-      "• /reserve — 한도 리셋 시 재시도 예약 · /reserve <다른 메시지> 로 내용 변경 · /reserve rm 으로 취소\n" +
+      "• /reserve — 한도 리셋 시 대기열 상태 확인 · /reserve rm 으로 취소\n" +
       "• /restart — 봇 재시작 (문법 검사 후 안전하게)\n" +
       "• /status — 봇 상태·버전 보기\n" +
       "• /model — 모델 보기·전환\n" +
@@ -294,6 +301,11 @@ const STR = {
     compactFail: (m) => `⚠️ compact 실패: ${m}`,
     compactNoSession: "압축할 활성 세션이 없습니다. 메시지를 보내 세션을 시작하세요.",
     autoCompact: "🗜️ 대화가 길어져 컨텍스트를 자동 압축했습니다.",
+    planUsage: "사용법: `/plan <요청>` — 예: `/plan 회원가입 폼에 입력값 검증 추가해줘`",
+    planApprove: "✅ 진행",
+    planCancel: "❌ 취소",
+    planCancelled: "❌ 계획을 취소했습니다. 아무 변경도 없습니다.",
+    planNoPending: "승인할 계획이 없습니다 (/new 이후 만료됐을 수 있음). /plan 을 다시 보내세요.",
     contextTooLong: "⚠️ 프롬프트가 너무 깁니다. `/compact` 로 컨텍스트를 압축하거나 `/new` 로 새 세션을 시작하세요.",
     testFallbackDisabled: "⚠️ Ollama 폴백이 비활성화 상태입니다. config.json에 `\"ollamaFallback\": true` 를 추가하세요.",
     testFallbackFail: (m) => `⚠️ Ollama 테스트 실패: ${m}`,
@@ -314,6 +326,7 @@ const COMMANDS = {
   en: [
     { command: "new", description: "Reset context (new session)" },
     { command: "compact", description: "Compress context to free up space (keeps session)" },
+    { command: "plan", description: "Plan only (no edits), then approve/cancel to run for real" },
     { command: "ollama", description: "Toggle Ollama chat mode (bypass Claude, use local LLM)" },
     { command: "stop", description: "Stop the current task (--reset to roll back session)" },
     { command: "remember", description: "Save to persistent memory (survives /new)" },
@@ -329,6 +342,7 @@ const COMMANDS = {
   ko: [
     { command: "new", description: "대화 맥락 초기화 (새 세션)" },
     { command: "compact", description: "컨텍스트 압축 (세션 유지, 공간 확보)" },
+    { command: "plan", description: "계획만 세우기 (편집 없음) → 승인/취소로 실제 실행" },
     { command: "ollama", description: "Ollama 채팅 모드 토글 (Claude 우회, 로컬 LLM)" },
     { command: "stop", description: "작업 중단 (--reset 으로 세션 되돌리기)" },
     { command: "remember", description: "퍼시스턴트 메모리에 저장 (/new 후에도 유지)" },
@@ -512,19 +526,30 @@ function mdToTelegramHtml(md) {
   return out.join("\n").replace(/ CB(\d+) /g, (_, i) => codeBlocks[Number(i)]);
 }
 
-async function send(chatId, text) {
-  for (const c of chunks(text)) {
-    const r = await tg("sendMessage", {
+// opts.replyMarkup: 인라인 키보드 — 여러 청크로 나뉘면 마지막 청크에만 붙음.
+// 반환값: 마지막으로 보낸 메시지의 message_id (버튼 클릭 후 편집용, 실패 시 null).
+async function send(chatId, text, opts = {}) {
+  const cs = [...chunks(text)];
+  let lastId = null;
+  for (let i = 0; i < cs.length; i++) {
+    const isLast = i === cs.length - 1;
+    const body = {
       chat_id: chatId,
-      text: mdToTelegramHtml(c),
+      text: mdToTelegramHtml(cs[i]),
       parse_mode: "HTML",
       disable_web_page_preview: true,
-    });
+    };
+    if (isLast && opts.replyMarkup) body.reply_markup = opts.replyMarkup;
+    let r = await tg("sendMessage", body);
     // If our HTML is malformed for some edge case, resend as plain text.
     if (!r || r.ok === false) {
-      await tg("sendMessage", { chat_id: chatId, text: c, disable_web_page_preview: true });
+      const plain = { chat_id: chatId, text: cs[i], disable_web_page_preview: true };
+      if (isLast && opts.replyMarkup) plain.reply_markup = opts.replyMarkup;
+      r = await tg("sendMessage", plain);
     }
+    if (r?.ok) lastId = r.result?.message_id;
   }
+  return lastId;
 }
 
 // ── Claude 에러 분류 ──────────────────────────────────────────────────────
@@ -572,12 +597,33 @@ function classifyClaudeError(raw, code) {
   return `Execution error (exit ${code}):\n${raw}`;
 }
 
+// ── 커스텀 명령어 스크립트 실행 ──────────────────────────────────────────
+function runCustomCommand(run, args) {
+  return new Promise((resolve) => {
+    const cmd = args ? `${run} ${args}` : run;
+    const child = spawn(cmd, [], {
+      shell: true,
+      cwd: cfg.projectDir,
+      env: { ...process.env, ...(cfg.env || {}) },
+    });
+    let out = "", err = "";
+    child.stdout.on("data", (d) => (out += d));
+    child.stderr.on("data", (d) => (err += d));
+    child.on("close", (code) => {
+      const text = (out + (err ? `\n[stderr]\n${err}` : "")).trim() || "(no output)";
+      resolve({ ok: code === 0, text, code });
+    });
+    child.on("error", (e) => resolve({ ok: false, text: e.message, code: -1 }));
+    setTimeout(() => { try { child.kill(); } catch {} resolve({ ok: false, text: "timeout (60s)", code: -1 }); }, 60_000);
+  });
+}
+
 // ── Claude 실행 ───────────────────────────────────────────────────────────
 function runClaude(prompt, sessionId, opts = {}) {
   return new Promise((resolve) => {
     const args = [
       "--output-format", "json",
-      "--permission-mode", cfg.permissionMode || "acceptEdits",
+      "--permission-mode", opts.permissionMode || cfg.permissionMode || "acceptEdits",
     ];
     const model = state.model || cfg.model; // /model 로 바꾸면 state.model 우선
     const brevity =
@@ -939,8 +985,120 @@ let currentTyping = null;   // 타이핑 인터벌 (/stop 시 정리용)
 let prevSessionId;          // /stop --reset 복원 대상
 let stopping = false;       // /stop 처리 중 오류 메시지 억제 플래그
 let rateLimitUntil = null;  // 레이트 리밋 활성 시 리셋 Date — 이 시간까지 메시지를 큐에 쌓음
+const pendingPlans = new Map(); // chatId → { sessionId, messageId } — /plan 승인 대기
+const PLAN_PROCEED_PROMPT = "Proceed with the plan you just approved above. Implement it now.";
 let rateLimitTimer = null;  // 리셋 시간에 큐를 드레인하는 타이머
 
+// runClaude 결과를 답장으로 변환 — 폴백/큐잉/자동 컴팩션 처리. handle()과 /plan 승인 실행이 공유.
+async function replyWithClaudeResult(chatId, l, prompt, msg, res, started) {
+  const secs = Math.round((Date.now() - started) / 1000);
+  if (!res.ok) {
+    // Ollama 폴백: 레이트리밋·크레딧 에러이고 ollamaFallback 켜져 있으면 Ollama로 재시도
+    if (cfg.ollamaFallback && res.canFallback && !stopping) {
+      try {
+        const oRes = await runOllama(prompt, l);
+        if (oRes.ok) { await send(chatId, oRes.text); return; }
+      } catch {}
+    }
+    // 리셋 시간을 알면 현재 메시지를 큐 앞에 다시 넣고 타이머 설정
+    let autoRetryMsg = "";
+    if (res.resetAt && !stopping) {
+      msgQueue.unshift({ msg, receivedAt: Date.now() });
+      rateLimitUntil = res.resetAt;
+      if (rateLimitTimer) clearTimeout(rateLimitTimer);
+      rateLimitTimer = setTimeout(() => {
+        rateLimitTimer = null;
+        rateLimitUntil = null;
+        if (msgQueue.length > 0) handle(drainQueue());
+      }, Math.max(res.resetAt - Date.now(), 1000));
+      const timeStr = res.resetAt.toLocaleTimeString(l === "ko" ? "ko-KR" : "en-US", { hour: "2-digit", minute: "2-digit" });
+      autoRetryMsg = "\n\n" + t(l, "reserveAuto", timeStr);
+    }
+    const errMsg = res.text === "contextTooLong" ? t(l, "contextTooLong") : `⚠️ ${res.text}${autoRetryMsg}`;
+    if (!stopping) await send(chatId, errMsg);
+  } else {
+    const footer = `\n\n— ${secs}s${res.cost ? ` · $${res.cost.toFixed(4)}` : ""}`;
+    if (!stopping) await send(chatId, res.text + footer);
+    // 자동 컴팩션: cache_read_input_tokens 가 임계값 초과 시 자동 /compact
+    const compactThreshold = cfg.autoCompactThreshold ?? 100000;
+    if (compactThreshold > 0 && res.cacheTokens > compactThreshold && state.sessionId && !stopping) {
+      try {
+        const cr = await runClaude("/compact", state.sessionId);
+        if (cr.sessionId) { state.sessionId = cr.sessionId; saveState(state); }
+        if (cr.ok !== false) await send(chatId, t(l, "autoCompact"));
+      } catch {}
+    }
+  }
+}
+
+// /plan 승인 후 실행 — busy 락·타이핑 표시를 handle()과 동일한 패턴으로 자체 처리.
+async function runApprovedPlan(chatId, l) {
+  const pending = pendingPlans.get(chatId);
+  pendingPlans.delete(chatId);
+  // /new 등으로 세션이 바뀌었으면 이 계획은 더 이상 유효하지 않음
+  if (!pending || pending.sessionId !== state.sessionId) {
+    await send(chatId, t(l, "planNoPending"));
+    return;
+  }
+  if (busy) {
+    msgQueue.push({ msg: { chat: { id: chatId }, text: PLAN_PROCEED_PROMPT }, receivedAt: Date.now() });
+    await send(chatId, t(l, "queued", msgQueue.length));
+    return;
+  }
+  if (checkLocalLock()) {
+    await send(chatId, t(l, "localBusy"));
+    return;
+  }
+  busy = true;
+  await tg("sendChatAction", { chat_id: chatId, action: "typing" });
+  const started = Date.now();
+  currentTyping = setInterval(
+    () => tg("sendChatAction", { chat_id: chatId, action: "typing" }).catch(() => {}),
+    5000,
+  );
+  const syntheticMsg = { chat: { id: chatId }, text: PLAN_PROCEED_PROMPT };
+  try {
+    prevSessionId = state.sessionId;
+    const res = await runClaude(PLAN_PROCEED_PROMPT, pending.sessionId, { modelHint: true, trackChild: true, injectMemory: true });
+    if (res.sessionId) {
+      state.sessionId = res.sessionId;
+      saveState(state);
+    }
+    await replyWithClaudeResult(chatId, l, PLAN_PROCEED_PROMPT, syntheticMsg, res, started);
+  } catch (e) {
+    if (!stopping) await send(chatId, t(l, "botError", e.message));
+  } finally {
+    clearInterval(currentTyping);
+    currentTyping = null;
+    stopping = false;
+    busy = false;
+    if (msgQueue.length > 0 && !rateLimitUntil) setImmediate(() => handle(drainQueue()));
+  }
+}
+
+// 텔레그램 인라인 버튼(✅/❌) 클릭 처리
+async function handleCallback(cq) {
+  const chatId = cq.message?.chat?.id;
+  if (!chatId || !allowedIds.includes(String(chatId))) {
+    await tg("answerCallbackQuery", { callback_query_id: cq.id }).catch(() => {});
+    return;
+  }
+  const l = langOf({ from: cq.from });
+  await tg("answerCallbackQuery", { callback_query_id: cq.id }).catch(() => {});
+  // 중복 클릭 방지 — 원본 메시지의 버튼 제거
+  tg("editMessageReplyMarkup", {
+    chat_id: chatId,
+    message_id: cq.message.message_id,
+    reply_markup: { inline_keyboard: [] },
+  }).catch(() => {});
+  if (cq.data === "plan:yes") {
+    runApprovedPlan(chatId, l).catch((e) => console.error("Plan approval error:", e.message));
+  } else if (cq.data === "plan:no") {
+    pendingPlans.delete(chatId);
+    await send(chatId, t(l, "planCancelled"));
+  }
+}
+
 async function handle(msg) {
   const chatId = msg.chat?.id;
   if (!chatId) return;
@@ -1126,6 +1284,22 @@ async function handle(msg) {
     return;
   }
 
+  // 커스텀 명령어 (config.commands) — Claude와 독립 실행
+  if (text.startsWith("/")) {
+    const cmdName = text.slice(1).split(" ")[0];
+    const def = (cfg.commands || {})[cmdName];
+    if (def) {
+      const run = typeof def === "object" ? def.run : null;
+      if (run) {
+        const args = text.length > cmdName.length + 1 ? text.slice(cmdName.length + 2) : "";
+        const res = await runCustomCommand(run, args || undefined);
+        const out = res.text.length > 4000 ? res.text.slice(0, 3990) + "\n…(truncated)" : res.text;
+        await send(chatId, `${res.ok ? "" : "⚠️ "}${out}`);
+        return;
+      }
+    }
+  }
+
   if (busy) {
     msgQueue.push({ msg, receivedAt: Date.now() });
     await send(chatId, t(l, "queued", msgQueue.length));
@@ -1148,6 +1322,32 @@ async function handle(msg) {
   );
 
   try {
+    // /plan <요청> — permission-mode를 강제로 plan으로 실행해 편집 없이 계획만 받고,
+    // 승인 버튼을 눌러야 실제 permissionMode로 이어서 실행 (runApprovedPlan).
+    if (text === "/plan" || text.startsWith("/plan ")) {
+      const planReq = text.slice(5).trim();
+      if (!planReq) { await send(chatId, t(l, "planUsage")); return; }
+      prevSessionId = state.sessionId;
+      const res = await runClaude(planReq, state.sessionId, { permissionMode: "plan", modelHint: true, trackChild: true, injectMemory: true });
+      if (res.sessionId) {
+        state.sessionId = res.sessionId;
+        saveState(state);
+      }
+      if (!res.ok) {
+        await send(chatId, `⚠️ ${res.text}`);
+        return;
+      }
+      const messageId = await send(chatId, res.text, {
+        replyMarkup: {
+          inline_keyboard: [[
+            { text: t(l, "planApprove"), callback_data: "plan:yes" },
+            { text: t(l, "planCancel"), callback_data: "plan:no" },
+          ]],
+        },
+      });
+      pendingPlans.set(chatId, { sessionId: state.sessionId, messageId });
+      return;
+    }
     let prompt = text;
     if (msg._mediaGroup?.length) {
       const notes = [];
@@ -1187,44 +1387,7 @@ async function handle(msg) {
       state.sessionId = res.sessionId;
       saveState(state);
     }
-    const secs = Math.round((Date.now() - started) / 1000);
-    if (!res.ok) {
-      // Ollama 폴백: 레이트리밋·크레딧 에러이고 ollamaFallback 켜져 있으면 Ollama로 재시도
-      if (cfg.ollamaFallback && res.canFallback && !stopping) {
-        try {
-          const oRes = await runOllama(prompt, l);
-          if (oRes.ok) { await send(chatId, oRes.text); return; }
-        } catch {}
-      }
-      // 리셋 시간을 알면 현재 메시지를 큐 앞에 다시 넣고 타이머 설정
-      let autoRetryMsg = "";
-      if (res.resetAt && !stopping) {
-        msgQueue.unshift({ msg, receivedAt: Date.now() });
-        rateLimitUntil = res.resetAt;
-        if (rateLimitTimer) clearTimeout(rateLimitTimer);
-        rateLimitTimer = setTimeout(() => {
-          rateLimitTimer = null;
-          rateLimitUntil = null;
-          if (msgQueue.length > 0) handle(drainQueue());
-        }, Math.max(res.resetAt - Date.now(), 1000));
-        const timeStr = res.resetAt.toLocaleTimeString(l === "ko" ? "ko-KR" : "en-US", { hour: "2-digit", minute: "2-digit" });
-        autoRetryMsg = "\n\n" + t(l, "reserveAuto", timeStr);
-      }
-      const errMsg = res.text === "contextTooLong" ? t(l, "contextTooLong") : `⚠️ ${res.text}${autoRetryMsg}`;
-      if (!stopping) await send(chatId, errMsg);
-    } else {
-      const footer = `\n\n— ${secs}s${res.cost ? ` · $${res.cost.toFixed(4)}` : ""}`;
-      if (!stopping) await send(chatId, res.text + footer);
-      // 자동 컴팩션: cache_read_input_tokens 가 임계값 초과 시 자동 /compact
-      const compactThreshold = cfg.autoCompactThreshold ?? 100000;
-      if (compactThreshold > 0 && res.cacheTokens > compactThreshold && state.sessionId && !stopping) {
-        try {
-          const cr = await runClaude("/compact", state.sessionId);
-          if (cr.sessionId) { state.sessionId = cr.sessionId; saveState(state); }
-          if (cr.ok !== false) await send(chatId, t(l, "autoCompact"));
-        } catch {}
-      }
-    }
+    await replyWithClaudeResult(chatId, l, prompt, msg, res, started);
   } catch (e) {
     if (!stopping) await send(chatId, t(l, "botError", e.message));
   } finally {
@@ -1284,9 +1447,14 @@ async function main() {
   }
   // 텔레그램 명령어 자동완성(/ 입력 시 뜨는 메뉴) 등록. 직접 파싱과 별개로 한 번 알려줘야 함.
   // 기본 목록(BOT_LANG) + 한국어 변형(language_code: ko) → ko 클라이언트는 한국어, 그 외 기본.
-  tg("setMyCommands", { commands: COMMANDS[BOT_LANG] || COMMANDS.en }).catch(() => {});
+  // config.commands 에 정의된 커스텀 명령어도 목록에 추가.
+  const customCmdEntries = Object.entries(cfg.commands || {}).map(([name, def]) => ({
+    command: name,
+    description: (typeof def === "object" ? (def.description || name) : name).slice(0, 256),
+  }));
+  tg("setMyCommands", { commands: [...(COMMANDS[BOT_LANG] || COMMANDS.en), ...customCmdEntries] }).catch(() => {});
   if (!FORCE_LANG) {
-    tg("setMyCommands", { commands: COMMANDS.ko, language_code: "ko" }).catch(() => {});
+    tg("setMyCommands", { commands: [...COMMANDS.ko, ...customCmdEntries], language_code: "ko" }).catch(() => {});
   }
 
   // 시작 시 밀린 메시지 건너뛰기
@@ -1310,6 +1478,7 @@ async function main() {
       for (const upd of res.result) {
         offset = upd.update_id + 1;
         if (upd.message) dispatch(upd.message);
+        else if (upd.callback_query) handleCallback(upd.callback_query).catch((e) => console.error("Callback error:", e.message));
       }
     } catch (e) {
       console.error("Polling error:", e.message);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-telegram-bot",
-  "version": "0.3.33",
+  "version": "0.3.36",
   "description": "Drive Claude Code from Telegram — messages run headless `claude -p` in a project dir and replies come back to the chat. Zero dependencies.",
   "type": "module",
   "bin": {