@link-assistant/hive-mind 1.52.1 → 1.53.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @link-assistant/hive-mind
 
+## 1.53.0
+
+### Minor Changes
+
+- 906f61e: Add Playwright MCP browser automation fallback hints to all tools (opencode, agent), WebSearch fallback guidance to all tools (claude, codex, opencode, agent), and --no-playwright-mcp flag to physically disable Playwright MCP server connection per session without affecting global registration.
+
 ## 1.52.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "1.52.1",
+  "version": "1.53.0",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",

package/src/agent.lib.mjs

@@ -20,6 +20,7 @@ import { detectUsageLimit, formatUsageLimitMessage } from './usage-limit.lib.mjs
 import { sanitizeObjectStrings } from './unicode-sanitization.lib.mjs';
 import Decimal from 'decimal.js-light';
 import { agentModels, defaultModels, freeToBaseModelMap } from './models/index.mjs';
+import { checkPlaywrightMcpPackageAvailability, getAgentPlaywrightMcpDisableEnv } from './playwright-mcp.lib.mjs';
 import { createAgentTokenUsage, accumulateAgentStepFinishUsage, parseAgentTokenUsage } from './agent-token-usage.lib.mjs';
 
 export { createAgentTokenUsage, accumulateAgentStepFinishUsage, parseAgentTokenUsage };
@@ -320,6 +321,9 @@ export const handleAgentRuntimeSwitch = async () => {
   await log('ℹ️  Agent runtime handling not required for this operation');
 };
 
+/** Check if Playwright MCP is available for Agent @returns {Promise<boolean>} */
+export const checkPlaywrightMcpAvailability = checkPlaywrightMcpPackageAvailability;
+
 // Main function to execute Agent with prompts and settings
 export const executeAgent = async params => {
   const { issueUrl, issueNumber, prNumber, prUrl, branchName, tempDir, workspaceTmpDir, isContinueMode, mergeStateStatus, forkedRepo, feedbackLines, forkActionsUrl, owner, repo, argv, log, formatAligned, getResourceSnapshot, agentPath = 'agent', $ } = params;
@@ -439,6 +443,19 @@ export const executeAgentCommand = async params => {
     await log(`   Memory: ${resourcesBefore.memory.split('\n')[1]}`, { verbose: true });
     await log(`   Load: ${resourcesBefore.load}`, { verbose: true });
 
+    // Issue #1521: Build environment for agent process.
+    // Pass LINK_ASSISTANT_AGENT_VERBOSE env var when --verbose is enabled so verbose logging is initialized at module load time.
+    const agentEnv = { ...process.env };
+    if (argv.verbose) {
+      agentEnv.LINK_ASSISTANT_AGENT_VERBOSE = 'true';
+    }
+
+    // Apply Playwright MCP session state before launching Agent.
+    if (argv.playwrightMcp === false) {
+      Object.assign(agentEnv, await getAgentPlaywrightMcpDisableEnv({ env: agentEnv, cwd: tempDir, log }));
+      await log('🎭 Playwright MCP physically disabled for this Agent session via --no-playwright-mcp', { verbose: true });
+    }
+
     // Build Agent command
     let execCommand;
 
@@ -473,17 +490,6 @@ export const executeAgentCommand = async params => {
       // Pipe the prompt file to agent via stdin
       // Use agentArgs which includes --model and optionally --verbose
 
-      // Issue #1521: Build environment for agent process
-      // Pass LINK_ASSISTANT_AGENT_VERBOSE env var when --verbose is enabled
-      // This ensures Flag.LINK_ASSISTANT_AGENT_VERBOSE is true at module load time inside the agent,
-      // which is required for HTTP request/response logging to work.
-      // The --verbose CLI flag alone is not sufficient because the agent's Flag module
-      // reads the env var at initialization, before yargs middleware calls Flag.setVerbose().
-      const agentEnv = { ...process.env };
-      if (argv.verbose) {
-        agentEnv.LINK_ASSISTANT_AGENT_VERBOSE = 'true';
-      }
-
       execCommand = $({
         cwd: tempDir,
         mirror: false,
@@ -1041,6 +1047,7 @@ export const checkForUncommittedChanges = async (tempDir, owner, repo, branchNam
 export default {
   validateAgentConnection,
   handleAgentRuntimeSwitch,
+  checkPlaywrightMcpAvailability,
   executeAgent,
   executeAgentCommand,
   checkForUncommittedChanges,

package/src/agent.prompts.lib.mjs

@@ -225,6 +225,24 @@ GitHub CLI command patterns.
    - When adding issue comment, use gh issue comment NUMBER --body "text" --repo OWNER/REPO.
    - When viewing PR details, use gh pr view NUMBER --repo OWNER/REPO.
    - When filtering with jq, use gh api repos/${owner}/${repo}/pulls/${prNumber}/comments --paginate --jq 'reverse | .[0:5]'.${
+     argv && argv.promptPlaywrightMcp
+       ? `
+
+Playwright MCP usage (browser automation via MCP tools).
+   - When you develop frontend web applications (HTML, CSS, JavaScript, React, Vue, Angular, etc.), use Playwright MCP tools to test the UI in a real browser.
+   - When WebFetch tool fails to retrieve expected content (e.g., returns empty content, JavaScript-rendered pages, or login-protected pages), use Playwright MCP tools (browser_navigate, browser_snapshot) as a fallback for web browsing.
+   - When WebSearch tool fails or returns insufficient results, use Playwright MCP tools (browser_navigate, browser_snapshot) as a fallback for internet search.
+   - When you need to interact with dynamic web pages that require JavaScript execution, use Playwright MCP tools.
+   - When you need to visually verify how a web page looks or take screenshots, use browser_take_screenshot from Playwright MCP.
+   - When you need to fill forms, click buttons, or perform user interactions on web pages, use Playwright MCP tools (browser_click, browser_type, browser_fill_form).
+   - When you need to test responsive design or different viewport sizes, use browser_resize from Playwright MCP.
+   - When you finish using the browser, close it with browser_close to free resources.
+   - When reproducing UI bugs, use browser_take_screenshot to capture the problem state before implementing any fix.
+   - When fixing UI bugs, take before/after screenshots to provide visual evidence of the fix for human verification.
+   - When creating UI tests, save baseline screenshots to the repository for visual regression testing.
+   - When verifying UI fixes, compare screenshots to ensure the fix does not introduce unintended visual changes.`
+       : ''
+   }${
      modelSupportsVision
        ? `
 

package/src/claude.lib.mjs

@@ -18,6 +18,7 @@ import { displayBudgetStats, createEmptySubSessionUsage, accumulateModelUsage, d
 import { buildClaudeResumeCommand } from './claude.command-builder.lib.mjs';
 import { handleClaudeRuntimeSwitch } from './claude.runtime-switch.lib.mjs'; // see issue #1141
 import { CLAUDE_MODELS as availableModels } from './models/index.mjs'; // Issue #1221
+import { buildMcpConfigWithoutPlaywright } from './playwright-mcp.lib.mjs';
 export { availableModels }; // Re-export for backward compatibility
 const showResumeCommand = async (sessionId, tempDir, claudePath, model, log) => {
   if (!sessionId || !tempDir) return;
@@ -772,6 +773,14 @@ export const executeClaudeCommand = async params => {
       await log(`🔄 Resuming from session: ${argv.resume}`);
       claudeArgs = `--resume ${argv.resume} ${claudeArgs}`;
     }
+    let mcpConfigPath = null;
+    if (argv.playwrightMcp === false) {
+      mcpConfigPath = await buildMcpConfigWithoutPlaywright(log);
+      if (mcpConfigPath) {
+        claudeArgs += ` --strict-mcp-config --mcp-config "${mcpConfigPath}"`;
+        await log('🎭 Playwright MCP physically disabled for this session via --strict-mcp-config', { verbose: true });
+      }
+    }
     claudeArgs += ` -p "${escapedPrompt}" --append-system-prompt "${escapedSystemPrompt}"`;
     const fullCommand = `(cd "${tempDir}" && ${claudePath} ${claudeArgs} | jq -c .)`;
     await log(`\n${formatAligned('📝', 'Raw command:', '')}`);
@@ -795,11 +804,12 @@ export const executeClaudeCommand = async params => {
         if (!isNewVersion && thinkLevel) await log(`📊 Thinking level (via keywords): ${thinkLevel}`, { verbose: true });
       }
       const simpleEscapedSystem = systemPrompt.replace(/"/g, '\\"');
+      const mcpDisableArgs = mcpConfigPath ? ['--strict-mcp-config', '--mcp-config', mcpConfigPath] : [];
       if (argv.resume) {
         const simpleEscapedPrompt = prompt.replace(/"/g, '\\"');
-        execCommand = $({ cwd: tempDir, mirror: false, env: claudeEnv })`${claudePath} --resume ${argv.resume} --output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel} -p "${simpleEscapedPrompt}" --append-system-prompt "${simpleEscapedSystem}"`;
+        execCommand = $({ cwd: tempDir, mirror: false, env: claudeEnv })`${claudePath} --resume ${argv.resume} --output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel} ${mcpDisableArgs} -p "${simpleEscapedPrompt}" --append-system-prompt "${simpleEscapedSystem}"`;
       } else {
-        execCommand = $({ cwd: tempDir, stdin: prompt, mirror: false, env: claudeEnv })`${claudePath} --output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel} --append-system-prompt "${simpleEscapedSystem}"`;
+        execCommand = $({ cwd: tempDir, stdin: prompt, mirror: false, env: claudeEnv })`${claudePath} --output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel} ${mcpDisableArgs} --append-system-prompt "${simpleEscapedSystem}"`;
       }
       await log(`${formatAligned('📋', 'Command details:', '')}`);
       await log(formatAligned('📂', 'Working directory:', tempDir, 2));

package/src/claude.prompts.lib.mjs

@@ -268,6 +268,7 @@ GitHub CLI command patterns.
 Playwright MCP usage (browser automation via mcp__playwright__* tools).
    - When you develop frontend web applications (HTML, CSS, JavaScript, React, Vue, Angular, etc.), use Playwright MCP tools to test the UI in a real browser.
    - When WebFetch tool fails to retrieve expected content (e.g., returns empty content, JavaScript-rendered pages, or login-protected pages), use Playwright MCP tools (browser_navigate, browser_snapshot) as a fallback for web browsing.
+   - When WebSearch tool fails or returns insufficient results, use Playwright MCP tools (browser_navigate, browser_snapshot) as a fallback for internet search.
    - When you need to interact with dynamic web pages that require JavaScript execution, use Playwright MCP tools.
    - When you need to visually verify how a web page looks or take screenshots, use browser_take_screenshot from Playwright MCP.
    - When you need to fill forms, click buttons, or perform user interactions on web pages, use Playwright MCP tools (browser_click, browser_type, browser_fill_form).

package/src/codex.lib.mjs

@@ -21,6 +21,7 @@ import { sanitizeObjectStrings } from './unicode-sanitization.lib.mjs';
 import { mapModelToId, resolveCodexReasoningEffort } from './codex.options.lib.mjs';
 import { createInteractiveHandler } from './interactive-mode.lib.mjs';
 import { initProgressMonitoring } from './solve.progress-monitoring.lib.mjs';
+import { getCodexPlaywrightMcpDisableConfigArgs } from './playwright-mcp.lib.mjs';
 
 const CODEX_USAGE_FIELD_NAMES = ['input_tokens', 'cached_input_tokens', 'output_tokens', 'cache_write_tokens', 'cache_creation_input_tokens', 'reasoning_tokens', 'input_tokens_details.cached_tokens', 'input_tokens_details.cache_read_tokens', 'input_tokens_details.cache_write_tokens', 'input_tokens_details.cache_creation_tokens', 'input_tokens_details.cache_creation_input_tokens', 'output_tokens_details.reasoning_tokens'];
 const getCodexExecEnv = (verbose = false) => (verbose ? { ...process.env, RUST_LOG: 'debug' } : { ...process.env });
@@ -584,6 +585,10 @@ export const executeCodexCommand = async params => {
     } else {
       codexArgs += ` --model ${shellQuote(mappedModel)}`;
     }
+    const codexPlaywrightMcpDisableConfigArgs = argv.playwrightMcp === false ? await getCodexPlaywrightMcpDisableConfigArgs(log) : [];
+    for (const arg of codexPlaywrightMcpDisableConfigArgs) {
+      codexArgs += ` ${shellQuote(arg)}`;
+    }
     codexArgs += ` --json --skip-git-repo-check -o ${shellQuote(lastMessageFile)} -c ${shellQuote(`model_reasoning_effort=${reasoningEffort}`)} -c ${shellQuote('model_reasoning_summary=auto')} --dangerously-bypass-approvals-and-sandbox`;
 
     const fullCommand = `(cd ${shellQuote(tempDir)} && cat ${shellQuote(promptFile)} | ${codexPath} ${codexArgs})`;

package/src/codex.prompts.lib.mjs

@@ -260,6 +260,7 @@ GitHub CLI command patterns.
 Playwright MCP usage (browser automation via MCP tools).
    - When you develop frontend web applications or debug UI issues, use Playwright MCP tools to test the UI in a real browser.
    - When simple fetch-based browsing is insufficient for dynamic pages, use Playwright MCP browser automation as a fallback.
+   - When WebSearch tool fails or returns insufficient results, use Playwright MCP browser automation as a fallback for internet search.
    - When reproducing or verifying UI bugs, take before/after screenshots and close the browser when finished.`
        : ''
    }${

package/src/opencode.lib.mjs

@@ -19,6 +19,7 @@ import { timeouts } from './config.lib.mjs';
 import { detectUsageLimit, formatUsageLimitMessage } from './usage-limit.lib.mjs';
 import { sanitizeObjectStrings } from './unicode-sanitization.lib.mjs';
 import { opencodeModels, defaultModels } from './models/index.mjs';
+import { checkPlaywrightMcpPackageAvailability, getOpenCodePlaywrightMcpDisableEnv } from './playwright-mcp.lib.mjs';
 import { createAgentTokenUsage, accumulateAgentStepFinishUsage, parseAgentTokenUsage as parseOpenCodeTokenUsage } from './agent-token-usage.lib.mjs';
 import { calculateAgentPricing } from './agent.lib.mjs';
 
@@ -101,6 +102,9 @@ export const handleOpenCodeRuntimeSwitch = async () => {
   await log('ℹ️  OpenCode runtime handling not required for this operation');
 };
 
+/** Check if Playwright MCP is available for OpenCode @returns {Promise<boolean>} */
+export const checkPlaywrightMcpAvailability = checkPlaywrightMcpPackageAvailability;
+
 // Main function to execute OpenCode with prompts and settings
 export const executeOpenCode = async params => {
   const { issueUrl, issueNumber, prNumber, prUrl, branchName, tempDir, workspaceTmpDir, isContinueMode, mergeStateStatus, forkedRepo, feedbackLines, forkActionsUrl, owner, repo, argv, log, formatAligned, getResourceSnapshot, opencodePath = 'opencode', $ } = params;
@@ -241,6 +245,14 @@ export const executeOpenCodeCommand = async params => {
     await log(`   Memory: ${resourcesBefore.memory.split('\n')[1]}`, { verbose: true });
     await log(`   Load: ${resourcesBefore.load}`, { verbose: true });
 
+    const opencodeEnv = { ...process.env };
+
+    // Apply Playwright MCP session state before launching OpenCode.
+    if (argv.playwrightMcp === false) {
+      Object.assign(opencodeEnv, await getOpenCodePlaywrightMcpDisableEnv({ env: opencodeEnv, cwd: tempDir, log }));
+      await log('🎭 Playwright MCP physically disabled for this OpenCode session via --no-playwright-mcp', { verbose: true });
+    }
+
     // Build OpenCode command
     let execCommand;
 
@@ -288,11 +300,13 @@ export const executeOpenCodeCommand = async params => {
         execCommand = $({
           cwd: tempDir,
           mirror: false,
+          env: opencodeEnv,
         })`cat ${promptFile} | ${opencodePath} run --format json --resume ${argv.resume} --model ${mappedModel}`;
       } else {
         execCommand = $({
           cwd: tempDir,
           mirror: false,
+          env: opencodeEnv,
         })`cat ${promptFile} | ${opencodePath} run --format json --model ${mappedModel}`;
       }
 
@@ -653,6 +667,7 @@ export const checkForUncommittedChanges = async (tempDir, owner, repo, branchNam
 export default {
   validateOpenCodeConnection,
   handleOpenCodeRuntimeSwitch,
+  checkPlaywrightMcpAvailability,
   executeOpenCode,
   executeOpenCodeCommand,
   checkForUncommittedChanges,

package/src/opencode.prompts.lib.mjs

@@ -226,6 +226,24 @@ GitHub CLI command patterns.
    - When adding issue comment, use gh issue comment NUMBER --body "text" --repo OWNER/REPO.
    - When viewing PR details, use gh pr view NUMBER --repo OWNER/REPO.
    - When filtering with jq, use gh api repos/${owner}/${repo}/pulls/${prNumber}/comments --paginate --jq 'reverse | .[0:5]'.${
+     argv && argv.promptPlaywrightMcp
+       ? `
+
+Playwright MCP usage (browser automation via MCP tools).
+   - When you develop frontend web applications (HTML, CSS, JavaScript, React, Vue, Angular, etc.), use Playwright MCP tools to test the UI in a real browser.
+   - When WebFetch tool fails to retrieve expected content (e.g., returns empty content, JavaScript-rendered pages, or login-protected pages), use Playwright MCP tools (browser_navigate, browser_snapshot) as a fallback for web browsing.
+   - When WebSearch tool fails or returns insufficient results, use Playwright MCP tools (browser_navigate, browser_snapshot) as a fallback for internet search.
+   - When you need to interact with dynamic web pages that require JavaScript execution, use Playwright MCP tools.
+   - When you need to visually verify how a web page looks or take screenshots, use browser_take_screenshot from Playwright MCP.
+   - When you need to fill forms, click buttons, or perform user interactions on web pages, use Playwright MCP tools (browser_click, browser_type, browser_fill_form).
+   - When you need to test responsive design or different viewport sizes, use browser_resize from Playwright MCP.
+   - When you finish using the browser, close it with browser_close to free resources.
+   - When reproducing UI bugs, use browser_take_screenshot to capture the problem state before implementing any fix.
+   - When fixing UI bugs, take before/after screenshots to provide visual evidence of the fix for human verification.
+   - When creating UI tests, save baseline screenshots to the repository for visual regression testing.
+   - When verifying UI fixes, compare screenshots to ensure the fix does not introduce unintended visual changes.`
+       : ''
+   }${
      modelSupportsVision
        ? `
 

package/src/playwright-mcp.lib.mjs

@@ -0,0 +1,298 @@
+#!/usr/bin/env node
+// Playwright MCP session-level disable/restore utilities.
+if (typeof globalThis.use === 'undefined') {
+  globalThis.use = (await eval(await (await fetch('https://unpkg.com/use-m/use.js')).text())).use;
+}
+const { $ } = await use('command-stream');
+const fs = (await use('fs')).promises;
+const os = await use('os');
+const path = (await use('path')).default;
+
+export const getCommandResultCode = result => result?.code ?? result?.exitCode ?? null;
+
+export const getCommandResultOutput = result => `${result?.stdout?.toString() || ''}${result?.stderr?.toString() || ''}`;
+
+export const isCommandResultSuccess = result => getCommandResultCode(result) === 0;
+
+export const checkPlaywrightMcpPackageAvailability = async () => {
+  try {
+    const result = await $`timeout 5 npx --no-install @playwright/mcp --help 2>&1`.catch(() => null);
+    if (isCommandResultSuccess(result)) return true;
+    const npmResult = await $`timeout 5 npm ls -g @playwright/mcp 2>&1`.catch(() => null);
+    return getCommandResultOutput(npmResult).includes('@playwright/mcp');
+  } catch {
+    return false;
+  }
+};
+
+export const parseCodexMcpServerNames = output =>
+  output
+    .split(/\r?\n/)
+    .map(line => line.trim())
+    .filter(line => line && !line.startsWith('Name '))
+    .map(line => line.split(/\s+/)[0])
+    .filter(name => /^[A-Za-z0-9_-]+$/.test(name));
+
+export const getCodexPlaywrightMcpDisableConfigArgs = async log => {
+  try {
+    const result = await $`timeout 5 codex mcp list 2>&1`.catch(() => null);
+    if (!isCommandResultSuccess(result)) return [];
+    const names = parseCodexMcpServerNames(getCommandResultOutput(result)).filter(name => name.toLowerCase().includes('playwright'));
+    if (names.length === 0) {
+      if (log) await log('🎭 No Codex Playwright MCP server registration found to disable for this session', { verbose: true });
+      return [];
+    }
+    if (log) {
+      await log(`🎭 Playwright MCP disabled for this Codex session via config override: ${names.join(', ')}`, {
+        verbose: true,
+      });
+    }
+    return names.flatMap(name => ['-c', `mcp_servers.${name}.enabled=false`]);
+  } catch (err) {
+    if (log) await log(`⚠️  Could not build Codex Playwright MCP disable override: ${err.message}`, { verbose: true });
+    return [];
+  }
+};
+
+const isPlainObject = value => value && typeof value === 'object' && !Array.isArray(value);
+
+const mergeDeep = (base, override) => {
+  const result = { ...(isPlainObject(base) ? base : {}) };
+  for (const [key, value] of Object.entries(isPlainObject(override) ? override : {})) {
+    result[key] = isPlainObject(result[key]) && isPlainObject(value) ? mergeDeep(result[key], value) : value;
+  }
+  return result;
+};
+
+const stripJsonComments = input => {
+  let output = '';
+  let inString = false;
+  let quote = '';
+  let escaped = false;
+  for (let index = 0; index < input.length; index++) {
+    const char = input[index];
+    const next = input[index + 1];
+    if (inString) {
+      output += char;
+      if (escaped) {
+        escaped = false;
+      } else if (char === '\\') {
+        escaped = true;
+      } else if (char === quote) {
+        inString = false;
+      }
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      inString = true;
+      quote = char;
+      output += char;
+      continue;
+    }
+    if (char === '/' && next === '/') {
+      while (index < input.length && input[index] !== '\n') index++;
+      output += '\n';
+      continue;
+    }
+    if (char === '/' && next === '*') {
+      index += 2;
+      while (index < input.length && !(input[index] === '*' && input[index + 1] === '/')) index++;
+      index++;
+      continue;
+    }
+    output += char;
+  }
+  return output;
+};
+
+const stripTrailingCommas = input => {
+  let output = '';
+  let inString = false;
+  let quote = '';
+  let escaped = false;
+  for (let index = 0; index < input.length; index++) {
+    const char = input[index];
+    if (inString) {
+      output += char;
+      if (escaped) {
+        escaped = false;
+      } else if (char === '\\') {
+        escaped = true;
+      } else if (char === quote) {
+        inString = false;
+      }
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      inString = true;
+      quote = char;
+      output += char;
+      continue;
+    }
+    if (char === ',') {
+      let lookahead = index + 1;
+      while (/\s/.test(input[lookahead] || '')) lookahead++;
+      if (input[lookahead] === '}' || input[lookahead] === ']') continue;
+    }
+    output += char;
+  }
+  return output;
+};
+
+const parseConfigContent = content => {
+  if (!content || typeof content !== 'string') return {};
+  try {
+    return JSON.parse(content);
+  } catch {
+    try {
+      return JSON.parse(stripTrailingCommas(stripJsonComments(content)));
+    } catch {
+      return {};
+    }
+  }
+};
+
+const readConfigFile = async filePath => {
+  const content = await fs.readFile(filePath, 'utf-8').catch(() => null);
+  return parseConfigContent(content);
+};
+
+const pathExists = async filePath =>
+  fs
+    .stat(filePath)
+    .then(() => true)
+    .catch(() => false);
+
+const findUpConfigPaths = async (startDir, filenames) => {
+  const results = [];
+  let dir = startDir || process.cwd();
+  while (dir) {
+    for (const file of filenames) results.push(path.join(dir, file));
+    if (await pathExists(path.join(dir, '.git'))) break;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return results;
+};
+
+const configFilesInDir = dir => (dir ? ['config.json', 'opencode.json', 'opencode.jsonc'].map(file => path.join(dir, file)) : []);
+
+const isPlaywrightMcpEntry = (name, config) => {
+  const haystack = `${name || ''} ${JSON.stringify(config || {})}`.toLowerCase();
+  return haystack.includes('playwright');
+};
+
+export const collectPlaywrightMcpServerNames = (...configs) => {
+  const names = new Set();
+  for (const config of configs.flat()) {
+    if (!isPlainObject(config?.mcp)) continue;
+    for (const [name, mcpConfig] of Object.entries(config.mcp)) {
+      if (isPlaywrightMcpEntry(name, mcpConfig)) names.add(name);
+    }
+  }
+  return [...names];
+};
+
+export const buildPlaywrightMcpDisableConfig = (serverNames = []) => {
+  const names = [...new Set(['playwright', ...serverNames].filter(Boolean))];
+  const mcp = {};
+  const tools = {
+    '*playwright*': false,
+    'mcp__playwright__*': false,
+  };
+  for (const name of names) {
+    mcp[name] = {
+      type: 'local',
+      command: ['npx', '-y', '@playwright/mcp@latest'],
+      enabled: false,
+    };
+    tools[`${name}_*`] = false;
+    tools[`mcp__${name}__*`] = false;
+  }
+  return {
+    $schema: 'https://opencode.ai/config.json',
+    mcp,
+    tools,
+  };
+};
+
+export const mergePlaywrightMcpDisableConfigContent = (existingContent = '', serverNames = []) => {
+  const existingConfig = parseConfigContent(existingContent);
+  const detectedNames = collectPlaywrightMcpServerNames(existingConfig);
+  const disableConfig = buildPlaywrightMcpDisableConfig([...serverNames, ...detectedNames]);
+  return JSON.stringify(mergeDeep(existingConfig, disableConfig), null, 2);
+};
+
+const collectPlaywrightMcpServerNamesFromFiles = async filePaths => {
+  const configs = [];
+  for (const filePath of filePaths) configs.push(await readConfigFile(filePath));
+  return collectPlaywrightMcpServerNames(configs);
+};
+
+const getConfigHome = env => env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+
+const getOpenCodeConfigFilePaths = async ({ env = process.env, cwd = process.cwd() } = {}) => [...configFilesInDir(path.join(getConfigHome(env), 'opencode')), ...(env.OPENCODE_CONFIG ? [env.OPENCODE_CONFIG] : []), ...(await findUpConfigPaths(cwd, ['opencode.jsonc', 'opencode.json'])), ...configFilesInDir(env.OPENCODE_CONFIG_DIR)];
+
+const getAgentConfigFilePaths = async ({ env = process.env, cwd = process.cwd() } = {}) => [...configFilesInDir(path.join(getConfigHome(env), 'link-assistant-agent')), ...(env.LINK_ASSISTANT_AGENT_CONFIG ? [env.LINK_ASSISTANT_AGENT_CONFIG] : []), ...(env.OPENCODE_CONFIG ? [env.OPENCODE_CONFIG] : []), ...(await findUpConfigPaths(cwd, ['opencode.jsonc', 'opencode.json'])), ...configFilesInDir(path.join(cwd, '.link-assistant-agent')), ...configFilesInDir(path.join(cwd, '.opencode')), ...configFilesInDir(env.LINK_ASSISTANT_AGENT_CONFIG_DIR), ...configFilesInDir(env.OPENCODE_CONFIG_DIR)];
+
+export const getOpenCodePlaywrightMcpDisableEnv = async ({ env = process.env, cwd = process.cwd(), includeConfigFiles = true, log } = {}) => {
+  const inlineConfig = env.OPENCODE_CONFIG_CONTENT || '';
+  const names = collectPlaywrightMcpServerNames(parseConfigContent(inlineConfig));
+  if (includeConfigFiles) {
+    names.push(...(await collectPlaywrightMcpServerNamesFromFiles(await getOpenCodeConfigFilePaths({ env, cwd }))));
+  }
+  const uniqueNames = [...new Set(names)];
+  const displayNames = [...new Set(['playwright', ...uniqueNames])];
+  if (log) await log(`🎭 OpenCode Playwright MCP disabled through OPENCODE_CONFIG_CONTENT for: ${displayNames.join(', ')}`, { verbose: true });
+  return {
+    OPENCODE_CONFIG_CONTENT: mergePlaywrightMcpDisableConfigContent(inlineConfig, uniqueNames),
+  };
+};
+
+export const getAgentPlaywrightMcpDisableEnv = async ({ env = process.env, cwd = process.cwd(), includeConfigFiles = true, log } = {}) => {
+  const agentInlineConfig = env.LINK_ASSISTANT_AGENT_CONFIG_CONTENT || env.OPENCODE_CONFIG_CONTENT || '';
+  const names = collectPlaywrightMcpServerNames(parseConfigContent(agentInlineConfig), parseConfigContent(env.OPENCODE_CONFIG_CONTENT || ''));
+  if (includeConfigFiles) {
+    names.push(...(await collectPlaywrightMcpServerNamesFromFiles(await getAgentConfigFilePaths({ env, cwd }))));
+  }
+  const uniqueNames = [...new Set(names)];
+  const displayNames = [...new Set(['playwright', ...uniqueNames])];
+  const configContent = mergePlaywrightMcpDisableConfigContent(agentInlineConfig, uniqueNames);
+  if (log) await log(`🎭 Agent Playwright MCP disabled through LINK_ASSISTANT_AGENT_CONFIG_CONTENT for: ${displayNames.join(', ')}`, { verbose: true });
+  return {
+    LINK_ASSISTANT_AGENT_CONFIG_CONTENT: configContent,
+    OPENCODE_CONFIG_CONTENT: mergePlaywrightMcpDisableConfigContent(env.OPENCODE_CONFIG_CONTENT || agentInlineConfig, uniqueNames),
+  };
+};
+
+/** Build a temporary MCP config JSON excluding Playwright, for use with --strict-mcp-config */
+export const buildMcpConfigWithoutPlaywright = async log => {
+  try {
+    const claudeJsonPath = path.join(os.homedir(), '.claude.json');
+    const claudeJson = JSON.parse(await fs.readFile(claudeJsonPath, 'utf-8'));
+    const mcpServers = claudeJson.mcpServers || {};
+    const filtered = {};
+    for (const [name, config] of Object.entries(mcpServers)) {
+      if (name.toLowerCase().includes('playwright')) continue;
+      filtered[name] = config;
+    }
+    const tempConfigPath = path.join(os.tmpdir(), `claude-mcp-no-playwright-${Date.now()}-${process.pid}.json`);
+    await fs.writeFile(tempConfigPath, JSON.stringify({ mcpServers: filtered }, null, 2));
+    if (log) await log(`🎭 Created filtered MCP config (without Playwright): ${tempConfigPath}`, { verbose: true });
+    return tempConfigPath;
+  } catch (err) {
+    if (log) await log(`⚠️  Could not build filtered MCP config: ${err.message}`, { verbose: true });
+    return null;
+  }
+};
+
+/** Cascade --no-playwright-mcp to disable related flags */
+export const cascadePlaywrightMcpDisable = async (argv, log) => {
+  if (argv.playwrightMcp === false) {
+    if (log) await log('🎭 Playwright MCP physically disabled via --no-playwright-mcp', { verbose: true });
+    argv.promptPlaywrightMcp = false;
+    argv.playwrightMcpAutoCleanup = false;
+    if (log) await log('ℹ️  --prompt-playwright-mcp and --playwright-mcp-auto-cleanup also disabled', { verbose: true });
+  }
+};

package/src/solve.config.lib.mjs

@@ -366,7 +366,7 @@ export const SOLVE_OPTION_DEFINITIONS = {
   },
   'prompt-playwright-mcp': {
     type: 'boolean',
-    description: 'Enable Playwright MCP browser automation hints in system prompt (enabled by default, only takes effect if Playwright MCP is installed). Use --no-prompt-playwright-mcp to disable. Supported for --tool claude and --tool codex.',
+    description: 'Enable Playwright MCP browser automation hints in system prompt (enabled by default, only takes effect if Playwright MCP is installed). Use --no-prompt-playwright-mcp to disable. Supported for --tool claude, --tool codex, --tool opencode, and --tool agent.',
     default: true,
   },
   'prompt-check-sibling-pull-requests': {
@@ -384,6 +384,11 @@ export const SOLVE_OPTION_DEFINITIONS = {
     description: 'Path to examples folder used in system prompt. Set to empty string to disable examples folder prompt. Default: ./examples',
     default: './examples',
   },
+  'playwright-mcp': {
+    type: 'boolean',
+    description: 'Enable Playwright MCP server connection for this session (enabled by default). Use --no-playwright-mcp to physically disable the Playwright MCP server without affecting the global MCP registration. When disabled, also disables --prompt-playwright-mcp and --playwright-mcp-auto-cleanup. Supported for --tool claude, --tool codex, --tool opencode, and --tool agent.',
+    default: true,
+  },
   'playwright-mcp-auto-cleanup': {
     type: 'boolean',
     description: 'Automatically remove .playwright-mcp/ folder before checking for uncommitted changes. This prevents browser automation artifacts from triggering auto-restart. Use --no-playwright-mcp-auto-cleanup to keep the folder for debugging.',

package/src/solve.mjs

@@ -707,12 +707,31 @@ try {
     $,
   });
 
+  const { cascadePlaywrightMcpDisable } = await import('./playwright-mcp.lib.mjs');
+  await cascadePlaywrightMcpDisable(argv, log);
+
+  async function resolvePlaywrightMcp(checkFn) {
+    if (argv.playwrightMcp === false) return;
+    if (argv.promptPlaywrightMcp) {
+      const available = await checkFn();
+      if (available) {
+        await log('🎭 Playwright MCP detected - enabling browser automation hints', { verbose: true });
+      } else {
+        await log('ℹ️  Playwright MCP not detected - browser automation hints will be disabled', { verbose: true });
+        argv.promptPlaywrightMcp = false;
+      }
+    } else {
+      await log('ℹ️  Playwright MCP explicitly disabled via --no-prompt-playwright-mcp', { verbose: true });
+    }
+  }
+
   // Execute tool command with all prompts and settings
   let toolResult;
   if (argv.tool === 'opencode') {
     const opencodeLib = await import('./opencode.lib.mjs');
-    const { executeOpenCode } = opencodeLib;
+    const { executeOpenCode, checkPlaywrightMcpAvailability: checkOpenCodePlaywrightMcp } = opencodeLib;
     const opencodePath = process.env.OPENCODE_PATH || 'opencode';
+    await resolvePlaywrightMcp(checkOpenCodePlaywrightMcp);
 
     toolResult = await executeOpenCode({
       issueUrl,
@@ -742,18 +761,7 @@ try {
     const codexLib = await import('./codex.lib.mjs');
     const { executeCodex, checkPlaywrightMcpAvailability } = codexLib;
     const codexPath = process.env.CODEX_PATH || 'codex';
-
-    if (argv.promptPlaywrightMcp) {
-      const playwrightMcpAvailable = await checkPlaywrightMcpAvailability();
-      if (playwrightMcpAvailable) {
-        await log('🎭 Playwright MCP detected - enabling browser automation hints', { verbose: true });
-      } else {
-        await log('ℹ️  Playwright MCP not detected - browser automation hints will be disabled', { verbose: true });
-        argv.promptPlaywrightMcp = false;
-      }
-    } else {
-      await log('ℹ️  Playwright MCP explicitly disabled via --no-prompt-playwright-mcp', { verbose: true });
-    }
+    await resolvePlaywrightMcp(checkPlaywrightMcpAvailability);
 
     toolResult = await executeCodex({
       issueUrl,
@@ -781,8 +789,9 @@ try {
     });
   } else if (argv.tool === 'agent') {
     const agentLib = await import('./agent.lib.mjs');
-    const { executeAgent } = agentLib;
+    const { executeAgent, checkPlaywrightMcpAvailability: checkAgentPlaywrightMcp } = agentLib;
     const agentPath = process.env.AGENT_PATH || 'agent';
+    await resolvePlaywrightMcp(checkAgentPlaywrightMcp);
 
     toolResult = await executeAgent({
       issueUrl,
@@ -810,20 +819,8 @@ try {
     });
   } else {
     // Default to Claude
-    // Check for Playwright MCP availability if using Claude tool
     if (argv.tool === 'claude' || !argv.tool) {
-      // If flag is true (default), check if Playwright MCP is actually available
-      if (argv.promptPlaywrightMcp) {
-        const playwrightMcpAvailable = await checkPlaywrightMcpAvailability();
-        if (playwrightMcpAvailable) {
-          await log('🎭 Playwright MCP detected - enabling browser automation hints', { verbose: true });
-        } else {
-          await log('ℹ️  Playwright MCP not detected - browser automation hints will be disabled', { verbose: true });
-          argv.promptPlaywrightMcp = false;
-        }
-      } else {
-        await log('ℹ️  Playwright MCP explicitly disabled via --no-prompt-playwright-mcp', { verbose: true });
-      }
+      await resolvePlaywrightMcp(checkPlaywrightMcpAvailability);
     }
     const claudeResult = await executeClaude({
       issueUrl,

package/src/solve.restart-shared.lib.mjs

@@ -178,13 +178,28 @@ export const executeToolIteration = async params => {
   const memoryCheck = await import('./memory-check.mjs');
   const { getResourceSnapshot } = memoryCheck;
 
+  const { cascadePlaywrightMcpDisable } = await import('./playwright-mcp.lib.mjs');
+  await cascadePlaywrightMcpDisable(argv, log);
+
   let toolResult;
   if (argv.tool === 'opencode') {
     // Use OpenCode
     const opencodeExecLib = await import('./opencode.lib.mjs');
-    const { executeOpenCode } = opencodeExecLib;
+    const { executeOpenCode, checkPlaywrightMcpAvailability } = opencodeExecLib;
     const opencodePath = argv.opencodePath || 'opencode';
 
+    if (argv.promptPlaywrightMcp) {
+      const playwrightMcpAvailable = await checkPlaywrightMcpAvailability();
+      if (playwrightMcpAvailable) {
+        await log('🎭 Playwright MCP detected - enabling browser automation hints', { verbose: true });
+      } else {
+        await log('ℹ️  Playwright MCP not detected - browser automation hints will be disabled', { verbose: true });
+        argv.promptPlaywrightMcp = false;
+      }
+    } else {
+      await log('ℹ️  Playwright MCP explicitly disabled via --no-prompt-playwright-mcp', { verbose: true });
+    }
+
     toolResult = await executeOpenCode({
       issueUrl,
       issueNumber,
@@ -249,9 +264,21 @@ export const executeToolIteration = async params => {
   } else if (argv.tool === 'agent') {
     // Use Agent
     const agentExecLib = await import('./agent.lib.mjs');
-    const { executeAgent } = agentExecLib;
+    const { executeAgent, checkPlaywrightMcpAvailability } = agentExecLib;
     const agentPath = argv.agentPath || 'agent';
 
+    if (argv.promptPlaywrightMcp) {
+      const playwrightMcpAvailable = await checkPlaywrightMcpAvailability();
+      if (playwrightMcpAvailable) {
+        await log('🎭 Playwright MCP detected - enabling browser automation hints', { verbose: true });
+      } else {
+        await log('ℹ️  Playwright MCP not detected - browser automation hints will be disabled', { verbose: true });
+        argv.promptPlaywrightMcp = false;
+      }
+    } else {
+      await log('ℹ️  Playwright MCP explicitly disabled via --no-prompt-playwright-mcp', { verbose: true });
+    }
+
     toolResult = await executeAgent({
       issueUrl,
       issueNumber,