codebuff-agent 2.1.74__py3-none-any.whl

jupyter_ext/agent/codex_bridge.py

@@ -0,0 +1,3339 @@
+"""centri 의 codex 서버사이드와 말하는 브릿지 (이슈 #88).
+
+코드버프는 codex app-server 의 JSON-RPC 를 **기존 agent SSE 계약**으로 번역한다.
+그 반대 방향(centri 가 코드버프 계약을 내게 하는 것)을 택하지 않은 이유는 외부에
+발행한 계약이 브랜치 안에서 되돌릴 수 없기 때문이다.
+
+도구는 두 갈래다.
+
+- pod 실행분: 이 프로세스가 직접 돌리고 같은 JSON-RPC id 로 회신한다.
+- 브라우저 실행분: pod 에 커널도 노트북 모델도 없으므로 `hitl_request` 로 스트림을
+  끊고, 프론트가 실행한 결과를 `/agent/codex/resume` 으로 받아 회신한다.
+
+사이드패널은 터미널의 codex CLI 처럼 동작한다. 코드 실행·빌드는 `execute_command`(셸),
+수정은 물리 파일에 직접 한다. 노트북 도구는 코드 셀(`jupyter_cell`) 하나만 알린다 —
+셸 프로세스는 노트북 커널의 변수를 못 보므로, 그 변수를 쓰는 분석만 셀로 보낸다
+(이슈 #155). 마크다운 셀 도구는 알리지 않는다.
+
+`codexPermissionMode` 는 **pod 에서 돌릴 수 있는 변경 작업**에만 걸린다. 브라우저
+실행분은 권한과 무관하게 왕복해야 한다 — 그것이 유일한 실행 경로다. 다만 bypass 면
+`hitl_request` 에 `autoApprove` 를 실어 프론트가 묻지 않고 바로 실행하게 한다.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import codecs
+import contextlib
+import copy
+import difflib
+import hashlib
+import json
+import logging
+import os
+import shlex
+import time
+from typing import (
+    Any,
+    AsyncIterator,
+    Callable,
+    Dict,
+    Iterator,
+    List,
+    Optional,
+    Set,
+    Tuple,
+)
+
+import httpx
+from codebuff_core.managers.config_manager import prompt_value
+from codebuff_core.platform_rules import platform_rules_block, tool_call_violation
+from codebuff_core.prompts.auto_agent_prompts import NEXUS_URL_PATH, read_pip_index_url
+from codebuff_core.services.pii_guardrail import mask_pii
+
+from . import background_procs, codex_hooks, custom_skills
+
+logger = logging.getLogger(__name__)
+
+
+def _mask(text: str) -> Tuple[str, List[str]]:
+    """pod 밖으로 나가는 본문에서 개인정보를 가린다.
+
+    LangChain chat 경로는 `chat_service` 가 입력을 가리고, LangChain Agent 경로는
+    `PiiMaskMiddleware` 가 모델 호출 직전에 가린다. codex 경로는 프롬프트와 파일 내용이 pod 밖의 서버로 나가므로 여기가
+    마지막 관문이다. 도구 결과는 `_tool_result` 가 문맥 조건을 더한 모드로 가린다.
+    """
+    if not text:
+        return text, []
+    result = mask_pii(text)
+    return result.masked_text, list(result.detected_types)
+
+
+def _mask_except(text: str, keep: str) -> str:
+    """`keep` 문자열은 그대로 두고 나머지를 `_mask` 로 가린다.
+
+    포트 접두(`/user/<사번>/proxy/`)는 사용자 자신의 허브 경로다. 사번이 전화번호
+    꼴이면 `mask_pii` 가 그것을 지워 codex 가 안 열리는 주소를 안내한다 (이슈 #136).
+    """
+    if not keep:
+        return _mask(text)[0]
+    return keep.join(_mask(part)[0] for part in text.split(keep))
+
+
+# (agent_call_hst 컬럼, codex TokenUsageBreakdown 키) — codex 0.154.0 스키마
+_USAGE_KEYS = (
+    ("input_tokens", "inputTokens"),
+    ("output_tokens", "outputTokens"),
+    ("cached_tokens", "cachedInputTokens"),
+)
+
+
+def _identity() -> Dict[str, str]:
+    """client 경로와 같은 사용자 식별 — jsonl 과 RDS 행이 같은 값을 갖게 한다."""
+    from jupyter_ext.agent.observability import default_user_identity
+
+    return default_user_identity()
+
+
+def _default_recorder(event: Dict[str, Any]) -> None:
+    """관측 이벤트를 client 경로와 같은 적재기로 흘린다."""
+    from jupyter_ext.agent.observability import _write_structured_event
+
+    _write_structured_event(event)
+
+
+# 프론트가 스트림 종료로 인정하는 이벤트 (ApiService 가 그 외에는 예외를 던진다)
+
+# 브라우저에서만 실행되는 도구 — pod 에는 커널도 노트북 모델도 없다
+BROWSER_TOOLS = {"jupyter_cell"}
+
+# 승인을 받아야 하는 pod 실행분 (permission_mode == "ask" 일 때)
+GUARDED_POD_TOOLS = {"write_file", "edit_file", "execute_command", "kill_process"}
+
+# codex 알림의 도구 이름 → 프론트가 아는 action 이름
+_ACTION_NAME_MAP = {
+    "jupyter_cell": "jupyter_cell_tool",
+    "write_file": "write_file_tool",
+    "edit_file": "edit_file_tool",
+    "execute_command": "execute_command_tool",
+    "kill_process": "kill_process_tool",
+}
+
+# codex 계획 단계 상태 → deepagents todo 상태
+#: 본문을 버려야 하는 "도구를 부른 턴" 의 item 종류. dynamic tool 만 세던 것을
+#: 운영 게이트웨이가 여는 codex 네이티브 도구까지 넓혔다 (이슈 #155)
+_TOOL_ITEM_TYPES = frozenset(
+    {"dynamicToolCall", "mcpToolCall", "commandExecution", "webSearch"}
+)
+
+_PLAN_STATUS = {
+    "pending": "pending",
+    "inProgress": "in_progress",
+    "completed": "completed",
+}
+#: deepagents `write_todos` 의 상태 — 프론트 todo 패널이 아는 셋
+_TODO_STATUSES = frozenset(_PLAN_STATUS.values())
+
+# deepagents 의 승인 설명(`agent_factory.ds_tool_description`)에서 쓰는 도구 이름
+_HITL_LANGCHAIN_NAME = {"write_file": "file_write"}
+
+
+def _hitl_description(tool: str, args: Dict[str, Any]) -> str:
+    """승인 요청 설명 — deepagents 경로와 같은 꼴로 쓴다 (이슈 #155).
+
+    카드는 args 로 그리지만, 이 문구가 대화 기록에 남는 승인 메시지 본문이다.
+    `test_codex_parity.py::TestHitlDescription` 이 두 꼴을 대조한다.
+    """
+    from .middleware_prompts import DS_HITL_DESCRIPTION_PREFIX
+
+    name = _HITL_LANGCHAIN_NAME.get(tool, tool)
+    if name == "jupyter_cell":
+        code = args.get("code", "")
+        lines = code.split("\n") if code else []
+        if len(lines) > 5:
+            preview = "\n".join(lines[:5])
+            return (
+                f"{DS_HITL_DESCRIPTION_PREFIX}\n\n"
+                f"**Jupyter Cell Execution** ({len(lines)} lines):\n"
+                f"```python\n{preview}\n# ... {len(lines) - 5} more lines\n```"
+            )
+        return (
+            f"{DS_HITL_DESCRIPTION_PREFIX}\n\n"
+            f"**Jupyter Cell Execution:**\n```python\n{code}\n```"
+        )
+    if name == "file_write":
+        path = args.get("path", "unknown")
+        size = len(args.get("content", ""))
+        return (
+            f"{DS_HITL_DESCRIPTION_PREFIX}\n\n**File Write:** `{path}` ({size} bytes)"
+        )
+    return (
+        f"{DS_HITL_DESCRIPTION_PREFIX}\n\n"
+        f"**Tool:** {tool}\n"
+        f"**Args:** {json.dumps(args, ensure_ascii=False, indent=2)}"
+    )
+
+
+# 샌드박스는 **두 모드 다 `read-only`** 다. codex 는 centri 쪽에서 도는데 그 쪽
+# 파일시스템은 사용자의 작업공간이 아니다 — 쓰기를 열어 주면 네이티브
+# `apply_patch` 가 dynamic tool 을 제치고 이겨서, 사용자 pod 이 아니라 centri
+# 서버의 파일이 바뀐다 (이슈 #96 실측). 읽기는 막지 않는다: codex 가 자기 쪽
+# 임시 파일을 읽는 것까지 막을 이유는 없고, pod 파일은 어차피 도구로만 닿는다.
+_PERMISSION_POLICY = {
+    "ask": {"approvalPolicy": "on-request", "sandbox": "read-only"},
+    "bypass": {"approvalPolicy": "never", "sandbox": "read-only"},
+}
+
+# Chat/Q&A는 코드 작업 에이전트가 아니다. `dynamicTools`만 줄여서는 codex 내장
+# shell·web·browser·computer·app·subagent가 그대로 남으므로 스레드 config에서도 끈다.
+# feature 이름은 `codex features list`(0.157.0) 실측이다 — config 는 스키마상 열린
+# 객체라 오타 키도 서버가 받으므로, 이름은 `test_codex_live` 가 실물 목록과 대조한다.
+# 기본값이 켜진 것 중 모델에게 도구로 노출되는 것만 끈다(hooks·goals 등은 그대로).
+# 빈 MCP/plugin 표는 이 통합이 별도 서버를 싣지 않는다는 선언이다.
+_SEARCH_ONLY_FEATURES_OFF = (
+    "shell_tool",
+    "unified_exec",
+    "view_image",
+    "image_generation",
+    "browser_use",
+    "browser_use_external",
+    "computer_use",
+    "in_app_browser",
+    "multi_agent",
+    "apps",
+    "plugins",
+    "remote_plugin",
+    "skill_search",
+    "tool_suggest",
+    "sleep_tool",
+)
+#: 답 없이 끝난 Agent 밖 턴에 한 번 더 보내는 요청 (LangChain `_fallback_llm_call` 대응)
+EMPTY_ANSWER_FOLLOW_UP = (
+    "직전 턴이 최종 답변 없이 끝났습니다. 도구를 더 부르지 말고, 지금까지의 대화와 "
+    "도구 결과만으로 사용자 요청에 대한 최종 답변을 작성하세요."
+)
+#: Agent 가 아무것도 바꾸지 않고 답 없이 끝났을 때 보내는 요청. Agent 는 도구로 일을 마쳐야
+#: 하므로 "도구를 부르지 말라" 는 위 문구를 쓰지 않는다 (이슈 #176)
+AGENT_EMPTY_ANSWER_FOLLOW_UP = (
+    "직전 턴이 최종 답변 없이 끝났습니다. 요청한 작업이 끝나지 않았으면 도구로 이어서 "
+    "끝내고, 끝났으면 무엇을 바꾸고 실행했는지 짧게 요약하세요."
+)
+#: 워크스페이스를 바꾸는 도구. 이 중 하나라도 부른 Agent 턴은 답이 비어도 일을 한 것이다
+_CHANGING_TOOLS = frozenset(
+    {"write_file", "edit_file", "execute_command", "jupyter_cell", "kill_process"}
+)
+
+#: codex base 지시문은 코드 상수가 아니다 (이슈 #218). Agent 밖 스레드는 짧은 정체성 문구
+#: `prompts.codex_base_instructions`(이슈 #155·#176·#178), Agent 스레드는 셸이 pod 도구뿐이라고
+#: 못 박는 `prompts.codex_agent_base_instructions`(이슈 #176)다 — codex 기본 base 는 read-only
+#: 샌드박스의 네이티브 셸을 쓰라고 가르쳐 gpt-oss 가 execute_command 까지 거절했다.
+#: Agent 스레드에서 끄는 codex 네이티브 셸. 켜 두면 모델이 read-only 샌드박스의 셸을 먼저
+#: 집어 거절당한다. centri 게이트웨이는 false 값만 통과시킨다 (centri #1774)
+_AGENT_NATIVE_SHELL_OFF = {"shell_tool": False, "unified_exec": False}
+
+_SEARCH_ONLY_THREAD_CONFIG = {
+    "web_search": "disabled",
+    "features": {name: False for name in _SEARCH_ONLY_FEATURES_OFF},
+    "mcp_servers": {},
+    "plugins": {},
+}
+
+# 서버가 보내는 승인 요청 중 우리가 답하는 것. 승인 흐름은 dynamic tool 쪽
+# `hitl_request` 가 이미 담당하므로, 네이티브 쓰기 요청은 여기서 거절한다.
+# 회신 모양이 메서드마다 다르다 — `decision` 을 쓰는 것만 여기 둔다
+# (`item/permissions/requestApproval` 은 `permissions` 를 요구해 모양이 다르다).
+_DECLINE_RESPONSE = {
+    "item/commandExecution/requestApproval": {"decision": "decline"},
+    "item/fileChange/requestApproval": {"decision": "decline"},
+    "applyPatchApproval": {"decision": "abort"},
+    "execCommandApproval": {"decision": "abort"},
+}
+
+# 진행 줄은 터미널처럼 한 줄씩 쌓인다 — 너무 긴 인자·요약은 자른다.
+_PROGRESS_MAX = 160
+# 도구 인자 중 "무엇을 하는지" 가 드러나는 키. 앞에 있는 것이 이긴다.
+_ARG_HINT_KEYS = (
+    "path",
+    "file_path",
+    "command",
+    "query",
+    "pattern",
+    "url",
+    "process_id",
+)
+
+
+def _one_line(text: Any) -> str:
+    flat = " ".join(str(text).replace("**", "").split())
+    return flat if len(flat) <= _PROGRESS_MAX else flat[: _PROGRESS_MAX - 1] + "…"
+
+
+def _describe_started(item: Dict[str, Any]) -> Optional[str]:
+    """`item/started` 를 진행 줄 하나로. 원시 타입명은 내보내지 않는다."""
+    kind = item.get("type")
+    if kind == "commandExecution":
+        return _one_line(f"$ {item.get('command') or ''}")
+    if kind in ("dynamicToolCall", "mcpToolCall"):
+        name = item.get("tool") or "?"
+        args = item.get("arguments")
+        if name == "write_todos":
+            # LangChain `agent_factory` 의 진행 문구와 같다
+            return "작업 계획 수립 중..."
+        if name == "execute_command" and isinstance(args, dict):
+            # 터미널의 프롬프트처럼 보인다 — 명령 자체가 진행 줄이다
+            suffix = " &" if args.get("background") else ""
+            return _one_line(f"$ {args.get('command') or ''}{suffix}")
+        if kind == "mcpToolCall" and item.get("server"):
+            name = f"{item['server']}.{name}"
+        hint = next(
+            (args[k] for k in _ARG_HINT_KEYS if isinstance(args, dict) and args.get(k)),
+            "",
+        )
+        return _one_line(f"도구 {name} {hint}".rstrip())
+    if kind == "fileChange":
+        paths = [
+            c.get("path", "") for c in item.get("changes") or [] if isinstance(c, dict)
+        ]
+        return _one_line(f"파일 변경 {', '.join(p for p in paths if p)}".rstrip())
+    if kind == "webSearch":
+        return _one_line(f"웹 검색 {item.get('query') or ''}".rstrip())
+    if kind == "contextCompaction":
+        return "컨텍스트 압축"
+    if kind == "collabAgentToolCall":
+        prompt = item.get("prompt") or ""
+        return _one_line(f"서브에이전트 {_collab_label(item)} {prompt}".rstrip())
+    return None
+
+
+# 서브에이전트 도구·상태를 진행 줄 낱말로 (codex 0.154.0 `CollabAgentTool` 등).
+# 모르는 값은 원문 대신 뭉뚱그린 낱말로 — 원시 enum 을 화면에 내지 않는다.
+_COLLAB_TOOL_LABEL = {
+    "spawnAgent": "시작",
+    "sendInput": "입력 전달",
+    "resumeAgent": "재개",
+    "wait": "대기",
+    "closeAgent": "종료",
+    "sendMessage": "메시지",
+    "followupTask": "후속 작업",
+    "interruptAgent": "중단",
+    "listAgents": "목록",
+}
+_COLLAB_STATE_LABEL = {
+    "pendingInit": "준비",
+    "running": "실행 중",
+    "interrupted": "중단",
+    "completed": "완료",
+    "errored": "오류",
+    "shutdown": "종료",
+    "notFound": "없음",
+}
+_SUBAGENT_ACTIVITY_LABEL = {
+    "started": "시작",
+    "interacted": "응답",
+    "interrupted": "중단",
+    "completed": "완료",
+}
+
+
+def _collab_label(item: Dict[str, Any]) -> str:
+    return _COLLAB_TOOL_LABEL.get(str(item.get("tool") or ""), "작업")
+
+
+def _collab_states(item: Dict[str, Any]) -> str:
+    """`agentsStates` 를 "완료 2 · 실행 중 1" 처럼 센다."""
+    counts: Dict[str, int] = {}
+    states = item.get("agentsStates")
+    for state in states.values() if isinstance(states, dict) else []:
+        if not isinstance(state, dict):
+            continue
+        label = _COLLAB_STATE_LABEL.get(str(state.get("status") or ""), "기타")
+        counts[label] = counts.get(label, 0) + 1
+    return " · ".join(f"{label} {n}" for label, n in counts.items())
+
+
+def _describe_completed(item: Dict[str, Any]) -> Optional[str]:
+    """`item/completed` 중 결과가 궁금한 것만 한 줄로."""
+    kind = item.get("type")
+    if kind == "reasoning":
+        summary = " ".join(str(s) for s in item.get("summary") or [] if s)
+        return _one_line(f"생각: {summary}") if summary.strip() else None
+    if kind == "commandExecution":
+        code = item.get("exitCode")
+        if code not in (None, 0):
+            return f"↳ 종료 코드 {code}"
+    if kind in ("dynamicToolCall", "mcpToolCall") and (
+        item.get("success") is False or item.get("error")
+    ):
+        return f"↳ {item.get('tool') or '도구'} 실패"
+    if kind == "collabAgentToolCall":
+        if item.get("status") == "failed":
+            return f"↳ 서브에이전트 {_collab_label(item)} 실패"
+        states = _collab_states(item)
+        return f"↳ 서브에이전트 {states}" if states else None
+    if kind == "subAgentActivity":
+        label = _SUBAGENT_ACTIVITY_LABEL.get(str(item.get("kind") or ""), "활동")
+        path = item.get("agentPath") or ""
+        return _one_line(f"서브에이전트 {path} {label}".replace("  ", " "))
+    return None
+
+
+# Agent 모드 developer 지시문은 `prompts.codex_agent_instructions`(도구·응답 규칙) 뒤에
+# 두 엔진 공용 `prompts.todo_rules`(write_todos 규칙)를 붙인 것이다 (이슈 #155, #218).
+# write_todos 는 deepagents 와 같은 이름의 dynamic 도구다 — 계획은 패널의 todo 목록으로
+# 보인다. codex 네이티브 update_plan 은 모델에 따라 안 보인다(gpt-5.6-sol·0.157.0 실측).
+
+
+# 셸 명령 한도. 기본 한도는 **출력이 없는 시간**이다 — 출력이 흐르는 동안은
+# 살아 있는 것이므로 기다린다. 무한 루프를 막는 절대 한도는 따로 둔다.
+_COMMAND_IDLE_TIMEOUT = 120
+_COMMAND_HARD_LIMIT = 1800
+# background 로그 읽기 한도 — 모델에 알리는 값이 실제 동작과 갈리지 않게 한 곳에서 가져온다
+_BG_TAIL_DEFAULT = background_procs._TAIL_DEFAULT
+_BG_TAIL_MAX = background_procs._TAIL_MAX
+_BG_TAIL_READ_KB = background_procs._TAIL_READ_BYTES // 1024
+# 모델에 돌려주는 명령 출력의 상한 (codex CLI 와 같은 앞뒤 보존 방식)
+_OUTPUT_HEAD_LINES = 100
+_OUTPUT_TAIL_LINES = 150
+_OUTPUT_MAX_CHARS = 16000
+# read_file 이 모델에 돌려주는 내용의 상한. `package-lock.json` 은 수백 KB 다 (이슈 #100)
+_READ_FILE_MAX_CHARS = 64000
+# 셸의 pip 이 client 경로(`PIP_INDEX_OPTION`)와 같은 사내 인덱스를 보게 한다 (이슈 #100)
+_PIP_INDEX_FILE = NEXUS_URL_PATH
+# 패널에 보여 주는 파일 변경 diff 의 상한
+_DIFF_MAX_LINES = 80
+
+# dynamic tool 카탈로그. 설명은 언어 중립으로 쓴다 — 코드버프는 파이썬과 자바를
+# 가리지 않는다. 노트북 도구는 코드 셀(`jupyter_cell`)만 싣는다 (모듈 설명 참고).
+CODEX_DYNAMIC_TOOLS: List[Dict[str, Any]] = [
+    {
+        "type": "function",
+        "name": "read_file",
+        "description": "작업공간의 파일 하나를 텍스트로 읽는다.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "description": "작업공간 기준 상대 경로"},
+                "encoding": {"type": "string", "default": "utf-8"},
+            },
+            "required": ["path"],
+        },
+    },
+    {
+        "type": "function",
+        "name": "write_file",
+        "description": (
+            "작업공간의 파일에 내용을 쓴다. 있는 파일은 덮어쓰고, append 를 켜면 뒤에 "
+            "붙인다. 확장자에 맞는 포매터가 있으면 함께 돌린다."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string"},
+                "content": {"type": "string"},
+                "append": {"type": "boolean", "default": False},
+            },
+            "required": ["path", "content"],
+        },
+    },
+    {
+        "type": "function",
+        "name": "edit_file",
+        "description": (
+            "작업공간의 파일에서 old_string 을 new_string 으로 바꿔 필요한 부분만 고친다. "
+            "old_string 은 파일에서 한 곳만 일치해야 하며, 여러 곳을 모두 바꾸려면 "
+            "replace_all 을 켠다."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "description": "작업공간 기준 상대 경로"},
+                "old_string": {"type": "string"},
+                "new_string": {"type": "string"},
+                "replace_all": {"type": "boolean", "default": False},
+            },
+            "required": ["path", "old_string", "new_string"],
+        },
+    },
+    {
+        "type": "function",
+        "name": "list_files",
+        "description": "작업공간의 디렉토리 목록을 조회한다.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "default": "."},
+                "recursive": {"type": "boolean", "default": False},
+                "pattern": {"type": "string"},
+            },
+        },
+    },
+    {
+        "type": "function",
+        "name": "search_code",
+        "description": "작업공간에서 정규식으로 코드를 검색한다. 언어를 가리지 않는다.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "pattern": {"type": "string"},
+                "path": {"type": "string", "default": "."},
+                "file_pattern": {"type": "string", "default": "*"},
+                "max_results": {"type": "integer", "default": 50},
+            },
+            "required": ["pattern"],
+        },
+    },
+    {
+        "type": "function",
+        "name": "execute_command",
+        "description": (
+            "작업공간 루트에서 셸 명령을 실행하고 출력과 종료 코드를 돌려준다. "
+            "코드 실행·빌드·테스트·포매터는 이 도구로 돌린다 "
+            "(예: python app.py, ./mvnw package, gradle test, javac, pytest, npm run build). "
+            "셸 스크립트는 bash build.sh 처럼 돌리고, 하위 디렉토리에서는 cd sub && … 로 "
+            "한 명령에 묶는다 — 호출마다 루트에서 새 셸이 뜬다. 입력을 기다리는 대화형 "
+            "명령은 쓰지 않는다(stdin 은 닫혀 있다). "
+            f"timeout 은 출력이 없는 시간의 한도(초, 최대 {_COMMAND_HARD_LIMIT})라서 "
+            "출력이 이어지는 긴 빌드는 끊기지 않는다. 긴 출력은 앞뒤만 남기고 잘린다. "
+            "개발 서버처럼 끝나지 않는 명령은 background 를 켠다 — 바로 process_id 를 "
+            "돌려주고 출력은 로그에 쌓인다. 사용자는 pod 밖에 있어 localhost 로는 못 연다 — "
+            "지시문에 '## pod 포트 열기' 가 있으면 그 주소 규칙으로 안내하고 앱을 맞춘다. "
+            "서버는 0.0.0.0 이 아니라 127.0.0.1 로 띄워도 된다. background 명령에 "
+            "&·nohup·setsid·--daemon 을 붙이지 않는다 — 그룹을 벗어난 프로세스는 목록과 "
+            "종료에서 빠진다."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "command": {"type": "string"},
+                "timeout": {"type": "integer", "default": _COMMAND_IDLE_TIMEOUT},
+                "background": {"type": "boolean", "default": False},
+            },
+            "required": ["command"],
+        },
+    },
+    # 브라우저 실행분 — 인자는 LangChain `jupyter_cell` 도구와 같다 (이슈 #155)
+    {
+        "type": "function",
+        "name": "jupyter_cell",
+        "description": (
+            "열려 있는 노트북 끝에 코드 셀을 넣고 그 노트북의 커널에서 실행한 뒤 출력을 "
+            "돌려준다. 커널에 이미 있는 변수(데이터프레임 등)를 쓰는 분석·시각화에 쓴다. "
+            "커널은 python3 하나뿐이므로 빌드·테스트·스크립트와 다른 언어의 코드는 "
+            "execute_command 로 돌린다. 열린 노트북이 없으면 커널 대신 별도 프로세스에서 "
+            "돌아 커널 변수가 없다(NameError) — 그때는 사용자에게 노트북을 열어 달라고 한다."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "code": {"type": "string", "description": "셀에 넣어 실행할 코드"},
+                "description": {
+                    "type": "string",
+                    "description": "셀이 하는 일 한 줄 (승인 카드에 보인다)",
+                },
+            },
+            "required": ["code"],
+        },
+    },
+    {
+        "type": "function",
+        "name": "list_processes",
+        "description": (
+            "background 로 띄운 프로세스 목록을 돌려준다 "
+            "(process_id·pid·명령·상태·종료 코드·LISTEN 포트)."
+        ),
+        "inputSchema": {"type": "object", "properties": {}},
+    },
+    {
+        "type": "function",
+        "name": "read_process_output",
+        "description": (
+            "background 프로세스의 로그 끝부분을 읽는다. tail 은 줄 수이고 최대 "
+            f"{_BG_TAIL_MAX}줄, 로그 마지막 {_BG_TAIL_READ_KB}KB 안에서만 센다."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "process_id": {"type": "string"},
+                "tail": {"type": "integer", "default": _BG_TAIL_DEFAULT},
+            },
+            "required": ["process_id"],
+        },
+    },
+    {
+        "type": "function",
+        "name": "kill_process",
+        "description": "background 프로세스를 자식까지 함께 종료한다.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {"process_id": {"type": "string"}},
+            "required": ["process_id"],
+        },
+    },
+    {
+        "type": "function",
+        "name": "load_skill",
+        "description": (
+            "developer 지시문의 Custom Skills·Built-in Skills 목록에 있는 스킬 하나의 "
+            "본문을 읽는다. 작업이 스킬 설명과 맞으면 먼저 읽고 그 절차를 따른다."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "name": {"type": "string", "description": "스킬 이름"},
+            },
+            "required": ["name"],
+        },
+    },
+    {
+        "type": "function",
+        "name": "write_todos",
+        "description": (
+            "여러 단계인 작업의 계획을 패널의 todo 목록으로 보여 준다. 호출할 때마다 "
+            "목록 전체를 보낸다. 상태는 pending·in_progress·completed 중 하나다."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "todos": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "content": {"type": "string"},
+                            "status": {
+                                "type": "string",
+                                "enum": ["pending", "in_progress", "completed"],
+                            },
+                        },
+                        "required": ["content", "status"],
+                    },
+                },
+            },
+            "required": ["todos"],
+        },
+    },
+]
+
+CODEX_QA_TOOL_NAMES = frozenset(
+    {
+        "rag_search",
+        "get_table_columns",
+        "get_iceberg_snapshots",
+        "search_l2_table",
+        "load_skills",
+    }
+)
+
+
+def _langchain_tool_spec(tool: Any) -> Dict[str, Any]:
+    """LangChain BaseTool을 codex app-server dynamic tool 스키마로 바꾼다."""
+    schema = tool.args_schema.model_json_schema() if tool.args_schema else {}
+    return {
+        "type": "function",
+        "name": tool.name,
+        "description": tool.description or "",
+        "inputSchema": schema or {"type": "object", "properties": {}},
+    }
+
+
+def _qa_tools(workspace_root: Optional[str] = None) -> Dict[str, Any]:
+    """기존 Q&A 도구 구현을 Codex 호출기에서도 그대로 쓴다."""
+    from .langchain_tools import (
+        create_enhanced_rag_search_tool,
+        create_get_table_columns_tool,
+        create_iceberg_snapshots_tool,
+        create_load_skills_tool,
+        create_search_l2_table_tool,
+    )
+
+    tools = [
+        create_enhanced_rag_search_tool(),
+        create_get_table_columns_tool(),
+        create_iceberg_snapshots_tool(),
+        create_search_l2_table_tool(),
+        create_load_skills_tool(workspace_root),
+    ]
+    return {tool.name: tool for tool in tools}
+
+
+# 응답 서식 규칙(`prompts.answer_format_rules`)은 이슈 #155 에서 codex 에만 붙였는데, 이슈 #218
+# 에서 Chat·BDP Q&A 공용 빌더(`build_chat_mode_system_prompt`)로 옮겨 두 엔진이 같이 쓴다.
+
+
+# Q&A 계열(BDP Q&A·노트북·EDA) 한 턴의 도구 호출 상한. LangChain `stream_response` 의
+# `_MAX_TOOL_CALLS` 와 같은 값이다
+QA_MAX_TOOL_CALLS = 30
+
+
+def _mode_instructions(mode: str) -> str:
+    if mode == "agent":
+        return f"{prompt_value('codex_agent_instructions')}\n\n{prompt_value('todo_rules')}"
+    from codebuff_core.services.rag_chat_agent import build_chat_mode_system_prompt
+
+    chat_mode = "knowledge" if mode == "qa" else "simple"
+    return build_chat_mode_system_prompt(chat_mode)
+
+
+# 도구별로 핸들러가 받는 인자. 카탈로그 `properties` 는 이것의 부분집합이어야 한다 —
+# 알려 놓고 여기서 버리면 모델의 기대와 실제 동작이 조용히 갈린다 (이슈 #100).
+POD_TOOL_ARGS: Dict[str, set] = {
+    "read_file": {"path", "encoding"},
+    "write_file": {"path", "content", "append"},
+    "edit_file": {"path", "old_string", "new_string", "replace_all"},
+    "list_files": {"path", "recursive", "pattern"},
+    "search_code": {"pattern", "path", "file_pattern", "max_results"},
+    "execute_command": {"command", "timeout", "background"},
+    "list_processes": set(),
+    "read_process_output": {"process_id", "tail"},
+    "kill_process": {"process_id"},
+    "load_skill": {"name"},
+    "write_todos": {"todos"},
+}
+
+
+class CodexError(Exception):
+    """codex 쪽이 돌려준 오류."""
+
+
+class CodexRejected(CodexError):
+    """codex 가 요청 하나를 JSON-RPC 오류로 거부했다 — 연결과 스레드는 멀쩡하다.
+
+    슬래시 명령(이슈 #121)은 이것을 받으면 문구만 내고 세션을 살려 둔다. 배포에
+    없는 메서드(`-32601`)는 그 명령만 못 쓰는 것이지 대화가 끊긴 것이 아니다.
+    """
+
+
+class CodexUnavailable(CodexError):
+    """codex 서버에 닿지 못했다."""
+
+
+class CodexGatewayRejected(CodexUnavailable):
+    """centri 게이트웨이가 연결을 accept 전에 거절했다 (이슈 #158, #167).
+
+    구 게이트웨이는 동시 상한 초과·키 불일치·사이드카 미설정을 모두 accept 전
+    `websocket.close` 로 거절하고, uvicorn 이 그것을 close code 없는 403 으로
+    내보낸다 — 그래서 원인은 셋 중 무엇인지 모른다. centri#1768 이후에는 상태
+    코드와 JSON `reason` 본문으로 오고, 포화만 `CodexGatewaySaturated` 로 가른다.
+    서버에 못 닿은 것과는 가른다: turn status 가 `error:CodexGatewayRejected` 로
+    따로 적재된다. `CodexRejected`(JSON-RPC 요청 하나 거부, 세션 유지)와는 뜻이
+    반대다.
+
+    `reason` 은 centri 가 본문에 실은 거절 종류다(모르면 None). 오류 이벤트의
+    `gatewayReason` 으로 화면까지 가서 안내 문구를 가른다 (#183).
+    """
+
+    def __init__(self, message: str, reason: Optional[str] = None) -> None:
+        super().__init__(message)
+        self.reason = reason
+
+
+class CodexGatewaySaturated(CodexGatewayRejected):
+    """게이트웨이 동시 사용 한도에 걸렸다 — 503 + `reason: saturated` (이슈 #167).
+
+    설정 오류와 달리 기다리면 풀리는 거절이라 문구가 다르고, turn status 도
+    `error:CodexGatewaySaturated` 로 따로 센다.
+    """
+
+
+# 설정 문제 거절의 원인 문구 — 포화(`saturated`)는 따로 다룬다. 프론트
+# `utils/chatError.ts` 의 CONFIG_REJECTIONS 가 같은 키를 본다(가드: test_codex_gateway_rejection).
+_GATEWAY_CONFIG_CAUSES = {
+    "unauthorized": "API 키가 게이트웨이와 맞지 않습니다",
+    "sidecar_missing": "게이트웨이에 에이전트 실행 서버가 설정되지 않았습니다",
+    "sidecar_unreachable": "게이트웨이가 에이전트 실행 서버에 닿지 못했습니다",
+}
+
+
+# centri 게이트웨이가 accept 전 거절 본문에 싣는 `reason` (centri#1768).
+_GATEWAY_REJECT_REASONS = frozenset({"saturated", *_GATEWAY_CONFIG_CAUSES})
+
+
+def _gateway_reject_body(response: Any) -> Dict[str, Any]:
+    """거절 응답의 JSON 본문 — 본문이 없거나 JSON 객체가 아니면 빈 dict."""
+    try:
+        body = json.loads(getattr(response, "body", None) or b"")
+    except (TypeError, ValueError):
+        return {}
+    return body if isinstance(body, dict) else {}
+
+
+def _gateway_rejection(code: int, response: Any) -> Optional[CodexGatewayRejected]:
+    """HTTP 거절 응답을 게이트웨이 거절로 읽는다. 게이트웨이 것이 아니면 None.
+
+    403 은 구 게이트웨이(빈 본문)도 내므로 본문 없이도 거절이다. 503 은 인그레스가
+    본문을 오류 페이지로 바꿀 수 있어 본문 없이도 거절로 읽는다. 그 밖의 상태
+    코드는 centri `reason` 이 있을 때만 게이트웨이 것이다.
+    """
+    body = _gateway_reject_body(response)
+    reason = body.get("reason")
+    if not isinstance(reason, str) or reason not in _GATEWAY_REJECT_REASONS:
+        reason = None
+    if reason == "saturated":
+        limit = body.get("max_concurrency")
+        cap = f"({limit}명)" if isinstance(limit, int) else ""
+        return CodexGatewaySaturated(
+            f"codex 게이트웨이의 동시 사용 한도{cap}에 걸렸습니다(HTTP {code}). "
+            "다른 사용자의 작업이 끝나면 풀리니 잠시 후 다시 시도하세요.",
+            reason="saturated",
+        )
+    if reason is None and code not in (403, 503):
+        return None
+    if reason is not None:
+        # 설정 문제는 기다려도 안 풀린다. 확인할 곳은 프론트가 `gatewayReason` 으로
+        # 안내하므로 여기서는 원인만 적는다 — 두 층이 같은 안내를 겹쳐 쓰지 않는다 (#183)
+        return CodexGatewayRejected(
+            f"에이전트 게이트웨이가 연결을 거절했습니다(HTTP {code}, {reason}) — "
+            f"{_GATEWAY_CONFIG_CAUSES[reason]}. 계속되면 관리자에게 문의하세요.",
+            reason=reason,
+        )
+    return CodexGatewayRejected(
+        f"codex 게이트웨이가 연결을 거절했습니다(HTTP {code}"
+        + ") — 동시 사용 한도 초과이거나 API 키·사이드카 설정 문제입니다. "
+        "잠시 후 다시 시도하고, 계속되면 관리자에게 문의하세요."
+    )
+
+
+class Transport:
+    """JSON-RPC 한 쌍의 메시지 통로. 테스트는 이 자리를 스텁으로 바꾼다."""
+
+    async def connect(self) -> None:  # pragma: no cover - 인터페이스
+        raise NotImplementedError
+
+    async def send(self, message: Dict[str, Any]) -> None:  # pragma: no cover
+        raise NotImplementedError
+
+    async def receive(self) -> Optional[Dict[str, Any]]:  # pragma: no cover
+        raise NotImplementedError
+
+    async def close(self) -> None:  # pragma: no cover
+        raise NotImplementedError
+
+
+# `codebuff.agent_call_hst.status` 컬럼 폭 (schemas/rds/codebuff_mysql.sql)
+_STATUS_MAX = 64
+
+#: 핸드셰이크 요청 하나가 답을 기다리는 상한(초). LLM 이 돌기 전 단계라
+#: 왕복이 짧다 — 실측(0.154.0, 로컬) `initialize`·`thread/start` 각 0.1초 미만.
+_HANDSHAKE_TIMEOUT = 30.0
+
+
+class StubTransport(Transport):
+    """스크립트된 서버 메시지를 순서대로 돌려주는 테스트용 통로."""
+
+    def __init__(
+        self,
+        scripted: List[Dict[str, Any]],
+        *,
+        fail_on_connect: Optional[Exception] = None,
+        reject: Optional[Dict[str, Dict[str, Any]]] = None,
+    ) -> None:
+        self.scripted = list(scripted)
+        self.sent: List[Dict[str, Any]] = []
+        self.closed = False
+        self._fail_on_connect = fail_on_connect
+        # 메서드 → JSON-RPC error 객체. 배포에 없는 메서드(-32601)를 흉내 낸다 (이슈 #121)
+        self._reject = dict(reject or {})
+        self._forks = 0
+
+    async def connect(self) -> None:
+        if self._fail_on_connect is not None:
+            raise self._fail_on_connect
+
+    #: 요청 메서드별 자동 응답. **빈 결과를 돌려주지 않는다** — 핸드셰이크가
+    #: `thread/start` 응답에서 thread id 를 꺼내는데, 빈 결과로 답하면 테스트가
+    #: 실물과 다른 경로를 타고 그 결함을 못 잡는다 (이슈 #96).
+    #:
+    #: 브릿지가 읽는 것은 `thread.id`·`turn.id` 뿐이지만 **스냅샷이 요구하는
+    #: 필수 필드를 다 채운다.** 손으로 줄인 응답을 쓰면 아웃바운드만 스키마로
+    #: 재고 인바운드는 자기가 지어낸 값을 자기가 확인하는 꼴이 된다 — 이 이슈가
+    #: 고치려던 자기참조가 방향만 바꿔 남는다.
+    #: `test_codex_contract.py::TestStubFidelity` 가 이 값들을 스냅샷과 대조한다.
+    AUTO_RESULT = {
+        "thread/start": {
+            "approvalPolicy": "on-request",
+            "approvalsReviewer": "user",
+            "cwd": "/ws",
+            "model": "gpt-5-codex",
+            "modelProvider": "openai",
+            "sandbox": {"type": "readOnly"},
+            "thread": {
+                "cliVersion": "0.154.0",
+                "createdAt": 0,
+                "cwd": "/ws",
+                "ephemeral": False,
+                "id": "codex-thread-stub",
+                "modelProvider": "openai",
+                "preview": "",
+                "projectId": "proj-stub",
+                "sessionId": "sess-stub",
+                "source": "cli",
+                "status": {"type": "idle"},
+                "turns": [],
+                "updatedAt": 0,
+            },
+        },
+        "turn/start": {
+            "turn": {"id": "codex-turn-stub", "status": "inProgress", "items": []}
+        },
+        # 스레드 관리 (이슈 #121). resume·fork·read 는 클래스 아래에서 thread/start 로
+        # 채운다 — `send()` 가 thread.id 를 요청에 맞춰 바꾼다
+        "thread/name/set": {},
+        "thread/archive": {},
+        "thread/delete": {},
+        # 슬래시 명령 (이슈 #121)
+        "thread/compact/start": {},
+        "review/start": {
+            "reviewThreadId": "codex-thread-stub",
+            "turn": {"id": "codex-turn-stub", "status": "inProgress", "items": []},
+        },
+        "model/list": {
+            "data": [
+                {
+                    "id": "gpt-5-codex",
+                    "model": "gpt-5-codex",
+                    "displayName": "GPT-5 Codex",
+                    "description": "코딩용 기본 모델",
+                    "hidden": False,
+                    "isDefault": True,
+                    "defaultReasoningEffort": "medium",
+                    "supportedReasoningEfforts": [
+                        {"reasoningEffort": "low", "description": "빠름"},
+                        {"reasoningEffort": "medium", "description": "균형"},
+                        {"reasoningEffort": "high", "description": "깊게"},
+                    ],
+                },
+                {
+                    "id": "gpt-5-mini",
+                    "model": "gpt-5-mini",
+                    "displayName": "GPT-5 mini",
+                    "description": "가벼운 모델",
+                    "hidden": False,
+                    "isDefault": False,
+                    "defaultReasoningEffort": "low",
+                    "supportedReasoningEfforts": [
+                        {"reasoningEffort": "low", "description": "빠름"}
+                    ],
+                },
+            ]
+        },
+        "mcpServerStatus/list": {
+            "data": [
+                {
+                    "name": "bdp",
+                    "authStatus": "unsupported",
+                    "runtimeStatus": "connected",
+                    "tools": {
+                        "query": {"name": "query", "inputSchema": {"type": "object"}}
+                    },
+                    "resources": [],
+                    "resourceTemplates": [],
+                }
+            ]
+        },
+        "skills/list": {
+            "data": [
+                {
+                    "cwd": "/ws",
+                    "errors": [],
+                    "skills": [
+                        {
+                            "name": "pdf",
+                            "description": "PDF 를 읽는다",
+                            "enabled": True,
+                            "path": "/home/u/.codex/skills/pdf/SKILL.md",
+                            "scope": "user",
+                        }
+                    ],
+                }
+            ]
+        },
+        "hooks/list": {
+            "data": [{"cwd": "/ws", "errors": [], "hooks": [], "warnings": []}]
+        },
+    }
+
+    async def send(self, message: Dict[str, Any]) -> None:
+        self.sent.append(message)
+        # 요청에는 즉시 결과를 돌려준다 — 핸드셰이크가 막히지 않게.
+        if "id" in message and message.get("method"):
+            error = self._reject.get(message["method"])
+            if error is not None:
+                self.scripted.insert(
+                    0, {"jsonrpc": "2.0", "id": message["id"], "error": dict(error)}
+                )
+                return
+            result = copy.deepcopy(self.AUTO_RESULT.get(message["method"], {}))
+            thread = result.get("thread")
+            params = message.get("params") or {}
+            if isinstance(thread, dict):
+                # 스레드를 가리키는 요청은 그 스레드로 답하고, fork 는 새 id 를 준다
+                if message["method"] == "thread/fork":
+                    self._forks += 1
+                    thread["id"] = f"codex-thread-fork-{self._forks}"
+                    thread["forkedFromId"] = params.get("threadId")
+                elif params.get("threadId"):
+                    thread["id"] = params["threadId"]
+            self.scripted.insert(
+                0, {"jsonrpc": "2.0", "id": message["id"], "result": result}
+            )
+
+    async def receive(self) -> Optional[Dict[str, Any]]:
+        if not self.scripted:
+            return None
+        return self.scripted.pop(0)
+
+    async def close(self) -> None:
+        self.closed = True
+
+    # 테스트 편의
+    def sent_by_method(self, method: str) -> Dict[str, Any]:
+        for m in self.sent:
+            if m.get("method") == method:
+                return m
+        raise AssertionError(f"보내지 않은 메서드: {method}")
+
+    def responses_for(self, call_id: Any) -> List[Dict[str, Any]]:
+        return [m for m in self.sent if m.get("id") == call_id and "result" in m]
+
+    def errors_for(self, call_id: Any) -> List[Dict[str, Any]]:
+        return [m for m in self.sent if m.get("id") == call_id and "error" in m]
+
+
+#: 스텁 스트림에 넣는 서버 알림. `StubTransport.AUTO_RESULT` 와 같은 이유로
+#: **스냅샷이 요구하는 필수 필드를 다 채운다** — 테스트가 손으로 줄인 알림을
+#: 쓰면 브릿지가 읽는 자리만 맞고 실물과 다른 모양을 검증하게 된다 (이슈 #96).
+# resume·fork 의 응답은 thread/start 와 같은 모양이고, read 는 그 안의 thread 만 준다
+StubTransport.AUTO_RESULT["thread/resume"] = copy.deepcopy(
+    StubTransport.AUTO_RESULT["thread/start"]
+)
+StubTransport.AUTO_RESULT["thread/fork"] = copy.deepcopy(
+    StubTransport.AUTO_RESULT["thread/start"]
+)
+StubTransport.AUTO_RESULT["thread/read"] = {
+    "thread": copy.deepcopy(StubTransport.AUTO_RESULT["thread/start"]["thread"])
+}
+
+
+def stub_turn_completed(
+    status: str = "completed", *, error: Optional[str] = None
+) -> Dict[str, Any]:
+    turn: Dict[str, Any] = {
+        "id": "codex-turn-stub",
+        "items": [],
+        "status": status,
+    }
+    if error is not None:
+        turn["error"] = {"message": error}
+    return {
+        "jsonrpc": "2.0",
+        "method": "turn/completed",
+        "params": {"threadId": "codex-thread-stub", "turn": turn},
+    }
+
+
+def stub_error_notification(
+    message: str, *, will_retry: bool = False
+) -> Dict[str, Any]:
+    return {
+        "jsonrpc": "2.0",
+        "method": "error",
+        "params": {
+            "threadId": "codex-thread-stub",
+            "turnId": "codex-turn-stub",
+            "willRetry": will_retry,
+            "error": {"message": message},
+        },
+    }
+
+
+SseEvent = Tuple[Optional[str], Dict[str, Any]]
+
+
+class WebSocketTransport(Transport):
+    """centri 의 codex app-server 와 WebSocket 으로 JSON-RPC 를 주고받는다.
+
+    codex 는 stdio 가 기본이고 `--listen` 이 실험 기능이다. 서버사이드 codex 는
+    pod 밖에 있어 stdio 를 쓸 수 없으므로 이쪽을 쓴다.
+    """
+
+    def __init__(self, url: str, headers: Dict[str, str]) -> None:
+        self.url = url
+        self.headers = headers
+        self._conn = None
+
+    async def connect(self) -> None:
+        from tornado.httpclient import HTTPClientError, HTTPRequest
+        from tornado.websocket import websocket_connect
+
+        try:
+            self._conn = await websocket_connect(
+                HTTPRequest(self.url, headers=self.headers)
+            )
+        except HTTPClientError as e:
+            rejected = _gateway_rejection(e.code, e.response)
+            if rejected is not None:
+                raise rejected from e
+            raise CodexUnavailable(f"codex 서버에 접속하지 못했습니다: {e}") from e
+        except Exception as e:
+            raise CodexUnavailable(f"codex 서버에 접속하지 못했습니다: {e}") from e
+
+    async def send(self, message: Dict[str, Any]) -> None:
+        if self._conn is None:
+            raise CodexUnavailable("codex 연결이 열려 있지 않습니다.")
+        await self._conn.write_message(json.dumps(message, ensure_ascii=False))
+
+    async def receive(self) -> Optional[Dict[str, Any]]:
+        if self._conn is None:
+            return None
+        raw = await self._conn.read_message()
+        if raw is None:
+            return None
+        try:
+            return json.loads(raw)
+        except (TypeError, ValueError) as e:
+            raise CodexError(f"codex 응답을 해석하지 못했습니다: {e}") from e
+
+    async def close(self) -> None:
+        if self._conn is not None:
+            self._conn.close()
+            self._conn = None
+
+
+#: `AgentFactory._AGENTS_MD_MAX_CHARS` 와 같은 값이어야 한다 — 엔진을 바꿔도 모델이 받는
+#: `AGENTS.md` 길이가 같아야 해서다. 둘이 갈라지면 테스트가 잡는다 (이슈 #99).
+#: 상태 표시(`AgentsMdStatusHandler`)도 이 상수와 글자 수로 "잘림" 을 판정한다.
+AGENTS_MD_MAX_CHARS = 10_000
+
+
+def read_project_instructions(workspace_root: str) -> str:
+    """워크스페이스 루트의 `AGENTS.md` 를 읽는다 (대소문자 무시).
+
+    이슈 #139 에서 `codebuff.md` 를 `AGENTS.md` 로 바꿨다. 옛 이름은 읽지 않는다.
+    client 경로에서는 `AgentFactory._read_agents_md` 가 같은 일을 하는데 그쪽은
+    팩토리 인스턴스에 묶여 있어 codex 경로에서 재사용할 수 없다. 상한도 그쪽과 같다.
+    """
+    try:
+        for name in os.listdir(workspace_root):
+            if name.lower() == "agents.md":
+                path = os.path.join(workspace_root, name)
+                if os.path.isfile(path):
+                    with open(path, encoding="utf-8") as f:
+                        return f.read()[:AGENTS_MD_MAX_CHARS]
+    except OSError:
+        pass
+    return ""
+
+
+def proxy_rules_block(proxy_prefix: str) -> str:
+    """pod 에서 띄운 서버를 사용자가 여는 주소 규칙 (이슈 #136).
+
+    사용자는 pod 밖(관리공간 VDI)에서 주피터 허브가 발급한 URL 로만 들어온다. 그래서
+    포트는 주소의 `:포트` 가 아니라 같은 URL 의 경로(`<base_url>proxy/<포트>/`)로 열리고,
+    `jupyter-server-proxy` 가 pod 안의 `localhost:<포트>` 로 중계한다. 앱은 그 접두
+    아래에서 돌므로 절대경로를 쓰는 앱은 접두를 알아야 한다.
+    """
+    if not proxy_prefix:
+        return ""
+    p = proxy_prefix
+    return (
+        "## pod 포트 열기\n"
+        "사용자는 pod 밖의 브라우저에서 접속하므로 `localhost:<포트>` 는 열리지 않는다. "
+        f"pod 에서 띄운 서버는 같은 주피터 주소에서 경로만 바꾼 `{p}<포트>/` 로 열린다.\n"
+        "- 서버를 띄웠으면 사용자에게 이 주소를 마크다운 링크로 안내한다 "
+        f"(예: 8080 이면 `[열기]({p}8080/)`). localhost 주소를 안내하지 않는다.\n"
+        "- 이 주소는 접두를 떼고 앱에 `/` 부터 넘긴다. streamlit·`python -m http.server` "
+        "처럼 상대경로를 쓰는 앱은 그대로 된다. Spring Boot 는 "
+        "`server.forward-headers-strategy=framework` 로 중계가 보내는 `X-Forwarded-Prefix` 를 따른다.\n"
+        "- base 경로를 자기 경로로 받는 앱은 접두를 떼지 않는 "
+        f"`{p}absolute/<포트>/` 로 열고, 링크와 base 를 끝의 `/` 까지 같은 문자열로 맞춘다. "
+        f"Vite 는 `base: '{p}absolute/<포트>/'` 와 `server.allowedHosts: true` "
+        "(중계가 사용자 Host 를 그대로 넘긴다)를 두고 `server.hmr` 은 건드리지 않는다. "
+        "base 는 기동할 때 읽으므로 이미 띄운 dev 서버는 다시 띄운다."
+    )
+
+
+# 목록의 설명만으로는 gpt-oss-120b 가 이 스킬을 읽지 않았다(0/4, 이슈 #228) — 이름으로 지시한다
+_PYTHON_QUALITY_DIRECTIVE = (
+    "Python 코드(.py 파일·노트북 셀)를 쓰거나 고치기 전에는 반드시 `load_skill` 로 "
+    "`python_code_quality` 스킬을 먼저 읽고 그 원칙을 코드에 반영한다."
+)
+
+
+def developer_context(workspace_root: str, proxy_prefix: str = "") -> str:
+    """`developerInstructions` 에 덧붙일 것 — 사내 플랫폼 규칙, 포트 주소 규칙,
+    `AGENTS.md`, 커스텀 스킬 목록, 내장 스킬 목록.
+
+    사내가 아니고 중계가 없으면 `AGENTS.md` 뒤에 스킬 목록만 붙는다 (이슈 #120, #134,
+    #136). 내장 스킬은 늘 있으므로 목록도 늘 붙는다 (이슈 #219). 목록은 `extra_context`
+    로 들어가 `_mask` 를 거친다.
+    """
+    custom = custom_skills.discover(workspace_root)
+    parts = [
+        platform_rules_block(),
+        proxy_rules_block(proxy_prefix),
+        read_project_instructions(workspace_root),
+        custom_skills.prompt_section(custom, "load_skill"),
+        custom_skills.builtin_section(custom, "load_skill"),
+        _PYTHON_QUALITY_DIRECTIVE,
+    ]
+    return "\n\n".join(p for p in parts if p)
+
+
+def make_codex_transport(endpoint: str, api_key: str) -> WebSocketTransport:
+    """설정의 endpoint 를 WebSocket URL 로 바꾼다.
+
+    `CODEX_SERVER_URL` 은 사람이 적는 값이라 `https://` 로 들어오는 경우가 많다.
+    """
+    if not endpoint:
+        raise CodexUnavailable(
+            "codex 서버 주소가 설정되지 않았습니다. 관리자에게 문의하세요."
+        )
+    url = endpoint.strip()
+    if url.startswith("https://"):
+        url = "wss://" + url[len("https://") :]
+    elif url.startswith("http://"):
+        url = "ws://" + url[len("http://") :]
+    headers = {"Authorization": f"Bearer {api_key}"} if api_key else {}
+    return WebSocketTransport(url, headers)
+
+
+#: centri 준비 신호의 `reason` → 화면이 쓰는 단계 (centri#1860, 이슈 #254 코멘트).
+#: 모르는 `reason` 은 `gateway` 로 둔다 — 연결 안 됨이 맞고 원문은 detail 에 남는다.
+READY_REASON_STAGE = {
+    "unauthorized": "auth",
+    "gateway_key_missing": "gateway",
+    "model_config_missing": "model",
+    "sidecar_unreachable": "bridge",
+}
+
+
+def ready_url(endpoint: str) -> str:
+    """codex ws 주소 옆의 준비 신호 주소 — `…/codex` → `…/codex/ready` (http·https)."""
+    url = endpoint.strip().rstrip("/")
+    if url.startswith("wss://"):
+        url = "https://" + url[len("wss://") :]
+    elif url.startswith("ws://"):
+        url = "http://" + url[len("ws://") :]
+    return url + "/ready"
+
+
+async def check_codex_ready(
+    endpoint: str, api_key: str, timeout: float = 10.0
+) -> Optional[Dict[str, Any]]:
+    """centri 준비 신호를 읽는다. 신호가 없으면 None 이다.
+
+    토큰도 codex 프로세스도 쓰지 않는 확인이다(centri#1860). 신호가 없는 centri
+    (404·다른 모양·접속 실패)는 None 을 돌려주고, 부르는 쪽이 모델 턴으로 대신 잰다 —
+    신호가 없다는 것만으로 연결 안 됨이라 하지 않는다.
+    """
+    headers = {"Authorization": f"Bearer {api_key}"} if api_key else {}
+    try:
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            resp = await client.get(ready_url(endpoint), headers=headers)
+    except httpx.HTTPError:
+        return None
+    # 인증 거부는 본문 모양과 무관하게 인증이다 — 평문으로 와도 "게이트웨이" 로 흐리지 않는다
+    if resp.status_code == 403:
+        return {"ready": False, "reason": "unauthorized"}
+    try:
+        body = resp.json()
+    except ValueError:
+        return None
+    if not isinstance(body, dict) or "ready" not in body:
+        return None
+    return body
+
+
+class CodexProbeFailed(CodexError):
+    """연결 확인이 어느 단계에서 실패했는지 싣는다 (이슈 #254).
+
+    `stage` 는 `gateway`(소켓·인증) · `bridge`(`initialize`) · `model`(모델 턴) 중 하나다.
+    화면은 이 이름으로 무엇이 빠졌는지 보인다.
+    """
+
+    def __init__(self, stage: str, message: str) -> None:
+        super().__init__(message)
+        self.stage = stage
+
+
+#: 모델 턴 확인에 보내는 입력. 짧게 답할 수 있는 것이어야 토큰이 적다.
+PROBE_TURN_PROMPT = "Reply with exactly one word: ok"
+
+
+async def probe_codex(
+    transport: Transport,
+    timeout: float = 10.0,
+    *,
+    model_turn: bool = False,
+    turn_timeout: float = 60.0,
+    prompt: str = PROBE_TURN_PROMPT,
+) -> Dict[str, Any]:
+    """`initialize` 를 왕복해 연결이 사는지 본다. `model_turn` 이면 모델 턴 한 번까지 간다.
+
+    `initialize` 만으로는 주소·인증·프로토콜까지만 판정된다 — 브리지에 모델 키가 빠져도
+    초록이었다(이슈 #254). 그래서 설정 화면의 확인은 `model_turn=True` 로 부른다.
+    그때 스레드는 `ephemeral` 로 열어 codex 쪽에 저장되는 스레드를 남기지 않는다.
+
+    실패는 `CodexProbeFailed` 로 단계(`gateway`·`bridge`·`model`)를 싣는다. 성공하면
+    `initialize` 결과에 모델 턴의 답(`reply`)을 얹어 돌려준다.
+    """
+    try:
+        await asyncio.wait_for(transport.connect(), timeout)
+    except asyncio.TimeoutError as e:
+        raise CodexProbeFailed(
+            "gateway", f"codex 서버가 {timeout:.0f}초 안에 연결을 받지 않았습니다."
+        ) from e
+    except CodexError as e:
+        raise CodexProbeFailed("gateway", str(e)) from e
+
+    next_id = 0
+
+    async def call(method: str, params: Dict[str, Any], stage: str, limit: float):
+        nonlocal next_id
+        next_id += 1
+        call_id = next_id
+        await transport.send(
+            {"jsonrpc": "2.0", "id": call_id, "method": method, "params": params}
+        )
+        deadline = time.monotonic() + limit
+        while True:
+            message = await receive(stage, deadline, limit)
+            if message.get("id") != call_id:
+                # 응답 전에 오는 알림은 확인에 쓸 것이 없다.
+                continue
+            error = message.get("error")
+            if error:
+                raise CodexProbeFailed(
+                    stage, f"codex 가 {method} 를 거부했습니다: {error}"
+                )
+            return message.get("result") or {}
+
+    async def receive(stage: str, deadline: float, limit: float) -> Dict[str, Any]:
+        remaining = deadline - time.monotonic()
+        try:
+            if remaining <= 0:
+                raise asyncio.TimeoutError
+            message = await asyncio.wait_for(transport.receive(), remaining)
+        except asyncio.TimeoutError as e:
+            raise CodexProbeFailed(
+                stage, f"codex 서버가 {limit:.0f}초 안에 응답하지 않았습니다."
+            ) from e
+        if message is None:
+            raise CodexProbeFailed(stage, "codex 서버가 연결을 닫았습니다.")
+        return message
+
+    try:
+        info = await call(
+            "initialize",
+            {
+                "clientInfo": {"name": "codebuff", "version": "1"},
+                "capabilities": {"experimentalApi": True},
+            },
+            "bridge",
+            timeout,
+        )
+        if not model_turn:
+            return info
+        await transport.send({"jsonrpc": "2.0", "method": "initialized"})
+        thread = await call("thread/start", {"ephemeral": True}, "model", timeout)
+        thread_id = (thread.get("thread") or {}).get("id")
+        await call(
+            "turn/start",
+            {"threadId": thread_id, "input": [{"type": "text", "text": prompt}]},
+            "model",
+            timeout,
+        )
+        reply: List[str] = []
+        errors: List[str] = []
+        deadline = time.monotonic() + turn_timeout
+        while True:
+            message = await receive("model", deadline, turn_timeout)
+            method = message.get("method")
+            params = message.get("params") or {}
+            if method == "item/agentMessage/delta":
+                reply.append(str(params.get("delta", "")))
+            elif method == "error" and not params.get("willRetry"):
+                errors.append(str((params.get("error") or {}).get("message", "")))
+            elif method == "turn/completed":
+                turn = params.get("turn") or {}
+                if turn.get("status") != "completed":
+                    detail = (turn.get("error") or {}).get("message") or (
+                        errors[-1] if errors else f"턴 상태 {turn.get('status')}"
+                    )
+                    raise CodexProbeFailed("model", detail)
+                return {**info, "reply": "".join(reply)}
+    finally:
+        await transport.close()
+
+
+class CodexSession:
+    """codex thread 하나의 수명을 든다.
+
+    `run()` 과 `resume()` 은 (event, data) 를 내는 비동기 제너레이터다. `event` 가
+    None 이면 무명 `data:` 줄이고, 그 외에는 `event: <이름>` 줄이 앞에 붙는다.
+    """
+
+    def __init__(
+        self,
+        transport: Transport,
+        *,
+        workspace_root: str,
+        thread_id: str,
+        permission_mode: str = "ask",
+        endpoint: str = "",
+        api_key: str = "",
+        developer_instructions: Optional[str] = None,
+        mode: str = "agent",
+        extra_context: str = "",
+        mask_exempt: str = "",
+        recovery_context: Optional[Callable[[], Optional[str]]] = None,
+        on_record: Optional[Callable[[Dict[str, Any]], None]] = None,
+        on_thread: Optional[Callable[[str, Dict[str, Any]], None]] = None,
+        qa_postprocessor: Any = None,
+    ) -> None:
+        self._t = transport
+        self._workspace_root = workspace_root
+        self._thread_id = thread_id
+        self._permission_mode = (
+            permission_mode if permission_mode in _PERMISSION_POLICY else "ask"
+        )
+        self._endpoint = endpoint
+        # 키 원문은 세션에 남기지 않는다. 중앙 설정이 바뀌었는지만 재사용 판정에 쓴다.
+        self._api_key_digest = hashlib.sha256(api_key.encode("utf-8")).digest()
+        self._mode = mode if mode in {"agent", "chat", "qa"} else "agent"
+        self._developer_instructions = developer_instructions or _mode_instructions(
+            self._mode
+        )
+        self._qa_tool_runners = _qa_tools(workspace_root) if self._mode == "qa" else {}
+        if self._mode == "qa":
+            from codebuff_core.services.rag_chat_agent import CodexQAToolPostprocessor
+
+            # 노트북·EDA 는 테이블 확인 방식·grounding 문구가 다른 후처리기를 넣는다 (이슈 #155)
+            self._qa_postprocessor = qa_postprocessor or CodexQAToolPostprocessor()
+        else:
+            self._qa_postprocessor = None
+        if self._mode == "agent":
+            self._dynamic_tools = CODEX_DYNAMIC_TOOLS
+        elif self._mode == "qa":
+            self._dynamic_tools = [
+                _langchain_tool_spec(tool) for tool in self._qa_tool_runners.values()
+            ]
+        else:
+            self._dynamic_tools = []
+        self._allowed_tools = {spec["name"] for spec in self._dynamic_tools}
+        # 지시문도 pod 밖으로 나간다 — 프롬프트와 같은 마스킹을 건다. 포트 접두
+        # (`mask_exempt`)만 뺀다 — 사번이 전화번호 꼴이면 주소가 지워진다 (이슈 #136)
+        self._extra_context = _mask_except(extra_context, mask_exempt)
+        self._recovery_context = recovery_context
+        self._on_record = on_record or _default_recorder
+        # 이 세션이 **새로 만든** 스레드를 알린다 — ("start"|"fork", thread). 핸들러가
+        # 사용자별 스레드 목록(`/resume`)에 적는다 (이슈 #121)
+        self._on_thread = on_thread
+        # `initialize` 를 마친 연결인가. `/resume` 은 스레드를 새로 열지 않고 이 위에서
+        # 기존 스레드를 붙인다
+        self._initialized = False
+        self._turn_started_at = 0.0
+        self._tool_calls = 0
+        # Q&A 도구 결과가 나온 뒤 본문이 시작되기 전인가 — 프론트의 "분석 중" 표시를 켜고 끈다
+        self._tool_processing = False
+        # 이번 턴에 센 dynamic tool 의 callId — `item/started` 와 실행 지점이 같은
+        # 호출을 두 번 세지 않게 한다 (이슈 #119)
+        self._counted_calls: Set[str] = set()
+        # 이번 턴에 워크스페이스를 바꾸는 도구를 불렀나 — Agent 후속 턴을 가른다 (이슈 #176)
+        self._changed_workspace = False
+        # 요청마다 핸들러가 넣는 UX 세션 id — turn·tool_call 행을 ux_event_hst 에 잇는다 (#98)
+        self.ux_session_id: Optional[str] = None
+        # `thread/tokenUsage/updated` 의 `total` 은 스레드 누적이다. 턴 시작 때 값을
+        # 기준으로 두고 턴 끝의 차이를 그 턴의 토큰으로 본다 (#98)
+        self._usage_total: Optional[Dict[str, int]] = None
+        self._usage_base: Optional[Dict[str, int]] = None
+        # 시작했지만 turn 행을 아직 안 낸 턴이 있다. 승인 대기 중 세션이 닫히면
+        # `_pump` 가 안 돌아 아무도 기록하지 않으므로 `close()` 가 이것을 보고 닫는다 (#98)
+        self._turn_open = False
+        # 빈 답 후속 턴(이슈 #155). `run()` 안에서만 켜진다 — 켜져 있으면 답 없이 끝난 턴의
+        # turn 행을 미뤄 후속 턴까지 한 행으로 적는다(프롬프트 1건 = 1행, #98)
+        self._follow_up_armed = False
+        self._turn_has_answer = False
+        self._next_id = 0
+        self._started = False
+        self._closed = False
+        self._cancelled = False
+        # async generator 본문이 첫 __anext__ 에서 시작되기 전의 경쟁 구간을 막는다.
+        self._request_reserved = False
+        # hitl 로 프론트에 넘긴 도구 호출 — resume 이 이 id 로 회신한다
+        self._pending_call: Optional[Dict[str, Any]] = None
+        # 지금 이 세션에서 턴이 돌고 있는가 (이슈 #93)
+        self._turn_active = False
+        # 턴 밖 슬래시 명령이 소켓을 쓰는 중인가 (이슈 #121)
+        self._slash_active = False
+        # 재사용 턴의 turn/start — codex 가 거부하면 새 스레드로 한 번 다시 연다
+        self._retry_prompt: Optional[str] = None
+        self._retry_call_id: Optional[int] = None
+        # codex 쪽 식별자. `thread_id` 는 코드버프가 만든 것이고 이 둘은 codex 가
+        # 준 것이다 — `turn/start` 와 `turn/interrupt` 가 필수로 요구한다 (이슈 #96).
+        self._codex_thread_id = ""
+        self._codex_turn_id = ""
+        # 핸드셰이크가 응답을 기다리는 동안 먼저 온 알림. 버리면 첫 토큰이 샌다.
+        self._buffered: List[Dict[str, Any]] = []
+        # `thread/start` 응답 — `/status` 가 모델·샌드박스를 여기서 읽는다 (이슈 #121)
+        self._thread_info: Dict[str, Any] = {}
+        # `/model` 로 고른 모델·effort. codex 는 이 값을 "이 턴과 이후 턴" 에 적용하지만
+        # 새 스레드로 다시 열리면 사라지므로 턴마다 싣는다 (이슈 #121)
+        self._model_override: Optional[str] = None
+        self._effort_override: Optional[str] = None
+        # 이미 패널에 띄운 hook 알림 — 같은 문장은 세션당 한 번만 띄운다 (이슈 #145)
+        self._hook_notices: Set[str] = set()
+
+    # --- 내부 ---
+
+    def _new_id(self) -> int:
+        self._next_id += 1
+        return self._next_id
+
+    async def _request(self, method: str, params: Dict[str, Any]) -> int:
+        call_id = self._new_id()
+        await self._t.send(
+            {"jsonrpc": "2.0", "id": call_id, "method": method, "params": params}
+        )
+        return call_id
+
+    async def _notify(self, method: str, params: Dict[str, Any]) -> None:
+        await self._t.send({"jsonrpc": "2.0", "method": method, "params": params})
+
+    async def _respond(self, call_id: Any, result: Dict[str, Any]) -> None:
+        await self._t.send({"jsonrpc": "2.0", "id": call_id, "result": result})
+
+    async def _respond_error(self, call_id: Any, message: str) -> None:
+        """지원하지 않는 서버 요청에는 JSON-RPC 오류로 답한다.
+
+        모양을 모르는 회신을 지어내면 codex 가 역직렬화에서 죽는다. 답을
+        아예 안 하면 턴이 영원히 매달린다 (이슈 #88).
+        """
+        await self._t.send(
+            {
+                "jsonrpc": "2.0",
+                "id": call_id,
+                "error": {"code": -32601, "message": message},
+            }
+        )
+
+    async def _await_response(self, call_id: int, label: str) -> Dict[str, Any]:
+        """요청 하나의 응답을 기다린다. 그 사이 온 알림은 버퍼에 쌓는다.
+
+        **데드라인을 건다.** centri 앞단 게이트웨이가 WebSocket 만 받고 codex 가
+        안 붙은 상태면 소켓이 열린 채 영영 조용하다 — 그러면 SSE 가 아무 출력
+        없이 매달리고, 게이트에서는 실물 테스트가 skip 이 아니라 hang 이 된다.
+        """
+        deadline = time.monotonic() + _HANDSHAKE_TIMEOUT
+        while True:
+            left = deadline - time.monotonic()
+            if left <= 0:
+                raise CodexError(f"codex 가 {label} 에 제때 답하지 않았습니다.")
+            try:
+                message = await asyncio.wait_for(self._t.receive(), timeout=left)
+            except asyncio.TimeoutError:
+                raise CodexError(f"codex 가 {label} 에 제때 답하지 않았습니다.")
+            if message is None:
+                raise CodexError(f"codex 가 {label} 에 답하지 않고 끊었습니다.")
+            if message.get("method") is None and message.get("id") == call_id:
+                if "error" in message:
+                    err = message["error"]
+                    detail = err.get("message") if isinstance(err, dict) else str(err)
+                    raise CodexRejected(f"codex 가 {label} 을 거부했습니다: {detail}")
+                return message
+            self._buffered.append(message)
+
+    def _remember_ids(self, message: Dict[str, Any]) -> None:
+        """지나가는 메시지에서 codex 의 thread/turn id 를 줍는다.
+
+        `turn/start` 는 답을 기다리지 않는다 — 기다리면 첫 토큰까지 스트림이
+        멈춘다. 그래서 turn id 는 그 응답·`turn/started` 알림·도구 호출 중
+        **먼저 오는 것**에서 잡는다. `turn/interrupt` 가 둘 다 요구한다.
+
+        스레드 id 는 **한 번 정해지면 바꾸지 않는다.** codex 는 `thread/started`·
+        `thread/status/changed` 를 모든 연결에 뿌려서(실측 0.154.0), 공유 서버에서는
+        남의 스레드 id 가 이 소켓으로 온다. 덮어쓰면 중지·`/rename`·`/delete` 가 남의
+        스레드를 겨냥한다 (이슈 #121). 스레드를 바꾸는 것은 `_reopen` 과 스레드 전환뿐이다.
+        """
+        for holder in (message.get("params"), message.get("result")):
+            if not isinstance(holder, dict):
+                continue
+            thread = holder.get("thread")
+            tid = ""
+            if isinstance(thread, dict) and thread.get("id"):
+                tid = str(thread["id"])
+            if holder.get("threadId"):
+                tid = str(holder["threadId"])
+            if tid:
+                if not self._codex_thread_id:
+                    self._codex_thread_id = tid
+                elif tid != self._codex_thread_id:
+                    continue
+            turn = holder.get("turn")
+            if isinstance(turn, dict) and turn.get("id"):
+                self._codex_turn_id = str(turn["id"])
+            if holder.get("turnId"):
+                self._codex_turn_id = str(holder["turnId"])
+
+    def _is_foreign(self, params: Any) -> bool:
+        """이 알림이 이 세션의 스레드가 아닌 스레드(서브에이전트)의 것인가."""
+        if not isinstance(params, dict) or not params.get("threadId"):
+            return False
+        own = self._codex_thread_id
+        return bool(own) and str(params["threadId"]) != own
+
+    @staticmethod
+    def _describe_foreign(method: Any, params: Dict[str, Any]) -> Optional[str]:
+        item = params.get("item") or {}
+        if not isinstance(item, dict) or item.get("type") == "reasoning":
+            return None
+        if method == "item/started":
+            line = _describe_started(item)
+        elif method == "item/completed":
+            line = _describe_completed(item)
+        else:
+            return None
+        if not line or line.lstrip("↳ ").startswith("서브에이전트"):
+            return line
+        return _one_line(f"서브에이전트 › {line}")
+
+    def _error_event(
+        self, message: str, gateway_reason: Optional[str] = None
+    ) -> SseEvent:
+        suffix = f" (codex endpoint: {self._endpoint})" if self._endpoint else ""
+        data: Dict[str, Any] = {"error": f"{message}{suffix}"}
+        if gateway_reason:
+            data["gatewayReason"] = gateway_reason
+        return (None, data)
+
+    def _complete_event(self) -> SseEvent:
+        """종료 이벤트. 중단된 턴은 complete 대신 cancelled 로 보고한다."""
+        name = "cancelled" if self._cancelled else "complete"
+        return (name, {"thread_id": self._thread_id})
+
+    def _record(self, event: Dict[str, Any]) -> None:
+        """적재는 부가 기능이다 — 실패해도 스트림을 끊지 않는다."""
+        try:
+            self._on_record(
+                dict(
+                    event,
+                    session_id=self._thread_id,
+                    ux_session_id=self.ux_session_id,
+                    agent_backend="codex",
+                    **_identity(),
+                )
+            )
+        except Exception as e:  # noqa: BLE001 - 적재 실패가 대화를 막으면 안 된다
+            logger.warning("codex 관측 적재 실패: %s", e)
+
+    def _started_line(self, item: Dict[str, Any]) -> Any:
+        """`item/started` 의 진행 줄. Q&A 도구는 LangChain 과 같은 문구(dict)다."""
+        if item.get("type") == "dynamicToolCall":
+            tool = str(item.get("tool") or "")
+            if tool in self._qa_tool_runners:
+                from codebuff_core.services.rag_chat_agent import qa_tool_start_status
+
+                return qa_tool_start_status(tool, item.get("arguments") or {})
+        return _describe_started(item)
+
+    def _count_tool_call(self, tool: str, call_id: Any = None) -> None:
+        """도구 호출 1건을 세고 적재한다 — 실행 위치와 무관하다.
+
+        게이트웨이가 가로채 답한 호출은 `item/tool/call` 이 안 오고 `item/started`
+        만 온다. 그래서 거기서도 세고, 같은 callId 는 한 번만 센다 (이슈 #119).
+        """
+        if call_id:
+            if str(call_id) in self._counted_calls:
+                return
+            self._counted_calls.add(str(call_id))
+        self._tool_calls += 1
+        if tool in _CHANGING_TOOLS:
+            self._changed_workspace = True
+        self._record({"event": "tool_call", "tool_name": tool})
+
+    def _turn_usage(self) -> Dict[str, Optional[int]]:
+        """이번 턴의 토큰. 턴 중 사용량 알림이 없었으면 None (0 이 아니다)."""
+        now = self._usage_total
+        if now is None or now is self._usage_base:
+            return {"input_tokens": None, "output_tokens": None, "cached_tokens": None}
+        base = self._usage_base or {}
+        out: Dict[str, Optional[int]] = {}
+        for col, key in _USAGE_KEYS:
+            diff = now.get(key, 0) - base.get(key, 0)
+            # 누적이 줄었으면 스레드가 새로 열린 것이다 — 기준 없이 지금 값을 쓴다
+            out[col] = diff if diff >= 0 else now.get(key, 0)
+        return out
+
+    @property
+    def turn_open(self) -> bool:
+        """턴이 아직 안 닫혔다 — 스트리밍 중이거나 승인을 기다린다."""
+        return self._turn_open
+
+    def _record_turn(self, status: str) -> None:
+        # 한 턴은 한 번만 닫는다. 중지는 `close()` 가 먼저 적고, `receive()` 에 매달려
+        # 있던 `_pump` 가 소켓이 닫혀 깨어나 한 번 더 적으려 한다 (#98)
+        if not self._turn_open:
+            return
+        self._turn_open = False
+        elapsed = int((time.monotonic() - self._turn_started_at) * 1000)
+        self._record(
+            {
+                # 프롬프트 1건 = 1행이다. client 의 model_call(호출 1건)과 grain 이
+                # 달라 `turn` 으로 가른다 (이슈 #98)
+                "event": "turn",
+                "elapsed_ms": elapsed,
+                "output_tool_calls": self._tool_calls,
+                # `agent_call_hst.status` 는 VARCHAR(64) 다. 넘겨 보내면
+                # INSERT IGNORE 가 경고로 낮춰 **조용히 잘라 넣는다** (이슈 #92).
+                "status": status[:_STATUS_MAX],
+                # 실제로 돈 모델 — 요청 모델이 운영에서 강제로 바뀌어도 행에 남는다 (이슈 #176)
+                "model_name": self._model_override
+                or str(self._thread_info.get("model") or "")
+                or None,
+                **self._turn_usage(),
+            }
+        )
+
+    async def _initialize(self) -> None:
+        """`initialize` 왕복. 연결마다 한 번이다."""
+        await self._await_response(
+            await self._request(
+                "initialize",
+                {
+                    "clientInfo": {"name": "codebuff", "version": "1"},
+                    # dynamicTools 가 experimental 이라 이 플래그가 없으면
+                    # thread/start 가 `-32600 … requires experimentalApi
+                    # capability` 로 **거부된다** (무시가 아니다. 실측 0.154.0,
+                    # `test_codex_live.py::test_dynamic_tools_need_the_flag`).
+                    "capabilities": {"experimentalApi": True},
+                },
+            ),
+            "initialize",
+        )
+        await self._notify("initialized", {})
+        self._initialized = True
+
+    def _thread_params(self) -> Dict[str, Any]:
+        """스레드를 열 때마다 싣는 설정. `thread/resume`·`thread/fork` 도 같은 값을 받는다.
+
+        두 요청에는 `dynamicTools` 필드가 없다 — 도구는 원 스레드의 것이 이어진다
+        (실측 0.154.0: resume 은 새 연결에서, fork 는 같은 연결에서 `list_files` 호출).
+        """
+        params: Dict[str, Any] = {
+            "cwd": self._workspace_root,
+            **_PERMISSION_POLICY[self._permission_mode],
+        }
+        instructions = self._developer_instructions
+        if self._extra_context:
+            instructions = f"{instructions}\n\n{self._extra_context}"
+        # 모드 지시문은 developer 층에 싣는다 (이슈 #155). base·config 는 centri 게이트웨이가
+        # #1774 부터 규칙(`schemas/centri/code_agent_gateway.json` 의 thread_start_config)대로
+        # 통과시킨다 — 그 규칙에 걸리는 값을 넣으면 운영에서만 조용히 빠진다 (이슈 #176)
+        params["developerInstructions"] = instructions
+        if self._mode == "agent":
+            params["baseInstructions"] = prompt_value("codex_agent_base_instructions")
+            # AGENTS.md 는 위 지시문에 이미 있다 — codex 가 cwd 에서 다시 읽으면 두 벌이 된다
+            params["config"] = {
+                "project_doc_max_bytes": 0,
+                "features": dict(_AGENT_NATIVE_SHELL_OFF),
+            }
+            return params
+        # codex 기본 base("You are Codex…")·작업 폴더 AGENTS.md·`/root` 멀티에이전트
+        # 지시문은 LangChain 경로에 없는 입력이라 걷어낸다(실측)
+        params["baseInstructions"] = prompt_value("codex_base_instructions")
+        config = copy.deepcopy(_SEARCH_ONLY_THREAD_CONFIG)
+        config["project_doc_max_bytes"] = 0
+        config["agents"] = {"enabled": False}
+        params["config"] = config
+        return params
+
+    def _adopt(self, result: Dict[str, Any]) -> None:
+        """`thread/start`·`resume`·`fork` 의 응답을 이 세션의 현재 스레드로 삼는다."""
+        thread = result.get("thread") or {}
+        tid = str(thread.get("id") or "") if isinstance(thread, dict) else ""
+        if not tid:
+            raise CodexError("codex 가 thread id 를 돌려주지 않았습니다.")
+        self._codex_thread_id = tid
+        self._codex_turn_id = ""
+        self._thread_info = result
+        # 토큰 누적은 스레드마다 따로다 — 옛 스레드의 누적을 기준으로 두면 키마다 틀린다
+        self._usage_total = None
+        self._usage_base = None
+        self._started = True
+
+    def _announce(self, kind: str, parent: str = "") -> None:
+        if self._on_thread is None:
+            return
+        thread = dict(self._thread_info.get("thread") or {})
+        if parent and not thread.get("forkedFromId"):
+            thread["forkedFromId"] = parent
+        try:
+            self._on_thread(kind, thread)
+        except Exception as e:  # noqa: BLE001 - 목록 기록이 턴을 막으면 안 된다
+            logger.warning("codex 스레드 기록 실패: %s", e)
+
+    async def _handshake(self) -> None:
+        """스레드를 연다. **턴은 시작하지 않는다.**
+
+        `thread/start` 의 응답을 기다려야 한다 — codex 의 thread id 가 그 응답에만
+        있고 `turn/start` 가 그것을 필수로 요구한다. 예전에는 기다리지 않고 바로
+        턴을 얹어서 codex 가 `-32600 missing field 'threadId'` 로 거부했고,
+        그래서 codex 모드는 **한 턴도 성공하지 못했다** (이슈 #96).
+        """
+        if not self._initialized:
+            await self._initialize()
+        started = await self._await_response(
+            await self._request(
+                "thread/start",
+                {**self._thread_params(), "dynamicTools": self._dynamic_tools},
+            ),
+            "thread/start",
+        )
+        self._adopt(started.get("result") or {})
+        self._announce("start")
+
+    async def _reopen_if_thread_is_gone(self, message: Dict[str, Any]) -> bool:
+        """재사용 턴의 `turn/start` 가 거부됐으면 새 스레드로 다시 연다.
+
+        `_start_turn` 은 보내기만 하고 답을 안 기다린다. codex 가 유휴로 스레드를
+        걷었어도 **연결은 살아 있어서**, 그 사실은 소켓 예외가 아니라 이 JSON-RPC
+        오류 응답으로 온다 (이슈 #93). 한 턴에 한 번만 시도한다.
+        """
+        if self._retry_call_id is None or message.get("id") != self._retry_call_id:
+            return False
+        prompt, self._retry_prompt = self._retry_prompt, None
+        self._retry_call_id = None
+        if prompt is None:
+            return False
+        logger.info("codex 가 스레드를 거부해 새로 엽니다")
+        try:
+            await self._reopen(prompt)
+        except Exception as e:  # noqa: BLE001 - 재시도까지 실패하면 원 오류를 보인다
+            logger.error("codex 스레드 재개 실패: %s", e, exc_info=True)
+            return False
+        return True
+
+    async def _reopen(self, prompt: str) -> None:
+        """끊긴 스레드를 걷고 새 스레드로 같은 턴을 다시 시작한다."""
+        if self._recovery_context is not None:
+            recovery = self._recovery_context()
+            if recovery:
+                prompt = _mask(recovery)[0] + "\n\n" + prompt
+        self._started = False
+        self._pending_call = None
+        self._next_id = 0
+        self._retry_prompt = None
+        self._retry_call_id = None
+        self._initialized = False
+        # 새 스레드는 새 id 다. 남겨 두면 `turn/interrupt` 가 죽은 스레드를 가리킨다.
+        self._codex_thread_id = ""
+        self._codex_turn_id = ""
+        self._buffered = []
+        # 새 스레드의 누적은 0 부터 다시 센다 — 옛 누적을 기준으로 두면 키마다 틀린다
+        self._usage_total = None
+        self._usage_base = None
+        try:
+            await self._t.close()
+        except Exception as e:  # noqa: BLE001 - 이미 끊긴 소켓이다
+            logger.debug("끊긴 codex 소켓 정리 실패: %s", e)
+        await self._t.connect()
+        await self._handshake()
+        await self._start_turn(prompt)
+
+    async def _start_turn(self, prompt: str) -> int:
+        """이미 열린 스레드에 턴 하나를 더 얹는다.
+
+        같은 스레드에 실어야 codex 가 앞 턴을 기억한다 (이슈 #93).
+        """
+        self._codex_turn_id = ""
+        params: Dict[str, Any] = {
+            "threadId": self._codex_thread_id,
+            "input": [{"type": "text", "text": prompt}],
+        }
+        if self._model_override:
+            params["model"] = self._model_override
+        if self._effort_override:
+            params["effort"] = self._effort_override
+        return await self._request("turn/start", params)
+
+    # --- 공개 ---
+
+    async def run(self, prompt: str) -> AsyncIterator[SseEvent]:
+        self._turn_started_at = time.monotonic()
+        self._tool_calls = 0
+        self._tool_processing = False
+        self._counted_calls = set()
+        self._changed_workspace = False
+        self._usage_base = self._usage_total
+        self._cancelled = False
+        self._turn_active = True
+        self._turn_open = True
+        self._follow_up_armed = True
+        self._turn_has_answer = False
+        if self._qa_postprocessor is not None:
+            # grounding 이 echo 할 질문은 이력·파일 문맥이 붙기 전의 사용자 원문이다
+            from .langchain_tools import _last_user_message
+
+            self._qa_postprocessor.reset(_last_user_message.get() or prompt)
+        try:
+            masked_prompt, detected = _mask(prompt)
+            if detected:
+                yield (
+                    None,
+                    {"status": f"개인정보를 마스킹해 보냅니다: {', '.join(detected)}"},
+                )
+            try:
+                if self._closed:
+                    raise CodexError("이 codex 세션은 이미 닫혔습니다.")
+                if self._started:
+                    # 두 번째 턴부터는 연결도 thread/start 도 다시 하지 않는다 —
+                    # 새 스레드를 열면 codex 쪽 컨텍스트가 끊긴다 (이슈 #93).
+                    try:
+                        # 거부 응답은 소켓이 아니라 `_pump` 로 온다 — 그 자리에서
+                        # 되살리려고 프롬프트와 호출 id 를 들고 간다.
+                        self._retry_prompt = masked_prompt
+                        self._retry_call_id = await self._start_turn(masked_prompt)
+                    except Exception as e:  # noqa: BLE001
+                        # 소켓 자체가 죽은 경우다. 컨텍스트는 잃지만 턴까지
+                        # 잃지는 않게 새 스레드로 한 번 다시 연다.
+                        logger.info("codex 스레드가 끊겨 새로 엽니다: %s", e)
+                        await self._reopen(masked_prompt)
+                else:
+                    if not self._initialized:
+                        await self._t.connect()
+                    await self._handshake()
+                    await self._start_turn(masked_prompt)
+            except CodexError as e:
+                self._record_turn(f"error:{type(e).__name__}")
+                yield self._error_event(str(e), getattr(e, "reason", None))
+                yield self._complete_event()
+                await self.close()
+                return
+            except Exception as e:  # 네트워크·직렬화 등 예상 못 한 실패
+                logger.error("codex 세션 시작 실패: %s", e, exc_info=True)
+                self._record_turn(f"error:{type(e).__name__}")
+                yield self._error_event(f"codex 서버에 연결하지 못했습니다: {e}")
+                yield self._complete_event()
+                await self.close()
+                return
+
+            while True:
+                held: Optional[SseEvent] = None
+                async for event in self._pump():
+                    # 판정은 `_pump` 가 turn 행을 쓰기 전에 끝냈다 — 행이 아직 열려 있으면
+                    # 후속 턴을 얹을 턴이다. 오류로 끝난 턴은 행이 닫혀 여기 안 걸린다
+                    if event[0] == "complete" and self._awaiting_follow_up():
+                        held = event
+                        continue
+                    yield event
+                if held is None:
+                    break
+                # LangChain 은 답 없이 끝난 턴을 도구 결과로 한 번 더 부른다(`_fallback_llm_call`).
+                # codex 에서는 같은 스레드에 턴을 하나 더 얹는다 — 한 번뿐이다 (이슈 #155)
+                self._follow_up_armed = False
+                yield (None, {"status": "답변이 비어 있어 한 번 더 요청합니다..."})
+                follow_up = (
+                    AGENT_EMPTY_ANSWER_FOLLOW_UP
+                    if self._mode == "agent"
+                    else EMPTY_ANSWER_FOLLOW_UP
+                )
+                try:
+                    self._retry_prompt = follow_up
+                    self._retry_call_id = await self._start_turn(follow_up)
+                except Exception as e:  # noqa: BLE001
+                    logger.info("codex 후속 턴을 열지 못했습니다: %s", e)
+                    self._record_turn("ok")
+                    yield held
+                    break
+        finally:
+            self._follow_up_armed = False
+            self._turn_active = False
+            self._close_unrecorded_turn()
+            self._retry_prompt = None
+            self._retry_call_id = None
+
+    def _awaiting_follow_up(self) -> bool:
+        """`turn/completed` 를 받고도 turn 행을 미뤄 둔 상태 — 후속 턴을 얹는다."""
+        return self._follow_up_armed and self._turn_open and not self._closed
+
+    def _wants_answer_follow_up(self) -> bool:
+        """답 없이 끝난 턴에 후속 턴을 얹을지.
+
+        Agent 는 도구 실행만으로 끝날 수 있다 — 워크스페이스를 바꾼 턴이나 도구를 하나도
+        안 부른 턴은 얹지 않는다. 읽기 도구만 부르고 멈춘 Agent 턴(목록만 보고 끝남)만 한 번
+        이어 가게 한다 (이슈 #176).
+        """
+        if not self._follow_up_armed or self._turn_has_answer:
+            return False
+        if self._cancelled or self._closed:
+            return False
+        if self._mode == "agent" and (self._changed_workspace or not self._tool_calls):
+            return False
+        if self._pending_call is not None:
+            return False
+        post = self._qa_postprocessor
+        return getattr(post, "pending_confirmation", None) is None
+
+    async def resume(self, decision: Dict[str, Any]) -> AsyncIterator[SseEvent]:
+        """사람의 승인·거부를 받아 도구를 마무리하고 스트림을 이어 간다.
+
+        브라우저 도구는 프론트가 이미 실행했으므로 그 결과를 그대로 회신한다.
+        pod 도구는 **승인만 받은 상태**라 여기서 실행한다 — 프론트에는 실행
+        분기가 없어서, 회신만 하면 명령이 안 돌고 성공으로 보고된다 (이슈 #88).
+        """
+        pending = self._pending_call
+        if pending is None:
+            yield self._error_event("재개할 도구 호출이 없습니다.")
+            yield self._complete_event()
+            return
+
+        decision_type = decision.get("type") if isinstance(decision, dict) else None
+        args = decision.get("args") if isinstance(decision, dict) else None
+        invalid_decision = not isinstance(decision_type, str) or decision_type not in {
+            "approve",
+            "edit",
+            "reject",
+        }
+        if decision_type == "edit" and (not isinstance(args, dict) or not args):
+            invalid_decision = True
+        if (
+            decision_type == "approve"
+            and args is not None
+            and not isinstance(args, dict)
+        ):
+            invalid_decision = True
+        self._pending_call = None
+        if invalid_decision:
+            # 실행하지 않았다는 실패를 codex 에 돌려 턴이 승인 대기에 고립되지 않게 한다.
+            await self._respond(
+                pending["id"],
+                _tool_result(
+                    {"success": False, "error": "승인 응답이 올바르지 않습니다."}
+                ),
+            )
+            self._count_tool_call(pending["tool"], pending.get("call_id"))
+
+        # 승인 왕복도 이 스레드를 쓰는 중이다 — 그 사이 새 메시지가 같은 세션에
+        # 얹히면 두 `_pump` 가 한 소켓을 읽는다 (이슈 #93).
+        self._turn_active = True
+        try:
+            # 턴 시작 시각을 다시 찍지 않는다 — 승인 왕복은 턴의 일부다. 다시 찍으면
+            # 승인 대기 시간이 `elapsed_ms` 에서 빠져 codex 가 client 보다 체계적으로
+            # 빨라 보인다 (이슈 #92).
+            tool = pending["tool"]
+            if invalid_decision:
+                pass
+            elif (decision.get("type") or "") == "reject":
+                feedback = (
+                    decision.get("feedback") or "사용자가 이 작업을 거부했습니다."
+                )
+                await self._respond(
+                    pending["id"],
+                    # 거부 사유는 사람이 친 글이라 사용자 입력처럼 엄격하게 가린다 (이슈 #155)
+                    _tool_result(
+                        {"success": False, "error": feedback}, tool_output=False
+                    ),
+                )
+                self._count_tool_call(tool, pending.get("call_id"))
+            elif tool in BROWSER_TOOLS:
+                await self._respond(
+                    pending["id"], _tool_result(decision.get("args") or {})
+                )
+                # 브라우저가 실행했어도 도구 호출 1건이다. 안 세면 codex 에서 가장 잦은
+                # `jupyter_cell` 이 `agent_call_hst` 에서 통째로 빠진다 (이슈 #92).
+                self._count_tool_call(tool, pending.get("call_id"))
+            else:
+                args = (
+                    decision["args"]
+                    if decision_type == "edit"
+                    else decision.get("args") or pending["args"]
+                )
+                violation = tool_call_violation(tool, args)
+                if violation:
+                    await self._respond(
+                        pending["id"],
+                        _tool_result({"success": False, "error": violation}),
+                    )
+                    self._count_tool_call(tool, pending.get("call_id"))
+                    yield (
+                        None,
+                        {"status": "⛔ 수정된 인자가 플랫폼 규칙을 위반했습니다"},
+                    )
+                else:
+                    async for event in self._run_and_respond(
+                        pending["id"], tool, args, pending.get("call_id")
+                    ):
+                        yield event
+
+            async for event in self._pump():
+                yield event
+        finally:
+            self._turn_active = False
+            self._close_unrecorded_turn()
+
+    async def cancel(self) -> None:
+        """도는 턴을 멈춘다.
+
+        `turn/interrupt` 는 알림이 아니라 **요청**이고 `threadId`·`turnId` 를 둘 다
+        요구한다. 예전에는 빈 알림으로 보내서 codex 가 조용히 무시했다 (이슈 #96).
+        """
+        if not self._started or self._closed:
+            return
+        self._cancelled = True
+        if not (self._codex_thread_id and self._codex_turn_id):
+            # 아직 turn id 를 못 잡았다. 보내 봐야 거부되므로 화면 쪽만 취소로 둔다.
+            logger.info("codex turn id 가 없어 turn/interrupt 를 보내지 않습니다")
+            return
+        await self._request(
+            "turn/interrupt",
+            {"threadId": self._codex_thread_id, "turnId": self._codex_turn_id},
+        )
+
+    def mark_cancelled(self) -> None:
+        """사용자가 세션을 걷었다(`/reset`) — 도는 턴이 소켓을 잃어도 오류로 알리지 않는다."""
+        self._cancelled = True
+
+    # --- 슬래시 명령 (이슈 #121) ---
+
+    async def ensure_open(self) -> None:
+        """스레드가 없으면 연다. 턴은 시작하지 않는다.
+
+        `/model`·`/mcp` 처럼 첫 메시지 전에 부를 수 있는 명령이 쓴다. 여기서 연
+        스레드는 다음 턴이 그대로 이어 쓴다 — 핸들러가 같은 세션을 들고 있다.
+        """
+        if self._closed:
+            raise CodexError("이 codex 세션은 이미 닫혔습니다.")
+        if self._started:
+            return
+        # `/resume` 이 거부돼 연결만 열려 있을 수 있다 — 소켓을 두 벌 열지 않는다
+        if not self._initialized:
+            await self._t.connect()
+        await self._handshake()
+
+    async def switch_thread(self, thread_id: str) -> Dict[str, Any]:
+        """기존 스레드(`/resume`)로 옮긴다. 새 스레드는 열지 않는다.
+
+        거부되면(`CodexRejected` — 예: 턴이 한 번도 없어 rollout 이 없는 스레드) 지금
+        스레드를 그대로 둔다. 옮긴 뒤의 `turn/start` 는 새 스레드 id 로 간다.
+        """
+        await self.ensure_connected()
+        result = await self.call(
+            "thread/resume", {"threadId": thread_id, **self._thread_params()}
+        )
+        self._adopt(result)
+        return result
+
+    async def fork_thread(self, kind: str = "fork") -> Dict[str, Any]:
+        """지금 스레드를 문맥째 갈라 그쪽으로 옮긴다 (`/fork`·`/side`).
+
+        `ephemeral` fork 는 쓰지 않는다 — `excludeTurns:true` 를 함께 요구해 문맥이
+        0턴이 된다(실측). 곁가지(`/side`)도 보통 fork 이고 `kind` 로만 구별한다.
+        """
+        await self.ensure_open()
+        parent = self._codex_thread_id
+        result = await self.call(
+            "thread/fork", {"threadId": parent, **self._thread_params()}
+        )
+        self._adopt(result)
+        self._announce(kind, parent)
+        return result
+
+    async def ensure_connected(self) -> None:
+        """연결과 `initialize` 까지만 한다. 스레드는 열지 않는다 (`/resume` 목록)."""
+        if self._closed:
+            raise CodexError("이 codex 세션은 이미 닫혔습니다.")
+        if not self._initialized:
+            await self._t.connect()
+            await self._initialize()
+
+    def leave_thread(self) -> None:
+        """지금 스레드에서 손을 뗀다 (`/archive`·`/delete` 뒤). 다음 턴은 새 스레드다.
+
+        뒤따르는 슬래시 명령은 이 연결 위에 `thread/start` 만 다시 보낸다. 보통
+        메시지는 `reusable` 이 False 라 핸들러가 세션째 새로 연다.
+        """
+        self._started = False
+        self._codex_thread_id = ""
+        self._codex_turn_id = ""
+        self._thread_info = {}
+
+    def restart_thread(
+        self,
+        developer_instructions: Optional[str] = None,
+        dynamic_tools: Optional[List[Dict[str, Any]]] = None,
+    ) -> None:
+        """다음 턴을 새 스레드에서, 바꾼 지시문·도구로 연다. 연결은 그대로 쓴다.
+
+        EDA 는 단계마다 앞 단계의 대화가 섞이지 않아야 한다(LangChain 은 thread_id 를
+        갈았다). 단계마다 세션을 새로 열면 요청 하나가 centri 연결 상한을 여럿
+        차지하므로 한 연결에서 스레드만 바꾼다 (이슈 #155).
+        """
+        self.leave_thread()
+        if developer_instructions is not None:
+            self._developer_instructions = developer_instructions
+        if dynamic_tools is not None:
+            self._dynamic_tools = dynamic_tools
+            self._allowed_tools = {spec["name"] for spec in dynamic_tools}
+
+    @property
+    def qa_postprocessor(self) -> Any:
+        return self._qa_postprocessor
+
+    @property
+    def dynamic_tools(self) -> List[Dict[str, Any]]:
+        """지금 스레드에 알리는 도구 — `restart_thread` 로 뺐다가 되돌릴 때 쓴다."""
+        return list(self._dynamic_tools)
+
+    @contextlib.contextmanager
+    def occupied(self) -> Iterator[None]:
+        """턴 밖 슬래시 명령이 도는 동안 `busy` 로 보이게 한다.
+
+        그 명령도 이 소켓에서 응답을 읽는다. 그 사이 두 번째 요청이 세션을 얻으면
+        응답 프레임을 `_pump` 가 가로채 삼킨다.
+        """
+        self._slash_active = True
+        try:
+            yield
+        finally:
+            self._slash_active = False
+
+    async def call(self, method: str, params: Dict[str, Any]) -> Dict[str, Any]:
+        """턴 밖 요청 하나를 보내고 `result` 를 돌려준다.
+
+        거부는 `CodexRejected` 로 올리고 **세션을 닫지 않는다** — `_pump` 의 오류
+        경로와 다르다. 응답이 안 오거나 소켓이 끊긴 것은 세션이 죽은 것이라 닫는다.
+        """
+        if self._closed:
+            raise CodexError("이 codex 세션은 이미 닫혔습니다.")
+        try:
+            response = await self._await_response(
+                await self._request(method, params), method
+            )
+        except CodexRejected:
+            raise
+        except Exception:
+            await self.close()
+            raise
+        return response.get("result") or {}
+
+    async def run_request(
+        self,
+        method: str,
+        params: Dict[str, Any],
+        *,
+        deadline_s: Optional[float] = None,
+    ) -> AsyncIterator[SseEvent]:
+        """턴을 여는 요청(`thread/compact/start`·`review/start`)을 보내고 턴 끝까지 흘린다.
+
+        두 요청은 응답이 먼저 오고 그 뒤에 turn/started … turn/completed 가 온다
+        (실측 0.154.0). `thread/compacted` 알림은 오지 않았다 — 그래서 끝은
+        `turn/completed` 하나로 본다. 거부 응답은 `run()` 과 달리 세션을 닫지 않는다.
+
+        `deadline_s` 가 지나면 소켓을 닫는다. 열어 두면 늦게 온 `turn/completed` 가
+        다음 턴의 `_pump` 를 그 자리에서 끝내 버린다.
+        """
+        self._turn_started_at = time.monotonic()
+        self._tool_calls = 0
+        self._counted_calls = set()
+        self._usage_base = self._usage_total
+        self._cancelled = False
+        self._turn_active = True
+        try:
+            try:
+                await self.call(method, dict(params, threadId=self._codex_thread_id))
+            except CodexError as e:
+                yield self._error_event(str(e))
+                yield self._complete_event()
+                return
+            self._turn_open = True
+            stream = self._pump()
+            end = None if deadline_s is None else time.monotonic() + deadline_s
+            while True:
+                try:
+                    if end is None:
+                        event = await stream.__anext__()
+                    else:
+                        event = await asyncio.wait_for(
+                            stream.__anext__(), max(0.0, end - time.monotonic())
+                        )
+                except StopAsyncIteration:
+                    return
+                except asyncio.TimeoutError:
+                    self._record_turn("error: 시간 초과")
+                    yield self._error_event(
+                        f"codex 가 {deadline_s:.0f}초 안에 끝내지 않아 세션을 닫았습니다."
+                    )
+                    yield self._complete_event()
+                    await self.close()
+                    return
+                yield event
+        finally:
+            self._turn_active = False
+            self._close_unrecorded_turn()
+
+    def set_model(self, model: Optional[str], effort: Optional[str]) -> None:
+        """다음 `turn/start` 부터 실을 모델·effort. None 이면 서버 기본값이다."""
+        self._model_override = model
+        self._effort_override = effort
+
+    @property
+    def thread_id(self) -> str:
+        """코드버프가 만든 스레드 id (codex 의 것이 아니다)."""
+        return self._thread_id
+
+    @property
+    def started(self) -> bool:
+        return self._started and not self._closed
+
+    @property
+    def busy(self) -> bool:
+        """턴·슬래시 명령이 돌거나 승인을 기다리는 중이다 — 슬래시 명령을 얹으면 안 된다."""
+        return (
+            self._request_reserved
+            or self._turn_active
+            or self._slash_active
+            or self._pending_call is not None
+        )
+
+    def try_reserve(self, *, resume: bool = False) -> bool:
+        """첫 await 전에 이 세션의 소켓 읽기 권한을 한 요청에 예약한다."""
+        if self._request_reserved or self._turn_active or self._slash_active:
+            return False
+        if resume != (self._pending_call is not None):
+            return False
+        self._request_reserved = True
+        return True
+
+    def release_reservation(self) -> None:
+        self._request_reserved = False
+
+    @property
+    def thread_info(self) -> Dict[str, Any]:
+        """`thread/start` 응답. 핸드셰이크 전에는 빈 dict 다."""
+        return self._thread_info
+
+    @property
+    def model_override(self) -> Optional[str]:
+        return self._model_override
+
+    @property
+    def effort_override(self) -> Optional[str]:
+        return self._effort_override
+
+    @property
+    def permission_mode(self) -> str:
+        return self._permission_mode
+
+    @property
+    def mode(self) -> str:
+        return self._mode
+
+    @property
+    def workspace_root(self) -> str:
+        return self._workspace_root
+
+    @property
+    def connection_identity(self) -> Tuple[str, bytes]:
+        """세션을 만든 중앙 접속 설정. 키 원문은 노출하지 않는다."""
+        return self._endpoint, self._api_key_digest
+
+    @property
+    def turn_active(self) -> bool:
+        """유휴 회수에서 보호할 실제 실행 상태 (승인 대기는 제외)."""
+        return self._request_reserved or self._turn_active or self._slash_active
+
+    @property
+    def closed(self) -> bool:
+        return self._closed
+
+    @property
+    def codex_thread_id(self) -> str:
+        """codex 가 준 스레드 id. 핸드셰이크 전에는 빈 문자열이다."""
+        return self._codex_thread_id
+
+    @property
+    def reusable(self) -> bool:
+        """다음 턴을 이 스레드에 실을 수 있는가.
+
+        셋 다 아니어야 한다.
+
+        - 열려 있고 이미 핸드셰이크를 마쳤다
+        - 승인 대기(`_pending_call`)가 없다 — codex 는 그 도구 호출의 회신을
+          기다리는 중이라, 답하지 않은 채 `turn/start` 를 얹으면 두 흐름이 한
+          스레드에서 겹친다. 사용자가 승인 대화상자를 두고 새 메시지를 보내는
+          경로가 실제로 있다
+        - 도는 턴이 없다 — 한 소켓을 두 스트림이 같이 읽으면 codex 의 프레임이
+          둘로 갈린다 (탭 두 개, 취소 없이 끊은 요청의 재시도)
+
+        셋 중 하나라도 아니면 핸들러가 이 세션을 걷고 새 스레드를 연다 —
+        재사용 이전의 동작과 같다 (이슈 #93).
+        """
+        return (
+            self._started
+            and bool(self._codex_thread_id)
+            and not self._closed
+            and self._pending_call is None
+            and not self._request_reserved
+            and not self._turn_active
+            and not self._slash_active
+        )
+
+    def _close_unrecorded_turn(self) -> None:
+        """승인 대기가 아닌데 turn 행 없이 끝났으면 오류로 닫는다.
+
+        회신(`_respond`)이 끊긴 소켓에서 실패하거나 소비자가 스트림을 끊으면 예외가
+        `_pump` 밖으로 새어 기록 지점을 건너뛴다. 승인 대기는 턴이 아직 안 끝난
+        것이라 두고, `resume()` 이나 `close()` 가 닫는다.
+        """
+        if self._turn_open and self._pending_call is None:
+            self._record_turn("error: 턴이 기록 없이 끝남")
+
+    async def close(self) -> None:
+        if self._turn_open:
+            # 턴이 열린 채 닫혔다(승인 대기 중이거나 `_pump` 가 읽는 중에 중지·새 프롬프트·
+            # /reset·유휴 회수·클라이언트 끊김). 깨어난 `_pump` 는 다시 적지 않는다. 안 적으면
+            # 포기한 턴만 분모에서 빠져 codex 의 성공률이 부푼다 (#98)
+            self._record_turn("cancelled" if self._cancelled else "abandoned")
+        if not self._closed:
+            self._closed = True
+            await self._t.close()
+
+    async def _pump(self) -> AsyncIterator[SseEvent]:
+        """종료 이벤트가 나올 때까지 서버 메시지를 읽어 SSE 로 바꾼다."""
+        spoke = False  # 이 스트림에서 agentMessage 본문을 이미 냈는가
+        # Agent 밖(Chat/Q&A/노트북/EDA)은 LangChain 처럼 최종 답만 본문으로 낸다 (이슈 #155).
+        # agentMessage 의 phase 는 `item/started` 에만 오므로 아이템별로 기억한다
+        answer_only = self._mode != "agent"
+        phases: Dict[str, Any] = {}
+        commentary: Dict[str, List[str]] = {}
+        while True:
+            try:
+                # 핸드셰이크가 응답을 기다리는 동안 먼저 온 알림부터 흘린다.
+                message = (
+                    self._buffered.pop(0) if self._buffered else await self._t.receive()
+                )
+            except Exception as e:
+                logger.error("codex 스트림 오류: %s", e, exc_info=True)
+                self._record_turn(f"error: {e}")
+                yield self._error_event(f"codex 스트림이 끊겼습니다: {e}")
+                yield self._complete_event()
+                await self.close()
+                return
+
+            if message is None:
+                # 서버가 종료 알림 없이 끊었다. 프론트가 예외를 던지지 않도록
+                # 여기서 종료 이벤트를 책임지고 낸다.
+                #
+                # 취소해서 끊긴 것은 오류가 아니다. 핸들러가 `cancel()` 직후
+                # 소켓을 닫으므로 `turn/completed{interrupted}` 가 올 자리가
+                # 없고, 그것을 오류로 적으면 **모든 취소가 RDS 에 실패로
+                # 집계된다** — 두 엔진을 같은 축으로 보려던 이슈 #92 의 관측이
+                # 그만큼 왜곡된다.
+                self._record_turn(
+                    "cancelled" if self._cancelled else "error: 종료 알림 없이 끊김"
+                )
+                if not self._cancelled:
+                    yield self._error_event(
+                        "codex 서버 연결이 종료 알림 없이 끊겼습니다."
+                    )
+                yield self._complete_event()
+                await self.close()
+                return
+
+            self._remember_ids(message)
+            method = message.get("method")
+            if method is None:
+                # 우리 요청에 대한 응답 — 오류만 사용자에게 보인다.
+                if "error" in message:
+                    if await self._reopen_if_thread_is_gone(message):
+                        continue
+                    err = message["error"]
+                    detail = err.get("message") if isinstance(err, dict) else str(err)
+                    self._record_turn(f"error: {detail}")
+                    yield self._error_event(f"codex 요청이 거부됐습니다: {detail}")
+                    yield self._complete_event()
+                    await self.close()
+                    return
+                continue
+
+            params = message.get("params") or {}
+
+            if message.get("id") is None and self._is_foreign(params):
+                # 서브에이전트 스레드의 알림 (이슈 #130). 본문·턴 종료·토큰을 부모
+                # 것으로 읽으면 자식의 글이 답에 섞이고, 자식 턴이 끝날 때 부모
+                # 스트림이 닫힌다. 무엇을 하는지만 진행 줄로 보인다. 요청(id 있음)은
+                # 아래로 그대로 보낸다 — 답을 안 하면 자식 턴이 매달린다.
+                line = self._describe_foreign(method, params)
+                if line:
+                    yield (None, {"status": line})
+                continue
+
+            if method == "item/agentMessage/delta":
+                delta = params.get("delta", "")
+                item_id = str(params.get("itemId") or "")
+                if delta and answer_only and phases.get(item_id) == "commentary":
+                    # 도구를 부르기 전의 "찾아보겠습니다" 류. LangChain 은 이것을 본문에
+                    # 안 낸다 — 모아 두었다가 진행 줄 하나로 보인다
+                    commentary.setdefault(item_id, []).append(delta)
+                elif delta:
+                    if self._tool_processing:
+                        self._tool_processing = False
+                        yield (None, {"tool_processing_end": True})
+                    spoke = True
+                    if delta.strip():
+                        self._turn_has_answer = True
+                    yield (None, {"content": delta})
+            elif method == "item/started":
+                item = params.get("item") or {}
+                if item.get("type") == "agentMessage":
+                    phases[str(item.get("id") or "")] = item.get("phase")
+                    if spoke and not (
+                        answer_only and item.get("phase") == "commentary"
+                    ):
+                        # 메시지 경계를 본문에 남긴다 — 없으면 두 메시지가 한 문장으로 붙는다
+                        yield (None, {"content": "\n\n"})
+                if item.get("type") == "dynamicToolCall":
+                    self._count_tool_call(item.get("tool") or "", item.get("id"))
+                if item.get("type") in _TOOL_ITEM_TYPES and answer_only and spoke:
+                    # phase 를 안 주는 모델이다. 도구를 부른 턴의 본문은 LangChain 처럼
+                    # 버린다 — 이미 흘렸으므로 프론트에 지우라고 알린다(`content_clear`).
+                    # #1774 전 게이트웨이는 검색 전용 config 를 버려 셸·웹·MCP 도구도 열렸다
+                    spoke = False
+                    self._turn_has_answer = False
+                    yield (None, {"content_clear": True})
+                line = self._started_line(item)
+                if isinstance(line, dict):
+                    yield (None, line)
+                elif line:
+                    yield (None, {"status": line})
+            elif method == "item/completed":
+                item = params.get("item") or {}
+                item_id = str(item.get("id") or "")
+                if item_id in commentary:
+                    text = str(item.get("text") or "".join(commentary.pop(item_id)))
+                    if text.strip():
+                        yield (None, {"status": _one_line(f"💬 {text}")})
+                    continue
+                if answer_only and item.get("type") == "reasoning":
+                    # LangChain 경로에는 모델의 생각 요약 줄이 없다
+                    continue
+                if item.get("type") == "exitedReviewMode" and not spoke:
+                    # 리뷰 결과는 이 item 의 `review` 에 평문으로 온다. 같은 글이
+                    # agentMessage 로도 흐르면 그쪽이 이미 냈으므로 두 번 싣지 않는다 (이슈 #121)
+                    review = str(item.get("review") or "")
+                    if review:
+                        spoke = True
+                        yield (None, {"content": review})
+                line = _describe_completed(item)
+                if line:
+                    yield (None, {"status": line})
+            elif method == "item/tool/call":
+                async for event in self._handle_tool_call(message):
+                    yield event
+                if self._pending_call is not None or self._closed:
+                    return
+            elif method == "turn/plan/updated":
+                # deepagents 의 write_todos 가 내던 todo 패널과 같은 꼴로 옮긴다 (이슈 #155)
+                if self._mode == "agent":
+                    yield (
+                        "todos",
+                        {
+                            "todos": [
+                                {
+                                    "content": str(step.get("step") or ""),
+                                    "status": _PLAN_STATUS.get(
+                                        str(step.get("status")), "pending"
+                                    ),
+                                }
+                                for step in params.get("plan") or []
+                                if isinstance(step, dict)
+                            ]
+                        },
+                    )
+            elif method == "thread/tokenUsage/updated":
+                total = (params.get("tokenUsage") or {}).get("total")
+                if isinstance(total, dict):
+                    self._usage_total = total
+            elif method == "turn/completed":
+                # **`turn/failed` 라는 알림은 codex 에 없다.** 실패도 이 알림으로
+                # 오고 `turn.status` 가 가른다. 예전에는 무조건 `ok` 로 적재해서
+                # 실패한 턴이 성공으로 집계됐다 (이슈 #96).
+                turn = params.get("turn") or {}
+                status = str(turn.get("status") or "completed")
+                if status == "failed":
+                    error = turn.get("error")
+                    detail = str((error or {}).get("message") or "턴이 실패했습니다.")
+                    self._record_turn(f"error: {detail}")
+                    yield self._error_event(detail)
+                    yield self._complete_event()
+                    await self.close()
+                    return
+                if status == "interrupted":
+                    self._cancelled = True
+                if status == "completed" and self._wants_answer_follow_up():
+                    # 답 없이 끝났다 — `run()` 이 후속 턴을 얹고, 그 턴이 이 행을 닫는다
+                    pass
+                else:
+                    self._record_turn("ok" if status == "completed" else status)
+                yield self._complete_event()
+                # 소켓을 열어 둔다 — 다음 턴이 같은 스레드에 실려야 codex 가 앞
+                # 턴을 기억한다 (이슈 #93). 회수는 http_handlers 의
+                # `_sweep_codex_sessions` 가 유휴 TTL 로 한다. 실패 경로는
+                # 위처럼 그대로 닫는다 — 끊긴 소켓은 재사용할 수 없다.
+                return
+            elif method == "error":
+                # 본문은 `params.error.message` 다. `params.message` 를 읽던 탓에
+                # 모든 오류가 "알 수 없는 오류" 로 보였다 (이슈 #96).
+                info = params.get("error")
+                raw = (info or {}).get("message") if isinstance(info, dict) else info
+                # `str()` 을 바깥에 두면 `str(None)` 이 `"None"` 이라 폴백 문구에
+                # 영영 안 닿는다 — 본문 없는 알림이 화면에 `None` 으로 나갔다.
+                detail = str(raw) if raw else "알 수 없는 오류"
+                if params.get("willRetry"):
+                    # codex 가 스스로 다시 시도한다 — 턴은 아직 안 끝났다.
+                    yield (None, {"status": f"codex 재시도: {detail}"})
+                    continue
+                self._record_turn(f"error: {detail}")
+                yield self._error_event(detail)
+                yield self._complete_event()
+                await self.close()
+                return
+            elif message.get("id") is not None:
+                # id 가 있으면 **요청**이다. 답을 안 하면 codex 턴이 영원히
+                # 매달려 스트림이 종료 이벤트 없이 끊긴다 (이슈 #88).
+                # 회신 모양은 메서드마다 다르다 — 도구 결과 봉투로 다 답하면
+                # codex 가 역직렬화에서 죽는다 (이슈 #96).
+                decline = _DECLINE_RESPONSE.get(method)
+                if decline is not None:
+                    logger.info("codex 의 네이티브 승인 요청을 거절합니다: %s", method)
+                    await self._respond(message.get("id"), dict(decline))
+                else:
+                    await self._respond_error(
+                        message.get("id"),
+                        f"코드버프가 지원하지 않는 요청입니다: {method}",
+                    )
+            # 그 밖의 알림(thread/started, turn/started, 명령 출력 delta 등)은
+            # 흘려보낸다. 명령 출력은 답변이 아니라서 본문에 섞지 않는다.
+
+    async def _handle_tool_call(
+        self, message: Dict[str, Any]
+    ) -> AsyncIterator[SseEvent]:
+        params = message.get("params") or {}
+        tool = params.get("tool", "")
+        args = params.get("arguments") or {}
+        if tool not in self._allowed_tools:
+            self._count_tool_call(tool, params.get("callId"))
+            error = f"{self._mode} 모드에서 허용되지 않은 도구입니다: {tool}"
+            yield (None, {"status": f"⛔ {error}"})
+            await self._respond(
+                message.get("id"),
+                _tool_result({"success": False, "error": error}),
+            )
+            return
+        if self._mode == "qa":
+            # 같은 callId 는 한 번만 센다 — `item/started` 가 먼저 셌어도 그대로다
+            self._count_tool_call(tool, params.get("callId"))
+            if self._tool_calls > QA_MAX_TOOL_CALLS:
+                # LangChain 은 여기서 스트림을 끊어 답이 없었다. codex 는 턴을 살려
+                # 모은 결과로 답하게 한다 (이슈 #155)
+                yield (
+                    None,
+                    {
+                        "status": f"도구 호출 횟수 제한({QA_MAX_TOOL_CALLS}회)에 "
+                        "도달하여 중단합니다."
+                    },
+                )
+                await self._respond(
+                    message.get("id"),
+                    _tool_result(
+                        {
+                            "success": False,
+                            "error": f"도구 호출 한도({QA_MAX_TOOL_CALLS}회)에 "
+                            "도달했습니다. 도구를 더 부르지 말고 지금까지의 결과로 답하세요.",
+                        }
+                    ),
+                )
+                return
+        # 사내에서 boto3 를 직접 쓰는 코드는 사람에게 묻기 전에 돌려보낸다 — 어차피 실패할
+        # 것을 승인받지 않는다. 모델이 오류를 읽고 bdpengine 으로 고쳐 다시 부른다 (이슈 #120).
+        violation = tool_call_violation(tool, args)
+        if violation:
+            self._count_tool_call(tool, params.get("callId"))
+            yield (
+                None,
+                {"status": "⛔ boto3 직접 사용 — bdpengine 으로 다시 쓰게 했습니다"},
+            )
+            yield (
+                "tool_call",
+                {
+                    "id": str(message.get("id") or ""),
+                    "tool": tool,
+                    "name": tool,
+                    "arguments": args,
+                },
+            )
+            await self._respond(
+                message.get("id"), _tool_result({"success": False, "error": violation})
+            )
+            return
+        needs_browser = tool in BROWSER_TOOLS
+        needs_approval = self._permission_mode == "ask" and tool in GUARDED_POD_TOOLS
+
+        if needs_browser or needs_approval:
+            self._pending_call = {
+                "id": message.get("id"),
+                "call_id": params.get("callId"),
+                "tool": tool,
+                "args": args,
+            }
+            yield (
+                "hitl_request",
+                {
+                    "thread_id": self._thread_id,
+                    "action": _ACTION_NAME_MAP.get(tool, tool + "_tool"),
+                    "args": args,
+                    "description": params.get("description")
+                    or _hitl_description(tool, args),
+                    "actionCount": 1,
+                    "autoApprove": self._permission_mode == "bypass",
+                },
+            )
+            return
+
+        async for event in self._run_and_respond(
+            message.get("id"), tool, args, params.get("callId")
+        ):
+            yield event
+
+    async def _run_and_respond(
+        self,
+        call_id: Any,
+        tool: str,
+        args: Dict[str, Any],
+        codex_call_id: Optional[str] = None,
+    ) -> AsyncIterator[SseEvent]:
+        """pod 도구를 실행하고 결과를 codex 에 회신한다.
+
+        셸 명령은 출력을 한 줄씩(`│ `) 패널에 흘리고, 파일 변경은 diff 를 보인다 —
+        터미널에서 codex CLI 를 쓸 때 보이는 것을 사이드패널에서도 본다.
+        """
+        before = _read_for_diff(tool, args, self._workspace_root)
+        # 빈 기존 파일도 `before` 가 "" 라 존재 여부는 따로 본다 — hook 의 Add/Update 헤더
+        target = _resolve_in_workspace(args.get("path") or "", self._workspace_root)
+        is_new_file = before == "" and not (target and os.path.isfile(target))
+        result_success: Optional[bool] = None
+        try:
+            if tool == "write_todos":
+                todos = _todos_from_args(args)
+                if todos is None:
+                    # LangChain 은 pydantic 검증이 실행 전에 거부한다 — 모델이 고쳐 다시 부른다
+                    result = {"success": False, "error": _TODOS_ARG_ERROR}
+                else:
+                    if todos:
+                        yield ("todos", {"todos": todos})
+                    # langchain `TodoListMiddleware`(deepagents 가 쓰는 것)의 회신 문구와 같다
+                    result = {
+                        "success": True,
+                        "result": f"Updated todo list to {todos}",
+                    }
+            elif tool == "execute_command" and not args.get("background"):
+                result = None
+                async for kind, payload in _stream_command(
+                    args.get("command", ""),
+                    self._workspace_root,
+                    _idle_timeout(args),
+                ):
+                    if kind == "output":
+                        yield (None, {"status": payload})
+                    else:
+                        result = payload
+                yield (None, {"status": _command_summary(result)})
+            else:
+                runner = self._qa_tool_runners.get(tool)
+                if runner is not None:
+                    result, raw_result = await self._qa_postprocessor.invoke(
+                        tool,
+                        args,
+                        str(codex_call_id or call_id or ""),
+                        runner.ainvoke,
+                    )
+                    result_success = _succeeded(raw_result)
+                    from codebuff_core.services.rag_chat_agent import (
+                        qa_tool_end_status,
+                    )
+
+                    done = qa_tool_end_status(tool, raw_result, args)
+                    if done:
+                        yield (None, done)
+                        if not self._tool_processing:
+                            # 결과를 읽는 동안 패널이 "분석 중" 을 띄운다 (LangChain 과 같다)
+                            self._tool_processing = True
+                            yield (None, {"tool_processing": True})
+                else:
+                    result = await run_pod_tool(
+                        tool, args, self._workspace_root, owner=self._thread_id
+                    )
+        except Exception as e:
+            logger.error("codex 도구 실행 실패 (%s): %s", tool, e, exc_info=True)
+            result = {"success": False, "error": str(e)}
+        succeeded = result_success if result_success is not None else _succeeded(result)
+        process = _process_event(tool, args, result)
+        if process is not None:
+            # 패널의 프로세스 스트립이 이 이벤트로 행을 넣고 뺀다 (이슈 #130)
+            yield ("process", process)
+        outcome = codex_hooks.Outcome()
+        if self._mode == "agent" and succeeded:
+            # hook 이 무엇을 던져도 회신은 나가야 한다 — 안 나가면 codex 턴이 매달린다 (이슈 #88)
+            try:
+                async for event in self._post_tool_use(
+                    codex_call_id or call_id, tool, args, is_new_file, result, outcome
+                ):
+                    yield event
+            except Exception as e:
+                logger.error("codex hook 실행 실패 (%s): %s", tool, e, exc_info=True)
+                outcome.messages.append(f"hook 을 돌리지 못했습니다: {e}")
+                yield (None, {"status": outcome.messages[-1]})
+        if before is not None and succeeded:
+            diff = _diff_lines(args.get("path", ""), before, self._workspace_root)
+            if diff:
+                yield (None, {"status": diff})
+        self._count_tool_call(tool, codex_call_id)
+        # `tool` 키는 프론트(`ApiService`)가 이 이벤트를 알아보는 조건이다.
+        yield (
+            "tool_call",
+            {
+                "id": str(call_id or ""),
+                "tool": tool,
+                "name": tool,
+                "arguments": args,
+            },
+        )
+        await self._respond(
+            call_id,
+            _with_hook_outcome(_tool_result(result, success=succeeded), outcome),
+        )
+
+    async def _post_tool_use(
+        self,
+        tool_use_id: Any,
+        tool: str,
+        args: Dict[str, Any],
+        is_new_file: bool,
+        result: Any,
+        outcome: "codex_hooks.Outcome",
+    ) -> AsyncIterator[SseEvent]:
+        """codex `PostToolUse` hook 을 pod 에서 돌린다 (이슈 #145, `codex_hooks`).
+
+        도구가 성공했을 때만 부른다. 결과는 `outcome` 에 모이고 회신 봉투에 반영된다.
+        diff 보다 먼저 돌아서, autofix 가 고친 것까지 패널 diff 에 보인다.
+        """
+        errors: List[str] = []
+        hooks = codex_hooks.discover(self._workspace_root, errors)
+        name = codex_hooks.codex_tool_name(tool)
+        matched = [h for h in hooks if codex_hooks.matches(h.matcher, name)]
+        if self._permission_mode == "ask":
+            skipped = [h for h in matched if h.scope == "repo"]
+            matched = [h for h in matched if h.scope != "repo"]
+            if skipped:
+                sources = ", ".join(sorted({h.source for h in skipped}))
+                errors.append(
+                    f"ask 모드라 저장소 hook {len(skipped)}개를 건너뜀 ({sources}) — "
+                    "승인 없이 명령이 돌면 안 되므로 bypass 모드에서만 돈다"
+                )
+        if matched:
+            payload = codex_hooks.build_payload(
+                tool=tool,
+                args=args,
+                is_new_file=is_new_file,
+                tool_response=result
+                if isinstance(result, str)
+                else json.dumps(result, ensure_ascii=False, default=str),
+                tool_use_id=str(tool_use_id if tool_use_id is not None else ""),
+                cwd=self._workspace_root,
+                session_id=self._codex_thread_id,
+                turn_id=self._codex_turn_id,
+                model=self._model_override or str(self._thread_info.get("model") or ""),
+                permission_mode=self._permission_mode,
+            )
+            env = _command_env()
+            for hook in matched:
+                if hook.status_message:
+                    yield (None, {"status": hook.status_message})
+                try:
+                    run = await codex_hooks.run_hook(
+                        hook, payload, self._workspace_root, env
+                    )
+                except OSError as e:
+                    outcome.messages.append(f"hook 을 실행하지 못했습니다: {e}")
+                    continue
+                codex_hooks.interpret(hook, run, outcome)
+        # 실패·시간 초과는 매번, 설정 오류·건너뜀·systemMessage 는 세션당 한 번 띄운다
+        for message in outcome.messages:
+            yield (None, {"status": message})
+        for message in errors + outcome.notices:
+            if message not in self._hook_notices:
+                self._hook_notices.add(message)
+                yield (None, {"status": message})
+
+
+def _with_hook_outcome(
+    reply: Dict[str, Any], outcome: "codex_hooks.Outcome"
+) -> Dict[str, Any]:
+    """hook 결과를 회신 봉투에 싣는다 — codex 가 모델에 넘기는 방식과 같다.
+
+    `block` 은 실행을 되돌리지 않고 결과 텍스트를 이유로 바꾸고,
+    `additionalContext` 는 결과 뒤에 덧붙는다.
+    """
+    item = reply["contentItems"][0]
+    if outcome.block_reason is not None:
+        item["text"] = _mask(outcome.block_reason)[0]
+    if outcome.context:
+        item["text"] += "\n\n" + _mask("\n".join(outcome.context))[0]
+    return reply
+
+
+def _succeeded(result: Any) -> bool:
+    """도구 결과가 성공인지 본다.
+
+    pod 도구(`langchain_tools`)는 성공도 실패도 **JSON 문자열**로 돌려주고,
+    프론트가 실행한 결과는 `execution_result` 안에 성패가 들어 있다. 겉 타입만
+    보면 "파일 없음" 도 성공으로 회신된다 (이슈 #88).
+    """
+    if isinstance(result, str):
+        try:
+            parsed = json.loads(result)
+        except (ValueError, TypeError):
+            return True
+        return _succeeded(parsed) if isinstance(parsed, dict) else True
+    if not isinstance(result, dict):
+        return True
+    if "success" in result:
+        return bool(result["success"])
+    if "error" in result:
+        return not result["error"]
+    inner = result.get("execution_result")
+    return _succeeded(inner) if isinstance(inner, (dict, str)) else True
+
+
+def _tool_result(
+    result: Any, success: Optional[bool] = None, tool_output: bool = True
+) -> Dict[str, Any]:
+    """codex 가 기대하는 도구 응답 봉투로 감싼다.
+
+    `tool_output=False` 는 사람이 친 글(거부 사유)을 싣는 회신이다 — 프롬프트처럼 가린다.
+    """
+    if success is None:
+        success = _succeeded(result)
+    return {
+        "contentItems": [
+            {"type": "inputText", "text": mask_tool_output(result, tool_output)}
+        ],
+        "success": success,
+    }
+
+
+def mask_tool_output(result: Any, tool_output: bool = True) -> str:
+    """도구 결과를 가려 모델에 보낼 문자열로 만든다.
+
+    LangChain Agent 경로(`PiiMaskMiddleware`)도 같은 규칙을 쓴다 (이슈 #155).
+    """
+    payload = result
+    # JSON 객체·배열 문자열(read_file 결과)만 연다 — `1e5` 같은 텍스트가 숫자로 바뀌면 안 된다
+    if isinstance(result, str) and result.lstrip()[:1] in ("{", "["):
+        try:
+            payload = json.loads(result)
+        except ValueError:
+            payload = result
+    # 도구 결과는 파일 내용·명령 출력이라 그대로 pod 밖으로 나간다. 식별자 숫자가
+    # 흔해서 카드·건강보험에는 문맥 조건을 더한 모드로 가린다 (이슈 #155).
+    # 직렬화한 뒤에 가리면 줄바꿈이 `\n` 두 글자가 되어 줄머리 번호를 못 잡으므로,
+    # 문자열 값마다 먼저 가리고 직렬화한다.
+    masked = _mask_leaves(payload, tool_output)
+    if not isinstance(masked, str):
+        masked = json.dumps(masked, ensure_ascii=False, default=str)
+    return masked
+
+
+def _mask_leaves(value: Any, tool_output: bool, key: Any = None) -> Any:
+    """JSON 값의 문자열마다 `mask_pii` 를 건다.
+
+    값 앞에 키를 붙여 가린다 — `card_no`·`snapshot_id` 같은 키가 문맥 판정의 근거라서다.
+    마스킹은 같은 길이 `*` 로 바꾸므로 붙인 접두만큼 잘라 내면 값이 남는다.
+    """
+    if isinstance(value, str):
+        prefix = f"{key}: " if isinstance(key, str) else ""
+        masked = mask_pii(prefix + value, tool_output=tool_output).masked_text
+        return masked[len(prefix) :]
+    if isinstance(value, dict):
+        return {
+            _mask_leaves(k, tool_output) if isinstance(k, str) else k: _mask_leaves(
+                v, tool_output, k
+            )
+            for k, v in value.items()
+        }
+    if isinstance(value, (list, tuple)):
+        return [_mask_leaves(v, tool_output, key) for v in value]
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        # 숫자로 온 번호도 직렬화 전처럼 가린다. 가려지면 문자열로 바뀐다
+        masked = _mask_leaves(str(value), tool_output, key)
+        return value if masked == str(value) else masked
+    if value is None or isinstance(value, bool):
+        return value
+    # 그 밖의 객체는 직렬화가 `default=str` 로 문자열이 되므로 그 문자열을 가린다
+    return _mask_leaves(str(value), tool_output, key)
+
+
+def _process_event(tool: str, args: Dict[str, Any], result: Any) -> Optional[Dict]:
+    """백그라운드 시작·종료 결과를 SSE `process` 이벤트 데이터로."""
+    if not isinstance(result, dict) or not result.get("success"):
+        return None
+    if tool == "kill_process" or (tool == "execute_command" and args.get("background")):
+        keys = ("id", "pid", "command", "state", "exit_code", "ports", "elapsed_s")
+        return {k: result.get(k) for k in keys}
+    return None
+
+
+async def run_pod_tool(
+    tool: str, args: Dict[str, Any], workspace_root: str, owner: str = ""
+) -> Any:
+    """pod 안에서 끝나는 도구를 실행한다. 기존 LangChain 도구를 그대로 쓴다.
+
+    `owner` 는 백그라운드 프로세스를 띄운 대화(codebuff thread_id)이고 표시용이다.
+    레지스트리는 대화와 무관한 전역이라 대화를 리셋해도 프로세스는 남는다
+    (`background_procs` 모듈 설명).
+    """
+    bg = background_procs
+    from . import langchain_tools as lt
+
+    if tool == "execute_command" and args.get("background"):
+        return await asyncio.to_thread(
+            bg.start,
+            args.get("command", ""),
+            workspace_root,
+            _command_env(),
+            owner,
+        )
+    if tool == "list_processes":
+        return await asyncio.to_thread(bg.list_processes)
+    if tool == "read_process_output":
+        return await asyncio.to_thread(
+            bg.read_output, str(args.get("process_id", "")), args.get("tail")
+        )
+    if tool == "kill_process":
+        return await asyncio.to_thread(bg.kill, str(args.get("process_id", "")))
+    if tool == "execute_command":
+        result: Dict[str, Any] = {}
+        async for kind, payload in _stream_command(
+            args.get("command", ""), workspace_root, _idle_timeout(args)
+        ):
+            if kind == "done":
+                result = payload
+        return result
+    if tool == "edit_file":
+        return await asyncio.to_thread(_edit_file, args, workspace_root)
+    if tool == "load_skill":
+        return await asyncio.to_thread(_load_skill, args, workspace_root)
+
+    factories = {
+        "read_file": lt.create_file_read_tool,
+        "write_file": lt.create_file_write_tool,
+        "list_files": lt.create_file_list_tool,
+        "search_code": lt.create_search_code_tool,
+    }
+    if tool not in factories:
+        return {"success": False, "error": f"알 수 없는 도구: {tool}"}
+    factory = factories[tool]
+    payload = {k: v for k, v in args.items() if k in POD_TOOL_ARGS[tool]}
+    result = await asyncio.to_thread(factory(workspace_root).invoke, payload)
+    if tool == "read_file":
+        result = _cap_read(result)
+    return result
+
+
+_TODOS_ARG_ERROR = "todos 는 {content: 문자열, status: pending|in_progress|completed} 객체의 목록이어야 합니다."
+
+
+def _todos_from_args(args: Dict[str, Any]) -> Optional[List[Dict[str, str]]]:
+    """`write_todos` 인자를 todo 패널 꼴로. 스키마에 안 맞으면 None — 고쳐 부르게 한다."""
+    todos = args.get("todos")
+    if not isinstance(todos, list):
+        return None
+    out = []
+    for item in todos:
+        if not isinstance(item, dict):
+            return None
+        content, status = item.get("content"), item.get("status")
+        if not isinstance(content, str) or not isinstance(status, str):
+            return None
+        if status not in _TODO_STATUSES:
+            return None
+        out.append({"content": content, "status": status})
+    return out
+
+
+def _load_skill(args: Dict[str, Any], workspace_root: str) -> Dict[str, Any]:
+    """호출 때마다 다시 찾는다 — 대화 중에 사용자가 스킬을 더해도 보인다.
+
+    같은 이름이면 커스텀(포털) 스킬이 내장 스킬을 이긴다 (이슈 #202, #219).
+    """
+    skills = custom_skills.with_builtin(custom_skills.discover(workspace_root))
+    body = custom_skills.load_body(str(args.get("name") or ""), skills)
+    # 오류 문장은 전부 "Error: " 로 시작한다. "Error handling …" 같은 본문을 실패로 읽지 않는다
+    if body.startswith("Error: "):
+        return {"success": False, "error": body}
+    return {"success": True, "content": body}
+
+
+def _cap_read(result: str) -> str:
+    """큰 파일은 앞부분만 돌려주고 나머지를 읽는 법을 적는다."""
+    data = json.loads(result)
+    content = (data.get("data") or {}).get("content")
+    if not isinstance(content, str) or len(content) <= _READ_FILE_MAX_CHARS:
+        return result
+    data["data"]["content"] = (
+        content[:_READ_FILE_MAX_CHARS]
+        + f"\n… (전체 {len(content)}자 중 앞 {_READ_FILE_MAX_CHARS}자에서 잘랐다. "
+        "나머지는 search_code 나 execute_command 의 `sed -n '시작,끝p'` 로 읽는다) …"
+    )
+    return json.dumps(data, ensure_ascii=False)
+
+
+def _idle_timeout(args: Dict[str, Any]) -> int:
+    # 0·음수·못 읽는 값은 "한도 없음" 이 아니라 기본값이다 — `0` 과 `"0"` 이 갈리지 않게 (#100)
+    try:
+        value = int(args.get("timeout") or 0)
+    except (TypeError, ValueError):
+        value = 0
+    if value <= 0:
+        return _COMMAND_IDLE_TIMEOUT
+    return min(value, _COMMAND_HARD_LIMIT)
+
+
+def _command_env() -> Dict[str, str]:
+    """셸 명령의 환경. 사람이 이미 정한 인덱스는 덮지 않는다.
+
+    uv 는 `PIP_INDEX_URL` 을 안 보고 `UV_DEFAULT_INDEX`(옛 `UV_INDEX_URL`)를 본다.
+    """
+    env = dict(os.environ)
+    url = read_pip_index_url(_PIP_INDEX_FILE)
+    if url:
+        env.setdefault("PIP_INDEX_URL", url)
+        if "UV_INDEX_URL" not in env:
+            env.setdefault("UV_DEFAULT_INDEX", url)
+    return env
+
+
+async def _stream_command(
+    command: str, workspace_root: str, idle_timeout: int
+) -> AsyncIterator[Tuple[str, Any]]:
+    """셸 명령을 돌리며 출력을 `("output", 줄들)` 로 흘리고 끝에 `("done", 결과)` 를 낸다.
+
+    한도는 **출력이 없는 시간**이다. mvn 첫 빌드처럼 오래 걸려도 출력이 이어지면
+    살아 있는 것이므로 끊지 않는다. 절대 한도(`_COMMAND_HARD_LIMIT`)만 따로 건다.
+    """
+    if not command:
+        yield ("done", {"success": False, "error": "명령이 비어 있습니다."})
+        return
+    started = time.monotonic()
+    proc = await asyncio.create_subprocess_shell(
+        command,
+        cwd=workspace_root if os.path.isdir(workspace_root) else None,
+        # 서버의 stdin(소켓)을 물려받으면 대화형 명령이 무출력 한도까지 매달린다 (#100)
+        stdin=asyncio.subprocess.DEVNULL,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.STDOUT,
+        # 셸이 띄운 자식(java 등)까지 한 번에 끊으려고 프로세스 그룹을 따로 둔다
+        start_new_session=True,
+        env=_command_env(),
+    )
+    try:
+        async for event in _pump_command(proc, command, started, idle_timeout):
+            yield event
+    finally:
+        # 턴 취소·SSE 끊김·세션 회수로 제너레이터가 닫히면 여기로 온다. 셸이 아직
+        # 살아 있으면 그 그룹(셸이 띄운 자식 포함)을 거둔다 — 안 그러면 고아가 된다 (#130)
+        if proc.returncode is None:
+            _kill_group(proc)
+            await proc.wait()
+
+
+async def _pump_command(
+    proc: Any, command: str, started: float, idle_timeout: int
+) -> AsyncIterator[Tuple[str, Any]]:
+    decoder = codecs.getincrementaldecoder("utf-8")(errors="replace")
+    collected: List[str] = []
+    pending = ""
+    error = ""
+    while True:
+        remaining = _COMMAND_HARD_LIMIT - (time.monotonic() - started)
+        wait = min(idle_timeout, remaining)
+        try:
+            if wait <= 0:
+                raise asyncio.TimeoutError
+            chunk = await asyncio.wait_for(proc.stdout.read(4096), timeout=wait)
+        except asyncio.TimeoutError:
+            if remaining <= idle_timeout:
+                error = f"{_COMMAND_HARD_LIMIT}초를 넘겨 멈췄습니다"
+            else:
+                error = f"{idle_timeout}초 동안 출력이 없어 멈췄습니다"
+            break
+        if not chunk:
+            break
+        text = decoder.decode(chunk)
+        collected.append(text)
+        pending += text
+        lines = pending.split("\n")
+        pending = lines.pop()
+        if lines:
+            yield ("output", "\n".join("│ " + line for line in lines))
+    pending += decoder.decode(b"", final=True)
+    if pending:
+        yield ("output", "│ " + pending)
+    output = _truncate_output("".join(collected))
+    elapsed = round(time.monotonic() - started, 1)
+    if error:
+        _kill_group(proc)
+        await proc.wait()
+        yield (
+            "done",
+            {
+                "success": False,
+                "error": f"{error}: {shlex.quote(command)}",
+                "output": output,
+                "elapsed_s": elapsed,
+            },
+        )
+        return
+    await proc.wait()
+    yield (
+        "done",
+        {
+            "success": proc.returncode == 0,
+            "exit_code": proc.returncode,
+            "output": output,
+            "elapsed_s": elapsed,
+        },
+    )
+
+
+def _kill_group(proc: Any) -> None:
+    try:
+        os.killpg(proc.pid, 9)
+    except (ProcessLookupError, PermissionError):
+        try:
+            proc.kill()
+        except ProcessLookupError:
+            pass
+
+
+def _truncate_output(text: str) -> str:
+    """모델에 돌려줄 출력을 앞뒤만 남기고 자른다 (codex CLI 와 같은 방식).
+
+    빌드 로그는 앞(무엇을 했나)과 뒤(어떻게 끝났나)가 중요하고 가운데는 반복이다.
+    """
+    lines = text.splitlines()
+    keep = _OUTPUT_HEAD_LINES + _OUTPUT_TAIL_LINES
+    if len(lines) > keep:
+        omitted = len(lines) - keep
+        lines = (
+            lines[:_OUTPUT_HEAD_LINES]
+            + [f"… ({omitted}줄 생략) …"]
+            + lines[-_OUTPUT_TAIL_LINES:]
+        )
+    result = "\n".join(lines)
+    if len(result) > _OUTPUT_MAX_CHARS:
+        head = _OUTPUT_MAX_CHARS // 4
+        tail = _OUTPUT_MAX_CHARS - head
+        omitted = len(result) - _OUTPUT_MAX_CHARS
+        result = f"{result[:head]}\n… ({omitted}자 생략) …\n{result[-tail:]}"
+    return result
+
+
+def _command_summary(result: Any) -> str:
+    if not isinstance(result, dict):
+        return "명령 종료"
+    elapsed = result.get("elapsed_s")
+    took = f" · {elapsed}초" if elapsed is not None else ""
+    if elapsed is not None and elapsed < 0.1:
+        # 반올림한 "0.0초" 는 시간을 못 잰 것처럼 읽힌다
+        took = " · 0.1초 미만"
+    if "exit_code" in result:
+        return f"종료 코드 {result['exit_code']}{took}"
+    return _one_line(f"명령 실패: {result.get('error') or ''}{took}")
+
+
+def _resolve_in_workspace(path: str, workspace_root: str) -> Optional[str]:
+    """작업공간 안의 실제 경로. 밖을 가리키면 None."""
+    root = os.path.realpath(workspace_root)
+    target = os.path.realpath(os.path.join(root, path))
+    if target != root and not target.startswith(root + os.sep):
+        return None
+    return target
+
+
+def _edit_file(args: Dict[str, Any], workspace_root: str) -> Dict[str, Any]:
+    """파일에서 old_string 을 new_string 으로 바꾼다. 물리 파일을 직접 고친다."""
+    path = args.get("path") or ""
+    old = args.get("old_string") or ""
+    new = args.get("new_string") or ""
+    replace_all = bool(args.get("replace_all"))
+    target = _resolve_in_workspace(path, workspace_root)
+    if target is None:
+        return {"success": False, "error": f"작업공간 밖의 경로입니다: {path}"}
+    if not os.path.isfile(target):
+        return {"success": False, "error": f"파일을 찾을 수 없음: {path}"}
+    if not old:
+        return {"success": False, "error": "old_string 이 비어 있습니다."}
+    with open(target, encoding="utf-8", newline="") as f:
+        text = f.read()
+    count = text.count(old)
+    if count == 0:
+        return {"success": False, "error": f"old_string 을 찾지 못했습니다: {path}"}
+    if count > 1 and not replace_all:
+        return {
+            "success": False,
+            "error": (
+                f"old_string 이 {count}곳과 일치합니다. 앞뒤 줄을 더 넣어 한 곳으로 "
+                "좁히거나 replace_all 을 켜세요."
+            ),
+        }
+    updated = text.replace(old, new) if replace_all else text.replace(old, new, 1)
+    with open(target, "w", encoding="utf-8", newline="") as f:
+        f.write(updated)
+    return {"success": True, "path": path, "replacements": count if replace_all else 1}
+
+
+def _read_for_diff(
+    tool: str, args: Dict[str, Any], workspace_root: str
+) -> Optional[str]:
+    """파일을 바꾸는 도구면 바꾸기 전 내용을 돌려준다 (새 파일이면 빈 문자열)."""
+    if tool not in ("write_file", "edit_file"):
+        return None
+    target = _resolve_in_workspace(args.get("path") or "", workspace_root)
+    if target is None:
+        return None
+    if not os.path.isfile(target):
+        return ""
+    try:
+        with open(target, encoding="utf-8", errors="replace") as f:
+            return f.read()
+    except OSError:
+        return None
+
+
+def _diff_lines(path: str, before: str, workspace_root: str) -> str:
+    """바뀐 내용을 CLI 처럼 diff 로 보인다. 너무 길면 자른다."""
+    target = _resolve_in_workspace(path, workspace_root)
+    if target is None or not os.path.isfile(target):
+        return ""
+    with open(target, encoding="utf-8", errors="replace") as f:
+        after = f.read()
+    diff = list(
+        difflib.unified_diff(before.splitlines(), after.splitlines(), lineterm="", n=2)
+    )[2:]
+    if not diff:
+        return ""
+    if len(diff) > _DIFF_MAX_LINES:
+        more = len(diff) - _DIFF_MAX_LINES
+        diff = diff[:_DIFF_MAX_LINES] + [f"… ({more}줄 더)"]
+    return "\n".join("│ " + line for line in diff)