feat(providers): add hook-based usage cache for Claude usage tracking

[kwag93]

Background / 배경

Anthropic 서드파티 OAuth 제한 정책

2026년 1월, Anthropic은 사전 공지 없이 서버 측 보안 조치를 배포하여 Claude 구독(Free/Pro/Max) OAuth 토큰의 서드파티 사용을 차단했습니다. 2026년 2월에는 이를 공식 정책으로 문서화했습니다:

"Using OAuth tokens obtained through Claude Free, Pro, or Max accounts in any other product, tool, or service — including the Agent SDK — is not permitted and constitutes a violation of the Consumer Terms of Service."

이로 인해 OpenCode(107K+ GitHub stars), Roo Code, Cline 등 수십 개의 서드파티 도구가 일시에 동작 불능 상태에 빠졌습니다.

CreditClock에 미치는 영향: CreditClock은 사용량 조회를 위해 OAuth 토큰으로 Anthropic Usage API를 호출하고 있었으므로, 이 정책이 엄격하게 적용될 경우 핵심 기능이 차단될 수 있습니다.

oh-my-claudecode(OMC) 종속성 문제

기존에는 Claude 사용량 캐시를 OMC 플러그인의 내부 파일(~/.claude/plugins/oh-my-claudecode/.usage-cache.json)에 의존하고 있었습니다. 이는 다음과 같은 문제를 야기합니다:

• OMC 미설치 사용자는 캐시 전략을 사용할 수 없음
• OMC의 내부 파일 경로/형식 변경 시 CreditClock이 즉시 영향을 받음
• CreditClock의 핵심 기능이 서드파티 플러그인에 종속되는 구조

---

Motivation / 동기

1. OMC 종속성 제거 — CreditClock 자체 hook으로 독립적인 사용량 캐시 파이프라인을 확보하여, OMC 설치 여부와 무관하게 동작
2. OAuth 차단 대비 — Anthropic이 서드파티 OAuth를 완전히 차단하더라도, Claude Code 세션 내에서 실행되는 hook은 공식 Claude Code의 일부로 동작하므로 정책 영향을 받지 않음
3. Resilient fallback chain — hook cache → OMC cache → OAuth direct → stale cache 순서의 다단계 전략으로, 어떤 경로가 차단되더라도 사용량 데이터를 확보

---

Changes / 변경 사항

1. Hook-based usage cache pipeline (a062e01)

데이터 흐름:

Claude Code Session
  → [PostToolUse / SessionStart 이벤트]
  → bash fetch-usage.sh (30초 TTL 체크)
  → python3 fetch-usage.py (Keychain OAuth → Anthropic API)
  → ~/.creditclock/usage-cache.json (atomic write)

• scripts/creditclock-usage-hook.sh — bash 래퍼 (30초 캐시 신선도 체크로 불필요한 Python 호출 방지)
• scripts/creditclock-usage-hook.py — Keychain에서 OAuth 토큰 읽기 → Anthropic Usage API 호출 → 캐시 저장
• scripts/install-claude-hook.sh — ~/.claude/settings.json에 hook 등록/제거 자동화
• AnthropicProviderAdapter — 3단계 fetch 전략: hook cache(1순위) → OMC cache(2순위) → OAuth direct(3순위)

2. Settings UI 안내 및 문서화 (44145e3)

• ProviderSettingsView — hook 미설치 시 안내 배너 표시 (설치 스크립트 경로 안내)
• README.md / README.ko.md — hook 설치/제거 가이드, 데이터 소스 우선순위 문서화

---

Benefits / 기대 효과

항목	Before	After
OMC 필수 여부	OMC 설치 필수 (캐시용)	선택 사항 (fallback으로만 유지)
OAuth 차단 시	사용량 조회 불가	Hook이 Claude Code 세션 내에서 캐시 유지
캐시 갱신 주기	OMC 내부 로직에 의존	30초 TTL로 명시적 제어
독립성	서드파티 플러그인 종속	CreditClock 자체 파이프라인

---

Test plan

• Hook 미설치 상태에서 Anthropic 설정 화면 진입 시 안내 메시지 표시 확인
• ./scripts/install-claude-hook.sh 실행 후 ~/.claude/settings.json에 hook 등록 확인
• Claude Code 세션에서 ~/.creditclock/usage-cache.json 자동 갱신 확인
• Hook 설치 후 ProviderSettingsView 안내 메시지 미표시 확인
• Hook cache 존재 시 1순위로 사용됨 (로그에 source=creditClockHook)
• Hook cache 없을 때 OMC cache → OAuth fallback 정상 동작
• ./scripts/install-claude-hook.sh remove로 깨끗한 제거 확인

---

References

• Anthropic clarifies ban on third-party tool access to Claude (The Register, 2026-02-20)
• Anthropic Bans Claude Subscription OAuth in Third-Party Apps (WinBuzzer, 2026-02-19)
• Anthropic Banned OpenClaw: The OAuth Lockdown (Natural 20)

🤖 Generated with Claude Code