dex-agents-cli-core 0.5.0__py3-none-any.whl

dex_agents_cli_core/schemas/config.schema.json

@@ -0,0 +1,315 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Dex Agents CLI configuration",
+  "description": "The configuration file of a Dex Agents CLI command, ~/.dex/agents/<harness>.yaml by default. It is YAML 1.2; this schema checks the parsed value. Every harness command in Python and TypeScript reads the same common fields and its own harness section. Do not put secrets in this file: provider keys come from the environment, and connector credentials stay in the connections that Dex Web authorizes. The schema cannot enforce this inside the open harness sections. Omit a field to take its default; null is never a valid value. The settings of one session may change model and system_prompt and may only narrow the rest; see session-settings.schema.json.",
+  "$comment": "Patterns end with (?![\\s\\S]) rather than $, because Python's re lets $ match before a trailing newline and ECMAScript does not. The not schema repeats properties so that Ajv's strictRequired mode accepts it.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "model": {
+      "$ref": "#/$defs/model",
+      "description": "The model the agent calls, in the harness's own format, such as claude-opus-5-5 or a <provider>/<model> ID. Omitted: the harness command's default model. A harness command without a default model refuses to run until this is set."
+    },
+    "system_prompt": {
+      "type": "string",
+      "description": "The agent's instructions. Omitted, together with system_prompt_file: the harness's default instructions. Mutually exclusive with system_prompt_file."
+    },
+    "system_prompt_file": {
+      "$ref": "#/$defs/single_line_text",
+      "description": "A UTF-8 text file whose content is the agent's instructions, read when the command starts. A leading ~ means the home directory; a relative path is relative to the directory of this configuration file. Mutually exclusive with system_prompt."
+    },
+    "dex": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "The Dex server the Worker connects to.",
+      "default": {
+        "server": "auto"
+      },
+      "properties": {
+        "server": {
+          "anyOf": [
+            {
+              "const": "auto"
+            },
+            {
+              "type": "string",
+              "pattern": "^https?://(?:(?:[A-Za-z0-9-]+\\.)*[A-Za-z][A-Za-z0-9-]*|[0-9]{1,3}(?:\\.[0-9]{1,3}){3}|\\[[0-9A-Fa-f:.]+\\])(?::[0-9]{1,5})?(?:/[!-~]*)?(?![\\s\\S])"
+            }
+          ],
+          "default": "auto",
+          "description": "auto: reuse the running dexcli dev server of this machine, or start one. Otherwise the http or https URL of a Dex server, without user info. Its host is a DNS name whose last label starts with a letter, a dotted IPv4 address, or a bracketed IPv6 address. After the schema, the CLI core also checks that each IPv4 part is 0 or a decimal from 1 to 255 without a leading zero, that an IPv6 address is valid, that no DNS label starts with xn--, and that the port is at most 65535."
+        }
+      }
+    },
+    "connectors": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "The connector tools the agent may call.",
+      "default": {
+        "mcp": "auto"
+      },
+      "properties": {
+        "mcp": {
+          "anyOf": [
+            {
+              "const": "auto"
+            },
+            {
+              "type": "string",
+              "pattern": "^https?://(?:127\\.0\\.0\\.1|localhost|\\[::1\\])(?::[0-9]{1,5})?(?:/[!-~]*)?(?![\\s\\S])"
+            }
+          ],
+          "default": "auto",
+          "description": "The connectors MCP server. auto: the server that dexcli dev provides. Otherwise its http or https URL on a loopback host: 127.0.0.1, localhost, or [::1], without user info. After the schema, the CLI core also checks that the port is at most 65535."
+        },
+        "enabled": {
+          "$ref": "#/$defs/connector_entries",
+          "description": "The connections whose operations the agent may call. Omitted: every authorized connection, with every operation its connector offers to agents. An empty list: no connector tools. An entry names a connector, which covers all of its connections, or connector/connection. A single-key map {\"connector/connection\": {\"tools\": [...]}} or {\"connector\": {\"tools\": [...]}} also limits the operations. Two entries must not cover the same connection."
+        }
+      }
+    },
+    "approval": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Approval beyond what each tool already requires.",
+      "default": {
+        "always": []
+      },
+      "properties": {
+        "always": {
+          "$ref": "#/$defs/tool_names",
+          "default": [],
+          "description": "Tool names, as the agent sees them, whose every call waits for approval, in addition to the tools whose connector or local tool policy asks for it."
+        }
+      }
+    },
+    "workspace": {
+      "$ref": "#/$defs/single_line_text",
+      "default": "~/dex-agent-workspace",
+      "description": "The only directory the local file tools may read and write, and the working directory of shell commands. A leading ~ means the home directory; a relative path is relative to the directory of this configuration file."
+    },
+    "local_tools": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Tools that act on this machine. Reads run without approval; writes, browser clicks, form fills, and submits wait for approval; each shell command waits for approval unless it matches the allow list.",
+      "default": {
+        "files": true,
+        "shell": {
+          "enabled": true,
+          "allow": []
+        },
+        "web_fetch": true,
+        "browser": true
+      },
+      "properties": {
+        "files": {
+          "type": "boolean",
+          "default": true,
+          "description": "Read, write, list, and search files inside workspace."
+        },
+        "shell": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Run shell commands in workspace.",
+          "default": {
+            "enabled": true,
+            "allow": []
+          },
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": true,
+              "description": "Whether the agent may run shell commands at all."
+            },
+            "allow": {
+              "$ref": "#/$defs/shell_commands",
+              "default": [],
+              "description": "Commands that run without approval. A command matches only when its whole text equals an entry exactly; every other command waits for approval."
+            }
+          }
+        },
+        "web_fetch": {
+          "type": "boolean",
+          "default": true,
+          "description": "Fetch web pages."
+        },
+        "browser": {
+          "type": "boolean",
+          "default": true,
+          "description": "Drive a local browser. The browser is downloaded the first time the agent uses it."
+        }
+      }
+    },
+    "media": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Where the images of a session are stored: the images attached with /image and the images that connector tools return. Session state keeps only a reference to each image; the bytes stay in this store, one copy per distinct image, named by its SHA-256. Every Worker of a session must reach the same store. Sessions cannot change it: session settings ignore a media key with a warning. Credentials never go in this file: an s3 store reads them from the environment or the standard AWS chain.",
+      "default": {
+        "store": "auto"
+      },
+      "properties": {
+        "store": {
+          "anyOf": [
+            {
+              "const": "auto"
+            },
+            {
+              "type": "string",
+              "pattern": "^s3://[a-z0-9][a-z0-9.-]{1,61}[a-z0-9](?:/[!-~]*)?(?![\\s\\S])"
+            }
+          ],
+          "default": "auto",
+          "description": "auto: a directory on this machine, ~/.dex/agents/media, which keeps its own copy of each image, never a link to the original file. Otherwise s3://<bucket> or s3://<bucket>/<prefix> for an S3 bucket, which Workers on other machines can reach too. The bucket name has 3 to 63 lowercase letters, digits, dots, or hyphens and starts and ends with a letter or digit; the prefix is printable ASCII without spaces. An s3 store needs the S3 support of the agents library: the dex-agents[s3] extra in Python, the @aws-sdk/client-s3 package in TypeScript."
+        },
+        "endpoint": {
+          "type": "string",
+          "pattern": "^https?://(?:(?:[A-Za-z0-9-]+\\.)*[A-Za-z][A-Za-z0-9-]*|[0-9]{1,3}(?:\\.[0-9]{1,3}){3}|\\[[0-9A-Fa-f:.]+\\])(?::[0-9]{1,5})?(?:/[!-~]*)?(?![\\s\\S])",
+          "description": "The http or https URL of an S3-compatible service, such as http://127.0.0.1:9000; omitted, AWS S3. Only valid with an s3 store. With an endpoint, the bucket is addressed in the URL path, as most S3-compatible services need. The host rules and the CLI core checks are those of dex.server."
+        }
+      },
+      "not": {
+        "type": "object",
+        "properties": {
+          "store": {
+            "const": "auto"
+          },
+          "endpoint": true
+        },
+        "required": [
+          "endpoint"
+        ]
+      }
+    },
+    "claude": {
+      "$ref": "#/$defs/harness_options",
+      "description": "Options of the Claude Agent SDK command. Omitted: its defaults."
+    },
+    "openai": {
+      "$ref": "#/$defs/harness_options",
+      "description": "Options of the OpenAI Agents SDK command. Omitted: its defaults."
+    },
+    "pydantic_ai": {
+      "$ref": "#/$defs/harness_options",
+      "description": "Options of the Pydantic AI command. Omitted: its defaults."
+    },
+    "deepagents": {
+      "$ref": "#/$defs/harness_options",
+      "description": "Options of the Deep Agents command. Omitted: its defaults."
+    },
+    "google_adk": {
+      "$ref": "#/$defs/harness_options",
+      "description": "Options of the Google ADK command. Omitted: its defaults."
+    },
+    "vercel_ai": {
+      "$ref": "#/$defs/harness_options",
+      "description": "Options of the Vercel AI SDK command. Omitted: its defaults."
+    },
+    "mastra": {
+      "$ref": "#/$defs/harness_options",
+      "description": "Options of the Mastra command. Omitted: its defaults."
+    },
+    "pi": {
+      "$ref": "#/$defs/harness_options",
+      "description": "Options of the Pi command. Omitted: its defaults."
+    },
+    "builtin": {
+      "$ref": "#/$defs/harness_options",
+      "description": "Options of the built-in agent loop command. Omitted: its defaults."
+    }
+  },
+  "not": {
+    "type": "object",
+    "properties": {
+      "system_prompt": true,
+      "system_prompt_file": true
+    },
+    "required": [
+      "system_prompt",
+      "system_prompt_file"
+    ]
+  },
+  "$defs": {
+    "model": {
+      "type": "string",
+      "minLength": 1,
+      "description": "A model ID in the harness's own format, such as claude-opus-5-5 or openai/gpt-5-mini. Any non-empty string; the harness checks it."
+    },
+    "single_line_text": {
+      "type": "string",
+      "pattern": "^[^\\x00-\\x1f\\x7f]+(?![\\s\\S])",
+      "description": "Non-empty text without control characters."
+    },
+    "tool_name": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_.-]{1,128}(?![\\s\\S])",
+      "description": "A tool name: 1 to 128 ASCII letters, digits, underscores, hyphens, or dots."
+    },
+    "tool_names": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "$ref": "#/$defs/tool_name"
+      }
+    },
+    "operation_name": {
+      "type": "string",
+      "pattern": "^[A-Za-z][A-Za-z0-9_]{0,127}(?![\\s\\S])",
+      "description": "A connector operation: its snake-case name, such as get_message, or its operationId, such as getMessage. Both spellings name the same operation: an operationId is compared after the connectors library's lowerCamelToSnake conversion, which keeps acronym runs together, so listStoryIDs is list_story_ids and getHTTPResponse is get_http_response."
+    },
+    "connector_key": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]{1,62}(?:/[^/\\x00-\\x20\\x7f-\\x9f](?:[^/\\x00-\\x1f\\x7f-\\x9f]{0,254}[^/\\x00-\\x20\\x7f-\\x9f])?)?(?![\\s\\S])",
+      "description": "A connector ID, or connector/connection. A connection name has at most 256 characters, no slash, no control character, and no leading or trailing space, as Dex Web requires."
+    },
+    "connector_entry": {
+      "anyOf": [
+        {
+          "$ref": "#/$defs/connector_key"
+        },
+        {
+          "type": "object",
+          "minProperties": 1,
+          "maxProperties": 1,
+          "propertyNames": {
+            "$ref": "#/$defs/connector_key"
+          },
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "tools"
+            ],
+            "properties": {
+              "tools": {
+                "type": "array",
+                "uniqueItems": true,
+                "minItems": 1,
+                "items": {
+                  "$ref": "#/$defs/operation_name"
+                },
+                "description": "The connector operations the agent may call, by snake-case name or operationId. Two entries must not name the same operation."
+              }
+            }
+          }
+        }
+      ]
+    },
+    "connector_entries": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/connector_entry"
+      }
+    },
+    "shell_commands": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "$ref": "#/$defs/single_line_text"
+      }
+    },
+    "harness_options": {
+      "type": "object",
+      "description": "Harness options. Each harness command defines its own fields and ignores the sections of other harnesses."
+    }
+  }
+}

dex_agents_cli_core/schemas/session-settings.schema.json

@@ -0,0 +1,153 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Dex Agents CLI session settings",
+  "description": "The settings of one session that a Dex Agents CLI command runs: the JSON object that start_session and update_session_settings store, at most 16 KiB. They override the configuration file from the next turn on. model and system_prompt replace the file's values. connectors.enabled may only narrow the file's connections and tools, approval.always only adds tools that need approval, and local_tools may only switch tools off or shrink the shell allow list. An omitted field keeps the file's value; there are no defaults here. Other top-level keys belong to other readers of the settings: they are ignored and reported as warnings, so they never fail a turn. Unknown keys inside a known field are errors. Settings that fail this schema or try to widen the file are rejected as a whole, and the turn fails with the error. A session without settings uses the file as it is. Do not put secrets in settings: they are stored in the session.",
+  "$comment": "The $defs shared with config.schema.json must stay identical to it; the tests in agents/cli/tests check them.",
+  "type": "object",
+  "properties": {
+    "model": {
+      "$ref": "#/$defs/model",
+      "description": "Replaces the file's model."
+    },
+    "system_prompt": {
+      "type": "string",
+      "description": "Replaces the file's system_prompt or system_prompt_file."
+    },
+    "connectors": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "$ref": "#/$defs/connector_entries",
+          "description": "Replaces the file's list, which bounds it. Each entry must fall inside one entry of the file: the same connector, the same connection unless the file's entry names none, and a subset of the file's operations unless the file's entry lists none. When the file omits connectors.enabled, any list narrows it. An empty list: no connector tools."
+        }
+      },
+      "description": "Narrows the file's connectors. connectors.mcp is fixed by the file."
+    },
+    "approval": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "always": {
+          "$ref": "#/$defs/tool_names",
+          "description": "More tools whose every call waits for approval, added to the file's approval.always."
+        }
+      },
+      "description": "Tightens the file's approval."
+    },
+    "local_tools": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Each field may only switch off what the file switches on, or repeat the file's value.",
+      "properties": {
+        "files": {
+          "type": "boolean",
+          "description": "false switches the file tools off; true only repeats the file's true."
+        },
+        "shell": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "description": "false switches shell commands off; true only repeats the file's true."
+            },
+            "allow": {
+              "$ref": "#/$defs/shell_commands",
+              "description": "Replaces the file's allow list. Every command must be in the file's allow list, compared as exact strings."
+            }
+          },
+          "description": "Narrows the file's shell tool."
+        },
+        "web_fetch": {
+          "type": "boolean",
+          "description": "false switches web fetching off; true only repeats the file's true."
+        },
+        "browser": {
+          "type": "boolean",
+          "description": "false switches the browser off; true only repeats the file's true."
+        }
+      }
+    }
+  },
+  "$defs": {
+    "model": {
+      "type": "string",
+      "minLength": 1,
+      "description": "A model ID in the harness's own format, such as claude-opus-5-5 or openai/gpt-5-mini. Any non-empty string; the harness checks it."
+    },
+    "single_line_text": {
+      "type": "string",
+      "pattern": "^[^\\x00-\\x1f\\x7f]+(?![\\s\\S])",
+      "description": "Non-empty text without control characters."
+    },
+    "tool_name": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_.-]{1,128}(?![\\s\\S])",
+      "description": "A tool name: 1 to 128 ASCII letters, digits, underscores, hyphens, or dots."
+    },
+    "tool_names": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "$ref": "#/$defs/tool_name"
+      }
+    },
+    "operation_name": {
+      "type": "string",
+      "pattern": "^[A-Za-z][A-Za-z0-9_]{0,127}(?![\\s\\S])",
+      "description": "A connector operation: its snake-case name, such as get_message, or its operationId, such as getMessage. Both spellings name the same operation: an operationId is compared after the connectors library's lowerCamelToSnake conversion, which keeps acronym runs together, so listStoryIDs is list_story_ids and getHTTPResponse is get_http_response."
+    },
+    "connector_key": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]{1,62}(?:/[^/\\x00-\\x20\\x7f-\\x9f](?:[^/\\x00-\\x1f\\x7f-\\x9f]{0,254}[^/\\x00-\\x20\\x7f-\\x9f])?)?(?![\\s\\S])",
+      "description": "A connector ID, or connector/connection. A connection name has at most 256 characters, no slash, no control character, and no leading or trailing space, as Dex Web requires."
+    },
+    "connector_entry": {
+      "anyOf": [
+        {
+          "$ref": "#/$defs/connector_key"
+        },
+        {
+          "type": "object",
+          "minProperties": 1,
+          "maxProperties": 1,
+          "propertyNames": {
+            "$ref": "#/$defs/connector_key"
+          },
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "tools"
+            ],
+            "properties": {
+              "tools": {
+                "type": "array",
+                "uniqueItems": true,
+                "minItems": 1,
+                "items": {
+                  "$ref": "#/$defs/operation_name"
+                },
+                "description": "The connector operations the agent may call, by snake-case name or operationId. Two entries must not name the same operation."
+              }
+            }
+          }
+        }
+      ]
+    },
+    "connector_entries": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/connector_entry"
+      }
+    },
+    "shell_commands": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "$ref": "#/$defs/single_line_text"
+      }
+    }
+  }
+}

dex_agents_cli_core/tool_policy.py

@@ -0,0 +1,179 @@
+# Copyright (c) 2026 Super Durable, Inc.
+#
+# Licensed under the Sustainable Use License 1.0.
+# You may not use this file except in compliance with the License.
+# See the LICENSE file in the repository root.
+#
+# SPDX-License-Identifier: LicenseRef-Sustainable-Use-1.0
+
+"""Per-turn tool policy and narrowing, for the CLI core's tools and a harness's own replacements."""
+
+from __future__ import annotations
+
+import json
+
+from dex_agents import (
+    AgentTurnContext,
+    DeferredToolCall,
+    DeferredToolExecution,
+    ToolEffect,
+    ToolExecutionError,
+    ToolPolicy,
+)
+from dex_agents_cli_core.config import EffectiveConfig, is_shell_command_allowed
+from dex_agents_cli_core.harness import LocalToolGroup
+
+# From least to most cautious: a policy may move a tool right, never left.
+_EFFECT_CAUTION = {
+    ToolEffect.READ: 0,
+    ToolEffect.IDEMPOTENT_WRITE: 1,
+    ToolEffect.NON_IDEMPOTENT_WRITE: 2,
+    ToolEffect.UNCLASSIFIED: 3,
+}
+_APPROVED_BY_DEFAULT = frozenset({ToolEffect.NON_IDEMPOTENT_WRITE, ToolEffect.UNCLASSIFIED})
+
+
+def resolve_turn_tool_policy(
+    turn: AgentTurnContext,
+    tool_name: str,
+    effect: ToolEffect,
+    requires_approval: bool,
+    turn_config: EffectiveConfig,
+) -> ToolPolicy:
+    """Return one tool call's policy from the tool's own, an explicit session policy, and the turn.
+
+    The tool's effect is a floor. An explicit ``ToolPolicy`` for the tool in
+    ``AgentSessionOptions.tool_policies`` may make the effect more cautious,
+    such as ``read`` to ``non_idempotent_write``, but never less, so a write
+    is never retried as a read; the ranking is ``read``,
+    ``idempotent_write``, ``non_idempotent_write``, then ``unclassified``.
+    Approval is a floor too: the call waits when the tool asks for it, when
+    the explicit policy asks for it, or, when the explicit policy leaves it
+    unset, when the combined effect needs approval by default. An explicit
+    ``requires_approval=False`` never removes the tool's own approval. A tool
+    in the turn's ``approval.always`` always waits.
+
+    A harness that replaces a local tool group, such as with Claude Code's own
+    tools, uses it to give those tools the CLI core's policy.
+
+    Example:
+        >>> turn_config = context.current_turn()
+        >>> policy = resolve_turn_tool_policy(
+        ...     turn, "Bash", ToolEffect.NON_IDEMPOTENT_WRITE,
+        ...     is_shell_command_approval_required(turn_config, command), turn_config)
+
+    Args:
+        turn: The ``RunModel`` context, whose explicit policies may tighten the tool.
+        tool_name: The tool name as the agent sees it.
+        effect: The tool's own effect.
+        requires_approval: Whether the tool itself asks for approval.
+        turn_config: The turn's configuration, for ``approval.always``.
+
+    Returns:
+        The policy for ``DeferredToolCall.policy``.
+    """
+    is_always_approved = tool_name in turn_config.approval.always
+    explicit = turn.tool_policies.get(tool_name)
+    if explicit is None:
+        return ToolPolicy(effect, requires_approval=requires_approval or is_always_approved)
+    if _EFFECT_CAUTION[explicit.effect] > _EFFECT_CAUTION[effect]:
+        effect = explicit.effect
+    if explicit.requires_approval is None:
+        is_explicitly_approved = effect in _APPROVED_BY_DEFAULT
+    else:
+        is_explicitly_approved = explicit.requires_approval
+    return ToolPolicy(
+        effect,
+        requires_approval=requires_approval or is_explicitly_approved or is_always_approved,
+    )
+
+
+def is_local_tool_group_enabled(turn: EffectiveConfig, group: LocalToolGroup) -> bool:
+    """Report whether a turn switches a local tool group on.
+
+    A harness that replaces a group offers its own tools only while this is ``True``.
+
+    Example:
+        >>> if not is_local_tool_group_enabled(context.current_turn(), LocalToolGroup.SHELL):
+        ...     return deny("shell commands are switched off for this session")
+
+    Args:
+        turn: The turn's configuration.
+        group: The local tool group.
+
+    Returns:
+        The group's ``local_tools`` switch for the turn.
+    """
+    local_tools = turn.local_tools
+    match group:
+        case LocalToolGroup.FILES:
+            return local_tools.files
+        case LocalToolGroup.SHELL:
+            return local_tools.shell.enabled
+        case LocalToolGroup.WEB_FETCH:
+            return local_tools.web_fetch
+        case LocalToolGroup.BROWSER:
+            return local_tools.browser
+
+
+def is_shell_command_approval_required(turn: EffectiveConfig, command: str) -> bool:
+    """Report whether a shell command waits for approval in a turn.
+
+    Args:
+        turn: The turn's configuration.
+        command: The command text.
+
+    Returns:
+        ``True`` unless the turn's ``local_tools.shell.allow`` has the command's exact text.
+    """
+    return not is_shell_command_allowed(command, turn.local_tools.shell.allow)
+
+
+#: Key of the reference a source stores for a call of a tool its turn switched off.
+DISABLED_TOOL_REFERENCE_KEY = "disabled_tool"
+
+
+def disabled_tool_call(tool_call_id: str, tool_name: str, arguments: str) -> DeferredToolCall:
+    """Return a call that its tool Step refuses: the turn switched the tool off.
+
+    A runner can still name a tool the turn does not offer, such as from a
+    listing it kept. The refusal is stored with the call, so the tool Step
+    refuses it on any Worker without running anything.
+
+    Args:
+        tool_call_id: The model's tool call ID.
+        tool_name: The tool name.
+        arguments: The arguments as JSON text.
+
+    Returns:
+        A read call without approval whose reference marks it switched off.
+    """
+    return DeferredToolCall(
+        tool_call_id=tool_call_id,
+        tool_name=tool_name,
+        arguments=arguments,
+        policy=ToolPolicy(ToolEffect.READ, requires_approval=False),
+        tool_source_reference=json.dumps({DISABLED_TOOL_REFERENCE_KEY: tool_name}),
+    )
+
+
+def raise_if_disabled(call: DeferredToolExecution) -> None:
+    """Refuse a call that ``disabled_tool_call`` built.
+
+    Args:
+        call: The tool Step's call.
+
+    Raises:
+        ToolExecutionError: If the call's turn switched its tool off.
+    """
+    reference = call.tool_call.tool_source_reference
+    if reference is None:
+        return
+    try:
+        parsed = json.loads(reference)
+    except json.JSONDecodeError:
+        return
+    if isinstance(parsed, dict) and DISABLED_TOOL_REFERENCE_KEY in parsed:
+        raise ToolExecutionError(
+            f"tool {call.tool_call.tool_name} is switched off for this session"
+        )