fix(opencode): avoid deferred MCP search near step limit

packages/opencode/src/session/mcp-tools.ts

@@ -53,6 +53,7 @@ interface Input {
   bypassAgentCheck: boolean
   messages: SessionV1.WithParts[]
   promptOps: TaskPromptOps
+  remainingSteps?: number
 }
 
 interface DeferredToolDescriptor {
@@ -220,6 +221,7 @@ export const resolve = Effect.fn("SessionMcpTools.resolve")(function* (input: In
       : []
   const deferMcpTools =
     deferredDescriptors.length > 0 &&
+    (input.remainingSteps ?? Infinity) >= 3 &&
     Token.estimate(JSON.stringify(deferredDescriptors.map(deferredToolEstimatePayload))) >=
       MIN_DEFERRED_MCP_SCHEMA_TOKENS
 

packages/opencode/src/session/prompt.ts

@@ -1231,6 +1231,7 @@ export const layer = Layer.effect(
               bypassAgentCheck,
               messages: msgs,
               promptOps,
+              remainingSteps: Number.isFinite(maxSteps) ? maxSteps - step + 1 : undefined,
             }).pipe(
               Effect.provideService(Plugin.Service, plugin),
               Effect.provideService(Permission.Service, permission),
@@ -1265,7 +1266,9 @@ export const layer = Layer.effect(
               ...env,
               ...instructions,
               ...(mcpInstructions ? [mcpInstructions] : []),
-              ...(tools.search_deferred_tools && tools.call_deferred_tool ? [SessionTools.DEFERRED_TOOL_SYSTEM_PROMPT] : []),
+              ...(tools.search_deferred_tools && tools.call_deferred_tool
+                ? [SessionTools.DEFERRED_TOOL_SYSTEM_PROMPT]
+                : []),
               ...(skills ? [skills] : []),
             ]
             const format = lastUser.format ?? { type: "text" as const }

packages/opencode/src/session/tools.ts

@@ -28,6 +28,7 @@ export const resolve = Effect.fn("SessionTools.resolve")(function* (input: {
   bypassAgentCheck: boolean
   messages: SessionV1.WithParts[]
   promptOps: TaskPromptOps
+  remainingSteps?: number
 }) {
   const tools: Record<string, Tool> = {}
   const run = yield* EffectBridge.make()

packages/opencode/test/session/tools.test.ts

@@ -119,7 +119,7 @@ const belowThresholdIt = makeIt({
   queryDescription: "Natural language analytics query",
 })
 
-function resolveTools() {
+function resolveTools(input: { remainingSteps?: number } = {}) {
   return SessionTools.resolve({
     agent,
     model,
@@ -128,6 +128,7 @@ function resolveTools() {
     bypassAgentCheck: false,
     messages: [],
     promptOps,
+    remainingSteps: input.remainingSteps,
   })
 }
 
@@ -172,4 +173,12 @@ describe("session.tools", () => {
       expect(Object.keys(tools).sort()).toEqual(["posthog_feature_flags", "posthog_query_trends"])
     }),
   )
+
+  deferredIt.instance("keeps MCP tools direct when the remaining step budget is too small", () =>
+    Effect.gen(function* () {
+      const tools = yield* resolveTools({ remainingSteps: 2 })
+
+      expect(Object.keys(tools).sort()).toEqual(["posthog_feature_flags", "posthog_query_trends"])
+    }),
+  )
 })