feat(copilot): add ZERO-294 GitHub Copilot adapter

[spencercharest]

Summary

Subtask: ZERO-297 (GitHub Copilot adapter — CLI plugin + VS Code agent plugin)

Adds a GitHub Copilot plugin surface for the shared Zero plugin:

• Copilot marketplace manifest at .github/plugin/marketplace.json
• Copilot plugin manifest at plugins/zero/.github/plugin/plugin.json
• Copilot hook wiring at plugins/zero/hooks/copilot-hooks.json
• Copilot MCP config at plugins/zero/mcp-copilot.json
• /zero prompt command at plugins/zero/commands/zero.prompt.md
• Copilot standalone guide in guides/github-copilot.md and README link
• shared hook matcher hardening so PreToolUse can self-filter Copilot/VS Code camelCase terminal payloads when matcher values are ignored
• version bump 1.3.3 -> 1.4.0 across versioned plugin manifests via make minor

This PR intentionally does not modify guides/agent-install.md. Proposed runbook notes are documented below for the later agent-install rework.

Official sources used

• GitHub Copilot CLI plugin overview: https://docs.github.com/en/copilot/concepts/agents/copilot-cli/about-cli-plugins
• GitHub Copilot CLI plugin reference: https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-plugin-reference
• Creating a GitHub Copilot CLI plugin: https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/plugins-creating
• VS Code agent plugins: https://code.visualstudio.com/docs/agent-customization/agent-plugins
• VS Code prompt files: https://code.visualstudio.com/docs/copilot/customization/prompt-files

Install and update surfaces

Human in-harness paths:

/plugin marketplace add officialzeroxyz/zero-plugins
/plugin install zero@zero-plugins

VS Code agent mode:

• Extensions view -> search @agentPlugins -> install Zero from the officialzeroxyz/zero-plugins marketplace
• or Command Palette -> Chat: Install Plugin From Source -> https://github.com/officialzeroxyz/zero-plugins

Terminal paths:

copilot plugin marketplace add officialzeroxyz/zero-plugins
copilot plugin install zero@zero-plugins
copilot plugin update zero

Proposed guides/agent-install.md notes

Do not apply in this PR. Suggested section for the later runbook rework:

### GitHub Copilot CLI

1. **Add the Zero marketplace and install the plugin:**

   ```bash
   copilot plugin marketplace add officialzeroxyz/zero-plugins
   copilot plugin install zero@zero-plugins

2. Find the installed plugin root. It lives under Copilot's
   installed-plugins/ directory — default ~/.copilot/installed-plugins/,
   unless COPILOT_HOME overrides it. You have the right directory when it
   contains skills/zero/SKILL.md. Continue with Step 2 below.

## Docker verification

Environment:

- Docker image: `node:22-bookworm`
- Copilot CLI: `@github/copilot` -> `GitHub Copilot CLI 1.0.62`
- Zero runner: `@zeroxyz/cli 1.1.0`
- Mounted branch worktree at `/workspace`
- Copied host `~/.zero` into the container as `/root/.zero` before Zero E2E testing
- Passed host GitHub auth token to Copilot only through `GITHUB_TOKEN`, never printed it

Plugin install/load check:

```bash
docker run --rm \
  -v "$PWD:/workspace" \
  -v "$HOME/.zero:/host-zero:ro" \
  -w /workspace \
  node:22-bookworm bash -lc '
set -euo pipefail
apt-get update >/tmp/apt.log && apt-get install -y --no-install-recommends git jq ca-certificates >/tmp/apt-install.log
cp -a /host-zero /root/.zero
npm install -g @github/copilot
copilot --version
copilot plugin marketplace add /workspace
copilot plugin marketplace list
copilot plugin install zero@zero-plugins
copilot plugin list
find /root/.copilot/installed-plugins -maxdepth 5 -type f | sort
'

Result:

• Marketplace "zero-plugins" added successfully.
• Plugin "zero" installed successfully. Installed 1 skill.
• Installed plugins: zero@zero-plugins (v1.4.0)
• Installed tree included the Copilot manifest, hooks, MCP config, /zero command, and skills/zero/SKILL.md.

Direct Docker Zero loop after copying ~/.zero:

zero search "cdn.withzero.xyz upload txt file" --json
zero get cdn-withzero-xyz-static-site-file-cdn-upload-a0d9f22f
zero fetch --json --capability cdn-withzero-xyz-static-site-file-cdn-upload-a0d9f22f https://cdn.withzero.xyz/api/v1/uploads -d @/tmp/zero-cdn-body.json --max-pay 0.001
curl -fsSL "$returned_url"

Result:

• Run ID: run_4MtIkkz0I7aVU_CRW-OS1
• Returned URL: https://cdn.withzero.xyz/LolkTqxW/agent-harness-e2e-20260614211228.txt
• Payment amount: 0 USDC
• CDN body matched uploaded text: copilot zero e2e 20260614211228
• ~/.zero was copied into the container and accepted by the runner after host auth was refreshed.

Copilot harness E2E attempt:

GITHUB_TOKEN="$(gh auth token)" docker run --rm \
  -e GITHUB_TOKEN \
  -v "$PWD:/workspace" \
  -v "$HOME/.zero:/host-zero:ro" \
  -w /workspace \
  node:22-bookworm bash -lc '
set -euo pipefail
apt-get update >/dev/null && apt-get install -y --no-install-recommends git jq ca-certificates curl >/dev/null
cp -a /host-zero /root/.zero
npm install -g @github/copilot >/dev/null
copilot plugin marketplace add /workspace
copilot plugin install zero@zero-plugins
copilot -p "Use the installed zero skill and terminal tool. Do not run zero review. Run the full Zero upload verification..." --allow-all --add-dir=/workspace
'

Result:

Copilot exited before running the prompt because the active Copilot policy disables third-party MCP servers:

Third-party MCP servers are disabled by your organization's Copilot policy. Only built-in servers are available.
Error: Access denied by policy settings

I also retried with the alternate locally authenticated GitHub account token; it hit the same policy blocker.

Local checks

find . -name '*.json' -print0 | xargs -0 -n1 jq empty
bash -n plugins/zero/hooks/auto-approve-zero.sh plugins/zero/hooks/ensure-runner.sh plugins/zero/hooks/zero-context.sh
git diff --check
# CI-style version lockstep over JSON files with top-level "version"
printf '%s' '{"hook_event_name":"PreToolUse","tool_name":"runTerminalCommand","tool_input":{"command":"zero search hello"}}' | bash plugins/zero/hooks/auto-approve-zero.sh
printf '%s' '{"hookEventName":"preToolUse","toolName":"shell","toolArgs":{"fullCommandText":"zero fetch https://example.com"}}' | bash plugins/zero/hooks/auto-approve-zero.sh

Results:

• JSON parse passed
• shell syntax passed
• whitespace check passed
• versioned manifests all at 1.4.0
• PreToolUse smoke test allowed zero search
• PreToolUse smoke test did not allow zero fetch

Claude-style plugin compatibility and simpler install option

Full Claude Code plugin package support: No. GitHub Copilot has its own CLI/VS Code agent plugin format. It can consume skill/prompt-style artifacts that look familiar to Claude Code users, but there is no documented path where copilot directly installs a .claude-plugin package.

What this means for users:

• Do not ask end users to run build scripts. The consumer path should be Copilot's plugin marketplace/source install flow.

• Once the Zero plugin marketplace entry is published, the preferred CLI flow is:

  /plugin marketplace add officialzeroxyz/zero-plugins
  /plugin install zero@zero-plugins
  

  or from a terminal:

  copilot plugin marketplace add officialzeroxyz/zero-plugins
  copilot plugin install zero@zero-plugins
  copilot plugin update zero

• If we decide the custom Copilot plugin is too much maintenance, the lower-scope alternative is not a Claude plugin install; it is a Copilot-specific install that ships only the Zero skill/prompt/MCP pieces and skips hook automation.

GitHub Releases / no-build install check

Result: No Gemini-style GitHub Release asset resolver needed. Copilot CLI already supports direct GitHub installs from a repository root, repository subdirectory, Git URL, marketplace entry, or local path. Source: GitHub's Copilot CLI plugin reference lists OWNER/REPO, OWNER/REPO:PATH/TO/PLUGIN, and Git URLs as valid copilot plugin install specifications.

Best no-build consumer path:

copilot plugin install officialzeroxyz/zero-plugins:plugins/zero/.github/plugin
# or, after marketplace registration:
copilot plugin marketplace add officialzeroxyz/zero-plugins
copilot plugin install zero@zero-plugins

A GitHub Release tarball would not make this simpler unless Copilot adds release-asset install semantics. The maintenance-friendly direction is to keep the Copilot plugin source-installable from a stable subdirectory and avoid generated build output.

PR status

Draft. Plugin install/load and the direct Docker Zero loop passed, but the required full Copilot-agent-driven E2E is blocked by Copilot policy disabling third-party MCP servers for the available accounts. Move to ready only after testing under a Copilot account/org that allows third-party MCP/plugin MCP servers.

[spencercharest]

Folded into #63 as a matrix entry (copilot in plugins/zero/agents.json) — standalone skills + MCP + a sessionStart hooks fragment in Copilot's dialect. The install block is deferred until this branch's Copilot plugin packaging (marketplace.json + .github/plugin/plugin.json) lands on main; #63's "CLI changes required" section tracks that graduation, including the copilot plugin update zero sweep line. The adapter-template work here stays available on this branch if we later ship per-host templates.