add warning when models are used with hybrid mode that will not perf…

[tkattkat]

why

hybrid mode requires specific models to perform optimally

what changed

if the models we recommend are not used, we throw an error log and link out to the agent docs

test plan

tested locally

---

Summary by cubic

Add a runtime warning when hybrid mode is used with models that may not perform well, linking to the docs with recommended models. This helps catch misconfiguration early and improves agent reliability.

• New Features
  • Log a warning in hybrid mode if the model ID isn’t “gemini-3-flash” or “claude”, with a link to the agent docs.
  • Updated hybrid mode docs to align guidance with the new warning.

^{Written for commit eb0dd6a. Summary will update on new commits. Review in cubic}

[changeset-bot]

🦋 Changeset detected

Latest commit: eb0dd6a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[greptile-apps]

Greptile Overview

Greptile Summary

This PR adds a runtime warning when hybrid mode is used with models that may not perform optimally. The change logs a warning message with a link to the documentation when the model ID doesn't include "gemini-3-flash" or "claude".

Key Changes:

• Added model validation check in v3AgentHandler.ts:116-126 that warns users when non-recommended models are used with hybrid mode
• Cleaned up documentation by removing a redundant recommendation line from the warning box

Critical Issue Found:

• The validation logic checks for "gemini-3-flash" but the documented recommended model is google/gemini-3-flash-preview (note the -preview suffix), which means users following the documentation will incorrectly receive the warning

Confidence Score: 2/5

• This PR has a critical bug in the model validation logic that will cause false warnings for the documented recommended model
• The implementation has the right intent but fails to correctly match the recommended Gemini model due to a missing -preview suffix in the validation check, which will confuse users and undermine trust in the warning system
• packages/core/lib/v3/handlers/v3AgentHandler.ts requires immediate attention to fix the model validation logic

Important Files Changed

Filename	Overview
packages/core/lib/v3/handlers/v3AgentHandler.ts	Added warning for non-recommended models in hybrid mode, but model validation logic has a critical bug that won't match the documented recommended model
packages/docs/v3/basics/agent.mdx	Removed redundant recommendation line from warning box, documentation is now cleaner
.changeset/late-parks-taste.md	Standard changeset file with appropriate patch-level semantic version

Sequence Diagram

sequenceDiagram
    participant User
    participant V3AgentHandler
    participant LLMClient
    participant Logger
    participant Agent

    User->>V3AgentHandler: agent({ mode: "hybrid", model: "..." })
    V3AgentHandler->>V3AgentHandler: prepareAgent()
    V3AgentHandler->>LLMClient: getLanguageModel()
    LLMClient-->>V3AgentHandler: baseModel (with modelId)
    
    alt model is NOT recommended for hybrid
        V3AgentHandler->>V3AgentHandler: Check modelId includes "gemini-3-flash" OR "claude"
        V3AgentHandler->>Logger: log warning with docs link
        Logger-->>User: Warning: model may not perform well
    end
    
    V3AgentHandler->>V3AgentHandler: Wrap model with middleware
    V3AgentHandler-->>Agent: Return prepared agent config
    Agent-->>User: Agent ready for execution

Loading

[greptile-apps]

_{3 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[cubic-dev-ai]

1 issue found across 3 files

Confidence score: 3/5

• Hardcoded model-name allowlist logic in packages/core/lib/v3/handlers/v3AgentHandler.ts violates the stated rule and could cause incorrect behavior as models change.
• Severity is medium-high (7/10) with high confidence, so there is some regression/policy risk despite the change being localized.
• Pay close attention to packages/core/lib/v3/handlers/v3AgentHandler.ts - hardcoded model-name checks for hybrid mode.

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="packages/core/lib/v3/handlers/v3AgentHandler.ts">

<violation number="1" location="packages/core/lib/v3/handlers/v3AgentHandler.ts:116">
P1: Rule violated: **Ensure we never check against hardcoded lists of allowed LLM model names**

Hardcoding model-name checks for hybrid mode violates the rule against allowlists of LLM model names. The new condition only treats "gemini-3-flash" and "claude" as acceptable, which will go stale as models change. Replace this with provider capability metadata or avoid model-name checks entirely.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant Client
    participant Handler as V3AgentHandler
    participant Model as BaseModel
    participant Log as Logger

    Client->>Handler: initializeAgent()
    Handler->>Model: Inspect modelId
    Model-->>Handler: modelId (e.g. "gpt-4o")

    Note over Handler: Logic: Check if mode is "hybrid"

    alt mode is "hybrid"
        alt NEW: modelId DOES NOT include "gemini-3-flash" OR "claude"
            Handler->>Log: NEW: logWarning()
            Note right of Log: Includes link to docs for recommended models
        else Model is recommended
            Note over Handler,Log: Proceed without warning
        end
    end

    Handler-->>Client: Return agent configuration (options, maxSteps, etc.)

Loading

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}