Copilot CLI
Make GitHub Copilot CLI wait for a person's yes before every shell command, file change and MCP tool call: a preToolUse hook set up in one command, verified in Copilot CLI 1.0.114.
GitHub Copilot CLI asks before it runs a command or changes a file, unless you told it not to: --allow-all-tools, --yolo, an allow rule, or a -p run in a script. Its preToolUse hook lets a program answer instead. With the VariantGate hook, every shell command, file change, web fetch and MCP tool call waits for a person, who answers from the inbox, a phone notification, Slack or email. Rules answer the routine ones, and every answer lands on the same record as your other agents.
The quick way: one command
With Node.js on the computer it runs on, this does both steps for you. It opens the browser to sign in (or to make your free account), saves an agent key on this computer, and adds the approval hook to ~/.copilot/hooks/variantgate.json, keeping the old file beside it:
npx -y https://variantgate.com/sdk/variantgate-agent-0.4.0.tgz setup copilotStart a new Copilot CLI session and ask it to run echo hello: the command waits until you approve it in the inbox, and so does every file change and MCP tool call. A file it cannot change safely, such as one with comments or one that links elsewhere, is left alone, and the command prints the entry to add yourself. The steps below do the same by hand.
1. Create a key
Sign in, open Agents and create a key for Copilot CLI. Copy it: it is shown once. Put it in your shell profile, such as ~/.zshrc, as export VARIANTGATE_KEY=….
2. Put tool calls through approval
Install the variantgate command (more on the SDK page):
npm install -g https://variantgate.com/sdk/variantgate-agent-latest.tgzThe hook reads VARIANTGATE_KEY from the environment Copilot starts in, or a key saved on this computer:
Or run variantgate login once on this computer instead. It opens the browser, you check a code and press Connect, and it saves a new agent key in ~/.config/variantgate/credentials.json, readable only by you. The hook uses that key, with the API address it was made for, whenever VARIANTGATE_KEY is not set. The MCP server still needs the key from step 1.
Then add the hook in its own file, ~/.copilot/hooks/variantgate.json (under $COPILOT_HOME when that is set). Copilot reads every file in that folder when a session starts, for every folder you work in:
{
"version": 1,
"hooks": {
"preToolUse": [
{
"type": "command",
"command": "variantgate hook copilot",
"env": { "VARIANTGATE_COPILOT_HOOK_WAIT": "120" },
"timeoutSec": 150,
"matcher": "(?!(?:view|grep|glob|rg|read_bash|list_bash|stop_bash|ask_user|report_intent|fetch_copilot_cli_documentation|skill|sql|session_store_sql|read_agent|list_agents|update_todo|think)$).*"
}
]
}
}Copilot matches the matcher against the whole tool name. This one leaves out only the tools that look, such as view, grep and glob, and the ones that keep Copilot’s own session notes, so a tool a later version adds waits for a yes until you say otherwise. Before each call, Copilot runs the hook, which opens a request and waits. A denial blocks the call, and the reason goes to the agent; an approval hands it back to Copilot’s own permissions, as below. Each call becomes a request with an action name that rules can match:
- shell.run
- A bash or PowerShell command, with the command, Copilot's description of it and the folder. The same name the Claude Code, Codex, Gemini CLI and Cursor hooks use, so one rule covers them all.
- file.write
- A new file (create), with its path and text.
- file.edit
- A change to a file (edit), with the text replaced.
- web.fetch
- A page Copilot wants to fetch, with its address.
- mcp.<copilot name>
- A call to an MCP tool, under the one name Copilot gives it: the server and the tool joined by a dash, such as mcp.shop-refund_order.
- tool.<name>
- Any other tool, such as tool.task for a subagent, or one a later Copilot version adds.
MCP tool names
Copilot hands the hook an MCP tool under a single name: the server and the tool joined by a dash, with dots and other marks made dashes too. A server called my-shop.eu with a tool refund_order arrives as my-shop-eu-refund_order, so the server cannot be told apart from the tool. The request’s action is that whole name, mcp.my-shop-eu-refund_order, which is not the mcp.<server>.<tool> shape the Claude Code and Cursor hooks send. Write rules for Copilot by its names. A rule on mcp.shop-* covers every tool of a server called shop, and also those of one called shop-admin, so name the tool in an allow rule.
Instead of the hook: the MCP server
The hook puts every call in front of a person. If you would rather the model decide what to ask about, add the approvals server to ~/.copilot/mcp-config.json instead. Copilot fills in the key from the environment it starts in, so the key stays out of the file:
{
"mcpServers": {
"variantgate": {
"type": "http",
"url": "https://api.variantgate.com/mcp",
"headers": { "Authorization": "Bearer ${VARIANTGATE_KEY}" },
"tools": ["*"]
}
}
}The server gives the agent a request_approval tool to call before an action you want signed off. Tell it when, in .github/copilot-instructions.md or your own ~/.copilot/copilot-instructions.md:
Before you send, pay, publish, deploy or delete anything, call
request_approval with one sentence saying exactly what will happen.
Then call check_approval until it is no longer pending.
Act only if "allowed" is true. Otherwise stop and say why.That relies on the model choosing to ask. Use one or the other, not both: with the hook in place, the server’s own tools are asked about like any other call, because the hook sees only a name, which any server could borrow, so each question would reach you twice.
What Copilot does when a hook fails
We ran the hook in Copilot CLI 1.0.114, against a scripted model and a local copy of the service. A hook that exits with any code but 0 blocks the call. But a hook that runs past its timeoutSec (30 seconds if you leave it out), or prints something that is not JSON, lets the call run as if there were no hook, with --allow-all-tools too. That is the wrong default for an approval, so the hook always prints its deny in time:
- It waits
VARIANTGATE_COPILOT_HOOK_WAITseconds for a person (10 if you leave it out, inside the 30-second default), then withdraws the request and denies the call. KeeptimeoutSecat least 20 longer than the wait. - If the service cannot be reached, or stops answering, the call is denied a few seconds after the wait, and a request it already opened is taken back.
- It never answers “ask”, which Copilot turns into a no in
-pruns and autopilot anyway. - With no key set or saved, the hook exits with code 2, which Copilot reads as a deny.
- Copilot’s
preMcpToolCallevent cannot stop a call: in our runs a deny, an exit code of 2 and a timeout there all let the MCP tool run. UsepreToolUse, as above.
Approvals and Copilot’s own permissions
The hook only ever adds a person’s no. A denial wins over --allow-all-tools and --yolo. An approval sends Copilot no answer at all, so the call then goes through Copilot’s own permissions as it would without the hook: with --allow-all-tools or an allow rule it runs, a --deny-tool rule still refuses it, and in a session without either, Copilot asks at the terminal as well.
Why not answer “allow”? In our runs, a hook’s allow let a command through that --deny-tool refused, and let an unattended -p run do what it would otherwise turn down. An approval in the inbox should not quietly widen what you configured Copilot to do.
In scripts and CI
A -p run has nobody at the terminal, so it is where the hook matters most. Give the run a key and let it allow the tools it needs, here all of them: the hook still puts each command and change in front of a person first, and a denial stops it.
export VARIANTGATE_KEY=... # a key for this pipeline
copilot -p "Fix the failing test and push a branch" --allow-all-toolsA -p run in a folder Copilot does not trust skips that folder’s own hooks, but not the ones in your home folder.
Only some tools
To send only some tools to the inbox, list them in the matcher:
"preToolUse": [
{
"type": "command",
"command": "variantgate hook copilot",
"env": { "VARIANTGATE_COPILOT_HOOK_WAIT": "120" },
"timeoutSec": 150,
"matcher": "bash|powershell|create|edit|shop-.*"
}
]A narrow matcher lets every other tool through without a word, including file changes and tools added later. For an agent that runs unattended, keep the full matcher and let rules approve the harmless calls.
For a team, and the cloud agent
Put the same file in a repository as .github/hooks/variantgate.json to give everyone who opens it the hook. Copilot runs a repository’s hooks only once you trust the folder. Treat a change to that file like a change to your pipeline: whoever can edit it can remove the hook. GitHub’s docs say Copilot’s cloud agent reads the same files; it starts the hook without your saved key, so give its environment a VARIANTGATE_KEY secret. We tested the CLI, not the cloud agent.
If you also use Claude Code
Copilot runs the hooks in a project’s .claude/settings.json too, and reads their answers. If that file runs the VariantGate hook as well, each call there is asked about twice. The Claude Code hook knows when Copilot runs it: it then names Copilot as the agent and denies, rather than asks, when the service cannot be reached. Copilot does not read the ~/.claude/settings.json in your home folder, so variantgate setup claude-code and setup copilot do not overlap.
Check that it works
Start a new session and ask Copilot to run echo hello. A request appears in the inbox; deny it and check that Copilot reports the command as denied. Then ask again and approve it.