feat: Claude Code Hooks 옵저빌리티 통합

[dohapark81]

목표

Claude Code Hooks를 활용하여 CrewX의 옵저빌리티를 에이전트 내부 도구 호출 레벨까지 확장합니다.

배경

• 현재: CrewX CLI 레벨에서 에이전트 실행 트레이싱 (traces.db)
• 추가: Claude Code의 Write/Edit/Bash 도구 호출 상세 로깅
• 참고: https://www.daleseo.com/claude-code-hooks/

구현 범위

Phase 1: Hooks 인프라 구축

• hooks/ 디렉토리 생성 및 스크립트 작성
  • log-tool-use.js (PostToolUse 핸들러)
  • validate-tool-use.js (PreToolUse 검증)
  • finalize-session.js (Stop 핸들러)
• TracingService 확장 (logToolCall 메서드 추가)
• 환경변수 전달 로직 (CREWX_TASK_ID)

Phase 2: traces.db 스키마 확장

• tool_calls 테이블 생성
  • id, task_id, tool_name, files, input, output, duration_ms, timestamp
• 인덱스 추가 (task_id, tool_name)
• 마이그레이션 스크립트 작성

Phase 3: crewx init 통합

• crewx init --with-hooks 옵션 추가
• ~/.config/claude/settings.json 자동 생성/업데이트
• 훅 스크립트 절대 경로 주입
• 설치 검증 로직

Phase 4: CLI 조회 기능

• crewx trace tools <task-id> 명령어
• crewx trace file <file-path> 명령어
• 출력 포맷팅

기술 스택

• Node.js (훅 스크립트)
• better-sqlite3 (traces.db 연동)
• Claude Code Hooks API

예상 소요

• Phase 1-2: 2일
• Phase 3-4: 1-2일
• 총 3-4일

차별화 포인트

• 다른 CLI 에이전트 프레임워크에 없는 CrewX만의 기능
• 에이전트 작업 추적의 완전성 (CLI + Tool 레벨)
• 디버깅/감사/학습에 유용

참고 문서

• 검토 문서: Slack 스레드 (1768470699.107939)
• 기존 TracingService: packages/cli/src/services/tracing.service.ts

[dohapark81]

crewx init 통합 설계

설치 프로세스

# 기본 사용 (훅 포함)
crewx init

# 또는 명시적 옵션
crewx init --with-hooks
crewx init --skip-hooks  # 훅 스킵

구현 단계

1. 훅 스크립트 설치

crewx/
├── hooks/              # 프로젝트 루트에 생성
│   ├── log-tool-use.js
│   ├── validate-tool-use.js
│   └── finalize-session.js
└── .crewx/
    └── traces.db       # 기존

2. Claude Code 설정 업데이트

~/.config/claude/settings.json 자동 생성/업데이트:

{
  "hooks": {
    "postToolUse": {
      "Write": "node /absolute/path/to/crewx/hooks/log-tool-use.js",
      "Edit": "node /absolute/path/to/crewx/hooks/log-tool-use.js",
      "Bash": "node /absolute/path/to/crewx/hooks/log-tool-use.js"
    },
    "preToolUse": {
      "Write": "node /absolute/path/to/crewx/hooks/validate-tool-use.js"
    },
    "stop": "node /absolute/path/to/crewx/hooks/finalize-session.js"
  }
}

3. 기존 설정 병합

• 기존 settings.json이 있으면 병합 (덮어쓰지 않음)
• hooks.postToolUse 섹션만 업데이트
• 사용자 확인 프롬프트 제공

4. 검증

# 설치 후 자동 검증
crewx hooks verify
# 출력 예시:
# ✅ hooks/ 디렉토리 존재
# ✅ log-tool-use.js 실행 가능
# ✅ ~/.config/claude/settings.json 올바름
# ✅ 테스트 로깅 성공

CLI 명령어 추가

# 훅 상태 확인
crewx hooks status

# 훅 재설치
crewx hooks install

# 훅 제거
crewx hooks uninstall

# 훅 검증
crewx hooks verify

사용자 경험

$ crewx init
✓ Initialized .crewx/ directory
✓ Created traces.db schema
? Install Claude Code hooks for observability? (Y/n) y
✓ Installed hooks/ scripts
✓ Updated ~/.config/claude/settings.json
✓ Verified hook installation

🎉 CrewX initialized successfully!
💡 Tip: Hooks will automatically log tool usage to traces.db

$ crewx hooks status
✅ Hooks installed and active
📂 Hooks directory: /Users/doha/git/crewx/hooks
⚙️  Claude settings: ~/.config/claude/settings.json

고려사항

1. 프로젝트별 격리

   • 각 프로젝트마다 hooks/ 디렉토리 독립 생성
   • settings.json은 절대 경로로 프로젝트별 훅 참조

2. 다중 프로젝트 지원

   • CrewX 프로젝트 A, B가 있을 때 각각 자신의 훅 사용
   • CREWX_PROJECT_ROOT 환경변수로 구분

3. 업그레이드 시나리오

   • 기존 프로젝트에서 crewx hooks install 실행
   • 버전 마이그레이션 스크립트 제공

4. 선택적 기능

   • 일부 사용자는 훅 불필요 → --skip-hooks 옵션
   • .crewx/config.json에 hooksEnabled: false 설정 가능

구현 파일

• packages/cli/src/commands/init.command.ts - init 로직 확장
• packages/cli/src/commands/hooks.command.ts - 새 명령어
• packages/cli/src/services/hooks-installer.service.ts - 설치 로직
• hooks/ - 템플릿 스크립트들

[dohapark81]

🤖 Dev Lead Analysis

작업 분해 제안

이 작업은 4개 Phase로 구성되며, 각 Phase는 독립적으로 구현 및 테스트 가능합니다.

권장 접근법: WBS 활용

• 복잡도: 중~고 (여러 컴포넌트 연동)
• 예상 소요: 3-4일
• 에이전트: @crewx_claude_dev (아키텍처 설계 필요)

Phase별 담당

Phase	담당	예상 소요	의존성
1. Hooks 인프라	@crewx_claude_dev	1일	-
2. DB 스키마 확장	@crewx_codex_dev	0.5일	Phase 1
3. crewx init 통합	@crewx_claude_dev	1일	Phase 1-2
4. CLI 조회 기능	@crewx_codex_dev	0.5-1일	Phase 2

구현 순서

Phase 1 → Phase 2 → Phase 3 ┐
                            ├→ 통합 테스트
                 Phase 4 ──┘

다음 단계

사용자 승인 후:

1. WBS 프로젝트 생성
2. Job 등록 (4개 Phase)
3. Coordinator 데몬 통해 순차 실행

또는 직접 작업 시작:

crewx x "@crewx_claude_dev Implement issue #104 Phase 1: Hooks infrastructure"

[dohapark81]

🤖 Dev Lead Decision

Core Requirement Update:

• Hook installation will be enabled by default in crewx init
• No --with-hooks flag needed
• Observability is a critical feature for CrewX

Implementation Strategy:
This is a complex feature requiring multiple phases:

1. Hooks infrastructure (scripts + templates)
2. crewx init integration (install hooks by default)
3. traces.db schema extension
4. CLI query commands

Assignment:

• Worker: @crewx_claude_dev (complex architecture)
• Starting with Phase 1 implementation

@crewx_claude_dev Please start work in a new worktree and implement Phase 1 as described in the issue.

[dohapark81]

Working on feature/issue-104 at worktree/feature-issue-104 - Phase 1: Hooks Infrastructure

[dohapark81]

✅ Phase 1 Implementation Complete

PR Created: #105

What's Implemented:

• ✅ hooks/ directory with 3 scripts:
  • log-tool-use.js (PostToolUse handler)
  • validate-tool-use.js (PreToolUse validation)
  • finalize-session.js (Stop handler)
• ✅ TracingService extended with:
  • logToolCall() method
  • tool_calls table schema
  • Query methods for tool call history
• ✅ Environment variable handling (CREWX_TASK_ID, CLAUDE_FILE_PATHS)
• ✅ npm run build passes

Branch: feature/issue-104
Worker: @crewx_claude_dev

Ready for cross-review before merge.