Support developer-controlled built-in tool sets via builtinTools option

[astrobot-houston]

Originally proposed by @alanzabihi in #142. Their description is reproduced verbatim below.

All community-submitted pull requests are automatically converted to issues (bugs) & discussions (feature requests, enhancements) where they can be triaged and prioritized. Once prioritized, a PR implementation is created automatically.

Summary

• Adds builtinTools to harness, session, and per-call options so developers can choose which built-in tools are visible to a model turn.
• Preserves today's default behavior when builtinTools is omitted: read, write, edit, bash, grep, glob, and task are all available.
• Updates the support-agent docs and examples to show a knowledge-base session limited to read, grep, and glob.

Motivation

Flue already lets agent code attach custom tools at the harness and call scopes. This gives built-in tools the same shape.

Some agents do not need the full built-in tool set. A support agent backed by an R2 knowledge base may need to search and read files, but it may not need shell execution, file writes, file edits, or task spawning. A CI triage agent might make the opposite tradeoff.

Letting developers choose the built-in tools for an agent narrows the model's action space, can make tool selection more accurate, and avoids sending tool schemas the agent will not use. That can reduce token use, latency, and cost. It also gives application authors one guardrail among many against unwanted actions. Sandboxing is still the deeper isolation layer.

Test plan

• pnpm install --frozen-lockfile
• pnpm run check:types in packages/runtime
• pnpm run build in packages/runtime
• pnpm run build in packages/cli
• git diff --check

---

Original implementation from #142 by @alanzabihi

[stainlu]

i like this direction, but i’d be pretty explicit about what layer it is.

imo builtinTools is a model-facing affordance / policy hint, not a security boundary.

• builtinTools decides which built-in tool schemas the model can see/use
• sandbox capabilities decide what authority actually exists
• approvals / policy can later decide whether a requested action is allowed at runtime

so if builtinTools: ['read', 'grep'] is set, trusted code can still use session.fs.writeFile() if the sandbox allows it. that feels fine: hiding write from the model is not the same thing as revoking filesystem authority from the environment.

i’d also want this to fail loudly when the requested tool set and sandbox do not match. e.g. builtinTools: ['bash'] with a no-bash sandbox should probably error during init/call setup, not silently drop the tool and make the model guess what happened.

the merge semantics are the part i’d pin down early:

• omitted = current default behavior
• explicit array = replace the inherited built-in set
• empty array = no built-in model tools

that keeps harness/session/call-level overrides understandable. merging arrays across three scopes can get surprising fast.

this also fits the explicit-sandbox direction from #57: tool visibility and environment capability become two separate knobs, which is the right split.

[alanzabihi]

Yes, I agree with that split. I’m not thinking of builtinTools as a replacement for sandboxing, or as the thing that defines real authority. The sandbox still decides what the environment can actually do.

The value I see is one layer earlier: model behavior. If I don’t want the model to write files, call bash, or spawn tasks for a given session, hiding those tool schemas is still useful even if trusted TypeScript code can do those things. It narrows the model’s choices, keeps the prompt/tool surface smaller, and makes it less likely the model wanders into an action path the agent was never meant to take.

So I’d frame it as: sandboxing controls capability; builtinTools controls model-facing affordance. That is weaker than a security boundary, but still a real guardrail. It helps make the agent’s intended behavior explicit. It is our job to help the agent not fail at its job.

I also agree on the semantics:

• omitted means current default behavior
• explicit array replaces the inherited set
• empty array means no built-in model tools

And yeah, failing loudly on tool/sandbox mismatch makes sense to me. That may be a separate capability-checking layer, but I agree with the direction.