Context-Aware Tool Restrictions

• Entity ID: ent-20260410-8acc723ac051
• Type: mechanism
• Scope: shared
• Status: active

Description

The system enforces distinct tool availability depending on the execution context in which code runs. There are four primary contexts -- main session, sub-agent (sync or async), in-process teammate, and coordinator mode -- each with its own allowed/denied tool set. The restrictions are defined as static Set constants in src/constants/tools.ts and enforced through filtering functions in src/tools/AgentTool/agentToolUtils.ts (for agent contexts) and src/utils/toolPool.ts (for coordinator mode).

In the main session (REPL), all base tools returned by getAllBaseTools() in src/tools.ts are available, subject only to per-tool isEnabled() checks, feature flags, and permission deny-rules applied via filterToolsByDenyRules(). The full tool pool is assembled by assembleToolPool(), which combines built-in tools with MCP tools, deduplicates by name, and sorts for prompt-cache stability. The React hook useMergedTools (or the headless equivalent in main.tsx) then applies coordinator-mode filtering if active. When coordinator mode is off, the main session sees the complete tool set.

For sub-agents (spawned via AgentTool), tools pass through filterToolsForAgent() in agentToolUtils.ts. This function first removes all tools in ALL_AGENT_DISALLOWED_TOOLS (AgentTool itself for non-Anthropic users, TaskOutputTool, ExitPlanModeTool, EnterPlanModeTool, AskUserQuestionTool, TaskStopTool, WorkflowTool). For async agents specifically, only tools listed in ASYNC_AGENT_ALLOWED_TOOLS are kept -- a whitelist of filesystem, search, shell, editing, web, and skill tools. In-process teammates get additional tools beyond the async whitelist: IN_PROCESS_TEAMMATE_ALLOWED_TOOLS adds TaskCreate, TaskGet, TaskList, TaskUpdate, SendMessage, and (if feature-gated) cron scheduling tools. In-process teammates also regain access to AgentTool for spawning sync sub-agents. In coordinator mode, the main session itself is restricted to only COORDINATOR_MODE_ALLOWED_TOOLS: AgentTool, TaskStopTool, SendMessageTool, and SyntheticOutputTool (plus any PR activity subscription MCP tools matched by suffix). This filtering is applied by applyCoordinatorToolFilter() in toolPool.ts, which runs in both the REPL path (via mergeAndFilterTools) and the headless path (via main.tsx).

Key claims

• ALL_AGENT_DISALLOWED_TOOLS is a Set containing TaskOutputTool, ExitPlanModeV2Tool, EnterPlanModeTool, AskUserQuestionTool, TaskStopTool, and (for non-Anthropic users) AgentTool; WorkflowTool is also included when the WORKFLOW_SCRIPTS feature flag is active. These are unconditionally removed from all sub-agent tool pools. (Source: src/constants/tools.ts, lines 36-46)
• ASYNC_AGENT_ALLOWED_TOOLS is a strict whitelist of tools permitted for async agents: FileRead, WebSearch, TodoWrite, Grep, WebFetch, Glob, Bash/PowerShell (via SHELL_TOOL_NAMES), FileEdit, FileWrite, NotebookEdit, Skill, SyntheticOutput, ToolSearch, EnterWorktree, and ExitWorktree. Any tool not in this set is denied unless an in-process teammate exception applies. (Source: src/constants/tools.ts, lines 55-71)
• In-process teammates bypass the async whitelist restriction for tools in IN_PROCESS_TEAMMATE_ALLOWED_TOOLS (TaskCreate, TaskGet, TaskList, TaskUpdate, SendMessage, and conditionally cron tools) and also regain AgentTool access for spawning sync sub-agents. The check uses isInProcessTeammate() from AsyncLocalStorage-based teammateContext.ts. (Source: src/tools/AgentTool/agentToolUtils.ts, lines 100-111; src/constants/tools.ts, lines 77-88)
• Coordinator mode restricts the main session to exactly four tools (AgentTool, TaskStopTool, SendMessageTool, SyntheticOutputTool) plus MCP tools whose names end with subscribe_pr_activity or unsubscribe_pr_activity. The filtering is applied by applyCoordinatorToolFilter() in toolPool.ts. (Source: src/constants/tools.ts, lines 107-112; src/utils/toolPool.ts, lines 35-41)
• MCP tools (names starting with mcp__) are always allowed through filterToolsForAgent() regardless of agent type, bypassing both the disallowed-tools check and the async whitelist. They are separately subject to filterToolsByDenyRules() at the tool-pool assembly level. (Source: src/tools/AgentTool/agentToolUtils.ts, lines 82-84)

Relations

• depends on AgentTool -- the agent-spawning tool that triggers filterToolsForAgent() to restrict the child's tool set
• depends on ToolPermissionContext -- the permission context object whose mode field determines whether coordinator filtering applies
• depends on AsyncLocalStorage teammate context (teammateContext.ts) -- used to detect in-process teammates and grant additional tool access
• used by assembleToolPool() / useMergedTools hook -- the tool-pool assembly pipeline that applies deny rules and coordinator filtering before tools reach the model
• used by resolveAgentTools() in agentToolUtils.ts -- resolves agent definition tool specs against the filtered available tools
• used by coordinatorMode.ts -- getCoordinatorUserContext() reads ASYNC_AGENT_ALLOWED_TOOLS to tell the coordinator what tools its workers have access to

Sources

• src/constants/tools.ts -- defines ALL_AGENT_DISALLOWED_TOOLS, CUSTOM_AGENT_DISALLOWED_TOOLS, ASYNC_AGENT_ALLOWED_TOOLS, IN_PROCESS_TEAMMATE_ALLOWED_TOOLS, COORDINATOR_MODE_ALLOWED_TOOLS
• src/tools/AgentTool/agentToolUtils.ts -- implements filterToolsForAgent() and resolveAgentTools() with the filtering logic for sub-agents
• src/utils/toolPool.ts -- implements applyCoordinatorToolFilter() and mergeAndFilterTools() for coordinator-mode restriction
• src/tools.ts -- getAllBaseTools(), getTools(), assembleToolPool(), filterToolsByDenyRules() for main-session tool assembly
• src/hooks/useMergedTools.ts -- React hook that delegates to assembleToolPool() and mergeAndFilterTools() for the REPL path
• src/coordinator/coordinatorMode.ts -- isCoordinatorMode(), getCoordinatorUserContext(), and the coordinator system prompt
• src/utils/teammateContext.ts -- isInProcessTeammate() via AsyncLocalStorage, used in the teammate tool-access exception
• src/tools/AgentTool/AgentTool.tsx -- builds workerTools via assembleToolPool() and passes them to runAgent()