The Open Framework for Building Agents
fix(eve): allow disabling agent tool (#825)
Ruidab9889c7fb3
diff --git a/.changeset/calm-agents-rest.md b/.changeset/calm-agents-rest.mdnew file mode 100644index 000000000..35a78b9c6--- /dev/null+++ b/.changeset/calm-agents-rest.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Allow agents to remove the root-only built-in `agent` delegation tool with `disableTool()` from `agent/tools/agent.ts`.diff --git a/docs/concepts/default-harness.md b/docs/concepts/default-harness.mdindex c680253f6..96a1d557f 100644--- a/docs/concepts/default-harness.md+++ b/docs/concepts/default-harness.md@@ -79,6 +79,8 @@ import { disableTool } from "eve/tools";export default disableTool();```+Use `agent/tools/agent.ts` to remove the root-only `agent` delegation tool. The root session then receives no recursive delegation capability, and the model never sees the tool.+If the filename matches no known framework tool, resolution fails instead of silently doing nothing, so a typo surfaces at build time rather than removing the wrong tool.## When to override, disable, or author a new tooldiff --git a/docs/subagents.mdx b/docs/subagents.mdxindex 0c1b8b7f3..b6908fd72 100644--- a/docs/subagents.mdx+++ b/docs/subagents.mdx@@ -22,6 +22,14 @@ The copy uses the root's instructions, connections, auth, and sandbox. It receivThe parent transfers data to the child through the `message` input it gives the subagent. Do not include sensitive data in a subagent request unless that child and its inherited tools, connections, sandbox, and telemetry path are appropriate for that data.+To prevent the root session from delegating, disable `agent` the same way as any other built-in tool:++```ts title="agent/tools/agent.ts"+import { disableTool } from "eve/tools";++export default disableTool();+```+An authored root tool at `agent/tools/agent.ts` takes priority over the built-in.## Declared subagentsdiff --git a/packages/eve/src/execution/node-step.test.ts b/packages/eve/src/execution/node-step.test.tsindex 69622b67e..e87c34105 100644--- a/packages/eve/src/execution/node-step.test.ts+++ b/packages/eve/src/execution/node-step.test.ts@@ -191,8 +191,13 @@ function createTestNode(turnAgent?: RuntimeTurnAgent,overrides: Partial<ResolvedRuntimeAgentNode> = {},): ResolvedRuntimeAgentNode {+ const agent = {} as ResolvedRuntimeAgentNode["agent"];+return {- agent: {} as ResolvedRuntimeAgentNode["agent"],+ agent: {+ ...agent,+ disabledFrameworkTools: [],+ },channels: [],hookRegistry: createEmptyHookRegistry(),nodeId: ROOT_RUNTIME_AGENT_NODE_ID,@@ -239,6 +244,21 @@ describe("createNodeHarnessTools", () => {expect(tools.has("agent")).toBe(false);});++ it("does not give the root node a recursive agent tool when it is disabled", () => {+ const node = createTestNode();+ const tools = createNodeHarnessTools({+ node: {+ ...node,+ agent: {+ ...node.agent,+ disabledFrameworkTools: ["agent"],+ },+ },+ });++ expect(tools.has("agent")).toBe(false);+ });});describe("createExecutionNodeStep", () => {diff --git a/packages/eve/src/execution/node-step.ts b/packages/eve/src/execution/node-step.tsindex 2781cc8f1..c5f8176cd 100644--- a/packages/eve/src/execution/node-step.ts+++ b/packages/eve/src/execution/node-step.ts@@ -14,6 +14,7 @@ import {type RuntimeModelResolutionScope,} from "#runtime/agent/resolve-model.js";import type { RuntimeCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";+import { AGENT_TOOL_DESCRIPTION, AGENT_TOOL_NAME } from "#runtime/framework-tools/agent.js";import { ROOT_RUNTIME_AGENT_NODE_ID, type ResolvedRuntimeAgentNode } from "#runtime/graph.js";import type { PreparedRuntimeTool } from "#runtime/sessions/turn.js";@@ -25,13 +26,6 @@ import { createToolExecuteWithAuth } from "#execution/tool-auth.js";const log = createLogger("execution.node-step");-const BUILT_IN_AGENT_TOOL_DESCRIPTION = [- "Delegate a focused subtask to a fresh copy of yourself.",- "Use it to isolate complex work or split a large task into independent pieces.",- "Issue multiple `agent` calls in one response to run a small fixed set in parallel.",- "Each child has fresh history and state but shares your tools and sandbox, so include essential context in `message` and give parallel writers non-overlapping scopes.",-].join(" ");-/*** Factory that creates a {@link Runtime} for the given compiled* artifacts source and optional node id. Matches the signature of@@ -181,16 +175,20 @@ export function createNodeHarnessTools(input: {}}- if (input.node.nodeId === ROOT_RUNTIME_AGENT_NODE_ID && !tools.has("agent")) {- tools.set("agent", {- description: BUILT_IN_AGENT_TOOL_DESCRIPTION,+ if (+ input.node.nodeId === ROOT_RUNTIME_AGENT_NODE_ID &&+ !input.node.agent.disabledFrameworkTools.includes(AGENT_TOOL_NAME) &&+ !tools.has(AGENT_TOOL_NAME)+ ) {+ tools.set(AGENT_TOOL_NAME, {+ description: AGENT_TOOL_DESCRIPTION,inputSchema: jsonSchema(SUBAGENT_TOOL_INPUT_SCHEMA),- name: "agent",+ name: AGENT_TOOL_NAME,runtimeAction: {kind: "subagent-call",nodeId: input.node.nodeId,recursive: true,- subagentName: "agent",+ subagentName: AGENT_TOOL_NAME,},});}diff --git a/packages/eve/src/runtime/framework-tools/agent.ts b/packages/eve/src/runtime/framework-tools/agent.tsnew file mode 100644index 000000000..6ea842e0d--- /dev/null+++ b/packages/eve/src/runtime/framework-tools/agent.ts@@ -0,0 +1,14 @@+/**+ * Stable model-visible name for the root-only recursive agent tool.+ */+export const AGENT_TOOL_NAME = "agent";++/**+ * Model-facing instructions for the root-only recursive agent tool.+ */+export const AGENT_TOOL_DESCRIPTION = [+ "Delegate a focused subtask to a fresh copy of yourself.",+ "Use it to isolate complex work or split a large task into independent pieces.",+ "Issue multiple `agent` calls in one response to run a small fixed set in parallel.",+ "Each child has fresh history and state but shares your tools and sandbox, so include essential context in `message` and give parallel writers non-overlapping scopes.",+].join(" ");diff --git a/packages/eve/src/runtime/framework-tools/index.test.ts b/packages/eve/src/runtime/framework-tools/index.test.tsindex bdbe11da8..2f817cd16 100644--- a/packages/eve/src/runtime/framework-tools/index.test.ts+++ b/packages/eve/src/runtime/framework-tools/index.test.ts@@ -18,6 +18,7 @@ describe("framework-tools/index", () => {expect(names.has("todo")).toBe(true);expect(names.has("load_skill")).toBe(true);expect(names.has("ask_question")).toBe(true);+ expect(names.has("agent")).toBe(true);// connection_search is now a dynamic tool resolver, not a framework toolexpect(names.has("connection_search")).toBe(false);});diff --git a/packages/eve/src/runtime/framework-tools/index.ts b/packages/eve/src/runtime/framework-tools/index.tsindex f5f7ec953..97cf2b876 100644--- a/packages/eve/src/runtime/framework-tools/index.ts+++ b/packages/eve/src/runtime/framework-tools/index.ts@@ -1,3 +1,4 @@+import { AGENT_TOOL_NAME } from "#runtime/framework-tools/agent.js";import { ASK_QUESTION_TOOL_DEFINITION } from "#runtime/framework-tools/ask-question.js";import { BASH_TOOL_DEFINITION } from "#runtime/framework-tools/bash.js";import { GLOB_TOOL_DEFINITION } from "#runtime/framework-tools/glob.js";@@ -53,5 +54,5 @@ export function getFrameworkToolDefinitions(_config?: {* as an authoring error rather than silently dropping the request.*/export function getAllFrameworkToolNames(): ReadonlySet<string> {- return new Set(ALL_FRAMEWORK_TOOLS.map((def) => def.name));+ return new Set([...ALL_FRAMEWORK_TOOLS.map((def) => def.name), AGENT_TOOL_NAME]);}diff --git a/packages/eve/test/runtime-agent-graph.test.ts b/packages/eve/test/runtime-agent-graph.test.tsindex b0d7dac0d..801a17f43 100644--- a/packages/eve/test/runtime-agent-graph.test.ts+++ b/packages/eve/test/runtime-agent-graph.test.ts@@ -744,6 +744,34 @@ describe("resolveRuntimeAgentGraph", () => {]);});+ it("accepts the runtime-owned agent tool in disabledFrameworkTools", async () => {+ const manifest = createCompiledAgentManifest({+ agentRoot: "/app/agent",+ appRoot: "/app",+ config: {+ model: {+ id: TEST_DEFAULT_MODEL_ID,+ routing: { kind: "gateway", target: "openai" },+ },+ name: "weather-agent",+ },+ disabledFrameworkTools: ["agent"],+ });++ const graph = await resolveRuntimeAgentGraph({+ manifest,+ moduleMap: {+ nodes: {+ [ROOT_COMPILED_AGENT_NODE_ID]: {+ modules: {},+ },+ },+ },+ });++ expect(graph.root.agent.disabledFrameworkTools).toContain("agent");+ });+it("combines replacement and disable in one agent", async () => {const manifest = createCompiledAgentManifest({agentRoot: "/app/agent",