> ## Documentation Index
> Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 에이전트 하네스

> 지원되는 에이전트 CLI에서 세션을 캡처하고 정책을 적용합니다.

Failproof AI는 Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin CLI, Antigravity CLI, Goose를 지원합니다.

| 하네스                                              | 지원되는 훅 범위            |
| ------------------------------------------------ | -------------------- |
| Claude Code                                      | User, project, local |
| Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi  | User, project        |
| Factory Droid, Devin CLI, Antigravity CLI, Goose | User, project        |
| Hermes, OpenClaw                                 | User                 |

각 통합은 정책이 실행되기 전에 네이티브 훅 이벤트 이름, 도구 이름, 도구 입력 필드를 정규화합니다. 정책은 하네스가 노출하는 이벤트에만 적용할 수 있으며, 실제로 배포할 하네스 및 버전에서 턴 종료와 명령 동작을 직접 테스트하십시오.

## 적용 기능

"블록"이란 현재 어댑터가 반환한 판정이 해당 하네스에 의해 소비됨을 의미합니다. 도구 사후 차단은 모델에 표시되는 결과를 대체할 수 있지만, 이미 발생한 도구 사이드 이펙트를 되돌릴 수는 없습니다.

| 하네스                | 검증된 차단 이벤트                                                                                                   | 관찰 전용 또는 비차단 주의사항                                                                |
| ------------------ | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| Claude Code        | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact`, 및 여러 태스크/설정 이벤트 | `PostToolUse`, 세션 라이프사이클, 알림, 실패 후 이벤트는 관찰용입니다.                                  |
| Codex              | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse`                 | 도구 사후 차단은 실행 후 결과를 대체하며, 세션 시작 및 컴팩트 이벤트는 현재 어댑터에서 관찰용입니다.                       |
| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse`                 | 도구 사후 차단은 실행 후 결과를 대체하며, 세션 및 알림 이벤트는 관찰용입니다.                                    |
| Cursor             | `PreToolUse`, `UserPromptSubmit`, `Stop`                                                                     | `PostToolUse` 및 세션 이벤트는 관찰용입니다.                                                  |
| OpenCode           | `PreToolUse`                                                                                                 | 도구 사후 및 라이프사이클 이벤트는 관찰용이며, 현재 stop 처리는 검증된 게이트가 아닌 이후 턴에 대한 안내입니다.               |
| Pi                 | `PreToolUse`, `UserPromptSubmit`                                                                             | 도구 사후 및 라이프사이클 이벤트는 관찰용이며, stop 안내는 이후 턴에 적용됩니다.                                 |
| Hermes             | `PreToolUse`                                                                                                 | 도구 사후, 세션, 서브에이전트 stop 판정은 게이트가 아닙니다.                                            |
| OpenClaw           | `PreToolUse`, `UserPromptSubmit`, `Stop`                                                                     | 도구 사후, 세션, 서브에이전트 stop, 컴팩션 이벤트는 관찰용입니다.                                         |
| Factory Droid      | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact`                                                       | 도구 사후 및 서브에이전트 stop 판정은 관찰용입니다.                                                  |
| Devin CLI          | `PreToolUse`, `UserPromptSubmit`, `Stop`, 조건부 `PermissionRequest`                                            | 권한 훅은 모든 권한 모드에서 실행되지 않으며, 도구 사후 및 세션 이벤트는 관찰용입니다.                               |
| Antigravity CLI    | `PreToolUse`, `Stop`                                                                                         | 사용자 프롬프트 및 도구 사후 판정은 관찰용이며, 프롬프트 명령은 여전히 주입될 수 있습니다.                             |
| Goose              | `PreToolUse`                                                                                                 | 사용자 프롬프트, 도구 사후, 세션 이벤트는 관찰용입니다. 네이티브 차단 stop 훅이 업스트림에 존재하지만 현재 어댑터에는 설치되지 않습니다. |

기능은 버전에 따라 달라집니다. 특히 정책이 공통 사전 도구 게이트가 아닌 프롬프트, stop, 권한, 도구 사후 동작에 의존하는 경우, 에이전트 CLI를 업그레이드한 후 반드시 재테스트하십시오.

## 캡처 및 정책 훅 설치

<Tabs>
  <Tab title="대시보드">
    1. **관리 → 키**를 열고 머신 또는 환경 이름으로 `events:add`와 `policies:pull` 권한을 가진 키를 생성합니다.
    2. 대상 머신에서 표시된 키로 로컬 CLI를 연결하고 하네스 훅을 설치합니다.
    3. 새 에이전트 세션을 시작한 후 **관찰 → 이벤트**에서 해당 훅 및 세션 이벤트를 확인합니다.
    4. 동일한 시간대에 **관찰 → 정책**을 열고 해당 머신에 정책 결정이 귀속되었는지 확인합니다.

    연결은 머신 키로 시작됩니다. 시크릿을 복사하기 전에 인제스션 및 정책 전달 권한이 모두 포함되어 있는지 확인하십시오.

    <img src="https://mintcdn.com/exosphere/WgPwQzedeDNwJBTy/images/dashboard/key-create.png?fit=max&auto=format&n=WgPwQzedeDNwJBTy&q=85&s=a428bdae79f837471acb66414ff6455b" alt="이벤트 인제스션 및 정책 전달 권한을 부여하는 새 API 키 드로어." width="2940" height="1604" data-path="images/dashboard/key-create.png" />

    훅을 설치한 후, 이벤트 스트림에 연결한 머신 및 환경의 새 이벤트가 표시되어야 합니다.

    <img src="https://mintcdn.com/exosphere/WgPwQzedeDNwJBTy/images/dashboard/events-stream.png?fit=max&auto=format&n=WgPwQzedeDNwJBTy&q=85&s=2cbda31a05ade12cbf015f6800ba34e1" alt="새로 설치된 하네스가 보고 중인지 확인하는 라이브 이벤트 스트림." width="3200" height="2000" data-path="images/dashboard/events-stream.png" />

    마지막으로, 동일한 머신에 정책 결정이 귀속되는지 확인합니다. 이는 하네스가 트레이스 이벤트뿐만 아니라 정책 활동도 보고하고 있음을 확인합니다.

    <img src="https://mintcdn.com/exosphere/WgPwQzedeDNwJBTy/images/dashboard/policy-observe.png?fit=max&auto=format&n=WgPwQzedeDNwJBTy&q=85&s=13535ad27c8bddac6589f9d1560916cb" alt="새로 연결된 하네스의 정책 결정을 검증하는 정책 페이지." width="2372" height="1548" data-path="images/dashboard/policy-observe.png" />
  </Tab>

  <Tab title="CLI">
    감지된 모든 하네스에 훅을 설치합니다:

    ```bash theme={null}
    failproofai config \
      --connect https://app.befailproof.ai \
      --token <machine-key>
    failproofai policies --install
    ```

    또는 특정 하네스와 설정 범위를 지정합니다:

    ```bash theme={null}
    failproofai policies --install \
      --cli claude codex cursor \
      --scope user
    ```

    프로젝트 범위는 훅 설정을 저장소와 함께 유지합니다. 사용자 범위는 여러 저장소에 걸친 작업을 포괄합니다. Claude Code는 local 범위도 지원하며, 지원 여부는 하네스에 따라 다르고 CLI는 지원되지 않는 조합을 거부합니다.

    머신 및 이벤트를 확인합니다:

    ```bash theme={null}
    failproofai config --status
    failproofai flush --wait
    fp events --since 1h --event-type hook_triggered,hook_completed
    ```
  </Tab>
</Tabs>

## 기본값이 아닌 세션 경로 추가

<Tabs>
  <Tab title="대시보드">
    추가 경로는 클라우드가 아닌 머신에 등록됩니다. 경로를 추가한 후 **관찰 → 세션**을 열고 머신 환경으로 필터링하여 새 경로의 세션이 표시되는지 확인합니다. 세션을 열고 감사에 활용하기 전에 에이전트, 하네스, 이벤트 타임스탬프를 확인하십시오.

    <img src="https://mintcdn.com/exosphere/WgPwQzedeDNwJBTy/images/dashboard/sessions-list.png?fit=max&auto=format&n=WgPwQzedeDNwJBTy&q=85&s=f1fb545746143e87b8b5daedabfc5559" alt="추가 캡처 경로의 데이터를 수신하는 환경으로 필터링된 세션 목록." width="3200" height="2000" data-path="images/dashboard/sessions-list.png" />
  </Tab>

  <Tab title="CLI">
    선택적 레이블과 함께 경로를 추가한 후 설정된 경로를 확인합니다:

    ```bash theme={null}
    failproofai harness add-path claude checkout=/srv/checkout/.claude
    failproofai harness list claude
    failproofai backfill --since 7d --dry-run
    failproofai backfill --since 7d
    ```

    `failproofai harness remove-path claude checkout`으로 경로를 제거합니다.
  </Tab>
</Tabs>

<Tip>
  설치 후 새 세션을 하나 실행하십시오. 롤아웃을 확대하기 전에 라이브 이벤트 스트림과 실제 정책 결정을 모두 확인하십시오.
</Tip>