146
"""
147
148
enable: t.List[str]
149
+ require_approval: t.List[str]
150
+ """Experimental. Toolkits whose tools need the user's approval before they
151
+ run. A call that needs approval doesn't run: ``session.execute()`` raises
152
+ ``ToolInputRequiredError`` with the question to show the user."""
153
154
155
class ToolRouterToolkitsDisableConfig(te.TypedDict, total=False):
160
"""
161
162
disable: t.List[str]
163
+ require_approval: t.List[str]
164
+ """Experimental. Toolkits whose tools need the user's approval before they
165
+ run. A call that needs approval doesn't run: ``session.execute()`` raises
166
+ ``ToolInputRequiredError`` with the question to show the user."""
167
+
168
+
169
+class ToolRouterToolkitsRequireApprovalConfig(te.TypedDict):
170
+ """Toolkit policy that only sets which toolkits need the user's approval."""
171
+
172
+ require_approval: t.List[str]
173
+ """Experimental. Toolkits whose tools need the user's approval before they
174
+ run. A call that needs approval doesn't run: ``session.execute()`` raises
175
+ ``ToolInputRequiredError`` with the question to show the user."""
176
177
178
class ToolRouterToolsEnableConfig(te.TypedDict, total=False):
183
"""
184
185
enable: t.List[str]
186
+ require_approval: t.List[str]
187
+ """Experimental. Tools of this toolkit that need the user's approval
188
+ before they run."""
189
190
191
class ToolRouterToolsDisableConfig(te.TypedDict, total=False):
196
"""
197
198
disable: t.List[str]
199
+ require_approval: t.List[str]
200
+ """Experimental. Tools of this toolkit that need the user's approval
201
+ before they run."""
202
203
204
class ToolRouterToolsTagsConfig(te.TypedDict, total=False):
211
"""
212
213
tags: ToolRouterConfigTags
214
+ require_approval: t.List[str]
215
+ """Experimental. Tools of this toolkit that need the user's approval
216
+ before they run."""
217
+
218
+
219
+class ToolRouterToolsRequireApprovalConfig(te.TypedDict):
220
+ """Per-toolkit tool policy that only sets which tools need the user's approval."""
221
+
222
+ require_approval: t.List[str]
223
+ """Experimental. Tools of this toolkit that need the user's approval
224
+ before they run."""
225
226
227
# Type alias for per-toolkit tool configuration
230
# - ToolRouterToolsEnableConfig: Dict with 'enable' key (whitelist)
231
# - ToolRouterToolsDisableConfig: Dict with 'disable' key (blacklist)
232
# - ToolRouterToolsTagsConfig: Dict with 'tags' key (filter by MCP tags)
233
+# - ToolRouterToolsRequireApprovalConfig: Dict with only 'require_approval'
234
+# Each dict can also carry an experimental 'require_approval' list.
235
ToolRouterToolsConfig = t.Union[
236
t.List[str],
237
ToolRouterToolsEnableConfig,
238
ToolRouterToolsDisableConfig,
239
ToolRouterToolsTagsConfig,
240
+ ToolRouterToolsRequireApprovalConfig,
241
]
242
243
251
252
enable: t.Optional[t.List[ToolRouterTag]]
253
disable: t.Optional[t.List[ToolRouterTag]]
254
+ require_approval: t.Optional[t.List[ToolRouterTag]]
255
+ """Experimental. Tools with any of these tags need the user's approval
256
+ before they run."""
257
258
259
# Type alias for tags configuration
472
assistive_prompt: ToolRouterAssistivePromptConfig
473
custom_tools: t.List[CustomTool]
474
custom_toolkits: t.List[ExperimentalToolkit]
475
+ no_elicitation_support_fallback: t.Literal["deny", "allow"]
476
+ """What happens to a call that needs the user's approval when the
477
+ session's MCP client can't ask the user: ``"deny"`` (the default) or
478
+ ``"allow"``."""
479
480
481
@dataclass
740
# Return value structure matches TagsUnionMember1: {"enable": [...]}
741
return {"enable": tags}
742
elif isinstance(tags, dict):
699
- # Object format with enable/disable
743
+ # Object format with enable/disable and an approval list
744
# Only include keys that are present and not None
745
# Return value structure matches TagsUnionMember1
746
+ result: session_create_params.TagsUnionMember1 = {}
747
enable_value = tags.get("enable")
748
+ if enable_value is not None:
749
+ result["enable"] = enable_value
750
disable_value = tags.get("disable")
704
-
705
- # Build result dict only with non-None values
706
- if enable_value is not None and disable_value is not None:
707
- return {
708
- "enable": enable_value,
709
- "disable": disable_value,
710
- }
711
- elif enable_value is not None:
712
- return {"enable": enable_value}
713
- elif disable_value is not None:
714
- return {"disable": disable_value}
715
- else:
716
- return None
751
+ if disable_value is not None:
752
+ result["disable"] = disable_value
753
+ require_approval_value = tags.get("require_approval")
754
+ if require_approval_value is not None:
755
+ result["require_approval"] = require_approval_value
756
+ return result or None
757
758
# Overloads: pass ``mcp=True`` to surface ``session.mcp`` in the returned
759
# type (ToolRouterSessionWithMcp). The MCP endpoint exists at runtime on
768
t.List[str],
769
ToolRouterToolkitsEnableConfig,
770
ToolRouterToolkitsDisableConfig,
771
+ ToolRouterToolkitsRequireApprovalConfig,
772
]
773
] = None,
774
tools: t.Optional[t.Dict[str, ToolRouterToolsConfig]] = None,
799
t.List[str],
800
ToolRouterToolkitsEnableConfig,
801
ToolRouterToolkitsDisableConfig,
802
+ ToolRouterToolkitsRequireApprovalConfig,
803
]
804
] = None,
805
tools: t.Optional[t.Dict[str, ToolRouterToolsConfig]] = None,
829
t.List[str],
830
ToolRouterToolkitsEnableConfig,
831
ToolRouterToolkitsDisableConfig,
832
+ ToolRouterToolkitsRequireApprovalConfig,
833
]
834
] = None,
835
tools: t.Optional[t.Dict[str, ToolRouterToolsConfig]] = None,
860
Example: {'enable': ['github', 'slack']}
861
- ToolRouterToolkitsDisableConfig: Dict with 'disable' key.
862
Example: {'disable': ['linear']}
863
+ Experimental: any dict can carry 'require_approval', the
864
+ toolkits whose tools need the user's approval, or have
865
+ only that key. Example: {'require_approval': ['gmail']}
866
:param tools: Optional per-toolkit tool configuration. Key is toolkit slug,
867
value is ToolRouterToolsConfig which can be:
868
- List[str]: List of tool slugs (shorthand for enable).
881
'slack': {'disable': ['SLACK_DELETE_MESSAGE']},
882
'linear': {'tags': ['readOnlyHint']}
883
}
884
+ Experimental: any dict can carry 'require_approval', the
885
+ tools that need the user's approval, or have only that key.
886
+ Example: {'gmail': {'require_approval': ['GMAIL_SEND_EMAIL']}}
887
:param tags: Optional global MCP tags to filter tools by.
888
Can be:
889
- List[str]: List of tag literals (shorthand for enable).
893
Available tag values: 'readOnlyHint', 'createHint',
894
'updateHint', 'destructiveHint', 'idempotentHint',
895
'openWorldHint'.
896
+ Experimental: the dict can also carry 'require_approval',
897
+ tags whose tools need the user's approval.
898
+ Example: {'require_approval': ['destructiveHint']}
899
Toolkit-level tags override this global setting.
900
:param manage_connections: Optional connection management configuration. Can be:
901
- bool: Simple boolean to enable/disable.
960
- 'user_timezone' (str): IANA timezone identifier
961
(e.g., "America/New_York", "Europe/London").
962
- 'custom_tools' / 'custom_toolkits': SDK custom tools.
963
+ - 'no_elicitation_support_fallback' ('deny' or 'allow'):
964
+ what happens to a call that needs approval when the
965
+ session's MCP client can't ask the user.
966
Set preload=True on a custom tool or toolkit to expose
967
it directly from session.tools(); otherwise custom tools
968
remain search-only.
1148
# config is ToolRouterToolsDisableConfig when "disable" is present
1149
disable_config = t.cast(ToolRouterToolsDisableConfig, config)
1150
transformed_config["disable"] = disable_config["disable"]
1151
+ if "require_approval" in config:
1152
+ approval_config = t.cast(
1153
+ ToolRouterToolsRequireApprovalConfig, config
1154
+ )
1155
+ transformed_config["require_approval"] = approval_config[
1156
+ "require_approval"
1157
+ ]
1158
# Use type guard to narrow the type when "tags" is present
1159
if _is_tools_tags_config(config):
1160
# Type narrowed: config is now ToolRouterToolsTagsConfig
1265
"user_timezone": user_timezone,
1266
}
1267
1268
+ fallback = experimental.get("no_elicitation_support_fallback")
1269
+ if fallback is not None:
1270
+ experimental_payload["no_elicitation_support_fallback"] = fallback
1271
+
1272
# Serialize custom tools and toolkits for the backend
1273
custom_tools = experimental.get("custom_tools")
1274
custom_toolkits = experimental.get("custom_toolkits")