Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
106 changes: 56 additions & 50 deletions docs/ar/reference/harnesses.mdx

Large diffs are not rendered by default.

88 changes: 47 additions & 41 deletions docs/de/reference/harnesses.mdx

Large diffs are not rendered by default.

96 changes: 56 additions & 40 deletions docs/es/reference/harnesses.mdx

Large diffs are not rendered by default.

88 changes: 47 additions & 41 deletions docs/fr/reference/harnesses.mdx

Large diffs are not rendered by default.

104 changes: 55 additions & 49 deletions docs/he/reference/harnesses.mdx

Large diffs are not rendered by default.

98 changes: 52 additions & 46 deletions docs/hi/reference/harnesses.mdx

Large diffs are not rendered by default.

108 changes: 57 additions & 51 deletions docs/it/reference/harnesses.mdx

Large diffs are not rendered by default.

84 changes: 45 additions & 39 deletions docs/ja/reference/harnesses.mdx

Large diffs are not rendered by default.

92 changes: 49 additions & 43 deletions docs/ko/reference/harnesses.mdx

Large diffs are not rendered by default.

68 changes: 37 additions & 31 deletions docs/pt-br/reference/harnesses.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,68 +4,74 @@ description: "Capture sessões e aplique políticas em todos os 12 harnesses de
icon: "plug-zap"
---

Um harness é o ambiente no qual seu agente realmente executa. Failproof AI suporta doze deles, em duas categorias:
Um harness é o ambiente em que seu agente realmente executa. O Failproof AI suporta doze deles, em duas categorias:

- **CLIs de codificação** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose
- **Gateways de chat e assistentes** (2) — Hermes (Slack, Telegram, cron), OpenClaw (assistente auto-hospedado)
- **Gateways de chat e assistente** (2) — Hermes (Slack, Telegram, cron), OpenClaw (assistente auto-hospedado)

As mesmas políticas e o mesmo histórico de sessões se aplicam independentemente de qual harness o agente utiliza. Uma camada de adaptador mapeia os nomes de eventos nativos, nomes de ferramentas e campos de entrada de ferramentas de cada harness para 29 eventos canônicos antes que qualquer política seja executada.

Um agente que não utiliza **nenhum** dos doze é instrumentado diretamente com o [SDK Python](/pt-br/reference/custom-agents). Esse é um contrato diferente, e vale dizer claramente: o SDK oferece rastreamento, sessões, avaliações e auditorias — **mas não aplica políticas por conta própria.** Bloquear uma ação insegura antes que ela seja executada requer um hook de enforcement no limite de ferramentas do seu runtime; [entre em contato](mailto:support@befailproof.ai) e iremos mapeá-lo.
Um agente que não roda em **nenhum** dos doze é instrumentado diretamente com o [Python SDK](/pt-br/reference/custom-agents). Esse é um contrato diferente, e vale deixar claro: o SDK fornece rastreamento, sessões, avaliações e auditorias — **ele não aplica políticas por conta própria.** Bloquear uma ação insegura antes de sua execução requer um hook de aplicação no limite de ferramentas do seu runtime; [entre em contato conosco](mailto:support@befailproof.ai) e faremos o mapeamento.

| Harness | Escopos de hook suportados |
| --- | --- |
| 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 | Usuário, projeto, local |
| Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi | Usuário, projeto |
| Factory Droid, Devin CLI, Antigravity CLI, Goose | Usuário, projeto |
| Hermes, OpenClaw | Usuário |

Cada integração normaliza os nomes de eventos de hook nativos, nomes de ferramentas e campos de entrada de ferramentas antes que as políticas sejam executadas. Uma política só pode agir sobre eventos que o harness expõe; teste o comportamento de fim de turno e de instrução no harness e versão exatos que você implanta.
Cada integração normaliza seus nomes de eventos de hook nativos, nomes de ferramentas e campos de entrada de ferramentas antes que as políticas sejam executadas. Uma política só pode agir sobre eventos que o harness expõe; teste o comportamento de fim de turno e de instrução no harness e versão exatos que você vai implantar.

## Capacidade de enforcement
## Capacidade de aplicação

"Bloquear" significa que o veredicto retornado pelo adaptador atual é consumido pelo harness indicado. O bloqueio pós-ferramenta pode substituir o resultado exibido ao modelo, mas não pode desfazer um efeito colateral de ferramenta que já ocorreu.

| Harness | Eventos de bloqueio verificados | Ressalvas de observação apenas ou sem bloqueio |
| Harness | Eventos de bloqueio verificados | Ressalvas de observação ou não bloqueantes |
| --- | --- | --- |
| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact` e vários eventos de task/config | `PostToolUse`, ciclo de vida de sessão, notificações e eventos pós-falha são observacionais. |
| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact` e vários eventos de tarefa/configuração | `PostToolUse`, ciclo de vida de sessão, notificações e eventos pós-falha são observacionais. |
| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | O bloqueio pós-ferramenta substitui o resultado após a execução; eventos de início de sessão e compactação são observacionais no adaptador atual. |
| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | O bloqueio pós-ferramenta substitui o resultado após a execução; eventos de sessão e notificação são observacionais. |
| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` e eventos de sessão são observacionais. |
| OpenCode | `PreToolUse` | Eventos pós-ferramenta e de ciclo de vida são observacionais; o tratamento de stop atual é uma orientação para um turno posterior, não um gate verificado. |
| OpenCode | `PreToolUse` | Eventos pós-ferramenta e de ciclo de vida são observacionais; o tratamento de stop atual é uma orientação para um turno posterior, e não um gate verificado. |
| Pi | `PreToolUse`, `UserPromptSubmit` | Eventos pós-ferramenta e de ciclo de vida são observacionais; a orientação de stop se aplica a um turno posterior. |
| Hermes | `PreToolUse` | Veredictos pós-ferramenta, de sessão e de subagent-stop não são gates. |
| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Eventos pós-ferramenta, de sessão, subagent-stop e compactação são observacionais. |
| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | Veredictos pós-ferramenta e subagent-stop são observacionais. |
| Hermes | `PreToolUse` | Um plugin nativo entrega `instruct()` como uma interrupção delimitada e visível ao modelo antes de permitir uma iteração de API posterior. Veredictos pós-ferramenta, de sessão e de subagent-stop não são gates. |
| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Eventos pós-ferramenta, de sessão, de subagent-stop e de compactação são observacionais. |
| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | Veredictos pós-ferramenta e de subagent-stop são observacionais. |
| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PermissionRequest` condicional | Hooks de permissão não são executados em todos os modos de permissão; eventos pós-ferramenta e de sessão são observacionais. |
| Antigravity CLI | `PreToolUse`, `Stop` | Veredictos de user-prompt e pós-ferramenta são observacionais; instruções de prompt ainda podem ser injetadas. |
| Goose | `PreToolUse` | Eventos de user-prompt, pós-ferramenta e de sessão são observacionais. Existe um hook de stop de bloqueio nativo upstream, mas não é instalado pelo adaptador atual. |
| Antigravity CLI | `PreToolUse`, `Stop` | Veredictos de prompt de usuário e pós-ferramenta são observacionais; instruções de prompt ainda podem ser injetadas. |
| Goose | `PreToolUse` | Eventos de prompt de usuário, pós-ferramenta e de sessão são observacionais. Um hook de stop nativo com bloqueio existe upstream, mas não é instalado pelo adaptador atual. |

As capacidades são sensíveis à versão. Repita os testes após atualizar um CLI de agente, especialmente quando uma política depende de comportamento de prompt, stop, permissão ou pós-ferramenta em vez do gate pré-ferramenta comum.
As capacidades são sensíveis à versão. Repita os testes após atualizar um CLI de agente, especialmente quando uma política depende de comportamento de prompt, stop, permissão ou pós-ferramenta, em vez do gate comum de pré-ferramenta.

## Instalar hooks de captura e políticas
### Plugin nativo do Hermes

O Hermes é integrado por meio de um plugin nativo local de perfil, em vez de um comando de shell. A instalação copia o plugin em todos os perfis Hermes padrão e nomeados, o habilita no `config.yaml` desse perfil e migra apenas entradas legadas de shell-hook do FailproofAI. Isso evita um spawn de processo a cada hook e permite que `instruct()` alcance o modelo por meio do resultado de ferramenta bloqueada nativo do Hermes.

A primeira instrução correspondente bloqueia a chamada pendente. A mesma requisição de API permanece bloqueada; uma iteração posterior do modelo pode tentar novamente. Um ledger persistente com escopo de perfil e um limite por turno impedem que uma instrução consultiva se torne um loop ilimitado. `deny()` continua sendo um bloqueio definitivo. Execute `failproofai config --status` para detectar um perfil desabilitado, incompleto, duplicado ou não configurado recentemente.

## Instalar hooks de captura e de política

<Tabs>
<Tab title="Dashboard">
1. Abra **AdministrationKeys** e crie uma chave com `events:add` e `policies:pull`, nomeada para a máquina ou ambiente.
1. Abra **AdministraçãoChaves** e crie uma chave com `events:add` e `policies:pull`, nomeada para a máquina ou ambiente.
2. Na máquina de destino, conecte o CLI local com a chave exibida e instale os hooks do harness.
3. Inicie uma nova sessão de agente e confirme seus eventos de hook e sessão em **ObserveEvents**.
4. Abra **Observepolicy** para a mesma janela de tempo e confirme que uma decisão de política está atribuída à máquina.
3. Inicie uma nova sessão de agente e confirme seus eventos de hook e de sessão em **ObservarEventos**.
4. Abra **Observarpolítica** para a mesma janela de tempo e confirme que uma decisão de política está atribuída à máquina.

A conexão começa com uma chave de máquina. Confirme que ela inclui permissões de ingestão e entrega de políticas antes de copiar o segredo.
A conexão começa com uma chave de máquina. Confirme que ela inclui permissões de ingestão e de entrega de políticas antes de copiar seu secret.

![O drawer de nova chave de API usado para conceder permissões de ingestão de eventos e entrega de políticas.](/images/dashboard/key-create.png)

Após instalar os hooks, o stream de eventos deve mostrar novos eventos da máquina e do ambiente que você conectou.
Após instalar os hooks, o stream de Eventos deve mostrar novos eventos da máquina e do ambiente que você conectou.

![O stream de eventos ao vivo usado para confirmar que um harness recém-instalado está reportando.](/images/dashboard/events-stream.png)
![O stream de Eventos ao vivo usado para confirmar que um harness recém-instalado está reportando.](/images/dashboard/events-stream.png)

Por fim, verifique se as decisões de política estão atribuídas à mesma máquina. Isso confirma que o harness está reportando atividade de políticas além dos eventos de rastreamento.
Por fim, verifique se as decisões de política estão atribuídas à mesma máquina. Isso confirma que o harness está reportando atividade de política, além dos eventos de rastreamento.

![A página de políticas usada para verificar decisões de política de um harness recém-conectado.](/images/dashboard/policy-observe.png)
![A página de Política usada para verificar decisões de política de um harness recém-conectado.](/images/dashboard/policy-observe.png)
</Tab>
<Tab title="CLI">
Leia a chave da máquina no shell. `read -s` a solicita em um prompt que não exibe a entrada, portanto ela nunca aparece em um comando ou no histórico do shell:
Leia a chave da máquina no shell. `read -s` a captura em um prompt que não exibe o input, para que ela nunca apareça em um comando ou no histórico do shell:

```bash
read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN
Expand All @@ -88,7 +94,7 @@ As capacidades são sensíveis à versão. Repita os testes após atualizar um C
--scope user
```

O escopo de projeto mantém a configuração de hooks junto ao repositório. O escopo de usuário cobre o trabalho entre repositórios. Claude Code também suporta escopo local; o suporte varia por harness e o CLI rejeita combinações não suportadas.
O escopo de projeto mantém a configuração de hook junto a um repositório. O escopo de usuário cobre o trabalho em múltiplos repositórios. Claude Code também suporta escopo local; o suporte varia por harness e o CLI rejeita combinações não suportadas.

Verifique a máquina e seus eventos:

Expand All @@ -104,9 +110,9 @@ As capacidades são sensíveis à versão. Repita os testes após atualizar um C

<Tabs>
<Tab title="Dashboard">
Caminhos extras são registrados na máquina, não no Cloud. Após adicionar um, abra **ObserveSessions**, filtre pelo ambiente da máquina e confirme que as sessões do novo caminho aparecem. Abra uma sessão e verifique o agente, o harness e os timestamps de eventos antes de utilizá-la em uma auditoria.
Caminhos extras são registrados na máquina, não no Cloud. Após adicionar um, abra **ObservarSessões**, filtre pelo ambiente da máquina e confirme que as sessões do novo caminho aparecem. Abra uma sessão e verifique o agente, o harness e os timestamps de eventos antes de usá-la em uma auditoria.

![A lista de sessões filtrada pelo ambiente que recebe dados do caminho de captura adicional.](/images/dashboard/sessions-list.png)
![A lista de Sessões filtrada para o ambiente que recebe dados do caminho de captura adicional.](/images/dashboard/sessions-list.png)
</Tab>
<Tab title="CLI">
Adicione um caminho com um rótulo opcional e inspecione os caminhos configurados:
Expand Down
Loading