{"record":{"id":"16370064acfdd4b4","repo":"github/copilot-sdk","slug":"client-is-in-mode-modeempty-but-the-session-config","errorCode":null,"errorMessage":"Client is in Mode=ModeEmpty but the session config did not specify AvailableTools. Empty mode requires every session to explicitly opt into the tools it wants — e.g. NewToolSet().AddBuiltIn(BuiltInToolsIsolated...).ToSlice()","messagePattern":"Client is in Mode=ModeEmpty but the session config did not specify AvailableTools\\. Empty mode requires every session to explicitly opt into the tools it wants — e\\.g\\. NewToolSet\\(\\)\\.AddBuiltIn\\(BuiltInToolsIsolated\\.\\.\\.\\)\\.ToSlice\\(\\)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"go/mode_empty.go","lineNumber":68,"sourceCode":"\t\t\t\tfield, entry)\n\t\t}\n\t}\n\treturn nil\n}\n\n// resolveToolFilterOptions validates the configured tool filters and applies\n// empty-mode invariants. Returns the (possibly-mutated) request fields to set.\nfunc (c *Client) resolveToolFilterOptions(availableTools, excludedTools []string) (\n\t[]string, []string, *rpc.OptionsUpdateToolFilterPrecedence, error,\n) {\n\tif err := validateToolFilterList(\"availableTools\", availableTools); err != nil {\n\t\treturn nil, nil, nil, err\n\t}\n\tif err := validateToolFilterList(\"excludedTools\", excludedTools); err != nil {\n\t\treturn nil, nil, nil, err\n\t}\n\tif c.options.Mode == ModeEmpty && availableTools == nil {\n\t\treturn nil, nil, nil, errors.New(\n\t\t\t\"Client is in Mode=ModeEmpty but the session config did not specify AvailableTools. \" +\n\t\t\t\t\"Empty mode requires every session to explicitly opt into the tools it wants — \" +\n\t\t\t\t\"e.g. NewToolSet().AddBuiltIn(BuiltInToolsIsolated...).ToSlice()\")\n\t}\n\tprecedence := rpc.OptionsUpdateToolFilterPrecedenceExcluded\n\treturn availableTools, excludedTools, &precedence, nil\n}\n\n// systemMessageForMode applies empty-mode environment_context stripping to\n// the caller-supplied system message config. App values win (we only inject\n// when the app hasn't already specified an environment_context override).\nfunc (c *Client) systemMessageForMode(supplied *SystemMessageConfig) *SystemMessageConfig {\n\tif c.options.Mode != ModeEmpty {\n\t\treturn supplied\n\t}\n\tremoveAction := SectionOverride{Action: SectionActionRemove}\n\tif supplied == nil {\n\t\treturn &SystemMessageConfig{","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/go/mode_empty.go#L50-L86","documentation":"When the Client is configured with Mode=ModeEmpty, resolveToolFilterOptions requires every session to explicitly declare its available tools. ModeEmpty gives no tools by default, so CreateSession/ResumeSessionWithOptions fail if availableTools is nil.","triggerScenarios":"Creating or resuming a session (CreateSession, ResumeSessionWithOptions) on a ModeEmpty client without passing AvailableTools in the session options.","commonSituations":"Switching a client to ModeEmpty for least-privilege isolation but reusing old session code that never set AvailableTools; passing only ExcludedTools and assuming defaults exist.","solutions":["Build an explicit tool list, e.g. NewToolSet().AddBuiltIn(BuiltInToolsIsolated...).ToSlice(), and pass it as AvailableTools","Change the client Mode if unrestricted tool resolution is intended","Pass an empty (non-nil) tool slice if a tool-less session is deliberate, if supported"],"exampleFix":"// before\nsession, _, _, err := client.CreateSession(ctx, nil) // ModeEmpty, no tools\n// after\ntools := copilot.NewToolSet().AddBuiltIn(copilot.BuiltInToolsIsolated...).ToSlice()\nsession, _, _, err := client.CreateSession(ctx, copilot.SessionOptions{AvailableTools: tools})","handlingStrategy":"validation","validationCode":"if client.Options().Mode == copilot.ModeEmpty && sessionOpts.AvailableTools == nil {\n    return fmt.Errorf(\"ModeEmpty requires AvailableTools\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pair ModeEmpty clients with a helper that always builds a tool set via NewToolSet()","Never create sessions with nil options on ModeEmpty clients","Prefer explicit tool allow-lists for isolation-focused modes"],"tags":["go","tools","configuration","validation"],"backgroundTag":"missing-required-option","analyzedSha":"cd8cf15dc3f9e762615790aaed0a771a0f392755","analyzedAt":"2026-09-09T18:32:31.973Z","contentChangedAt":"2026-09-09T18:32:31.973Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}