refactor tools

[whoiskatrin]

disclaimer: this is breaking change, but man i think we need to clean this

Replaces the two-hook pattern (useAgent + useAgentChat) with a single useChat hook that provides:

• Declarative tool config: execute for client-side, confirm: true/false for approval flow
• Simple approve(id) / deny(id) API instead of addToolResult() with magic strings
• Cleaner query option for auth tokens with caching support
• Flexible initialMessages configuration
• Centralize TOOL_CONFIRMATION protocol constants in ai-types.ts

const { messages, sendMessage, approve, deny } = useChat({
  agent: "my-agent",
  tools: {
    calc: { execute: fn },           // client, auto
    delete: { confirm: true },       // server, requires approval
  }
});

[changeset-bot]

⚠️ No Changeset found

Latest commit: c361864

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/cloudflare/agents@731

commit: c361864

[claude]

Claude Code Review

Summary: Clean refactoring that simplifies the human-in-the-loop API. The new useChat hook is more intuitive than the two-hook pattern.

Issues Found

Critical:

1. Type safety issue in use-chat.tsx:47-49: The requiresConfirmation logic is backwards for the default case:

   function requiresConfirmation(tool: Tool): boolean {
     if (tool.confirm !== undefined) return tool.confirm;
     return !tool.execute;  // ❌ Wrong: tools with execute should auto-run by default
   }

   Current behavior: tools with execute but no explicit confirm will require confirmation. This contradicts the documented behavior in tools.ts comments that say execute tools with confirm: false auto-run. Should be: return true (require confirmation by default unless they have execute, then use confirm value).

2. Validation bypassed in utils.ts:76-78: When no schema exists in toolDef, input validation is skipped entirely:

   } else {
     result = await (executeFunc as (args: unknown) => Promise<string>)(toolInput);
   }

   This silently accepts invalid inputs. Either always validate or throw an error if schema is missing.

Moderate:

3. Breaking protocol change in utils.ts:85: Custom denial messages now treated as errors:

   } else {
     result = `Tool execution denied: ${userResponse}`;
   }

   Any client sending a custom denial reason (not TOOL_CONFIRMATION.DENIED) will have it formatted as "Tool execution denied: ...". This may break existing integrations expecting the raw user message.

4. Missing type export in react.tsx:9: Exports ToolConfirmationSignal but not used/documented anywhere. Either use it consistently or remove.

Minor:

5. Test coverage incomplete: use-chat.test.tsx only tests type definitions, not runtime behavior (approve/deny/tool execution logic). Consider adding integration tests.

6. getWeatherInformation duplicated: Exported from both tools.ts:12 and utils.ts:88. Consolidate to single location.

Positive Changes

• Clear separation of concerns (tool config vs transport)
• Protocol constants centralized in ai-types.ts
• Better error handling with try/catch in approve()
• Cleaner guide example code

Recommendation

Fix issues #1-2 before merging (type safety + validation). Consider addressing #3 if backward compatibility matters.