Pantheon 페르소나 도구 구조 디버깅 플레이북

reports/architecture/persona-tool-structure.html

TL;DR

• 페르소나(지니/완수/자비스/라파엘/나노)는 Pantheon 단일 프로세스 안의 N개 Slack Bolt App으로 Slack 이벤트를 받지만, LLM 호출은 매 메시지마다 새로 spawn되는 Claude CLI 서브프로세스에서 처리된다. 메인 Claude Code 세션과는 완전히 분리된 프로세스 인스턴스다.
• MCP 도구 노출은 세 경로의 합성이다 — ① ~/.claude.json mcpServers (사용자 OAuth/Bearer, 영속 토큰), ② <cwd>/.mcp.json (workspace-scoped, 보통 API key), ③ ~/.claude/plugins/<plugin>/.mcp.json (플러그인 MCP, 런타임 OAuth 캐시 의존).
• 콜로세움 케이스의 Notion만 authenticate tool만 노출 현상은 ③번 경로의 세션-스코프 OAuth 캐시가 페르소나 spawn에 전파되지 않은 패턴이 가장 강한 가설이다. 토큰이 config 파일에 명시되지 않고 클라이언트 인스턴스 상태로만 보관되는 MCP는 모두 같은 실패 양상에 노출돼 있다.
• 본 문서는 이번 사고 해명이 아니라 MCP-페르소나 인증 비대칭이 반복될 때마다 꺼내 쓸 진단 플레이북이다. Notion 케이스는 §4에서 대표 케이스로만 인용한다.
• 사용자에게 검증을 부탁드릴 결정은 §6에 모았다.

관련 보고서: Pantheon 페르소나 도구·세션 아키텍처 (전략 수립용, 2026-06-08) — 같은 구조를 전략·옵션 A/B/C 관점으로 다룸. 본 문서와 결이 다르고 보완 관계.

Context

사고 발단

2026-06-07 #northstar 콜로세움 트래커 작업 중, 지니 페르소나가 Notion DB row를 가져오려다 MCP 도구 부재로 실패. 지니의 deferred tool 목록에는 mcp__notion__authenticate만 있고 notion-search/notion-fetch/notion-create-pages는 부재. 같은 시점 메인 Claude Code 세션에는 Notion MCP 도구 전체가 정상 노출 — 비대칭이 같은 머신·같은 사용자에서 발생했다.

지니가 임시로 메인 세션에 row fetch를 위임해 사건은 봉합됐지만, "지니가 어떤 구조로 도구를 쓰고 있는지 알아야 앞으로 도구 전략을 세울 수 있겠다"는 사용자 요청이 본 보고서의 출처다.

표기 규약

본 보고서가 다루지 않는 것

• 콜로세움 면접 결과·일정 관리 흐름 (다른 보고서)
• 페르소나-문서 오너십 매트릭스 (별도 보고서)
• Slack 소켓 dispatcher 구조 (HAN-403 보고서)

진단 — 5섹션

1. Slack 메시지 → 페르소나 라우팅 → 세션 생성/복원 흐름

확정 사실 (pantheon/bridge.py, pantheon/router.py, pantheon/providers/claude.py:62-68)

sequenceDiagram
  autonumber
  participant U as 사용자 (Slack)
  participant SL as Slack Cloud
  participant SH as Bolt App<br/>(persona별)
  participant BR as bridge.py<br/>handle_user_message
  participant RT as router.py<br/>(haiku)
  participant SES as persona_sessions<br/>+ sessions.json
  participant CLI as Claude CLI subprocess<br/>(spawn per call)
  participant MCP as MCP 서버군

  U->>SL: 메시지 (멘션·DM·스레드 답글)
  SL->>SH: WebSocket 이벤트 (페르소나별 Bolt App 각자 수신)
  SH->>BR: app_mention / message 이벤트
  Note over BR: _dup_guard (30분 TTL) +<br/>_in_flight dict로 N개 봇 중복 응답 차단

  alt 새 메시지 + 태그 없음
    BR->>RT: route(text, personas)
    RT->>CLI: claude -p (haiku, 30s timeout)
    CLI-->>RT: ["jini"] 또는 ["jarvis"] fallback
    RT-->>BR: 응답할 페르소나 결정
  else 멘션·스레드 owner·force prefix
    BR-->>BR: 라우팅 skip (직접 결정)
  end

  BR->>SES: get_or_create_session(persona, thread_ts)
  SES-->>BR: session_id (없으면 None)

  BR->>CLI: subprocess.Popen([<br/>  "claude", "-p", prompt,<br/>  "--output-format", "stream-json",<br/>  "--model", "sonnet",<br/>  "--permission-mode", "bypassPermissions",<br/>  "--resume", session_id?<br/>], cwd=~/Workspace)

  Note over CLI: 새 프로세스. 환경변수 상속.<br/>cwd 기반 .mcp.json 로드.<br/>user-level ~/.claude.json 로드.

  CLI->>MCP: tool 호출 (노출된 것만)
  MCP-->>CLI: 결과
  CLI-->>BR: stream-json (type=result, session_id)
  BR->>SES: save session_id (다음 회차 --resume용)
  BR->>SH: say(reply, thread_ts=...)
  SH->>SL: 페르소나 봇 토큰으로 게시
  SL->>U: 페르소나 명의 응답

핵심 사실 묶음:

핵심 함의: "지니가 기억한다"는 것은 Pantheon이 다음 호출에 session_id를 다시 넘긴다는 뜻이지, LLM 프로세스가 살아 있다는 뜻이 아니다. 따라서 프로세스 인스턴스 상태(OAuth 캐시 포함)는 매번 새로 만들어진다.

2. 페르소나별 MCP 도구 노출 방식

확정 사실 (~/.claude.json mcpServers, ~/Workspace/.mcp.json, ~/.claude/plugins/.../.mcp.json)

Claude CLI 서브프로세스가 시작될 때 MCP 도구가 노출되는 경로는 세 곳에서 합쳐진다.

flowchart TB
  subgraph SPAWN["페르소나 Claude CLI subprocess (spawn 시점)"]
    direction TB
    CWD["cwd = ~/Workspace<br/>(providers/claude.py:28)"]
  end

  subgraph CONFIGS["MCP 설정 합성"]
    direction TB
    C1["① ~/.claude.json<br/>mcpServers<br/>(user-level)"]
    C2["② &lt;cwd&gt;/.mcp.json<br/>(workspace-scoped)"]
    C3["③ ~/.claude/plugins/&lt;plugin&gt;/<br/>.mcp.json + 캐시<br/>(plugin manifest)"]
  end

  SPAWN -->|읽음| C1
  SPAWN -->|읽음| C2
  SPAWN -->|enabledPlugins 기준 활성화| C3

  C1 -->|"chrome-devtools, calendar, slack, slack-hangman,<br/>linear-davinci, linear-hangman"| TOOLS["deferred tools 목록"]
  C2 -->|gemini| TOOLS
  C3 -->|notion@claude-plugins-official,<br/>code-review@claude-plugins-official| TOOLS

  TOOLS -->|ToolSearch query=select:&lt;name&gt;| LOADED["로드된 도구<br/>(실제 호출 가능)"]

세 경로의 토큰/인증 보관 방식이 결정적으로 다르다.

ToolSearch / deferred tools 패턴: Claude CLI는 시작 시 모든 MCP에 connect하지 않고, 도구 메타데이터(이름)만 deferred 목록에 등재한 뒤, 실제 호출 직전에 ToolSearch query="select:<name>"로 스키마를 로드한다. 따라서 MCP 서버 연결은 lazy이고, 연결 시점의 인증 상태가 노출되는 도구 집합을 결정한다.

→ Notion plugin의 경우, 페르소나 subprocess가 시작될 때 mcp.notion.com에 인증 없이 핸드셰이크하면 서버가 authenticate tool만 반환하고 notion-search/notion-fetch는 권한 없는 상태로는 노출하지 않는다 (추정).

3. 메인 Claude Code 세션 ↔ Pantheon 페르소나 세션 분리 지점

확정 사실 (providers/claude.py:28, 62-68, ~/.claude.json, ~/.claude/settings.json)

같은 머신·같은 사용자(hangman) 하에서 도는 두 영역이지만, 어디까지가 공유고 어디부터가 별개인지가 본 보고서의 핵심.

핵심 분리 지점 = OAuth 캐시: Bearer/API key는 config 파일 본문에 있거나 없거나이므로 이진 결정이고 페르소나도 동일하게 작동한다. 반면 OAuth는 세션 인스턴스의 메모리/캐시 상태에 의존하는 경우가 있어 페르소나 subprocess가 fresh state로 시작할 때 권한 누락 가능성이 있다.

4. Notion 인증만 실패한 원인 후보 (대표 케이스)

콜로세움 케이스의 관측:

가설 3가지:

가설 A — OAuth 캐시 미전파 (Plugin runtime state)

• 주장: Notion plugin은 사용자가 메인 세션에서 한 번 OAuth flow를 거친 결과가 런타임 캐시에 저장되어 있고, 페르소나 subprocess는 같은 사용자라도 fresh process라 이 캐시를 들고 있지 않다.
• 지지 증거: 다른 MCP는 config 파일 본문 또는 외부 키 파일에 토큰이 박혀 있어 fresh process도 즉시 작동. Notion만 plugin manifest .mcp.json에 URL만 있고 토큰 명시 없음 (~/.claude/plugins/cache/claude-plugins-official/notion/0.1.0/.mcp.json 확인됨).
• 반증 필요: Notion OAuth 토큰이 실제로 어디에 저장되는지 확인 — ~/.claude.json 다른 키, ~/.claude/.credentials, OS keychain, 또는 세션 메모리 only 중 하나.

가설 B — OAuth vs Integration Token 본질 차이

• 주장: Notion API는 두 가지 인증 모드가 있다 — OAuth (사용자 grant)와 Internal Integration Token (워크스페이스 통합). plugin이 OAuth 모드를 쓰면 사용자별 grant가 필요하지만, Integration Token은 config에 박아 두면 영구다.
• 지지 증거: 사고 스레드에서 지니가 "Pantheon config에 Notion Internal Integration Token을 박는 방법"을 빠른 해결책으로 제시.
• 반증 필요: Notion MCP plugin이 Integration Token을 받는 config 슬롯이 실제로 있는지 (~/.claude/plugins/.../notion/.../README.md 또는 plugin 문서 확인 필요).

가설 C — config 누락 (단순 misconfiguration)

• 주장: Notion MCP가 페르소나 측 어떤 config에 단순히 등록 안 됐을 뿐이고, 다른 MCP는 등록돼 있다.
• 지지 증거: 약함. user-level ~/.claude.json mcpServers에는 어차피 Notion 항목이 없다 — Notion은 플러그인 경로로 관리됨. 메인 세션에서 정상 작동하는 건 enabledPlugins가 켜져 있고 OAuth가 완료됐기 때문.
• 반증: 메인 세션과 페르소나가 같은 ~/.claude/settings.json을 읽는다면 enabledPlugins는 동일하게 보일 것 → 그럼에도 도구 노출이 다른 건 plugin이 시작 시 검사하는 추가 상태가 있다는 뜻 → 가설 A로 회귀.

가장 강한 가설: A (plugin runtime state 미전파). B는 해결책으로는 유효하지만 원인 진단으로는 한 층 위. C는 거의 기각.

검증 방법은 §5에 모았다.

5. 재발 방지 운영안 + 검증 명령

A. 즉시 검증 (가설 A·B 좁히기)

가설 A·B를 가르는 1단계 검증:

# 1. Notion plugin이 인증 상태를 어디 저장하는지 후보 탐색
grep -rn "notion" ~/.claude/ 2>/dev/null \
  | grep -vE "(plugins/cache|history|projects/.*memory)" \
  | head -20

# 2. ~/.claude.json 안에 mcp 관련 키 외에 OAuth/token 저장 키가 있는지
jq 'keys' ~/.claude.json | grep -iE "(oauth|token|notion|auth|credential)"

# 3. plugin 디렉토리 안에 user-state 캐시가 있는지
find ~/.claude/plugins/cache/claude-plugins-official/notion -type f \
  \( -name "*.json" -o -name "*.tokencache*" -o -name ".env*" \)

→ 후보 위치 확인되면 가설 A 확정. 후보 위치 없고 메인 세션 메모리에만 토큰이 있으면 가설 A의 더 강한 버전 (process-local only).

B. 빠른 해결책 (사고 직결 fix)

Notion Internal Integration Token을 발급해 user-level config에 박는 방향이 가장 작은 패치다.

# 1. Notion 사이트에서 Integration 생성: https://notion.so/profile/integrations
#    → "Internal" 타입, 권한: Read content / Update content / Insert content
# 2. workspace의 페이지·DB에 integration share
# 3. ~/.claude.json mcpServers에 추가 (전제: Notion MCP가 Bearer 헤더를 받는지 확인 필요)
#    또는 ~/Workspace/.mcp.json에 추가 (페르소나 cwd=~/Workspace 이므로 동일 효력)

⚠️ 전제 검증 필요: Notion plugin MCP가 Bearer <token> 헤더 또는 env: { NOTION_TOKEN: ... }을 받는지 확인. plugin 문서 또는 .mcp.json 스키마 확인 후에만 진행.

C. 일반 패턴 (재발 방지)

D. 페르소나-측 자기 진단 명령 (지니/완수가 직접 쓸 수 있는 것)

페르소나가 자기 deferred tool 목록을 점검할 수 있는 1줄:

# 페르소나 세션에서 ToolSearch로 후보 검색 후 deferred 목록과 대조
# 또는 사용자에게 직접 보고:
#   "내 MCP 도구 목록에 notion-search가 있나요? authenticate만 있다면 가설 A 재현."

이건 페르소나가 자기 환경을 메인 세션에 보고할 때 사용. 메인 세션이 두 환경을 매트릭스로 비교 가능.

신호 — 관측된 증거

결론

본 보고서의 핵심 주장 셋:

1. 페르소나 LLM 인스턴스는 매 메시지마다 새로 spawn된다. 따라서 프로세스 시작 시 인증 가능한 MCP만 안정적이다. OAuth runtime 캐시 의존 MCP는 페르소나에서 예측 불가능한 실패를 보인다.
2. Notion 단일 사고가 아니라 plugin MCP 인증 비대칭이라는 일반 패턴이다. 같은 패턴은 향후 다른 OAuth 기반 plugin MCP가 추가될 때마다 재현될 수 있다.
3. 즉시 해결은 Integration Token을 config에 박는 가설 B 경로가 가장 작은 패치다. 단, Notion plugin이 Bearer/env 토큰을 받는지 먼저 검증해야 한다 (검증 못 하면 가설 B는 그림에 그친 떡).

권장 우선순위(지니가 사고 스레드에서 제시한 C → B → A 순서와 호응):

검증 질문 — 사용자에게

§5의 진단 명령을 돌려 본 다음, 사용자(또는 완수가 위임받아) 가르마를 타야 할 결정 3가지:

1. 가설 A vs B 검증 결과가 나오면, Integration Token 경로로 가는 것이 페르소나 전반의 인증 정책으로 적절한가? OAuth(사용자 grant)와 Integration Token(워크스페이스 통합)은 행위 주체가 다르다 — 페르소나가 항승 본인 명의로 Notion 페이지를 만드는 것이 허용되는가, 아니면 페르소나 명의 별도 integration까지 가야 하는가?
2. 페르소나가 자기 도구 목록을 사용자에게 보고하는 패턴을 일상화할 것인지. "지니, 너 deferred tools에 notion-search 있어?" 같은 점검을 세션 시작 시 자동으로 둘 것인지, 필요할 때만 사용자가 묻는 것으로 둘 것인지.
3. plugin MCP는 페르소나에서 deprecated로 가는 정책을 채택할 것인지. OAuth runtime 캐시 의존 MCP는 메인 세션 전용으로 두고, 페르소나는 Bearer/API key 기반 MCP만 노출하는 룰. (Notion은 향후 Integration Token 경로가 열린다면 페르소나도 OK.)

모름·확인 필요

• Notion plugin이 토큰 주입을 받는 슬롯이 실제로 있는지 — ~/.claude/plugins/cache/claude-plugins-official/notion/0.1.0/.mcp.json의 스키마와 plugin README 확인.
• 메인 세션 Notion OAuth 토큰의 실제 저장 위치 — §5-A 명령 결과로 확정.
• Chrome DevTools MCP·gemini MCP가 페르소나에 노출되는지 — 본 보고서는 미확인. 페르소나가 자기 deferred tool 목록을 사용자에게 보고하면 매트릭스 완성.
• router.py의 fallback ["jarvis"]가 OAuth 캐시 누락 같은 환경 차이를 어떻게 다루는지 — 현재는 응답 페르소나 결정 단이고 환경 차이는 다루지 않음. 별 보고서 주제.

부록 — 핵심 파일 인용

pantheon/providers/claude.py:28
  self.cwd = cwd or str(Path(__file__).resolve().parents[2])
  # = ~/Workspace

pantheon/providers/claude.py:62-68
  cmd = ["claude", "-p", prompt,
         "--output-format", "stream-json", "--verbose",
         "--model", model or self.model,
         "--permission-mode", self.permission_mode]
  if session_id:
      cmd.extend(["--resume", session_id])

~/Workspace/.mcp.json
  { "mcpServers": { "gemini": { ..., "env": { "GEMINI_API_KEY": "..." } } } }

~/.claude.json mcpServers (요약)
  - chrome-devtools  : stdio (npx), env 없음
  - calendar         : stdio (npx), env GOOGLE_OAUTH_CREDENTIALS=파일경로
  - slack            : http (mcp.slack.com), oauth (clientId만)
  - linear-davinci   : http (mcp.linear.app), 헤더 없음
  - linear-hangman   : http (mcp.linear.app), 헤더 없음
  - slack-hangman    : http (mcp.slack.com), Bearer xoxp-...

~/.claude/settings.json enabledPlugins
  - notion@claude-plugins-official       ← 사고 케이스
  - code-review@claude-plugins-official

~/.claude/plugins/cache/claude-plugins-official/notion/0.1.0/.mcp.json
  { "mcpServers": { "notion": { "type": "http",
                                "url": "https://mcp.notion.com/mcp" } } }
  ← 토큰 슬롯 없음 (그래서 OAuth runtime cache 의존)

참조

• 사고 스레드: #northstar 콜로세움 트래커 (1780911286.911759)
• 관련 보고서:
• 전략 옵션 A/B/C: 2026-06-08-pantheon-persona-tool-architecture
• 페르소나-문서 오너십: 2026-06-07-persona-document-ownership
• 소켓 dispatcher 구조: pantheon-socket-dispatcher-architecture-2026-05-31
• memory 인덱스 키워드: reference_pantheon_slack_send, reference_slack_mcp, project_jarvis_roadmap, feedback_pantheon_persona_skill_execution