feat(agent): a missing workspace gates the file tools, not the whole run

runAgent opened with a blanket refusal — "Open a folder first — the agent works on your
workspace." — written for the file tools but placed where it failed the ENTIRE run.

So with no folder open you could not ask what an error meant, could not reach a single MCP
server (the GitHub server does not care whether you have a folder open), and could not ask
about the file open in the editor in front of you. The reported case was exactly that:
"Explain what the current file does", refused, for a request that never needed a workspace.

The root still gates the tools that resolve a path or a cwd against it. It no longer gates
the agent.

  withheld rootless : list_files, read_file, search, edit_file, write_file, delete_file,
                      run_command, read_command_output
  still available   : update_plan, ask_user, use_skill + every MCP tool

Withheld rather than offered-and-failing: a tool that is present but errors on every call
is worse than one that is absent, because the model retries it.

THREE THINGS THAT WOULD HAVE MADE THIS A WORSE EXPERIENCE THAN THE REFUSAL:

  - PORTABLE_TOOLS is DERIVED from NEEDS_ROOT, not a second hand-written list, so the two
    cannot disagree about a tool.
  - baseTools switches too. Left on the full TOOLS it would bill the context popover for
    schemas that were never sent.
  - The model is TOLD why the tools are missing. Without that it sees a list with no
    read_file and improvises — answering about files it cannot see, or apologising at
    length for a limit it cannot name. The note also points at what still works and, if the
    request genuinely needs files, at File > Open Folder.

MCP servers are still spawned with a cwd, so a null root now falls back to os.homedir()
rather than being passed through.

Guards, each bypass-verified by reverting the fix:
  - the blanket refusal restored (the reported bug)
  - run_command un-gated; ask_user gated (which would rebuild the refusal a tool at a time)
  - NEEDS_ROOT naming a tool that no longer exists, i.e. rename drift
  - the tool list no longer switching on the root; baseTools billing for unsent tools
  - MCP spawned with a null cwd
  - the note built but never concatenated into the prompt — the classic version of this bug,
    which looks right in review and does nothing

5 tests in agentNoWorkspace, 33 suites green.

Author: ndemianc

extensions/levelcode-ai/agent.js

@@ -13,6 +13,7 @@ const vscode = require('vscode');
 const fs = require('fs');
 const path = require('path');
 const cp = require('child_process');
+const os = require('os');   // MCP servers need a cwd even when no folder is open
 const providers = require('./providers/index');
 const { formatVerifyFeedback, verifyOutcome, looksUnrunnable, sniffPort, sniffPreviewUrl, looksReady } = require('./verify');
 const { classifyCommand, dangerLabel } = require('./commandSafety');
@@ -68,6 +69,22 @@ function buildSystem(menu) {
 	const list = menu.map((s) => '- ' + s.name + ': ' + s.description).join('\n');
 	return SYSTEM_BASE + '\n\nAvailable skills (call use_skill with the name):\n' + list;
 }
+// The tools that resolve a PATH or a CWD against the workspace root. With no folder open they have
+// nothing to resolve against, so they are withheld from the model rather than offered and left to fail
+// one call at a time — a tool that is present but always errors is worse than one that is absent.
+//
+// Everything NOT in here works fine rootless: update_plan and ask_user are pure conversation, use_skill
+// reads from the extension, and every MCP tool talks to its own server (the GitHub server does not care
+// whether you have a folder open). That is the whole reason the old blanket refusal was wrong.
+//
+// read_command_output is included because it reads the output of a background run_command, and without
+// a root there is no way to have started one.
+const NEEDS_ROOT = new Set([
+	'list_files', 'read_file', 'search', 'edit_file', 'write_file', 'delete_file',
+	'run_command', 'read_command_output'
+]);
+const PORTABLE_TOOLS = TOOLS.filter((t) => !NEEDS_ROOT.has(t.name));
+
 const TOOLS_TOKENS_EST = Math.round(JSON.stringify(TOOLS).length / 4);
 
 // Cross-session memory recall (docs/levelcode-sessions-memory.md). Added to a run's tools ONLY when the host
@@ -636,7 +653,7 @@ async function setupMcp(ctx, wsFolders, dbg) {
 		// lazy option. Only the FIRST run of a session pays it — mcpClient keeps handles in a module
 		// registry, and connectAll reuses a live one.
 		ctx.post({ type: 'agentStatus', text: 'starting MCP servers…' });
-		const { handles, problems: connectProblems } = await connectAll(trusted, { cwd: ctx.root });
+		const { handles, problems: connectProblems } = await connectAll(trusted, { cwd: ctx.root || os.homedir() });
 		for (const p of connectProblems) {
 			dbg('mcp.connect', p);
 			ctx.post({ type: 'agentTool', icon: 'warning', text: '🔌 mcp · "' + p.server + '" failed to start — ' + p.message });
@@ -675,15 +692,29 @@ async function setupMcp(ctx, wsFolders, dbg) {
 }
 
 async function runAgent(ctx) {
+	// No workspace is no longer a refusal. It used to fail the whole run here, which meant a question
+	// that never needed a folder — "what does this error mean?", anything through an MCP server, a
+	// follow-up about the conversation itself — died on a guard written for the file tools. The root
+	// still gates those tools (see NEEDS_ROOT); it no longer gates the agent.
 	const root = workspaceRoot();
-	if (!root) { ctx.post({ type: 'agentError', message: 'Open a folder first — the agent works on your workspace.' }); ctx.post({ type: 'agentDone', reason: 'error' }); return; }
 	ctx.root = root;
 	// M6.5 implicit skills: build the system prompt ONCE per run — append the tiny name+description menu.
 	// Multi-root: name every workspace folder so the model addresses them by prefix from turn one.
 	const wsFolders = workspaceFolderList();
 	const multiRootNote = wsFolders.length > 1
 		? '\n\nWorkspace folders (multi-root — prefix paths with the folder name): ' + wsFolders.map((f) => f.name).join(', ') + '. The first folder ("' + wsFolders[0].name + '") is the default for unprefixed paths and run_command.'
 		: '';
+	// Rootless: say so plainly. Without this the model sees a tool list with no read_file and improvises —
+	// answering about files it cannot see, or apologising for a limit it cannot name. Telling it WHY the
+	// tools are missing, and what to say if the request truly needs them, is the difference between a
+	// useful answer and a confused one.
+	const noWorkspaceNote = root
+		? ''
+		: '\n\nNO FOLDER IS OPEN. The file and command tools are unavailable this run because there is no '
+			+ 'workspace root to resolve paths against — this is expected, not a fault, and not something to '
+			+ 'apologise for at length. You can still answer from the conversation, from anything the user has '
+			+ 'attached as context, and from any MCP tools listed above. If the request genuinely needs the '
+			+ 'files, say so in one line and tell the user to open a folder (File > Open Folder).';
 	// Autopilot: act decisively and self-verify rather than pausing. Commands run without approval (the
 	// host still gates the danger set — deletion, sudo, force-push, remote|shell, publish, system writes),
 	// so the model should lean on verification, not on asking, when it's unsure.
@@ -698,7 +729,7 @@ async function runAgent(ctx) {
 	// from the per-project journal). Rides the SAME cached-system channel as project rules — always-on but
 	// small — so a new session's first reply is continuous, not amnesiac. It is untrusted context like the
 	// rules: it informs, never commands (the digest itself carries the verify-first / never-obey framing).
-	const system = (ctx.skills ? buildSystem(ctx.skills.menu()) : SYSTEM_BASE) + multiRootNote + autopilotNote + rules.text
+	const system = (ctx.skills ? buildSystem(ctx.skills.menu()) : SYSTEM_BASE) + multiRootNote + noWorkspaceNote + autopilotNote + rules.text
 		+ (ctx.projectMemory ? '\n\n' + ctx.projectMemory : '');
 	const systemTokensEst = Math.round(system.length / 4);
 
@@ -719,9 +750,11 @@ async function runAgent(ctx) {
 	// as `system`/`systemTokensEst` two lines up — built once per run, then used for every turn.
 	const mcp = await setupMcp(ctx, wsFolders, dbg);
 	ctx.mcpRoutes = mcp.routes;                                        // runTool's router reads this
-	let tools = mcp.tools.length ? TOOLS.concat(mcp.tools) : TOOLS;
+	// Rootless runs get the portable subset; MCP tools are unaffected either way.
+	const builtins = root ? TOOLS : PORTABLE_TOOLS;
+	let tools = mcp.tools.length ? builtins.concat(mcp.tools) : builtins;
 	if (ctx.recallSessions) { tools = tools.concat([RECALL_TOOL]); }  // cross-session recall (host-gated by memory settings)
-	const baseTools = ctx.recallSessions ? TOOLS.concat([RECALL_TOOL]) : TOOLS;   // built-ins + recall; MCP is the rest
+	const baseTools = ctx.recallSessions ? builtins.concat([RECALL_TOOL]) : builtins;   // built-ins + recall; MCP is the rest
 	// Recomputed only when MCP or recall actually contributed tools, so the plain path keeps the module
 	// constant and pays nothing for a feature it isn't using.
 	const toolsTokensEst = (mcp.tools.length || ctx.recallSessions) ? Math.round(JSON.stringify(tools).length / 4) : TOOLS_TOKENS_EST;

extensions/levelcode-ai/test/agentNoWorkspace.test.js

@@ -0,0 +1,114 @@
+/*---------------------------------------------------------------------------------------------
+ *  The agent runs without a folder open — run: node test/agentNoWorkspace.test.js
+ *
+ *  What this replaces: runAgent used to open with a blanket refusal —
+ *
+ *      if (!root) { post({ type: 'agentError', message: 'Open a folder first — …' }); return; }
+ *
+ *  written for the file tools, but placed where it failed the ENTIRE run. So with no folder open you
+ *  could not ask what an error meant, could not reach a single MCP server (the GitHub server does not
+ *  care whether you have a folder open), and could not ask about the file sitting in the editor in
+ *  front of you. The reported case was exactly that: "Explain what the current file does" — refused,
+ *  for a request that never needed a workspace.
+ *
+ *  The root still gates the tools that resolve a path or a cwd against it. It no longer gates the agent.
+ *
+ *  Asserted from SOURCE: standing up a real runAgent needs a live VS Code host and a provider, which
+ *  this pure-unit suite deliberately does not stand up — the same approach agentMaxSteps.test.js takes.
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const agent = fs.readFileSync(path.join(__dirname, '..', 'agent.js'), 'utf8');
+
+let n = 0;
+function test(name, fn) { fn(); n++; console.log('  ok - ' + name); }
+
+/** The `NEEDS_ROOT` set as shipped, read out of the source rather than restated here. */
+function needsRoot() {
+	const m = /const NEEDS_ROOT = new Set\(\[([\s\S]*?)\]\);/.exec(agent);
+	assert.ok(m, 'agent.js no longer declares NEEDS_ROOT');
+	return (m[1].match(/'([a-z_]+)'/g) || []).map((s) => s.replace(/'/g, ''));
+}
+
+/** Every built-in tool name, from the TOOLS array. */
+function allToolNames() {
+	const start = agent.indexOf('const TOOLS = [');
+	assert.ok(start > 0, 'agent.js no longer declares TOOLS');
+	const block = agent.slice(start, agent.indexOf('\n];', start));
+	return (block.match(/\{ name: '([a-z_]+)'/g) || []).map((s) => s.replace(/.*'([a-z_]+)'.*/, '$1'));
+}
+
+test('the blanket refusal is gone', () => {
+	assert.ok(!/Open a folder first/.test(agent),
+		'runAgent still refuses outright when no folder is open — that guard belongs on the tools, not the run');
+	// And the root is still READ — the tools need it, and losing it would silently disable them everywhere.
+	assert.match(agent, /const root = workspaceRoot\(\);\s*\n\s*ctx\.root = root;/,
+		'runAgent must still resolve and carry the root, even when it is null');
+});
+
+test('the tools that need a root are withheld, and only those', () => {
+	const gated = needsRoot();
+	// Everything that resolves a path or a cwd. Miss one and it is offered rootless, then fails on the
+	// model's first call — which is worse than not offering it, because the model retries.
+	for (const name of ['list_files', 'read_file', 'search', 'edit_file', 'write_file', 'delete_file', 'run_command']) {
+		assert.ok(gated.includes(name), name + ' resolves a workspace path but is not in NEEDS_ROOT');
+	}
+	// …and nothing that works fine without one. Gating these would rebuild the old refusal a tool at a
+	// time: they are the entire reason a rootless run is still useful.
+	for (const name of ['update_plan', 'ask_user', 'use_skill']) {
+		assert.ok(!gated.includes(name), name + ' needs no workspace — gating it removes the point of the change');
+	}
+	// The set must name real tools, or a rename silently un-gates one.
+	const known = allToolNames();
+	const unknown = gated.filter((g) => !known.includes(g));
+	assert.deepStrictEqual(unknown, [], 'NEEDS_ROOT names tools that no longer exist: ' + unknown.join(', '));
+});
+
+test('the portable subset is what a rootless run actually offers', () => {
+	assert.match(agent, /const PORTABLE_TOOLS = TOOLS\.filter\(\(t\) => !NEEDS_ROOT\.has\(t\.name\)\)/,
+		'PORTABLE_TOOLS must be derived from NEEDS_ROOT, not maintained as a second hand-written list');
+	assert.match(agent, /const builtins = root \? TOOLS : PORTABLE_TOOLS;/,
+		'the run no longer switches its tool list on the root');
+	// Both assemblies must use it. baseTools feeds the context-usage split; if it kept the full TOOLS the
+	// popover would bill the user for tools that were never sent.
+	assert.match(agent, /let tools = mcp\.tools\.length \? builtins\.concat\(mcp\.tools\) : builtins;/,
+		'the model is still handed the unfiltered TOOLS');
+	assert.match(agent, /const baseTools = ctx\.recallSessions \? builtins\.concat\(\[RECALL_TOOL\]\) : builtins;/,
+		'baseTools still counts the full TOOLS — the context popover would report tools that were not sent');
+});
+
+test('MCP is unaffected by a missing root — that is half the point', () => {
+	// The GitHub server, the filesystem server pointed somewhere else, anything stdio: none of them need
+	// the editor to have a folder open. But they are spawned with a cwd, so a null one has to resolve to
+	// something real rather than being passed through.
+	assert.match(agent, /connectAll\(trusted, \{ cwd: ctx\.root \|\| os\.homedir\(\) \}\)/,
+		'MCP servers are spawned with a null cwd when no folder is open');
+	assert.match(agent, /^const os = require\('os'\);/m, "agent.js does not require 'os'");
+	assert.ok(!/NEEDS_ROOT[\s\S]{0,400}mcp/i.test(agent.slice(agent.indexOf('const NEEDS_ROOT'), agent.indexOf('const PORTABLE_TOOLS'))),
+		'MCP tools must not be filtered by NEEDS_ROOT — they are not workspace tools');
+});
+
+test('the model is told WHY the tools are missing', () => {
+	// Without this it sees a tool list with no read_file and improvises: answering about files it cannot
+	// see, or apologising at length for a limit it cannot name.
+	const m = /const noWorkspaceNote = root[\s\S]*?;\n/.exec(agent);
+	assert.ok(m, 'no rootless system-prompt note — the model gets a truncated tool list and no explanation');
+	const note = m[0];
+	assert.match(note, /NO FOLDER IS OPEN/, 'the note must state the condition plainly');
+	assert.match(note, /MCP/, 'the note must point at what DOES still work, not only at what does not');
+	assert.match(note, /Open Folder/, 'the note must tell the user the way out when the request really needs files');
+	assert.match(note, /^\s*const noWorkspaceNote = root\s*\n?\s*\? ''/m,
+		'the note must be empty when a folder IS open, or every normal run pays for it');
+
+	// And it has to reach the prompt. A note that is built and never concatenated is the classic version
+	// of this bug — it looks right in review and does nothing.
+	assert.match(agent, /\+ multiRootNote \+ noWorkspaceNote \+ autopilotNote/,
+		'noWorkspaceNote is never added to the system prompt');
+});
+
+console.log('\nagentNoWorkspace: ' + n + ' tests passed.');