test: add comprehensive test coverage for MCP allowHeadless feature

TEST_IMPROVEMENTS.md

@@ -0,0 +1,90 @@
+# Test Improvements for MCP Headless Mode (PR #9328)
+
+## Summary
+
+This PR adds comprehensive test coverage for the `allowHeadless` feature introduced in PR #9328. The new tests ensure robust behavior of MCP tools in headless mode across various scenarios.
+
+## Test Coverage Added
+
+### 1. **Edge Cases and Error Handling** (`MCP tool edge cases and error handling`)
+
+- **Disconnected servers**: Verifies graceful handling when MCP server is disconnected
+- **Empty connections**: Tests behavior when no MCP connections are configured
+- **Empty tools array**: Ensures no errors when a server has no tools
+- **Explicit false**: Confirms tools are excluded when `allowHeadless: false` is explicit
+
+### 2. **Permission Policy Interactions** (`MCP tool permission policy interactions`)
+
+- **Wildcard exclude over allowHeadless**: Ensures wildcard excludes take precedence
+- **Specific allow vs wildcard ask**: Tests policy priority resolution
+- **allowHeadless with wildcard ask**: Verifies upgrade behavior in headless mode
+- **Wildcard ask without allowHeadless**: Confirms denial in headless mode
+- **argumentMatches with allowHeadless**: Tests argument-based permission matching
+
+### 3. **Integration Tests** (`MCP tool integration tests`)
+
+- **Mixed built-in and MCP tools**: Verifies correct filtering in headless mode
+- **Tool order preservation**: Ensures filtering maintains tool ordering
+- **Interactive to headless transition**: Tests mode switching behavior
+
+### 4. **Built-in Tool Behavior**
+
+- **Built-in tools in headless**: Confirms built-in tools work regardless of `allowHeadless`
+
+## Test Scenarios
+
+### Security-Critical Tests
+
+1. ✅ Explicit exclusions always respected (cannot be bypassed by `allowHeadless`)
+2. ✅ Wildcard excludes take precedence over `allowHeadless`
+3. ✅ Default behavior is secure (tools excluded without explicit `allowHeadless: true`)
+
+### Functionality Tests
+
+1. ✅ Tools with `allowHeadless: true` work in headless mode
+2. ✅ Tools with `allowHeadless: false` are excluded in headless mode
+3. ✅ Tools with `allowHeadless: undefined` are excluded in headless mode
+4. ✅ All MCP tools work in interactive mode regardless of `allowHeadless`
+
+### Integration Tests
+
+1. ✅ Multiple servers with different `allowHeadless` settings
+2. ✅ Built-in tools always available in headless mode
+3. ✅ Tool enumeration maintains consistent ordering
+4. ✅ Mode transitions handled correctly
+
+## Key Improvements Over Original Tests
+
+1. **Comprehensive edge case coverage**: Tests error conditions and boundary cases
+2. **Permission policy interactions**: Validates complex policy scenarios with wildcards
+3. **Integration testing**: Ensures components work together correctly
+4. **Real-world scenarios**: Tests common use cases like mixed servers
+5. **Security validation**: Explicitly tests that security cannot be bypassed
+
+## Test Organization
+
+Tests are organized into 4 logical groups:
+
+- `MCP tools in headless mode` (original tests from PR #9328)
+- `MCP tool execution permission in headless mode` (original + new built-in test)
+- `MCP tool edge cases and error handling` (new)
+- `MCP tool permission policy interactions` (new)
+- `MCP tool integration tests` (new)
+
+## Files Modified
+
+- `extensions/cli/src/stream/mcp-headless.test.ts`: Added 12 new test cases
+
+## Test Execution
+
+Run tests with:
+
+```bash
+cd extensions/cli
+npm test -- mcp-headless.test.ts
+```
+
+## Related PRs
+
+- PR #9328: Original feature implementation and documentation
+- PR #9327: Parent PR for allowHeadless feature