agent: a model-written command is shown as it will run; the shell gets the model's label

Approval and command cards show the command and its explanation through host.displaySafe: the
desktop's identity, and in a tab the shell's forDisplay, which makes bidi overrides, zero-width and
other invisible characters visible so that what is approved is what runs. The shell is still handed
the real string. SpawnOptions carries the model's label (at most 300 characters) for the tab that
mirrors the agent's commands.

Author: ndemianc

extensions/levelcode-ai/agent.js

@@ -459,7 +459,7 @@ function runCommand(root, command, onChunk, onExit, onStart, timeoutMs, opts) {
 		let child;
 		// detached:true → the shell becomes its own process-group leader, so process.kill(-pid) kills the
 		// whole tree (the shell AND the server/children it spawned), not just the shell (which orphans the server).
-		try { child = host.spawn(command, { cwd: root, folders: opts && opts.folders, commit: opts && opts.commit }); }
+		try { child = host.spawn(command, { cwd: root, folders: opts && opts.folders, commit: opts && opts.commit, explanation: opts && opts.explanation }); }
 		catch (e) { if (onExit) { onExit(-1, 0, 'error'); } resolve('ERROR: ' + ((e && e.message) || e)); return; }
 		const killGroup = (sig) => { try { if (child.pid) { process.kill(-child.pid, sig); } else { child.kill(sig); } } catch (e) { try { child.kill(sig); } catch (e2) { /* already gone */ } } };
 		const stop = () => { if (settled || stopped) { return; } stopped = true; killGroup('SIGTERM'); setTimeout(() => { if (!settled) { killGroup('SIGKILL'); } }, 1500); };
@@ -603,11 +603,11 @@ async function runTool(tu, ctx) {
 			// remote|shell, publish, system writes), which always asks. Manual mode asks for everything.
 			const danger = ctx.autopilot ? classifyCommand(cmd) : { dangerous: true, category: null };
 			const approved = danger.dangerous
-				? await ctx.approve({ kind: 'command', command: cmd, explanation: input.explanation || '', danger: danger.category ? dangerLabel(danger.category) : null })
+				? await ctx.approve({ kind: 'command', command: host.displaySafe(cmd), explanation: host.displaySafe(input.explanation || ''), danger: danger.category ? dangerLabel(danger.category) : null })
 				: true;
 			if (!approved) { return 'User skipped this command. Do not retry it.'; }
 			const runId = tu.id || ('run-' + Date.now());
-			ctx.post({ type: 'termRun', id: runId, command: cmd, cwd: path.basename(cwdRoot) || 'workspace', background: bg, explanation: input.explanation || '' });
+			ctx.post({ type: 'termRun', id: runId, command: host.displaySafe(cmd), cwd: path.basename(cwdRoot) || 'workspace', background: bg, explanation: host.displaySafe(input.explanation || '') });
 			const stops = ctx.commandStops;   // shared registry so the Stop button / ■ can kill the process group
 			// Only BACKGROUND commands get a registry entry (read_command_output reads it). Foreground
 			// one-shots keep their old behavior + don't accumulate — the model already gets their output.
@@ -651,7 +651,7 @@ async function runTool(tu, ctx) {
 				ctx.post({ type: 'termExit', id: runId, code: code, ms: ms, how: how });
 			};
 			const onStart = (child, stop) => { if (stops) { stops.set(runId, stop); } };
-			const spawnOpts = Object.assign({ onData }, shellSpawnOpts(ctx, sh));
+			const spawnOpts = Object.assign({ onData, explanation: String(input.explanation || '').slice(0, 300) }, shellSpawnOpts(ctx, sh));
 			if (bg) {
 				// Fire-and-forget: keep streaming + tracking, but return NOW so the agent loop isn't blocked.
 				// No timeout — a background server is meant to run long (Stop / New Chat reap it).

extensions/levelcode-ai/host.js

@@ -31,7 +31,7 @@ const isBrowser = !!globalThis.__LEVELCODE_BROWSER_HOST__;
 /**
  * A shell the browser build can borrow: a LevelCode-owned extension (web/shell) that exports one. It is
  * connected lazily (connectShell), once, the first time a run needs to know whether there is one.
- * @type {{ info: ShellInfo, spawn: (command: string, opts: SpawnOptions) => ChildLike } | null}
+ * @type {{ info: ShellInfo, spawn: (command: string, opts: SpawnOptions) => ChildLike, forDisplay?: (text: string) => string } | null}
  */
 let shell = null;
 
@@ -173,6 +173,7 @@ const SHELL_API_VERSION = 1;
  * @property {string} cwd                       absolute path of a workspace folder, or inside one
  * @property {WorkspaceFolderRef[]} [folders]   the workspace folders, live and in order (a shell mounts each at its root)
  * @property {Record<string,string>} [env]      extra environment
+ * @property {string} [explanation]             the model's own label for the command (at most 300 characters), for a tab that mirrors it
  * @property {(changes: Change[]) => Promise<{ rest: Change[], notes: string[], failed?: number, refused?: boolean }>} [commit]
  *     Agent runs only. Called once, after the command has run to its END (never after Stop, a timeout or an engine
  *     limit: those apply nothing) and BEFORE 'close', with the files the command left changed. The caller validates
@@ -208,9 +209,22 @@ function spawn(command, opts) {
 /** The registered shell's description, or null (always null on the desktop: its shell is the user's own). */
 function shellInfo() { return shell ? shell.info : null; }
 
+/**
+ * A model-written string as the user is shown it on an approval card or a command card: invisible and
+ * direction-changing characters made visible, so what is approved is what runs. The desktop shows text as it
+ * always has; a shell that brings its own rules (the browser's) supplies them.
+ * @param {string} text
+ * @returns {string}
+ */
+function displaySafe(text) {
+	const f = shell && shell.forDisplay;
+	if (typeof f !== 'function') { return text; }
+	try { const out = f(String(text)); return typeof out === 'string' ? out : text; } catch { return text; }
+}
+
 /**
  * Register a shell. Called by connectShell; exported so a test (or a later in-process engine) can register one.
- * @param {{ info: ShellInfo, spawn: Function }} impl
+ * @param {{ info: ShellInfo, spawn: Function, forDisplay?: (text: string) => string }} impl
  * @returns {{ dispose(): void }}
  */
 function registerShell(impl) {
@@ -302,7 +316,7 @@ function findFiles(glob, exclude, max) {
 
 module.exports = {
 	isBrowser, caps,
-	spawn, shellInfo, registerShell, connectShell,
+	spawn, shellInfo, displaySafe, registerShell, connectShell,
 	uriFor, readBytes, readText, readTextOrNull, stat, exists, isBinary, withReads, findFiles, openAuth,
 	// For tests.
 	_path: path,

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

@@ -271,6 +271,33 @@ function ctxFor(over) {
 			vscodeMock.extensions.getExtension = () => undefined;
 		});
 
+		await test('BROWSER, shell registered: the card and the approval show the command through the shell\'s forDisplay; the shell is still handed the real one', async () => {
+			const { agent, host } = load(true);
+			const calls = registerFake(host, { forDisplay: (t) => t.replace(/\u202e/g, '[U+202E]') });
+			const real = 'echo \u202eevil';
+			script = [tool('d1', 'run_command', { command: real, explanation: 'say \u202ehi', }), say('Done: x')];
+			const approvals = [];
+			const ctx = ctxFor({ approve: async (r) => { approvals.push(r); return true; } });
+			const p = agent.runAgent(ctx);
+			await settle(); await settle();
+			assert.strictEqual(approvals.length, 1);
+			assert.strictEqual(approvals[0].command, 'echo [U+202E]evil');
+			assert.strictEqual(approvals[0].explanation, 'say [U+202E]hi');
+			const card = ctx.posted.find((m) => m.type === 'termRun');
+			assert.strictEqual(card.command, 'echo [U+202E]evil');
+			assert.strictEqual(calls[0].command, real, 'what runs is what the model wrote');
+			assert.strictEqual(calls[0].opts.explanation, 'say \u202ehi', 'the mirror tab gets the label, to make safe itself');
+			calls[0].child.emit('close', 0);
+			await p;
+		});
+
+		await test('DESKTOP: displaySafe is the identity, and nothing is registered', async () => {
+			const { host } = load(false);
+			assert.strictEqual(host.displaySafe('a\u202eb'), 'a\u202eb');
+			const { host: bh } = load(true);
+			assert.strictEqual(bh.displaySafe('x'), 'x', 'a browser with no shell, or one without forDisplay, shows text as it is');
+		});
+
 		await test('BROWSER, shell registered: the verify command runs in the shell, and its changes are reviewed too', async () => {
 			const { agent, host } = load(true);
 			const calls = registerFake(host);