Skip to content

fork: MCP profile builtinTools "none" (assistant PR 1) - #927

Merged
scuttletoby merged 3 commits into
mainfrom
fork/assistant-builtin-tools-none
Nov 22, 2026
Merged

scuttletoby merged 3 commits into
mainfrom
fork/assistant-builtin-tools-none

Conversation

@scuttletoby

@scuttletoby scuttletoby commented Nov 22, 2026 •

Copy link
Copy Markdown
Owner

Assistant PR 1 of 18.

What

An MCP profile may now say "builtinTools": "none" (optional field). A thread with such a profile gets only MCP tools (T3's own, plus the outside servers its servers keeps): no shell, file, web or other built-in tool. It is the base the assistant runs on: it can read the owner's data through MCP tools without changing files.

  • Claude applies it (claudeMcpProfile.ts): the query opens with tools: [], every built-in the SDK names in disallowedTools, and a PreToolUse guard that refuses any tool whose name is not mcp__…, with the reason. The guard fails closed: a tool name that is not a string, or any error while it checks, is refused (a hook that throws would count as a non-blocking error and let the call through). The plan key includes the field, so a thread switched to it opens a fresh Claude process instead of reusing one that still has its tools. With tools: [] Claude turns tool search off and lists MCP tools directly, so T3's tools stay callable.
  • Every other driver is refused (fail closed): mcpProfileTurnCheck.ts refuses the turn (start, resume, compaction) on Codex and every other wrapped driver, and codexMcpProfile.ts also stops a turn Codex starts by itself for a goal (soon after that turn starts, so its first tool calls may already run; the README says so).
  • Resolver (packages/contracts): a child keeps none from its parent (never wider), isEveryMcpTool and isWithinMcpProfile count it, so launch, local and remote delegation and scheduled tasks treat it as narrower than all. Their refusals name what the wider thread really keeps (new mcpProfileWiderParts: "MCP servers", "T3 tools" and/or "built-in tools"), instead of always "MCP servers or T3 tools". A delegated task carries it to the other machine. Any other value makes the profile broken, and a broken profile is refused.
  • Settings → Fork: a "No built-in tools" box; an edit keeps the field; the profile row shows "Built-in tools: none".
  • Docs: docs/fork/README.md, section server.mcpProfiles. It says that builtinTools removes only the provider's own tools: for a really tool-less thread, also restrict t3Tools (leave out orchestration, playtest, worktree, preview and other groups that act) and servers.

Why

The assistant design (row 1 of its PR split): the assistant should run with MCP tools only, and a turn must be refused wherever that cannot be enforced, never run with more tools. Off by default: no profile uses it unless the owner sets it.

Tests (the new-behaviour tests fail without the change; the old-profile and bad-value tests pin behaviour that must not change)

  • claudeMcpProfile.adapter.test.ts: a thread switched to the profile opens a new Claude process with tools: [] and the built-ins disallowed; the guard denies Bash and allows mcp__…; the guard denies a tool name that is undefined, a number, null or an object, and an input that throws when read (fails closed).
  • launchMcpProfile.test.ts: a launcher with builtinTools: "none" launching into a project on all is refused with "keeps built-in tools", not "MCP servers"; a docs launcher's refusal says "keeps MCP servers".
  • scheduleForkMcpProfile.test.ts: the schedule and fork refusals say "keeps built-in tools" when only that is wider; an existing expectation now reads "keeps MCP servers".
  • scheduledTaskMcpProfile.test.ts: two existing expectations now read "keeps MCP servers" (the real reason there).
  • mcpProfileTurnCheck.test.ts: Claude runs; Codex and OpenCode refuse start and resume, and no call reaches them.
  • codexMcpProfile.test.ts: a direct turn is refused, and a turn Codex starts for a goal is interrupted with the reason.
  • mcpProfile.test.ts (server): an old profile without the field resolves as before; a child keeps none; the carried round trip; bad values are refused for both a profile and a carried task.
  • packages/contracts/src/mcpProfile.test.ts: the settings patch takes none/all and refuses others; mcpProfileWiderParts names each combination.
  • mcpProfileSettings.logic.test.ts: an edit keeps the field and the server takes the save; other profiles save without it.

State question

  • Profile changed mid-turn: the running turn keeps the process and tools it started with; the change applies from the next turn. On Claude the plan key changes, so the next turn opens a fresh process with no built-in tools (resumed), never reusing the old one. On Codex the next turn, or the next one Codex starts for a goal, is refused.
  • Provider restart: nothing is stored; each new process gets its options from the profile as it is when it opens, so a restarted Claude opens with no built-in tools again, and a restarted Codex is refused again.
  • Settings unreadable: the same shared settings read every driver already uses. A settings.json that cannot be read refuses the turn (never all on a guess); when only a provider secret cannot be read, the profiles come from settings.json alone, so builtinTools still applies. A bad builtinTools value marks the profile broken, so its threads are refused, never given the tools.
  • Guard input it cannot read: refused (deny), never let through.
  • Old profiles without the field: read as before (built-in tools kept); saved back without the field; the resolver output and plan key are unchanged, so live processes are reused as before. An older T3 reading a profile or carried task that has the field treats it as one it cannot read and refuses it. A task delegated from an older T3 carries nothing and gets this machine's profile as before. A machine on an older T3 that applies carried profiles accepts a delegated task with the field, then refuses its turn: a thread that does nothing is left there, never one with more tools (in the README).
  • Runs again / stops half-way: the check is read again for every turn; a turn interrupted while its profile is being read never starts (existing behaviour, unchanged).

Limits (in the docs): this is not a sandbox. A Claude setting that turns hooks off, or launch arguments that add tools, can weaken it on a machine set up that way.

Upstream fit

It builds only on the fork's existing MCP-profile code (merged parts 1–5): the same resolver, the same Claude plan seam (mcpProfileOptions spread after the adapter's own options), and the same turn check other drivers already pass through. No upstream file changes beyond the existing pinned seams (seam check passes); ClaudeAdapterV2.ts is untouched.

General vs project

All general: a profile field any T3 user can set, no project facts. Nothing project-specific is in this PR.

Checks

  • packages/contracts, apps/server and apps/web typecheck: 0 errors
  • Review round (head after the fixes): changed test files are now 9 (the first round's count was 6, not 7 as written before; the round adds launchMcpProfile.test.ts, scheduleForkMcpProfile.test.ts, scheduledTaskMcpProfile.test.ts). Run: server 7 files 230 passed, contracts mcpProfile.test.ts 42 passed, web mcpProfileSettings.logic.test.ts 11 passed. With claudeMcpProfile.ts, launchMcpProfile.ts and scheduledTaskMcpProfile.ts put back to the old head: 6 tests fail (the fail-closed guard test, the three built-in-tools / "MCP servers" message tests, and the scheduled-task message expectations). Server and contracts typecheck 0 errors; vp fmt --check and vp lint on the 11 touched files clean; pre-commit (fmt, lint, knip) pass; seam check exit 0.
  • First round: the 6 changed vitest files: 210 passed (as both review lenses ran them; the 264 written here before also counted a neighbouring file). With the source files put back to origin/main and the new tests kept: 7 failed (each new builtinTools test except the ones that pin old behaviour: an old profile without the field, and bad values refused).
  • node .github/scripts/fork-seam-check.cjs --config-ref origin/main origin/main HEAD: exit 0
  • vp fmt --check on touched files: clean; vp lint and knip (pre-commit): clean

🤖 Generated with Claude Code

An MCP profile may say `builtinTools: "none"`: the thread gets only MCP
tools, no shell, file or web tools. Claude applies it (tools: [], every
built-in disallowed, a PreToolUse guard refuses any non-MCP call, and a
changed set opens a fresh process). Every other driver cannot apply it,
so its turns are refused (fail closed), also a turn Codex starts itself.
A child keeps it from its parent; a delegated task carries it; an older
T3 refuses a profile or carried task with the field. Off by default.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@scuttletoby

Copy link
Copy Markdown
Owner Author

lens: code · reviewer: lens agent (Opus 5.5) · read at: 1aa830b
verdict: safe to merge
covered: the whole diff (contracts resolver and patch schema, claudeMcpProfile.ts plan, guard and plan key, the Claude adapter's option spread in ClaudeAdapterV2.ts, mcpProfileTurnCheck.ts, codexMcpProfile.ts incl. goal turns, launchMcpProfile.ts and remoteMcpProfile.ts for launch and delegation, Settings logic, README), with a security focus: can a Claude turn under builtinTools "none" still reach a built-in tool?
checks: ran the PR's 6 changed test files at this head (vp test run): 6 files, 210 tests passed; read the SDK 0.3.321 option code: tools: [] is sent as --tools "" (all built-ins off), disallowedTools as --disallowedTools; traced each route in the focus list (below)
state: runs again: the check runs on every turn start, resume and compaction, and the plan key holds builtin none, so a thread switched to the profile opens a fresh Claude process (never a reused one with its tools) and a switch back opens one with tools; stopped half-way: an interrupted profile read starts no turn (unchanged); old or empty state: a profile without the field resolves, saves and keys as before; an older T3 refuses a profile or carried task that has the field (unknown field: broken, checked on origin/main PROFILE_FIELDS/CARRIED_FIELDS); a bad value marks the profile broken and refuses the thread
blocker: none
major: none
minor: README does not list the main route around it (docs/fork/README.md:1002-1014). The paragraph calls the profile "a base for an assistant that reads the owner's data without changing files" and names only two limits (a hooks-off setting, launch args). With the usual t3Tools: "all" and servers: "all", the thread keeps T3's orchestration group (t3_thread_send asks an existing thread that has built-in tools to act for it), playtest (runs build and deploy steps), worktree, preview (preview_evaluate runs page script), and every outside MCP server Claude loads, which may wrap a shell or file writes. This is said further up the README, at :810-814, but not here. Add one sentence: "builtinTools only removes the provider's own tools; for a read-only assistant also give t3Tools a list without orchestration, playtest, worktree and preview, and servers a list of read-only servers". Starting new threads is already covered: t3_thread_launch, create_threads, schedule_task and the fork transfer refuse a wider thread through isWithinMcpProfile, which now counts builtinTools.
minor: the guard fails open only if it throws (apps/server/src/fork/claudeMcpProfile.ts:133): a PreToolUse callback that throws counts as a non-blocking hook error, so input.tool_name.startsWith on a malformed input would let the call through. This cannot happen with today's SDK, and tools: [] plus disallowedTools are the main barrier, so it is only defence in depth. A typeof input.tool_name !== "string" check returning a deny would make the guard fail closed.
minor: a Codex goal turn is stopped after it starts (apps/server/src/fork/codexMcpProfile.ts:349): the refusal runs on turn/started and then sends goal pause and turn/interrupt, so a thread that had a goal before its profile changed to none can run its first tool calls before the interrupt lands. A direct turn/start is refused before it is sent. The README line "Codex also stops a turn it starts on its own" could say "soon after it starts".
minor: BUILTIN_TOOL_NAMES (SDK 0.3.321) has no legacy names (Task, MultiEdit, BashOutput, KillShell) and no built-ins a newer CLI adds. That is fine because tools: [] (the SDK documents it as "Disable all built-in tools") and the mcp__ name guard cover them; the list only stops allowedTools from bringing one back (SDK: Grep/Glob can be added through allowedTools). No change needed, noted for the record.
routes checked and closed: tools: [] spread after the adapter's tools (ClaudeAdapterV2.ts:2457, set from queryPolicy.tools at :13286); the adapter's later hooks rebuild keeps mcpProfileOptions.hooks (:2482), so the guard survives the SubagentStart/Stop hooks; the adapter sets no disallowedTools of its own on this path, so the override loses nothing; sub-agents: Agent is off, and hooks run in sub-agents; Skill/MCP-served skills: Skill is off; resume and compaction: a fresh process with the same options, earlier tool uses in history cannot run; launch args --tools/--allowedTools/--settings with disableAllHooks: README names it as a limit; other drivers: the turn check refuses start, resume and compaction on every wrapped driver before fixT3ToolSet would let it run, and Codex also refuses its own turn/start; delegation: a carried none goes only to a Claude instance on a machine that applies carried profiles, an older one refuses the unknown field, and a child is cut to none (child.builtinTools ?? parent.builtinTools). A thread-pick on a child stays final (wider than the parent), as for every profile before this PR.

@scuttletoby scuttletoby reopened this Nov 22, 2026
@scuttletoby

Copy link
Copy Markdown
Owner Author

lens: state · reviewer: opus high (state lens agent) · read at: 1aa830b
verdict: safe to merge
covered: the whole diff (contracts resolver and save schema, Claude plan and guard, turn check, Codex goal turns, Settings logic and form, docs); also read the callers it reaches: launchMcpProfile.ts, remoteMcpProfile.ts, scheduledTaskMcpProfile.ts, the delegatedFrom schema, the settings patch rule (replaceEntries), the Claude adapter's option merge and live-query key, and origin/main's Settings page (how an older web build shows such a profile).
checks: ran the 6 changed test files at this head: 210 passed. Removed 8 fix lines one at a time, each turned its test red: isWithinMcpProfile's builtinTools compare, cutTo's child-or-parent, isEveryMcpTool's builtinTools check, the turn-check refusal, the Codex goal-turn refusal, the plan key's builtinTools part, the PreToolUse guard, and draftOf keeping the box ticked.
state: profile edited while a thread runs: the running turn keeps its process; the next turn reads the profile again, and on Claude the plan key changes, so a fresh process opens with no built-in tools (never a reused one); on Codex and other wrapped drivers the next start, resume or compaction is refused, and a turn Codex starts for a goal is interrupted. Field added or removed on a running thread: same path, from the next turn. Old profiles without the field: read as before, plan key and resolver output unchanged, saved back without the field. A broken value ("some", false, a list): the profile and a carried task both refuse, never widen. T3 restart mid-turn: nothing is stored; every new process and every resume reads the profile again. Delegated task, older target: a target without carry is refused before sending; a target with carry but older than this PR keeps the field (delegatedFrom.mcpProfile is a record of unknown, not a struct that strips it) and its readCarried refuses the unknown field, so the task never runs wider. Child of a child: each level is cut to its parent, and "none" from any level stays (child or parent). Settings saved by an older web build: that build reads the profile as one with a field it does not know, shows it as broken ("This version cannot read it") with Delete but no Edit button, and a new profile with the same name is refused, so it cannot save a copy without the field; a new web build talking to an older server is refused by that server's save schema. Scheduled tasks: the saved profile keeps the field (readCarried, then spread), and a run whose new thread would be wider is not run.
blocker: none
major: none
minor: launchMcpProfile.ts:94 and :131 (and scheduledTaskMcpProfile.ts:408 and :468) still say the new thread "keeps MCP servers or T3 tools" the launcher's profile does not; when the only difference is builtinTools the refusal is right but its reason names the wrong thing. Suggest "keeps MCP servers, T3 tools or built-in tools".
minor: a carry-capable target older than this PR takes the delegated task and only refuses it when its turn starts, so a dead thread is left there; a fork feature flag for builtinTools would let the sender refuse before sending. Fails closed, so not blocking.

- claudeMcpProfile.ts: the PreToolUse guard denies a tool name that is not
  a string and any error while it checks (a hook that throws counts as a
  non-blocking error and would let the call through).
- New mcpProfileWiderParts (contracts resolver): what a wider profile keeps
  that the narrower one does not ("MCP servers", "T3 tools", "built-in
  tools"). The launch, fork and scheduled-task refusals use it instead of
  always saying "MCP servers or T3 tools", so a refusal caused only by
  builtinTools says "built-in tools".
- README: builtinTools removes only the provider's own tools (restrict
  t3Tools and servers too for a really tool-less thread); a Codex goal turn
  is stopped only soon after it starts; an older machine that takes
  delegated tasks accepts the task, then refuses its turn (a thread that
  does nothing, never one with more tools).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@scuttletoby

Copy link
Copy Markdown
Owner Author

lens: code r2 · reviewer: lens agent (Opus 5.5 high) · read at: 7a15bda
verdict: safe to merge
covered: the fix commit since round 1 (1aa830b..7a15bda: claudeMcpProfile.ts guard, mcpProfileResolve.ts mcpProfileWiderParts, launchMcpProfile.ts, scheduledTaskMcpProfile.ts, mcpProfile.ts export, README, and the test changes) and the full diff against main again; every remaining caller of isWithinMcpProfile and every refusal text that named "MCP servers or T3 tools".
checks: ran the PR's 9 changed test files at this head: server 7 files 230/230 (claudeMcpProfile.adapter, codexMcpProfile, launchMcpProfile, mcpProfile, mcpProfileTurnCheck, scheduleForkMcpProfile, scheduledTaskMcpProfile), contracts mcpProfile.test.ts 42/42, web mcpProfileSettings.logic.test.ts 11/11. Read: mcpProfileWiderParts uses the same cutTo and the same three compares as isWithinMcpProfile, so it names a part exactly when that part makes the child wider, and the five refusals (launchMcpProfile.ts:99 and :136, scheduledTaskMcpProfile.ts:192, :409 and :469) all call it only after isWithinMcpProfile said false, so it is never empty there. No "MCP servers or T3 tools" text is left in source. PR body test-file count 9: matches the diff.
state: the guard: a thread from before this change whose profile has no builtinTools gets the same plan, the same plan key and no guard, so its live process is reused as before; a thread whose profile gains none keeps its running turn, and its next turn opens a fresh Claude process (the plan key holds builtin none) with tools: [], the disallowed list and the guard. A resumed session (after a restart, or a resume or compaction) opens a new process with the options read from the profile at that moment, so it gets the guard again; nothing is stored. A remote machine on an older T3: one without carried profiles is refused before sending; one with carried profiles but older than this PR reads the field as unknown and refuses the turn, so a thread that does nothing is left there, never one with tools (the README says so now); a task sent by an older T3 carries no field and gets this machine's own profile.
round 1, fixed: the guard fails closed on a tool name that is not a string (undefined, a number, null, an object) and on any error while it checks (try/catch around the whole check returns a deny), tested.
round 1, fixed: the five refusals name the real reason ("built-in tools", "MCP servers", "T3 tools", joined with "or"), tested in launch, schedule/fork and scheduled-task tests.
round 1, fixed: the README says builtinTools removes only the provider's own tools and what to restrict for a really read-only thread, that a Codex goal turn is stopped only soon after it starts, and what an older carry-capable machine does.
blocker: none
major: none
minor: one path in the guard still returns allow without looking at the tool: input.hook_event_name !== "PreToolUse" (apps/server/src/fork/claudeMcpProfile.ts:138). The guard is registered only under PreToolUse, so the SDK always sets that name today; a malformed input with the event name missing would let a non-MCP call through. tools: [] and disallowedTools stay the main barrier, so this is defence in depth only: dropping the event-name test (or denying when it is not "PreToolUse") would leave no allow path but mcp__.

@scuttletoby
scuttletoby merged commit a71d25c into main Nov 22, 2026
40 checks passed
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