VS Code Copilot Chat - Copilot Goal System

The VS Code Copilot Chat adapter brings persisted goal mode into VS Code through a custom agent, lifecycle hooks, direct VS Code language model tools, and the local goalctl fallback command. This adapter is preview because VS Code agent hooks and agent plugins are Preview surfaces. The Copilot CLI adapter remains the stable strict mode.

Requirements

Requirement	Notes
VS Code with Copilot Chat	Agent mode must be available.
VS Code `>= 1.95`	Required for extension-contributed language model tools.
Node.js `>= 20`	Runs the hook runner and local goalctl fallback.
Hook access	Organizations can disable agent hooks.

Install

From VS Code Marketplace, run:

Copilot Goal System: Install Recommended Setup

From a cloned repository, run:

./install.sh --target vscode-chat

Install CLI, MCP, and VS Code Chat support:

./install.sh --target all

After install, reload VS Code and select the Goal System custom agent in Copilot Chat. After Marketplace extension updates, VS Code compares the bundled runtime version with the local files in ~/.copilot/extensions/goal-system/. If local files are stale, the status bar changes to Goal Update and VS Code prompts you to update them. Updating local files replaces the installed runtime snapshot, so stale files from older releases do not keep running.

Installed files

Path	Purpose
`~/.copilot/extensions/goal-system/`	Shared package, core, adapters, tests, docs, and dependencies.
`~/.copilot/extensions/goal-system/bin/goalctl.mjs`	Local command fallback for goal operations.
`~/.copilot/agents/goal-system.agent.md`	VS Code custom agent instructions.
`~/.copilot/hooks/goal-system-vscode.json`	VS Code hook config with PascalCase lifecycle events.
`~/.copilot/session-state/goal-system/`	Shared persisted goal state.

The installer writes backups before changing hook config, MCP config, or custom agent files. Current recommended installs add the Copilot CLI goalSystem MCP server entry and keep goalctl as the local recovery fallback.

Enforcement

The VS Code Chat adapter uses official VS Code hook events:

Hook	Behavior
`SessionStart`	Injects the current `sessionId`, `cwd`, and active goal context.
`UserPromptSubmit`	Creates a persisted draft goal for explicit `/goal` activation, injects active-goal context, and loads one unambiguous same-directory goal on explicit continuation.
`PreToolUse`	Warns on repeated goal-state drift and escalates to a critical recovery reminder while still allowing the tool call by default.
`PostToolUse`	Records non-goal tool history into the persisted goal.
`PreCompact`	Writes a compact snapshot before conversation compaction.
`SubagentStart`	Gives subagents a boundary message without exposing goal state.
`SubagentStop`	Lets subagents finish without taking goal ownership.
`Stop`	Blocks premature completion while an active goal remains open.

Goal state remains isolated by sessionId and cwd. Multiple same-directory sessions do not silently merge. If the same goal has been resumed into another session, same-directory continuation treats those duplicate records as one goal and picks the newest copy. Renamed, merged, duplicate, superseded, and clearer-worded discovered issues must be recorded as evidence-backed issueResolutions. They do not disappear from completion checks just because the wording changed.

Goal Tools

The VS Code extension contributes:

goal_system_status
goal_system_open
goal_system_checkpoint
goal_system_finish
goal_system_update
goal_system_close

All tools require the sessionId and cwd that the hook injects into the chat context. This keeps VS Code Chat sessions isolated even when several sessions share one workspace. If direct tools are unavailable, run goalctl status, goalctl checkpoint, or goalctl finish with those values. goalctl update and goalctl close remain available for compatibility and blocked/cancelled terminal states.

Limits

VS Code hooks are Preview and can change.
Organizations can disable hooks or extension tools.
The adapter cannot force goal behavior if you do not select the Goal System agent and Copilot ignores available direct tools.
VS Code asks for confirmation before extension-contributed language model tools run. Choose Always Allow for the Goal System tools to avoid repeated prompts.
Hook output depends on VS Code honoring the documented lifecycle events.

With those surfaces available, VS Code Chat gets the same core persistence, drift control, subagent boundary, and proof-based completion rules as the CLI adapter.

Troubleshooting

Goal tools do not appear

Reload VS Code and select the Goal System custom agent. If tools still do not appear, use goalctl with the sessionId and cwd from hook context, then run Copilot Goal System: Show Status.

Hooks do not run

Open the GitHub Copilot Chat Hooks output channel in VS Code. If no goal hook runs, check:

~/.copilot/hooks/goal-system-vscode.json
VS Code setting chat.hookFilesLocations
organization policy for agent hooks

Stop is blocked

An active goal is still open. The stop hook returns a hard continuation directive: reload goal_system_status, continue the next concrete remaining item, checkpoint persisted state with evidence, and call goal_system_finish only when completion is proven. Use goal_system_close for a real blocker or explicit cancellation.

​Requirements

​Install

​Installed files

​Enforcement

​Goal Tools

​Limits

​Troubleshooting

​Goal tools do not appear

​Hooks do not run

​Stop is blocked