훅
SessionStart, PreToolUse, Stop에서 발화하는 도구 이벤트 핸들러로, git 격리와 계획 규율을 강제하는 메시지 컨텍스트를 로드합니다.
훅은 도구 이벤트에서 발화하며, 어시스턴트가 추가 시스템 프롬프트로 취급하는
메시지 컨텍스트를 로드합니다. 배선은 Claude Code의 settings.json 훅 블록,
Codex의 hooks.json 훅 파일, Qwen Code의 settings.json 훅 맵에 존재합니다.
| 이벤트 | 타임아웃 | 목적 |
|---|---|---|
| SessionStart | 30초 | 메모리 읽기, 계획 상태 확인, 준비 상태 보고 |
| PreCompact | 30초 | 압축 전에 상태가 외부화되었는지 검증 |
| PostCompact | 30초 | 압축 후 작업 상태 복원 |
| Stop | 60초 | 세션 종료 시 외부화 |
| PreToolUse (Bash) | 10초 | Bash 검증 — git 산출물 격리 |
| PreToolUse (Write/Edit/NotebookEdit/apply_patch) | 10초 | 계획 참조 격리, frontmatter 점검 |
디스패처
설치된 훅 항목은 절대 스크립트 경로로 디스패처를 호출합니다. 설정 템플릿은
${HARNESS_ROOT} 토큰을 담고 있으며——
python "${HARNESS_ROOT}/apothem/hooks/dispatch.py" <event> [<message-name>]
——설치 프로그램은 설치 시점에 이를 harness 루트의 실제 경로로 렌더링합니다
(Claude Code와 Qwen Code는 디스패처를 <harness-root>/apothem/hooks/ 아래에,
Codex는 <harness-root>/hooks/ 아래에 구체화합니다). 디스패처는 독립형 표준
라이브러리 스크립트입니다. 자체 sys.path를 부트스트랩하므로 호스트에 임포트
가능한 apothem 패키지가 필요하지 않습니다. 소스 체크아웃에서는 모듈 형식
python -m apothem.hooks.dispatch <event>(PYTHONPATH=src 와 함께)가 개발용으로
동일한 코드를 실행합니다. 디스패처는 생태계 루트 해석을 위해
hooks/lib/resolve_root.py 를 로드하고, hooks/emit_hook_context.py 와
hooks/session_start_bootstrap.py 에 위임합니다.
메시지 컨텍스트
이벤트별 Markdown 컨텍스트는 src/apothem/hooks/messages/ 아래에 존재합니다.
postcompact.md,precompact.md,stop.mdpretooluse-bash.md,pretooluse-write.md,pretooluse-edit.md,pretooluse-notebookedit.md
각 컨텍스트 파일은 해당 이벤트가 발화하고 그 컨텍스트 인자가 설정 파일에 등록되어 있을 때 디스패처에 의해 로드됩니다.
생성된 훅 메시지 인벤토리
| Name | Description | Source |
|---|---|---|
postcompact | Post-compaction Blind Bootstrap (CM-24 §6.2). Restore working state from durable files; conversation context is now compressed. | src/apothem/hooks/messages/postcompact.md |
posttooluse-proactive-compaction | Proactive-compaction tracker for PostToolUse tool calls. | src/apothem/hooks/messages/posttooluse-proactive-compaction.md |
precompact | Pre-compaction protocol (CM-24 §2.3). Externalize all in-conversation state BEFORE the harness compresses context. | src/apothem/hooks/messages/precompact.md |
pretooluse-askuserquestion-recommended | Call-time (Recommended)-marker guard for AskUserQuestion tool calls. | src/apothem/hooks/messages/pretooluse-askuserquestion-recommended.md |
pretooluse-bash-plan-guard | Plans-Discipline write guard for Bash tool calls (companion to pretooluse-write-plan-guard.md). | src/apothem/hooks/messages/pretooluse-bash-plan-guard.md |
pretooluse-bash | CM-7 git-artifact isolation + M12 numeric-prefix discipline + M15 human-only authorship. | src/apothem/hooks/messages/pretooluse-bash.md |
pretooluse-conformity | > Advisory: this hook reports; it does not block. Mechanical enforcement runs in CI. | src/apothem/hooks/messages/pretooluse-conformity.md |
pretooluse-dependency-guard | Dependency-manifest supply-chain guard (advisory). | src/apothem/hooks/messages/pretooluse-dependency-guard.md |
pretooluse-edit-header-guard | SPDX-header inject guard for Edit tool calls. | src/apothem/hooks/messages/pretooluse-edit-header-guard.md |
pretooluse-edit | Codebase isolation (Edit scope). | src/apothem/hooks/messages/pretooluse-edit.md |
pretooluse-eval-guard | Dynamic-eval / unsafe-deserialization guard — advisory prompt-injection defense. | src/apothem/hooks/messages/pretooluse-eval-guard.md |
pretooluse-notebookedit | Codebase isolation (notebook scope). | src/apothem/hooks/messages/pretooluse-notebookedit.md |
pretooluse-write-header-guard | SPDX-header inject guard for Write tool calls. | src/apothem/hooks/messages/pretooluse-write-header-guard.md |
pretooluse-write-plan-guard | Plans-Discipline write guard for Write / Edit / NotebookEdit tool calls. | src/apothem/hooks/messages/pretooluse-write-plan-guard.md |
pretooluse-write | Codebase isolation + frontmatter compliance. | src/apothem/hooks/messages/pretooluse-write.md |
sessionstart | Session-start conformity posture. | src/apothem/hooks/messages/sessionstart.md |
stop | Session-end protocol (CM-14 + CM-24 §2.5 + CM-26 + CM-22 §2/§4). | src/apothem/hooks/messages/stop.md |