Merge branch 'dev' into feat/cs-code-search-tool

# Conflicts:
#	packages/api/src/agent-manager.ts
#	packages/api/tests/agent-manager.test.ts
#	packages/frontend/src/lib/components/ToolPermissions.svelte
#	packages/frontend/src/lib/settings.svelte.ts

4 files changed, 309 insertions, 2 deletions

diff --git a/packages/core/tests/tools/lsp-tool.test.ts b/packages/core/tests/tools/lsp-tool.test.ts
new file mode 100644
index 0000000..7f26522
--- /dev/null
+++ b/packages/core/tests/tools/lsp-tool.test.ts
@@ -0,0 +1,110 @@
+import { describe, expect, it, vi } from "vitest";
+import type { LspManager } from "../../src/lsp/manager.js";
+import type { ResolvedLspServer } from "../../src/lsp/server.js";
+import { createLspTool, type LspToolContext } from "../../src/tools/lsp.js";
+
+const SERVER: ResolvedLspServer = {
+	id: "luau-lsp",
+	extensions: [".luau"],
+	spawn: () => ({ process: {} as never }),
+};
+
+function makeManager(overrides: Partial<LspManager> = {}): LspManager {
+	return {
+		hasServerForFile: vi.fn(() => true),
+		touchFile: vi.fn(async () => {}),
+		getDiagnostics: vi.fn(() => ({})),
+		request: vi.fn(async () => []),
+		getClients: vi.fn(async () => []),
+		shutdownAll: vi.fn(async () => {}),
+		...overrides,
+	} as unknown as LspManager;
+}
+
+function ctx(manager: LspManager, servers = [SERVER]): () => LspToolContext {
+	return () => ({ manager, workingDirectory: "/work", servers });
+}
+
+describe("createLspTool", () => {
+	it("exposes the expected schema/name", () => {
+		const tool = createLspTool(ctx(makeManager()));
+		expect(tool.name).toBe("lsp");
+		expect(tool.description).toMatch(/luau-lsp/i);
+	});
+
+	it("errors when no servers are configured", async () => {
+		const tool = createLspTool(ctx(makeManager(), []));
+		const out = await tool.execute({ operation: "diagnostics", path: "a.luau" });
+		expect(out).toMatch(/no LSP servers are configured/i);
+	});
+
+	it("errors when no server matches the file", async () => {
+		const manager = makeManager({ hasServerForFile: vi.fn(() => false) as never });
+		const tool = createLspTool(ctx(manager));
+		const out = await tool.execute({ operation: "diagnostics", path: "a.ts" });
+		expect(out).toMatch(/no configured LSP server matches/i);
+	});
+
+	it("diagnostics: touches the file then reports errors", async () => {
+		const touchFile = vi.fn(async () => {});
+		const getDiagnostics = vi.fn(() => ({
+			"/work/a.luau": [
+				{
+					range: { start: { line: 2, character: 1 }, end: { line: 2, character: 9 } },
+					severity: 1,
+					message: "bad type",
+				},
+			],
+		}));
+		const manager = makeManager({
+			touchFile: touchFile as never,
+			getDiagnostics: getDiagnostics as never,
+		});
+		const tool = createLspTool(ctx(manager));
+		const out = await tool.execute({ operation: "diagnostics", path: "a.luau" });
+		expect(touchFile).toHaveBeenCalledOnce();
+		expect(out).toContain("ERROR [3:2] bad type");
+	});
+
+	it("diagnostics: reports clean when no errors", async () => {
+		const tool = createLspTool(ctx(makeManager()));
+		const out = await tool.execute({ operation: "diagnostics", path: "a.luau" });
+		expect(out).toMatch(/No errors reported/i);
+	});
+
+	it("hover: requires line and character", async () => {
+		const tool = createLspTool(ctx(makeManager()));
+		const out = await tool.execute({ operation: "hover", path: "a.luau" });
+		expect(out).toMatch(/requires both 'line' and 'character'/i);
+	});
+
+	it("hover: converts 1-based coords to 0-based on the wire", async () => {
+		const request = vi.fn(async () => [{ contents: "hi" }]);
+		const manager = makeManager({ request: request as never });
+		const tool = createLspTool(ctx(manager));
+		await tool.execute({ operation: "hover", path: "a.luau", line: 5, character: 3 });
+		expect(request).toHaveBeenCalledOnce();
+		const arg = request.mock.calls[0]?.[0] as { method: string; params: { position: unknown } };
+		expect(arg.method).toBe("textDocument/hover");
+		expect(arg.params.position).toEqual({ line: 4, character: 2 });
+	});
+
+	it("references: includes declaration context", async () => {
+		const request = vi.fn(async () => []);
+		const manager = makeManager({ request: request as never });
+		const tool = createLspTool(ctx(manager));
+		await tool.execute({ operation: "references", path: "a.luau", line: 1, character: 1 });
+		const arg = request.mock.calls[0]?.[0] as { params: { context?: unknown } };
+		expect(arg.params.context).toEqual({ includeDeclaration: true });
+	});
+
+	it("documentSymbol: does not require a position", async () => {
+		const request = vi.fn(async () => [{ name: "foo" }]);
+		const manager = makeManager({ request: request as never });
+		const tool = createLspTool(ctx(manager));
+		const out = await tool.execute({ operation: "documentSymbol", path: "a.luau" });
+		const arg = request.mock.calls[0]?.[0] as { method: string };
+		expect(arg.method).toBe("textDocument/documentSymbol");
+		expect(out).toContain("foo");
+	});
+});
diff --git a/packages/core/tests/tools/send-to-tab.test.ts b/packages/core/tests/tools/send-to-tab.test.ts
index 4450fc5..21d8032 100644
--- a/packages/core/tests/tools/send-to-tab.test.ts
+++ b/packages/core/tests/tools/send-to-tab.test.ts
@@ -14,6 +14,7 @@ function makeCallbacks(overrides: Partial<SendToTabCallbacks> = {}): SendToTabCa
 		deliver: () => ({ status: "started" }),
 		listOpenHandles: () => [{ handle: "targ", title: "Target" }],
 		self: { id: "self-id", handle: "self" },
+		canReadTab: true,
 		...overrides,
 	};
 }
@@ -24,6 +25,22 @@ describe("createSendToTabTool — schema & description", () => {
 		expect(tool.name).toBe("send_to_tab");
 		expect(tool.description).toContain("fire-and-forget");
 		expect(tool.description.toLowerCase()).toContain("queued");
+		// Description must steer the model away from busy-waiting for a reply.
+		expect(tool.description.toLowerCase()).toContain("do not sleep");
+		expect(tool.description.toLowerCase()).toContain("end your turn");
+	});
+
+	it("mentions read_tab in the description only when canReadTab is true", () => {
+		const tool = createSendToTabTool(makeCallbacks({ canReadTab: true }));
+		expect(tool.description).toContain("read_tab");
+	});
+
+	it("never mentions read_tab in the description when canReadTab is false", () => {
+		const tool = createSendToTabTool(makeCallbacks({ canReadTab: false }));
+		expect(tool.description).not.toContain("read_tab");
+		// Still tells the agent a reply will wake it + to end its turn.
+		expect(tool.description.toLowerCase()).toContain("wake you with a new message");
+		expect(tool.description.toLowerCase()).toContain("end your turn");
 	});
 });
 
@@ -35,11 +52,37 @@ describe("createSendToTabTool — execute()", () => {
 		expect(deliver).toHaveBeenCalledTimes(1);
 		const [targetId, delivered] = deliver.mock.calls[0] ?? [];
 		expect(targetId).toBe("target-id");
-		// Provenance prefix names the sending tab's handle.
-		expect(delivered).toContain("[message from tab self]");
+		// Provenance header names the sending tab's handle and marks it as a
+		// peer agent (not the recipient's own user).
+		expect(delivered).toContain("[message from tab self");
+		expect(delivered).toContain("another agent");
 		expect(delivered).toContain("hello there");
+		// Reply contract: the recipient must answer via send_to_tab back to the
+		// sender's handle, not as a plain text reply to its own user.
+		expect(delivered).toContain('send_to_tab tool with tab_id "self"');
+		expect(delivered).toContain("ONLY reply if");
 		expect(out).toContain("idle");
 		expect(out).toContain("targ");
+		// Sender is steered away from busy-waiting and told to end its turn.
+		expect(out.toLowerCase()).toContain("do not sleep");
+		expect(out.toLowerCase()).toContain("end your turn");
+	});
+
+	it("points the sender at read_tab in the result only when canReadTab is true", async () => {
+		const deliver = vi.fn(() => ({ status: "started" as const }));
+		const tool = createSendToTabTool(makeCallbacks({ deliver, canReadTab: true }));
+		const out = await tool.execute({ tab_id: "targ", message: "hi" });
+		expect(out).toContain("read_tab");
+	});
+
+	it("omits read_tab from the result when canReadTab is false", async () => {
+		const deliver = vi.fn(() => ({ status: "started" as const }));
+		const tool = createSendToTabTool(makeCallbacks({ deliver, canReadTab: false }));
+		const out = await tool.execute({ tab_id: "targ", message: "hi" });
+		expect(out).not.toContain("read_tab");
+		// Still steers away from busy-waiting and toward ending the turn.
+		expect(out.toLowerCase()).toContain("do not sleep");
+		expect(out.toLowerCase()).toContain("end your turn");
 	});
 
 	it("reports the queued status when the target is busy", async () => {
diff --git a/packages/core/tests/tools/summon.test.ts b/packages/core/tests/tools/summon.test.ts
index f59f345..4885a94 100644
--- a/packages/core/tests/tools/summon.test.ts
+++ b/packages/core/tests/tools/summon.test.ts
@@ -239,3 +239,111 @@ describe("createSummonTool — execute() argument forwarding", () => {
 		expect(getResult).toHaveBeenCalled();
 	});
 });
+
+describe("createSummonTool — user-agent-only mode (perm_user_agent without perm_summon)", () => {
+	// userAgentEnabled=true, subagentEnabled=false → the tool spawns ONLY
+	// top-level user agents. `top_level` is implied (and forced), the
+	// subagent/parallel-work prose is dropped, and only the user-agent
+	// catalog group is shown.
+	const subagents: AvailableAgent[] = [
+		{
+			slug: "programmer",
+			name: "Programmer",
+			description: "Codes things",
+			path: "/agents/programmer.toml",
+		},
+	];
+	const userAgents: AvailableAgent[] = [
+		{
+			slug: "default",
+			name: "Default",
+			description: "Default agent",
+			path: "/agents/default.toml",
+		},
+	];
+
+	function userAgentOnlyTool(
+		spawn = vi.fn(async () => "ua-1"),
+		getResult = vi.fn(async () => ({ status: "done" as const, result: "nope" })),
+	) {
+		return {
+			spawn,
+			getResult,
+			tool: createSummonTool(
+				"/tmp/work",
+				{ spawn, getResult },
+				subagents,
+				userAgents,
+				["/agents"],
+				true, // userAgentEnabled
+				false, // subagentEnabled
+			),
+		};
+	}
+
+	it("describes spawning user agents and omits subagent/parallel-work prose", () => {
+		const { tool } = userAgentOnlyTool();
+		expect(tool.description).toContain("Spawn an independent top-level user agent");
+		expect(tool.description).toContain("fire-and-forget");
+		expect(tool.description).not.toContain("Pattern for parallel work");
+		expect(tool.description).not.toContain("Set background=true");
+	});
+
+	it("lists only the user-agent catalog group, not subagents", () => {
+		const { tool } = userAgentOnlyTool();
+		expect(tool.description).toContain("User agents (spawned as independent top-level tabs):");
+		expect(tool.description).toContain("default");
+		// Subagents must not be advertised in user-agent-only mode.
+		expect(tool.description).not.toContain("Subagents (spawned as child tabs):");
+		expect(tool.description).not.toContain("- programmer: Programmer");
+	});
+
+	it("only lists user-agent slugs in the 'agent' parameter description", () => {
+		const { tool } = userAgentOnlyTool();
+		const agentParam = (tool.parameters as unknown as { shape: { agent: { description: string } } })
+			.shape.agent;
+		expect(agentParam.description).toContain("default");
+		expect(agentParam.description).not.toContain("programmer");
+	});
+
+	it("omits the top_level parameter (it is implied)", () => {
+		const { tool } = userAgentOnlyTool();
+		const shape = (tool.parameters as unknown as { shape: Record<string, unknown> }).shape;
+		expect("top_level" in shape).toBe(false);
+	});
+
+	it("omits the background parameter (user agents are fire-and-forget)", () => {
+		const { tool } = userAgentOnlyTool();
+		const shape = (tool.parameters as unknown as { shape: Record<string, unknown> }).shape;
+		expect("background" in shape).toBe(false);
+	});
+
+	it("forces topLevel=true on spawn even when top_level is not passed", async () => {
+		const spawn = vi.fn(async () => "ua-99");
+		const getResult = vi.fn(async () => ({ status: "done" as const, result: "nope" }));
+		const { tool } = userAgentOnlyTool(spawn, getResult);
+		const out = await tool.execute({ task: "do stuff", agent: "default" });
+		expect(out).toContain("User agent spawned successfully");
+		expect(out).toContain("ua-99");
+		expect(out).toContain("fire-and-forget");
+		// Never blocks on a result for fire-and-forget user agents.
+		expect(getResult).not.toHaveBeenCalled();
+		const callArg = spawn.mock.calls[0]?.[0];
+		expect(callArg).toMatchObject({ topLevel: true, agentSlug: "default" });
+	});
+});
+
+describe("createSummonTool — subagentEnabled defaults preserve legacy behavior", () => {
+	it("defaults subagentEnabled=true so omitting it keeps subagent spawning", async () => {
+		const spawn = vi.fn(async () => "tab-1");
+		const getResult = vi.fn(async () => ({ status: "done" as const, result: "child" }));
+		// No userAgentEnabled/subagentEnabled args → legacy subagent-only mode.
+		const tool = createSummonTool("/tmp/work", { spawn, getResult }, [], []);
+		const out = await tool.execute({ task: "x", agent: "programmer" });
+		// Foreground subagent summon blocks and returns the child result.
+		expect(out).toBe("agent_id: tab-1\n\nchild");
+		expect(getResult).toHaveBeenCalled();
+		const callArg = spawn.mock.calls[0]?.[0];
+		expect(callArg).not.toHaveProperty("topLevel");
+	});
+});
diff --git a/packages/core/tests/tools/write-file.test.ts b/packages/core/tests/tools/write-file.test.ts
index f071e12..0dedbfc 100644
--- a/packages/core/tests/tools/write-file.test.ts
+++ b/packages/core/tests/tools/write-file.test.ts
@@ -103,4 +103,50 @@ describe("write_file tool", () => {
 			expect(entries).toEqual([]);
 		});
 	});
+
+	describe("onAfterWrite hook", () => {
+		it("appends the hook's returned string to a successful write", async () => {
+			const tool = createWriteFileTool(workDir, async (abs) => `DIAGNOSTICS for ${abs}`);
+			const result = await tool.execute({ path: "a.luau", content: "local x = 1" });
+			expect(result).toMatch(/successfully wrote/i);
+			expect(result).toContain("DIAGNOSTICS for");
+			expect(result).toContain(join(workDir, "a.luau"));
+		});
+
+		it("does not append when the hook returns empty string", async () => {
+			const tool = createWriteFileTool(workDir, async () => "");
+			const result = await tool.execute({ path: "a.luau", content: "local x = 1" });
+			expect(result.trim()).toMatch(/^Successfully wrote to "a\.luau"\.$/);
+		});
+
+		it("does not run the hook when the write is blocked (traversal)", async () => {
+			let called = false;
+			const tool = createWriteFileTool(workDir, async () => {
+				called = true;
+				return "should not appear";
+			});
+			const result = await tool.execute({ path: "../evil.txt", content: "bad" });
+			expect(result).toMatch(/outside the working directory/i);
+			expect(called).toBe(false);
+		});
+
+		it("swallows hook errors so a throwing hook never fails the write", async () => {
+			const tool = createWriteFileTool(workDir, async () => {
+				throw new Error("lsp blew up");
+			});
+			const result = await tool.execute({ path: "a.luau", content: "local x = 1" });
+			expect(result).toMatch(/successfully wrote/i);
+			expect(result).not.toContain("lsp blew up");
+		});
+
+		it("passes the canonical absolute path to the hook", async () => {
+			let seen = "";
+			const tool = createWriteFileTool(workDir, async (abs) => {
+				seen = abs;
+				return "";
+			});
+			await tool.execute({ path: "nested/b.luau", content: "x" });
+			expect(seen).toBe(join(workDir, "nested/b.luau"));
+		});
+	});
 });