Multitenancy hardening: Client Mode

[SteveSandersonMS]

Why

By default, CopilotClient gives every session the full Copilot CLI experience: every built-in tool, every host-side capability, user files like AGENTS.md / co-author trailers / plugins / custom agents, and a system prompt full of environment context.

That is great for an IDE plugin, but unsafe for a multi-tenant app where each session may belong to a different end user. There is no single switch to opt out of the host integration and start from a clean slate.

What

Add CopilotClientMode.Empty (TS mode: "empty"). When set, the SDK flips the host-integration defaults to safe values and requires every session to declare its tool surface up front via availableTools. The runtime stays mode-agnostic; this is a thin SDK-side translation.

Empty mode contract

• Tool surface defaults to empty. availableTools is required on every session; pass a ToolSet (or string[]). excludedTools composes with it via deny-precedence so callers can write "everything matching X except Y".
• Host integration disabled: per-user installed plugins, custom instructions, custom agents on disk, the co-author trailer, the manage-schedule tool, and session telemetry are all forced off (caller-supplied values still win).
• System prompt sanitized: the environment_context section (working directory, OS, etc.) is stripped unless the caller explicitly opts in.
• System keychain integration is disabled
• Storage is required: baseDirectory (or sessionFs) must be set so session data doesn't leak into ~/.copilot by mistake

TypeScript

const client = new CopilotClient({
    mode: "empty",
    baseDirectory: "/tmp/per-tenant-state",
});

const session = await client.createSession({
    onPermissionRequest: approveAll,
    availableTools: new ToolSet()
        .addBuiltIn(BuiltInTools.Isolated)
        .addMcp("*"),
    excludedTools: new ToolSet()
        .addMcp("github-delete_repository"),
});

C#

using var client = new CopilotClient(new CopilotClientOptions
{
    Mode = CopilotClientMode.Empty,
    BaseDirectory = "/tmp/per-tenant-state",
});

await using var session = await client.CreateSessionAsync(new SessionConfig
{
    OnPermissionRequest = PermissionHandler.ApproveAll,
    AvailableTools = new ToolSet()
        .AddBuiltIn(BuiltInTools.Isolated)
        .AddMcp("*"),
    ExcludedTools = new ToolSet()
        .AddMcp("github-delete_repository"),
});

Coverage

TypeScript, Python, Go, C#, and Rust SDKs. Mirrored E2E tests across all five SDKs (shared cassettes under test/snapshots/mode_empty/) verify the SDK translation reaches the runtime correctly: the tool list the LLM sees, the stripped system message, and end-to-end behavior on representative prompts.

Remaining work

This PR establishes the pattern for setting empty mode, but doesn't implement all the runtime flags for disabling all the things we want to disable in that mode. The remaining parts are tracked in different issue that @MackinnonBuck is handling.

[Copilot]

Pull request overview

Adds an opt-in “empty” client mode across SDKs to support multi-tenant / untrusted-prompt hosts by forcing explicit tool allowlisting, stripping environment context from system prompts by default, and applying additional safe session options after create/resume.

Changes:

• Introduces mode="empty" / ClientMode::Empty / ModeEmpty / CopilotClientMode.Empty and enforces extra validation (explicit storage + explicit availableTools).
• Adds ToolSet builders and “isolated” built-in tool allowlists, plus tool-filter validation (reject bare "*").
• Adds E2E + unit coverage across Node/Python/Go/Rust/.NET and shared CAPI proxy snapshots; updates wire payloads to send toolFilterPrecedence="excluded".

Show a summary per file

File	Description
test/snapshots/mode_empty/empty_mode_system_message_replace_llm_follows_caller_content_verbatim.yaml	New empty-mode E2E cassette for systemMessage: replace.
test/snapshots/mode_empty/empty_mode_strips_environment_context_from_the_system_message_by_default.yaml	New empty-mode E2E cassette verifying env-context stripping.
test/snapshots/mode_empty/empty_mode_isolated_set_shell_tool_is_not_exposed.yaml	New empty-mode E2E cassette for isolated built-in tool set.
test/snapshots/mode_empty/empty_mode_excluded_tools_subtracts_from_available_tools.yaml	New empty-mode E2E cassette for allowlist+denylist composition.
test/snapshots/mode_empty/empty_mode_builtin_star_exposes_all_built_in_tools.yaml	New empty-mode E2E cassette for builtin:*.
test/snapshots/mode_empty/empty_mode_append_caller_instruction_takes_effect_and_env_context_stripped.yaml	New empty-mode E2E cassette for append→customize promotion + env stripping.
rust/tests/e2e/mode_empty.rs	Rust E2E coverage mirroring Node cassettes.
rust/tests/e2e.rs	Registers the new Rust E2E module.
rust/src/wire.rs	Adds toolFilterPrecedence to create/resume wire payloads.
rust/src/types.rs	Adds session option fields and ensures wire payload emits deny-wins precedence.
rust/src/session.rs	Enforces empty-mode requirements, strips env context, defaults telemetry off, applies post-create option patch.
rust/src/mode.rs	New Rust mode + ToolSet + isolated allowlist + validation helpers.
rust/src/lib.rs	Exposes mode module + re-exports ClientMode, ToolSet, BUILTIN_TOOLS_ISOLATED; adds client option mode.
rust/src/generated/api_types.rs	Schema/codegen updates (incl. options update enum + MCP auth config reshaping).
python/test_tool_set.py	Python unit tests for ToolSet + empty-mode helpers.
python/e2e/test_mode_empty_e2e.py	Python E2E tests sharing the same recorded snapshots.
python/copilot/client.py	Adds mode, ToolSet support for tool filters, empty-mode defaults, and post-create patching.
python/copilot/_mode.py	Implements Python ToolSet + isolated list + empty-mode validation/defaulting helpers.
python/copilot/init.py	Re-exports ToolSet / mode types / isolated list.
nodejs/test/toolSet.test.ts	Node unit tests for ToolSet, empty-mode validation/defaulting, and wire normalization.
nodejs/test/e2e/mode_empty.e2e.test.ts	Node E2E tests for empty-mode behavior + tool exposure + env stripping.
nodejs/src/types.ts	Adds CopilotClientMode, ToolSet-typed tool filters, and new session option flags.
nodejs/src/toolSet.ts	Adds ToolSet builder and BuiltInTools.Isolated curated set.
nodejs/src/index.ts	Exports ToolSet + BuiltInTools; exports CopilotClientMode type.
nodejs/src/generated/rpc.ts	Schema/codegen updates (incl. toolFilterPrecedence type + MCP auth config reshaping).
nodejs/src/client.ts	Implements empty-mode validation/defaulting, ToolSet normalization, toolFilterPrecedence, and post-create option patching.
nodejs/package.json	Bumps @github/copilot dependency.
nodejs/package-lock.json	Lockfile update for @github/copilot bump.
go/types.go	Adds ClientOptions.Mode and new session option flags; wires toolFilterPrecedence + related fields.
go/toolset.go	Adds Go ClientMode, ToolSet builder, and isolated built-in tool list.
go/toolset_test.go	Go unit tests for ToolSet + empty-mode helpers.
go/rpc/zrpc.go	Generated RPC updates for MCP auth config + toolFilterPrecedence enum.
go/rpc/zrpc_encoding.go	Encoding updates for MCP auth config union decoding.
go/mode_empty.go	Implements Go empty-mode validation/defaulting and post-create options patch.
go/internal/e2e/mode_empty_e2e_test.go	Go E2E tests sharing recorded snapshots.
go/client.go	Hooks empty-mode defaults/validation into create/resume + CLI env updates (disable keytar).
dotnet/test/Unit/ToolSetTests.cs	.NET unit coverage for ToolSet and empty-mode construction constraints.
dotnet/test/E2E/ModeEmptyE2ETests.cs	.NET E2E coverage mirroring other SDKs and recorded snapshots.
dotnet/src/Types.cs	Adds CopilotClientMode + new session option flags and docs.
dotnet/src/ToolSet.cs	Adds .NET ToolSet builder + BuiltInTools.Isolated.
dotnet/src/Generated/Rpc.cs	Generated RPC updates for toolFilterPrecedence option.
dotnet/src/Client.cs	Implements empty-mode validation/defaulting, tool filter validation, toolFilterPrecedence, and post-create option patching.

Copilot's findings

Files not reviewed (3)

• go/rpc/zrpc.go: Language not supported
• go/rpc/zrpc_encoding.go: Language not supported
• nodejs/package-lock.json: Language not supported

Comments suppressed due to low confidence (2)

dotnet/src/Client.cs:855

• If UpdateSessionOptionsForModeAsync throws after session.create succeeds, the catch block only calls RemoveFromClient() (unregisters locally) and does not send session.destroy to the runtime. In empty mode this can leave a running session with defaults the SDK failed to harden. Consider best-effort await session.DisposeAsync() / session.destroy in the failure path once the session has been created/resumed.

            session.WorkspacePath = response.WorkspacePath;
            session.SetCapabilities(response.Capabilities);
            session.SetOpenCanvases(response.OpenCanvases);

            await UpdateSessionOptionsForModeAsync(session, config, cancellationToken).ConfigureAwait(false);
        }
        catch (Exception ex)
        {
            session.RemoveFromClient();
            if (ex is not OperationCanceledException)
            {
                LoggingHelpers.LogTiming(_logger, LogLevel.Warning, ex,
                    "CopilotClient.CreateSessionAsync failed. Elapsed={Elapsed}, SessionId={SessionId}",
                    totalTimestamp,
                    sessionId);
            }
            throw;

dotnet/src/Client.cs:1030

• ResumeSessionAsync has the same failure-mode as CreateSessionAsync: if UpdateSessionOptionsForModeAsync (or any later step) throws after the resume RPC succeeds, the catch path only unregisters locally and does not send session.destroy to the runtime. Consider best-effort disposing/destroying the runtime session in this failure path, especially for empty mode hardening.

            await UpdateSessionOptionsForModeAsync(session, config, cancellationToken).ConfigureAwait(false);
        }
        catch (Exception ex)
        {
            session.RemoveFromClient();
            if (ex is not OperationCanceledException)
            {
                LoggingHelpers.LogTiming(_logger, LogLevel.Warning, ex,
                    "CopilotClient.ResumeSessionAsync failed. Elapsed={Elapsed}, SessionId={SessionId}",
                    totalTimestamp,
                    sessionId);
            }
            throw;

• Files reviewed: 36/43 changed files
• Comments generated: 6

[github-actions]

Cross-SDK Consistency Review ✅ (with one gap noted)

The PR adds the Client Mode / ToolSet feature consistently across Node.js, .NET, Go, Python, and Rust — all five look well-aligned on:

Feature	Node.js	.NET	Go	Python	Rust	Java
ClientMode / mode option	✅ "empty"	✅ CopilotClientMode.Empty	✅ ClientMode	✅ ClientMode	✅ ClientMode	❌
ToolSet builder	✅	✅	✅	✅	✅	❌
BuiltInTools / BuiltinTools	✅	✅	✅	✅	✅	❌
toolFilterMode on session config	✅	✅	✅	✅	✅	❌
Empty-mode construction-time validation	✅	✅	✅	✅	✅	❌
Empty-mode createSession validation	✅	✅	✅	✅	✅	❌
E2E tests for mode=empty	✅	✅	✅	✅	—	❌

Java SDK gap

The Java SDK (java/) is the only implementation not updated in this PR. It currently has:

• SessionConfig.setAvailableTools(List<String>) / setExcludedTools(List<String>) — accepts raw strings only, no ToolSet builder
• No mode field on CopilotClientOptions
• No ClientMode enum
• No BuiltinTools constants (e.g. BuiltinTools.ISOLATED)
• No toolFilterMode on SessionConfig
• No construction-time or createSession-time validation for empty mode

This is already tracked as a follow-up checkbox in the PR description, so no action is required before merging — just flagging for completeness. When the Java implementation lands, the equivalent API would be:

// New: ClientMode enum
public enum ClientMode { COPILOT_CLI, EMPTY }

// New: CopilotClientOptions.setMode(ClientMode)
var client = new CopilotClient(new CopilotClientOptions()
    .setMode(ClientMode.EMPTY)
    .setBaseDirectory("/srv/agents"));

// New: ToolSet builder + BuiltinTools constants
var session = client.createSession(new SessionConfig()
    .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
    .setAvailableTools(new ToolSet()
        .addBuiltIn(BuiltinTools.ISOLATED)
        .addMcp("*"))
    .setExcludedTools(List.of("mcp:github-delete_repository"))).get();

No blocking issues for this PR — the five SDKs that are updated are consistent with each other.

Generated by SDK Consistency Review Agent for issue #1428 · ● 4M · ◷