Hooks

Step 1: Create the 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

Step 2: Add the configuration

Add the following to ~/.lingma/settings.json:

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

Step 3: Verify the result

Restart the IDE. In the Qoder CN panel, ask the Agent to run a command containing rm -rf. The hook blocks execution and feeds the error message back to the Agent.

Step 1: Define the requirement

Determine when to intervene and what to match:

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

Step 2: Write the hook script

Hook scripts follow this protocol:

• Input: Receives event context as a JSON object via stdin.

• Output: Controls behavior through its 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)

Script template:

#!/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

You can also output JSON on exit 0 for finer control:

#!/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

Step 3: Register the script in the configuration file

Register the script under the appropriate event:

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

Step 4: Test and debug

Test hooks by piping JSON input from the 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: $?"

Check the stderr output (block message):

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

Configuration file locations

Hooks merge from these files, lowest to highest priority:

Configuration format

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

A single event can have multiple matcher groups, each with multiple hook commands.

Matcher rules

A matcher narrows when a hook fires. Matched fields vary by event.

Tool name mapping

Qoder CN maps two sets of tool names — native and compatible — at runtime. For example, matcher: "Bash" and matcher: "run_in_terminal" are equivalent.

Input

All events share these stdin fields:

Events add fields beyond this base (listed in the Event reference). Parse with jq:

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

Output

A script signals its decision via its exit code and any data written to stdout.

The exit code determines the basic behavior:

stdout JSON (optional; only takes effect when exit code is 0):

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

UserPromptSubmit

• Trigger: After the user submits a prompt, but before the Agent processes it.

• Blockable: Yes (exit code 2 cancels the request).

• Additional input fields: prompt (the raw text entered by the user).

PreToolUse

• Trigger: Before the Agent executes a tool call.

• Blockable: Yes (exit code 2 rejects the tool call).

• Matcher field: tool_name.

• Additional input fields: tool_name, tool_input.

PostToolUse

• Trigger: After a tool call succeeds.

• Blockable: No.

• Matcher field: tool_name.

• Additional input fields: tool_name, tool_input, tool_response.

PostToolUseFailure

• Trigger: After a tool call fails.

• Blockable: No.

• Matcher field: tool_name.

• Additional input fields: tool_name, tool_input, error.

Stop

• Trigger: When the Agent completes its response.

• Blockable: No.

• Additional input fields: stop_hook_active, last_assistant_message.

Why don't my configuration changes take effect?

Hot reloading is not supported. Restart the IDE after modifying settings.json.

What happens if a hook script times out?

A timeout (default: 30s) is treated as an error. Execution continues and stderr is shown to the user.

How is the execution order determined for multiple hooks?

Same-event hooks run in declared order. Across files, priority applies: user (lowest) → project → project-local (highest).

What environment variables can hook scripts access?

Hooks run in the project root as the current user, inheriting the IDE process environment.

How do I view hook execution logs?

stderr output goes to the Agent or user. For detailed logs, search Qoder CN runtime logs for the [hook] prefix.