Windsurf SWE-1.5 & Cascade Hooks: Complete Developer Guide

Windsurf's November 2025 updates mark a significant evolution in agentic coding capabilities. While competitors focus on integrating more frontier models, Windsurf invested in developer workflow infrastructure—Cascade Hooks for automation, Codemaps for visualization, and their proprietary SWE-1.5 model with native image understanding.

Released across versions 1.12.28 through 1.12.36, these features transform how development teams interact with AI coding assistants. Rather than treating AI as a simple autocomplete tool, Windsurf positions Cascade as a customizable workflow engine that adapts to your team's policies, compliance requirements, and development patterns.

SWE-1.5 Proprietary Model

SWE-1.5, introduced in v1.12.31 on November 13, 2025, represents Windsurf's commitment to purpose-built coding models. Unlike generic LLMs adapted for coding, SWE-1.5 was trained specifically for software engineering tasks with native multimodal capabilities.

Model Architecture

SWE-1.5 was later revealed to be powered by Zhipu AI (Z.ai), a leading Chinese AI lab. This partnership allows Windsurf to offer a competitive proprietary model while frontier models like GPT-5.1 and Claude Opus 4.5 remain available for users who prefer them.

The model family includes three variants optimized for different use cases:

• SWE-1.5: Full-capability model for complex reasoning, multi-file refactoring, and feature development
• SWE-1.5-Fast (SWE-1-lite): Optimized for speed with autocomplete and quick edits
• SWE-1-mini: Lightweight variant for simple completions, unlimited on free tier

Cascade Hooks Deep Dive

Cascade Hooks, rolled out to all tiers in v1.12.31, provide programmatic control over every AI interaction in your workflow. Unlike simple prompt templates, hooks execute custom logic at specific points in the Cascade pipeline.

Hook Types

Configuration Example

Hooks are defined in your project's .windsurf/hooks.json file:

{
  "hooks": {
    "pre_prompt": [
      {
        "name": "sanitize_secrets",
        "script": "./hooks/sanitize.ts",
        "enabled": true
      },
      {
        "name": "inject_context",
        "script": "./hooks/context.ts",
        "config": {
          "include_recent_commits": true,
          "max_files": 10
        }
      }
    ],
    "post_response": [
      {
        "name": "audit_log",
        "script": "./hooks/audit.ts",
        "destination": "s3://logs/cascade/"
      }
    ]
  }
}

Enterprise Compliance Use Cases

• SOC 2 Auditing: Capture every prompt and response with timestamps, user IDs, and project context for compliance reporting
• Data Loss Prevention: Automatically detect and redact credentials, API keys, or PII before they reach external models
• Approval Workflows: Require human approval for destructive operations like database migrations or production deployments

Codemaps & Visual Architecture

Codemaps, expanded in v1.12.28 (November 3, 2025), brings visual code architecture to Windsurf. The feature automatically generates Mermaid diagrams representing your codebase structure, making complex systems understandable at a glance.

Diagram Types

Cascade Integration

Codemaps integrates directly with Cascade chat. Ask questions like "Show me the data flow from user registration to database" and receive an interactive Mermaid diagram with explanations. Diagrams can be exported, embedded in documentation, or shared in pull requests.

Fast Context Search

Fast Context, powered by SWE-grep, is a subagent that dramatically accelerates code search during agentic workflows. Traditional search methods become bottlenecks when AI agents need to locate relevant context across large codebases—Fast Context solves this.

How It Works

When Cascade needs to understand your codebase for a task, Fast Context runs in the background, building a semantic index of relevant files. This index is cached and incrementally updated, so subsequent queries are even faster. The result: agents spend more time generating code and less time searching.

Real Agency Applications

Here's how agencies can leverage Windsurf's November features for concrete client deliverables with measurable ROI:

Getting Started

All November features are available in Windsurf v1.12.31 and later. Here's how to enable and configure each capability:

Conclusion

Windsurf's November 2025 updates shift focus from model quantity to workflow quality. SWE-1.5's image understanding, Cascade Hooks' automation capabilities, Codemaps' visual documentation, and Fast Context's search performance create an integrated development environment that adapts to enterprise requirements.

For agencies managing multiple client projects with varying compliance needs, these features provide the customization layer that generic AI assistants lack. The ability to define hooks, enforce policies, and generate documentation programmatically transforms AI coding from a productivity tool into a workflow platform.

Frequently Asked Questions