Hook 시스템

​

훅이 존재하는 이유

​

훅이 연결되는 위치

​

훅 vs. 명령어 선택 기준

​

훅 계약

class ReadOnlyGuard(PreToolUseHook):
    name = "readonly_guard"
    priority = 5                          # lower runs earlier

    def should_trigger(self, ctx: HookContext) -> bool:
        return ctx.tool_name.startswith("sql_")

    async def execute(self, ctx: HookContext) -> HookResult:
        if org_is_readonly(ctx.metadata["org_id"]):
            return HookResult(
                allow=False,
                error="Org is in read-only mode — write blocked.",
                side_effects=["readonly_guard: blocked sql write"],
            )
        return HookResult()               # default: allow=True, no mutation

• allow: bool = True — 도구 호출 진행 여부 (PostToolUse / SessionStart에서는 무시됨)
• error: str | None — 인간이 읽을 수 있는 이유로, 차단될 때 LLM에 관찰로 표시됨
• modified_args: dict | None — 설정된 경우, 실행 전에 도구 인자를 대체함
• modified_result: Any | None — 설정된 경우 (PostToolUse), LLM으로 반환되기 전에 관찰을 대체함
• side_effects: list[str] — 훅이 수행한 작업의 감사 추적으로, 에이전트의 추적에 병합됨

​

사례 연구: FeishuGateHook

• 도구 호출이 진정으로 일시 중지됩니다. 에이전트의 SSE 스트림은 “I will call oa__purchase_pay”와 관찰 사이에서 일시 중지됩니다. 사용자는 에이전트가 대기 중인 것을 보며, 이는 내부에서 일어나는 일과 일치합니다.
• 승인이 프로세스 재시작을 견딥니다. 대기 중인 행은 데이터베이스에 있으며, 메모리에는 없습니다. 카드가 미결 상태일 때 백엔드가 재시작되면, 다음 폴링이 중단된 지점부터 계속됩니다.
• 결정이 감사됩니다. ConfirmationRequest는 payload, responded_at, responded_by_open_id 및 최종 상태를 유지합니다. 누가 무엇을 언제 승인했는지에 대한 감사 가능한 기록입니다.
• 의사 결정 루프에 LLM이 없습니다. 모델이 도구 호출을 생성합니다. 인간이 판정을 생성합니다. 훅은 결정론적 다리입니다.

​

계획된 훅 (v0.9)

​

Hooks vs. Channels

​

Current state (v0.8.4)

• ✅ HookRegistry, HookContext, HookResult primitives가 ReAct와 DAG 모두에 연결됨
• ✅ PreToolUseHook / PostToolUseHook / SessionStartHook 추상 기본 클래스
• ✅ FeishuGateHook — 완성됨. ConfirmationRequest 테이블, 폴링 루프, 타임아웃/만료, 콜백 기반 상태 전환 포함
• ✅ Feishu 채널 콜백 엔드포인트가 card.action.trigger를 디코딩하고 pending 행을 업데이트함
• ✅ Agent 레벨 hook 선언: agent.model_config_json.hooks.class_hooks가 모든 ReAct/DAG 세션에서 인스턴스화된 HookRegistry로 해석됨
• ✅ Hooks가 모든 실행 표면에서 작동: 메인 채팅 경로(Portal, API, DAG), 위임된 sub-agent(CallAgentTool), Workflow AGENT 노드. Eval Center는 의도적으로 hooks를 우회함 (자동화된 평가는 인간 승인에서 차단되면 안 됨). 위임된 agent는 호출자의 registry를 상속하지 않음 — 자신의 model_config_json에서 자신의 것을 빌드함. 확인 闸门이 모든 agent에 자동으로 첨부되므로, 재구축은 상속의 상위 집합임: delegate는 闸门 plus 자신이 선언한 것을 얻고, 闸门은 호출자의 require_confirmation_for_all이 아닌 delegate의 것을 해석함. 두 표면 모두 closed fail: hooks를 빌드할 수 없는 agent는 실행되지 않음.
• ❌ AuditLogHook, ReadOnlyGuard, ResultTruncateHook, ConnectorRateLimitHook (v0.9)
• ❌ 사용자 정의 YAML hook 선언 (v0.9)