Repository navigation
feat(mcp)!: preload loop tools, trim schemas, and shorten errors - #4507
Conversation
Claude Code defers MCP tool schemas, so each tool a run needs costs a tool search turn. Mark the 'loop' framework tier (open, snapshot, press, fill, back, wait, scroll, screenshot) with _meta "anthropic/alwaysLoad", and give every tool an "anthropic/searchHint" from its command text. Make the always-loaded schemas lean: debug, the MCP response controls (cost, responseLevel), and the target alias leave every tool schema. The controls become operator settings (AGENT_DEVICE_COST, AGENT_DEVICE_RESPONSE_LEVEL); mcpOutputFormat is removed. Loop tool descriptions carry their usage guidance from the command help text, batch documents its step shape with tested examples, MCP errors put the typed reason beside the code and drop the log path unless the recovery step reads it, and MCP open text drops the Session state path. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Size Report
Startup median (7 runs, lower is better):
|
There was a problem hiding this comment.
All reported issues were addressed across 59 files
Reply with feedback, questions, or to request a fix.
View guided diff | Turn on auto-fix | Re-trigger cubic
Apex Sentinel · ✅ ApproveSince the last review: 0 new · 0 still open · 1 no longer raised (1 marked fixed) No open findings. 1 finding below 💬 Talking to SentinelIn a finding's thread, reply with:
On this conversation, comment Earlier reviewsReview of
|
| Where | Finding |
|---|---|
website/docs/docs/agent-setup.md:66 |
🆕 agent-setup.md still lists screenshot among the always-loaded loop tools |
Reviewed with this repository's own Sentinel configuration (d38e35e61193).
Review of 9c4a12c4 · 14.11.2026 07:40 UTC
Apex Sentinel · 🟠 Request changes
Since the last review: 1 new · 0 still open · 0 no longer raised
1 finding(s): 1 major.
Required fixes
- Loop-tier pin test still expects 'screenshot', which the last commit reverted to 'core'
🟠 Major (1)
| Where | Finding |
|---|---|
src/__tests__/command-descriptor-parity.test.ts:301 |
🆕 Loop-tier pin test still expects 'screenshot', which the last commit reverted to 'core' |
2 new findings away from what changed since 3ede315 not shown. Comment @apex-sentinel-staging review for a full review.
Reviewed with this repository's own Sentinel configuration (d38e35e61193).
Review of 3ede3159 · 13.11.2026 19:52 UTC
Apex Sentinel · ✅ Approve
Since the last review: 0 new · 0 still open · 0 no longer raised
No open findings.
1 finding below minor hidden (user_settings.min_severity).
Reviewed with this repository's own Sentinel configuration (b68ed4bf285a).
Review of 4d365c31 · 13.11.2026 16:17 UTC
Apex Sentinel · ✅ Approve
Since the last review: 0 new · 0 still open · 0 no longer raised
No open findings.
2 findings below minor hidden (user_settings.min_severity).
Reviewed with this repository's own Sentinel configuration (cc3b99b38530).
Review of 067626d2 · 13.11.2026 15:18 UTC
Apex Sentinel · ✅ Approve
Since the last review: 0 new · 0 still open · 1 no longer raised (1 marked fixed)
No open findings.
1 finding below minor hidden (user_settings.min_severity).
Reviewed with this repository's own Sentinel configuration (cc3b99b38530).
Review of 8e043474 · 13.11.2026 15:08 UTC
Apex Sentinel · 🟠 Request changes
Since the last review: 1 new · 0 still open · 1 no longer raised (1 marked fixed)
1 finding(s): 1 major.
Required fixes
- ai-sdk default 'core' tool set now silently includes tier-less local-CLI commands
🟠 Major (1)
| Where | Finding |
|---|---|
src/ai-sdk/index.ts:104 |
🆕 ai-sdk default 'core' tool set now silently includes tier-less local-CLI commands |
1 finding below minor hidden (user_settings.min_severity).
Reviewed with this repository's own Sentinel configuration (80075b6412df).
Review of 88080f60 · 13.11.2026 14:58 UTC
Apex Sentinel · ✅ Approve
Since the last review: 1 new · 0 still open · 2 no longer raised (2 marked fixed)
1 finding(s): 1 minor.
🟡 Minor (1)
| Where | Finding |
|---|---|
packages/command-surface/src/batch/index.ts:49 |
🆕 batch's MCP description states a 60-second budget that the policy does not encode |
1 finding below minor hidden (user_settings.min_severity).
Reviewed with this repository's own Sentinel configuration (80075b6412df).
Review of 0751d1aa · 13.11.2026 14:35 UTC
Apex Sentinel · ✅ Approve
2 finding(s): 2 minor.
🟡 Minor (2)
| Where | Finding |
|---|---|
packages/command-output/src/output/error.ts:66 |
Log path suppression compares raw hint to the default hint, not the printed Next: |
packages/command-surface/src/post-action-observation-grammar.ts:32 |
settleQuietMs help drops the iOS 1500ms floor and bridge default |
1 finding below minor hidden (user_settings.min_severity).
Reviewed with this repository's own Sentinel configuration (80075b6412df).
There was a problem hiding this comment.
Apex Sentinel: 2 new findings on 0751d1a. The verdict and the full list are in the summary comment.
…rule - Settle fields state the diff is against the pre-action tree and keep the iOS 300 ms default and broad-replacement floor, tersely. - open documents initialSnapshotError on a fresh open; customActions keeps its recovery routes, with the full wording in help snapshot. - Model-facing errors keep the log path only when the code's default step reads the log (defaultHintReadsLog), and bound details.reason to one line. - batch grounds its @E12 example; searchHints carry only words the tool text lacks, enforced by a test. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
All reported issues were addressed across 33 files (changes from recent commits).
Reply with feedback, questions, or to request a fix.
View guided diff | Turn on auto-fix | Re-trigger cubic
… is absent Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
Apex Sentinel: 1 new finding on 88080f6. The verdict and the full list are in the summary comment.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
Apex Sentinel: 1 new finding on 8e04347. The verdict and the full list are in the summary comment.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
At 067626d, the agent-facing MCP error text can tell the reader to check a log while omitting the log path. In packages/command-output/src/output/error.ts:128, the "Log:" line is kept only when the hint equals the default hint for the code. Two producers pass a logPath with their own hint that names the log: packages/apple-runner/src/runner-recycle-ledger.ts:101 and packages/command-runtime/src/commands/interaction/runtime/wait-polling.ts:242. For those, the MCP text keeps "Next: Check the runner log…" and drops the path, so an agent on an iOS runner recycle failure or a wait that exhausted runner restarts has no path to read. This also contradicts the new sentence in agent-setup.md. Please make the rule "the agent text keeps the log path whenever its Next step directs the reader to a log" a declared fact, for example a typed details flag set by the default-hint path and by every producer whose hint mentions a log (a grep of hints that mention a log enumerates them), or drop the agent-only suppression and always keep the line. Please add a test with a producer hint that reads the log. Not blocking, take or leave: ai-sdk.md should say that createAgentDeviceTools calls now refuse debug and the target alias too (they go through the same executor, src/ai-sdk/index.ts:97,125), and the PR body breaking section could say so; for the agent reader, a message over 300 characters is cut with "…" and the full "Message:" line is no longer emitted (error.ts:70), so keeping it when truncated would help; the toolInputAudience comment at src/mcp/command-tools.ts:123 still says the command map is spread first, and the cost/responseLevel type checks in readClientConfig (command-tools.ts:382-405) may no longer be reachable from tool input; and the reader union in output-common.ts:45 and error.ts:36 could be one exported OutputReader type. CI is green, 22 checks with none failing at 067626d, and I did not run the suites or rebuild the tools/list byte figures locally, so those are covered only by the CI size gates. No conflicts. The earlier review threads are resolved. The log-path fix above must land before merge. |
…or text A producer hint that sends the reader to the runner or diagnostics log lost the path under the default-hint rule. Agent text now keeps the Log: line whenever a log exists and the full Message: line when the summary cuts it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Fixed in 44e7c76: the agent text now keeps the Non-blocking notes: taken — a cut summary is now followed by the full |
There was a problem hiding this comment.
All reported issues were addressed across 7 files (changes from recent commits).
Reply with feedback, questions, or to request a fix.
View guided diff | Turn on auto-fix | Re-trigger cubic
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
This PR is ready at 4d365c3. I found no new problems in the code, and the findings from the earlier review are fixed. All 22 checks pass at this commit, and no conflicts are known. I did not run the test suites or the linter. I judged the new tests from the diff, and CI is the execution evidence. No live device run is needed, because this change only affects text formatting. Nothing else must happen before merge. Not blocking: in ai-sdk.md, The review thread on the ai-sdk.md session and platform wording is fixed at this head, so you can resolve it: #4507 (comment). The "refused" wording for |
… log path Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Took both notes in 3ede315: |
|
The new head 3ede315 looks good, and the earlier clean review at 4d365c3 (#4507 (comment)) still stands. The change since then touches only two website docs files, and I found no problems in it. I read the INVALID_ARGS behavior for debug and target in the AI SDK route from the code and did not run it. All 8 remaining CI jobs are still in progress on this head, and the docs-only change cannot affect their code paths apart from the docs build. No threads are open. Once those jobs finish green, this is ready to merge. |
Benchmark runs showed that a preloaded screenshot pulls agents into a screenshot, image read and coordinate-tap detour whenever open returns before the app is ready, so it moves back to the core tier: still in the default AI SDK set, loaded on demand over MCP. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
All reported issues were addressed across 2 files (changes from recent commits).
Reply with feedback, questions, or to request a fix.
View guided diff | Turn on auto-fix | Re-trigger cubic
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* origin/main: fix(android): carry an empty text on a node labelled by its content description (#4531) fix(ios): restore the back swipe's pre-swipe still span (#4515) fix(daemon-client): type the remote daemon refusal with its dispatch fact (#4532) fix: prepare reinstall artifacts before removing apps (#4533) fix(ios): classify the keyboard dismiss refusal by what it dispatched (#4536) fix(ios): press the navigation bar back button and speed up the back swipe (#4508) refactor(gestures): one owner for the densified gesture path; drop the unproven sendevent transport (#4239) fix(host-kit): keep Linux process identity stable across clock steps (#4438) fix(ios): bound the idle wait of keyboard dismiss and keyboard enter (#4454) fix(device-selection): fail an ambiguous device request with only the tied devices (#4506)
There was a problem hiding this comment.
Apex Sentinel: 1 new finding on 9c4a12c. The verdict and the full list are in the summary comment.
…rmat the loop pin Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
Apex Sentinel: 1 new finding on 06c9d4c. The verdict and the full list are in the summary comment.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
I found no problems in the changes since the earlier review of 3ede315 (#4507 (comment)). I reviewed 83c034c, which adds 9c4a12c, 2dc0ae1, 06c9d4c and 83c034c on top of the eight commits that did not change. The parity pin no longer lists screenshot, the loop pin matches the 7 loop descriptors, and the agent-setup doc lists the 7 loop tools and says screenshot loads on first use. The three earlier inline threads are fixed at this commit, so you can resolve them: #4507 (comment) (parity pin lists screenshot), #4507 (comment) (loop pin format and count) and #4507 (comment) (agent-setup tool list). All 22 checks pass at 83c034c, and there are no conflicts. I did not run the MCP server. I read the always-loaded set from the code (command-tools.ts:194) and from the loading-meta test that CI ran. I did not reproduce the benchmark claim that a preloaded screenshot causes detours, and the change does not depend on it. Nothing else stands in the way of merging. |
Resolves the open summary conflict with #4507: keeps main's agent guidance and adds the local-iOS-simulator first-screen wait, compact enough to keep the always-loaded tools inside their 22 KB budget. Takes the review note that other devices and backends (Android included) skip the wait. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Summary
Claude Code defers MCP tool schemas: each tool a run needs costs a tool-search turn, and a failed call to an unloaded tool gets its whole schema appended. This PR cuts both costs.
_meta["anthropic/alwaysLoad"]on the new'loop'tier (part of'core'): open, snapshot, press, fill, back, wait, scroll; screenshot stays on demand, since preloading it caused detours. Every tool gets_meta["anthropic/searchHint"]from its command text.debug,cost, andresponseLevel. A newaliasaudience sends tool calls todeviceTargetinstead oftarget.batchdocuments its step shape with thehelp batchexamples.Error (CODE, reason)and one line, then the log path when one exists. MCPopendropsSession state:.tools/listBreaking changes for MCP clients
MCP tool calls are refused for
mcpOutputFormat(removed),includeCost,responseLevel,debug, andtarget; AI SDK calls refusedebugandtargetand drop the rest. For JSON text, setAGENT_DEVICE_RESPONSE_LEVELorAGENT_DEVICE_COST; for a form factor, usedeviceTarget.Validation
Focused unit suites, typecheck and lint pass; byte counts come from the built server over stdio. Not device-facing; CI owns full validation.
🤖 Generated with Claude Code
Open in [code]smith · Need help on this PR? Tag
@codesmith-botwith what you need.