feat(vscode-copilot): agent hooks for Copilot Chat in VS Code

[svadrutk]

implement-agenthooks-support-for-vscode-copilot | HumanLayer Task

Why the change

Copilot Chat in VS Code fires agent hooks that this library could not serve, because it speaks the Claude-shaped dialect rather than the Copilot CLI's camelCase one, and the README told users the IDE surfaces fire nothing.

Special things to note

• VS Code cannot be driven headlessly, so there is no e2e/vscode_test.go and no fake hook-executor harness. Verification is unit plus install plus a cross-runtime e2e against the real copilot binary, backed by one manual capture session whose recorded payloads are committed as fixtures. Two things stay unproven and are marked as such: the stop-continuation path (the recorder has no OnStop handler), and SubagentStart/SubagentStop/PreCompact, which never fired in either runtime.
• event.go's canonical tool map is not VS Code-only. It is shared across every provider, and VS Code's tool names were missing from it, so run_in_terminal classified as ToolOther and a deny-shell policy silently did not block it — caught live when a capture session ran echo hello straight through a deny. The trap is that the extension registers copilot_readFile in its package.json but sends read_file on the wire, so auditing from the obvious source maps the wrong strings.
• One generated file serves two runtimes. VS Code and the Copilot CLI glob the same two hook directories, so anything installed is loaded by both. Installing vscode-copilot and copilot together double-fires in the CLI.

Change outline

The wire shape is Claude Code's, so both codecs delegate and only the response placement differs. Decode relabels; encode wraps.

 decodePayload(provider, ...)
+  case ProviderVSCodeCopilot -> decodeClaudeAs(ProviderVSCodeCopilot, ...)   # decodeClaude hardcodes claude-code

 encodeDecision(...)
+  case ProviderVSCodeCopilot -> encodeVSCode(base, d)
+    out := encodeClaude(base, d)
+    if Kind is Stop or SubagentStop and out has "decision":
+      move decision/reason INTO out["hookSpecificOutput"]      # toolCallingLoop reads them nested
+    if Kind is SubagentStart:
+      set hookSpecificOutput.additionalContext                 # encodeClaude has no case; VS Code honors it
+    stamp hookSpecificOutput.hookEventName, never a top-level one

Placement is per-event and not symmetric. Getting it wrong fails silently rather than loudly, which is why each row is pinned by a test.

PreToolUse         permissionDecision, updatedInput   -> hookSpecificOutput
PostToolUse        decision, reason                   -> TOP LEVEL
UserPromptSubmit   decision, reason                   -> TOP LEVEL
Stop, SubagentStop decision, reason                   -> hookSpecificOutput   (the one move)
every type         continue, stopReason, systemMessage-> TOP LEVEL

The runtime is resolved before decode, so nothing downstream needs a second branch.

 Run(...)
   provider, conf := detectProvider(inv, payload)
+  provider = demoteVSCodeToCLI(provider)
+    if provider == vscode-copilot and copilotCLIEnv()   # COPILOT_CLI / COPILOT_PLUGIN_ROOT / COPILOT_PLUGIN_DATA
+      return ProviderCopilot                            # same PascalCase file, CLI session
   decodePayload(provider, ...)

The mirror case shares the helper, and fixes a bug that exists on main today: a camelCase CLI config discovered by VS Code decoded to KindOther with the tool fields lost.

 decodeCopilot(v, conf, now, payload)
   unmarshal copilotIn
+  if in.HookEventName != "" and in.SessionID == ""      # Claude-shaped, not camelCase
+    return decodeClaudeAs(ProviderCopilot, ...)          # label stays copilot -> encodeCopilot answers FLAT
   native := copilotEventName(in)

Files, by responsibility:

 agenthooks/
+├── codec_vscode.go          # encodeVSCode: encodeClaude plus two placement fixups
 ├── codec_claudecode.go      # + decodeClaudeAs, the relabel both new callers share
 ├── codec_copilot.go         # + the Claude-shaped fallthrough
 ├── detect.go                # + copilotCLIEnv, demoteVSCodeToCLI; flag-only provider
 ├── capability.go            # + the VS Code row, read from extension source not docs
 ├── event.go                 # ~ canonical tool map: VS Code's wire names (shared, all providers)
 ├── quirks.go                # + #38-41 Copilot CLI backfills, #42-48 VS Code
 ├── agenthookstest/fixtures/vscode/   # + 3 payloads recorded from a live agent turn
 └── install/
+    └── render_vscode.go     # agenthooks-vscode.json, PascalCase, four omissions

The renderer's omissions each prevent a silent failure, so they are worth reading as intent rather than as gaps: no matcher (VS Code parses matchers and then ignores them, so --filter on the argv is the only real enforcement), no version, no bash/powershell (VS Code's split is windows/linux/osx), and both timeout spellings because the reference table says timeout while a usage example says timeoutSec.

{"hooks": {"PreToolUse": [{
  "type": "command",
  "command": "/usr/local/bin/myhooks agenthooks run --provider=vscode-copilot --timeout=30s --filter=names=Bash",
  "timeout": 30, "timeoutSec": 30
}]}}

Scope	Path	Target.Dir
ScopeUser	hooks/agenthooks-vscode.json	~/.copilot
ScopeProject	.github/hooks/agenthooks-vscode.json	repo root
ScopePlugin	(error)	—

---

Summary by cubic

Adds Copilot Chat in VS Code as a ninth provider. It speaks Claude Code's wire dialect, so decoding delegates to the Claude codec and encoding wraps it with event-specific placement fixups. The installed config is shared with the Copilot CLI — both glob the same hook directories — so CLI sessions demote the provider via COPILOT_* env, and the mirror case lets a Claude-shaped CLI payload fall through to the Claude codec instead of KindOther.

New Features

• Renders agenthooks-vscode.json at ~/.copilot/hooks/ (user) or .github/hooks/ (project) with PascalCase event keys, no matcher, and both timeout spellings.
• Adds a capability row plus quirk registry entries #38–49, grounded in extension source that contradicts the docs on Stop nesting and the timeout key.
• Detection is flag-only: VS Code sets no env marker, so a config without --provider=vscode-copilot degrades to claude-code.
• Resolves MCP tool calls from .vscode/mcp.json and .mcp.json, with the extension's truncating mcp_ prefix sanitization and JSONC parsing.
• Corrects README and DESIGN claims that Copilot hooks are CLI-only.

Bug Fixes

• Maps VS Code wire tool names so deny-shell policies now cover run_in_terminal and six other execution tools, previously all ToolOther.
• decodeCopilot falls through to the Claude codec on snake_case input, so tool args survive and the flat response schema is kept.
• Normalizes toolArgs across Copilot CLI versions, where it is a JSON string through 1.0.80 and a plain object from 1.0.81.

^{Written for commit 64a288b. Summary will update on new commits.}

---

Manual VS Code verification

Verified on VS Code 1.135 / Copilot Chat 0.63 on macOS using a project-scoped .github/hooks/agenthooks-vscode.json in a real repository. Each result below was checked against the Copilot Hooks log; tool/continuation results were also checked in the session transcript or on disk. The normal project hook configuration was restored after the temporary decision hooks.

Scenario	Result	Evidence
Project-scope discovery and provider selection	✅ Pass	A fresh Agent chat loaded agenthooks-vscode.json, invoked the generated command with --provider=vscode-copilot, and used the repository as cwd.
Normal lifecycle	✅ Pass	Observed SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, and Stop, all completing successfully.
File and terminal tool round trip	✅ Pass	read_file and run_in_terminal each produced matching pre/post tool-use IDs. Terminal output VSCODE_AGENTHOOKS_OK arrived intact in PostToolUse.tool_response.
Canonical terminal classification and deny	✅ Pass	A temporary OnToolPre policy classified run_in_terminal as ToolShell and returned nested permissionDecision: "deny". VS Code blocked touch /tmp/VSCODE_AGENTHOOKS_SHOULD_NOT_EXIST; the file remained absent.
Stop continuation	✅ Pass	First Stop arrived with stop_hook_active: false; nested decision: "block"/reason caused one more model iteration containing VSCODE_STOP_CONTINUATION_WORKED. The second Stop had stop_hook_active: true and finished without a loop.
Session-start context	✅ Pass	hookSpecificOutput.additionalContext supplied VSCODE_SESSION_CONTEXT_WORKED; the model returned that marker when asked.
Prompt denial	✅ Pass	Top-level decision: "block"/reason on UserPromptSubmit prevented the model from processing the marker prompt.
Ask-user flow	✅ Pass	permissionDecision: "ask" displayed approval UI; approving allowed the harmless terminal command to run.
Updated tool input	✅ Pass	A requested VSCODE_UPDATE_INPUT_ORIGINAL terminal command was rewritten through updatedInput; only VSCODE_UPDATED_INPUT_WORKED executed.
Post-tool model context	⚠️ Valid shape, upstream race	Both documented nested hookSpecificOutput.additionalContext and a diagnostic top-level block/reason were parsed and logged, but neither marker appeared in the immediate next response on 1.135. Version-pinned source confirms support but shows appendHookContext(...) is started without await; see quirk #49, docs/research/vscode-copilot-posttooluse-context.md, microsoft/vscode#314118, and fix PR microsoft/vscode#331785. The PR therefore retains the documented nested shape and CapAddContext for fixed VS Code builds.

Scope notes

• SubagentStart, SubagentStop, and PreCompact were not observed because this VS Code session did not expose a deterministic way to trigger them.
• A real Windows VS Code invocation and an MCP tool call were not part of this manual session; renderer quoting and VS Code MCP resolution remain covered by automated tests.
• Final automated check: go test ./... passes at c303db3.

[cubic-dev-ai]

Running ultrareview automatically — This PR adds a whole new provider dialect (vscode-copilot) across 25 files, with subtle response-schema placement differences and silent-failure modes — a bug could silently break hooks for both VS Code and the Copilot CLI, warranting deep multi-pass review.. I'll post findings when complete.

[cubic-dev-ai]

Ultrareview completed in 13m 50s

All reported issues were addressed across 25 files

<sub>Tip: instead of fixing issues one by one fix them all with cubic

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 14 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[danielkov]

& cubic comment(s)

[danielkov]

It's good to call this out, but wonder if there's anything we can do about this.

If I give VSCode or Copilot a hook and lie to agenthooks via --provider claude using the current version, what happens?

If behaviour is completely equivalent, I'd think about not adding explicit support and just documenting that --provider claude works for these two harnesses.

If there's any difference in behaviour, I'd smarten the detection logic to reliably detect it or remove detection support from Claude, as we can no longer guarantee it works faithfully.

[svadrutk]

Claude behavior isn't fully equivalent, there are some key differences that affect the provider functionality

• Claude expects decision and reason at the top level. VS Code reads them inside hookSpecificOutput. Using the Claude codec makes ContinueWith(...) silently do nothing in VS Code.
• VS Code accepts additionalContext for SubagentStart. Claude’s codec does not encode context for that event.
• Events would report ProviderClaudeCode, so provider-specific policy, capability checks, MCP resolution, documentation, and diagnostics would all follow the wrong runtime.
  ...and a couple others.

It's hard to smarten the detection logic cause VSCode passes essentially the same shape as Claude, I think silent misclassification is worse than requiring this configuration