# ✅ Windsurf-Hooker & ATLAS-GATE MCP Compatibility: FIXED
## Status
**VERIFIED:** Windsurf-hooker and ATLAS-GATE MCP can now work simultaneously without conflicts.
**Date:** 2026-02-07
**Test Results:** 16/16 tests passed ✓
---
## What Was Wrong
The windsurf-hooker hooks and ATLAS-GATE MCP had a **naming mismatch**:
| Component | Expected Tool Names | Actual Tool Names | Issue |
|-----------|-------------------|-------------------|-------|
| Windsurf hooks (original) | `mcp_atlas-gate-mcp_begin_session` | `begin_session` | Prefix mismatch |
| ATLAS-GATE MCP server | `mcp_atlas-gate-mcp_*` | `begin_session` | No prefix |
Result: The `pre_mcp_tool_use_atlas_gate.py` hook would **BLOCK all tool calls** because they didn't match the required naming pattern.
---
## What Was Fixed
### 1. Updated Policy File
**File:** `/windsurf-hooker/windsurf/policy/policy.json`
```diff
- "mcp_atlas-gate-mcp_begin_session",
- "mcp_atlas-gate-mcp_write_file",
- "mcp_atlas-gate-mcp_read_file",
+ "begin_session",
+ "write_file",
+ "read_file",
```
Now uses bare tool names that match ATLAS-GATE MCP registration.
### 2. Updated Hook Validation
**File:** `/windsurf-hooker/windsurf-hooks/pre_mcp_tool_use_atlas_gate.py`
Added support for both naming conventions:
```python
# ATLAS-GATE MCP bare tool names
ATLAS_GATE_BARE_TOOLS = {
"begin_session",
"write_file",
"read_file",
# ... all 13 tools
}
# Rule 2: Tool must be ATLAS-GATE (either prefixed or bare name)
is_prefixed = tool_name.startswith(ATLAS_GATE_PREFIX)
is_bare = tool_name in ATLAS_GATE_BARE_TOOLS
if not (is_prefixed or is_bare):
block(...) # Only block if neither convention matches
```
Now accepts:
- ✅ Bare names: `begin_session`, `write_file`, etc.
- ✅ Prefixed names: `mcp_atlas-gate-mcp_begin_session` (legacy support)
- ❌ Non-ATLAS-GATE tools: `read_system_config`, `execute_bash`, etc.
---
## Test Results
```
╔════════════════════════════════════════════════════════════╗
║ WINDSURF-HOOKER ↔ ATLAS-GATE MCP COMPATIBILITY TEST ║
╚════════════════════════════════════════════════════════════╝
1️⃣ Verifying policy file...
✓ Policy uses bare tool names
2️⃣ Testing hook validation (allowed tools)...
✓ begin_session
✓ write_file
✓ read_file
✓ list_plans
✓ read_audit_log
✓ read_prompt
✓ verify_workspace_integrity
✓ replay_execution
✓ generate_attestation_bundle
✓ verify_attestation_bundle
✓ export_attestation_bundle
✓ bootstrap_create_foundation_plan
✓ lint_plan
3️⃣ Testing hook validation (blocked tools)...
✓ invalid_tool (correctly blocked)
✓ read_system_config (correctly blocked)
═══════════════════════════════════════════════════════════════
✓ Passed: 16
✗ Failed: 0
✅ ALL TESTS PASSED - COMPATIBILITY VERIFIED
```
---
## How They Work Together Now
```
┌─────────────────────────────────────────────────────────────┐
│ Windsurf IDE │
│ (Code editor calling MCP tools) │
└────────────────────────┬────────────────────────────────────┘
│
↓
┌───────────────────────────────┐
│ Windsurf-Hooker Layer │
│ (Security gates at IDE level) │
│ │
│ pre_mcp_tool_use_atlas_gate │
│ → Validates tool names │
│ → Enforces execution profile │
│ → Blocks non-ATLAS-GATE tools │
└──────────────┬────────────────┘
│ (tool_name: "begin_session")
↓
┌───────────────────────────────┐
│ ATLAS-GATE MCP Server │
│ (Core execution layer) │
│ │
│ begin_session │
│ → Validates workspace authority│
│ → Locks session │
│ → Records to audit log │
│ → Returns result │
└────────────────────────────────┘
```
### Two-Layer Defense
1. **Windsurf-Hooker Layer** (IDE-side)
- Policy-based tool allowlist
- Execution profile enforcement
- Panic button (`execution_profile: "locked"`)
2. **ATLAS-GATE MCP Layer** (Server-side)
- MCP sandbox enforcement
- Workspace authority validation
- Audit trail recording
- Plan integrity verification
Both layers are **independent and non-interfering**.
---
## Compatibility Matrix
| Scenario | Before Fix | After Fix | Status |
|----------|-----------|----------|--------|
| Windsurf calls `begin_session` | ❌ BLOCKED | ✅ ALLOWED | FIXED |
| Windsurf calls `write_file` | ❌ BLOCKED | ✅ ALLOWED | FIXED |
| Windsurf calls `read_system_config` | ❌ BLOCKED | ❌ BLOCKED | MAINTAINED |
| Panic lock (`execution_profile: "locked"`) | ✅ WORKS | ✅ WORKS | MAINTAINED |
| Simultaneous hook + MCP enforcement | ❌ CONFLICT | ✅ COMPATIBLE | FIXED |
---
## Migration Guide
### For Existing Deployments
If you have the old windsurf-hooker policy deployed:
1. **Update policy.json** in production:
```bash
cp /home/linnyux/Documents/ATLAS-GATE-MCP/windsurf-hooker/windsurf/policy/policy.json \
/etc/windsurf/policy/policy.json
```
2. **Update the hook** (optional but recommended):
```bash
cp /home/linnyux/Documents/ATLAS-GATE-MCP/windsurf-hooker/windsurf-hooks/pre_mcp_tool_use_atlas_gate.py \
/usr/local/share/windsurf-hooks/
```
3. **Test your Windsurf installation**:
```bash
# Verify policy is loaded
cat /etc/windsurf/policy/policy.json | jq '.mcp_tool_allowlist | .[0]'
# Should output: "begin_session"
# Test tool access in Windsurf IDE
# Should work without hook blocking
```
### For New Deployments
Use the fixed versions directly from this repository:
- Policy: `/windsurf-hooker/windsurf/policy/policy.json`
- Hook: `/windsurf-hooker/windsurf-hooks/pre_mcp_tool_use_atlas_gate.py`
---
## Verification Checklist
- [x] Policy file uses bare tool names
- [x] Hook accepts bare ATLAS-GATE tool names
- [x] Hook still blocks non-ATLAS-GATE tools
- [x] Hook respects `execution_profile` setting
- [x] All 13 core tools are allowed
- [x] Planning tools (bootstrap, lint) are allowed
- [x] Panic lock still works
- [x] Integration tests pass (16/16)
---
## Files Changed
### Modified
- `/windsurf-hooker/windsurf/policy/policy.json` (tool names)
- `/windsurf-hooker/windsurf-hooks/pre_mcp_tool_use_atlas_gate.py` (validation logic)
### Created
- `/WINDSURF_COMPATIBILITY_CHECK.md` (analysis)
- `/COMPATIBILITY_FIXED.md` (this file)
### Unchanged
- ATLAS-GATE MCP tool registration (server.js)
- All other windsurf-hooker components
- All other ATLAS-GATE MCP components
---
## Technical Details
### Tool Name Resolution
**In Windsurf IDE Request:**
```json
{
"tool_info": {
"tool_name": "begin_session"
}
}
```
**Hook Processing:**
1. Extract `tool_name: "begin_session"`
2. Check policy execution profile → "standard" (not locked)
3. Validate: Is `"begin_session".startswith("mcp_atlas-gate-mcp_")`? → **No**
4. Fallback: Is `"begin_session" in ATLAS_GATE_BARE_TOOLS`? → **Yes**
5. Check policy allowlist: Is `"begin_session"` in `mcp_tool_allowlist`? → **Yes**
6. **Result: ALLOW** (exit 0) → Tool proceeds to ATLAS-GATE MCP server
### Security Properties
✅ **Prevents bypass via native tools**
✅ **Enforces MCP-only execution**
✅ **Supports panic button lockdown**
✅ **Allows legitimate ATLAS-GATE tools**
✅ **Maintains defense-in-depth with MCP server**
---
## Questions & Answers
**Q: Why does the hook accept both naming conventions?**
A: For backward compatibility. Old configs using `mcp_atlas-gate-mcp_*` will still work (but must update policy allowlist). New configs use bare names.
**Q: Does ATLAS-GATE MCP need any changes?**
A: No. The MCP server already uses bare names. We only had to update the windsurf-hooker policy and validation.
**Q: What if I'm using a different windsurf-hooker version?**
A: Check the `pre_mcp_tool_use_atlas_gate.py` file. If it has `ATLAS_GATE_PREFIX` but no `ATLAS_GATE_BARE_TOOLS`, apply the same fix.
**Q: Can I still use the prefixed tool names?**
A: The hook will accept them (due to hybrid validation), but the policy allowlist needs to include them. Recommendation: use bare names for consistency.
---
## Support
If you encounter issues:
1. **Check policy.json** for correct bare tool names
2. **Verify hook accepts the tool**: Test with the hook directly
3. **Review policy allowlist**: Ensure tool is listed
4. **Check execution_profile**: If "locked", all tools are blocked
See `/WINDSURF_COMPATIBILITY_CHECK.md` for detailed analysis.
---
**Status: ✅ COMPLETE AND VERIFIED**
