policy-and-managed-settings

Enterprise Policy and Managed Settings

Route a control by where the governed behavior is implemented, not by who requested it. Most Copilot agent controls belong in the runtime, not VS Code.

Governed behavior	Destination	Guide
Copilot runtime: tools, shell, files, URLs, MCP, plugins, subagents, permissions, sandbox, runtime model/telemetry	Runtime managed setting (SDK type only if the host owns the value)	sdk-runtime-policy.md
VS Code editor/workbench	VS Code configuration policy:	vscode-policy.md
Extension-contributed setting	extensionConfigurationPolicy in vscode-distro	extension-policy.md
Independent runtime and editor behavior	Split: runtime setting for agent behavior, VS Code policy for editor behavior only	both of the above
Existing permission policy introduced before 1.133	Bounded migration only	legacy-permission-policy.md

Supporting references:

• github-managed-settings.md: projecting managed settings into VS Code policy (channels, precedence, key declaration).
• policy-support-maintenance.md: Agent Host support inventory and Policy Diagnostics readiness.
• local-testing.md: mock policy server.

Rules

• Runtime enforcement is authoritative. Do not duplicate runtime parsing, matching, or security decisions in VS Code, and never substitute editor UI suppression for runtime enforcement.
• New Copilot controls go directly in the shared managed-settings schema/SDK contract. Do not add a VS Code setting to mirror or bridge one.
• Closed to new properties (existing entries stay for compatibility): GitHub token/account IPolicyData fields consumed by AccountPolicyService, the legacy VS Code setting bridge, and pre-1.133 permission translation.
• Split controls: add the runtime capability first and keep existing editor behavior until it ships. Keep both projections semantically aligned; keep permission authorization separate from sandbox containment; make create/resume/removal/peer/subagent/cloud behavior explicit.
• Every VS Code or extension policy change needs an agentHostPolicySupport entry and pnpm run export-policy-data. Never hand-edit build/lib/policies/policyData.jsonc.
• Never log raw enterprise rules/values or add telemetry containing them.
• Trust source and tests over these docs. Document decisions and invariants; link to source instead of copying it.

Policy-disabled UI

Prefer an option that stays visible but disabled, with the briefcase managed-policy indicator, a localized reason, and an accessible next step, over silently hiding it (design guidance). Use policy provenance to distinguish prohibition from unsupported, feature-gated, or pending states. Presentation never changes authorization: a disabled option must not re-enter the runtime's allowed set or bypass create/resume/write validation. Test policy refresh/removal, keyboard and pointer activation, and stale menus; preserve AI-hiding behavior.