@interven/copilot-hook

GitHub Copilot Coding Agent preToolUse hook for Interven.

Every tool call (bash, edit, create, view, grep, glob, ...) gets scanned through Interven's policy + risk pipeline before execution. Block dangerous actions, approve high-risk ones, log everything for audit.

Quick start

1. Get an API key at app.intervensecurity.com/api-keys

2. In your repository, create .github/hooks/preToolUse.json:

   {
     "command": "npx",
     "args": ["-y", "@interven/copilot-hook"],
     "env": {
       "INTERVEN_API_KEY": "iv_live_your_key_here"
     }
   }

3. Commit and push. The hook runs on every Copilot Coding Agent tool call.

How it works

Copilot wants to run a tool (e.g. `bash rm -rf /`)
    ↓ Coding Agent invokes preToolUse hook
@interven/copilot-hook reads tool name + args from stdin
    ↓ POSTs to /v1/scan with method, url, body
Interven runs full policy + risk pipeline
    ↓ returns decision
Hook writes JSON to stdout: { permissionDecision: "allow"|"deny" }
    ↓
Coding Agent honors the decision

Decisions

| Interven decision | Hook returns | Effect | |------|-------|------| | ALLOW | permissionDecision: "allow" | Tool executes | | DENY | permissionDecision: "deny" with reason codes | Tool blocked | | SANITIZE | permissionDecision: "allow" (logged for audit) | Tool executes; can't rewrite args via this hook | | REQUIRE_APPROVAL | permissionDecision: "deny" with approval URL | Block, retry after analyst approves (10-min grant window) |

Environment variables

| Variable | Default | Notes | |----------|---------|-------| | INTERVEN_API_KEY | required | iv_live_... token | | INTERVEN_GATEWAY | https://api.intervensecurity.com | Override for self-hosted | | INTERVEN_TIMEOUT_MS | 5000 | Hard timeout per scan | | INTERVEN_FAIL_CLOSED | 0 | Set to 1 to deny on hook failures (default fails open to avoid breaking the dev loop) |

Limitations

• The hook can allow or deny. It cannot rewrite tool arguments. For SANITIZE, the scan is recorded but the original args run through.
• preToolUse hooks are not enforced in subagents (GitHub issue #2392).

License

MIT