Hooks de Terceiros

O Cherri Code oferece suporte ao carregamento de hooks de ferramentas de terceiros, garantindo compatibilidade com configurações de hooks existentes de outros assistentes de programação com IA.

Hooks do Claude Code

O Cherri Code pode carregar e executar hooks configurados para o Claude Code, permitindo usar os mesmos scripts de hook nas duas ferramentas.

Requisitos

Os hooks do Claude Code são carregados quando Include Third-Party Plugins, Skills, and Other Configs está habilitado em Configurações do Cherri Code → Agents → Third-Party Imports. A configuração vem ativada por padrão.

Locais de configuração

Os hooks do Claude Code são carregados destes locais (em ordem de prioridade):

Ordem de prioridade

Quando hooks são configurados em vários locais, eles são mesclados nesta ordem de prioridade (da mais alta para a mais baixa):

1. Hooks corporativos (implantação gerenciada)
2. Hooks de equipe (configurados no dashboard)
3. Hooks de projeto (.cursor/hooks.json)
4. Hooks de usuário (~/.cursor/hooks.json)
5. Projeto local do Claude (.claude/settings.local.json)
6. Projeto do Claude (.claude/settings.json)
7. Usuário do Claude (~/.claude/settings.json)

Todos os hooks correspondentes de todas as fontes são executados. Quando as respostas entram em conflito, as fontes de maior prioridade prevalecem durante o merge.

Hooks gerenciados pelo plano corporativo e a distribuição pelo dashboard exigem um plano Enterprise. Entre em contato com vendas para saber mais.

Formato de Hooks do Claude Code

Os hooks do Claude Code usam um formato semelhante, mas com algumas diferenças. O Cherri Code mapeia automaticamente os nomes dos hooks do Claude para os equivalentes no Cherri Code.

Exemplo de settings.json do Claude Code:

{  "hooks": {    "PreToolUse": [      {        "matcher": "Shell",        "hooks": [          {            "type": "command",            "command": "./hooks/validate-shell.sh"          }        ]      }    ],    "PostToolUse": [      {        "matcher": ".*",        "hooks": [          {            "type": "command",            "command": "./hooks/audit.sh"          }        ]      }    ]  }}

Compatibilidade de formatos de resposta

O Cherri Code oferece suporte tanto ao formato de resposta aninhado hookSpecificOutput do Claude Code quanto ao antigo formato de resposta plano. Os scripts de hook escritos para o Claude Code funcionarão no Cherri Code independentemente do formato usado.

Formatos de resposta de PreToolUse

Formato aninhado (estilo do Claude Code):

{  "hookSpecificOutput": {    "hookEventName": "PreToolUse",    "permissionDecision": "deny",    "permissionDecisionReason": "Blocked by policy",    "updatedInput": { "command": "npm ci" }  }}

Formato plano (estilo nativo do Cherri Code):

{  "permission": "deny",  "user_message": "Blocked by policy",  "updated_input": { "command": "npm ci" }}

Ambos os formatos são equivalentes. O permissionDecision aninhado corresponde a permission, permissionDecisionReason corresponde a user_message e updatedInput corresponde a updated_input.

Formatos de resposta de Stop / SubagentStop

Formato aninhado (no estilo do Claude Code):

{  "hookSpecificOutput": {    "decision": "block",    "reason": "Tasks incomplete, continue working"  }}

Formato plano (estilo legado do Claude Code):

{  "decision": "block",  "reason": "Tasks incomplete, continue working"}

Formato nativo do Cherri Code:

{  "followup_message": "Tasks incomplete, continue working"}

Para os hooks Stop e SubagentStop, uma decision de "block" com uma reason é tratada como uma mensagem de acompanhamento automática, equivalente a fornecer followup_message no formato nativo do Cherri Code.

Mapeamento de etapas de hooks

Os nomes de hooks do Claude Code são automaticamente mapeados para os nomes de hooks do Cherri Code:

Comportamento do código de saída

Os hooks do Cherri Code e do Claude Code oferecem suporte ao código de saída 2 para bloquear uma ação. Isso garante um comportamento consistente ao compartilhar hooks entre ferramentas:

#!/bin/bash# Bloqueia comandos perigososif [[ "$COMMAND" == *"rm -rf"* ]]; then  echo '{"permission": "deny", "user_message": "Destructive command blocked"}'  exit 2fiecho '{"permission": "allow"}'exit 0

• Código de saída 0: Hook executado com sucesso; use a saída JSON
• Código de saída 2: Bloqueia a ação (equivalente a permission: "deny")
• Outros códigos de saída: Falha no hook; a ação prossegue (falha aberta)

Migração do Claude Code

Se você já usa hooks do Claude Code, pode:

1. Continuar usando arquivos de configuração do Claude Code: Deixe Include Third-Party Plugins, Skills, and Other Configs habilitado, e os hooks existentes em .claude/settings.json funcionarão automaticamente.
2. Migrar para o formato do Cherri Code: Copie seus hooks para .cursor/hooks.json usando o formato do Cherri Code para ter suporte completo às funcionalidades.

Equivalente no formato do Cherri Code:

{  "version": 1,  "hooks": {    "preToolUse": [      {        "command": "./hooks/validate-shell.sh",        "matcher": "Shell"      }    ],    "postToolUse": [      {        "command": "./hooks/audit.sh"      }    ]  }}

Funcionalidades compatíveis

Ao usar hooks do Claude Code no Cherri Code, há suporte às seguintes funcionalidades:

Funcionalidades adicionais compatíveis:

Mapeamento de nomes de ferramentas

Os nomes das ferramentas do Claude Code correspondem aos seguintes nomes de ferramentas no Cherri Code:

Limitações

Algumas funcionalidades estão disponíveis apenas ao usar o formato nativo do Cherri Code:

• Hook subagentStart (o Claude Code tem apenas SubagentStop)
• Configuração do limite de loops (loop_limit)
• Distribuição de hooks para equipes/corporativo pelo dashboard

Solução de problemas

Hooks do Claude Code não carregam

1. Verifique se "Include Third-Party Plugins, Skills, and Other Configs" está habilitado nas Configurações do Cherri Code → Agents → Third-Party Imports
2. Verifique se o arquivo .claude/settings.json contém JSON válido
3. O Cherri Code monitora arquivos de configuração e os recarrega automaticamente. Se os hooks ainda não carregarem, reinicie o Cherri Code.

Hooks são executados, mas não bloqueiam

1. Certifique-se de que o script do hook seja encerrado com o código 2 para bloquear ações
2. Verifique se o formato da saída JSON corresponde ao schema esperado
3. Consulte o canal de saída Hooks no Cherri Code para ver os detalhes do erro

Comportamento diferente entre o Cherri Code e o Claude Code

Podem haver diferenças de comportamento devido aos diferentes ambientes de execução. Teste seus hooks nas duas ferramentas para garantir a compatibilidade.