Hooks and middleware

GEODE는 확장 표면을 권한별로 나눕니다. 외부 통합이 의존할 수 있는 HookName, 실행을 감싸는 신뢰 표면 MiddlewareRegistry, 운영 관측을 위한 RuntimeEvent로 역할과 권한을 분리합니다.

세 표면

표면	용도	권한
공개 훅	사용자 입력, 도구, 압축, 세션, 서브에이전트, 검증 경계	이름별로 허용된 typed decision만 반환
신뢰 미들웨어	도구·LLM 요청 변환과 실제 실행 래핑	요청 단계는 변환, 실행 단계는 감싸기·단축 반환
런타임 이벤트	메트릭, 감사, 저장, 운영 진단	내부 관측 전용. 실행 제어 계약이 아님

공개 훅 13종

공개 목록은 의도적으로 작고 버전이 고정됩니다. 와일드카드 구독은 없으며, 입력은 크기 제한·JSON 안전화·비밀값 제거를 거칩니다.

훅	필수 payload	허용 action
`UserPromptSubmit`	`user_input`	continue · rewrite · block
`PreToolUse`	`tool_name, arguments`	continue · rewrite · block · request_permission
`PermissionRequest`	`tool_name, safety_level, detail`	allow · deny · ask
`PostToolUse`	`tool_name, arguments, result, has_error, executed`	continue · add_context · block
`PreCompact`	`model, provider, message_count, keep_recent, trigger, hard`	continue · rewrite · defer
`PostCompact`	`model, provider, original_message_count, new_message_count, keep_recent, trigger, persisted`	continue
`SessionStart`	`model, provider, resumed, status`	continue
`SessionEnd`	`reason, status`	continue
`SubagentStart`	`task_id, task_type, description, child_session_key, parent_session_key`	continue
`SubagentStop`	`task_id, task_type, success, status, duration_ms, error, child_session_key`	continue
`PreVerify`	`termination_reason, rounds, tool_call_count, candidate_summary`	continue · strengthen
`PostVerify`	`passed, mode, score, rubric_misses, termination_reason, rounds, tool_call_count, candidate_summary`	accept · revise · escalate
`Stop`	`PostVerify fields + policy_action, evidence_refs`	finalize · continue

훅별 schema에 없는 필드와 허용되지 않은 action은 거부됩니다. 선택 필드는 아래 runtime schema에서 확인합니다. 실패한 내장 검증을 외부 훅이 pass로 뒤집을 수도 없습니다. rewrite는 비어 있지 않은 updates, PostVerify.revise와Stop.continue는 비어 있지 않은 instruction이 필요합니다.

공통 envelope와 제한

항목	계약
버전	`geode.public-hook.v2` (v1 schema 조회 가능)
상관관계	`session_id`, `turn_id`, `step_id`, `run_id`, session generation, verify attempt, tool/LLM call ID
payload 상한	문자열 4,096자, JSON 32 KiB, collection 64개, depth 8
decision 상한	reason 1,024자, instruction 4,096자, evidence reference 32개
기본 timeout	handler별 10초. sync handler는 event loop 밖에서 실행
결정 없음	`None`은 `ok`로 감사하되 결정은 추가하지 않음. 묵시적 continue나 권한 허용이 아님
오류·취소	일반 오류는 기록 후 다음 handler 실행. 취소는 `error`와 예외 타입명만 감사한 뒤 원본을 다시 전파
검증 강화	`PreVerify.strengthen`은 `additional_misses`가 필요. 지시문만 있는 결정은 오류로 기록하고 적용하지 않음

각 hook의 Draft 2020-12 JSON Schema는 런타임에서 직접 조회합니다. 문서 표와 직렬화 계약이 다르면 런타임 schema가 정본입니다.

from core.hooks import HookName, public_hook_schema

schema = public_hook_schema(HookName.POST_VERIFY)
print(schema["properties"]["payload"])
print(schema["properties"]["decision"])

PostVerify와 외부 루프

PostVerify는 이미 실행된 부수 효과를 재생하지 않고, 완성된 후보와 내장 검증 결과를 외부 평가기·CI 정책·오케스트레이터가 판정하게 합니다. revise는 구체적인 후속 지시가 있어야 하며 최대 2회 연속 시도로 제한됩니다. 최종 결과에는 모든 시도의 rounds, tool calls, usage가 합산된 뒤 증거와 체크포인트가 저장됩니다. escalate는 delivery gate로 동작합니다. 세션을 pause하고 후보를 외부 소유자에게만 pending_text로 반환하며 terminal session.ended를 만들지 않습니다.

외부 handler 결정이 없으면 pass는 accept, 재시도 가능한 실패는 revise, 그 밖의 실패는 escalate하는 기본 정책이 동작합니다. revision 지시는 human transcript를 보존한 채 dynamic system context에 한 번 주입됩니다. verification.decided는 후보 본문을 생략하고 SHA-256 digest와 handler별 결정을 session timeline에 남깁니다.

신뢰 미들웨어 4개 결합점

결합점	계약
`tool_request`	승인 전 도구명·인자를 순차 변환하고 다시 스키마 검증
`tool_execution`	승인된 요청을 변경하지 않고 실제 executor를 async onion으로 감쌈
`llm_request`	조립된 adapter request를 순차 변환. 캐시 prefix 변경은 명시 권한과 사유가 필요
`llm_execution`	요청을 변경하지 않고 provider 실행을 감싸거나 단축 반환

실행 미들웨어의 next_call은 한 번만 호출할 수 있습니다. 변환이 필요하면 반드시 request 결합점을 사용합니다.

내부 이벤트와 저장

현재 RuntimeEvent는 57개의 내부 관측 이벤트를 가집니다. HookEvent/HookSystem은 기존 통합을 위한 타입 별칭이며, 새 코드는 RuntimeEvent/RuntimeEventBus를 사용합니다.

관측자는 중첩 데이터까지 격리된 복사본을 받으므로 승인된 tool 인자나 다음 관측자의 입력을 바꾸지 못합니다. 학습 상태 정리는 durable SessionEnd에 연결하며, 과거 turn-end 이벤트로 공유 offload 파일을 삭제하지 않습니다.

저장소	동작
SQLite activity store	운영 이벤트의 정본. 공개 훅과 미들웨어 호출도 `extension.invoked` 행으로 저장
RunTimeline `events.jsonl`	활성 run projection이 있을 때만 같은 typed activity row를 미러링

확장 호출 행은 표면, 이름, 확장자, 상태, 지연, 상관 ID만 보존합니다. 원문 사용자 입력, 전체 요청·응답, 개인 데이터, 비밀값은 저장하지 않습니다.

도구 경계 순서

original policy → tool_request → policy + schema validation
→ PreToolUse → policy + schema revalidation → PermissionRequest / approval
→ pending-call checkpoint → effect admission → terminal executor 1회 호출
→ TOOL_EXEC_ENDED → PostToolUse → receipt commit

위 순서는 새 실행이 결과를 반환하는 경로입니다. 오류 결과는 호환용TOOL_EXEC_FAILED도 알리지만 이중 저장하지 않습니다. admission 거부, 완료 receipt 재생, 전파되는 예외·취소에는PostToolUse를 실행하지 않습니다.

승인이 필요한 요청은 headless에서도 PermissionRequest를 거칩니다. 훅의 결정이 없거나 ask이면 허용된 사람 확인으로 넘기며, 확인할 수 없으면 거부합니다.

여기서 1회는 승인된 한 요청의 프로세스 내부 호출 횟수입니다. 외부 효과의 exactly-once를 뜻하지 않습니다. 변경·통신·관리 도구는 별도의 durable admission receipt로 같은 logical operation의 중복을 억제합니다. receipt에는 PostToolUse까지 끝난 결과를 저장하며, 완료 여부가 불명확하면 자동 재실행하지 않습니다. PostToolUse.executed는 terminal dispatch 진입 여부이지 효과의 성공이 아닙니다. has_error와 결과를 별도로 읽으며, post-hook은 완료된 효과를 되돌리지 못합니다.

훅과 미들웨어