[ramantehlan]

Summary

A TrueFoundry-mode turn can send x-tfg-tools as a JSON array of tool definitions (name, description, parameters). Those tools mount on the root agent for that turn. The header is not stored, child threads do not get the tools, and a secret value never enters the harness. Without a host form for ask_user_secret, the composer does not accept a typed secret.

Closes #

Changes

• Parse x-tfg-tools as tool definitions and reject a bad payload, a reserved name, or use outside TrueFoundry mode.
• Mount the definitions as client-side tools on the root thread only.
• Hide a pending ask_user_secret card in live chat. If no host secret form is registered, the composer shows a notice instead of a plaintext answer.

How was this tested?

• pnpm --filter @truefoundry/trueforge exec jest --config jest.unit.config.cjs -- tests/unit/truefoundry/tfgTools.test.ts tests/unit/truefoundry/TrueFoundryTurnResourceResolver.test.ts
• pnpm --filter @truefoundry/trueforge-ui exec vitest run test/hooks/useComposerPauseView.test.tsx test/containers/AskUserContainer.test.tsx test/containers/ComposerContainer.test.tsx test/containers/ToolCallContainer.test.tsx
• pnpm exec eslint on the changed source files with --max-warnings=0

Checklist

• I have read the contributing guidelines
• pnpm build, pnpm test, pnpm typecheck, pnpm lint:ci, and pnpm format:check pass locally
• Tests added/updated where it makes sense
• No hand-edits to generated code (packages/trueforge-sdk, python/trueforge_sdk, .github/fern/openapi/openapi.json, docs/openapi.json). Fork PRs omit SDK regen; maintainers regenerate after merge.
• Docs / .env.example updated if configuration or behavior changed

---

Note

Medium Risk
Adds a new per-turn tool surface on the main agent thread with client-side execution semantics; validation and TrueFoundry-only gating limit exposure, but tool metadata affects what the model can invoke.

Overview
TrueFoundry-mode HTTP turns can now send x-tfg-tools: a JSON array of MCP tool definitions (inputSchema, optional outputSchema and annotations). The server parses and validates the header before a turn id is minted, rejects use outside TrueFoundry mode, and does not persist it (resumed turns must resend the header). Schedule runs omit the header and mount nothing.

Parsed tools become client-side system tools on the root agent thread only via a new rootCapabilities hook on TurnResourceResolver; sub-agents do not inherit them. Server-side execution returns a client-side-required response instead of running the tool in the harness.

LocalToolMCP.listTools now forwards outputSchema and annotations so discovery and selector policy match full tool metadata (needed for tools like ask_user_secret).

^{Reviewed by Cursor Bugbot for commit 80830a7. Bugbot is set up for automated code reviews on this repo. Configure here.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 80830a7

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@truefoundry/trueforge	Patch
@truefoundry/trueforge-core	Patch

Not sure what this means? Click here to learn what changesets are.

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

[cursor]

Stale Bugbot comment from a previous run.

[chiragjn]

Keeping it approved

[qodex-ai]

Inline findings below. See the walkthrough comment for the summary.

[qodex-ai]

Qodex review

(no summary)

Effort: ●●●○○ (3/5) · No findings worth raising. The diff reads clean.

Since last review: 0 addressed, 0 new.

Scope: the changes since the last review (delta: only what changed since the previously reviewed commit bee24f3 is reviewed; findings are anchored on the whole change).

Qodex review threads: 0 open, 1 resolved by Qodex, 2 resolved by a reviewer.

Walkthrough

What Qodex checked

Lenses (openqodex review with checked answers, all dimensions)

• Bugs and correctness
• Security (auth, injection, SSRF, secrets, headers)
• Performance regressions
• Maintainability
• Style and consistency

Scanners

• Scanners (none fit the changed files)
• 0 scanner candidates raised or dropped by the reviewer

Quality filters

• PR description: adequate (present: length, checklist; missing: issue link)
• Per-category confidence floor (bug/security/performance 0.7, maintainability 0.71, style 0.75)
• Severity threshold from .qodex.yaml: minor
• Path excludes (none configured in .qodex.yaml)
• Disabled rules (none configured in .qodex.yaml)

Verification (M1b probes against PR preview)

• Preview deployment discovered (no successful deploy for this commit)
• Probes (skipped, no preview to probe)

Cross-review dedup

• Delta review: delta: only what changed since the previously reviewed commit bee24f3 is reviewed; findings are anchored on the whole change
• Carry-overs (no findings from earlier reviews still present)

Output

• Walkthrough comment posted
• Inline comments (no in-diff findings to attach)

---

Reviewer: 0 tool calls served, 0 model calls, 0 correction rounds, 0.0s. The library does not report tool calls asked apart from those it served, or a step cap.
Reviewed by Qodex · 9.3s

Every dimension is reviewed. Bugs, security, and performance post inline; low-severity style and convention notes are collected in the group above rather than dropped. Mark a finding resolved or flag a false positive in the Qodex Pull Requests view.

[qodex-ai]

Inline findings below. See the walkthrough comment for the summary.

[qodex-ai]

Inline findings below. See the walkthrough comment for the summary.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit bee24f3. Configure here.}