Apply reviewer feedback to Security section in agent mode docs #8710

Copilot · 2025-08-05T11:57:42Z

This PR applies comprehensive reviewer feedback to improve the Security section of the agent mode documentation. The changes enhance clarity, structure, and completeness based on detailed review comments.

Key Improvements Made

Enhanced language and clarity:

More concise introductory text for better readability
Improved descriptions for autonomous file operations and context access risks
Clearer warnings about MCP server trust and arbitrary code execution

Expanded Workspace Trust explanation:

Added high-level introduction explaining what Workspace Trust is as VS Code's security feature
Added details about restricted mode being the default for untrusted workspaces
Included recommendation to review code before trusting workspaces
Clarified that AI capabilities are disabled in restricted mode

Better structure and formatting:

Changed "MCP security" heading to "MCP server trust" for clarity
Converted user best practices from paragraph format to bulleted list
Enhanced file change review description to mention diff editor capabilities
Added specific example for tool enablement (preventing code edits in planning mode)

Improved technical accuracy:

Updated secure credentials store description to be more specific about "sensitive tool input parameters"
Enhanced session isolation explanation with clearer language
Added proper link to dev containers documentation
Cleaned up corrupted text in Related resources section

User-focused improvements:

Restructured MCP trust section to emphasize security risks upfront
Provided more actionable guidance throughout the section
Maintained security-first approach while improving accessibility

These changes address all reviewer feedback while preserving the comprehensive security guidance and maintaining the security-first approach of the original implementation.

Fixes #8571

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

Co-authored-by: ntrogh <[email protected]>

ntrogh · 2025-08-11T16:57:25Z

@copilot I like the cross-references within the article.
For the Security section, here's an outline and talking points I suggest you use:

Understanding the security model
Document the risks:
- Autonomous file operations: could modify sensitive files, could trigger watch tasks that run malicious code
- Tool and command execution: run tools and terminal commands that can run arbitrary code, interact with local file system, communicate with external services, or modify your dev environment,
- Context and data access: has access to your workspace files and can use this information to make decisions about what changes to implement
Built-in protections
- Workspace Trust integration
- Permission-based security architecture
  - Approve tool calls and terminal commands
  - Review file changes
  - Tool enablement
- MCP security
  - Before starting an MCP server, you need to trust it
    - avoids malicious code execution on startup
    - trust prompt when installing or on MCP server configuration change
- Additional safeguards
  - Secure credentials store for tool configuration
User responsibility and best practices
- Review suggested commands before approval
- Review MCP tool configuration before starting them
- Review MCP server publisher information
- Verify proposed changes to (critical) files
- Consider using dev containers or VMs for isolation to run scripts and make tool calls
- When opening a codebase, open it in restricted mode until you've reviewed it for malicious code like watch tasks or scripts.

ntrogh · 2025-08-11T17:26:04Z

@copilot Only update chat-agent-mode.md

- Reorganize security content per reviewer feedback - Focus on documenting risks in security model section - Enhance built-in protections with clearer structure - Update user best practices based on suggested guidelines - Streamline FAQ answer to match new security content Co-authored-by: ntrogh <[email protected]>

Copilot · 2025-08-11T17:47:29Z

@copilot Only update chat-agent-mode.md

--- ...

Updated the Security section in chat-agent-mode.md following your detailed outline. The new structure focuses on documenting the specific risks, reorganizes built-in protections with clearer sub-sections, and includes comprehensive user best practices as requested. Commit 8555e8a

ntrogh · 2025-08-12T07:38:23Z

docs/copilot/chat/chat-agent-mode.md

+
+### Understanding the security model
+
+Agent mode operates with significant autonomy and comes with important security considerations. It's crucial to understand the potential risks:


Suggested change

Agent mode operates with significant autonomy and comes with important security considerations. It's crucial to understand the potential risks:

Agent mode operates with significant autonomy and comes with important security considerations:

Updated the introductory text to be more concise as suggested. Commit 75090be

ntrogh · 2025-08-12T07:39:53Z

docs/copilot/chat/chat-agent-mode.md

+
+Agent mode operates with significant autonomy and comes with important security considerations. It's crucial to understand the potential risks:
+
+**Autonomous file operations**: Agent mode can automatically modify files in your workspace, including sensitive configuration files, source code, or data files. These modifications could potentially trigger watch tasks or scripts that run malicious code if working with untrusted projects.


Suggested change

**Autonomous file operations**: Agent mode can automatically modify files in your workspace, including sensitive configuration files, source code, or data files. These modifications could potentially trigger watch tasks or scripts that run malicious code if working with untrusted projects.

**Autonomous file operations**: Agent mode automatically modifies files in your workspace, including sensitive configuration files, source code, or data files. These modifications might trigger watch tasks or scripts that run malicious code if working with untrusted projects.

Updated the autonomous file operations description with the suggested wording improvements. Commit 75090be

ntrogh · 2025-08-12T07:41:16Z

docs/copilot/chat/chat-agent-mode.md

+
+**Tool and command execution**: Agent mode can run tools and execute terminal commands that can run arbitrary code, interact with your local file system, communicate with external services, or modify your development environment. These operations have the same privileges as your user account.
+
+**Context and data access**: Agent mode has access to your workspace files and can use this information to make decisions about what changes to implement. This includes potentially sensitive information like API keys, configuration files, or proprietary code.


Suggested change

**Context and data access**: Agent mode has access to your workspace files and can use this information to make decisions about what changes to implement. This includes potentially sensitive information like API keys, configuration files, or proprietary code.

**Context and data access**: Agent mode has access to your workspace files and uses this information to make decisions about what changes to implement. This includes potentially sensitive information like API keys, configuration files, or proprietary code.

Updated the context and data access description with clearer language as suggested. Commit 75090be

ntrogh · 2025-08-12T07:45:34Z

docs/copilot/chat/chat-agent-mode.md

+
+#### Workspace Trust integration
+
+Agent mode respects VS Code's [Workspace Trust](https://code.visualstudio.com/docs/editor/workspace-trust) feature, which is a critical security boundary. Only use agent mode in workspaces you trust completely, as agent mode's autonomous capabilities should not be used with untrusted code or projects.


Can you add a little more background on what Workspace Trust is?
By default, when your workspace is in restricted mode (untrusted), agent mode and other AI capabilities are disabled for the workspace.
Recommendation is that you carefully review code or projects you downloaded before you trust the workspace, and only then use agent mode.

Added more background on Workspace Trust including details about restricted mode by default and the recommendation to review code before trusting the workspace. Commit 75090be

ntrogh · 2025-08-12T07:47:15Z

docs/copilot/chat/chat-agent-mode.md

+
+**Approve tool calls and terminal commands**: Before running tools and terminal commands, agent mode requests explicit confirmation. You can approve actions for the current session, workspace, or all future invocations. See [Manage tool approvals](#manage-tool-approvals) for details.
+
+**Review file changes**: While agent mode can automatically write files, you can review proposed changes in the chat interface before they are applied.


Suggested change

**Review file changes**: While agent mode can automatically write files, you can review proposed changes in the chat interface before they are applied.

**Review file changes**: While agent mode can automatically write files, you can review proposed changes in a diff editor and decide to keep or reject each individual change.

Updated the file changes review description to mention the diff editor and individual change decisions. Commit 75090be

ntrogh · 2025-08-12T08:02:07Z

docs/copilot/chat/chat-agent-mode.md

+
+#### Additional safeguards
+
+**Secure credentials store**: VS Code uses a secure credentials store for tool configuration, helping protect sensitive authentication information.


Suggested change

**Secure credentials store**: VS Code uses a secure credentials store for tool configuration, helping protect sensitive authentication information.

**Secure credentials store**: VS Code uses a secure credentials store for sensitive tool input parameters, helping protect sensitive authentication information.

Updated the secure credentials store description to be more specific about "sensitive tool input parameters". Commit 75090be

ntrogh · 2025-08-12T08:07:39Z

docs/copilot/chat/chat-agent-mode.md

+
+**Request limits**: The `setting(chat.agent.maxRequests)` setting limits the number of requests agent mode can make, preventing runaway operations.
+
+**Session isolation**: Tool approvals can be scoped to the current session, allowing you to grant temporary permissions that don't persist.


Suggested change

**Session isolation**: Tool approvals can be scoped to the current session, allowing you to grant temporary permissions that don't persist.

**Session isolation**: You can scope tool approvals to the current session, enabling you to grant temporary permissions that don't persist.

Updated the session isolation description with clearer language about scoping and enabling temporary permissions. Commit 75090be

ntrogh · 2025-08-12T08:08:02Z

docs/copilot/chat/chat-agent-mode.md

+
+### User responsibility and best practices
+
+While agent mode includes security protections, users should follow these best practices:


Suggested change

While agent mode includes security protections, users should follow these best practices:

While agent mode includes security protections, you should follow these best practices:

Updated the user best practices intro with simpler language as suggested. Commit 75090be

ntrogh · 2025-08-12T08:08:26Z

docs/copilot/chat/chat-agent-mode.md

+### User responsibility and best practices
+
+While agent mode includes security protections, users should follow these best practices:
+


Use a bulleted list for these items

Converted all best practices to a bulleted list format as requested. Commit 75090be

ntrogh · 2025-08-12T08:09:26Z

docs/copilot/chat/chat-agent-mode.md

+
+**Verify proposed changes to critical files**: Pay special attention when agent mode wants to modify important files like configuration files, security settings, or build scripts.
+
+**Consider using dev containers or VMs for isolation**: For enhanced security, run agent mode operations in isolated environments like dev containers or virtual machines to limit potential impact.


Suggested change

**Consider using dev containers or VMs for isolation**: For enhanced security, run agent mode operations in isolated environments like dev containers or virtual machines to limit potential impact.

**Consider using dev containers or VMs for isolation**: For enhanced security, run agent mode operations in isolated environments like [dev containers](https://code.visualstudio.com/docs/devcontainers/containers) or virtual machines to limit potential impact.

Updated the dev containers description with the proper link to the dev containers documentation. Commit 75090be

ntrogh · 2025-08-12T08:49:14Z

@copilot handle my review comments

Co-authored-by: ntrogh <[email protected]>

Copilot · 2025-08-12T09:11:20Z

@copilot handle my review comments

All review comments have been addressed with the suggested changes applied. The Security section now includes the improved language, better structure, expanded Workspace Trust explanation, bulleted list format for best practices, and proper links. Commit 75090be

ntrogh

@copilot Please implement the requested changes

ntrogh · 2025-08-12T11:07:24Z

docs/copilot/chat/chat-agent-mode.md

+
+#### Workspace Trust integration
+
+Agent mode respects VS Code's [Workspace Trust](https://code.visualstudio.com/docs/editor/workspace-trust) feature, which is a critical security boundary. By default, when your workspace is in restricted mode (untrusted), agent mode and other AI capabilities are disabled for the workspace. Recommendation is that you carefully review code or projects you downloaded before you trust the workspace, and only then use agent mode.


@copilot Add a high-level introduction about what Workspace Trust is, so the reader can better frame this section.

Added a high-level introduction explaining that Workspace Trust is VS Code's security feature that helps users decide whether code in a folder can be executed safely. This provides better context for readers to understand the section. Commit 30d8155

ntrogh · 2025-08-12T11:08:03Z

docs/copilot/chat/chat-agent-mode.md

@@ -324,3 +400,20 @@ A chat request can have a maximum of 128 tools enabled at a time. If you have mo

 * [Configure MCP servers to add tools to agent mode](/docs/copilot/chat/mcp-servers.md)
 * [Customize AI with instructions and prompts](/docs/copilot/copilot-customization.md)
+ot/copilot-customization.md)


@copilot What is this? Can you review and remove where appropriate?

Cleaned up the corrupted text that was duplicating parts of the customization documentation link. The Related resources section now ends cleanly with just the two proper links as intended. Commit 30d8155

… up corrupted text Co-authored-by: ntrogh <[email protected]>

Initial plan

3891043

Copilot AI assigned Copilot and ntrogh Aug 5, 2025

Copilot started work on behalf of ntrogh August 5, 2025 11:57 View session

Add comprehensive Security section to agent mode documentation

0433069

Co-authored-by: ntrogh <[email protected]>

Copilot AI changed the title ~~[WIP] Add Security section to agent mode docs (Issue #8571)~~ Add Security section to agent mode docs (Issue #8571) Aug 5, 2025

Copilot AI requested a review from ntrogh August 5, 2025 12:20

Copilot finished work on behalf of ntrogh August 5, 2025 12:20

Copilot started work on behalf of ntrogh August 11, 2025 16:57 View session

Copilot stopped work on behalf of ntrogh due to an error August 11, 2025 17:13
Copilot has encountered an error. See logs for additional details.

Copilot started work on behalf of ntrogh August 11, 2025 17:26 View session

Copilot AI changed the title ~~Add Security section to agent mode docs (Issue #8571)~~ Add comprehensive Security section to agent mode docs (Issue #8571) Aug 11, 2025

Copilot finished work on behalf of ntrogh August 11, 2025 17:48

ntrogh requested changes Aug 12, 2025

View reviewed changes

Copilot started work on behalf of ntrogh August 12, 2025 08:49 View session

Copilot AI and others added 2 commits August 12, 2025 09:10

Apply all reviewer feedback suggestions to Security section

e9a5450

Co-authored-by: ntrogh <[email protected]>

Fix tool enablement description with specific example

75090be

Co-authored-by: ntrogh <[email protected]>

Copilot AI changed the title ~~Add comprehensive Security section to agent mode docs (Issue #8571)~~ Apply reviewer feedback to Security section in agent mode docs Aug 12, 2025

Copilot AI requested a review from ntrogh August 12, 2025 09:12

Copilot finished work on behalf of ntrogh August 12, 2025 09:12

ntrogh requested changes Aug 12, 2025

View reviewed changes

Copilot started work on behalf of ntrogh August 12, 2025 11:08 View session

Address reviewer feedback: Add Workspace Trust introduction and clean…

30d8155

… up corrupted text Co-authored-by: ntrogh <[email protected]>

Copilot finished work on behalf of ntrogh August 12, 2025 11:28

Copilot AI requested a review from ntrogh August 12, 2025 11:28


		### Understanding the security model

		Agent mode operates with significant autonomy and comes with important security considerations. It's crucial to understand the potential risks:


		Agent mode operates with significant autonomy and comes with important security considerations. It's crucial to understand the potential risks:

		Autonomous file operations: Agent mode can automatically modify files in your workspace, including sensitive configuration files, source code, or data files. These modifications could potentially trigger watch tasks or scripts that run malicious code if working with untrusted projects.


		Tool and command execution: Agent mode can run tools and execute terminal commands that can run arbitrary code, interact with your local file system, communicate with external services, or modify your development environment. These operations have the same privileges as your user account.

		Context and data access: Agent mode has access to your workspace files and can use this information to make decisions about what changes to implement. This includes potentially sensitive information like API keys, configuration files, or proprietary code.


		#### Workspace Trust integration

		Agent mode respects VS Code's [Workspace Trust](https://code.visualstudio.com/docs/editor/workspace-trust) feature, which is a critical security boundary. Only use agent mode in workspaces you trust completely, as agent mode's autonomous capabilities should not be used with untrusted code or projects.


		Approve tool calls and terminal commands: Before running tools and terminal commands, agent mode requests explicit confirmation. You can approve actions for the current session, workspace, or all future invocations. See [Manage tool approvals](#manage-tool-approvals) for details.

		Review file changes: While agent mode can automatically write files, you can review proposed changes in the chat interface before they are applied.


		#### Additional safeguards

		Secure credentials store: VS Code uses a secure credentials store for tool configuration, helping protect sensitive authentication information.


		Request limits: The `setting(chat.agent.maxRequests)` setting limits the number of requests agent mode can make, preventing runaway operations.

		Session isolation: Tool approvals can be scoped to the current session, allowing you to grant temporary permissions that don't persist.

	Session isolation: Tool approvals can be scoped to the current session, allowing you to grant temporary permissions that don't persist.
	Session isolation: You can scope tool approvals to the current session, enabling you to grant temporary permissions that don't persist.


		### User responsibility and best practices

		While agent mode includes security protections, users should follow these best practices:


		Verify proposed changes to critical files: Pay special attention when agent mode wants to modify important files like configuration files, security settings, or build scripts.

		Consider using dev containers or VMs for isolation: For enhanced security, run agent mode operations in isolated environments like dev containers or virtual machines to limit potential impact.

Apply reviewer feedback to Security section in agent mode docs #8710

Are you sure you want to change the base?

Apply reviewer feedback to Security section in agent mode docs #8710

Conversation

Copilot AI commented Aug 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Key Improvements Made

Uh oh!

ntrogh commented Aug 11, 2025

Uh oh!

ntrogh commented Aug 11, 2025

Uh oh!

Copilot AI commented Aug 11, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 12, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 12, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 12, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 12, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 12, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 12, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 12, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 12, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 12, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 12, 2025

Choose a reason for hiding this comment

Uh oh!

ntrogh commented Aug 12, 2025

Uh oh!

Copilot AI commented Aug 12, 2025

Uh oh!

ntrogh left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 12, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 12, 2025

Choose a reason for hiding this comment

Copilot AI commented Aug 5, 2025 •

edited

Loading