Skip to main content

Using Hooks

Hooks are Copilot Shell's interception mechanism. They execute custom scripts before and after tool calls and agent processing, enabling security enforcement, automated approval, context injection, and more.

Quick Start​

List all registered hooks:

/hooks list

Hook Events​

Copilot Shell supports the following hook events:

EventTriggerTypical Use
SessionStartSession begins (start/resume/clear)Initialize environment, load context
SessionEndSession ends (exit/clear)Clean up resources, save state
UserPromptSubmitAfter user submits prompt, before planningInject context, validate input, block turn
StopWhen agent is about to stopReview output, force retry
BeforeModelBefore sending LLM requestSwitch model, modify parameters, mock response
AfterModelAfter receiving LLM responseFilter response, log
BeforeToolSelectionBefore LLM selects toolsFilter available tool set
PreToolUseBefore tool executionIntercept dangerous commands, modify parameters, security audit
PostToolUseAfter tool executionProcess results, log, hide sensitive output
PostToolUseFailureAfter tool execution failureError recovery, sandbox bypass
PreCompactBefore context compressionSave state, notify user
NotificationWhen system notification occursForward desktop alerts
PermissionRequestWhen permission dialog showsAuto-approve or deny permissions

Managing Hooks​

View Registered Hooks​

/hooks list

Displays all hooks with their name, source, and status (enabled/disabled).

Enable or Disable Specific Hooks​

Disable via configuration file:

{
  "hooksConfig": {
    "disabled": ["sandbox-guard"]
  }
}

Disable Hooks System Globally​

{
  "hooksConfig": {
    "enabled": false
  }
}

Hook Configuration Format​

Configure custom hooks in settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "run_shell_command",
        "sequential": true,
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/my-hook.sh",
            "name": "my-hook",
            "timeout": 10000
          }
        ]
      }
    ]
  }
}

Configuration Fields​

Each event contains an array of matcher groups. Each matcher group has:

FieldTypeDescription
matcherstringTool name regex to match; empty or "*" matches all
sequentialbooleanExecute sequentially (default: parallel)
hooksarrayHook list for this matcher group

Each hook object:

FieldTypeDescription
typestringExecution engine; currently only "command"
commandstringHook script path or command
namestringHook name (used in logs and management commands)
timeoutnumberTimeout in milliseconds (default: 60000)

Hook Source Priority​

When multiple sources define hooks for the same event, execution priority is:

  1. User — Hooks defined in user settings
  2. Extension — Hooks injected by extensions
  3. Remote — Remotely loaded hooks

Hook Input/Output​

Hook scripts receive JSON input via stdin and return JSON output via stdout.

PreToolUse Input Example​

{
  "hook_event_name": "PreToolUse",
  "tool_name": "run_shell_command",
  "tool_input": {
    "command": "rm -rf /tmp/test"
  },
  "session_id": "abc123",
  "cwd": "/home/user/project",
  "timestamp": "2025-01-01T00:00:00Z"
}

PreToolUse Output Examples​

Deny execution:

{
  "decision": "deny",
  "reason": "Dangerous command intercepted"
}

Allow execution with modified parameters:

{
  "hookSpecificOutput": {
    "tool_input": {
      "command": "linux-sandbox -- rm -rf /tmp/test"
    }
  }
}