Como os hooks funcionam

O supervisor de hooks é a parte do Pathrule que faz as sessões de IA parecerem como se o assistente já conhecesse as convenções da sua equipe. Ele roda localmente, lê de um cache, entrega memórias e regras relevantes e oferece skills pelo nome antes que o assistente execute a primeira ação. As instruções de uma skill chegam quando você a invoca.

Esta página apresenta um modelo do funcionamento voltado para o usuário. Ela não é um mergulho profundo nos detalhes internos do runtime.

O que é um hook

Um hook é um pequeno script que o seu cliente de IA executa em momentos bem definidos de um turno. O Pathrule usa os eventos de entrega e de aplicação que cada cliente de fato expõe.

• SessionStart informa ao assistente em qual espaço de trabalho ele está, o protocolo do Pathrule e o contexto da sua equipe, uma vez por sessão.
• UserPromptSubmit delimita o escopo do próximo turno nos clientes cujo evento de prompt aceita contexto.
• PreToolUse fornece contexto ou uma decisão de regra estrita antes de uma ação, quando o cliente aceita.
• PostToolUse registra resultados e compensa com contexto vinculado ao caminho nos clientes cujo evento pré-ferramenta aceita decisões, mas não contexto.
• Os eventos de parada e de fim de sessão encerram o turno. No Claude Code e no Codex, uma verificação obrigatória aprovada por uma pessoa pode manter o turno aberto nesse ponto até que o comando dela tenha passado.

pathrule setup e pathrule sync, ou a extensão do VS Code, registram esses hooks para Claude Code, Codex, Cursor e GitHub Copilot. O Windsurf não tem hooks do Pathrule, então o arquivo de regras gerado para ele fornece o bootstrap da sessão e o servidor MCP local fornece contexto mais profundo sob demanda.

Perfis de entrega por cliente

Uma regra estrita é aquela que traz um padrão de bloqueio aprovado por uma pessoa. Veja Regras como guardrails para entender o que bloqueia e o que apenas informa.

O que o hook faz

O supervisor de hooks faz quatro coisas, nesta ordem.

1. Resolve o caminho. Ele mapeia o diretório de trabalho para um nó do espaço de trabalho.
2. Lê o cache. O cache local guarda um índice pré-calculado de memórias, regras e skills para aquele caminho.
3. Molda a fatia. Ele escolhe uma profundidade adequada à intenção. Um ajuste de UI recebe um payload mínimo. Uma correção de bug ou um refactor recebe um payload focado. Prompts de descoberta liberam um payload mais profundo.
4. Devolve o payload. O texto volta ao cliente como contexto de sistema para a próxima ação.

No modo local, todo o fluxo roda na sua máquina. Em um espaço de trabalho do Cloud, o hook de prompt também envia o início do seu prompt (aproximadamente os primeiros 1.000 caracteres) ao Pathrule Cloud para que o conhecimento seja priorizado pelo significado. Se essa chamada estiver lenta ou falhar, o hook recorre à correspondência com o índice local, para que um problema de rede não deixe o turno sem contexto.

O que você vê

A área de contexto do assistente (aquela que o seu editor exibe) ganha uma seção do Pathrule. Ela lista:

• O caminho resolvido pelo hook e também os caminhos onde o trabalho provavelmente está, uma rota que o assistente é instruído a abrir antes de pesquisar. O Pathrule registra se ele fez isso.
• As regras correspondentes, com a respectiva prioridade.
• As memórias mais relevantes para o seu prompt, entregues como corpos completos com os quais o assistente pode agir diretamente. Correspondências menos certas também aparecem, como títulos com ids que você pode ler na íntegra, se quiser.
• As skills que se encaixam nesse escopo, pelo nome, prontas para serem invocadas com ::skill-name.

Se o hook não tiver nada novo e relevante para o caminho atual, ele não adiciona nada, então um turno sem novidades não consome contexto.

Dois canais de entrega

O conhecimento chega ao assistente por dois canais de hook, cada um com uma função diferente.

• O canal por prompt roda uma vez quando você envia um prompt, nos clientes que têm um hook de envio de prompt (Claude Code e Codex). É nele que está a profundidade: as regras que se encaixam no prompt, as memórias com correspondência mais forte como corpos completos com os quais o assistente pode agir diretamente e as skills que parecem relevantes, oferecidas pelo nome. Uma skill é um procedimento, por isso nunca é enviada como instrução; o corpo completo dela chega quando você a invoca com ::skill-name.
• O canal por chamada de ferramenta roda antes ou depois de cada ação em arquivo ou no shell, muitas vezes por turno. Ele é propositalmente leve: traz os nomes e os resumos de uma linha das regras e memórias que se aplicam ao caminho que está sendo tocado, para que o assistente saiba o que existe ali e possa ler um corpo com uma única chamada, se precisar.

No Claude Code e no Codex, tanto o canal de prompt quanto o canal pré-ferramenta chegam ao assistente. Cursor e GitHub Copilot não aceitam contexto no evento de prompt, então o hook de início de sessão leva o bootstrap e o hook pós-ferramenta leva os nomes vinculados ao caminho.

Nenhum dos canais se repete. Um corpo já entregue na sessão não é enviado de novo, e um corpo editado volta a aparecer na próxima vez em que for relevante.

O que fica no disco

Um cliente com o hook do Pathrule instalado recebe o protocolo e o contexto da equipe pelo hook de início de sessão, e não pelo arquivo de instruções. No Claude Code, o contexto de início de sessão passa a fazer parte do prompt de sistema, então ele sobrevive à compactação da conversa. O arquivo de instruções (CLAUDE.md, AGENTS.md, a regra do Cursor ou as instruções do Copilot) mantém apenas uma nota curta do Pathrule, e o Pathrule remove as cópias do protocolo e os arquivos de conhecimento por diretório que ele gravou em versões anteriores. O conteúdo que você mesmo escreveu nesses arquivos permanece.

Dois casos mantêm os arquivos compilados:

• Um cliente sem hook do Pathrule, como o Windsurf, ou um cliente cujo hook não está instalado, mantém o protocolo completo e os arquivos de conhecimento por caminho, porque nada mais os entregaria.
• Se uma versão anterior do Pathrule moveu o seu próprio arquivo de instruções para um backup que ainda não foi restaurado, o Pathrule mantém o arquivo completo até que esse backup seja resolvido, para que você nunca fique olhando para uma nota curta enquanto as suas instruções estão em outro lugar.

Para manter os arquivos compilados mesmo com o hook instalado, defina PATHRULE_SIGNATURE_MODE=off no ambiente do runtime do Pathrule.

Quando o hook não basta

Os hooks foram projetados para o caso comum. O assistente sempre pode recorrer às ferramentas MCP quando precisar de mais.

• Para prompts de descoberta ("liste tudo o que sabemos sobre faturamento"), o assistente chama pathrule_get_context diretamente.
• Para corpos completos de memórias, o assistente chama pathrule_read_memory com o id trazido pelo hook.
• Para escritas (o usuário pede para salvar uma convenção ou uma regra), o assistente usa a ferramenta de escrita correspondente.

O hook é o caminho rápido. O MCP é o caminho profundo. Os dois compartilham a mesma fonte da verdade.

O escopo por caminho mantém tudo enxuto

O hook devolve uma fatia moldada pelo diretório de trabalho.

• Uma alteração em apps/web/dashboard não traz regras sobre migrações de banco de dados.
• Uma alteração em services/billing/webhooks traz as regras de faturamento e a skill de reprocessamento de webhooks, e não as convenções do site de marketing.
• Um prompt de descoberta na raiz do repositório traz uma visão geral do espaço de trabalho, e não todos os corpos.

É o escopo por caminho que mantém o contexto entregue pequeno em comparação com um único arquivo de instruções global que toda sessão carrega por inteiro.

Quando nada aparece

Se você abrir uma sessão e a seção do Pathrule estiver vazia, execute o doctor.

pathrule doctor

Ele é somente leitura e verifica:

• Seu login, sua organização e seu espaço de trabalho.
• Se a pasta atual está vinculada a um espaço de trabalho.
• Se a entrada MCP do Pathrule está instalada em cada cliente de IA.
• Quais arquivos gerenciados pelo Pathrule estão na pasta, e qual superfície e qual versão do Pathrule os gravou.

A saída termina com o próximo comando a executar quando algo precisa de atenção. Adicione --json para obter o relatório completo, que também cobre a versão do Node e aponta uma entrada MCP que se refere a um runtime que não existe mais.

Para colocar as peças locais de volta no lugar, execute:

pathrule repair

O repair reescreve entradas MCP desatualizadas, reinstala o script do hook e o registro de hook de cada cliente, sincroniza novamente os arquivos complementares e o cache local que o hook lê, e executa o doctor mais uma vez.

Se em algum momento você quiser desligar todos os hooks do Pathrule de uma vez, crie ~/.pathrule/kill-hooks. A próxima chamada de hook passa direto; remova o arquivo para religar os hooks.

O que ler em seguida

• Visão geral do MCP para conhecer o conjunto de ferramentas que sustenta o caminho profundo.
• Conceitos principais para entender o modelo de dados que o hook lê.
• Instalação do CLI para instalar o runtime que hospeda o supervisor de hooks.