Overview

도구 호출이 어디서 시작됐는지 추적해서, 실행하기 전에 막을지 판정하는 엔진의 명세입니다.

WithHuman 엔진은 AI 에이전트(Claude Code)가 도구를 호출하기 전에 그 호출을 막을지 판정하는 PDP(Policy Decision Point)입니다. 판정 근거는 호출이 어디서 시작됐는지입니다. 간접 프롬프트 인젝션이 대표적인 시나리오지만, 오류 뒤의 권한 상승이나 맡은 범위를 벗어난 행동도 같은 방식으로 다룹니다. 에이전트는 수정하지 않고 훅만 사용합니다.

이 페이지에서는 엔진의 구성, 이벤트 흐름, 시간 제한, 1차 범위를 설명합니다. 모듈별 입력과 출력은 각 모듈 페이지에 있습니다.

명세를 읽는 법

이 명세는 2026년 10월 1일 인계 문서를 기준으로 씁니다. 따로 언급하지 않은 내용은 인계 문서에서 확정된 것입니다. 명세 v0을 쓰면서 새로 정한 내용과 인계 문서가 임시로 둔 값은 본문에서 초안이라고 밝힙니다. 아직 정하지 않은 내용은 각 페이지 마지막의 “미정” 절과 Open Questions에 모읍니다.

핵심 아이디어

출처가 아니라 원인을 봅니다

외부 문서에서 온 값을 모두 막자 정상 작업의 56~62%가 함께 막혔습니다. 값이 문서에서 왔다는 것과 문서가 그 행동을 시켰다는 것은 다른 문제입니다.

할 일을 다리로 씁니다

에이전트는 도구를 호출하기 직전에 할 일을 화면에 씁니다(MessageDisplay). 호출을 이 할 일에 연결하고 할 일의 출처를 Jev에 물으면, 호출에서 시작점까지 거슬러 올라갈 수 있습니다.

의도를 추측하지 않습니다

“사용자가 이걸 시켰는가”를 직접 물으면 모호한 요청에서 점수가 0.5~0.7에 몰립니다. 그래서 두 글 사이의 좁은 관계만 예/아니오로 묻고, 반사실 재실행은 하지 않습니다.

ProvenanceGuard와의 차이

가장 가까운 연구인 ProvenanceGuard(ASE 2026)와 달리, 계획(할 일) 자체의 출처까지 추적하고 행동을 시킬 수 있는 곳을 사용자가 준 일로 제한합니다.

엔진 구성

Claude Codehooks

HTTP 127.0.0.1POST /v1/hooks

agentgatewayMCP tools/call

ext_authz gRPC

Engine Daemon

Collector
Segment Analyzer
Causal Structure Layer
- Call Parser
- Token Index
- Provenance Tracer
Decision Module
PEP

Shared

Jev Client질문 묶음 · 캐시→ Jev

Provenance Log기록→ Redis

Engine Daemon이 Claude Code 훅과 agentgateway의 요청을 받고, 안에서는 Collector부터 PEP까지 차례로 처리합니다. Jev Client와 Provenance Log는 여러 모듈이 함께 쓰는 공통 모듈입니다. 호출을 막는 곳은 두 군데입니다. 내장 도구는 PreToolUse 훅에서, MCP 도구는 agentgateway의 ext_authz에서 막습니다.

훅은 127.0.0.1의 HTTP로 엔진에 이벤트를 보내고, 엔진과 Redis, agentgateway는 Docker로 로컬에서 실행합니다. 엔진 코드는 OS에 의존하지 않으며 1차 지원 대상은 macOS와 Linux입니다. 이 실행 환경은 이번 명세에서 정한 초안입니다. Jev를 어디서 실행할지는 아직 정하지 않았습니다.

이벤트 흐름

한 번의 작업에서 이벤트는 대체로 아래 순서로 들어옵니다. MessageDisplay가 PreToolUse보다 먼저 온다는 것은 비대화 모드 25건에서만 확인했습니다.

MCP 도구를 한 번 호출할 때의 이벤트 순서

모든 이벤트는 Engine Daemon으로 들어와 Collector에서 순번을 받습니다. 그다음 거치는 모듈은 이벤트마다 다릅니다.

이벤트	거치는 모듈	하는 일
UserPromptSubmit	Collector	요청을 Request 노드로 저장하고, 요청에서 사용자가 가리킨 문서(이슈, 붙여 넣은 글, 링크)를 기록합니다.
MessageDisplay	Collector → Provenance Tracer	할 일을 Task 노드로 저장하고, 호출이 오기 전에 부모를 미리 판단합니다.
PreToolUse	Collector → Call Parser → Token Index → Provenance Tracer → Decision Module → PEP	호출을 요소로 나누고, 시작점을 찾아 판정한 뒤 훅에 응답합니다.
PostToolUse	Collector → Segment Analyzer	tool_response를 문단으로 나눠 Segment 노드로 저장하고, 문단마다 시키는 문장인지, 주제인지, 숨긴 글인지 표시합니다.
ext_authz	PEP	MCP 호출의 판정을 tool_use_id로 찾아 허용하거나 거부합니다.

TaskCreated를 수집할지는 아직 정하지 않았습니다.

시간 제한

항목	한도
PreToolUse 전체	5초
엔진 마감	3초
Jev 호출 1회	1.5초
훅 명령의 curl `--max-time`	4초

내장 도구가 통과일 때는 PreToolUse에 아무 응답도 하지 않습니다. allow를 보내면 Claude Code의 원래 권한 확인을 건너뛰기 때문입니다. MCP는 판정이 없으면 차단합니다(fail closed).

훅 명령은 curl -sf --max-time 4 ... || true 형태로 둡니다. 엔진이 꺼져 있어도 훅은 정상 종료되고, Claude Code의 원래 권한 확인으로 넘어갑니다. 훅 명령의 형태와 4초 제한은 이번 명세에서 정한 초안입니다.

1차 범위

10월 10일 IPI(Indirect Prompt Injection) 환경 평가까지는 판정 없이 기록부터 쌓고, Jev에 대한 가정을 먼저 검증한 다음 트레이서를 만듭니다.

단계	기간	내용
1. 수집기	1~2일	훅 이벤트 네 가지를 받아 노드로 저장합니다. 판정은 모두 통과입니다.
2. Jev 질문 검증	2일, 1단계와 병행	쌓인 기록으로 질문을 시험하고, 질문 문구와 기준 점수를 정합니다.
3. 최소 트레이서와 판정	3일	할 일 연결, 바깥 영향 판별, 시작점 찾기, Provenance Record, 판정을 만듭니다.
4. 차단 연결과 평가	2일	내장 도구와 MCP 차단을 연결하고, 공격 차단율과 정상 작업 통과율을 측정합니다.

평가 전에는 Bash 파서의 heredoc과 함수 정의 처리, 오류 대응, 결과에서 계산된 값의 근거 확인, 사용자에게 묻는 세부 흐름을 다루지 않습니다. 오류 대응(responds_to와 ERROR)은 1차에서 기록만 합니다. 평가에서는 묻기를 차단으로 계산합니다.