Qoder CN Series:Hooks

Paso 1: Cree el script

mkdir -p ~/.lingma/hooks
cat > ~/.lingma/hooks/block-rm.sh << 'EOF'
#!/bin/bash
input=$(cat)
command=$(echo "$input" | jq -r '.tool_input.command')

if echo "$command" | grep -q 'rm -rf'; then
  echo "Dangerous command blocked: $command" >&2
  exit 2
fi

exit 0
EOF
chmod +x ~/.lingma/hooks/block-rm.sh

Paso 2: Agregue la configuración

Agregue a continuación el contenido en ~/.lingma/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.lingma/hooks/block-rm.sh"
          }
        ]
      }
    ]
  }
}

Paso 3: Compruebe el resultado

Reinicie el IDE. En el panel de Qoder CN, pida al agente que ejecute un comando que contenga rm -rf. El hook bloquea la ejecución y devuelve el mensaje de error al agente.

Paso 1: Defina el requisito

Determine cuándo intervenir y qué debe coincidir:

I want to intercept/handle "what operation" "when"?
                              ↓             ↓
                           Write matcher   Choose event

Paso 2: Escriba el script del hook

Los scripts de hook siguen este protocolo:

• Entrada: recibe el contexto del evento como un objeto JSON mediante stdin.

• Salida: controla el comportamiento mediante su exit code.

exit 0   →  Allow (proceed with execution)
exit 2   →  Block (stop the operation; stderr is fed back to the Agent)
Other    →  Error (proceed with execution; stderr is displayed to the user)

Plantilla de script:

#!/bin/bash

# 1. Read JSON input from stdin.
input=$(cat)

# 2. Extract the fields you need with jq.
#    Different events have different fields; see the "Event Reference" section for details.
tool_name=$(echo "$input" | jq -r '.tool_name')
tool_input=$(echo "$input" | jq -r '.tool_input')

# 3. Write your validation logic.
if [ "$tool_name" = "Bash" ]; then
  command=$(echo "$input" | jq -r '.tool_input.command')

  # Check for dangerous operations.
  if echo "$command" | grep -qE 'rm\s+-rf|DROP\s+TABLE'; then
    # Block: exit 2 + stderr message is fed back to the Agent.
    echo "Operation denied: $command" >&2
    exit 2
  fi
fi

# 4. Allow the operation.
exit 0

También puede generar JSON con exit 0 para obtener un control más preciso:

#!/bin/bash
input=$(cat)

# Output JSON for fine-grained control (only takes effect on exit 0).
echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"This operation is not allowed"}}'
exit 0

Paso 3: Registre el script en el archivo de configuración

Registre el script bajo el evento correspondiente:

{
  "hooks": {
    "EventName": [
      {
        "matcher": "MatchCondition (optional)",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/your/script.sh"
          }
        ]
      }
    ]
  }
}

Paso 4: Pruebe y depure

Pruebe los hooks si canaliza la entrada JSON desde la terminal:

# Simulate a PreToolUse event
echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /"},"hook_event_name":"PreToolUse"}' \
  | ~/.lingma/hooks/block-rm.sh
echo "Exit code: $?"

Revise la salida de stderr (mensaje de bloqueo):

echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /"}}' \
  | ~/.lingma/hooks/block-rm.sh 2>&1

Ubicaciones de los archivos de configuración

Los hooks se combinan a partir de estos archivos, de menor a mayor prioridad:

Formato de configuración

{
  "hooks": {
    "EventName": [
      {
        "matcher": "MatchCondition",
        "hooks": [
          {
            "type": "command",
            "command": "command_to_run"
          }
        ]
      }
    ]
  }
}

Un solo evento puede tener varios grupos de matchers, cada uno con varios comandos de hook.

Reglas de coincidencia del matcher

Un matcher restringe cuándo se activa un hook. Los campos evaluados varían según el evento.

Asignación de nombres de herramientas

Qoder CN asigna dos conjuntos de nombres de herramientas en tiempo de ejecución: nativos y compatibles. Por ejemplo, matcher: "Bash" y matcher: "run_in_terminal" son equivalentes.

Entrada

Todos los eventos comparten estos campos de stdin:

Los eventos agregan campos adicionales a esta base (enumerados en la Referencia de eventos). Analícelos con jq:

#!/bin/bash
input=$(cat)
tool_name=$(echo "$input" | jq -r '.tool_name')

Salida

Un script indica su decisión mediante su exit code y los datos escritos en stdout.

El código de salida determina el comportamiento básico:

JSON de stdout (opcional; solo surte efecto cuando el código de salida es 0):

{
  "continue": true,
  "stopReason": "",
  "suppressOutput": false,
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow | deny | ask",
    "permissionDecisionReason": "Reason for the decision"
  }
}

UserPromptSubmit

• Activador: después de que el usuario envía un prompt, pero antes de que el agente lo procese.

• Bloqueable: sí (el código de salida 2 cancela la solicitud).

• Campos de entrada adicionales: prompt (el texto sin procesar que ingresó el usuario).

PreToolUse

• Activador: antes de que el agente ejecute una llamada a una herramienta.

• Bloqueable: sí (el código de salida 2 rechaza la llamada a la herramienta).

• Campo del matcher: tool_name.

• Campos de entrada adicionales: tool_name, tool_input.

PostToolUse

• Activador: después de que una llamada a una herramienta se completa correctamente.

• Bloqueable: no.

• Campo del matcher: tool_name.

• Campos de entrada adicionales: tool_name, tool_input, tool_response.

PostToolUseFailure

• Activador: después de que falla una llamada a una herramienta.

• Bloqueable: no.

• Campo del matcher: tool_name.

• Campos de entrada adicionales: tool_name, tool_input, error.

Stop

• Activador: cuando el agente termina su respuesta.

• Bloqueable: no.

• Campos de entrada adicionales: stop_hook_active, last_assistant_message.

¿Por qué los cambios de configuración no surten efecto?

No se admite la recarga en caliente. Reinicie el IDE después de modificar settings.json.

¿Qué sucede si un script de hook supera el tiempo de espera?

Un tiempo de espera agotado (valor predeterminado: 30 s) se trata como un error. La ejecución continúa y se muestra stderr al usuario.

¿Cómo se determina el orden de ejecución de varios hooks?

Los hooks del mismo evento se ejecutan en el orden declarado. Entre archivos se aplica la siguiente prioridad: usuario (la más baja) → proyecto → proyecto local (la más alta).

¿A qué variables de entorno pueden acceder los scripts de hook?

Los hooks se ejecutan en la raíz del proyecto con el usuario actual y heredan el entorno del proceso del IDE.

¿Cómo consulto los registros de ejecución de los hooks?

La salida de stderr se envía al agente o al usuario. Para consultar registros detallados, busque el prefijo [hook] en los registros de ejecución de Qoder CN.