Agent Team Planner

Agent Team Planner coordinates dependency-aware Copilot workers in Visual Studio Code. It is an experimental tool: review plans, changes, and commands before relying on their results.

Setup

1. Install the extension from Visual Studio Marketplace.
2. Open a trusted folder in VS Code and sign in to GitHub Copilot.
3. Open Agent Teams: Getting Started for a three-step introduction and a read-only example. The example button copies to your clipboard and opens chat; paste and send it yourself in Copilot Agent mode.
4. Follow progress in Explorer > Agent Teams or Agent Teams: Open Activity Panel.

On hosts supporting extension-contributed Skills, the bundled agent-team skill can be discovered when your request calls for team coordination. Use /agent-team to invoke it explicitly when available. Discovery depends on your VS Code/Copilot version, enabled customizations and tools; it is not guaranteed for every request. VS Code 1.105 does not provide this skill contribution: use #planAgentTeam to draft a plan, or #runAgentTeam for a fully specified authorized task list.

The extension does not install instruction files into your project or user profile, change approval settings, or start work merely because it was installed. Open Agent Teams: Open Troubleshooting for model access, approval, failed tasks, recovery and feedback guidance. A normal first run is: describe a goal, review and approve the draft, then inspect task results and verification evidence. In an unfamiliar or empty workspace, call agent_teams_status with workspaceOnly: true first and compare its effective workspace and Git HEAD to the intended project before creating a draft. Optional agent_teams_plan intake (intakeMode: "assist") inspects only bounded root filenames and asks up to four questions when a consequential planning choice is unresolved. If the goal already suffices, planning proceeds in the same call. The calling agent may answer from verified workspace evidence or prior conversation using intakeAnswers; no mandatory human form is added. Answers do not authorize writes, approval or publication. In optional intake, executable checks must match the entire separately supplied modifyVerification contract, including required project coverage and the working directory; neither goal wording nor answers authorize commands.

Features

• Runs bounded parallel workers with task dependencies and declared writable resources.
• Reclaims only verified owned worktrees of finished teams using file-backed extension storage; dirty worktrees require 30 days of inactivity and a verified archive before removal.
• Persists task state, bounded history, messages, checkpoints, and results in VS Code workspace storage.
• Supports status, cancellation, retry, resume, report export, and confirmed history deletion.
• Previews a locked-task change and creates a revision-fenced, separately approved successor draft for unfinished work without replaying completed tasks.
• Offers optional worktree isolation, model routing, plan approval, and continuous-iteration automation.
• Initializes a persistent Planner through chat using agent_teams_planner_create, with exact workspace binding and create-if-absent semantics; creation alone starts no team.
• Explicitly archives a completed/stopped Planner before starting an independent goal in the same workspace through agent_teams_planner_start_goal. Exact identity/revision and settled execution are required; history remains locally viewable and creation starts no model/team or automation-setting change.

Scoped source character paging

Workers can explicitly request character pages when a long line exceeds the 32,000 UTF-16-unit result cap. Start with offset: 0, then follow page.nextOffset using page.identity as expectedIdentity and the same line range. Changed file bytes or ranges reject continuation; surrogate pairs are not split. The existing 4 MiB file and 200-line range limits remain. Omitting offset preserves the old result shape. Custom scoped readers must explicitly support paging; it never falls back around their access restrictions. The reader's returned canonical path can be reused for reads under an assigned root alias. This does not authorize writes through that spelling, foreign aliases or links that escape the approved root.

Optional verified completion in 0.5

copilotAgentTeams.experimentalVerifiedHandoff is an explicit, disabled-by-default experimental preference. After reload, eligible modify workers can include their complete original report in one approved verification call. The report finishes the worker only after the required gate passes for the same attempt and unchanged source. Missing/advisory gates do not advertise this field. Worktree isolation, independent review and final approval are unchanged; enabling the preference does not start work or invent a verification command. Configure the preference through VS Code Settings and reload manually; leave it disabled unless the required verification workflow is ready.

Planner contracts in 0.4

The 0.4 line starts with consistent public input validation for Planner editing, chat, proposals and evidence retrieval. Unknown fields and malformed values are rejected before mutation or model lookup. Pass runNow as a boolean, integer maxTasks from 1 to 6, and integer maxChars from 100 to 80000; messages must contain 1-4000 characters. Omit optional budgets to retain their defaults. Proposal resources remain a mapping from literal TODO IDs to arrays of paths. This does not approve execution or enable automation.

Valid plans, persisted state and revision checks are unchanged. Evidence retrieval retains the legacy first entry even when that entry exceeds the requested budget; maxChars is not a strict serialized-output size bound. The extension remains experimental; a minor-version milestone is not a stable-API or compatibility guarantee for malformed requests.

Complete report references in 0.9

agent_teams_planner_chat optionally accepts outputRefs: 1-8 unique { teamId, taskId, expectedIdentity } selectors from agent_teams_read_task_output. Supply the exact current expectedPlannerId and expectedRevision. The host resolves only completed final reports from that Goal's owned or audited teams; invalidated authorization, missing reports and stale identities are rejected before the conversation changes.

Completed-output bundles require 1-8 unique exact task IDs in a dense array. The host captures the indexed selectors once before reading any reports; missing/inherited array entries or duplicate selectors are errors, never successful bundles containing null reports. Caller order is preserved. Source-receipt bundles use the same snapshot validation with their existing 1-16-ID limit, including metadata-only reads; provenance and body visibility remain unchanged.

The complete rendered reports, provenance and operator message together must fit the existing 4000-character limit. Oversized input is rejected, never clipped. Credential-shaped text is redacted, with original and rendered SHA-256 hashes distinguished. Reports are untrusted historical source text, not fresh workspace verification or permission to execute. The Planner remains tool-free: references cannot open arbitrary files, grant authority or change automation. Omit outputRefs to keep ordinary chat behavior.

Controls

Use the Activity Panel or Command Palette to inspect teams, stop work, retry or resume tasks, export reports, and delete completed history. Agent Teams: Stop All Automation (Emergency) pauses running teams and optional automation; Resume Automation reverses that pause. Automation is opt-in and external delivery remains manual.

Captain replies are durably queued for the selected task's current attempt and audit generation. A reply posted after that attempt's last model turn can remain unread; it is not silently applied to another task or retry that reuses the worker. Receipts expose this scope and do not promise another model turn. Legacy messages without a scope keep their original routing; the extension does not infer missing historical task ownership.

The graph's Simplify checkbox is enabled by default and remembers your choice in the panel. It hides only transitively implied links: when A leads to B and B leads to C, the extra A-to-C link is hidden. The hidden-link count is shown beside the checkbox. Clear it for the complete dependency graph. Task execution, handoffs and original dependencies are unchanged; Task Details > Execution retains the full dependency list. This does not merge tasks or change an approved plan.

Worktree Isolation

Plan review shows whether modification tasks will use the shared workspace or isolated Git worktrees. Isolation is off by default. Use Worktree settings to choose the User or Workspace setting explicitly; this shortcut does not change settings or approve a plan. Workspace settings can make a tracked settings file dirty. Agent approval of modify tasks requires a clean execution workspace. When the primary workspace is dirty, preview agent_teams_approve_plan with previewOnly: true, then explicitly select a clean registered worktree or request creation from the returned commit hash. The Activity Panel offers the same choice when approving an isolated modify plan. No stash or reset is performed; results remain on the selected execution branch, not the dirty primary branch.

With isolation enabled, each modify task gets its worktree only when it starts after approval and its dependencies. Drafts and read-only tasks do not create worktrees. Changing the setting does not move already-running tasks. Local feedback includes the current setting and recorded worktree status, but not worktree paths or branch names. For a worker's exact on-disk view, agent_teams_read_workspace_file reads a bounded UTF-8 range from its assigned worktree using the same canonical path rules as structured edits. It returns the path and file SHA-256 for comparison with shell output; unsaved VS Code editor buffers are not part of this view. Activity shows a retained worktree's exact path and changed/untracked paths when a failed task leaves dirty files behind. Model request, tool-call and stream-time totals in task details accumulate across task attempts and revisions.

Model Selection

Set copilotAgentTeams.defaultModel to a Copilot model family or id and copilotAgentTeams.fallbackModels to an ordered list of backup models. These settings apply to workers, Planner, conversation compaction and real-profile smoke. They do not follow the model selected in the Copilot Chat dropdown. The shipped modelRouting defaults select GPT-6 Sol for these roles when it is offered by Copilot; unavailable models fall back to the configured backups and then the automatic chain (including earlier supported models). Existing explicit settings and exact-model-pinned teams are not changed by this default.

Explicit modelRouting profile/role rules take priority. A nonempty defaultModel replaces the * route; unavailable routes then try the configured backups followed by the built-in automatic fallback. Empty new settings retain existing routing defaults. Planner and compaction use role:planner; smoke uses role:smoke. Existing reviewer/architect routes can therefore override your new default until you change those role settings.

Backup choices are explicit and may select high-cost models; cost exclusions apply only to implicit fallback. This is selection-time fallback, not provider failover: transient request errors retry the same model. An authorization that explicitly pins a task model still fails closed if that model cannot be resolved. New Continuous Planner dispatches resolve and persist exact catalog model IDs before execution. Retry and reload preserve these bindings even when routing settings change. A missing pinned ID stops that task instead of choosing another model; create a new Planner decision to select a different model. Historical policies and ordinary unpinned teams retain their existing routing behavior.

Team status and wait results include the five latest captain-directed messages, including ones already marked read, with each message limited to 1000 characters plus a truncation marker. Wait revision events remain metadata-only. Status also exposes bounded selected-model metadata and recorded request, queue/stream-time, tool-call and network retry/abort counters. Missing counters are omitted, not assumed to be zero. These counters are diagnostics, not a speedup guarantee. Request and concurrent-read counters remain cumulative across task attempts; late metrics from an earlier attempt are ignored, and tool-only turns do not erase the last observed first-text timing. Persisted verification summaries retain bounded, best-effort-redacted output tails so final test failures remain visible. Verify-worker test counts are self-reported: compare the approved verification command, working directory, and bounded gate output in the task detail before treating a count as a project or solution total. If the output is truncated or a different runner was used independently, the extension cannot infer a comparable aggregate from the worker report alone. For complete captured dotnet test summaries, the gate records observed passed/failed/skipped counts across the summary lines it can verify. A truncated or unrecognized output reports counts unavailable; this does not change the command's exit status. A verify worker's count-only complaint cannot overturn a passed command, but other independent failures still fail the task. For a required test project that a solution gate may omit, set verification.requiredTestProjects to an approved list of 1–5 workspace-relative .csproj paths or { "kind": "python", "manifest": "tests/pyproject.toml" } or { "kind": "node", "manifest": "tests/package.json" } entries. Each is tested separately after the main command; every project must exist in the task worktree, exit successfully, and report a complete, nonzero test summary. Missing or truncated summaries fail this opt-in gate, even when an older solution command passes. Activity and status show individual project outcomes; a passing project result is reusable only for the same contract, attempt, Git HEAD and workspace snapshot. required: false is not accepted with required projects. Independent reviewer verdicts still apply. Alternatively, explicitly opt in with autoDiscoverTestProjects: true and testProjectRoots: ["tests"] in the same required verification contract. Only newly added, non-ignored manifests beneath those approved roots are discovered relative to the Git HEAD frozen before the team's first worker claim. A gate with no newly added projects still runs its approved command; no repository-defined package scripts are invoked. Gated modify tasks without an auditable edit receive an early reminder and stop before their model-round budget ends. If Git finds dirty task artifacts, the retained worktree path and changed paths remain visible in task status. When a task has exactly one declared file and a direct, selected producer handoff, its first-edit reminder comes at 20% of the round budget instead of 40%. The no-edit stop remains at 80%; if the worker edits but does not run the gate, it receives a separate verification reminder. Verification commands run through the platform's native shell (cmd.exe on Windows), not the VS Code terminal's selected profile. Draft approval and direct dispatch reject recognizable unwrapped PowerShell syntax such as $env:TEMP or if (...) { ... }, $LASTEXITCODE, and 2>$null before a worker starts. For a PowerShell-specific check, place the approved logic in an existing .ps1 script and explicitly call it with powershell.exe -NoProfile -NonInteractive -File in the approved command. The extension never rewrites or silently changes the approved command's shell.

Closing the status-wait service ends pending waits with a cancelled outcome (or missing if the team no longer exists); it does not stop the team's work. Deleted teams no longer occupy its revision-tracking cache. Message projection still scans recipients for the omitted count but keeps only five selected references, independent of the number of matching historical messages.

Repeated verification failures are bounded: three failed required gates with the same command, working directory and Git content in one attempt stop the worker and notify the captain. Changed content, success, timeouts, cancellation or unavailable fingerprints reset that count. No success is cached and no gate is skipped. Review the error and ownership before retrying; reloading also resets this attempt-local guard.

Iteration Resource Review

For a Continuous Iteration mission, the agent can set planResources: true on agent_teams_iteration_create and supply up to 20 inspected workspace-relative candidate file paths in resources (or use configured iteration resources). The planner selects a smaller writable set; it cannot invent or expand paths. This step proposes ownership only and does not run workers or commands.

Use Agent Teams: Review Iteration Resources to inspect the goal and exact proposed files, then approve and start or reject. Closing the dialog does nothing. Approval still requires a trusted Git workspace, clean working tree, enabled worktree isolation and unpaused automation. New file candidates need an existing parent directory; directory prefixes and Git metadata are not accepted in this proposal flow. Paths are checked again before dispatch.

Approved ownership is persisted for the whole mission and reused after reload. To change scope, stop the mission and propose again. Failed or interrupted planning never dispatches work; inspect status and stop it before retrying. The existing explicitly scoped create flow remains available when planResources is omitted. Neither path uses a built-in broad resource fallback.

Limits

AI output can be incomplete or wrong. Workers consume Copilot model quotas and may also be subject to tool, provider, and concurrency limits. They can receive repository content, completed dependency output, selected skills, direct messages, and other context supplied by enabled tools. Available host tools may access local files or remote services and can have side effects; declared resources improve coordination but are not a security sandbox.

Local history is bounded and may be compacted. Deleting a team removes the extension's selected local record after confirmation, but cannot recall content already sent to model providers, remote tools, logs, exports, backups, or source-control history. Remote-host retention and deletion are governed by those services. Do not provide secrets or sensitive personal data.

Privacy

The extension uses the VS Code Language Model API and enabled tools to perform requested work. Relevant prompts and context can leave the local machine for Copilot or remote tool hosts. Inspect tool permissions, workspace trust, automation settings, and proposed commands before use. The extension does not provide complete data-loss prevention.

Workspace history and recovery checkpoints are stored through VS Code's extension storage; in remote workspaces this can be on the remote extension host. Logs, exports, Git artifacts and VS Code backups are separate records. There is no fixed automatic deletion period promised here, and deleting a team does not erase those other copies or provider-held data.

The Feedback action opens an unsaved local JSON draft and does not upload it or invoke an AI. Descriptions are optional; bounded diagnostics are included automatically. Review before saving or sharing: redaction is best effort, and VS Code may retain unsaved content in backups. Provider and tool data-handling policies apply separately; this extension does not promise provider training exclusions or a data-residency region.

Agents can call agent_teams_feedback to save the same bounded, redacted report under extension storage, optionally associated with a team/task. Use category, actual (what happened), expected, and/or notes. The tool returns a local file URI and uploaded: false; it does not submit to an external service.

Existing Local Builds

This extension's identity is TrWei.agent-team-planner. An older local build named local.copilot-agent-teams is a different extension, not an automatic upgrade source. Its history is not automatically migrated. Test in a separate profile/workspace, preserve the old installation and history, and do not enable both identities in the same profile because their command/tool identifiers overlap.

Review inherited copilotAgentTeams settings before opening a real repository. For an initially paused environment, set copilotAgentTeams.automationPaused to true. Continuous Planner auto-dispatch and continuous-iteration auto-advance are opt-in; configured automation and recovery can continue work after the initiating chat turn. Retained checkpoints, exports and rollback copies are not proof of a supported import/migration workflow.

Source Development Checks

From a source checkout, npm run check runs the existing host, webview and controlled-host TypeScript validations with no emission. It overlaps at most three compiler processes, bounded by available CPU parallelism, without dropping projects or compiler options. The controlled-host entry files and original strict settings are captured in tsconfig.controlled-host.json in the source checkout.

Failures remain nonzero and report each component. Already-started compilers are drained; cancellation targets only owned compiler children and prevents queued startup. For custom compiler flags, invoke an individual tsc project instead of passing arguments to the parallel coordinator. npm run check:controlled-host remains available independently.

Support

For non-sensitive bug reports and questions, use the extension's Q & A page on Visual Studio Marketplace. Include the extension version, VS Code version, and a redacted description. Do not post credentials, proprietary source, personal data, or other sensitive content.