§ architecture · os modos de hook

Cada modo de hook e por que ele existe

Um projeto gerado registra um único programa, o ArchHook.jar, várias vezes, cada uma com um modo diferente. Um modo é um trabalho: manter uma skill dentro do seu território, segurar uma fronteira, rodar os testes, registrar a run. Esta página lista todos: para que serve cada um, se ele pode parar o trabalho e se um projeto pode mudá-lo.

O catálogo

12 linhas. O ArchHook.jar tem onze modos, mas doctor, export e build rodam à mão e não são hooks, então não estão aqui. Os hooks que um projeto registra são os outros oito, com o guard dividido nas suas cinco fases. Uma linha pode representar vários modos que dividem um trabalho: tests também cobre tests agent-start e tests agent-end, e audit cobre os seus doze modos.

Modo	Dispara em	Por que existe	Bloqueia?	O projeto pode mudar?
guard: cada peça fica dentro do seu território
`guard prompt`	`UserPromptSubmit`	Sabe qual skill está rodando.	nunca	não
`guard call`	`PreToolUse`	Mantém uma run de design longe das skills de build.	Uma chamada `Skill` a uma skill de classe build enquanto uma run de design está aberta.	não
`guard write`	`PreToolUse`	A escrita fica no território da classe.	Uma escrita fora do território da skill ou do agente em execução, e qualquer escrita em um caso de uso aprovado, salvo o fechamento do status e o marcar de checklist.	não
`guard bash`	`PreToolUse`	A mesma checagem, pelo shell.	Uma escrita via shell em um lugar que a classe não pode escrever ou em um caso de uso congelado, e um force push em qualquer grafia.	não
`guard sweep`	`Stop`	O reforço no fim do turno.	Qualquer mudança deste turno que a classe não pode escrever. Ele detecta; não previne.	não
schema: os arquivos de instrução continuam válidos
`schema`	`PreToolUsePostToolUseStop`	Os arquivos do próprio harness continuam válidos.	Um `SKILL.md`, agente, regra ou entrada de hook do `settings.json` inválido, e um segredo no `.mcp.json`.	não
build: o código continua correto
`check`	`PostToolUse`	A arquitetura é julgada a cada edição.	Um import ou nome qualificado proibido, ou uma compilação incremental que falha no módulo tocado. O arquivo já foi escrito, então o Claude é mandado corrigir.	não
`format`	`PostToolUse`	Formatar nunca custa um turno.	nunca	não
`tests`	`SubagentStartSubagentStopStop`	Um turno não termina com teste vermelho.	O fim do turno enquanto o `verify` falha nos módulos alterados desde o `HEAD`. Ele espera enquanto um subagente escritor roda.	não
compose: a stack sobe
`compose gate`	`Stop`	Uma stack que não sobe é pega cedo.	O fim do turno enquanto um serviço do compose está `exited` ou `dead`.	sim, um valor
context: com o que um agente começa
`context subagent`	`SubagentStart`	O agente começa com o que precisa.	nunca	não
audit: a trilha de cada run
`audit`	`UserPromptSubmitPreToolUsePostToolUseSubagentStopStopseis eventos discretos`	A trilha de cada run, a zero token.	nunca	sim, desligar

Cada modo, em detalhe

O que ele lê, o que faz quando recusa e por que existe. Cada linha vem da documentação do nerviz e do settings.json.

`guard prompt`

guard

Sabe qual skill está rodando.

Dispara em: UserPromptSubmit
O que ele bloqueia: Nunca bloqueia. Ele registra ou prepara, e o trabalho segue.

Quando um prompt é /<skill>, ele fecha a fase anterior e abre uma para a classe daquela skill. Também tira o baseline do git com que o guard sweep compara no fim do turno. Sem fase aberta não há restrição: uma pessoa editando um arquivo à mão não é uma skill passando do limite.

O projeto pode mudar?: Não. O Nerviz é dono deste modo: ele é escrito em .claude/settings.json e extensions.json, e o /arch-adopt sobrescreve os dois a cada atualização.
Fonte: 08-audit-usage.md settings.json.example

`guard call`

guard

Mantém uma run de design longe das skills de build.

Dispara em: PreToolUse
O que ele bloqueia: Uma chamada Skill a uma skill de classe build enquanto uma run de design está aberta.

Uma chamada Skill abre a fase, e uma fase nunca é trocada por uma skill da mesma classe. Com uma run de design aberta, a chamada a uma skill de classe listada em blocked_during_design sai com exit 2. Uma chamada Agent não muda nada: as escritas de um subagente são julgadas pela classe dele.

O projeto pode mudar?: Não. O Nerviz é dono deste modo: ele é escrito em .claude/settings.json e extensions.json, e o /arch-adopt sobrescreve os dois a cada atualização.
Fonte: 08-audit-usage.md settings.json.example

`guard write`

guard

A escrita fica no território da classe.

Dispara em: PreToolUse
O que ele bloqueia: Uma escrita fora do território da skill ou do agente em execução, e qualquer escrita em um caso de uso aprovado, salvo o fechamento do status e o marcar de checklist.

O território é dado, no extensions.json: skill_classes e agent_classes dão a cada classe o seu write_allow. É uma allowlist, negada por padrão, porque o arquivo que vaza nunca é o que alguém listou: uma run de design já escreveu um serviço no docker-compose.yml. Um subagente é julgado pela própria classe, com fase ou sem. Um caso de uso cujo spec está approved, implemented ou implemented-blocked fica congelado, salvo a mudança do status: do spec, o marcar de checklist e o CHANGELOG.md da pasta.

O projeto pode mudar?: Não. O Nerviz é dono deste modo: ele é escrito em .claude/settings.json e extensions.json, e o /arch-adopt sobrescreve os dois a cada atualização.
Fonte: 08-audit-usage.md settings.json.example

`guard bash`

guard

A mesma checagem, pelo shell.

Dispara em: PreToolUse
O que ele bloqueia: Uma escrita via shell em um lugar que a classe não pode escrever ou em um caso de uso congelado, e um force push em qualquer grafia.

Toda outra proteção casa por nome de ferramenta, então um heredoc, sed -i ou tee já escreveu em um caso de uso congelado sem nada objetar. Este modo lê o comando atrás dos formatos de escrita listados em guard.bash_write_shapes e aplica as mesmas duas regras a cada alvo que consegue ler literalmente. Um alvo que ele não resolve ($, crase, glob) é ignorado em silêncio, o que evita que um hook que roda em todo comando de shell bloqueie um build. Um force push, em qualquer grafia, é recusado.

O projeto pode mudar?: Não. O Nerviz é dono deste modo: ele é escrito em .claude/settings.json e extensions.json, e o /arch-adopt sobrescreve os dois a cada atualização.
Fonte: 08-audit-usage.md settings.json.example

`guard sweep`

guard

O reforço no fim do turno.

Dispara em: Stop
O que ele bloqueia: Qualquer mudança deste turno que a classe não pode escrever. Ele detecta; não previne.

Ele compara a árvore de trabalho com o baseline que o guard prompt tirou, e aplica as mesmas regras ao que mudou sem que nenhum guard em tempo de ferramenta tivesse admitido, qualquer que tenha sido a ferramenta. Ele detecta, não previne, e um caminho que o git ignora nunca é varrido.

O projeto pode mudar?: Não. O Nerviz é dono deste modo: ele é escrito em .claude/settings.json e extensions.json, e o /arch-adopt sobrescreve os dois a cada atualização.
Fonte: 08-audit-usage.md settings.json.example

`schema`

schema

Os arquivos do próprio harness continuam válidos.

Dispara em: PreToolUsePostToolUseStop
O que ele bloqueia: Um SKILL.md, agente, regra ou entrada de hook do settings.json inválido, e um segredo no .mcp.json.

Todo SKILL.md e todo agente deve estar em exatamente uma classe, ter a linha **Class:** e as seções que a classe exige, e um agente não pode definir permissionMode: bypassPermissions. Ele também confere o frontmatter das regras, os campos do .mcp.json com uma busca por segredos em headers e env, as entradas de hook do settings.json e o manifest de export contra o disco. Roda antes de uma escrita, depois dela e no fim do turno.

O projeto pode mudar?: Não. O Nerviz é dono deste modo: ele é escrito em .claude/settings.json e extensions.json, e o /arch-adopt sobrescreve os dois a cada atualização.
Fonte: 01-tipos-de-arquivo.md settings.json.example

`check`

build

A arquitetura é julgada a cada edição.

Dispara em: PostToolUse
O que ele bloqueia: Um import ou nome qualificado proibido, ou uma compilação incremental que falha no módulo tocado. O arquivo já foi escrito, então o Claude é mandado corrigir.

Depois de uma edição em um arquivo .java, ele lê os imports proibidos (.claude/forbidden-imports.txt) e compila o módulo tocado de forma incremental. Uma violação sai com exit 2, com o arquivo e a regra. No PostToolUse o exit code não desfaz a edição: o arquivo está escrito, e a mensagem chega ao Claude para ele corrigir a causa. Um filtro if: Edit(**/*.java) evita subir a JVM para qualquer outro arquivo.

O projeto pode mudar?: Não. O Nerviz é dono deste modo: ele é escrito em .claude/settings.json e extensions.json, e o /arch-adopt sobrescreve os dois a cada atualização.
Fonte: 01-tipos-de-arquivo.md settings.json.example

`format`

build

Formatar nunca custa um turno.

Dispara em: PostToolUse
O que ele bloqueia: Nunca bloqueia. Ele registra ou prepara, e o trabalho segue.

Roda spotless:apply no módulo tocado depois de toda edição Java, com o mesmo filtro if do check. Nunca bloqueia.

O projeto pode mudar?: Não. O Nerviz é dono deste modo: ele é escrito em .claude/settings.json e extensions.json, e o /arch-adopt sobrescreve os dois a cada atualização.
Fonte: 01-tipos-de-arquivo.md settings.json.example

`tests`

build

Um turno não termina com teste vermelho.

Dispara em: SubagentStartSubagentStopStop
Modos: tests agent-starttests agent-endtests
O que ele bloqueia: O fim do turno enquanto o verify falha nos módulos alterados desde o HEAD. Ele espera enquanto um subagente escritor roda.

No fim do turno roda tests.stop_maven_args (verify -DskipITs -Djacoco.skip=true) nos módulos alterados desde o HEAD. Enquanto um subagente escritor da sessão roda, ele espera, e só então: agent-start e agent-end marcam essa janela.

O projeto pode mudar?: Não. O Nerviz é dono deste modo: ele é escrito em .claude/settings.json e extensions.json, e o /arch-adopt sobrescreve os dois a cada atualização.
Fonte: 01-tipos-de-arquivo.md settings.json.example

`compose gate`

compose

Uma stack que não sobe é pega cedo.

Dispara em: Stop
O que ele bloqueia: O fim do turno enquanto um serviço do compose está exited ou dead.

É o relatório que o doctor e o compose puro usam, mudo enquanto tudo está saudável e exit 2 quando não. Ele olha serviços que não estão rodando, portas que outro contêiner publica e tags de image: que divergem das que os testes fixam. Um achado de porta é só aviso enquanto não existe nenhum contêiner deste projeto. A checagem existia e ninguém a rodava, e um broker que nenhum cliente do host alcançava foi entregue no primeiro dia: por isso ela é um portão.

O projeto pode mudar?: Sim, um valor: compose-gate, chave exited, é block (o padrão) ou warn.
Fonte: 01-tipos-de-arquivo.md 16-project-config.md settings.json.example

`context subagent`

context

O agente começa com o que precisa.

Dispara em: SubagentStart
O que ele bloqueia: Nunca bloqueia. Ele registra ou prepara, e o trabalho segue.

No SubagentStart ele entrega as seções do catálogo gof-design-patterns que o subagent_context nomeia a todo agente cuja entrada em agent_classes diz pattern_catalog: true, antes do primeiro turno, e não imprime nada para os demais. Existe porque essa skill é só manual, e uma skill só manual não pode ser pré-carregada pelo campo skills: de um agente. Não há matcher de propósito: o filtro é a flag no extensions.json.

O projeto pode mudar?: Não. O Nerviz é dono deste modo: ele é escrito em .claude/settings.json e extensions.json, e o /arch-adopt sobrescreve os dois a cada atualização.
Fonte: 01-tipos-de-arquivo.md settings.json.example

`audit`

audit

A trilha de cada run, a zero token.

Dispara em: UserPromptSubmitPreToolUsePostToolUseSubagentStopStopseis eventos discretos
Modos: audit promptaudit callaudit askaudit fileaudit answeraudit agentaudit flushaudit failaudit permaudit compactaudit stopfailaudit close
O que ele bloqueia: Nunca bloqueia. Ele registra ou prepara, e o trabalho segue.

Doze modos, em onze eventos, alimentam uma trilha: um relatório em Markdown por run de skill ou agente, com tokens por peça, a cadeia, os arquivos tocados e as perguntas feitas, mais ledgers. Prompts e respostas passam por uma lista de redação. Ela só existe enquanto .claude/audit-usage/ existe: sem a pasta, toda entrada retorna na hora, então um projeto que não a usa paga o início de um processo e mais nada.

O projeto pode mudar?: Sim. Apague .claude/audit-usage/ para desligar a trilha. O audited.json escolhe quais peças ela registra.
Fonte: 08-audit-usage.md 16-project-config.md settings.json.example

O que um projeto pode mudar

Quase tudo sob o .claude/ de um projeto gerado é do Nerviz. Três arquivos pequenos são do projeto: o export nunca os nomeia, então uma atualização nunca os toca, e enquanto um arquivo não existe o projeto recebe o que o Nerviz entrega.

Setting	O que muda	Padrão
`compose-gate`	Se um serviço do compose em `exited` ou `dead` bloqueia o fim de um turno: `block` ou `warn`.	`block`
`audited`	Quais skills e agentes a trilha de auditoria registra, um `true` ou `false` por peça.	a classe de cada peça decide
`plan-limits`	O orçamento de tokens faturáveis por trás da projeção da janela do plano nos relatórios de auditoria.	não definido: sem projeção

Mudando uma

O config é o único que escreve. Ele monta o arquivo como ficaria depois da mudança, valida com o validador que o doctor usa e, em qualquer problema, não escreve nada e sai com exit 2.
O guard recusa um Write, um Edit ou um redirect de shell direto nesses arquivos e imprime o comando config set no lugar, então um modelo não consegue deixar um deles meio válido.
O unset volta ao padrão. Um arquivo ausente significa o padrão.
No Claude Code, o /project-config faz o mesmo em conversa: mostra o que está definido, pergunta qual mudança você quer e roda o comando.

# o comando funciona com ou sem agente
java -jar .claude/hooks/ArchHook.jar config list
java -jar .claude/hooks/ArchHook.jar config set compose-gate exited warn
java -jar .claude/hooks/ArchHook.jar config set audited skills.report-issue false
java -jar .claude/hooks/ArchHook.jar config unset compose-gate exited

# no Claude Code, o mesmo em conversa
> /project-config

As settings, na documentação do nerviz →Voltar para Architecture