feat(optimize): mcp-deferral-gaps finding family (part 1 of #614)#630
Open
AVSRPA1KR wants to merge 1 commit into
Open
feat(optimize): mcp-deferral-gaps finding family (part 1 of #614)#630AVSRPA1KR wants to merge 1 commit into
AVSRPA1KR wants to merge 1 commit into
Conversation
Add three read-only detectors for MCP tool-def deferral coverage gaps: - mcp-deferral-off: sessions carrying MCP tool-def overhead with zero ToolSearch invocations and no deferred_tools_delta inventory across the window. Cause attribution, each with its own message and fix: stale ENABLE_TOOL_SEARCH=false (settings env, any scope, or shell profile), non-first-party ANTHROPIC_BASE_URL (reported as unknown proxy — never assumes capability), Vertex AI config, all observed Claude Code versions predating default-on tool search (v2.1.7), or a generic deferral-appears-inactive fallback. - mcp-alwaysload-hygiene: alwaysLoad-pinned servers whose observed call rate is below 1 call per 5 sessions (named constant). Notes the 5s startup-blocking cost of alwaysLoad in the explanation. - mcp-defer-threshold: ENABLE_TOOL_SEARCH=auto/auto:N overrides whose threshold the estimated def volume never reaches, so tools load upfront; recommends the tightest auto:N that would defer. Detection only: no FindingApply payloads, no act-layer changes, no file mutation. Users without deferral gaps see zero new output — deferral-active evidence (ToolSearch calls or inventory) suppresses the findings, and each detector gates on conservative named thresholds. Config readers take an injectable homeDir (PlanContext style) for hermetic tests. Discrepancies vs the design notes, codebase/live-docs win: - The Claude Code changelog records default-on (2.1.7), not first ship, so the version cause uses the default-on boundary. - Per-tool "anthropic/alwaysLoad" lives in server-served tool _meta, not static config; server-level only, limitation documented. - Live docs confirm auto default threshold 10% of context window and the alwaysLoad v2.1.121+ requirement. Refs getagentseal#614
AVSRPA1KR
force-pushed
the
submit/mcp-deferral-gaps
branch
from
7333604 to
077cce5
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Implements part 1 (detection) of the deferral-coverage design, #614.
Adds a read-only
mcp-deferral-gapsfinding family tooptimize— three detectors, no file mutation anywhere in this PR:mcp-deferral-off— sessions carrying MCP tool-def overhead with zeroToolSearchinvocations and nodeferred_tools_deltainventory across the window. Cause attribution, each with its own message and fix: staleENABLE_TOOL_SEARCH=false(settings env, any scope, or shell profile), non-first-partyANTHROPIC_BASE_URL(reported as unknown proxy — never assumes capability), Vertex AI, all observed Claude Code versions predating default-on tool search (v2.1.7), or a generic fallback.mcp-alwaysload-hygiene—alwaysLoad-pinned servers whose observed call rate is below 1 call / 5 sessions. Notes the 5s startup-blocking cost.mcp-defer-threshold—ENABLE_TOOL_SEARCH=auto:Noverrides whose threshold the estimated def volume never reaches; recommends the tightestauto:Nthat would defer.Detection only — no
FindingApplypayloads, noactchanges, no file mutation. Zero new output for users without deferral gaps (deferral-active evidence suppresses the findings). 32 fixture-based unit tests; config readers take an injectablehomeDirfor hermetic tests.Live-docs discrepancies noted in the commit body (changelog records default-on at v2.1.7 not first-ship; per-tool
anthropic/alwaysLoadlives in server-served_meta, so server-level only).Refs #614