Aviso: a Cairo Labs não tem nenhuma afiliação com o PHP nem com The PHP Group. Este guia é um resumo em português das informações publicadas pelo próprio time de segurança do PHP. Em caso de dúvida, vale o aviso oficial.

1. Resumo

Em 21/10/2026, o time de segurança do PHP divulgou duas vulnerabilidades críticas de execução remota de código (RCE):

• CVE-2026-109618: "RCE via OOM corruption".

• CVE-2026-109619: "RCE via stale global state".

Ambas têm CVSS v4.0 9.2 (crítico) e não exigem autenticação. A complexidade de ataque é classificada como alta e há pré-requisitos.

Segundo o php.net, o problema atinge instalações PHP que atendem requests web (por exemplo PHP-FPM, Apache mod_php, php-cgi, FrankenPHP e LiteSpeed).

O que fazer: atualizar o PHP para uma versão corrigida (ou para o pacote da sua distribuição que já inclua a correção). As mitigações temporárias da seção 6 reduzem o risco, mas não substituem a atualização.

2. Links oficiais

• Aviso e downloads: https://www.php.net/

• GHSA da CVE-2026-109618: https://github.com/php/php-src/security/advisories/GHSA-w8hw-w9fx-j79w

• GHSA da CVE-2026-109619: https://github.com/php/php-src/security/advisories/GHSA-6wmf-4rv5-p3rp

• NVD CVE-2026-109618: https://nvd.nist.gov/vuln/detail/CVE-2026-109618

• NVD CVE-2026-109619: https://nvd.nist.gov/vuln/detail/CVE-2026-109619

• CVE.org CVE-2026-109618: https://www.cve.org/CVERecord?id=CVE-2026-109618

• CVE.org CVE-2026-109619: https://www.cve.org/CVERecord?id=CVE-2026-109619

• Anúncio na lista oss-security: https://www.openwall.com/lists/oss-security/2026/10/21/6

3. Versões afetadas e corrigidas

Nota sobre 7.4, 8.0 e 8.1: para esses ramos, o time do PHP publicou apenas backports mínimos em código-fonte, sem release oficial. Quem os usa precisa compilar com o backport ou obter a correção de um fornecedor de suporte estendido (LTS). O ideal é migrar para um ramo com release corrigida.

4. Como checar a versão

Linha de comando

php -v

Atenção: a CLI pode ser uma versão diferente da usada pelo servidor web (FPM, Apache). Confira também o binário do serviço, por exemplo php-fpm8.3 -v.

phpinfo(), com cuidado

Se precisar ver a versão que o servidor web realmente usa, crie temporariamente um arquivo que chame phpinfo(), acesse-o e apague-o logo depois. Nunca deixe uma página de phpinfo() exposta publicamente: ela revela configuração interna do servidor. Se possível, restrinja o acesso por IP enquanto ela existir.

Pacote da distribuição (Debian/Ubuntu)

dpkg -l | grep php
apt-cache policy php8.3     # troque 8.3 pelo seu ramo

Changelog do pacote: o passo mais importante em distros

As distribuições costumam aplicar a correção (backport) sem mudar o número da versão upstream. Então php -v pode mostrar uma versão "menor que a corrigida" e o pacote já estar protegido. Verifique no changelog:

apt changelog php8.3-common | grep -i -E "CVE-2026-109618|CVE-2026-109619"

Se o CVE aparece como corrigido no changelog do pacote instalado, a correção está aplicada. Se não aparece, confira o aviso de segurança da sua distribuição. Em distros, vale o aviso de segurança da distro, não só o número da versão.

5. Como atualizar

Ubuntu / Debian

sudo apt update
sudo apt upgrade

• Use os repositórios oficiais e acompanhe os avisos de segurança da sua distribuição para saber quando o pacote corrigido estiver disponível.

• PPA ondrej/php e packages.sury.org são repositórios de terceiros. Se você os usa, a atualização depende do que eles publicarem; avalie se confia neles.

• Depois de atualizar, reinicie o serviço (por exemplo php8.3-fpm ou o Apache) e confirme a versão/changelog novamente.

cPanel / EasyApache 4

• Atualize os pacotes do EasyApache 4 (ea-php*) pelo WHM ou pelo gerenciador de pacotes do servidor.

• No MultiPHP Manager, confira qual versão cada domínio usa e mova os sites para um ramo que receba a correção.

• Se o seu ramo é 7.4, 8.0 ou 8.1, veja a nota da seção 3 e consulte seu fornecedor.

Docker

• Use a imagem oficial php:8.x. As tags corrigidas (8.2.35, 8.3.36, 8.4.27, 8.5.12 e variantes) já estão no Docker Hub (conferido em 21/10/2026). Prefira fixar a tag exata, como php:8.4.27-fpm.

• Atualize e refaça a imagem sem cache:

docker pull php:8.4.27-fpm   # ajuste ao seu ramo/variante
docker build --no-cache -t minha-app:novo .

• Faça o redeploy dos contêineres com a imagem nova e confirme a versão dentro do contêiner (php -v).

• Imagens antigas já em execução não se atualizam sozinhas.

Hospedagem compartilhada

1. No painel, verifique a versão do PHP e, se houver seletor, troque para um ramo corrigido (8.2, 8.3, 8.4 ou 8.5).

2. Se o provedor ainda não oferece a versão corrigida, envie uma mensagem ao suporte. Modelo:

Olá, equipe de suporte. Foram divulgadas as vulnerabilidades CVE-2026-109618 e CVE-2026-109619 no PHP (aviso em https://www.php.net/). Gostaria de saber: (1) qual versão do PHP está ativa na minha conta/domínio; (2) se os servidores já receberam a versão corrigida (8.2.35, 8.3.36, 8.4.27 ou 8.5.12) ou o patch equivalente da distribuição; (3) previsão para a atualização, caso ainda não tenha sido feita. Obrigado.

6. Mitigações temporárias

Fonte: as mitigações abaixo são as que constam no aviso do php.net (https://www.php.net/). Elas são incompletas: somente a atualização resolve.

• memory_limit=-1 definido via php_admin_value, (no pool do FPM ou na configuração do Apache), de modo que a aplicação não possa sobrescrever. Confira se nenhum pool, diretório ou aplicação volta a definir um limite finito. Segundo o aviso, isso remove a falha controlável do limite de memória, mas uma falha de alocação subjacente ainda pode chegar ao caminho vulnerável.

• post_max_size em 8M (ou 32M, se você realmente precisa de uploads), com upload_max_filesize menor que post_max_size.

• Limites no proxy / servidor web para o tamanho da requisição decodificada, a quantidade de campos de entrada, as partes multipart, a quantidade de cabeçalhos e a profundidade de aninhamento, inclusive em requisições sem Content-Length utilizável.

• Limite de memória por cgroup/contêiner, como barreira de disponibilidade, de preferência com uma política que mate só o worker afetado. Não use RLIMIT_AS nem RLIMIT_DATA.

• session.upload_progress.enabled=0, definido em php.ini, na configuração do pool ou do servidor, e reiniciando os workers. Não funciona via ini_set nem via .user.ini.

• PHP 8.5: fatal_error_backtraces=0 e reiniciar todos os workers (bloqueia só o caminho confirmado de backtrace fatal).

• Remover configurações INI inválidas ou obsoletas aplicadas por request que emitam diagnósticos antes da inicialização. Esconder diagnósticos com error_reporting, display_errors ou @ não ajuda.

• Corrigir erros fatais e timeouts de execução que um atacante consiga provocar, inclusive em callbacks, no processamento de upload/importação e na limpeza.

• session.upload_progress.enabled=0 bloqueia os caminhos de sessão confirmados, mas não outras variantes (php.net).

Lembrete: nada disso substitui a atualização.

7. Checklist final

• [ ] Identifiquei todos os servidores, contêineres e hospedagens que rodam PHP.

• [ ] Conferi a versão do PHP usada pelo serviço web (não só a CLI).

• [ ] Para pacotes de distro, li o changelog (apt changelog php8.x-common) procurando os dois CVEs.

• [ ] Atualizei para 8.2.35, 8.3.36, 8.4.27 ou 8.5.12 (ou pacote da distro com a correção).

• [ ] Para 7.4, 8.0 ou 8.1: apliquei o backport em código-fonte, obtive correção de um fornecedor LTS ou planejei a migração.

• [ ] Reiniciei PHP-FPM / Apache / workers após a atualização.

• [ ] No Docker: docker pull, rebuild sem cache e redeploy concluídos.

• [ ] Em hospedagem compartilhada: versão trocada no painel ou chamado aberto ao suporte.

• [ ] Se a atualização não foi possível ainda: apliquei as mitigações da seção 6 e marquei uma data para atualizar.

• [ ] Removi qualquer página phpinfo() criada para o diagnóstico.

• [ ] Acompanho os avisos oficiais (php.net, GHSA e avisos da minha distribuição).

Cairo Labs · 21/10/2026 Não temos afiliação com o PHP nem com The PHP Group.

Versão original e atualizada: https://claude-md-generator.pages.dev/php-cve/?utm\_source=hashnode-ptbr&utm\_medium=artigo&utm\_campaign=desafio1k

Três recursos fazem quase todo esse trabalho:

1. .claude/rules/*.md com paths:: instruções que carregam quando o Claude mexe em arquivos que batem com o padrão.

2. Skills (SKILL.md): procedimentos e conhecimento com um frontmatter que decide quem pode invocar e quando.

3. ${VAR} no .mcp.json: config de MCP compartilhada, com os valores de cada máquina e os tokens ficando no ambiente de cada dev.

Tudo aqui foi conferido na documentação do Claude Code (code.claude.com/docs) em outubro de 2026. A saída do claude mcp list mais abaixo é saída real do CLI v2.1.300. Quando algo vem da documentação e eu não rodei, eu aviso.

Transparência: eu faço o gerador grátis e o kit pago citados no fim. Texto escrito com ajuda de IA a partir da documentação oficial; as saídas de comando mostradas aqui são de comandos que eu rodei.

1. Rules com escopo de caminho: .claude/rules/ com paths:

Qualquer .md dentro de .claude/rules/ é uma rule. A busca é recursiva, então subpastas como frontend/ e backend/ funcionam. Uma rule sem frontmatter carrega na inicialização, com a mesma prioridade do .claude/CLAUDE.md. Uma rule com o campo paths: só carrega quando o Claude trabalha com um arquivo que bate com o padrão:

---
paths:
  - "src/api/**/*.ts"
  - "tests/api/**/*.test.ts"
---
# API handlers

- Validate every request body with the shared schema helper before using it.
- Errors go through `toHttpError()`; never return raw exception messages.

Quando uma rule com escopo carrega de verdade?

Segundo a doc de memória, uma rule com paths carrega quando o Claude usa a ferramenta Read, Write ou Edit num arquivo que bate com o padrão, ou quando ele vê esse arquivo com um comando Bash que conta como leitura (tipo cat ou head num arquivo só). Ou seja, a rule aparece na primeira vez que o Claude abre src/api/users.ts, não no startup. A graça é justamente essa: suas convenções de API ficam fora do contexto enquanto o Claude está mexendo em CSS.

Quatro detalhes que pegam

1. Coloque aspas nos globs. Em YAML, um valor sem aspas que começa com * é um alias, não uma string. Olha o que um parser YAML padrão faz com isso (PyYAML 6.0.3):

paths:\n  - **/*.ts        -> ScannerError: while scanning an alias
paths:\n  - "**/*.ts"      -> {'paths': ['**/*.ts']}
paths: src/**/*.ts, lib/**/*.ts -> {'paths': 'src/**/*.ts, lib/**/*.ts'}

Por que isso importa: a doc diz que, se o frontmatter não fizer parse, o Claude Code ignora o frontmatter e carrega a rule como se ela não tivesse paths, ou seja, sempre. Um errinho transforma, sem aviso nenhum, uma rule com escopo numa rule global. Rode claude --debug para ver o erro de parse. (A forma de string separada por vírgula, da última linha, também é aceita.)

2. paths é o único campo que uma rule lê. Qualquer outra chave no frontmatter (description:, priority:…) é ignorada sem erro. Não espere que ela faça alguma coisa.

3. Brace expansion tem limite. src/**/*.{ts,tsx} vira dois padrões; {a,b}/{c,d}/*.{ts,tsx} vira oito. A lista paths inteira de uma rule divide um orçamento de 1.000 padrões expandidos e 4 MiB. Um padrão que estouraria esse limite é usado sem expandir, e chaves literais não batem com arquivo nenhum. E mais: [ abre uma bracket expression; escape (photos \[2024/**) se o nome da pasta tiver mesmo um colchete.

4. Rules em symlink apontando pra fora do repo têm restrição. Dá para fazer symlink de uma pasta de rules compartilhada para dentro de .claude/rules/, mas um alvo fora do seu diretório de trabalho é tratado como import externo: nada carrega até você aprovar imports externos no projeto, e depois disso carregam só as rules sem paths. Para rules pessoais que valem em todo lugar, use ~/.claude/rules/; as rules de usuário carregam antes das do projeto e nenhuma sobrescreve a outra, então mantenha as duas coerentes.

2. Skills: decida quem invoca o quê

Uma skill é uma pasta com um SKILL.md. Skills de projeto ficam em .claude/skills/<nome>/SKILL.md (commite), as pessoais em ~/.claude/skills/<nome>/SKILL.md. Os arquivos antigos em .claude/commands/*.md continuam funcionando e aceitam o mesmo frontmatter, menos name e paths, então coisa nova deve ir para skills.

A description é um orçamento, não um README

O Claude decide quando usar uma skill pela description (mais o when_to_use, opcional). A doc diz que o texto combinado é cortado em 1.536 caracteres na listagem de skills. Coloque o gatilho e o caso de uso principal na primeira frase.

Duas flags, direções opostas

Use disable-model-invocation: true em tudo que tem efeito colateral: /deploy, /release, postar uma mensagem. Você não quer o Claude decidindo fazer deploy porque o código "parece pronto". Use user-invocable: false para conhecimento de fundo, tipo como funciona um módulo legado, que não faz sentido como comando.

Skills também podem ter escopo de caminho

Skills aceitam o mesmo campo paths: das rules: com ele, o Claude carrega a skill automaticamente só quando está trabalhando com arquivos que batem com o padrão. Isso casa bem com skills de conhecimento:

---
name: migrations-guide
description: How we write and review database migrations. Use when creating or editing files in db/migrations.
user-invocable: false
paths:
  - "db/migrations/**"
---
- Applied migrations are immutable; add a new one.
- Every migration needs a reversible down step or a comment explaining why not.

Dados ao vivo com ! e scripts empacotados com ${CLAUDE_SKILL_DIR}

Uma linha que começa com !`comando` roda antes de a skill chegar ao Claude, e a saída substitui a linha. Para comandos de várias linhas, use um bloco cercado aberto com ```!. Dois detalhes da doc: a forma inline só é reconhecida no começo da linha ou depois de espaço (KEY=!`cmd` fica literal), e a saída é inserida uma vez só, nunca reprocessada.

${CLAUDE_SKILL_DIR} expande para a pasta da própria skill, tanto no corpo quanto nas regras Bash do allowed-tools. Usar a variável nos dois lugares deixa a skill rodar o script que vem junto com ela sem prompt de permissão:

---
name: release-notes
description: Draft release notes from merged commits since the last tag.
disable-model-invocation: true
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/commits-since-tag.sh *)
---
## Commits since the last tag
!`git describe --tags --abbrev=0`

Run `${CLAUDE_SKILL_DIR}/scripts/commits-since-tag.sh --format md` and group the
output into Features / Fixes / Internal. Don't invent entries.

Duas coisas que a galera entende errado sobre allowed-tools:

• Ele pré-aprova, não restringe. Todas as outras ferramentas continuam disponíveis sob as suas regras de permissão normais. (Para tirar ferramentas existe um campo separado, disallowed-tools.)

• A liberação dura um turno: ela some quando você manda a próxima mensagem, mesmo que o texto da skill continue no contexto.

Se você não pode liberar shell arbitrário em skills (por política da empresa, digamos), o setting disableSkillShellExecution troca todo comando ! por [shell command execution disabled by policy]. Ele é mais útil em managed settings.

3. ${VAR} no .mcp.json: compartilhe a config, não o token

Commite o .mcp.json para o time inteiro ter os mesmos servidores MCP, e deixe os valores que mudam por máquina (ou que são secretos) em variáveis de ambiente.

Sintaxe: ${VAR} e ${VAR:-default}. Onde expande: command, args, env, url e headers.

{
  "mcpServers": {
    "docs": {
      "type": "http",
      "url": "${DOCS_MCP_URL:-https://example.invalid}/mcp",
      "headers": { "Authorization": "Bearer ${DOCS_MCP_TOKEN}" }
    }
  }
}

Variável sem valor não quebra com barulho

Se uma variável não tem valor nem default, a config carrega mesmo assim, e o texto ${VAR} é usado do jeito que está. O Claude Code avisa. Aqui está o claude mcp list (CLI 2.1.300) num repo novo com esse arquivo e DOCS_MCP_TOKEN sem valor:

docs: ${DOCS_MCP_URL}/mcp (HTTP) - ⏸ Pending approval (run `claude` to approve)

MCP config diagnostics ⚠
[Contains warnings] Project config (shared via .mcp.json)
 └ [Warning] [docs] mcpServers.docs: Missing environment variables: DOCS_MCP_TOKEN

Três coisas para reparar:

• Só o DOCS_MCP_TOKEN aparece no aviso; o DOCS_MCP_URL tem default. Com DOCS_MCP_TOKEN=abc definido, o aviso sumiu.

• A URL aparece por referência (${DOCS_MCP_URL}), não resolvida. A doc diz que claude mcp list, claude mcp get e /mcp mostram as referências ${VAR} pelo nome, então colar essa saída numa issue não vaza valor nenhum.

• O servidor está pendente de aprovação, que é o próximo ponto.

Servidor de projeto precisa de aprovação, e o repo não se aprova sozinho

O Claude Code pergunta antes de usar servidores do .mcp.json de um projeto. Dá para achar que commitar "enableAllProjectMcpServers": true no .claude/settings.json pula essa etapa. Numa pasta não confiável, não pula: eu commitei exatamente esse arquivo no repo de teste e o claude mcp list continuou mostrando ⏸ Pending approval. Isso bate com a doc: o setting é ignorado até você aceitar o diálogo de confiança do workspace rodando claude na pasta. (Para zerar suas escolhas depois: claude mcp reset-project-choices.)

Mais duas pegadinhas de variável

• CLAUDE_PROJECT_DIR em command/args precisa de default. O Claude Code define essa variável no ambiente do servidor, não no dele próprio, então num .mcp.json de projeto escreva ${CLAUDE_PROJECT_DIR:-.}. Configs de plugin substituem direto.

• Nomes de credencial são lidos como vazios. Na url e nos headers de um servidor remoto, nomes como ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN e NPM_TOKEN são lidos como vazios de propósito (um :-default também é ignorado), o que normalmente acaba num 401. Use um nome de variável seu. Falei disso no post anterior (em inglês).

4. Checagem de 5 minutos no seu repo

1. grep -rn "^ - \*" .claude/rules .claude/skills acha globs sem aspas que começam com *. Coloque aspas.

2. claude --debug e procure erros de parse de frontmatter em rules e skills.

3. Toda skill com efeito colateral deveria ter disable-model-invocation: true.

4. Leia a description de cada skill: o gatilho está na primeira frase?

5. claude mcp list num clone novo: cada linha Missing environment variables é o bug do primeiro dia de alguém do time. Adicione um :-default ou documente a variável no README.

Fechando

O CLAUDE.md deve guardar o que vale no repo inteiro. O resto pode esperar a hora em que importa: rules com paths: para convenções de arquivos específicos, skills para procedimentos (com a flag de invocação certa) e ${VAR} para a config de MCP compartilhada nunca carregar um token.

Se você quer um CLAUDE.md curto e um bloco de permissões para começar e pendurar essas coisas, eu fiz um Gerador de CLAUDE.md grátis. Ele roda no seu navegador e o que você digita não sai dele (a única requisição de rede é um contador de visitas anônimo).

Transparência: eu sou o criador e vendedor do Claude Code Power Kit (R$149 pela Kiwify, com Pix, garantia de 7 dias), então eu ganho com cada venda. Ele traz 6 rules com escopo de caminho, 14 skills e 9 configs de MCP que usam variáveis ${CCPK_*}, na linha deste post. O kit é em inglês (templates, subagents, skills, hooks e guias), com um guia curto em pt-BR. Texto escrito com ajuda de IA a partir da documentação oficial. Não afiliado à Anthropic; Claude e Claude Code são marcas da Anthropic.

That "most" is the whole problem. The official memory docs are explicit that Claude treats CLAUDE.md as context, not enforced configuration, and they point you to a PreToolUse hook if you need to block an action regardless of what Claude decides.

So here is the split I now use:

• CLAUDE.md is advice. Short, specific, about how the project works.

• Permissions and hooks are enforcement. Anything that must hold every time goes there.

This post walks through both halves with small, working examples. Everything was checked against the Claude Code docs (code.claude.com/docs) in October 2026, CLI v2.1.300, and the shell snippets were run with bash + jq.

Disclosure: I'm the maker of the free generator and the paid kit mentioned at the end. This post was written with AI assistance against the official docs, and I tested the snippets myself.

1. What CLAUDE.md is actually good for

The docs suggest keeping each CLAUDE.md under 200 lines, because longer files cost context and reduce adherence. In practice, mine hold three things:

• Commands: how to install, test a single file, lint, typecheck, build.

• Conventions: the things a new teammate would get wrong on day one.

• Gotchas: domain rules Claude can't infer from the code.

Two features keep it short.

Imports. @path/to/file pulls another file into context, so @AGENTS.md or @docs/architecture.md doesn't have to be pasted in. Import parsing skips code spans and fenced code blocks, so if you want to mention a path without importing it, wrap it in backticks: `@README` stays literal, while a bare @README is imported.

Path-scoped rules. Put instructions that only matter for part of the repo in .claude/rules/*.md with a paths: frontmatter. They load only when Claude works with matching files:

---
paths:
  - "db/migrations/**"
  - "**/*.sql"
---
# Migrations

- A migration that has been applied anywhere is immutable. Add a new one.
- Read the generated SQL before accepting it.

That keeps your migration rules out of context while Claude is editing CSS.

Notice what's not in that list: "never", "always", "under no circumstances". If you catch yourself typing those in CLAUDE.md, that rule probably belongs in one of the next two sections.

2. Permissions: deny > ask > allow

Permission rules live in .claude/settings.json (project) or your user settings. The precedence is the first thing to internalize: rules are evaluated deny, then ask, then allow, and the first match in that order wins. Specificity doesn't matter, so an allow rule can't carve an exception out of a deny rule.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": ["Bash(git diff *)", "Bash(git status *)", "Bash(npm test *)"],
    "ask":   ["Bash(git push *)"],
    "deny":  ["Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)"]
  }
}

Two gotchas that cost me time:

The space before * is part of the rule. Bash(ls *) matches ls and ls -la but not lsof. Bash(ls*) matches lsof too. So write Bash(git diff *), with the space.

Project allow rules wait for workspace trust. permissions.allow entries in a project's .claude/settings.json grant capability, so Claude Code only applies them after you accept the workspace trust dialog for that folder. If your allow list "doesn't work" in a freshly cloned repo, that's the first thing to check. Deny and ask rules are restrictions, so they don't depend on that step.

Add the $schema line: the settings schema at json.schemastore.org gives you editor autocomplete and catches typos. The file above validates against it.

3. Hooks: exit 2 means "no"

Permission rules match patterns. Hooks run your code, so they can make decisions a glob can't. A hook is a command that gets the event as JSON on stdin. For PreToolUse, that includes tool_name and tool_input (for Bash, tool_input.command).

The contract you need to remember:

• Exit 0: carry on.

• Exit 2: block. On a PreToolUse hook that blocks the tool call, and stderr is sent back to Claude as the reason, so write a message that tells it what to do instead.

• Stderr from a hook that exits 0 is never shown to Claude.

Here's a hook that blocks force-pushes to main/master:

#!/usr/bin/env bash
# .claude/hooks/guard-push.sh — PreToolUse (matcher: Bash)
set -uo pipefail
command -v jq >/dev/null || { echo "guard-push: jq is required; blocking to be safe." >&2; exit 2; }

cmd=$(jq -r '.tool_input.command // empty')
[ -z "$cmd" ] && exit 0

if grep -Eq 'git +push\b.*(--force|-f\b|\+[^ ]*:)' <<<"$cmd" &&
   grep -Eq 'git +push\b.*[ :+](main|master)( |$)' <<<"$cmd"; then
  echo "Blocked: force-push to main/master. Push a branch and open a PR instead." >&2
  exit 2
fi
exit 0

Two details matter more than the regex:

1. Fail closed. If jq is missing, a naive hook reads an empty command and happily exits 0, which means "allowed". For a security hook, a missing dependency should block, not wave everything through.

2. Match the branch, not a substring. An early version of mine matched \bmain\b, which also blocked git push --force origin feature/main-menu (the - is a word boundary). Anchoring on a space, : or + before the branch name fixed it.

"Ask" instead of "block"

Exit 2 is binary. When you want a human in the loop instead, PreToolUse can print JSON with a permissionDecision of deny, ask or allow:

#!/usr/bin/env bash
# .claude/hooks/ask-reset.sh — PreToolUse (matcher: Bash)
set -uo pipefail
cmd=$(jq -r '.tool_input.command // empty')
if grep -Eq 'git +reset +.*--hard' <<<"$cmd"; then
  jq -n '{hookSpecificOutput: {
            hookEventName: "PreToolUse",
            permissionDecision: "ask",
            permissionDecisionReason: "git reset --hard discards uncommitted work."}}'
fi
exit 0

Note the exit 0: the decision travels in the JSON, not the exit code.

Wiring them up

Hooks are registered in the same settings file. $CLAUDE_PROJECT_DIR keeps the paths working from any subdirectory:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/guard-push.sh" },
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/ask-reset.sh" }
        ]
      }
    ]
  }
}

Remember to chmod +x the scripts.

4. Stop hooks and the infinite loop

A Stop hook runs when Claude is about to finish its turn. Exit 2 there prevents stopping: Claude gets your stderr and keeps working. That's exactly what you want for "don't finish while the tests are red", and it's also an easy way to build a loop: the tests still fail, Claude stops again, your hook blocks again…

The docs give you the escape hatch: Stop hooks receive stop_hook_active, which is true when Claude is already continuing because of a stop hook. Check it first. (Claude Code also caps this at eight consecutive continuations, but don't design around the cap.)

#!/usr/bin/env bash
# .claude/hooks/stop-test-gate.sh — Stop. Opt-in via TEST_GATE_CMD.
set -uo pipefail
input=$(cat)
# Already continuing because of a Stop hook? Let it stop, or we loop.
[ "$(jq -r '.stop_hook_active // false' <<<"$input")" = "true" ] && exit 0
[ -z "${TEST_GATE_CMD:-}" ] && exit 0

cd "${CLAUDE_PROJECT_DIR:-.}" || exit 0
if ! out=$(bash -c "$TEST_GATE_CMD" 2>&1); then
  echo "Tests are failing (\`$TEST_GATE_CMD\`). Fix them before finishing. Last lines:" >&2
  tail -n 20 <<<"$out" >&2
  exit 2
fi
exit 0

Register it under "Stop" (no matcher) and enable it per project with something like TEST_GATE_CMD="npm test". I make test gates opt-in on purpose: a slow suite on every single stop gets old fast, and a gate you resent is a gate you delete.

If you only want to remind yourself (say, about uncommitted changes) without forcing Claude to keep going, print {"systemMessage": "..."} and exit 0 instead.

5. The .mcp.json env-var gotcha

This one produces a confusing 401 with no warning. In a remote MCP server's url and headers, Claude Code reads a set of well-known credential variables as empty, on purpose, so a repo's .mcp.json can't ship your credentials to a server it names. Covered names include ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, cloud provider tokens, HTTPS_PROXY and NPM_TOKEN, and a :-default fallback on them is ignored.

The fix is to use a variable name of your own:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "Bearer ${MYAPP_GITHUB_PAT}" }
    }
  }
}

Separately, an unset variable that isn't on that list is left as the literal ${VAR} text, and Claude Code warns about it in claude mcp list and /mcp. So if a server fails to connect, check there first.

6. Hooks are code, so test them

You don't need a Claude Code session to test a hook. Feed it the JSON it would receive and assert on the exit code or the decision:

#!/usr/bin/env bash
set -uo pipefail
H=.claude/hooks; pass=0; fail=0
bash_in() { jq -nc --arg c "$1" '{hook_event_name:"PreToolUse",tool_name:"Bash",tool_input:{command:$c}}'; }

expect_exit() { # expect_exit <code> <hook> <command>
  bash_in "$3" | "$H/$2" >/dev/null 2>&1; local rc=$?
  if [ "$rc" -eq "$1" ]; then pass=$((pass+1)); else fail=$((fail+1)); echo "FAIL $2: '$3' exited $rc, want $1"; fi
}

expect_exit 2 guard-push.sh 'git push --force origin main'
expect_exit 2 guard-push.sh 'git push -f origin master'
expect_exit 2 guard-push.sh 'git push origin +HEAD:main'
expect_exit 0 guard-push.sh 'git push origin main'
expect_exit 0 guard-push.sh 'git push --force origin feature/main-menu'

d=$(bash_in 'git reset --hard HEAD~1' | "$H/ask-reset.sh" | jq -r '.hookSpecificOutput.permissionDecision')
[ "$d" = ask ] && pass=$((pass+1)) || { fail=$((fail+1)); echo "FAIL ask-reset: got '$d'"; }

echo '{"stop_hook_active":false}' | TEST_GATE_CMD=false "$H/stop-test-gate.sh" 2>/dev/null
[ $? -eq 2 ] && pass=$((pass+1)) || { fail=$((fail+1)); echo "FAIL: stop gate should block"; }
echo '{"stop_hook_active":true}' | TEST_GATE_CMD=false "$H/stop-test-gate.sh" 2>/dev/null
[ $? -eq 0 ] && pass=$((pass+1)) || { fail=$((fail+1)); echo "FAIL: stop gate should let go"; }

echo "$pass passed, $fail failed"; [ "$fail" -eq 0 ]

The feature/main-menu case exists because that false positive actually happened. Every time a hook surprises you, add the input as a test case. Run the harness in CI next to the schema check for settings.json.

An honest caveat: I've run these on Linux with bash + jq. Hooks are shell scripts, so grep -E and sed differences between GNU and BSD (macOS) can bite. Test on the platforms your team actually uses.

7. Smaller things worth knowing

• Custom commands were merged into skills. .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both give you /deploy; existing command files keep working.

• Hooks need a POSIX shell. On Windows, run them through WSL or Git Bash; native PowerShell won't run these scripts.

• PostToolUse can't undo anything. The tool already ran; exit 2 there only shows stderr to Claude. Put prevention in PreToolUse.

• Keep the hook messages actionable. "Blocked" teaches nothing. "Blocked: force-push to main. Push a branch and open a PR instead" gives Claude a next step.

Wrap-up

The pattern fits on one line: if breaking a rule would hurt, it doesn't belong in CLAUDE.md. Put it in a deny rule if a pattern can express it, in a hook if it needs logic, and test the hook like any other code. That leaves CLAUDE.md short and focused on what it's good at, which is telling Claude how your project works.

If you want a starting point for the short CLAUDE.md plus a matching permissions block, I built a free CLAUDE.md Generator. It runs in your browser and your inputs never leave it (the only network request is an anonymous visit counter).

I'm the maker: if you'd rather not write all of this yourself, the Claude Code Power Kit (US$29) bundles 14 stack templates, path-scoped rules, permission presets and 11 hook scripts built on the same ideas (including a force-push guard and an opt-in test gate), with a bash + jq test harness. Written with AI assistance against the official docs. Not affiliated with Anthropic; Claude and Claude Code are trademarks of Anthropic.