axmap-cli 1.9.0 → 1.10.0

package/src/external-console.mts

@@ -7,7 +7,7 @@ import { spawnSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
 import { bridgeHome, repoKey, readJSON, writeJSON } from './bridge.mjs'
 import { nativeConsoleHelper } from './windows-console.mjs'
-import type { SessionRecord, RequestRecord, ConsoleSnapshot, HookInput, TranscriptEntry } from './session-types.mjs'
+import type { SessionRecord, RequestRecord, ConsoleSnapshot, HookInput, TranscriptEntry, SessionState } from './session-types.mjs'
 
 const helper = fileURLToPath(new URL('../tools/windows-console.ps1', import.meta.url))
 export function consoleCall(pid: number, action?: 'snapshot' | 'send', payload?: Record<string, unknown>): ConsoleSnapshot
@@ -20,19 +20,20 @@ export function consoleCall(pid: number, action = 'snapshot', payload: Record<st
     '-File', helper, '-TargetPid', String(pid), '-Action', action], {
     input: JSON.stringify(payload), encoding: 'utf8', windowsHide: true, timeout: 8000, maxBuffer: 1024 * 1024,
   })
-  let data: (Omit<Partial<ConsoleSnapshot>, 'ignored'> & { error?: string; ignored?: boolean }) | undefined
+  let data: (Omit<Partial<ConsoleSnapshot>, 'ignored'> & { error?: string; ignored?: boolean; notDelivered?: boolean }) | undefined
   try { data = JSON.parse(r.stdout) } catch { /* report the underlying failure */ }
-  if (r.error || r.status !== 0 || data?.error || !data) throw new Error(data?.error || r.error?.message || r.stderr?.trim() || '기존 콘솔 연결 실패')
+  if (r.error || r.status !== 0 || data?.error || !data) throw Object.assign(new Error(data?.error || r.error?.message || r.stderr?.trim() || '기존 콘솔 연결 실패'),
+    { notDelivered: !r.error && data?.notDelivered === true })
   if (action === 'ancestor' && data.ignored) return { ignored: true }
   if (typeof data.pid !== 'number' || typeof data.startedAt !== 'string' || (action !== 'ancestor' && typeof data.screen !== 'string')) throw new Error('기존 콘솔 응답 형식이 올바르지 않습니다.')
   return data as ConsoleSnapshot
 }
-function identityID({ pid, startedAt }: Pick<ConsoleSnapshot, 'pid' | 'startedAt'>): string {
-  const hex = createHash('sha256').update(`agy-console:${pid}:${startedAt}`).digest('hex')
+function identityID({ pid, startedAt, provider = 'agy' }: Pick<ConsoleSnapshot, 'pid' | 'startedAt' | 'provider'>): string {
+  const hex = createHash('sha256').update(`${provider}-console:${pid}:${startedAt}`).digest('hex')
   return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-4${hex.slice(13, 16)}-a${hex.slice(17, 20)}-${hex.slice(20, 32)}`
 }
 const target = (id: string) => path.join(bridgeHome(), 'sessions', `${id}.json`)
-export function consoleIdle(screen: string): boolean {
+export function consoleIdle(screen: string, live?: ConsoleSnapshot): boolean {
   // Use the last input box only. Old answers may contain quoted prompt boxes.
   const borders = [...screen.matchAll(/^[─━]{10,}\r?$/gm)]
   if (borders.length < 2) return false
@@ -40,7 +41,15 @@ export function consoleIdle(screen: string): boolean {
   if (!top || !bottom) return false
   const input = screen.slice(top.index + top[0].length, bottom.index).trim()
   const footer = screen.slice(bottom.index + bottom[0].length)
-  return input === '>' && /\? for shortcuts/.test(footer) && !/esc to cancel/i.test(footer)
+  const empty = /^[>❯]$/.test(input)
+  // Claude paints a suggestion after the cursor in an otherwise empty editor.
+  // Require the cursor to remain at that editor's start, never just match text.
+  const placeholder = live?.provider === 'claude' && live.cursorX === 2 &&
+    /^[>❯]\s+Try "[^"\r\n]+"$/.test(input) &&
+    live.cursorRow === screen.slice(0, top.index + top[0].length).split('\n').length
+  const claudeEditor = live?.provider === 'claude' && live.cursorX === 2 &&
+    live.cursorRow === screen.slice(0, top.index + top[0].length).split('\n').length
+  return (empty || placeholder) && (live?.provider === 'claude' ? claudeEditor : /\? for shortcuts/.test(footer)) && !/esc to (cancel|interrupt)/i.test(footer)
 }
 export function attachConsole({ pid, cwd }: { pid: number; cwd: string }) {
   const live = consoleCall(pid)
@@ -48,17 +57,34 @@ export function attachConsole({ pid, cwd }: { pid: number; cwd: string }) {
   const previous = fs.existsSync(target(id)) ? readJSON<Partial<SessionRecord>>(target(id)) : {}
   const repo = repoKey(cwd)
   if (previous.repos && !previous.repos.includes(repo)) throw new Error('이 프로세스는 다른 저장소에 등록되어 있습니다.')
-  const idle = consoleIdle(live.screen)
-  const s: SessionRecord = { ...previous, id, provider: 'agy', transport: 'console', pid, startedAt: live.startedAt,
+  const idle = consoleIdle(live.screen, live)
+  const s: SessionRecord = { ...previous, id, provider: live.provider || 'agy', transport: 'console', pid, startedAt: live.startedAt,
     workspaces: previous.workspaces || [path.resolve(cwd)], repos: previous.repos || [repo],
     state: idle ? 'idle' : 'unknown', fullyIdle: idle, registeredAt: new Date().toISOString(), event: previous.event || 'attach' }
   writeJSON(target(id), s)
   return { id, provider: s.provider, transport: s.transport, pid, state: s.state, workspaces: s.workspaces }
 }
-export function registerExternalHook(input: HookInput, event: string) {
-  if (!['SessionStart', 'PreInvocation', 'Stop'].includes(event)) throw new Error('지원하지 않는 훅 이벤트입니다.')
+export function registerExternalHook(input: HookInput, event: string, provider = 'agy') {
+  if (!['SessionStart', 'PreInvocation', 'UserPromptSubmit', 'Stop', 'SessionEnd'].includes(event)) throw new Error('지원하지 않는 훅 이벤트입니다.')
   const identity = consoleCall(process.pid, 'ancestor')
   if (identity.ignored) return {}
+  if (identity.provider && identity.provider !== provider) return {}
+  if (provider === 'claude') {
+    const conversationId = input.session_id
+    const log = input.transcript_path
+    const home = process.env.AXMAP_CLAUDE_HOME || process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude')
+    const relative = typeof log === 'string' ? path.relative(path.join(home, 'projects'), path.resolve(log)) : '..'
+    if (!conversationId || !/^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i.test(conversationId) ||
+      !log || relative.startsWith('..') || path.isAbsolute(relative) || path.basename(log) !== `${conversationId}.jsonl` ||
+      !input.cwd || !path.isAbsolute(input.cwd)) throw new Error('Claude 훅의 대화 기록·작업 폴더 신원이 올바르지 않습니다.')
+    const id = identityID(identity)
+    const previous = fs.existsSync(target(id)) ? readJSON<Partial<SessionRecord>>(target(id)) : {}
+    const state = event === 'SessionEnd' ? 'closed' : event === 'Stop' || event === 'SessionStart' ? 'settling' : 'running'
+    writeJSON(target(id), { ...previous, ...identity, id, provider: 'claude', transport: 'console', conversationId,
+      transcript: path.resolve(log), workspaces: [path.resolve(input.cwd)], repos: [repoKey(input.cwd)],
+      state, fullyIdle: false, event, registeredAt: new Date().toISOString() })
+    return { id }
+  }
   const id = identityID(identity)
   const previous = fs.existsSync(target(id)) ? readJSON<Partial<SessionRecord>>(target(id)) : {}
   const workspaces = input.workspacePaths || previous.workspaces
@@ -77,7 +103,8 @@ export function registerExternalHook(input: HookInput, event: string) {
 export function externalStatus(session: Pick<SessionRecord, 'id'>) {
   const s = readJSON<SessionRecord>(target(session.id))
   const live = consoleCall(consolePID(s), 'snapshot', { startedAt: s.startedAt })
-  const state: 'idle' | 'unknown' = consoleIdle(live.screen) ? 'idle' : 'unknown'
+  const eligible = s.provider !== 'claude' || ['SessionStart', 'Stop'].includes(s.event || '')
+  const state: SessionState = s.state === 'closed' ? 'closed' : eligible && consoleIdle(live.screen, live) ? 'idle' : 'unknown'
   writeJSON(target(s.id), { ...readJSON<SessionRecord>(target(s.id)), state, fullyIdle: state === 'idle' })
   return { id: s.id, state }
 }
@@ -87,7 +114,8 @@ function consolePID(s: SessionRecord): number {
 }
 export function checkConsole(s: SessionRecord): ConsoleSnapshot {
   const live = consoleCall(consolePID(s), 'snapshot', { startedAt: s.startedAt })
-  if (!consoleIdle(live.screen)) throw new Error('상대 콘솔이 빈 입력창에서 대기 중이지 않습니다. 입력을 보내지 않았습니다.')
+  if (s.provider === 'claude' && !['SessionStart', 'Stop'].includes(s.event || '')) throw new Error('Claude가 실행·승인 대기 중입니다.')
+  if (!consoleIdle(live.screen, live)) throw new Error('상대 콘솔이 빈 입력창에서 대기 중이지 않습니다. 입력을 보내지 않았습니다.')
   return live
 }
 export function validateConsolePrompt(prompt: string, from: string): void {
@@ -95,6 +123,7 @@ export function validateConsolePrompt(prompt: string, from: string): void {
 }
 export function findConsoleTranscript(s: SessionRecord, request: RequestRecord): SessionRecord {
   if (s.transcript) return s
+  if (s.provider === 'claude') return s
   const brain = path.join(process.env.AXMAP_AGY_HOME || path.join(os.homedir(), '.gemini', 'antigravity-cli'), 'brain')
   if (!fs.existsSync(brain)) return s
   const marker = `[axMap request ${request.id}]`
@@ -122,7 +151,8 @@ export function submitConsole(s: SessionRecord, request: RequestRecord, prefligh
   // Bracketed paste preserves multiline prompts and prevents embedded Enter keys
   // from becoming separate submissions. Only the final CR submits the message.
   const text = `\x1b[200~[axMap request ${request.id}]\n요청자: ${request.from}\n${request.prompt.replace(/\r\n/g, '\n')}\x1b[201~\r`
-  consoleCall(consolePID(s), 'send', { startedAt: s.startedAt, expectedScreen: live.screen, text })
+  consoleCall(consolePID(s), 'send', { startedAt: s.startedAt, expectedScreen: live.screen,
+    expectedCursorX: live.cursorX, expectedCursorRow: live.cursorRow, text })
   writeJSON(target(s.id), { ...readJSON<SessionRecord>(target(s.id)), state: 'running', fullyIdle: false })
   return { accepted: true, pid: s.pid }
 }

package/src/managed-session.mjs

@@ -10,12 +10,16 @@ import { bridgeHome, hostPipe, repoKey, writeJSON } from './bridge.mjs';
 import { normalizeUsage, usageDelta } from './session-usage.mjs';
 import { errorMessage } from './session-types.mjs';
 import { connectCodexProxy } from './codex-connection.mjs';
+const CLAUDE_USAGE_KEYS = ['input_tokens', 'cache_creation_input_tokens', 'cache_read_input_tokens', 'output_tokens', 'thinking_tokens'];
 // 생존 확인(bridge.sessions)이 같은 이름을 보도록 한 곳에서 만든다.
 const pipeFor = hostPipe;
 const uuid = (value) => /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value || '');
-export async function startManagedSession({ provider, executable = provider, prefix = [], args = null, model, role = '', existingThreadId, socketPath, observeActive = false, cwd = process.cwd(), maxTokens = 100000, timeoutMs = 120000, onEvent = () => { } }) {
-    if (!['codex', 'agy'].includes(provider))
-        throw new Error('지원하는 세션은 codex 또는 agy입니다.');
+export async function startManagedSession({ provider, executable = provider, prefix = [], args = null, model, role = '', existingThreadId, socketPath, observeActive = false, permissionMode = 'default', cwd = process.cwd(), maxTokens = 100000, timeoutMs = 120000, onEvent = () => { } }) {
+    if (!['codex', 'agy', 'claude'].includes(provider))
+        throw new Error('지원하는 세션은 codex, agy 또는 claude입니다.');
+    // 읽기 전용이 기본이다(Codex 의 sandbox read-only 와 같은 자리). 고쳐도 되는 세션은 사람이 serve 할 때 고른다.
+    if (!['default', 'plan', 'acceptEdits'].includes(permissionMode))
+        throw new Error('claude 권한은 default, plan 또는 acceptEdits입니다.');
     if (!Number.isSafeInteger(maxTokens) || maxTokens < 1 || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1)
         throw new Error('양의 토큰/시간 한도가 필요합니다.');
     if (typeof role !== 'string' || role.length > 1000)
@@ -28,7 +32,26 @@ export async function startManagedSession({ provider, executable = provider, pre
         workspaces: [path.resolve(cwd)], repos: [repoKey(cwd)], state: 'starting', fullyIdle: false, hostPid: process.pid,
         registeredAt: new Date().toISOString(), usage: null, usageKnown: true, maxTokens };
     const jobs = new Map();
+    const queue = [];
+    const persistJob = (job) => writeJSON(path.join(bridgeHome(), 'jobs', `${job.id}.json`), job);
+    let draining = false;
+    const drain = () => {
+        if (closed || draining || pending || s.state !== 'idle' || !queue.length)
+            return;
+        draining = true;
+        const request = queue.shift();
+        jobs.delete(request.id);
+        void handle({ action: 'submit', token, request }).catch(e => {
+            const job = { id: request.id, to: id, state: 'failed', error: errorMessage(e), completedAt: new Date().toISOString() };
+            jobs.set(request.id, job);
+            persistJob(job);
+            emit({ event: 'result', request: job });
+        }).finally(() => { draining = false; if (!pending)
+            setImmediate(drain); });
+    };
     let attachedUsageOrigin = null;
+    // Claude Code 는 실행마다 그 실행분만 준다. 다른 provider 처럼 누적값으로 다루려고 여기서 더한다.
+    let claudeTotals = null;
     let initialThreadState = 'idle';
     const calls = new Map();
     let child, sequence = 0, pending = null, closed = false, buffer = '', stderr = '', turnTimer;
@@ -67,12 +90,14 @@ export async function startManagedSession({ provider, executable = provider, pre
                 attachedUsageOrigin = usage;
         }
         s.usageKnown = usage !== null;
+        persistJob(pending);
         emit({ event: 'result', request: { ...pending } });
         pending = null;
         s.state = 'idle';
         s.fullyIdle = true;
         delete s.pendingApproval;
         save();
+        setImmediate(drain);
     };
     const shutdown = (reason) => {
         if (closed)
@@ -80,6 +105,11 @@ export async function startManagedSession({ provider, executable = provider, pre
         finish('unknown', undefined, reason);
         closed = true;
         clearTimeout(turnTimer);
+        for (const request of queue.splice(0)) {
+            const job = { id: request.id, to: id, state: 'failed', error: reason, completedAt: new Date().toISOString() };
+            jobs.set(request.id, job);
+            persistJob(job);
+        }
         for (const c of calls.values()) {
             clearTimeout(c.timer);
             c.reject(new Error(reason));
@@ -129,31 +159,49 @@ export async function startManagedSession({ provider, executable = provider, pre
         }
         if (message.action !== 'submit')
             throw new Error('지원하지 않는 로컬 세션 요청입니다.');
+        // 🔴 여기부터 접수(pending) 전까지의 거절은 모델을 부르지 않은 확정 거절이다. refused 를 붙여 보낸 쪽이
+        //    unknown 이 아니라 failed 로 기록하게 한다 — unknown 으로 남으면 그 세션의 다음 요청이 「이전 요청 미확정」으로
+        //    영영 막힌다(토큰 한도에 걸린 Claude 세션에 보낸 요청이 실제로 그렇게 막혔다).
+        const refuse = (text) => Object.assign(new Error(text), { refused: true });
         if (jobs.has(message.request?.id))
-            throw new Error('이미 접수한 요청 ID입니다. 다시 전송하지 않았습니다.');
+            throw refuse('이미 접수한 요청 ID입니다. 다시 전송하지 않았습니다.');
+        const queuedRequest = message.request;
+        if (!uuid(queuedRequest?.id) || queuedRequest.to !== id || typeof queuedRequest.prompt !== 'string' || !queuedRequest.prompt.trim() || Buffer.byteLength(queuedRequest.prompt) > 32768)
+            throw refuse('요청 형식이 올바르지 않습니다.');
+        if (message.queueIfBusy && !closed && (pending || draining || queue.length || s.state === 'running' || s.state === 'awaiting_user')) {
+            if (queue.length >= 100)
+                throw refuse('명령 큐가 가득 찼습니다.');
+            const job = { id: queuedRequest.id, to: id, state: 'queued' };
+            persistJob(job);
+            jobs.set(job.id, job);
+            queue.push(queuedRequest);
+            emit({ event: 'queued', request: job });
+            return { accepted: true, queued: true, session: id, position: queue.length };
+        }
         if (closed || s.state !== 'idle' || pending)
-            throw new Error('세션이 대기 중이 아닙니다. 요청을 전달하지 않았습니다.');
+            throw refuse('세션이 대기 중이 아닙니다. 요청을 전달하지 않았습니다.');
         if (existingThreadId) {
             if (checkingSubmission)
-                throw new Error('다른 요청의 상태를 확인 중입니다.');
+                throw refuse('다른 요청의 상태를 확인 중입니다.');
             checkingSubmission = true;
             try {
                 const read = await rpc('thread/read', { threadId: existingThreadId });
                 if (closed || pending || read.thread.id !== existingThreadId || read.thread.status.type !== 'idle')
-                    throw new Error('기존 대화가 다른 작업 중입니다. 새 요청을 전달하지 않았습니다.');
+                    throw refuse('기존 대화가 다른 작업 중입니다. 새 요청을 전달하지 않았습니다.');
             }
             finally {
                 checkingSubmission = false;
             }
         }
         if (!s.usageKnown)
-            throw new Error('직전 요청의 사용량을 확인하지 못했습니다. 새 연결에서 예산을 확인하세요.');
+            throw refuse('직전 요청의 사용량을 확인하지 못했습니다. 새 연결에서 예산을 확인하세요.');
         if (s.usage && s.usage.totalTokens - (existingThreadId ? attachedUsageOrigin?.totalTokens ?? s.usage.totalTokens : 0) >= maxTokens)
-            throw new Error('세션 토큰 한도에 도달했습니다.');
+            throw refuse('세션 토큰 한도에 도달했습니다.');
         const request = message.request;
         if (!uuid(request?.id) || request.to !== id || typeof request.prompt !== 'string' || !request.prompt.trim() || Buffer.byteLength(request.prompt) > 32768)
-            throw new Error('요청 형식이 올바르지 않습니다.');
+            throw refuse('요청 형식이 올바르지 않습니다.');
         pending = { id: request.id, to: id, state: 'submitted', baseline: s.usage, baselineKnown: s.usageKnown && (!existingThreadId || !!s.usage), result: '' };
+        persistJob(pending);
         jobs.set(request.id, pending);
         s.state = 'running';
         s.fullyIdle = false;
@@ -162,6 +210,8 @@ export async function startManagedSession({ provider, executable = provider, pre
         turnTimer = setTimeout(() => shutdown('실행 시간 한도 초과. 완료 여부가 불명확하므로 자동 재시도하지 않습니다.'), timeoutMs);
         if (provider === 'agy')
             write({ event: 'user', message: { content: prompt } });
+        else if (provider === 'claude')
+            write({ type: 'user', message: { role: 'user', content: prompt } });
         else
             rpc('turn/start', { threadId: s.conversationId, input: [{ type: 'text', text: prompt }], ...(!existingThreadId ? { effort: 'low' } : {}) })
                 .then(r => { if (pending?.id === request.id)
@@ -185,7 +235,7 @@ export async function startManagedSession({ provider, executable = provider, pre
                 return;
             handled = true;
             try {
-                void handle(JSON.parse(input.slice(0, end))).then(result => socket.end(JSON.stringify({ result }) + '\n'), e => socket.end(JSON.stringify({ error: errorMessage(e) }) + '\n'));
+                void handle(JSON.parse(input.slice(0, end))).then(result => socket.end(JSON.stringify({ result }) + '\n'), e => socket.end(JSON.stringify({ error: errorMessage(e), ...(e?.refused ? { refused: true } : {}) }) + '\n'));
             }
             catch (e) {
                 socket.end(JSON.stringify({ error: errorMessage(e) }) + '\n');
@@ -198,7 +248,9 @@ export async function startManagedSession({ provider, executable = provider, pre
         fs.chmodSync(pipeFor(id), 0o600);
     save();
     const cliArgs = args || (provider === 'codex' ? ['app-server', '--stdio']
-        : ['--input-format', 'stream-json', '--output-format', 'stream-json', '--disable-slash-commands', '--effort', 'low', ...(model ? ['--model', model] : [])]);
+        : provider === 'claude' ? ['-p', '--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose',
+            '--permission-mode', permissionMode, ...(model ? ['--model', model] : [])]
+            : ['--input-format', 'stream-json', '--output-format', 'stream-json', '--disable-slash-commands', '--effort', 'low', ...(model ? ['--model', model] : [])]);
     child = existingThreadId ? connectCodexProxy({ executable, prefix, socketPath: socketPath, cwd }) : spawn(executable, [...prefix, ...cliArgs], { cwd, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'],
         env: { ...process.env, AXMAP_AGENT: `${provider}-${id.slice(0, 8)}`, AXMAP_SESSION: id } });
     child.stdin.on('error', e => shutdown(e.message));
@@ -220,6 +272,30 @@ export async function startManagedSession({ provider, executable = provider, pre
                 continue;
             try {
                 const m = JSON.parse(line);
+                if (provider === 'claude') {
+                    const c = m;
+                    // init 은 실행마다 온다. 첫 init 의 대화 ID 를 붙잡고, 바뀌면 다른 대화에 답이 섞인 것이라 닫는다.
+                    if (c.type === 'system' && c.subtype === 'init') {
+                        if (!s.conversationId) {
+                            s.conversationId = c.session_id;
+                            save();
+                            emit({ event: 'conversation', conversationId: s.conversationId });
+                        }
+                        else if (c.session_id !== s.conversationId)
+                            throw new Error('claude 대화 ID가 바뀌었습니다.');
+                    }
+                    if (c.type === 'result' && pending) {
+                        if (c.session_id !== s.conversationId)
+                            throw new Error('claude 대화 ID가 바뀌었습니다.');
+                        const turn = c.usage ? { ...c.usage, thinking_tokens: c.usage.output_tokens_details?.thinking_tokens ?? 0 } : null;
+                        const known = !!turn && CLAUDE_USAGE_KEYS.every(k => Number.isSafeInteger(turn[k]) && turn[k] >= 0);
+                        if (known)
+                            claudeTotals = Object.fromEntries(CLAUDE_USAGE_KEYS.map(k => [k, (claudeTotals?.[k] || 0) + turn[k]]));
+                        const ok = c.subtype === 'success' && !c.is_error;
+                        finish(ok ? 'completed' : 'failed', c.result, ok ? undefined : String(c.result || c.subtype), known ? claudeTotals : null);
+                    }
+                    continue;
+                }
                 if (provider === 'agy') {
                     if (m.event === 'init') {
                         s.conversationId = m.conversation_id;
@@ -264,6 +340,7 @@ export async function startManagedSession({ provider, executable = provider, pre
                     s.state = status?.type === 'active' ? 'running' : status?.type === 'idle' ? 'idle' : 'unknown';
                     s.fullyIdle = s.state === 'idle';
                     save();
+                    setImmediate(drain);
                 }
                 if (m.method === 'thread/tokenUsage/updated') {
                     if (pending)
@@ -317,8 +394,20 @@ export async function startManagedSession({ provider, executable = provider, pre
             s.state = initialThreadState === 'active' ? 'running' : 'idle';
             s.fullyIdle = s.state === 'idle';
             save();
+            setImmediate(drain);
             emit({ event: 'ready', conversationId: s.conversationId });
         }
+        else if (provider === 'claude') {
+            // Claude Code 는 첫 입력이 올 때까지 아무것도 내보내지 않는다. 프로세스가 떴으면 대기로 둔다 —
+            // 대화 ID 는 첫 실행의 init 에서 정해진다. 기다리는 동안 모델은 부르지 않는다.
+            await new Promise((resolve, reject) => { child.once('spawn', () => resolve()); child.once('error', reject); });
+            if (closed)
+                throw new Error(`claude 시작 실패: ${stderr.slice(-1000)}`);
+            s.state = 'idle';
+            s.fullyIdle = true;
+            save();
+            emit({ event: 'ready', conversationId: null });
+        }
         else {
             const deadline = Date.now() + 30000;
             while (s.state === 'starting' && !closed && Date.now() < deadline)

package/src/managed-session.mts

@@ -11,7 +11,7 @@ import { errorMessage } from './session-types.mjs'
 import { connectCodexProxy } from './codex-connection.mjs'
 import type { ProviderProcess } from './codex-connection.mjs'
 import type { ChildProcessWithoutNullStreams } from 'node:child_process'
-import type { Provider, SessionRecord, RequestState, LocalMessage, JobRecord } from './session-types.mjs'
+import type { Provider, SessionRecord, RequestState, LocalMessage, JobRecord, LocalRequest } from './session-types.mjs'
 import type { Usage } from './session-types.mjs'
 
 interface ManagedSessionOptions {
@@ -19,6 +19,7 @@ interface ManagedSessionOptions {
   cwd?: string; maxTokens?: number; timeoutMs?: number; onEvent?: (event: Record<string, unknown>) => void
   existingThreadId?: string; socketPath?: string
   observeActive?: boolean
+  permissionMode?: string
 }
 interface ProviderMessage {
   id?: string | number; method?: string; event?: string; conversation_id?: string
@@ -30,14 +31,19 @@ interface ProviderMessage {
   }
 }
 interface AgyResult { conversation_id: string; status: string; response?: unknown; error?: string; usage?: unknown }
+interface ClaudeMessage { type?: string; subtype?: string; session_id?: string; result?: unknown; is_error?: boolean
+  usage?: { output_tokens_details?: { thinking_tokens?: number }; [key: string]: unknown } }
+const CLAUDE_USAGE_KEYS = ['input_tokens', 'cache_creation_input_tokens', 'cache_read_input_tokens', 'output_tokens', 'thinking_tokens'] as const
 
 // 생존 확인(bridge.sessions)이 같은 이름을 보도록 한 곳에서 만든다.
 const pipeFor = hostPipe
 const uuid = (value: string | undefined) => /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value || '')
 
 export async function startManagedSession({ provider, executable = provider, prefix = [], args = null, model, role = '', existingThreadId, socketPath, observeActive = false,
-  cwd = process.cwd(), maxTokens = 100000, timeoutMs = 120000, onEvent = () => {} }: ManagedSessionOptions) {
-  if (!['codex', 'agy'].includes(provider)) throw new Error('지원하는 세션은 codex 또는 agy입니다.')
+  permissionMode = 'default', cwd = process.cwd(), maxTokens = 100000, timeoutMs = 120000, onEvent = () => {} }: ManagedSessionOptions) {
+  if (!['codex', 'agy', 'claude'].includes(provider)) throw new Error('지원하는 세션은 codex, agy 또는 claude입니다.')
+  // 읽기 전용이 기본이다(Codex 의 sandbox read-only 와 같은 자리). 고쳐도 되는 세션은 사람이 serve 할 때 고른다.
+  if (!['default', 'plan', 'acceptEdits'].includes(permissionMode)) throw new Error('claude 권한은 default, plan 또는 acceptEdits입니다.')
   if (!Number.isSafeInteger(maxTokens) || maxTokens < 1 || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1) throw new Error('양의 토큰/시간 한도가 필요합니다.')
   if (typeof role !== 'string' || role.length > 1000) throw new Error('역할은 1000자 이하여야 합니다.')
   if (existingThreadId && (provider !== 'codex' || !uuid(existingThreadId) || !socketPath || model || args)) throw new Error('기존 Codex thread와 로컬 socket이 필요하며 모델·실행 인수를 바꾸지 않습니다.')
@@ -47,7 +53,22 @@ export async function startManagedSession({ provider, executable = provider, pre
     workspaces: [path.resolve(cwd)], repos: [repoKey(cwd)], state: 'starting', fullyIdle: false, hostPid: process.pid,
     registeredAt: new Date().toISOString(), usage: null, usageKnown: true, maxTokens }
   const jobs = new Map<string, JobRecord>()
+  const queue: LocalRequest[] = []
+  const persistJob = (job: JobRecord) => writeJSON(path.join(bridgeHome(), 'jobs', `${job.id}.json`), job)
+  let draining = false
+  const drain = () => {
+    if (closed || draining || pending || s.state !== 'idle' || !queue.length) return
+    draining = true
+    const request = queue.shift()!
+    jobs.delete(request.id)
+    void handle({ action: 'submit', token, request }).catch(e => {
+      const job: JobRecord = { id: request.id, to: id, state: 'failed', error: errorMessage(e), completedAt: new Date().toISOString() }
+      jobs.set(request.id, job); persistJob(job); emit({ event: 'result', request: job })
+    }).finally(() => { draining = false; if (!pending) setImmediate(drain) })
+  }
   let attachedUsageOrigin: Usage | null = null
+  // Claude Code 는 실행마다 그 실행분만 준다. 다른 provider 처럼 누적값으로 다루려고 여기서 더한다.
+  let claudeTotals: Record<string, number> | null = null
   let initialThreadState = 'idle'
   const calls = new Map<string | number, { resolve: (result: unknown) => void; reject: (reason: Error) => void; timer: NodeJS.Timeout }>()
   let child: ProviderProcess | undefined, sequence = 0, pending: JobRecord | null = null, closed = false, buffer = '', stderr = '', turnTimer: NodeJS.Timeout | undefined
@@ -73,13 +94,18 @@ export async function startManagedSession({ provider, executable = provider, pre
     delete pending.baselineKnown
     if (usage) { s.usage = usage; if (existingThreadId && !attachedUsageOrigin) attachedUsageOrigin = usage }
     s.usageKnown = usage !== null
+    persistJob(pending)
     emit({ event: 'result', request: { ...pending } })
-    pending = null; s.state = 'idle'; s.fullyIdle = true; delete s.pendingApproval; save()
+    pending = null; s.state = 'idle'; s.fullyIdle = true; delete s.pendingApproval; save(); setImmediate(drain)
   }
   const shutdown = (reason: string) => {
     if (closed) return
     finish('unknown', undefined, reason)
     closed = true; clearTimeout(turnTimer)
+    for (const request of queue.splice(0)) {
+      const job: JobRecord = { id: request.id, to: id, state: 'failed', error: reason, completedAt: new Date().toISOString() }
+      jobs.set(request.id, job); persistJob(job)
+    }
     for (const c of calls.values()) { clearTimeout(c.timer); c.reject(new Error(reason)) }
     calls.clear()
     s.state = 'closed'; s.fullyIdle = false; save()
@@ -112,25 +138,39 @@ export async function startManagedSession({ provider, executable = provider, pre
       delete s.pendingApproval; s.state = 'running'; save(); return { answered: true }
     }
     if (message.action !== 'submit') throw new Error('지원하지 않는 로컬 세션 요청입니다.')
-    if (jobs.has(message.request?.id)) throw new Error('이미 접수한 요청 ID입니다. 다시 전송하지 않았습니다.')
-    if (closed || s.state !== 'idle' || pending) throw new Error('세션이 대기 중이 아닙니다. 요청을 전달하지 않았습니다.')
+    // 🔴 여기부터 접수(pending) 전까지의 거절은 모델을 부르지 않은 확정 거절이다. refused 를 붙여 보낸 쪽이
+    //    unknown 이 아니라 failed 로 기록하게 한다 — unknown 으로 남으면 그 세션의 다음 요청이 「이전 요청 미확정」으로
+    //    영영 막힌다(토큰 한도에 걸린 Claude 세션에 보낸 요청이 실제로 그렇게 막혔다).
+    const refuse = (text: string) => Object.assign(new Error(text), { refused: true })
+    if (jobs.has(message.request?.id)) throw refuse('이미 접수한 요청 ID입니다. 다시 전송하지 않았습니다.')
+    const queuedRequest = message.request
+    if (!uuid(queuedRequest?.id) || queuedRequest.to !== id || typeof queuedRequest.prompt !== 'string' || !queuedRequest.prompt.trim() || Buffer.byteLength(queuedRequest.prompt) > 32768) throw refuse('요청 형식이 올바르지 않습니다.')
+    if (message.queueIfBusy && !closed && (pending || draining || queue.length || s.state === 'running' || s.state === 'awaiting_user')) {
+      if (queue.length >= 100) throw refuse('명령 큐가 가득 찼습니다.')
+      const job: JobRecord = { id: queuedRequest.id, to: id, state: 'queued' }
+      persistJob(job); jobs.set(job.id, job); queue.push(queuedRequest)
+      emit({ event: 'queued', request: job })
+      return { accepted: true, queued: true, session: id, position: queue.length }
+    }
+    if (closed || s.state !== 'idle' || pending) throw refuse('세션이 대기 중이 아닙니다. 요청을 전달하지 않았습니다.')
     if (existingThreadId) {
-      if (checkingSubmission) throw new Error('다른 요청의 상태를 확인 중입니다.')
+      if (checkingSubmission) throw refuse('다른 요청의 상태를 확인 중입니다.')
       checkingSubmission = true
       try {
         const read = await rpc<{ thread: { id: string; status: { type: string } } }>('thread/read', { threadId: existingThreadId })
-        if (closed || pending || read.thread.id !== existingThreadId || read.thread.status.type !== 'idle') throw new Error('기존 대화가 다른 작업 중입니다. 새 요청을 전달하지 않았습니다.')
+        if (closed || pending || read.thread.id !== existingThreadId || read.thread.status.type !== 'idle') throw refuse('기존 대화가 다른 작업 중입니다. 새 요청을 전달하지 않았습니다.')
       } finally { checkingSubmission = false }
     }
-    if (!s.usageKnown) throw new Error('직전 요청의 사용량을 확인하지 못했습니다. 새 연결에서 예산을 확인하세요.')
-    if (s.usage && s.usage.totalTokens - (existingThreadId ? attachedUsageOrigin?.totalTokens ?? s.usage.totalTokens : 0) >= maxTokens) throw new Error('세션 토큰 한도에 도달했습니다.')
+    if (!s.usageKnown) throw refuse('직전 요청의 사용량을 확인하지 못했습니다. 새 연결에서 예산을 확인하세요.')
+    if (s.usage && s.usage.totalTokens - (existingThreadId ? attachedUsageOrigin?.totalTokens ?? s.usage.totalTokens : 0) >= maxTokens) throw refuse('세션 토큰 한도에 도달했습니다.')
     const request = message.request
-    if (!uuid(request?.id) || request.to !== id || typeof request.prompt !== 'string' || !request.prompt.trim() || Buffer.byteLength(request.prompt) > 32768) throw new Error('요청 형식이 올바르지 않습니다.')
+    if (!uuid(request?.id) || request.to !== id || typeof request.prompt !== 'string' || !request.prompt.trim() || Buffer.byteLength(request.prompt) > 32768) throw refuse('요청 형식이 올바르지 않습니다.')
     pending = { id: request.id, to: id, state: 'submitted', baseline: s.usage, baselineKnown: s.usageKnown && (!existingThreadId || !!s.usage), result: '' }
-    jobs.set(request.id, pending); s.state = 'running'; s.fullyIdle = false; save()
+    persistJob(pending); jobs.set(request.id, pending); s.state = 'running'; s.fullyIdle = false; save()
     const prompt = `[axMap request ${request.id}]\n요청자: ${request.from || 'axmap'}\n${role ? `역할: ${role}\n` : ''}${request.prompt}`
     turnTimer = setTimeout(() => shutdown('실행 시간 한도 초과. 완료 여부가 불명확하므로 자동 재시도하지 않습니다.'), timeoutMs)
     if (provider === 'agy') write({ event: 'user', message: { content: prompt } })
+    else if (provider === 'claude') write({ type: 'user', message: { role: 'user', content: prompt } })
     else rpc<{ turn: { id: string } }>('turn/start', { threadId: s.conversationId, input: [{ type: 'text', text: prompt }], ...(!existingThreadId ? { effort: 'low' } : {}) })
       .then(r => { if (pending?.id === request.id) pending.turnId = r.turn.id })
       .catch(e => shutdown(e.message))
@@ -146,7 +186,7 @@ export async function startManagedSession({ provider, executable = provider, pre
       if (Buffer.byteLength(input) > 65536) return socket.destroy()
       const end = input.indexOf('\n'); if (end < 0) return
       handled = true
-      try { void handle(JSON.parse(input.slice(0, end))).then(result => socket.end(JSON.stringify({ result }) + '\n'), e => socket.end(JSON.stringify({ error: errorMessage(e) }) + '\n')) }
+      try { void handle(JSON.parse(input.slice(0, end))).then(result => socket.end(JSON.stringify({ result }) + '\n'), e => socket.end(JSON.stringify({ error: errorMessage(e), ...((e as { refused?: boolean })?.refused ? { refused: true } : {}) }) + '\n')) }
       catch (e) { socket.end(JSON.stringify({ error: errorMessage(e) }) + '\n') }
     })
   })
@@ -155,6 +195,8 @@ export async function startManagedSession({ provider, executable = provider, pre
   if (process.platform !== 'win32') fs.chmodSync(pipeFor(id), 0o600)
   save()
   const cliArgs = args || (provider === 'codex' ? ['app-server', '--stdio']
+    : provider === 'claude' ? ['-p', '--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose',
+      '--permission-mode', permissionMode, ...(model ? ['--model', model] : [])]
     : ['--input-format', 'stream-json', '--output-format', 'stream-json', '--disable-slash-commands', '--effort', 'low', ...(model ? ['--model', model] : [])])
   child = existingThreadId ? connectCodexProxy({ executable, prefix, socketPath: socketPath!, cwd }) : spawn(executable, [...prefix, ...cliArgs], { cwd, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'],
     env: { ...process.env, AXMAP_AGENT: `${provider}-${id.slice(0, 8)}`, AXMAP_SESSION: id } })
@@ -174,6 +216,23 @@ export async function startManagedSession({ provider, executable = provider, pre
       if (!line.trim()) continue
       try {
         const m = JSON.parse(line) as ProviderMessage
+        if (provider === 'claude') {
+          const c = m as unknown as ClaudeMessage
+          // init 은 실행마다 온다. 첫 init 의 대화 ID 를 붙잡고, 바뀌면 다른 대화에 답이 섞인 것이라 닫는다.
+          if (c.type === 'system' && c.subtype === 'init') {
+            if (!s.conversationId) { s.conversationId = c.session_id; save(); emit({ event: 'conversation', conversationId: s.conversationId }) }
+            else if (c.session_id !== s.conversationId) throw new Error('claude 대화 ID가 바뀌었습니다.')
+          }
+          if (c.type === 'result' && pending) {
+            if (c.session_id !== s.conversationId) throw new Error('claude 대화 ID가 바뀌었습니다.')
+            const turn: Record<string, unknown> | null = c.usage ? { ...c.usage, thinking_tokens: c.usage.output_tokens_details?.thinking_tokens ?? 0 } : null
+            const known = !!turn && CLAUDE_USAGE_KEYS.every(k => Number.isSafeInteger(turn[k]) && (turn[k] as number) >= 0)
+            if (known) claudeTotals = Object.fromEntries(CLAUDE_USAGE_KEYS.map(k => [k, (claudeTotals?.[k] || 0) + (turn![k] as number)]))
+            const ok = c.subtype === 'success' && !c.is_error
+            finish(ok ? 'completed' : 'failed', c.result, ok ? undefined : String(c.result || c.subtype), known ? claudeTotals : null)
+          }
+          continue
+        }
         if (provider === 'agy') {
           if (m.event === 'init') { s.conversationId = m.conversation_id; s.state = 'idle'; s.fullyIdle = true; save(); emit({ event: 'ready', conversationId: s.conversationId }) }
           if (m.event === 'result' && pending) {
@@ -199,7 +258,7 @@ export async function startManagedSession({ provider, executable = provider, pre
         if (m.method === 'thread/status/changed' && !pending) {
           const status = m.params?.status as { type?: string } | undefined
           s.state = status?.type === 'active' ? 'running' : status?.type === 'idle' ? 'idle' : 'unknown'
-          s.fullyIdle = s.state === 'idle'; save()
+          s.fullyIdle = s.state === 'idle'; save(); setImmediate(drain)
         }
         if (m.method === 'thread/tokenUsage/updated') {
           if (pending) pending.rawUsage = m.params?.tokenUsage?.total
@@ -231,8 +290,14 @@ export async function startManagedSession({ provider, executable = provider, pre
         ? { threadId: existingThreadId, excludeTurns: true }
         : { cwd: path.resolve(cwd), ...(model ? { model } : {}), sandbox: 'read-only', approvalPolicy: 'on-request' })
       if (existingThreadId && r.thread.id !== existingThreadId) throw new Error('기존 thread ID가 바뀌었습니다.')
-      s.conversationId = r.thread.id; s.model = r.model || model || null; s.state = initialThreadState === 'active' ? 'running' : 'idle'; s.fullyIdle = s.state === 'idle'; save()
+      s.conversationId = r.thread.id; s.model = r.model || model || null; s.state = initialThreadState === 'active' ? 'running' : 'idle'; s.fullyIdle = s.state === 'idle'; save(); setImmediate(drain)
       emit({ event: 'ready', conversationId: s.conversationId })
+    } else if (provider === 'claude') {
+      // Claude Code 는 첫 입력이 올 때까지 아무것도 내보내지 않는다. 프로세스가 떴으면 대기로 둔다 —
+      // 대화 ID 는 첫 실행의 init 에서 정해진다. 기다리는 동안 모델은 부르지 않는다.
+      await new Promise<void>((resolve, reject) => { child!.once('spawn', () => resolve()); child!.once('error', reject) })
+      if (closed) throw new Error(`claude 시작 실패: ${stderr.slice(-1000)}`)
+      s.state = 'idle'; s.fullyIdle = true; save(); emit({ event: 'ready', conversationId: null })
     } else {
       const deadline = Date.now() + 30000
       while (s.state === 'starting' && !closed && Date.now() < deadline) await new Promise(r => setTimeout(r, 25))

package/src/monitor.mjs

@@ -6,8 +6,8 @@ import { bridgeHome, repoKey, requestResult } from './bridge.mjs';
 import { sessionStatus } from './session-status.mjs';
 import { errorCode, errorMessage } from './session-types.mjs';
 const uuidFile = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}\.json$/i;
-const pending = new Set(['sending', 'submitted', 'unknown']);
-const requestLabels = { sending: '전달 중', submitted: '응답 대기', completed: '완료', failed: '실패', unknown: '전송 확인 필요', superseded: '다른 입력으로 대체됨' };
+const pending = new Set(['queued', 'sending', 'submitted', 'unknown']);
+const requestLabels = { queued: '작업 큐 대기', sending: '전달 중', submitted: '응답 대기', completed: '완료', failed: '실패', unknown: '전송 확인 필요', superseded: '다른 입력으로 대체됨' };
 const sessionLabels = { starting: '시작 중', running: '작업 중', idle: '대기', awaiting_user: '사용자 승인 필요', settling: '대기 전환 중', closed: '종료', unknown: '상태 미확인' };
 const dialogueLabels = { queued: '접수', running: '중계 중', stopping: '중단 대기', completed: '완료', failed: '실패', cancelled: '중단', token_limit: '토큰 한도', unknown: '확인 필요', usage_unavailable: '사용량 미확인', message_limit: '메시지 한도', invalid_response: '응답 형식 확인 필요', turn_limit: '횟수 한도' };
 function records(directory, issues, label, uuidOnly = true) {
@@ -74,7 +74,7 @@ export function createMonitor(cwd, options = {}) {
         const refreshed = new Set();
         for (let index = 0; index < requests.length && refreshed.size < 4; index++) {
             const request = requests[index];
-            if (!['submitted', 'unknown'].includes(request.state) || refreshed.has(request.to))
+            if (!['queued', 'submitted', 'unknown'].includes(request.state) || refreshed.has(request.to))
                 continue;
             refreshed.add(request.to);
             try {

package/src/monitor.mts

@@ -13,8 +13,8 @@ export interface MonitorSnapshot {
   dialogues: DialogueRecord[]; claims: MonitorClaim[]; events: MonitorEvent[]; issues: string[]
 }
 const uuidFile = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}\.json$/i
-const pending = new Set(['sending', 'submitted', 'unknown'])
-const requestLabels: Record<string, string> = { sending: '전달 중', submitted: '응답 대기', completed: '완료', failed: '실패', unknown: '전송 확인 필요', superseded: '다른 입력으로 대체됨' }
+const pending = new Set(['queued', 'sending', 'submitted', 'unknown'])
+const requestLabels: Record<string, string> = { queued: '작업 큐 대기', sending: '전달 중', submitted: '응답 대기', completed: '완료', failed: '실패', unknown: '전송 확인 필요', superseded: '다른 입력으로 대체됨' }
 const sessionLabels: Record<string, string> = { starting: '시작 중', running: '작업 중', idle: '대기', awaiting_user: '사용자 승인 필요', settling: '대기 전환 중', closed: '종료', unknown: '상태 미확인' }
 const dialogueLabels: Record<string, string> = { queued: '접수', running: '중계 중', stopping: '중단 대기', completed: '완료', failed: '실패', cancelled: '중단', token_limit: '토큰 한도', unknown: '확인 필요', usage_unavailable: '사용량 미확인', message_limit: '메시지 한도', invalid_response: '응답 형식 확인 필요', turn_limit: '횟수 한도' }
 
@@ -64,7 +64,7 @@ export function createMonitor(cwd: string, options: {
     const refreshed = new Set<string>()
     for (let index = 0; index < requests.length && refreshed.size < 4; index++) {
       const request = requests[index]!
-      if (!['submitted', 'unknown'].includes(request.state) || refreshed.has(request.to)) continue
+      if (!['queued', 'submitted', 'unknown'].includes(request.state) || refreshed.has(request.to)) continue
       refreshed.add(request.to)
       try { requests[index] = resolve(request.id, workspace) }
       catch (e) { issues.push(`요청 ${request.id.slice(0, 8)}: ${errorMessage(e)}`) }