feat(integrations): Claude Agent SDK harness example

[miguelg719]

Runnable project embedding a Claude agent via @anthropic-ai/claude-agent-sdk, with the stagehand-facade stdio server mounted programmatically — matching the pattern established by the evals claude_code harness (query() + mcpServers).

• allowedTools restricted to mcp__stagehand__{run,snapshot,screenshot} plus a canUseTool guard (headless runs hang on unanswered permission prompts).
• System prompt is FACADE_AGENT_INSTRUCTIONS imported from the facade package; server spawned with a STAGEHAND_*/BROWSERBASE_* env allowlist.
• One-line run after install + core build: pnpm --filter @browserbasehq/stagehand-integrations-example-claude-code-facade start "your instruction"
• Secondary README section: connecting a running Claude Code CLI via the project-scoped .mcp.json (verified: the CLI inherits the shell env; ${VAR} in .mcp.json is not expanded).

Verified: contract + allowlist tests in CI; Browserbase smoke — "The page heading is 'Example Domain', per snapshot element [0-19]".

---

Summary by cubic

Adds a runnable Claude agent harness using @anthropic-ai/claude-agent-sdk that mounts the Stagehand facade MCP stdio server. Provides a one-command example and an optional .mcp.json for the Claude Code CLI; only STAGEHAND_*/BROWSERBASE_* env reach the browser.

• New package: @browserbasehq/stagehand-integrations-example-claude-code-facade (Node 24+). Run: pnpm --filter @browserbasehq/stagehand-integrations-example-claude-code-facade start "your instruction". Choose model via CLAUDE_STAGEHAND_MODEL (default claude-sonnet-5).
• Spawns @browserbasehq/stagehand-integrations/facade/stdio-server with an env allowlist; ANTHROPIC_API_KEY is never forwarded.
• Restricts tools to mcp__stagehand__{run,snapshot,screenshot} via allowedTools and a deny-by-default canUseTool. Uses FACADE_AGENT_INSTRUCTIONS as the system prompt.
• .mcp.json enables the claude CLI in this directory; the CLI inherits the shell env (note: ${VAR} is not expanded in .mcp.json).
• Tests cover the tool name contract and env allowlist. Robustness: resolve server path inside main, add import.meta.main guard, and exit nonzero if the agent stream ends without a result. Workspace updates add @anthropic-ai/claude-agent-sdk to the catalog/lockfile and a turbo typecheck target; no changes to other packages’ runtime behavior.

^{Written for commit 129610f. Summary will update on new commits.}

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​@​anthropic-ai/​claude-agent-sdk@​0.3.224

View full report

[cubic-dev-ai]

All reported issues were addressed across 11 files

Architecture diagram

sequenceDiagram
    participant User as User/CLI
    participant Agent as Claude Agent SDK
    participant MCP as Stagehand MCP Server
    participant Facade as Stagehand Facade
    participant Browser as Browserbase Browser
    participant Env as Environment Filter

    Note over User,Browser: NEW: Claude Code Facade Integration Flow

    User->>Agent: Run instruction via query()
    Agent->>Agent: Load FACADE_AGENT_INSTRUCTIONS as system prompt

    Agent->>MCP: Spawn stdio server (mcpServers.stagehand)
    Agent->>Env: Request env allowlist
    Env->>Env: Filter to STAGEHAND_*/BROWSERBASE_* vars
    Env-->>Agent: Allowlisted env (ANTHROPIC_API_KEY excluded)
    Agent->>MCP: Pass allowlisted env to subprocess

    Note over Agent: Tool permission enforcement
    Agent->>Agent: Check canUseTool guard
    alt Tool starts with "mcp__stagehand__"
        Agent->>Agent: Allow tool execution
        Agent->>MCP: Call mcp__stagehand__{run,snapshot,screenshot}
        MCP->>Facade: Execute Stagehand operation
        Facade->>Browser: Drive browser (via Browserbase)
        Browser-->>Facade: Browser result
        Facade-->>MCP: Tool result
        MCP-->>Agent: MCP response
    else Non-stagehand tool
        Agent->>Agent: Deny with message "Only stagehand browser tools permitted"
    end

    Agent->>Agent: Stream agent messages
    alt Success result
        Agent-->>User: Print final result
    else Error/Cancelled result
        Agent-->>User: Throw error, set exit code 1
    end

    Note over User,MCP: Alternative: Claude Code CLI with .mcp.json
    User->>MCP: Connect via project-scoped .mcp.json
    Note over MCP: CLI inherits shell env (no ${VAR} expansion)
    MCP-->>User: Tool access available

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[changeset-bot]

⚠️ No Changeset found

Latest commit: 129610f

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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