GitHub Copilot CLI

The GitHub Copilot CLI connector wires DefenseClaw into Copilot CLI hooks globally under ~/.copilot/hooks/ by default, with an optional workspace mode for <workspace>/.github/hooks/. Native ask is supported on preToolUse, so HITL approvals surface inside the agent UI.

Platform support

Setup

defenseclaw setup copilot
defenseclaw setup copilot --workspace /path/to/repo

defenseclaw setup copilot
defenseclaw setup copilot --workspace 'C:\path\to\repo'

By default this is global/user-scoped: DefenseClaw writes hook entries into ~/.copilot/hooks/defenseclaw.json. Pass --workspace /path/to/repo only when you intentionally want repo-local <workspace>/.github/hooks/defenseclaw.json wiring. There is no proxy-enforcement path for Copilot CLI — blocking happens hook-side only through the documented preToolUse, permissionRequest, agentStop, and subagentStop responses. postToolUseFailure is advisory-only and can add recovery context after the tool has already failed. Native ask is supported on preToolUse, so HITL approvals surface inside the agent UI for that surface.

If COPILOT_HOME is set, DefenseClaw uses that official Copilot configuration root instead of ~/.copilot for hooks, MCP, skills, and agents.

With an explicitly pinned workspace, inventory follows Copilot's documented precedence instead of the DefenseClaw daemon's current directory. It reads .github/agents and .claude/agents at each ancestor through the Git root; only .md and .agent.md files are agents, with the full suffix removed for identity. MCP inventory reads .mcp.json and .github/mcp.json at each ancestor, then the personal mcp-config.json, preserving name precedence. These are declarations, not proof of live activation: workspace MCP requires folder trust, or GITHUB_COPILOT_PROMPT_MODE_WORKSPACE_MCP=true in untrusted prompt mode; skills include immediate .github, .agents, and .claude locations, inherited parent .github/skills, personal ~/.agents/skills, and additional COPILOT_SKILLS_DIRS entries. Plugin-contributed agents/skills and built-in or organization/remote agents/skills are not expanded from private or remote stores. Session, plugin-contributed, built-in, and remote runtime MCP servers also require official-client live inspection.

The reviewed Copilot CLI 1.0.77 built-in agent IDs are inventoried as immutable versioned-contract rows. Local custom files cannot shadow those built-ins; plugin-contributed and remote organization/enterprise agents still require a live session.

GitHub's current custom-agent command reference and plugin-reference loading diagram disagree about whether project or personal agents load first and how the project conventions are grouped. DefenseClaw follows the dedicated custom-agent reference (project/ancestor first, .github before .claude at each level); the effective order remains unverified pending official-client evidence.

Read-only plugin inventory uses the official copilot plugins list --kind plugin --json command. DefenseClaw does not use that inventory path to install, enable, disable, or remove Copilot plugins.

What setup copilot actually does

The table highlights convenience options rather than the complete alias surface. The alias also accepts --mode, --rule-pack, --fail-mode, approval, block-message, add/replace, and rule-pack-directory options. See the quick-alias reference; use full guardrail setup for scanner, detection-strategy, and judge-provider configuration.

setup copilot is the dedicated Copilot setup alias. It uses the shared guardrail setup backend, defaults to observe mode, and can join an existing hook-connector roster when you choose Add. claw.workspace_dir is cleared for global setup and set only when --workspace is supplied.

Common variations — pick the recipe that fits your phase

defenseclaw setup copilot

defenseclaw setup copilot --yes --with-local-stack

export DEFENSECLAW_LLM_KEY='replace-with-your-key'

defenseclaw setup copilot                                 # global hooks first
defenseclaw setup guardrail \
  --connector copilot \
  --rule-pack strict \
  --scanner-mode local \
  --detection-strategy regex_judge \
  --judge-model anthropic/claude-sonnet-4-20250514 \
  --judge-api-key-env DEFENSECLAW_LLM_KEY \
  --judge-hook-connectors copilot \
  --restart

defenseclaw setup copilot --mode action --human-approval

Decision aids — should I turn this on?

Files DefenseClaw will modify

Hook capabilities

On native Windows, Copilot selects the hook's official powershell field. DefenseClaw's prepared contract invokes a managed copilot-hook.ps1 byte-stream adapter. The adapter reads Copilot's JSON from console stdin, launches the stable defenseclaw-hook.exe runtime without a console and with explicitly redirected standard handles, waits for completion, and writes the runtime's decision back to Copilot unchanged. It normalizes Windows PowerShell 5.1's leading encoding marker and uses UTF-8 without a BOM for the child streams. It does not require Bash or WSL. See the recorded upstream Windows contract for source URLs, version/date evidence, event semantics, and the remaining authentic-client validation work.

Copilot upstream now documents optional OpenTelemetry traces and metrics. DefenseClaw does not configure or certify that native exporter in this connector: no Copilot OTel environment variables or native-exporter credentials are written. Connector telemetry remains derived from authenticated hook events and then flows through the ordinary DefenseClaw v8 audit, alert, webhook, and configured export destinations.

Disable

defenseclaw guardrail disable --connector copilot --yes

Teardown restores the exact pre-Setup hook document when its managed copy is unchanged. If an operator edits the file after Setup, DefenseClaw removes only its recognized handlers and preserves foreign entries, unknown events, and the rest of the file. The same custody rule applies to the pinned workspace hook file.