ref(tests): Remove direct handler fallback path

Require tool handlers to receive an explicit ToolHandlerContext instead of
supporting a no-context test response path. Update unit tests to use the
shared callHandler helper so tests provide context explicitly.

Remove the env-driven MCP next-step fallback test because MCP output should
be verified through the MCP boundary, not by forcing runtime state in handler
scaffolding. Document the no-fallback rule in AGENTS.md and CLAUDE.md.

Co-Authored-By: Codex <codex@openai.com>

Author: cameroncooke

AGENTS.md

@@ -47,6 +47,7 @@ ESM TypeScript project (`type: module`). Key layers:
 - **NEVER use inline imports** - no `await import("./foo.js")`, no `import("pkg").Type` in type positions, no dynamic imports for types. Always use standard top-level imports.
 - NEVER remove or downgrade code to fix type errors from outdated dependencies; upgrade the dependency instead
 - Always ask before removing functionality or code that appears to be intentional
+- Do not add fallback behavior by default. If required context, configuration, runtime state, or dependencies are missing, fail loudly and fix the caller/setup instead of silently switching to an alternate path. Add a fallback only when explicitly requested or when it is a documented product requirement.
 - Follow TypeScript best practices
 
 ## Import Conventions

CLAUDE.md

@@ -6,6 +6,7 @@
 - **NEVER use inline imports** - no `await import("./foo.js")`, no `import("pkg").Type` in type positions, no dynamic imports for types. Always use standard top-level imports.
 - NEVER remove or downgrade code to fix type errors from outdated dependencies; upgrade the dependency instead
 - Always ask before removing functionality or code that appears to be intentional
+- Do not add fallback behavior by default. If required context, configuration, runtime state, or dependencies are missing, fail loudly and fix the caller/setup instead of silently switching to an alternate path. Add a fallback only when explicitly requested or when it is a documented product requirement.
 - Follow TypeScript best practices
 
 ## Commands

src/mcp/tools/coverage/__tests__/get_coverage_report.test.ts

@@ -11,7 +11,7 @@ import {
   get_coverage_reportLogic,
   createGetCoverageReportExecutor,
 } from '../get_coverage_report.ts';
-import { allText, runLogic, runToolLogic } from '../../../../test-utils/test-helpers.ts';
+import { allText, runLogic, runToolLogic, callHandler} from '../../../../test-utils/test-helpers.ts';
 
 
 
@@ -99,7 +99,7 @@ describe('get_coverage_report', () => {
       __setTestCommandExecutorOverride(mockExecutor);
       __setTestFileSystemExecutorOverride(missingFs);
 
-      const result = await handler({ xcresultPath: '/tmp/missing.xcresult', showFiles: false });
+      const result = await callHandler(handler, { xcresultPath: '/tmp/missing.xcresult', showFiles: false });
 
       expect(result.isError).toBe(true);
       const text = allText(result);
@@ -120,7 +120,7 @@ describe('get_coverage_report', () => {
       __setTestCommandExecutorOverride(mockExecutor);
       __setTestFileSystemExecutorOverride(existingFs);
 
-      const result = await handler({ xcresultPath: '/tmp/test.xcresult' });
+      const result = await callHandler(handler, { xcresultPath: '/tmp/test.xcresult' });
 
       expect(result.isError).toBeUndefined();
       expect(commands).toHaveLength(1);

src/mcp/tools/coverage/__tests__/get_file_coverage.test.ts

@@ -15,7 +15,7 @@ import {
   get_file_coverageLogic,
   createGetFileCoverageExecutor,
 } from '../get_file_coverage.ts';
-import { allText, runLogic, runToolLogic } from '../../../../test-utils/test-helpers.ts';
+import { allText, runLogic, runToolLogic, callHandler} from '../../../../test-utils/test-helpers.ts';
 
 
 
@@ -98,7 +98,7 @@ describe('get_file_coverage', () => {
       __setTestCommandExecutorOverride(mockExecutor);
       __setTestFileSystemExecutorOverride(missingFs);
 
-      const result = await handler({
+      const result = await callHandler(handler, {
         xcresultPath: '/tmp/missing.xcresult',
         file: 'ViewModel.swift',
         showLines: false,
@@ -123,7 +123,7 @@ describe('get_file_coverage', () => {
       __setTestCommandExecutorOverride(mockExecutor);
       __setTestFileSystemExecutorOverride(existingFs);
 
-      const result = await handler({ xcresultPath: '/tmp/test.xcresult', file: 'ViewModel.swift' });
+      const result = await callHandler(handler, { xcresultPath: '/tmp/test.xcresult', file: 'ViewModel.swift' });
 
       expect(result.isError).toBeUndefined();
       expect(commands).toHaveLength(1);

src/mcp/tools/debugging/__tests__/debugging-tools.test.ts

@@ -50,7 +50,12 @@ import {
   handler as variablesHandler,
   debug_variablesLogic,
 } from '../debug_variables.ts';
-import { allText, runLogic, runToolLogic } from '../../../../test-utils/test-helpers.ts';
+import {
+  allText,
+  runLogic,
+  runToolLogic,
+  callHandler,
+} from '../../../../test-utils/test-helpers.ts';
 
 function createMockBackend(overrides: Partial<DebuggerBackend> = {}): DebuggerBackend {
   return {
@@ -125,7 +130,7 @@ describe('debug_attach_sim', () => {
 
   describe('Handler Requirements', () => {
     it('should return error when no session defaults for simulator', async () => {
-      const result = await attachHandler({
+      const result = await callHandler(attachHandler, {
         bundleId: 'com.test.app',
       });
 
@@ -143,7 +148,7 @@ describe('debug_attach_sim', () => {
         bundleId: 'com.default.app',
       });
 
-      const result = await attachHandler({ pid: 1234 });
+      const result = await callHandler(attachHandler, { pid: 1234 });
 
       expect(result.isError).toBeFalsy();
       const text = result.content[0].text;
@@ -155,7 +160,7 @@ describe('debug_attach_sim', () => {
       __setTestDebuggerToolContextOverride(createTestContext());
       sessionStore.setDefaults({ simulatorId: 'test-sim-uuid' });
 
-      const result = await attachHandler({
+      const result = await callHandler(attachHandler, {
         pid: 1234,
         bundleId: 'com.test.app',
       });

src/mcp/tools/device/__tests__/build_device.test.ts

@@ -2,16 +2,13 @@ import { describe, it, expect, beforeEach } from 'vitest';
 import { computeScopedDerivedDataPath } from '../../../../utils/derived-data-path.ts';
 import * as z from 'zod';
 import { createMockExecutor } from '../../../../test-utils/mock-executors.ts';
-import { expectPendingBuildResponse, runToolLogic } from '../../../../test-utils/test-helpers.ts';
+import {
+  expectPendingBuildResponse,
+  runToolLogic,
+  callHandler,
+} from '../../../../test-utils/test-helpers.ts';
 import { schema, handler, buildDeviceLogic } from '../build_device.ts';
 import { sessionStore } from '../../../../utils/session-store.ts';
-import type { CommandExecutor } from '../../../../utils/execution/index.ts';
-
-const runHandlerWithExecutor = handler as unknown as (
-  args: Record<string, unknown>,
-  executor: CommandExecutor,
-) => Promise<{ isError?: boolean }>;
-
 function createSpyExecutor(): {
   commandCalls: Array<{ args: string[]; logPrefix?: string }>;
   executor: ReturnType<typeof createMockExecutor>;
@@ -58,7 +55,7 @@ describe('build_device plugin', () => {
 
   describe('XOR Validation', () => {
     it('should error when neither projectPath nor workspacePath provided', async () => {
-      const result = await handler({
+      const result = await callHandler(handler, {
         scheme: 'MyScheme',
       });
 
@@ -68,7 +65,7 @@ describe('build_device plugin', () => {
     });
 
     it('should error when both projectPath and workspacePath provided', async () => {
-      const result = await handler({
+      const result = await callHandler(handler, {
         projectPath: '/path/to/MyProject.xcodeproj',
         workspacePath: '/path/to/MyProject.xcworkspace',
         scheme: 'MyScheme',
@@ -82,7 +79,7 @@ describe('build_device plugin', () => {
 
   describe('Parameter Validation (via Handler)', () => {
     it('should return Zod validation error for missing scheme', async () => {
-      const result = await handler({
+      const result = await callHandler(handler, {
         projectPath: '/path/to/MyProject.xcodeproj',
       });
 
@@ -92,7 +89,7 @@ describe('build_device plugin', () => {
     });
 
     it('should return Zod validation error for invalid parameter types', async () => {
-      const result = await handler({
+      const result = await callHandler(handler, {
         projectPath: 123, // Should be string
         scheme: 'MyScheme',
       });
@@ -220,26 +217,18 @@ describe('build_device plugin', () => {
         scheme: 'MyScheme',
       });
 
-      const result = await runHandlerWithExecutor({ platform: 'tvOS' }, spy.executor);
-
-      expect(result.isError).toBeUndefined();
-      expect(spy.commandCalls).toHaveLength(1);
-      expect(spy.commandCalls[0].args).toContain('generic/platform=tvOS');
-      expect(spy.commandCalls[0].logPrefix).toBe('tvOS Device Build');
-    });
-
-    it('should normalize simulator session platforms for device builds', async () => {
-      const spy = createSpyExecutor();
-
-      sessionStore.setDefaults({
-        projectPath: '/path/to/MyProject.xcodeproj',
-        scheme: 'MyScheme',
-        platform: 'tvOS Simulator',
-      });
-
-      const result = await runHandlerWithExecutor({}, spy.executor);
+      const { result } = await runToolLogic(() =>
+        buildDeviceLogic(
+          {
+            projectPath: '/path/to/MyProject.xcodeproj',
+            scheme: 'MyScheme',
+            platform: 'tvOS',
+          },
+          spy.executor,
+        ),
+      );
 
-      expect(result.isError).toBeUndefined();
+      expect(result.isError()).toBe(false);
       expect(spy.commandCalls).toHaveLength(1);
       expect(spy.commandCalls[0].args).toContain('generic/platform=tvOS');
       expect(spy.commandCalls[0].logPrefix).toBe('tvOS Device Build');

src/mcp/tools/device/__tests__/build_run_device.test.ts

@@ -5,7 +5,11 @@ import {
   createMockFileSystemExecutor,
   createMockExecutor,
 } from '../../../../test-utils/mock-executors.ts';
-import { runToolLogic, type MockToolHandlerResult } from '../../../../test-utils/test-helpers.ts';
+import {
+  runToolLogic,
+  type MockToolHandlerResult,
+  callHandler,
+} from '../../../../test-utils/test-helpers.ts';
 import type { CommandExecutor } from '../../../../utils/execution/index.ts';
 import { sessionStore } from '../../../../utils/session-store.ts';
 import { schema, handler, build_run_deviceLogic } from '../build_run_device.ts';
@@ -50,11 +54,14 @@ describe('build_run_device tool', () => {
 
   describe('Handler Requirements', () => {
     it('requires scheme + deviceId and project/workspace via handler', async () => {
-      const missingAll = await handler({});
+      const missingAll = await callHandler(handler, {});
       expect(missingAll.isError).toBe(true);
       expect(missingAll.content[0].text).toContain('Provide scheme and deviceId');
 
-      const missingSource = await handler({ scheme: 'MyApp', deviceId: 'DEVICE-UDID' });
+      const missingSource = await callHandler(handler, {
+        scheme: 'MyApp',
+        deviceId: 'DEVICE-UDID',
+      });
       expect(missingSource.isError).toBe(true);
       expect(missingSource.content[0].text).toContain('Provide a project or workspace');
     });

src/mcp/tools/device/__tests__/get_device_app_path.test.ts

@@ -12,7 +12,7 @@ import {
   createGetDeviceAppPathExecutor,
 } from '../get_device_app_path.ts';
 import { sessionStore } from '../../../../utils/session-store.ts';
-import { runLogic } from '../../../../test-utils/test-helpers.ts';
+import { runLogic, callHandler } from '../../../../test-utils/test-helpers.ts';
 
 describe('get_device_app_path plugin', () => {
   beforeEach(() => {
@@ -41,7 +41,7 @@ describe('get_device_app_path plugin', () => {
 
   describe('XOR Validation', () => {
     it('should error when neither projectPath nor workspacePath provided', async () => {
-      const result = await handler({
+      const result = await callHandler(handler, {
         scheme: 'MyScheme',
       });
       expect(result.isError).toBe(true);
@@ -50,7 +50,7 @@ describe('get_device_app_path plugin', () => {
     });
 
     it('should error when both projectPath and workspacePath provided', async () => {
-      const result = await handler({
+      const result = await callHandler(handler, {
         projectPath: '/path/to/project.xcodeproj',
         workspacePath: '/path/to/workspace.xcworkspace',
         scheme: 'MyScheme',
@@ -63,7 +63,7 @@ describe('get_device_app_path plugin', () => {
 
   describe('Handler Requirements', () => {
     it('should require scheme when missing', async () => {
-      const result = await handler({
+      const result = await callHandler(handler, {
         projectPath: '/path/to/project.xcodeproj',
       });
       expect(result.isError).toBe(true);
@@ -74,7 +74,7 @@ describe('get_device_app_path plugin', () => {
     it('should require project or workspace when scheme default exists', async () => {
       sessionStore.setDefaults({ scheme: 'MyScheme' });
 
-      const result = await handler({});
+      const result = await callHandler(handler, {});
       expect(result.isError).toBe(true);
       expect(result.content[0].text).toContain('Provide a project or workspace');
     });

src/mcp/tools/device/__tests__/install_app_device.test.ts

@@ -3,7 +3,7 @@ import * as z from 'zod';
 import { createMockExecutor } from '../../../../test-utils/mock-executors.ts';
 import { schema, handler, install_app_deviceLogic } from '../install_app_device.ts';
 import { sessionStore } from '../../../../utils/session-store.ts';
-import { allText, runLogic } from '../../../../test-utils/test-helpers.ts';
+import { allText, runLogic, callHandler } from '../../../../test-utils/test-helpers.ts';
 
 describe('install_app_device plugin', () => {
   beforeEach(() => {
@@ -12,7 +12,7 @@ describe('install_app_device plugin', () => {
 
   describe('Handler Requirements', () => {
     it('should require deviceId when session defaults are missing', async () => {
-      const result = await handler({
+      const result = await callHandler(handler, {
         appPath: '/path/to/test.app',
       });
 

src/mcp/tools/device/__tests__/launch_app_device.test.ts

@@ -6,7 +6,7 @@ import {
 } from '../../../../test-utils/mock-executors.ts';
 import { schema, handler, launch_app_deviceLogic } from '../launch_app_device.ts';
 import { sessionStore } from '../../../../utils/session-store.ts';
-import { allText, runLogic } from '../../../../test-utils/test-helpers.ts';
+import { allText, runLogic, callHandler } from '../../../../test-utils/test-helpers.ts';
 
 describe('launch_app_device plugin (device-shared)', () => {
   beforeEach(() => {
@@ -36,7 +36,7 @@ describe('launch_app_device plugin (device-shared)', () => {
 
   describe('Handler Requirements', () => {
     it('should require deviceId and bundleId when not provided', async () => {
-      const result = await handler({});
+      const result = await callHandler(handler, {});
 
       expect(result.isError).toBe(true);
       expect(result.content[0].text).toContain('Missing required session defaults');