Skip to content

Make tool search and PTC enabled by default - #53

Merged
gvdongen merged 3 commits into
mainfrom
feat/default-ptc-and-tool-search
Nov 16, 2026
Merged

gvdongen merged 3 commits into
mainfrom
feat/default-ptc-and-tool-search

Conversation

@gvdongen

@gvdongen gvdongen commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Turn on tool search and code mode by default

Agent runs now add search_tools and run_program automatically. Before this change, you had to add searchToolsTool() and programTool() to an agent's tools yourself.

  • Tool search: a run adds search_tools when the agent or the run has a deferred tool. The model sees a deferred tool's schema only after a search loads it, so a large catalog stays out of every request.
  • Code mode: a run adds run_program when the agent or the run has a tool a program can call. That is any tool except a handoff or a search tool. The model writes one JavaScript program that runs in QuickJS, calls several tools and returns a compact result. Program calls go through the same guardrails, approvals and maxToolCalls limit as direct calls.

Configure the defaults

agent() has two new options. Both default to true:

agent({
  // ...
  toolSearch: false, // no search_tools; deferred tools are listed like any other tool
  codeMode: false, // no run_program
});
  • A search or program tool in tools, such as programTool({limits}) from /program, replaces the default.
  • The run reads both options from the agent that starts the run.
  • While the run adds a default tool, an agent or run tool with the same name fails the run with Duplicate tool name.

Implementation

  • runTools() in agent-run.ts adds the default tools next to skill tools and read_tool_result. On a handoff, the run decides again based on the new agent's tools. For example, if the new agent has no deferred tools, the run drops search_tools.
  • The default tools hold no state, so all runs share one instance of each.
  • SEARCH_TOOL and PROGRAM_TOOL hold the tool names.

Rename programmatic tool calling to code mode

  • src/ptc/ is now src/code-mode/, and the ptc-* test files are now code-mode-*.
  • Tests named "PTC …" are now "Code mode …".
  • The replay harness's PTCTest service is now ReplayTest, because every replay test uses it.
  • programTool, the /program import path, the run_program tool and the program: true flag keep their names. They name the program the model writes, not the feature, and programTool and /program were released in 0.1.0.

Behavior changes for existing users

  • Deferred tools: an agent with deferred tools and no search tool used to list those tools in full. Now the run hides them until search_tools loads them. Set toolSearch: false to keep the old behavior.
  • Request size: every request that includes run_program grows by about 320 tokens, and search_tools adds about 100. The context-size estimate (jsonTokens, about 2 characters per token) counts them as about 635 and 205. That's why the compaction and usage tests that measure where the cut lands set codeMode: false.
  • Load time: the main entry now loads QuickJS when it's imported, which takes about 20 ms and 1.4 MB, because the program tool's guest module loads at the top level.
  • Reserved names: a tool named search_tools or run_program now fails the run while the run adds the default with that name.

Documentation

  • README.md and packages/core/README.md describe the new defaults.
  • The restate-agents skill (SKILL.md, references/tools.md, references/conversations-and-controls.md) documents the options, how to replace the defaults, and the reserved names.
  • The docs call the feature code mode. "Programmatic tool calling" stays in brackets in the README, tools.md and the codeMode doc comment, so a search for that term still finds it.

Testing

  • New tests in catalog-program.test.ts cover:
    • The default flow, with search, schema loading, a program call and a replay.
    • Turning off and replacing the defaults.
    • Deferred tools added at the run level.
    • Agents with no tools or only handoffs.
    • The name collision.
  • Existing tests expect the new tool lists.
  • After a clean build, pnpm build (compile, lint, format, typecheck), pnpm test (257 unit tests) and pnpm test:integration (68 integration tests) pass.

🤖 Generated with Claude Code

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found.

Reviewed changes This review covers default tool search and programmatic tool calling, including configuration, handoff behavior, documentation, and tests.

  • Default tool search Adds search_tools when deferred tools are present, with opt-out and custom-tool replacement support.
  • Default program calling Adds run_program when the run has callable tools, with opt-out, custom-tool replacement, and recalculation after handoffs.
  • Documentation and tests Updates usage guidance and covers default behavior, replay, handoffs, and configuration.

Important

This run used your free trial credits ($9.40 of $10 left) on GPT Luna, a fast, lightweight model. Connect a provider → to run the model you choose.

Pullfrog  | View workflow run | Using gpt-6-luna (free trial credits) | 𝕏

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found.

Reviewed changes This incremental review covers the rename from programmatic tool calling to code mode and the related updates since the prior pullfrog review.

  • Renamed the option and implementation Replaced the programs option with codeMode, moved the implementation under code-mode, and updated its imports and documentation.
  • Updated tests and replay identifiers Adjusted tests to the new terminology and generalized the replay harness service and invocation names. The package suite passes all 257 tests.

Important

This run used your free trial credits ($9.37 of $10 left) on GPT Luna, a fast, lightweight model. Connect a provider → to run the model you choose.

Pullfrog  | View workflow run | Using gpt-6-luna (free trial credits) | 𝕏

@gvdongen
gvdongen merged commit 7a580bf into main Nov 16, 2026
4 checks passed
@gvdongen
gvdongen deleted the feat/default-ptc-and-tool-search branch November 16, 2026 09:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant