Merge branch 'main' into cleanup/plugin-api-scope

src/server/app.test.ts

@@ -15,6 +15,7 @@ import type { SessionProxyDaemon } from "./sessiond/sessionProxyRoutes.js";
 import { PI_WEB_CAPABILITIES } from "../shared/capabilities.js";
 import { machineScopedPluginId } from "../shared/machinePluginIds.js";
 import { MAX_IMAGE_PREVIEW_BYTES } from "../shared/workspaceFiles.js";
+import type { PiWebConfigResponse, PiWebConfigValues } from "../shared/apiTypes.js";
 import type { Project, Workspace } from "./types.js";
 
 let app: FastifyInstance;
@@ -22,12 +23,14 @@ let tempDir: string;
 let projectDir: string;
 let remoteClient: MachineClient | undefined;
 let sessionDaemonRequests: CapturedSessionDaemonRequest[];
+let piWebConfig: PiWebConfigValues;
 
 beforeEach(async () => {
   tempDir = await realpath(await mkdtemp(join(tmpdir(), "pi-web-app-test-")));
   projectDir = join(tempDir, "project");
   remoteClient = undefined;
   sessionDaemonRequests = [];
+  piWebConfig = {};
   app = await buildApp({
     projects: new ProjectService(new ProjectStore(join(tempDir, "projects.json"))),
     workspaces: new WorkspaceService(),
@@ -48,6 +51,7 @@ beforeEach(async () => {
       }),
     }),
     sessionDaemon: fakeSessionDaemon(),
+    config: fakeConfigService(),
     piWebPlugins: {
       manifest: () => Promise.resolve({ plugins: [{ id: "fake", module: "/pi-web-plugins/fake/plugin.js?v=1", source: "test", scope: "local", machineSpecific: false }] }),
       plugins: () => Promise.resolve({ plugins: [{ id: "fake", module: "/pi-web-plugins/fake/plugin.js?v=1", source: "test", scope: "local", machineSpecific: false, enabled: true }] }),
@@ -206,6 +210,23 @@ describe("buildApp", () => {
     expect(request).toHaveBeenCalledWith("POST", "/api/projects/p1/workspaces/w1/terminal-command-runs", createBody);
   });
 
+  it("proxies remote session reloads through the selected machine", async () => {
+    const addResponse = await app.inject({ method: "POST", url: "/api/machines", payload: { name: "Remote", baseUrl: "https://remote.example.test/" } });
+    const remote = addResponse.json<{ id: string }>();
+    const request = vi.fn(() => Promise.resolve({
+      statusCode: 200,
+      headers: { "content-type": "application/json" },
+      body: Readable.from([JSON.stringify({ reloaded: true })]),
+    }));
+    remoteClient = fakeRemoteClient({ request });
+
+    const response = await app.inject({ method: "POST", url: `/api/machines/${remote.id}/sessions/s1/reload`, payload: { cwd: "/repo" } });
+
+    expect(response.statusCode).toBe(200);
+    expect(response.json()).toEqual({ reloaded: true });
+    expect(request).toHaveBeenCalledWith("POST", "/api/sessions/s1/reload", { cwd: "/repo" });
+  });
+
   it("forwards remote JSON request bodies and normalizes remote timeouts", async () => {
     const addResponse = await app.inject({ method: "POST", url: "/api/machines", payload: { name: "Remote", baseUrl: "https://remote.example.test/" } });
     const remote = addResponse.json<{ id: string }>();
@@ -479,6 +500,64 @@ describe("buildApp", () => {
     expect(tooLargeResponse.json()).toEqual({ error: "Image is too large to preview (limit 10 MB)" });
   });
 
+  it("keeps normal file suggestions workspace-local when path access config is invalid", async () => {
+    const addResponse = await app.inject({
+      method: "POST",
+      url: "/api/projects",
+      payload: { name: "Local Suggestions", path: projectDir, create: true },
+    });
+    expect(addResponse.statusCode).toBe(200);
+    await writeFile(join(projectDir, "sdk.md"), "local sdk\n");
+    await mkdir(join(projectDir, ".pi-web"), { recursive: true });
+    await writeFile(join(projectDir, ".pi-web", "config.json"), `${JSON.stringify({ version: 1, pathAccess: { allowedPaths: [""] } }, null, 2)}\n`);
+
+    const response = await app.inject({ method: "GET", url: `/api/files?cwd=${encodeURIComponent(projectDir)}&q=sdk&scope=all` });
+
+    expect(response.statusCode).toBe(200);
+    expect(response.json()).toEqual([{ path: "sdk.md", kind: "other" }]);
+  });
+
+  it("serves project-configured allowed external files through the workspace explorer", async () => {
+    const addResponse = await app.inject({
+      method: "POST",
+      url: "/api/projects",
+      payload: { name: "External", path: projectDir, create: true },
+    });
+    const project = addResponse.json<Project>();
+    const externalDir = join(tempDir, "external-docs");
+    const deniedFile = join(tempDir, "secret.md");
+    await mkdir(externalDir);
+    await writeFile(join(externalDir, "sdk.md"), "external sdk\n");
+    await writeFile(deniedFile, "secret\n");
+    await mkdir(join(projectDir, ".pi-web"), { recursive: true });
+    await writeFile(join(projectDir, ".pi-web", "config.json"), `${JSON.stringify({ version: 1, pathAccess: { allowedPaths: [externalDir] } }, null, 2)}\n`);
+
+    const workspacesResponse = await app.inject({ method: "GET", url: `/api/projects/${project.id}/workspaces` });
+    const workspace = workspacesResponse.json<Workspace[]>()[0];
+    if (workspace === undefined) throw new Error("Expected workspace");
+
+    const fileResponse = await app.inject({ method: "GET", url: `/api/projects/${project.id}/workspaces/${workspace.id}/file?path=${encodeURIComponent(join(externalDir, "sdk.md"))}` });
+    const treeResponse = await app.inject({ method: "GET", url: `/api/projects/${project.id}/workspaces/${workspace.id}/tree?path=${encodeURIComponent(externalDir)}` });
+    const suggestionResponse = await app.inject({ method: "GET", url: `/api/projects/${project.id}/workspaces/${workspace.id}/files?q=${encodeURIComponent(join(externalDir, "s"))}` });
+    const localSuggestionResponse = await app.inject({ method: "GET", url: `/api/projects/${project.id}/workspaces/${workspace.id}/files?q=sdk` });
+    const deniedResponse = await app.inject({ method: "GET", url: `/api/projects/${project.id}/workspaces/${workspace.id}/file?path=${encodeURIComponent(deniedFile)}` });
+
+    expect(fileResponse.statusCode).toBe(200);
+    expect(fileResponse.json()).toMatchObject({ path: join(externalDir, "sdk.md"), content: "external sdk\n", binary: false });
+    expect(treeResponse.statusCode).toBe(200);
+    expect(treeResponse.json()).toMatchObject({
+      path: externalDir,
+      entries: [expect.objectContaining({ name: "sdk.md", path: join(externalDir, "sdk.md"), type: "file" })],
+      truncated: false,
+    });
+    expect(suggestionResponse.statusCode).toBe(200);
+    expect(suggestionResponse.json()).toEqual([{ path: join(externalDir, "sdk.md"), kind: "other" }]);
+    expect(localSuggestionResponse.statusCode).toBe(200);
+    expect(localSuggestionResponse.json()).toEqual([]);
+    expect(deniedResponse.statusCode).toBe(400);
+    expect(deniedResponse.json()).toEqual({ error: "Path is outside allowed paths" });
+  });
+
   it("writes workspace files through the HTTP contract", async () => {
     const addResponse = await app.inject({
       method: "POST",
@@ -490,7 +569,6 @@ describe("buildApp", () => {
     const workspace = workspacesResponse.json<Workspace[]>()[0];
     if (workspace === undefined) throw new Error("Expected workspace");
 
-    // Write a text file
     const writeTextResponse = await app.inject({
       method: "PUT",
       url: `/api/projects/${project.id}/workspaces/${workspace.id}/file?path=${encodeURIComponent("hello.txt")}`,
@@ -499,15 +577,11 @@ describe("buildApp", () => {
     });
     expect(writeTextResponse.statusCode).toBe(200);
     expect(writeTextResponse.json()).toMatchObject({ path: "hello.txt", created: true });
-    const writeBody = writeTextResponse.json<Record<string, unknown>>();
-    expect(typeof writeBody['size']).toBe("number");
+    expect(typeof writeTextResponse.json<{ size: unknown }>().size).toBe("number");
 
-    // Read it back
     const readResponse = await app.inject({ method: "GET", url: `/api/projects/${project.id}/workspaces/${workspace.id}/file?path=${encodeURIComponent("hello.txt")}` });
-    const readBody = readResponse.json<Record<string, unknown>>();
-    expect(readBody['content']).toBe("hello world");
+    expect(readResponse.json<{ content: unknown }>().content).toBe("hello world");
 
-    // Write binary content
     const writeBinaryResponse = await app.inject({
       method: "PUT",
       url: `/api/projects/${project.id}/workspaces/${workspace.id}/file?path=${encodeURIComponent("image.png")}`,
@@ -517,7 +591,6 @@ describe("buildApp", () => {
     expect(writeBinaryResponse.statusCode).toBe(200);
     expect(writeBinaryResponse.json()).toMatchObject({ path: "image.png", created: true });
 
-    // Create intermediate directories (default)
     const writeDeepResponse = await app.inject({
       method: "PUT",
       url: `/api/projects/${project.id}/workspaces/${workspace.id}/file?path=${encodeURIComponent("deep/nested/dir/file.txt")}`,
@@ -526,12 +599,9 @@ describe("buildApp", () => {
     });
     expect(writeDeepResponse.statusCode).toBe(200);
 
-    // Verify the nested file was written
     const readDeepResponse = await app.inject({ method: "GET", url: `/api/projects/${project.id}/workspaces/${workspace.id}/file?path=${encodeURIComponent("deep/nested/dir/file.txt")}` });
-    const readDeepBody = readDeepResponse.json<Record<string, unknown>>();
-    expect(readDeepBody['content']).toBe("deep content");
+    expect(readDeepResponse.json<{ content: unknown }>().content).toBe("deep content");
 
-    // Overwrite an existing file (default)
     const overwriteResponse = await app.inject({
       method: "PUT",
       url: `/api/projects/${project.id}/workspaces/${workspace.id}/file?path=${encodeURIComponent("hello.txt")}`,
@@ -540,7 +610,6 @@ describe("buildApp", () => {
     });
     expect(overwriteResponse.json()).toMatchObject({ path: "hello.txt", created: false });
 
-    // Reject overwrite=false when file exists
     const noOverwriteResponse = await app.inject({
       method: "PUT",
       url: `/api/projects/${project.id}/workspaces/${workspace.id}/file?path=${encodeURIComponent("hello.txt")}&overwrite=false`,
@@ -548,10 +617,8 @@ describe("buildApp", () => {
       headers: { "content-type": "text/plain" },
     });
     expect(noOverwriteResponse.statusCode).toBe(400);
-    const noOverwriteBody = noOverwriteResponse.json<Record<string, unknown>>();
-    expect(noOverwriteBody['error']).toContain("File already exists");
+    expect(noOverwriteResponse.json<{ error: string }>().error).toContain("File already exists");
 
-    // Reject path traversal
     const traversalResponse = await app.inject({
       method: "PUT",
       url: `/api/projects/${project.id}/workspaces/${workspace.id}/file?path=${encodeURIComponent("../../etc/passwd")}`,
@@ -559,10 +626,8 @@ describe("buildApp", () => {
       headers: { "content-type": "text/plain" },
     });
     expect(traversalResponse.statusCode).toBe(400);
-    const traversalBody = traversalResponse.json<Record<string, unknown>>();
-    expect(traversalBody['error']).toContain("Path traversal");
+    expect(traversalResponse.json<{ error: string }>().error).toContain("Path traversal");
 
-    // Reject missing path
     const noPathResponse = await app.inject({
       method: "PUT",
       url: `/api/projects/${project.id}/workspaces/${workspace.id}/file`,
@@ -570,10 +635,8 @@ describe("buildApp", () => {
       headers: { "content-type": "text/plain" },
     });
     expect(noPathResponse.statusCode).toBe(400);
-    const noPathBody = noPathResponse.json<Record<string, unknown>>();
-    expect(noPathBody['error']).toContain("path query parameter is required");
+    expect(noPathResponse.json<{ error: string }>().error).toContain("path query parameter is required");
 
-    // Fail when createDirs=false and parent directory does not exist
     const noDirsResponse = await app.inject({
       method: "PUT",
       url: `/api/projects/${project.id}/workspaces/${workspace.id}/file?path=${encodeURIComponent("nonexistent/parent/file.txt")}&createDirs=false`,
@@ -582,7 +645,6 @@ describe("buildApp", () => {
     });
     expect(noDirsResponse.statusCode).toBe(400);
 
-    // Reject writing to a directory path
     await mkdir(join(projectDir, "subdir"), { recursive: true });
     const dirWriteResponse = await app.inject({
       method: "PUT",
@@ -604,7 +666,6 @@ describe("buildApp", () => {
     const workspace = workspacesResponse.json<Workspace[]>()[0];
     if (workspace === undefined) throw new Error("Expected workspace");
 
-    // Write a file first so we can delete it
     await app.inject({
       method: "PUT",
       url: `/api/projects/${project.id}/workspaces/${workspace.id}/file?path=${encodeURIComponent("to-delete.txt")}`,
@@ -612,7 +673,6 @@ describe("buildApp", () => {
       headers: { "content-type": "text/plain" },
     });
 
-    // Delete existing file
     const deleteResponse = await app.inject({
       method: "DELETE",
       url: `/api/projects/${project.id}/workspaces/${workspace.id}/file?path=${encodeURIComponent("to-delete.txt")}`,
@@ -620,7 +680,6 @@ describe("buildApp", () => {
     expect(deleteResponse.statusCode).toBe(200);
     expect(deleteResponse.json()).toMatchObject({ path: "to-delete.txt", existed: true });
 
-    // Delete non-existent file (idempotent)
     const deleteMissingResponse = await app.inject({
       method: "DELETE",
       url: `/api/projects/${project.id}/workspaces/${workspace.id}/file?path=${encodeURIComponent("missing.txt")}`,
@@ -628,23 +687,19 @@ describe("buildApp", () => {
     expect(deleteMissingResponse.statusCode).toBe(200);
     expect(deleteMissingResponse.json()).toMatchObject({ path: "missing.txt", existed: false });
 
-    // Reject path traversal
     const traversalResponse = await app.inject({
       method: "DELETE",
       url: `/api/projects/${project.id}/workspaces/${workspace.id}/file?path=${encodeURIComponent("../../etc/passwd")}`,
     });
     expect(traversalResponse.statusCode).toBe(400);
-    const deleteTraversalBody = traversalResponse.json<Record<string, unknown>>();
-    expect(deleteTraversalBody['error']).toContain("Path traversal");
+    expect(traversalResponse.json<{ error: string }>().error).toContain("Path traversal");
 
-    // Reject missing path
     const noPathResponse = await app.inject({
       method: "DELETE",
       url: `/api/projects/${project.id}/workspaces/${workspace.id}/file`,
     });
     expect(noPathResponse.statusCode).toBe(400);
-    const deleteNoPathBody = noPathResponse.json<Record<string, unknown>>();
-    expect(deleteNoPathBody['error']).toContain("path query parameter is required");
+    expect(noPathResponse.json<{ error: string }>().error).toContain("path query parameter is required");
   });
 
   it("moves workspace files through the HTTP contract", async () => {
@@ -658,7 +713,6 @@ describe("buildApp", () => {
     const workspace = workspacesResponse.json<Workspace[]>()[0];
     if (workspace === undefined) throw new Error("Expected workspace");
 
-    // Write a file first so we can move it
     await app.inject({
       method: "PUT",
       url: `/api/projects/${project.id}/workspaces/${workspace.id}/file?path=${encodeURIComponent("original.txt")}`,
@@ -666,27 +720,21 @@ describe("buildApp", () => {
       headers: { "content-type": "text/plain" },
     });
 
-    // Move a file to a new path
     const moveResponse = await app.inject({
       method: "POST",
       url: `/api/projects/${project.id}/workspaces/${workspace.id}/file/move?fromPath=${encodeURIComponent("original.txt")}&toPath=${encodeURIComponent("moved.txt")}`,
     });
     expect(moveResponse.statusCode).toBe(200);
     expect(moveResponse.json()).toMatchObject({ fromPath: "original.txt", toPath: "moved.txt" });
-    const moveBody = moveResponse.json<Record<string, unknown>>();
-    expect(typeof moveBody['size']).toBe("number");
+    expect(typeof moveResponse.json<{ size: unknown }>().size).toBe("number");
 
-    // Verify source is gone
     const readSourceResponse = await app.inject({ method: "GET", url: `/api/projects/${project.id}/workspaces/${workspace.id}/file?path=${encodeURIComponent("original.txt")}` });
     expect(readSourceResponse.statusCode).toBe(400);
 
-    // Verify target exists
     const readTargetResponse = await app.inject({ method: "GET", url: `/api/projects/${project.id}/workspaces/${workspace.id}/file?path=${encodeURIComponent("moved.txt")}` });
     expect(readTargetResponse.statusCode).toBe(200);
-    const targetBody = readTargetResponse.json<Record<string, unknown>>();
-    expect(targetBody['content']).toBe("move me");
+    expect(readTargetResponse.json<{ content: unknown }>().content).toBe("move me");
 
-    // Write another file for overwrite test
     await app.inject({
       method: "PUT",
       url: `/api/projects/${project.id}/workspaces/${workspace.id}/file?path=${encodeURIComponent("source2.txt")}`,
@@ -700,14 +748,12 @@ describe("buildApp", () => {
       headers: { "content-type": "text/plain" },
     });
 
-    // Move with overwrite=true succeeds
     const overwriteResponse = await app.inject({
       method: "POST",
       url: `/api/projects/${project.id}/workspaces/${workspace.id}/file/move?fromPath=${encodeURIComponent("source2.txt")}&toPath=${encodeURIComponent("target2.txt")}&overwrite=true`,
     });
     expect(overwriteResponse.statusCode).toBe(200);
 
-    // Move with overwrite=false (default) fails when target exists
     await app.inject({
       method: "PUT",
       url: `/api/projects/${project.id}/workspaces/${workspace.id}/file?path=${encodeURIComponent("source3.txt")}`,
@@ -725,24 +771,20 @@ describe("buildApp", () => {
       url: `/api/projects/${project.id}/workspaces/${workspace.id}/file/move?fromPath=${encodeURIComponent("source3.txt")}&toPath=${encodeURIComponent("target3.txt")}`,
     });
     expect(noOverwriteResponse.statusCode).toBe(400);
-    const moveNoOverwriteBody = noOverwriteResponse.json<Record<string, unknown>>();
-    expect(moveNoOverwriteBody['error']).toContain("File already exists");
+    expect(noOverwriteResponse.json<{ error: string }>().error).toContain("File already exists");
 
-    // Reject path traversal in fromPath
     const traversalFromResponse = await app.inject({
       method: "POST",
       url: `/api/projects/${project.id}/workspaces/${workspace.id}/file/move?fromPath=${encodeURIComponent("../../etc/passwd")}&toPath=${encodeURIComponent("safe.txt")}`,
     });
     expect(traversalFromResponse.statusCode).toBe(400);
 
-    // Reject missing params
     const noParamsResponse = await app.inject({
       method: "POST",
       url: `/api/projects/${project.id}/workspaces/${workspace.id}/file/move`,
     });
     expect(noParamsResponse.statusCode).toBe(400);
-    const noParamsBody = noParamsResponse.json<Record<string, unknown>>();
-    expect(noParamsBody['error']).toContain("fromPath query parameter is required");
+    expect(noParamsResponse.json<{ error: string }>().error).toContain("fromPath query parameter is required");
   });
 });
 
@@ -752,6 +794,26 @@ interface CapturedSessionDaemonRequest {
   body?: unknown;
 }
 
+function fakeConfigService() {
+  return {
+    read: () => piWebConfigResponse(piWebConfig),
+    write: (config: PiWebConfigValues) => {
+      piWebConfig = config;
+      return piWebConfigResponse(config);
+    },
+  };
+}
+
+function piWebConfigResponse(config: PiWebConfigValues): PiWebConfigResponse {
+  return {
+    path: join(tempDir, "config.json"),
+    exists: false,
+    config,
+    effectiveConfig: config,
+    envOverrides: { host: false, port: false, allowedHosts: false, spawnSessions: false, subsessions: false },
+  };
+}
+
 function fakeSessionDaemon(): SessionProxyDaemon {
   return {
     request: (method, path, body) => {

src/server/app.ts

@@ -7,7 +7,8 @@ import fastifyWebsocket from "@fastify/websocket";
 import { ProjectStore } from "./storage/projectStore.js";
 import { ProjectService } from "./projects/projectService.js";
 import { WorkspaceService } from "./workspaces/workspaceService.js";
-import { listFileSuggestions, listPathSuggestions } from "./workspaces/fileSuggestions.js";
+import { isAbsoluteishFileSuggestionQuery, listFileSuggestions, listPathSuggestions } from "./workspaces/fileSuggestions.js";
+import { pathAccessForCwd } from "./workspaces/effectivePathAccess.js";
 import { normalizeRequestCwd } from "./workingDirectory.js";
 import { listDirectorySuggestions } from "./projects/directorySuggestions.js";
 import { SessionDaemonClient } from "../sessiond/sessionDaemonClient.js";
@@ -16,7 +17,7 @@ import { registerWorkspaceExplorerRoutes } from "./workspaceExplorerRoutes.js";
 import { registerGitRoutes } from "./gitRoutes.js";
 import { registerTerminalProxyRoutes } from "./terminalProxyRoutes.js";
 import { registerWorkspaceDeletionRoutes } from "./workspaces/workspaceDeletionRoutes.js";
-import { registerConfigRoutes, type PiWebConfigService } from "./configRoutes.js";
+import { createFilePiWebConfigService, registerConfigRoutes, type PiWebConfigService } from "./configRoutes.js";
 import { PiWebPluginService } from "./piWebPluginService.js";
 import { createPiWebStatusCache } from "./piWebStatusCache.js";
 import { getPiWebRuntime, getPiWebStatus, getPiWebVersionStatus } from "./piWebStatus.js";
@@ -76,13 +77,19 @@ function registerLocalProjectRoutes(app: FastifyInstance, projects: ProjectServi
   });
 }
 
-function registerLocalFileSuggestionRoutes(app: FastifyInstance, prefix: string): void {
+interface LocalFileSuggestionRouteOptions {
+  config?: Pick<PiWebConfigService, "read">;
+}
+
+function registerLocalFileSuggestionRoutes(app: FastifyInstance, projects: ProjectService, workspaces: WorkspaceService, prefix: string, options: LocalFileSuggestionRouteOptions = {}): void {
   app.get<{ Querystring: { cwd?: string; q?: string; kind?: "tracked" | "untracked" | "other"; mode?: "file" | "path"; scope?: "tracked" | "all" } }>(`${prefix}/files`, async (request, reply) => {
     if (request.query.cwd === undefined || request.query.cwd === "") return reply.code(400).send({ error: "cwd query parameter is required" });
     try {
       const cwd = normalizeRequestCwd(request.query.cwd);
-      if (request.query.mode === "path") return await listPathSuggestions(cwd, request.query.q ?? "");
-      return await listFileSuggestions(cwd, request.query.q ?? "", { kind: request.query.kind, scope: request.query.scope });
+      const query = request.query.q ?? "";
+      const pathAccess = isAbsoluteishFileSuggestionQuery(query) ? await pathAccessForCwd(cwd, projects, workspaces, options.config) : undefined;
+      if (request.query.mode === "path") return await listPathSuggestions(cwd, query, pathAccess);
+      return await listFileSuggestions(cwd, query, { kind: request.query.kind, scope: request.query.scope, pathAccess });
     } catch (error) {
       return reply.code(400).send({ error: error instanceof Error ? error.message : String(error) });
     }
@@ -96,6 +103,7 @@ export async function buildApp(deps: AppDependencies = {}): Promise<FastifyInsta
   const projects = deps.projects ?? new ProjectService(new ProjectStore());
   const workspaces = deps.workspaces ?? new WorkspaceService();
   const piWebPlugins = deps.piWebPlugins ?? new PiWebPluginService();
+  const configService = deps.config ?? createFilePiWebConfigService();
   const sessionDaemon = deps.sessionDaemon ?? new SessionDaemonClient();
   const piWebStatusCache = createPiWebStatusCache(() => getPiWebStatus(sessionDaemon), {
     onError: (error) => { app.log.warn({ err: error }, "failed to refresh PI WEB status cache"); },
@@ -118,7 +126,7 @@ export async function buildApp(deps: AppDependencies = {}): Promise<FastifyInsta
   app.get("/api/pi-web/version", async () => getPiWebVersionStatus(sessionDaemon));
   app.get("/api/pi-web/runtime", async () => getPiWebRuntime(sessionDaemon));
   app.get("/api/plugins", async () => piWebPlugins.plugins());
-  registerConfigRoutes(app, deps.config);
+  registerConfigRoutes(app, configService);
 
   registerMachineRoutes(app, machines);
   registerMachinePluginProxyRoutes(app, machines);
@@ -128,8 +136,8 @@ export async function buildApp(deps: AppDependencies = {}): Promise<FastifyInsta
 
   registerSessionProxyRoutes(app, sessionDaemon);
   registerSessionProxyRoutes(app, sessionDaemon, "/api/machines/local");
-  registerWorkspaceExplorerRoutes(app, projects, workspaces);
-  registerWorkspaceExplorerRoutes(app, projects, workspaces, "/api/machines/local");
+  registerWorkspaceExplorerRoutes(app, projects, workspaces, "/api", { config: configService });
+  registerWorkspaceExplorerRoutes(app, projects, workspaces, "/api/machines/local", { config: configService });
   registerGitRoutes(app, projects, workspaces);
   registerGitRoutes(app, projects, workspaces, "/api/machines/local");
   registerTerminalProxyRoutes(app, projects, workspaces, sessionDaemon);
@@ -137,8 +145,8 @@ export async function buildApp(deps: AppDependencies = {}): Promise<FastifyInsta
   registerWorkspaceDeletionRoutes(app, projects, workspaces, sessionDaemon);
   registerWorkspaceDeletionRoutes(app, projects, workspaces, sessionDaemon, "/api/machines/local");
 
-  registerLocalFileSuggestionRoutes(app, "/api");
-  registerLocalFileSuggestionRoutes(app, "/api/machines/local");
+  registerLocalFileSuggestionRoutes(app, projects, workspaces, "/api", { config: configService });
+  registerLocalFileSuggestionRoutes(app, projects, workspaces, "/api/machines/local", { config: configService });
 
   registerMachineProxyRoutes(app, machines);
 

src/server/configRoutes.test.ts

@@ -37,11 +37,11 @@ describe("config routes", () => {
     const response = await app.inject({
       method: "PUT",
       url: "/api/config",
-      payload: { config: { host: "0.0.0.0", port: 9000, allowedHosts: true, shortcuts: { "core:view.chat": "mod+1", "core:session.stop": null }, plugins: { info: { enabled: false, settings: { note: "hidden" } } } } },
+      payload: { config: { host: "0.0.0.0", port: 9000, allowedHosts: true, spawnSessions: true, subsessions: true, shortcuts: { "core:view.chat": "mod+1", "core:session.stop": null }, plugins: { info: { enabled: false, settings: { note: "hidden" } } }, pathAccess: { allowedPaths: ["/tmp"] }, maxUploadBytes: 1234 } },
     });
 
     expect(response.statusCode).toBe(200);
-    expect(savedConfig).toEqual({ host: "0.0.0.0", port: 9000, allowedHosts: true, shortcuts: { "core:view.chat": "mod+1", "core:session.stop": null }, plugins: { info: { enabled: false, settings: { note: "hidden" } } } });
+    expect(savedConfig).toEqual({ host: "0.0.0.0", port: 9000, allowedHosts: true, spawnSessions: true, subsessions: true, shortcuts: { "core:view.chat": "mod+1", "core:session.stop": null }, plugins: { info: { enabled: false, settings: { note: "hidden" } } }, pathAccess: { allowedPaths: ["/tmp"] }, maxUploadBytes: 1234 });
     expect(response.json<PiWebConfigResponse>().config).toEqual(savedConfig);
   });
 
@@ -56,6 +56,30 @@ describe("config routes", () => {
     expect(response.json()).toHaveProperty("error");
     expect(service.write).not.toHaveBeenCalled();
   });
+
+  it("rejects invalid path access payloads before writing", async () => {
+    const response = await app.inject({
+      method: "PUT",
+      url: "/api/config",
+      payload: { config: { pathAccess: { allowedPaths: [""] } } },
+    });
+
+    expect(response.statusCode).toBe(400);
+    expect(response.json()).toHaveProperty("error");
+    expect(service.write).not.toHaveBeenCalled();
+  });
+
+  it("rejects invalid max upload bytes before writing", async () => {
+    const response = await app.inject({
+      method: "PUT",
+      url: "/api/config",
+      payload: { config: { maxUploadBytes: 0 } },
+    });
+
+    expect(response.statusCode).toBe(400);
+    expect(response.json()).toHaveProperty("error");
+    expect(service.write).not.toHaveBeenCalled();
+  });
 });
 
 function responseFor(config: PiWebConfigValues, exists: boolean): PiWebConfigResponse {
@@ -64,6 +88,6 @@ function responseFor(config: PiWebConfigValues, exists: boolean): PiWebConfigRes
     exists,
     config,
     effectiveConfig: config,
-    envOverrides: { host: false, port: false, allowedHosts: false },
+    envOverrides: { host: false, port: false, allowedHosts: false, spawnSessions: false, subsessions: false },
   };
 }

src/server/configRoutes.ts

@@ -58,6 +58,10 @@ function parseConfigRequest(value: unknown): PiWebConfig {
   const allowedHosts = value["allowedHosts"];
   const shortcuts = value["shortcuts"];
   const plugins = value["plugins"];
+  const pathAccess = value["pathAccess"];
+  const maxUploadBytes = value["maxUploadBytes"];
+  const spawnSessions = value["spawnSessions"];
+  const subsessions = value["subsessions"];
   if (host !== undefined) {
     if (typeof host !== "string") throw new Error("PI WEB config host must be a string");
     config.host = host;
@@ -69,6 +73,16 @@ function parseConfigRequest(value: unknown): PiWebConfig {
   if (allowedHosts !== undefined) config.allowedHosts = parseAllowedHostsRequest(allowedHosts);
   if (shortcuts !== undefined) config.shortcuts = parseShortcutsRequest(shortcuts);
   if (plugins !== undefined) config.plugins = parsePluginsRequest(plugins);
+  if (pathAccess !== undefined) config.pathAccess = parsePathAccessRequest(pathAccess);
+  if (maxUploadBytes !== undefined) config.maxUploadBytes = parseMaxUploadBytesRequest(maxUploadBytes);
+  if (spawnSessions !== undefined) {
+    if (typeof spawnSessions !== "boolean") throw new Error("PI WEB config spawnSessions must be a boolean");
+    config.spawnSessions = spawnSessions;
+  }
+  if (subsessions !== undefined) {
+    if (typeof subsessions !== "boolean") throw new Error("PI WEB config subsessions must be a boolean");
+    config.subsessions = subsessions;
+  }
   return config;
 }
 
@@ -88,6 +102,30 @@ function parseShortcutsRequest(value: unknown): Record<string, string | null> {
   }));
 }
 
+function parsePathAccessRequest(value: unknown): NonNullable<PiWebConfig["pathAccess"]> {
+  if (!isRecord(value)) throw new Error("PI WEB config pathAccess must be an object");
+  const allowedPaths = value["allowedPaths"];
+  return {
+    ...(allowedPaths === undefined ? {} : { allowedPaths: parseAllowedPathsRequest(allowedPaths) }),
+  };
+}
+
+function parseAllowedPathsRequest(value: unknown): string[] {
+  if (!isNonEmptyStringArray(value)) {
+    throw new Error("PI WEB config pathAccess.allowedPaths must be an array of non-empty strings");
+  }
+  return value;
+}
+
+function isNonEmptyStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === "string" && item !== "");
+}
+
+function parseMaxUploadBytesRequest(value: unknown): number {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 1) throw new Error("PI WEB config maxUploadBytes must be a positive integer");
+  return value;
+}
+
 function parsePluginsRequest(value: unknown): NonNullable<PiWebConfig["plugins"]> {
   if (!isRecord(value) || Array.isArray(value)) throw new Error("PI WEB config plugins must be an object");
   return Object.fromEntries(Object.entries(value).map(([pluginId, config]) => {
@@ -106,6 +144,8 @@ function piWebConfigEnvOverrides(env: NodeJS.ProcessEnv): PiWebConfigEnvOverride
     host: isEnvSet(env["PI_WEB_HOST"]),
     port: isEnvSet(env["PI_WEB_PORT"]) || isEnvSet(env["PORT"]),
     allowedHosts: isEnvSet(env["PI_WEB_ALLOWED_HOSTS"]),
+    spawnSessions: isEnvSet(env["PI_WEB_SPAWN_SESSIONS"]),
+    subsessions: isEnvSet(env["PI_WEB_SUBSESSIONS"]),
   };
 }
 

src/server/sessiond.ts

@@ -10,20 +10,34 @@ import { AuthService } from "./sessions/authService.js";
 import { registerAuthRoutes } from "./sessions/authRoutes.js";
 import { PiSessionService } from "./sessions/piSessionService.js";
 import { registerSessionRoutes } from "./sessions/sessionRoutes.js";
+import { ProjectScopedSpawnTargetResolver } from "./sessions/spawnTargetResolver.js";
+import { ProjectService } from "./projects/projectService.js";
+import { ProjectStore } from "./storage/projectStore.js";
+import { WorkspaceService } from "./workspaces/workspaceService.js";
 import { sessiondSocketPath } from "../sessiond/config.js";
 import { TerminalService } from "./terminals/terminalService.js";
 import { registerTerminalRoutes } from "./terminals/terminalRoutes.js";
 import { getPiWebRuntimeComponent } from "./piWebStatus.js";
 import { SESSIOND_RUNTIME_CAPABILITIES } from "../shared/capabilities.js";
-import { maxUploadBytes } from "../config.js";
+import { effectivePiWebConfig, maxUploadBytes, spawnSessionsEnabled, subsessionsEnabled } from "../config.js";
 
-const app = Fastify({ logger: true, bodyLimit: maxUploadBytes() });
+const { config } = effectivePiWebConfig();
+const app = Fastify({ logger: true, bodyLimit: maxUploadBytes(process.env, config) });
 await app.register(fastifyWebsocket);
 
 const eventHub = new SessionEventHub();
 const workspaceActivity = new WorkspaceActivityService(eventHub);
 const auth = new AuthService();
-const sessions = new PiSessionService(eventHub, { modelRegistry: auth.modelRegistry, workspaceActivity });
+const spawnTargets = spawnSessionsEnabled(process.env, config)
+  ? new ProjectScopedSpawnTargetResolver({ projects: new ProjectService(new ProjectStore()), workspaces: new WorkspaceService() })
+  : undefined;
+const sessions = new PiSessionService(eventHub, {
+  modelRegistry: auth.modelRegistry,
+  workspaceActivity,
+  logger: app.log,
+  ...(spawnTargets === undefined ? {} : { spawnTargets }),
+  subsessionsEnabled: spawnTargets !== undefined && subsessionsEnabled(process.env, config),
+});
 auth.subscribe((change) => { sessions.applyAuthChange(change); });
 const terminals = new TerminalService(eventHub, workspaceActivity);
 registerWorkspaceActivityRoutes(app, workspaceActivity);

src/server/sessions/attachmentService.test.ts

@@ -30,12 +30,12 @@ describe("saveAttachmentsToWorkspace", () => {
     );
 
     expect(saved).toHaveLength(2);
-    expect(saved[0]?.path.startsWith(`${DEFAULT_ATTACHMENT_FOLDER}/paste-`)).toBe(true);
+    expect(saved[0]?.path.startsWith(`${DEFAULT_ATTACHMENT_FOLDER}/attachment-`)).toBe(true);
     expect(saved[0]?.path.endsWith(".png")).toBe(true);
     expect(saved[1]?.path.endsWith(".webp")).toBe(true);
     expect(saved[0]?.size).toBe(pngBytes.byteLength);
 
-    const folderEntries = await readdir(join(workspace, ".pi-web", "paste"));
+    const folderEntries = await readdir(join(workspace, ".pi-web", "attachments"));
     expect(folderEntries).toHaveLength(2);
 
     const firstPath = saved[0]?.path ?? "";

src/server/sessions/attachmentService.ts

@@ -10,7 +10,7 @@ import { resolveParentInsideWorkspace } from "../workspaces/pathSafety.js";
  * Default workspace-relative folder used when saving pasted/dropped
  * attachments for the agent to read with its own tools.
  */
-export const DEFAULT_ATTACHMENT_FOLDER = ".pi-web/paste";
+export const DEFAULT_ATTACHMENT_FOLDER = ".pi-web/attachments";
 
 export interface InlineImage {
   image: ImageContent;
@@ -42,7 +42,7 @@ export async function attachmentsToInlineImages(attachments: PromptAttachment[])
 }
 
 export interface SaveAttachmentsOptions {
-  /** Workspace-relative folder to write into. Defaults to `.pi-web/paste`. */
+  /** Workspace-relative folder to write into. Defaults to `.pi-web/attachments`. */
   folder?: string;
   /** Clock injection for deterministic tests. */
   now?: () => Date;
@@ -66,7 +66,7 @@ export async function saveAttachmentsToWorkspace(
   const saved: SavedPromptAttachment[] = [];
   for (const [index, attachment] of attachments.entries()) {
     const bytes = Buffer.from(attachment.data, "base64");
-    const filename = `paste-${stamp}-${String(index + 1)}.${extensionForImageMimeType(attachment.mimeType)}`;
+    const filename = `attachment-${stamp}-${String(index + 1)}.${extensionForImageMimeType(attachment.mimeType)}`;
     const relativePath = `${folder}/${filename}`;
     await writeFile(join(folderTarget, filename), bytes);
     saved.push({ path: relativePath, mimeType: attachment.mimeType, size: bytes.byteLength });

src/server/sessions/piSessionManagerGateway.ts

@@ -63,9 +63,9 @@ class SettingsAwarePiSessionManagerGateway implements PiSessionManagerGateway {
     return filterSessionsForCwd(await listSessionsInDir(resolution.sessionDir), cwd);
   }
 
-  create(cwd: string): PiSessionManager {
+  create(cwd: string, options?: { parentSession?: string }): PiSessionManager {
     const resolution = this.resolver.resolve(cwd);
-    return SessionManager.create(cwd, resolution.sessionDir);
+    return SessionManager.create(cwd, resolution.sessionDir, options?.parentSession === undefined ? undefined : { parentSession: options.parentSession });
   }
 
   listAll(): Promise<PiSessionListEntry[]> {

src/server/sessions/piSessionService.test.ts

@@ -3,6 +3,7 @@ import { describe, expect, it, vi } from "vitest";
 import type { GlobalSessionEvent, SessionUiEvent } from "../../shared/apiTypes.js";
 import { SessionEventHub } from "../realtime/sessionEventHub.js";
 import { PiSessionService, type PiAgentSession, type PiSessionManager, type PiSessionRuntime, type PiSessionServiceDependencies } from "./piSessionService.js";
+import type { SpawnTargetDecision } from "./spawnTargetResolver.js";
 
 class CapturingSessionEventHub extends SessionEventHub {
   readonly sessionEvents: { sessionId: string; event: SessionUiEvent }[] = [];
@@ -49,9 +50,10 @@ function sessionRef(id: string, cwd = "/workspace") {
 
 function fakeRuntime(sessionId = "session-1", patch: Partial<TestSession> = {}) {
   const promptCalls: { text: string; options: unknown }[] = [];
+  const customMessageCalls: { message: { customType: string; content: string; display: boolean; details?: unknown }; options: unknown }[] = [];
   const bindExtensionCalls: unknown[] = [];
   const listeners: ((event: unknown) => void)[] = [];
-  const calls = { abort: 0, bindExtensions: bindExtensionCalls, clearQueue: 0, dispose: 0, prompt: promptCalls };
+  const calls = { abort: 0, bindExtensions: bindExtensionCalls, clearQueue: 0, dispose: 0, prompt: promptCalls, sendCustomMessage: customMessageCalls };
   const session: TestSession = {
     sessionId,
     sessionFile: `/tmp/${sessionId}.jsonl`,
@@ -86,6 +88,10 @@ function fakeRuntime(sessionId = "session-1", patch: Partial<TestSession> = {})
       calls.prompt.push({ text, options });
       return Promise.resolve();
     },
+    sendCustomMessage: (message: { customType: string; content: string; display: boolean; details?: unknown }, options: unknown) => {
+      calls.sendCustomMessage.push({ message, options });
+      return Promise.resolve();
+    },
     executeBash: () => Promise.resolve({ output: "", exitCode: 0, cancelled: false, truncated: false }),
     abort: () => {
       calls.abort += 1;
@@ -158,6 +164,7 @@ describe("PiSessionService", () => {
     expect(session).toMatchObject({ id: "session-1", cwd: "/workspace", messageCount: 0 });
     expect(service.activeCount()).toBe(1);
     expect(hub.globalEvents.some((event) => event.type === "status.update" && event.status.sessionId === "session-1")).toBe(true);
+    expect(hub.globalEvents.some((event) => event.type === "session.created" && event.session.id === "session-1" && event.session.cwd === "/workspace")).toBe(true);
 
     await service.dispose();
     expect(fake.calls.abort).toBe(1);
@@ -540,6 +547,32 @@ describe("PiSessionService", () => {
     await service.dispose();
   });
 
+  it("echoes the user message for direct prompts but not command-forwarded ones", async () => {
+    const fake = fakeRuntime("echo-session", {
+      resourceLoader: { getSkills: () => ({ skills: [{ name: "skill-creator" }] }) },
+    });
+    const hub = new CapturingSessionEventHub();
+    const service = new PiSessionService(hub, {
+      createAgentRuntime: runtimeCreator(fake.runtime),
+      sessionManager: sessionGateway([sessionRecord("echo-session")]),
+      heartbeatIntervalMs: 60_000,
+    });
+
+    await service.prompt(sessionRef("echo-session"), "Build the thing");
+    expect(hub.sessionEvents.filter(({ event }) => event.type === "message.append")).toHaveLength(1);
+
+    // The client optimistically renders command-forwarded prompts (e.g. /skill:*),
+    // so the server must not publish a second copy via message.append.
+    await service.runCommand(sessionRef("echo-session"), "/skill:skill-creator");
+    expect(hub.sessionEvents.filter(({ event }) => event.type === "message.append")).toHaveLength(1);
+    expect(fake.calls.prompt).toEqual([
+      { text: "Build the thing", options: undefined },
+      { text: "/skill:skill-creator", options: undefined },
+    ]);
+
+    await service.dispose();
+  });
+
   it("rejects malformed prompt text before opening the runtime", async () => {
     const fake = fakeRuntime("prompt-session");
     const service = new PiSessionService(new CapturingSessionEventHub(), {
@@ -747,4 +780,206 @@ describe("PiSessionService", () => {
     expect(fake.calls.clearQueue).toBe(1);
     await service.dispose();
   });
+
+  describe("spawnSession", () => {
+    function spawnService(decision: SpawnTargetDecision) {
+      const fake = fakeRuntime("spawned-1", { sessionFile: "/tmp/spawned-1.jsonl" });
+      const log: { details: Record<string, unknown>; message: string }[] = [];
+      const service = new PiSessionService(new CapturingSessionEventHub(), {
+        createAgentRuntime: runtimeCreator(fake.runtime),
+        sessionManager: sessionGateway([]),
+        spawnTargets: { resolveSpawnTarget: () => Promise.resolve(decision) },
+        logger: { info: (details, message) => { log.push({ details, message }); } },
+        heartbeatIntervalMs: 60_000,
+      });
+      return { fake, service, log };
+    }
+
+    it("starts a session at the resolved target, delivers the prompt, and logs the spawn", async () => {
+      const { fake, service, log } = spawnService({ allowed: true, cwd: "/workspace-feature" });
+
+      const result = await service.spawnSession({ spawningCwd: "/workspace", prompt: "continue the plan", cwd: "/workspace-feature" });
+
+      expect(result).toEqual({ sessionId: "spawned-1", cwd: "/workspace-feature" });
+      expect(fake.calls.prompt).toEqual([{ text: "continue the plan", options: undefined }]);
+      expect(log).toEqual([{ details: { spawningCwd: "/workspace", sessionId: "spawned-1", cwd: "/workspace-feature", promptLength: 17 }, message: "spawn_session started a new session" }]);
+      await service.dispose();
+    });
+
+    it("rejects an out-of-project target without starting a session", async () => {
+      const { fake, service } = spawnService({ allowed: false, reason: "out-of-project", allowedCwds: ["/workspace"] });
+
+      await expect(service.spawnSession({ spawningCwd: "/workspace", prompt: "go", cwd: "/elsewhere" }))
+        .rejects.toThrow("cwd must be a workspace of this project. Allowed: /workspace");
+      expect(fake.calls.prompt).toEqual([]);
+      expect(service.activeCount()).toBe(0);
+      await service.dispose();
+    });
+
+    it("rejects when the spawning session is not in a registered project", async () => {
+      const { service } = spawnService({ allowed: false, reason: "not-registered" });
+
+      await expect(service.spawnSession({ spawningCwd: "/workspace", prompt: "go", cwd: undefined }))
+        .rejects.toThrow("Spawning session is not in a registered project");
+      await service.dispose();
+    });
+
+    it("is disabled when no spawn target resolver is configured", async () => {
+      const fake = fakeRuntime("spawned-x");
+      const service = new PiSessionService(new CapturingSessionEventHub(), {
+        createAgentRuntime: runtimeCreator(fake.runtime),
+        sessionManager: sessionGateway([]),
+        heartbeatIntervalMs: 60_000,
+      });
+
+      await expect(service.spawnSession({ spawningCwd: "/workspace", prompt: "go", cwd: undefined }))
+        .rejects.toThrow("Spawning sessions is disabled");
+      await service.dispose();
+    });
+  });
+
+  describe("spawnSubsession", () => {
+    function subsessionService(decision: SpawnTargetDecision, heartbeatIntervalMs = 60_000) {
+      const parent = fakeRuntime("parent-1", { sessionFile: "/tmp/parent-1.jsonl" });
+      const child = fakeRuntime("child-1", { sessionFile: "/tmp/child-1.jsonl", sessionManager: fakeSessionManager("/workspace-feature") });
+      const created = [parent.runtime, child.runtime];
+      let index = 0;
+      const createAgentRuntime: RuntimeCreator = async () => {
+        await Promise.resolve();
+        const runtime = created[Math.min(index, created.length - 1)] ?? child.runtime;
+        index += 1;
+        return runtime;
+      };
+      const archived = new Map<string, { sessionId: string; cwd: string; archivedAt: string }>();
+      const archiveStore = {
+        list: () => Promise.resolve([...archived.values()]),
+        get: (sessionId: string) => Promise.resolve(archived.get(sessionId)),
+        archive: (input: { sessionId: string; cwd: string }) => {
+          const record = { sessionId: input.sessionId, cwd: input.cwd, archivedAt: "2026-01-01T00:00:00.000Z" };
+          archived.set(input.sessionId, record);
+          return Promise.resolve(record);
+        },
+        restore: (sessionId: string) => { archived.delete(sessionId); return Promise.resolve(); },
+        isArchived: (sessionId: string) => Promise.resolve(archived.has(sessionId)),
+      };
+      const service = new PiSessionService(new CapturingSessionEventHub(), {
+        createAgentRuntime,
+        sessionManager: sessionGateway([]),
+        archiveStore,
+        spawnTargets: { resolveSpawnTarget: () => Promise.resolve(decision) },
+        heartbeatIntervalMs,
+      });
+      return { parent, child, service };
+    }
+
+    it("records the parent, delivers the prompt, and lists the tracked child", async () => {
+      const { parent, child, service } = subsessionService({ allowed: true, cwd: "/workspace-feature" });
+      await service.start("/workspace"); // bring the parent online so it can be notified
+
+      const result = await service.spawnSubsession({ spawningCwd: "/workspace", parentSessionId: "parent-1", parentSessionFile: "/tmp/parent-1.jsonl", prompt: "do the slice", cwd: "/workspace-feature" });
+
+      expect(result).toEqual({ sessionId: "child-1", cwd: "/workspace-feature" });
+      expect(child.calls.prompt).toEqual([{ text: "do the slice", options: undefined }]);
+      await expect(service.listSubsessions("parent-1")).resolves.toEqual([
+        { sessionId: "child-1", cwd: "/workspace-feature", status: "idle" },
+      ]);
+      void parent;
+      await service.dispose();
+    });
+
+    it("notifies the parent once when the tracked child stops working", async () => {
+      const { parent, child, service } = subsessionService({ allowed: true, cwd: "/workspace-feature" });
+      await service.start("/workspace");
+      await service.spawnSubsession({ spawningCwd: "/workspace", parentSessionId: "parent-1", parentSessionFile: "/tmp/parent-1.jsonl", prompt: "go", cwd: "/workspace-feature" });
+      parent.calls.prompt.length = 0; // ignore the spawn prompt to the child; focus on the parent notification
+
+      child.session.isStreaming = true;
+      child.emit({ type: "agent_start" }); // arm the notification
+      child.session.isStreaming = false;
+      child.emit({ type: "agent_end" }); // fire once
+      child.emit({ type: "turn_end" }); // must not re-notify
+      await new Promise((resolve) => setTimeout(resolve, 20)); // the parent notification is delivered via the async custom-message path
+
+      expect(parent.calls.sendCustomMessage).toHaveLength(1);
+      expect(parent.calls.sendCustomMessage[0]?.message.content).toContain("Subsession child-1 stopped working");
+      expect(parent.calls.sendCustomMessage[0]?.message.customType).toBe("subsession.completion");
+      expect(parent.calls.sendCustomMessage[0]?.options).toEqual({ triggerTurn: true, deliverAs: "followUp" });
+      expect(parent.calls.prompt).toHaveLength(0); // not a user-authored message
+      await service.dispose();
+    });
+
+    it("notifies via the heartbeat when the child settles without a further event", async () => {
+      const { parent, child, service } = subsessionService({ allowed: true, cwd: "/workspace-feature" }, 10);
+      await service.start("/workspace");
+      await service.spawnSubsession({ spawningCwd: "/workspace", parentSessionId: "parent-1", parentSessionFile: "/tmp/parent-1.jsonl", prompt: "go", cwd: "/workspace-feature" });
+      parent.calls.prompt.length = 0;
+
+      // The child works, then settles silently: agent_end arrives while it still
+      // reports active work, so the event-driven latch does not fire here.
+      child.session.isStreaming = true;
+      child.emit({ type: "agent_start" });
+      child.emit({ type: "agent_end" });
+      expect(parent.calls.sendCustomMessage).toHaveLength(0);
+
+      // Once the session settles, the periodic heartbeat re-check notifies.
+      child.session.isStreaming = false;
+      await new Promise((resolve) => setTimeout(resolve, 40));
+
+      expect(parent.calls.sendCustomMessage).toHaveLength(1);
+      expect(parent.calls.sendCustomMessage[0]?.message.content).toContain("Subsession child-1 stopped working");
+      await service.dispose();
+    });
+
+    it("does not notify the parent when a tracked child is archived", async () => {
+      const { parent, child, service } = subsessionService({ allowed: true, cwd: "/workspace-feature" });
+      await service.start("/workspace");
+      await service.spawnSubsession({ spawningCwd: "/workspace", parentSessionId: "parent-1", parentSessionFile: "/tmp/parent-1.jsonl", prompt: "go", cwd: "/workspace-feature" });
+      // Arm the notification, as a real working child would.
+      child.session.isStreaming = true;
+      child.emit({ type: "agent_start" });
+      child.session.isStreaming = false;
+      parent.calls.sendCustomMessage.length = 0;
+
+      await service.archive("child-1");
+      await new Promise((resolve) => setTimeout(resolve, 20));
+
+      expect(parent.calls.sendCustomMessage).toHaveLength(0);
+      await service.dispose();
+    });
+
+    it("reports an archived child's status in the subsession list", async () => {
+      const { service } = subsessionService({ allowed: true, cwd: "/workspace-feature" });
+      await service.start("/workspace");
+      await service.spawnSubsession({ spawningCwd: "/workspace", parentSessionId: "parent-1", parentSessionFile: "/tmp/parent-1.jsonl", prompt: "go", cwd: "/workspace-feature" });
+
+      await service.archive("child-1");
+
+      await expect(service.listSubsessions("parent-1")).resolves.toEqual([
+        { sessionId: "child-1", cwd: "/workspace-feature", status: "archived" },
+      ]);
+      await service.dispose();
+    });
+
+    it("check_subsession and read_subsession refuse sessions that are not the caller's children", async () => {
+      const { service } = subsessionService({ allowed: true, cwd: "/workspace-feature" });
+      await service.start("/workspace");
+      await service.spawnSubsession({ spawningCwd: "/workspace", parentSessionId: "parent-1", parentSessionFile: "/tmp/parent-1.jsonl", prompt: "go", cwd: "/workspace-feature" });
+
+      await expect(service.checkSubsession("someone-else", "child-1")).rejects.toThrow("not one of your subsessions");
+      await expect(service.readSubsession("someone-else", "child-1", {})).rejects.toThrow("not one of your subsessions");
+      await service.dispose();
+    });
+
+    it("is disabled when no spawn target resolver is configured", async () => {
+      const fake = fakeRuntime("nope");
+      const service = new PiSessionService(new CapturingSessionEventHub(), {
+        createAgentRuntime: runtimeCreator(fake.runtime),
+        sessionManager: sessionGateway([]),
+        heartbeatIntervalMs: 60_000,
+      });
+      await expect(service.spawnSubsession({ spawningCwd: "/workspace", parentSessionId: "p", parentSessionFile: undefined, prompt: "go", cwd: undefined }))
+        .rejects.toThrow("Spawning sessions is disabled");
+      await service.dispose();
+    });
+  });
 });

src/server/sessions/piSessionService.ts

@@ -31,11 +31,31 @@ import type { SavedPromptAttachment } from "../../shared/apiTypes.js";
 
 import { cwdPathsEqual } from "../workingDirectory.js";
 import type { WorkspaceActivityService } from "../activity/workspaceActivityService.js";
+import { createSpawnSessionToolDefinition, type SpawnSessionInvocation, type SpawnSessionResult } from "./spawnSessionTool.js";
+import { createSubsessionToolDefinitions, type SpawnSubsessionInvocation, type SpawnSubsessionResult, type SubsessionCheckResult, type SubsessionReadQuery, type SubsessionReadResult, type SubsessionStatus, type SubsessionSummary, type SubsessionToolDeps } from "./spawnSubsessionTool.js";
+import { buildTranscriptView } from "./subsessionTranscript.js";
+import type { SpawnTargetDecision, SpawnTargetResolver } from "./spawnTargetResolver.js";
+
+/**
+ * Minimal structured-logging seam, shaped like Fastify's logger so sessiond can
+ * pass `app.log` directly. Defaults to a no-op so the service stays usable
+ * without booting a server (e.g. in tests).
+ */
+export interface PiSessionLogger {
+  info(details: Record<string, unknown>, message: string): void;
+}
+
+const noopLogger: PiSessionLogger = { info() { /* no-op */ } };
 
 function noop(): void {
   // Intentionally empty default unsubscribe callback.
 }
 
+function spawnTargetError(decision: Extract<SpawnTargetDecision, { allowed: false }>): Error {
+  if (decision.reason === "not-registered") return new Error("Spawning session is not in a registered project");
+  return new Error(`cwd must be a workspace of this project. Allowed: ${decision.allowedCwds.join(", ")}`);
+}
+
 function authLossWarningKey(sessionId: string, provider: string, modelId: string): string {
   return `${sessionId}:${provider}/${modelId}`;
 }
@@ -58,6 +78,7 @@ interface QueuedPrompt {
   kind: QueuedPromptKind;
   text: string;
   images?: ImageContent[];
+  echoUserMessage?: boolean;
 }
 
 function requirePromptText(value: unknown): string {
@@ -108,7 +129,7 @@ export interface PiSessionManager {
 
 export interface PiSessionManagerGateway {
   list(cwd: string): Promise<PiSessionListEntry[]>;
-  create(cwd: string): PiSessionManager;
+  create(cwd: string, options?: { parentSession?: string }): PiSessionManager;
   /**
    * Legacy id-only lookup surface for older clients. This intentionally searches
    * only Pi's default session store, because custom session directories require
@@ -153,6 +174,7 @@ export interface PiAgentSession {
   getSessionStats(): { sessionId: string; totalMessages: number; userMessages: number; assistantMessages: number; toolCalls: number; tokens: ClientSessionStatus["tokens"]; cost: number };
   getContextUsage(): ClientSessionStatus["contextUsage"] | undefined;
   prompt(text: string, options?: { streamingBehavior?: "steer" | "followUp"; images?: ImageContent[] }): Promise<void>;
+  sendCustomMessage(message: { customType: string; content: string; display: boolean; details?: unknown }, options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" }): Promise<void>;
   executeBash(command: string, onChunk?: (chunk: string) => void, options?: { excludeFromContext?: boolean }): Promise<{ output: string; exitCode: number | undefined; cancelled: boolean; truncated: boolean; fullOutputPath?: string }>;
   abort(): Promise<void>;
   clearQueue(): { steering: string[]; followUp: string[] };
@@ -187,10 +209,16 @@ function defaultCreateAgentRuntime(createRuntime: CreateAgentSessionRuntimeFacto
   return createAgentSessionRuntime(createRuntime, { ...options, sessionManager: options.sessionManager });
 }
 
-function createDefaultRuntimeFactory(authStorage: AuthStorage, modelRegistry: ModelRegistryInstance): CreateAgentSessionRuntimeFactory {
+type SpawnSessionFn = (input: SpawnSessionInvocation) => Promise<SpawnSessionResult>;
+
+function createDefaultRuntimeFactory(authStorage: AuthStorage, modelRegistry: ModelRegistryInstance, spawn?: SpawnSessionFn, subsessions?: SubsessionToolDeps): CreateAgentSessionRuntimeFactory {
   return async ({ cwd, agentDir, sessionManager, sessionStartEvent }) => {
     const services = await createAgentSessionServices({ cwd, agentDir, authStorage, modelRegistry });
-    const customTools = [createPiWebEditToolDefinition(cwd)];
+    const customTools = [
+      createPiWebEditToolDefinition(cwd),
+      ...(spawn === undefined ? [] : [createSpawnSessionToolDefinition(cwd, { spawn })]),
+      ...(subsessions === undefined ? [] : createSubsessionToolDefinitions(cwd, subsessions)),
+    ];
     const options = sessionStartEvent === undefined
       ? { services, sessionManager, customTools }
       : { services, sessionManager, sessionStartEvent, customTools };
@@ -232,6 +260,22 @@ export interface PiSessionServiceDependencies {
   modelRegistry?: ModelRegistryInstance;
   heartbeatIntervalMs?: number;
   workspaceActivity?: Pick<WorkspaceActivityService, "applySessionStatus" | "applySessionActivity" | "removeSession" | "reconcileSessionActivity">;
+  /**
+   * When provided, the `spawn_session` tool is registered on every session,
+   * letting the LLM start new sessions scoped to its project's workspaces.
+   * Omit to keep the capability disabled (the tool is never registered).
+   */
+  spawnTargets?: SpawnTargetResolver;
+  /**
+   * Beta: when true (and `spawnTargets` is provided), the tracked-subsession
+   * tools (`spawn_subsession`, `list_subsessions`, `check_subsession`,
+   * `read_subsession`) are
+   * registered on every session. Off by default so the capability can ship in
+   * main without being exposed in releases.
+   */
+  subsessionsEnabled?: boolean;
+  /** Structured logger for notable runtime events (e.g. spawns). */
+  logger?: PiSessionLogger;
 }
 
 export class PiSessionService {
@@ -242,6 +286,16 @@ export class PiSessionService {
   private readonly compactionPromptQueues = new Map<string, QueuedPrompt[]>();
   private readonly compactionDrainTimers = new Map<string, NodeJS.Timeout>();
   private readonly authLossWarnings = new Set<string>();
+  /** Tracked subsession id -> the parent session id that spawned it. */
+  private readonly subsessionParents = new Map<string, string>();
+  /** Parent session id -> the set of tracked subsession ids it spawned. */
+  private readonly subsessionChildren = new Map<string, Set<string>>();
+  /**
+   * Tracked subsession id -> whether a completion notification is armed.
+   * Armed when the child starts working; firing on completion disarms it so a
+   * child that works again (and stops again) notifies the parent each time.
+   */
+  private readonly subsessionNotifyArmed = new Map<string, boolean>();
   private readonly archiveStore: SessionArchiveRepository;
   private readonly agentDir: string;
   private readonly sessionManager: PiSessionManagerGateway;
@@ -249,19 +303,36 @@ export class PiSessionService {
   private readonly createAgentRuntime: CreateAgentRuntime;
   private readonly modelRegistry: ModelRegistryInstance;
   private readonly workspaceActivity: Pick<WorkspaceActivityService, "applySessionStatus" | "applySessionActivity" | "removeSession" | "reconcileSessionActivity"> | undefined;
+  private readonly spawnTargets: SpawnTargetResolver | undefined;
+  private readonly logger: PiSessionLogger;
 
   constructor(private readonly events: SessionEventHub, deps: PiSessionServiceDependencies = {}) {
     this.archiveStore = deps.archiveStore ?? new SessionArchiveStore();
     this.agentDir = deps.agentDir ?? getAgentDir();
     this.sessionManager = deps.sessionManager ?? createPiSessionManagerGateway({ agentDir: this.agentDir });
     this.modelRegistry = deps.modelRegistry ?? ModelRegistry.create(AuthStorage.create());
-    this.createRuntime = deps.createRuntime ?? createDefaultRuntimeFactory(this.modelRegistry.authStorage, this.modelRegistry);
+    this.spawnTargets = deps.spawnTargets;
+    this.logger = deps.logger ?? noopLogger;
+    // Subsessions are a beta capability gated behind their own flag, and they
+    // also require the spawn capability (they share its project-scope resolver).
+    const subsessionsActive = this.spawnTargets !== undefined && deps.subsessionsEnabled === true;
+    this.createRuntime = deps.createRuntime ?? createDefaultRuntimeFactory(
+      this.modelRegistry.authStorage,
+      this.modelRegistry,
+      this.spawnTargets === undefined ? undefined : (input) => this.spawnSession(input),
+      !subsessionsActive ? undefined : {
+        spawn: (input) => this.spawnSubsession(input),
+        list: (parentSessionId) => this.listSubsessions(parentSessionId),
+        check: (parentSessionId, sessionId) => this.checkSubsession(parentSessionId, sessionId),
+        read: (parentSessionId, sessionId, query) => this.readSubsession(parentSessionId, sessionId, query),
+      },
+    );
     this.createAgentRuntime = deps.createAgentRuntime ?? defaultCreateAgentRuntime;
     this.workspaceActivity = deps.workspaceActivity;
     this.heartbeat = setInterval(() => { this.publishHeartbeats(); }, deps.heartbeatIntervalMs ?? 2000);
     this.commandService = new SessionCommandService(
       (sessionId) => this.getActive(sessionId),
-      (sessionId, text) => this.prompt(sessionId, text),
+      (sessionId, text) => this.prompt(sessionId, text, undefined, undefined, { echoUserMessage: false }),
       events,
       {
         onCompactionStart: (session) => {
@@ -289,6 +360,9 @@ export class PiSessionService {
     this.activities.clear();
     this.compactionPromptQueues.clear();
     this.authLossWarnings.clear();
+    this.subsessionParents.clear();
+    this.subsessionChildren.clear();
+    this.subsessionNotifyArmed.clear();
     await Promise.all(activeSessions.map(async (active) => {
       active.unsubscribe();
       this.workspaceActivity?.removeSession(active.runtime.session.sessionId, active.runtime.session.sessionManager.getCwd());
@@ -315,10 +389,10 @@ export class PiSessionService {
     return [...unarchivedSessions, ...archivedSessions];
   }
 
-  async start(cwd: string): Promise<ClientSession> {
-    const active = await this.create(this.sessionManager.create(cwd), cwd);
+  async start(cwd: string, parentSession?: string): Promise<ClientSession> {
+    const active = await this.create(this.sessionManager.create(cwd, parentSession === undefined ? undefined : { parentSession }), cwd);
     const { session } = active.runtime;
-    return {
+    const created: ClientSession = {
       id: session.sessionId,
       path: session.sessionFile ?? "",
       cwd,
@@ -326,7 +400,163 @@ export class PiSessionService {
       modified: new Date().toISOString(),
       messageCount: session.messages.length,
       firstMessage: "",
+      // Include the parent so listeners can nest the new session in the tree
+      // immediately, instead of showing it flat until the next reload.
+      ...(parentSession === undefined ? {} : { parentSessionPath: parentSession }),
     };
+    // Broadcast so other clients (and the spawning agent's UI) can add the new
+    // session to their list without a manual reload.
+    this.events.publishGlobal({ type: "session.created", session: created });
+    return created;
+  }
+
+  /**
+   * Start a new session on behalf of a LLM and deliver an initial prompt to it.
+   * The target cwd is constrained to a workspace of the same registered project
+   * as the spawning session so the new session is visible in the web UI.
+   */
+  async spawnSession(input: SpawnSessionInvocation): Promise<SpawnSessionResult> {
+    if (this.spawnTargets === undefined) throw new Error("Spawning sessions is disabled");
+    const decision = await this.spawnTargets.resolveSpawnTarget(input.spawningCwd, input.cwd);
+    if (!decision.allowed) throw spawnTargetError(decision);
+    const created = await this.start(decision.cwd);
+    await this.prompt(created.id, input.prompt);
+    this.logger.info(
+      { spawningCwd: input.spawningCwd, sessionId: created.id, cwd: decision.cwd, promptLength: input.prompt.length },
+      "spawn_session started a new session",
+    );
+    return { sessionId: created.id, cwd: decision.cwd };
+  }
+
+  /**
+   * Start a *tracked* child session on behalf of a LLM. Identical to
+   * {@link spawnSession} in how the target cwd is resolved, but the child
+   * records its parent (so it shows in the session tree) and is registered so
+   * the parent is notified when it stops working and can inspect it later.
+   */
+  async spawnSubsession(input: SpawnSubsessionInvocation): Promise<SpawnSubsessionResult> {
+    if (this.spawnTargets === undefined) throw new Error("Spawning sessions is disabled");
+    const decision = await this.spawnTargets.resolveSpawnTarget(input.spawningCwd, input.cwd);
+    if (!decision.allowed) throw spawnTargetError(decision);
+    const created = await this.start(decision.cwd, input.parentSessionFile);
+    this.registerSubsession(input.parentSessionId, created.id);
+    await this.prompt(created.id, input.prompt);
+    this.logger.info(
+      { parentSessionId: input.parentSessionId, sessionId: created.id, cwd: decision.cwd, promptLength: input.prompt.length },
+      "spawn_subsession started a tracked child session",
+    );
+    return { sessionId: created.id, cwd: decision.cwd };
+  }
+
+  /** Summaries of the tracked subsessions spawned by `parentSessionId`. */
+  async listSubsessions(parentSessionId: string): Promise<SubsessionSummary[]> {
+    const childIds = this.subsessionChildren.get(parentSessionId);
+    if (childIds === undefined) return [];
+    return Promise.all([...childIds].map(async (childId) => ({ sessionId: childId, ...(await this.subsessionSummaryFields(childId)) })));
+  }
+
+  /** Status and final result of a subsession, scoped to the caller's children. */
+  async checkSubsession(parentSessionId: string, sessionId: string): Promise<SubsessionCheckResult> {
+    const session = await this.openSubsession(parentSessionId, sessionId);
+    const messages = historyMessages(session);
+    return {
+      sessionId,
+      cwd: session.sessionManager.getCwd(),
+      status: await this.subsessionStatus(session),
+      finalText: finalAssistantText(messages),
+      messageCount: messages.length,
+    };
+  }
+
+  /** Filtered, paginated transcript of a subsession, scoped to the caller's children. */
+  async readSubsession(parentSessionId: string, sessionId: string, query: SubsessionReadQuery): Promise<SubsessionReadResult> {
+    const session = await this.openSubsession(parentSessionId, sessionId);
+    const view = buildTranscriptView(historyMessages(session), query);
+    return {
+      sessionId,
+      cwd: session.sessionManager.getCwd(),
+      status: await this.subsessionStatus(session),
+      ...view,
+    };
+  }
+
+  /** Open a session after verifying it is one of the caller's tracked children. */
+  private async openSubsession(parentSessionId: string, sessionId: string): Promise<PiAgentSession> {
+    if (this.subsessionParents.get(sessionId) !== parentSessionId) {
+      throw new Error(`Session ${sessionId} is not one of your subsessions`);
+    }
+    return this.getOrOpen(sessionId);
+  }
+
+  private registerSubsession(parentSessionId: string, childSessionId: string): void {
+    this.subsessionParents.set(childSessionId, parentSessionId);
+    const children = this.subsessionChildren.get(parentSessionId) ?? new Set<string>();
+    children.add(childSessionId);
+    this.subsessionChildren.set(parentSessionId, children);
+    this.subsessionNotifyArmed.set(childSessionId, false);
+  }
+
+  private async subsessionSummaryFields(childSessionId: string): Promise<{ cwd: string; status: SubsessionStatus }> {
+    const active = this.active.get(childSessionId);
+    if (active !== undefined) {
+      return { cwd: active.runtime.cwd, status: await this.subsessionStatus(active.runtime.session) };
+    }
+    const archived = await this.archiveStore.get(childSessionId);
+    if (archived !== undefined) return { cwd: archived.cwd, status: "archived" };
+    return { cwd: "", status: "unknown" };
+  }
+
+  private async subsessionStatus(session: PiAgentSession): Promise<SubsessionStatus> {
+    if (await this.archiveStore.isArchived(session.sessionId)) return "archived";
+    if (this.hasActiveWork(session)) return "working";
+    if (this.activities.get(session.sessionId)?.phase === "error") return "error";
+    return "idle";
+  }
+
+  /**
+   * Drive parent notifications from a tracked child's status. Arms a pending
+   * notification while the child is working, and when it stops fires a single
+   * follow-up message to the parent via {@link prompt} (which queues if the
+   * parent is busy and delivers immediately when it is idle).
+   */
+  private updateSubsessionTracking(session: PiAgentSession): void {
+    const childId = session.sessionId;
+    const parentId = this.subsessionParents.get(childId);
+    if (parentId === undefined) return;
+    if (this.hasActiveWork(session)) {
+      this.subsessionNotifyArmed.set(childId, true);
+      return;
+    }
+    if (this.subsessionNotifyArmed.get(childId) !== true) return;
+    this.subsessionNotifyArmed.set(childId, false);
+    const status: SubsessionStatus = this.activities.get(childId)?.phase === "error" ? "error" : "idle";
+    const finalText = finalAssistantText(historyMessages(session));
+    const preview = finalText === "" ? "(no output)" : truncateForNotification(finalText);
+    const text = `Subsession ${childId} stopped working (status: ${status}). Latest output:\n\n${preview}\n\nUse check_subsession with sessionId "${childId}" for its status and latest output, or read_subsession to look through its full transcript.`;
+    void this.notifyParentOfSubsession(parentId, childId, text);
+  }
+
+  /**
+   * Deliver a subsession-completion notice to the parent as a system-authored
+   * custom message rather than a user message, so it is not attributed to the
+   * human in the transcript. It still wakes an idle parent (`triggerTurn`) and
+   * queues behind in-flight work (`deliverAs: "followUp"`), preserving the
+   * established "queue if busy, send and act if idle" behavior.
+   */
+  private async notifyParentOfSubsession(parentId: string, childId: string, text: string): Promise<void> {
+    try {
+      const session = await this.getOrOpen(parentId);
+      await session.sendCustomMessage(
+        { customType: SUBSESSION_NOTIFICATION_CUSTOM_TYPE, content: text, display: true, details: { sessionId: childId } },
+        { triggerTurn: true, deliverAs: "followUp" },
+      );
+      this.publishStatus(session);
+    } catch (error: unknown) {
+      this.logger.info(
+        { parentSessionId: parentId, sessionId: childId, error: error instanceof Error ? error.message : String(error) },
+        "failed to notify parent of subsession completion",
+      );
+    }
   }
 
   async messages(ref: PiSessionLookup, page?: { before?: number; limit?: number }): Promise<unknown[] | ClientMessagePage> {
@@ -417,8 +647,13 @@ export class PiSessionService {
     return commands.sort((a, b) => a.name.localeCompare(b.name));
   }
 
-  async prompt(ref: PiSessionLookup, text: unknown, streamingBehavior?: unknown, attachments?: unknown): Promise<void> {
+  async prompt(ref: PiSessionLookup, text: unknown, streamingBehavior?: unknown, attachments?: unknown, options?: { echoUserMessage?: boolean }): Promise<void> {
     const promptText = requirePromptText(text);
+    // Command-forwarded prompts (e.g. /skill:*) are expanded by the agent, which
+    // streams the canonical message back. The client doesn't render the raw
+    // command text, so the server must not echo it either, or it would show up
+    // as a transient line that vanishes on reload.
+    const echoUserMessage = options?.echoUserMessage !== false;
     const requestedBehavior = parsePromptStreamingBehavior(streamingBehavior);
     const parsedAttachments = parsePromptAttachments(attachments, { enforceInlineSizeLimit: false });
     const images = (await attachmentsToInlineImages(parsedAttachments)).map((entry) => entry.image);
@@ -433,15 +668,15 @@ export class PiSessionService {
       return;
     }
     if (session.isCompacting) {
-      this.enqueuePromptDuringCompaction(session, promptText, behavior ?? "followUp", images);
+      this.enqueuePromptDuringCompaction(session, promptText, behavior ?? "followUp", images, echoUserMessage);
       return;
     }
-    void this.submitPrompt(session, promptText, behavior, images);
+    void this.submitPrompt(session, promptText, behavior, images, echoUserMessage);
   }
 
-  private submitPrompt(session: PiAgentSession, text: string, behavior: QueuedPromptKind | undefined, images: ImageContent[] = []): Promise<void> {
+  private submitPrompt(session: PiAgentSession, text: string, behavior: QueuedPromptKind | undefined, images: ImageContent[] = [], echoUserMessage = true): Promise<void> {
     this.publishActivity(session, behavior === "steer" ? "steering queued" : behavior === "followUp" ? "message queued" : "prompt accepted", "active");
-    if (behavior === undefined) this.events.publish(session.sessionId, { type: "message.append", message: userMessage(text, images) });
+    if (behavior === undefined && echoUserMessage) this.events.publish(session.sessionId, { type: "message.append", message: userMessage(text, images) });
     const promptOptions = buildPromptOptions(behavior, images);
     const promptPromise = session.prompt(text, promptOptions).catch((error: unknown) => {
       const message = error instanceof Error ? error.message : String(error);
@@ -452,9 +687,9 @@ export class PiSessionService {
     return promptPromise;
   }
 
-  private enqueuePromptDuringCompaction(session: PiAgentSession, text: string, kind: QueuedPromptKind, images: ImageContent[] = []): void {
+  private enqueuePromptDuringCompaction(session: PiAgentSession, text: string, kind: QueuedPromptKind, images: ImageContent[] = [], echoUserMessage = true): void {
     const queue = this.compactionPromptQueues.get(session.sessionId) ?? [];
-    queue.push({ kind, text, ...(images.length > 0 ? { images } : {}) });
+    queue.push({ kind, text, ...(images.length > 0 ? { images } : {}), ...(echoUserMessage ? {} : { echoUserMessage: false }) });
     this.compactionPromptQueues.set(session.sessionId, queue);
     this.publishActivity(session, "message queued during compaction", "active");
     this.publishStatus(session);
@@ -684,6 +919,10 @@ export class PiSessionService {
     this.workspaceActivity?.removeSession(sessionId, active.runtime.session.sessionManager.getCwd());
     this.clearAuthLossWarningsForSession(sessionId);
     this.clearCompactionPromptQueue(sessionId);
+    // Disarm subsession notification before teardown so the abort below cannot
+    // emit a "stopped working" event that notifies the parent (e.g. on archive).
+    // The parent/children link is kept so the parent can still see the child.
+    this.subsessionNotifyArmed.delete(sessionId);
     clearSessionQueue(active.runtime.session);
     active.unsubscribe();
     try {
@@ -772,6 +1011,7 @@ export class PiSessionService {
       if (eventType === "compaction_end") this.scheduleCompactionQueueDrain(session.sessionId);
       if (eventType === "agent_start" || eventType === "agent_end") this.scheduleCompactionQueueDrain(session.sessionId);
       this.publishStatus(session);
+      this.updateSubsessionTracking(session);
     });
     this.active.set(session.sessionId, active);
   }
@@ -798,14 +1038,14 @@ export class PiSessionService {
       const queued = this.takeCompactionPromptQueue(sessionId);
       if (queued.length === 0) return;
       this.publishStatus(session);
-      for (const prompt of queued) void this.submitPrompt(session, prompt.text, prompt.kind, prompt.images);
+      for (const prompt of queued) void this.submitPrompt(session, prompt.text, prompt.kind, prompt.images, prompt.echoUserMessage ?? true);
       return;
     }
 
     const prompt = this.shiftCompactionPrompt(sessionId);
     if (prompt === undefined) return;
     this.publishStatus(session);
-    const submitted = this.submitPrompt(session, prompt.text, undefined, prompt.images);
+    const submitted = this.submitPrompt(session, prompt.text, undefined, prompt.images, prompt.echoUserMessage ?? true);
     void submitted.finally(() => { this.scheduleCompactionQueueDrain(sessionId); });
   }
 
@@ -902,6 +1142,10 @@ export class PiSessionService {
   private publishHeartbeats(): void {
     for (const active of this.active.values()) {
       const { session } = active.runtime;
+      // Re-evaluate subsession completion here too: agent_end can arrive while
+      // the session still reports active work transiently, so the event-driven
+      // latch may not fire. The heartbeat re-checks once the session settles.
+      this.updateSubsessionTracking(session);
       const activity = this.activities.get(session.sessionId);
       if (!this.hasActiveWork(session)) {
         if (activity?.phase === "active") this.publishStatus(session);
@@ -1231,6 +1475,33 @@ function historyMessages(session: PiAgentSession): unknown[] {
   return messages;
 }
 
+/** customType marking a parent-facing subsession-completion notice. */
+const SUBSESSION_NOTIFICATION_CUSTOM_TYPE = "subsession.completion";
+
+const SUBSESSION_NOTIFICATION_PREVIEW_CHARS = 2000;
+
+function truncateForNotification(text: string): string {
+  if (text.length <= SUBSESSION_NOTIFICATION_PREVIEW_CHARS) return text;
+  return `${text.slice(0, SUBSESSION_NOTIFICATION_PREVIEW_CHARS)}…`;
+}
+
+/** Most recent assistant text from a history message list, or "" if none. */
+function finalAssistantText(messages: readonly unknown[]): string {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (!isRecord(message) || message["role"] !== "assistant") continue;
+    const content = message["content"];
+    if (typeof content === "string") return content;
+    if (!Array.isArray(content)) continue;
+    const texts: string[] = [];
+    for (const part of content) {
+      if (isRecord(part) && part["type"] === "text" && typeof part["text"] === "string") texts.push(part["text"]);
+    }
+    if (texts.length > 0) return texts.join("\n").trim();
+  }
+  return "";
+}
+
 function toClientEvent(event: unknown): SessionUiEvent {
   const eventType = getString(event, "type");
   const assistantMessageEvent = getProperty(event, "assistantMessageEvent");

src/server/sessions/sessionCommandService.test.ts

@@ -60,7 +60,9 @@ describe("SessionCommandService", () => {
     const service = new SessionCommandService(() => getActive(active), prompt, eventPublisher());
 
     await expect(service.run("s1", "/missing")).resolves.toEqual({ type: "unsupported", message: "Unknown command: /missing" });
-    await expect(service.run("s1", "/ext arg")).resolves.toEqual({ type: "done", message: "Accepted /ext arg" });
+    // Forwarded runtime commands return a bare done result: the agent streams
+    // back the canonical expanded message, so no synthetic "Accepted" line.
+    await expect(service.run("s1", "/ext arg")).resolves.toEqual({ type: "done" });
     await expect(service.run("s1", "/template arg")).resolves.toMatchObject({ type: "done" });
     await expect(service.run("s1", "/skill:skill-a arg")).resolves.toMatchObject({ type: "done" });
     expect(prompt).toHaveBeenCalledTimes(3);

src/server/sessions/sessionCommandService.ts

@@ -80,8 +80,12 @@ export class SessionCommandService<TSession extends CommandSession = CommandSess
 
     if (!isBuiltinCommand(name)) {
       if (this.isRuntimeCommand(session, name)) {
+        // The command is forwarded to the agent, which expands it (e.g. /skill:*
+        // into a skill block) and streams the canonical message back. That is the
+        // authoritative feedback, so we don't synthesize an extra "Accepted" line
+        // that would only vanish on reload.
         await this.prompt(sessionId, text);
-        return { type: "done", message: `Accepted ${text}` };
+        return { type: "done" };
       }
       return { type: "unsupported", message: `Unknown command: /${name}` };
     }

src/server/sessions/sessionRoutes.test.ts

@@ -175,7 +175,7 @@ class CapturingRouteSessionService extends PiSessionService {
   override saveAttachments(_lookup: string | PiSessionRef, attachments: unknown, folder?: string) {
     const list = Array.isArray(attachments) ? attachments : [];
     return Promise.resolve(list.map((attachment: { mimeType: string; data: string; name?: string }) => ({
-      path: `${folder ?? ".pi-web/paste"}/${attachment.name ?? "file.png"}`,
+      path: `${folder ?? ".pi-web/attachments"}/${attachment.name ?? "file.png"}`,
       mimeType: attachment.mimeType,
       size: Buffer.from(attachment.data, "base64").byteLength,
     })));

src/server/sessions/spawnSessionTool.test.ts

@@ -0,0 +1,37 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { describe, expect, it, vi } from "vitest";
+import { createSpawnSessionToolDefinition } from "./spawnSessionTool.js";
+
+// The spawn tool's execute() never reads ctx, so an empty stub is sufficient.
+// eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- test stub; execute() does not use ctx.
+const ctx = {} as ExtensionContext;
+
+describe("createSpawnSessionToolDefinition", () => {
+  it("passes the spawning cwd and params to the spawn callback and reports success", async () => {
+    const spawn = vi.fn(() => Promise.resolve({ sessionId: "new-1", cwd: "/repos/a-feature" }));
+    const tool = createSpawnSessionToolDefinition("/repos/a", { spawn });
+
+    const result = await tool.execute("call-1", { prompt: "do the thing", cwd: "/repos/a-feature" }, undefined, undefined, ctx);
+
+    expect(spawn).toHaveBeenCalledWith({ spawningCwd: "/repos/a", prompt: "do the thing", cwd: "/repos/a-feature" });
+    expect(result.details).toEqual({ sessionId: "new-1", cwd: "/repos/a-feature" });
+    expect(result.content[0]).toMatchObject({ type: "text", text: "Started session new-1 in /repos/a-feature." });
+  });
+
+  it("defaults cwd to undefined so the service falls back to the spawning cwd", async () => {
+    const spawn = vi.fn(() => Promise.resolve({ sessionId: "new-2", cwd: "/repos/a" }));
+    const tool = createSpawnSessionToolDefinition("/repos/a", { spawn });
+
+    await tool.execute("call-2", { prompt: "continue" }, undefined, undefined, ctx);
+
+    expect(spawn).toHaveBeenCalledWith({ spawningCwd: "/repos/a", prompt: "continue", cwd: undefined });
+  });
+
+  it("propagates the spawn callback error so the agent loop reports it", async () => {
+    const spawn = vi.fn(() => Promise.reject(new Error("cwd must be a workspace of this project. Allowed: /repos/a")));
+    const tool = createSpawnSessionToolDefinition("/repos/a", { spawn });
+
+    await expect(tool.execute("call-3", { prompt: "x", cwd: "/elsewhere" }, undefined, undefined, ctx))
+      .rejects.toThrow("cwd must be a workspace of this project. Allowed: /repos/a");
+  });
+});

src/server/sessions/spawnSessionTool.ts

@@ -0,0 +1,54 @@
+import { Type } from "typebox";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+
+export interface SpawnSessionResult {
+  sessionId: string;
+  cwd: string;
+}
+
+export interface SpawnSessionInvocation {
+  spawningCwd: string;
+  prompt: string;
+  cwd: string | undefined;
+}
+
+export interface SpawnSessionToolDeps {
+  spawn(input: SpawnSessionInvocation): Promise<SpawnSessionResult>;
+}
+
+type SpawnSessionToolDetails = SpawnSessionResult;
+
+const SpawnSessionParams = Type.Object({
+  prompt: Type.String({
+    description: "The first instruction to send to the newly created session. The new session runs independently; you do not receive its output.",
+  }),
+  cwd: Type.Optional(Type.String({
+    description: "Working directory for the new session. Must be a workspace (worktree, or root) of the same project as this session. Defaults to this session's working directory.",
+  })),
+});
+
+/**
+ * Custom tool that lets the LLM start a new, independent pi-web session and
+ * deliver an initial prompt to it. The spawned session is a normal pi-web session
+ * a human can open and interact with. The tool is constructed per-session, so it
+ * carries the spawning session's cwd for project-scope validation.
+ */
+export function createSpawnSessionToolDefinition(spawningCwd: string, deps: SpawnSessionToolDeps) {
+  return defineTool<typeof SpawnSessionParams, SpawnSessionToolDetails>({
+    name: "spawn_session",
+    label: "Spawn session",
+    description: "Start a new, independent pi-web session and send it an initial prompt. Use this to dispatch a fresh agent to continue work or follow a plan. The new session runs on its own and a human can interact with it; you do not receive its output.",
+    promptSnippet: "spawn_session: start a new independent session with a first prompt",
+    parameters: SpawnSessionParams,
+    async execute(_toolCallId, params) {
+      // Failures throw: the agent loop turns the thrown message into an error
+      // tool result the model sees, so the spawning agent can adapt (e.g. pick a
+      // valid workspace) rather than crash.
+      const result = await deps.spawn({ spawningCwd, prompt: params.prompt, cwd: params.cwd });
+      return {
+        content: [{ type: "text", text: `Started session ${result.sessionId} in ${result.cwd}.` }],
+        details: result,
+      };
+    },
+  });
+}

src/server/sessions/spawnSubsessionTool.test.ts

@@ -0,0 +1,149 @@
+import type { ImageContent, TextContent } from "@earendil-works/pi-ai";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { describe, expect, it, vi } from "vitest";
+import { createSubsessionToolDefinitions, type SubsessionToolDeps } from "./spawnSubsessionTool.js";
+
+function ctxFor(sessionId: string, sessionFile: string | undefined): ExtensionContext {
+  const sessionManager = { getSessionId: () => sessionId, getSessionFile: () => sessionFile };
+  // The subsession tools only read sessionManager.getSessionId/getSessionFile.
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- test stub with the minimal surface the tools use.
+  return { sessionManager } as unknown as ExtensionContext;
+}
+
+function tools(deps: Partial<SubsessionToolDeps>) {
+  const full: SubsessionToolDeps = {
+    spawn: deps.spawn ?? vi.fn(() => Promise.resolve({ sessionId: "x", cwd: "/repos/a" })),
+    list: deps.list ?? vi.fn(() => Promise.resolve([])),
+    check: deps.check ?? vi.fn(() => Promise.resolve({ sessionId: "x", cwd: "/repos/a", status: "idle" as const, finalText: "", messageCount: 0 })),
+    read: deps.read ?? vi.fn(() => Promise.resolve({ sessionId: "x", cwd: "/repos/a", status: "idle" as const, entries: [], total: 0, matched: 0, start: 0, hasMore: false })),
+  };
+  const definitions = createSubsessionToolDefinitions("/repos/a", full);
+  const find = (name: string) => {
+    const tool = definitions.find((definition) => definition.name === name);
+    if (tool === undefined) throw new Error(`missing tool ${name}`);
+    return tool;
+  };
+  return { spawn: find("spawn_subsession"), list: find("list_subsessions"), check: find("check_subsession"), read: find("read_subsession") };
+}
+
+function firstText(content: readonly (TextContent | ImageContent)[]): string {
+  const first = content[0];
+  return first?.type === "text" ? first.text : "";
+}
+
+describe("createSubsessionToolDefinitions", () => {
+  it("spawn_subsession forwards parent identity and params from the live context", async () => {
+    const spawn = vi.fn(() => Promise.resolve({ sessionId: "child-1", cwd: "/repos/a-feature" }));
+    const { spawn: spawnTool } = tools({ spawn });
+
+    const result = await spawnTool.execute("call-1", { prompt: "do it", cwd: "/repos/a-feature" }, undefined, undefined, ctxFor("parent-1", "/sessions/parent-1.jsonl"));
+
+    expect(spawn).toHaveBeenCalledWith({
+      spawningCwd: "/repos/a",
+      parentSessionId: "parent-1",
+      parentSessionFile: "/sessions/parent-1.jsonl",
+      prompt: "do it",
+      cwd: "/repos/a-feature",
+    });
+    expect(result.details).toEqual({ sessionId: "child-1", cwd: "/repos/a-feature" });
+    expect(firstText(result.content)).toContain("Started subsession child-1");
+  });
+
+  it("list_subsessions reports the caller's subsessions and their status", async () => {
+    const list = vi.fn(() => Promise.resolve([
+      { sessionId: "child-1", cwd: "/repos/a", status: "working" as const },
+      { sessionId: "child-2", cwd: "/repos/a", status: "idle" as const },
+    ]));
+    const { list: listTool } = tools({ list });
+
+    const result = await listTool.execute("call-2", {}, undefined, undefined, ctxFor("parent-1", undefined));
+
+    expect(list).toHaveBeenCalledWith("parent-1");
+    expect(result.details).toEqual({ subsessions: [
+      { sessionId: "child-1", cwd: "/repos/a", status: "working" },
+      { sessionId: "child-2", cwd: "/repos/a", status: "idle" },
+    ] });
+    expect(firstText(result.content)).toContain("child-1 [working]");
+  });
+
+  it("list_subsessions reports an empty state", async () => {
+    const { list: listTool } = tools({ list: vi.fn(() => Promise.resolve([])) });
+    const result = await listTool.execute("call-3", {}, undefined, undefined, ctxFor("parent-1", undefined));
+    expect(result.content[0]).toMatchObject({ type: "text", text: "You have not spawned any subsessions." });
+  });
+
+  it("check_subsession scopes by parent and returns the final result", async () => {
+    const check = vi.fn(() => Promise.resolve({ sessionId: "child-1", cwd: "/repos/a", status: "idle" as const, finalText: "all done", messageCount: 4 }));
+    const { check: checkTool } = tools({ check });
+
+    const result = await checkTool.execute("call-4", { sessionId: "child-1" }, undefined, undefined, ctxFor("parent-1", undefined));
+
+    expect(check).toHaveBeenCalledWith("parent-1", "child-1");
+    expect(result.details).toMatchObject({ sessionId: "child-1", status: "idle", finalText: "all done" });
+    expect(firstText(result.content)).toContain("all done");
+  });
+
+  it("check_subsession propagates scope errors so the agent loop reports them", async () => {
+    const check = vi.fn(() => Promise.reject(new Error("Session child-9 is not one of your subsessions")));
+    const { check: checkTool } = tools({ check });
+
+    await expect(checkTool.execute("call-5", { sessionId: "child-9" }, undefined, undefined, ctxFor("parent-1", undefined)))
+      .rejects.toThrow("not one of your subsessions");
+  });
+
+  it("read_subsession forwards filter params and renders the transcript", async () => {
+    const read = vi.fn(() => Promise.resolve({
+      sessionId: "child-1", cwd: "/repos/a", status: "idle" as const,
+      entries: [{ index: 2, role: "assistant" as const, parts: [{ kind: "text" as const, text: "the answer" }] }],
+      total: 5, matched: 1, start: 2, hasMore: false,
+    }));
+    const { read: readTool } = tools({ read });
+
+    const result = await readTool.execute("call-6", { sessionId: "child-1", roles: ["assistant"], maxChars: 200 }, undefined, undefined, ctxFor("parent-1", undefined));
+
+    expect(read).toHaveBeenCalledWith("parent-1", "child-1", { roles: ["assistant"], maxChars: 200 });
+    expect(result.details).toMatchObject({ sessionId: "child-1", matched: 1 });
+    expect(firstText(result.content)).toContain("the answer");
+  });
+
+  it("read_subsession renders raw tool-call args and the truncation marker in the model-facing text", async () => {
+    const read = vi.fn(() => Promise.resolve({
+      sessionId: "child-1", cwd: "/repos/a", status: "idle" as const,
+      entries: [{
+        index: 1, role: "assistant" as const, parts: [
+          { kind: "tool_call" as const, toolName: "bash", summary: "ls", args: { command: "ls -la" } },
+          { kind: "text" as const, text: "clipped", truncated: { shown: 7, full: 50 } },
+        ],
+      }],
+      total: 3, matched: 1, start: 1, hasMore: false,
+    }));
+    const { read: readTool } = tools({ read });
+
+    const result = await readTool.execute("call-7", { sessionId: "child-1", includeToolArgs: true }, undefined, undefined, ctxFor("parent-1", undefined));
+    const text = firstText(result.content);
+    expect(text).toContain("command"); // raw args surfaced in text, not only details
+    expect(text).toContain("ls -la");
+    expect(text).toContain("[+43 chars truncated"); // 50 - 7
+  });
+
+  it("read_subsession distinguishes an empty page-window from a zero-match result", async () => {
+    const read = vi.fn(() => Promise.resolve({
+      sessionId: "child-1", cwd: "/repos/a", status: "idle" as const,
+      entries: [], total: 5, matched: 4, start: 0, hasMore: false,
+    }));
+    const { read: readTool } = tools({ read });
+
+    const result = await readTool.execute("call-8", { sessionId: "child-1", before: 0 }, undefined, undefined, ctxFor("parent-1", undefined));
+    const text = firstText(result.content);
+    expect(text).toContain("4 matched"); // not "nothing matched"
+    expect(text).not.toContain("nothing matched");
+  });
+
+  it("read_subsession propagates scope errors so the agent loop reports them", async () => {
+    const read = vi.fn(() => Promise.reject(new Error("Session child-9 is not one of your subsessions")));
+    const { read: readTool } = tools({ read });
+
+    await expect(readTool.execute("call-9", { sessionId: "child-9" }, undefined, undefined, ctxFor("parent-1", undefined)))
+      .rejects.toThrow("not one of your subsessions");
+  });
+});

src/server/sessions/spawnSubsessionTool.ts

@@ -0,0 +1,242 @@
+import { Type } from "typebox";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import type { TranscriptContentKind, TranscriptEntry, TranscriptRole, TranscriptView } from "./subsessionTranscript.js";
+
+/** Lifecycle phase of a tracked subsession as seen by its parent. */
+export type SubsessionStatus = "working" | "idle" | "error" | "archived" | "unknown";
+
+export interface SpawnSubsessionResult {
+  sessionId: string;
+  cwd: string;
+}
+
+export interface SpawnSubsessionInvocation {
+  /** cwd of the session that invoked the tool (used for project-scope checks). */
+  spawningCwd: string;
+  /** Session id of the parent; the spawned session is tracked against it. */
+  parentSessionId: string;
+  /** Session file of the parent, recorded in the child's `parentSession` header. */
+  parentSessionFile: string | undefined;
+  prompt: string;
+  cwd: string | undefined;
+}
+
+export interface SubsessionSummary {
+  sessionId: string;
+  cwd: string;
+  status: SubsessionStatus;
+}
+
+/** Quick glance at a subsession: status plus its most recent assistant output. */
+export interface SubsessionCheckResult {
+  sessionId: string;
+  cwd: string;
+  status: SubsessionStatus;
+  finalText: string;
+  messageCount: number;
+}
+
+/** Exploratory transcript read: a filtered, paginated slice of the subsession's history. */
+export interface SubsessionReadResult extends TranscriptView {
+  sessionId: string;
+  cwd: string;
+  status: SubsessionStatus;
+}
+
+/** Filters the parent passes to narrow a transcript read; mirrors {@link TranscriptQuery}. */
+export interface SubsessionReadQuery {
+  roles?: TranscriptRole[];
+  include?: TranscriptContentKind[];
+  search?: string;
+  maxChars?: number;
+  includeToolArgs?: boolean;
+  before?: number;
+  limit?: number;
+}
+
+export interface SubsessionToolDeps {
+  spawn(input: SpawnSubsessionInvocation): Promise<SpawnSubsessionResult>;
+  list(parentSessionId: string): Promise<SubsessionSummary[]>;
+  check(parentSessionId: string, sessionId: string): Promise<SubsessionCheckResult>;
+  read(parentSessionId: string, sessionId: string, query: SubsessionReadQuery): Promise<SubsessionReadResult>;
+}
+
+const SpawnSubsessionParams = Type.Object({
+  prompt: Type.String({
+    description: "The first instruction to send to the new tracked subsession.",
+  }),
+  cwd: Type.Optional(Type.String({
+    description: "Working directory for the subsession. Must be a workspace (worktree, or root) of the same project as this session. Defaults to this session's working directory.",
+  })),
+});
+
+const ListSubsessionsParams = Type.Object({});
+
+const CheckSubsessionParams = Type.Object({
+  sessionId: Type.String({
+    description: "Id of a subsession you spawned (as returned by spawn_subsession or list_subsessions).",
+  }),
+});
+
+const ReadSubsessionParams = Type.Object({
+  sessionId: Type.String({
+    description: "Id of a subsession you spawned (as returned by spawn_subsession or list_subsessions).",
+  }),
+  roles: Type.Optional(Type.Array(
+    Type.Union([Type.Literal("assistant"), Type.Literal("user"), Type.Literal("tool"), Type.Literal("system"), Type.Literal("custom")]),
+    { description: "Message roles to include. Omit for all roles." },
+  )),
+  include: Type.Optional(Type.Array(
+    Type.Union([Type.Literal("text"), Type.Literal("thinking"), Type.Literal("tool_call"), Type.Literal("tool_result"), Type.Literal("image")]),
+    { description: "Content kinds to keep within messages. Omit for all kinds." },
+  )),
+  search: Type.Optional(Type.String({
+    description: "Case-insensitive substring; keep only messages whose text or tool name matches. Always searches full message content, even when maxChars is set.",
+  })),
+  maxChars: Type.Optional(Type.Integer({
+    minimum: 0,
+    description: "Truncate each text/thinking/tool-result value to this many characters; clipped parts are marked '[+N chars truncated]'. Omit for full, untruncated text (there is no default, so truncation only happens when you ask for it).",
+  })),
+  includeToolArgs: Type.Optional(Type.Boolean({
+    description: "Include raw tool-call arguments (can be large). A compact one-line summary of each call is always shown regardless.",
+  })),
+  before: Type.Optional(Type.Integer({
+    minimum: 0,
+    description: "Return only messages before this transcript index; page backward by passing the previous response's 'start'.",
+  })),
+  limit: Type.Optional(Type.Integer({
+    minimum: 1,
+    description: "Maximum number of most-recent matching messages to return within the window (returned in chronological order). Defaults to 50.",
+  })),
+});
+
+function statusLine(summary: SubsessionSummary): string {
+  return `- ${summary.sessionId} [${summary.status}] in ${summary.cwd}`;
+}
+
+function renderEntry(entry: TranscriptEntry): string {
+  const header = `#${String(entry.index)} ${entry.role}`;
+  const body = entry.parts.map(renderPart).filter((line) => line !== "").join("\n");
+  return body === "" ? header : `${header}\n${body}`;
+}
+
+function clipNotice(part: TranscriptEntry["parts"][number]): string {
+  if ((part.kind === "text" || part.kind === "thinking" || part.kind === "tool_result") && part.truncated !== undefined) {
+    return ` [+${String(part.truncated.full - part.truncated.shown)} chars truncated; re-read with a larger maxChars]`;
+  }
+  return "";
+}
+
+function renderPart(part: TranscriptEntry["parts"][number]): string {
+  if (part.kind === "text") return `${part.text}${clipNotice(part)}`;
+  if (part.kind === "thinking") return `[thinking] ${part.text}${clipNotice(part)}`;
+  if (part.kind === "tool_call") {
+    // Raw args are only present when the caller asked (includeToolArgs); when
+    // present, surface them in the model-facing text, not just `details`.
+    const args = "args" in part && part.args !== undefined ? `\n  args: ${JSON.stringify(part.args)}` : "";
+    return `[tool ${part.toolName}] ${part.summary}${args}`;
+  }
+  if (part.kind === "tool_result") return `[result${part.isError ? " error" : ""}${part.toolName === undefined ? "" : ` ${part.toolName}`}] ${part.text}${clipNotice(part)}`;
+  return "[image]";
+}
+
+function renderTranscript(result: SubsessionReadResult): string {
+  const last = result.entries[result.entries.length - 1];
+  // Distinguish "nothing matched at all" (widen filters) from "matches exist but
+  // this page/window is empty" (page differently) so the agent isn't misled.
+  const range = last === undefined
+    ? (result.matched === 0
+      ? "no messages matched your filters"
+      : `no messages in this window (${String(result.matched)} matched outside it)`)
+    : `messages ${String(result.start)}–${String(last.index)} of ${String(result.total)} (${String(result.matched)} matched)`;
+  const more = result.hasMore ? `\n\nMore matching messages exist earlier; page back with before: ${String(result.start)}.` : "";
+  // Empty entries with matches means the `before` cursor excluded every match
+  // (they all sit at index >= before): the agent paged too far back and should
+  // raise `before` or omit it, not page back further.
+  const body = result.entries.length > 0
+    ? result.entries.map(renderEntry).join("\n\n")
+    : (result.matched === 0
+      ? "(nothing matched; try widening roles/include, dropping search, or raising limit)"
+      : `(no messages before index ${String(result.start)}; all ${String(result.matched)} matches are later — raise 'before' or omit it)`);
+  return `Subsession ${result.sessionId} [${result.status}] — ${range}:\n\n${body}${more}`;
+}
+
+/**
+ * Tools that let an agent spawn *tracked* child sessions and inspect them.
+ *
+ * Unlike `spawn_session` (fire-and-forget peers), a subsession records its
+ * parent in its session header, the parent is notified when it stops working,
+ * and the parent may read its transcript/result. The tools are constructed
+ * per-session, carrying the spawning cwd for project-scope validation; the
+ * parent's identity is taken from the live extension context at call time.
+ */
+export function createSubsessionToolDefinitions(spawningCwd: string, deps: SubsessionToolDeps) {
+  const spawnTool = defineTool<typeof SpawnSubsessionParams, SpawnSubsessionResult>({
+    name: "spawn_subsession",
+    label: "Spawn subsession",
+    description: "Start a tracked child session and send it an initial prompt. The subsession runs independently and a human can interact with it, but unlike spawn_session it is linked to you: you are notified when it stops working (finished, idle, or errored), and you can inspect it with list_subsessions, check_subsession (a quick glance at its latest output), and read_subsession (read through its transcript). Use this to delegate work you intend to follow up on.",
+    promptSnippet: "spawn_subsession: start a tracked child session you will be notified about",
+    parameters: SpawnSubsessionParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const parentSessionId = ctx.sessionManager.getSessionId();
+      const parentSessionFile = ctx.sessionManager.getSessionFile() ?? undefined;
+      const result = await deps.spawn({ spawningCwd, parentSessionId, parentSessionFile, prompt: params.prompt, cwd: params.cwd });
+      return {
+        content: [{ type: "text", text: `Started subsession ${result.sessionId} in ${result.cwd}. You will be notified when it stops working.` }],
+        details: result,
+      };
+    },
+  });
+
+  const listTool = defineTool<typeof ListSubsessionsParams, { subsessions: SubsessionSummary[] }>({
+    name: "list_subsessions",
+    label: "List subsessions",
+    description: "List the tracked subsessions you spawned, with their current status (working, idle, error, or unknown).",
+    promptSnippet: "list_subsessions: see the tracked child sessions you spawned",
+    parameters: ListSubsessionsParams,
+    async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+      const parentSessionId = ctx.sessionManager.getSessionId();
+      const subsessions = await deps.list(parentSessionId);
+      const text = subsessions.length === 0
+        ? "You have not spawned any subsessions."
+        : `Your subsessions:\n${subsessions.map(statusLine).join("\n")}`;
+      return { content: [{ type: "text", text }], details: { subsessions } };
+    },
+  });
+
+  const checkTool = defineTool<typeof CheckSubsessionParams, SubsessionCheckResult>({
+    name: "check_subsession",
+    label: "Check subsession",
+    description: "Quick glance at a subsession you spawned: its current status and most recent assistant output. Use this to react to what a subsession produced. When the summary is not enough, use read_subsession to look through its full transcript.",
+    promptSnippet: "check_subsession: glance at a subsession's status and latest output",
+    parameters: CheckSubsessionParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const parentSessionId = ctx.sessionManager.getSessionId();
+      const result = await deps.check(parentSessionId, params.sessionId);
+      const body = result.finalText === "" ? "(no output yet)" : result.finalText;
+      return {
+        content: [{ type: "text", text: `Subsession ${result.sessionId} [${result.status}]:\n\n${body}` }],
+        details: result,
+      };
+    },
+  });
+
+  const readTool = defineTool<typeof ReadSubsessionParams, SubsessionReadResult>({
+    name: "read_subsession",
+    label: "Read subsession",
+    description: "Read through the transcript of a subsession you spawned. Returns its messages filtered and paginated however you ask: choose which roles (assistant, user, tool, system, custom) and content kinds (text, thinking, tool_call, tool_result, image) to include, search for a substring (always over full content), cap each value's length with maxChars (omit for full text; clipped parts are flagged so truncation is never silent), optionally include raw tool args, and page backward with 'before'/'limit'. Start narrow (e.g. assistant text with a small maxChars) and widen the filters, raise maxChars, or page further back if you don't find what you need. For just the final result, use check_subsession instead.",
+    promptSnippet: "read_subsession: read through a subsession's transcript with filters",
+    parameters: ReadSubsessionParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const parentSessionId = ctx.sessionManager.getSessionId();
+      const { sessionId, ...query } = params;
+      const result = await deps.read(parentSessionId, sessionId, query);
+      return {
+        content: [{ type: "text", text: renderTranscript(result) }],
+        details: result,
+      };
+    },
+  });
+
+  return [spawnTool, listTool, checkTool, readTool];
+}

src/server/sessions/spawnTargetResolver.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import type { Project, Workspace } from "../types.js";
+import { ProjectScopedSpawnTargetResolver } from "./spawnTargetResolver.js";
+
+function project(id: string, path: string): Project {
+  return { id, name: id, path, createdAt: "2026-01-01T00:00:00.000Z" };
+}
+
+function workspace(projectId: string, path: string): Workspace {
+  return { id: `${projectId}:${path}`, projectId, path, label: path, isMain: false, isGitRepo: true, isGitWorktree: true };
+}
+
+function resolverFor(projects: Project[], workspacesByProject: Record<string, Workspace[]>): ProjectScopedSpawnTargetResolver {
+  return new ProjectScopedSpawnTargetResolver({
+    projects: { list: () => Promise.resolve(projects) },
+    workspaces: { list: (p) => Promise.resolve(workspacesByProject[p.id] ?? []) },
+  });
+}
+
+describe("ProjectScopedSpawnTargetResolver", () => {
+  it("allows a target that is a workspace of the spawning session's project", async () => {
+    const resolver = resolverFor([project("a", "/repos/a"), project("b", "/repos/b")], {
+      a: [workspace("a", "/repos/a"), workspace("a", "/repos/a-feature")],
+      b: [workspace("b", "/repos/b")],
+    });
+
+    await expect(resolver.resolveSpawnTarget("/repos/a", "/repos/a-feature")).resolves.toEqual({ allowed: true, cwd: "/repos/a-feature" });
+  });
+
+  it("defaults the target to the spawning cwd when none is requested", async () => {
+    const resolver = resolverFor([project("a", "/repos/a")], { a: [workspace("a", "/repos/a")] });
+
+    await expect(resolver.resolveSpawnTarget("/repos/a", undefined)).resolves.toEqual({ allowed: true, cwd: "/repos/a" });
+  });
+
+  it("returns the canonical workspace path even when the request differs only by trailing slash", async () => {
+    const resolver = resolverFor([project("a", "/repos/a")], { a: [workspace("a", "/repos/a")] });
+
+    await expect(resolver.resolveSpawnTarget("/repos/a", "/repos/a/")).resolves.toEqual({ allowed: true, cwd: "/repos/a" });
+  });
+
+  it("rejects a target outside the project's workspaces and lists the allowed ones", async () => {
+    const resolver = resolverFor([project("a", "/repos/a")], { a: [workspace("a", "/repos/a"), workspace("a", "/repos/a-feature")] });
+
+    await expect(resolver.resolveSpawnTarget("/repos/a", "/elsewhere")).resolves.toEqual({
+      allowed: false,
+      reason: "out-of-project",
+      allowedCwds: ["/repos/a", "/repos/a-feature"],
+    });
+  });
+
+  it("rejects when the spawning cwd is in no registered project", async () => {
+    const resolver = resolverFor([project("a", "/repos/a")], { a: [workspace("a", "/repos/a")] });
+
+    await expect(resolver.resolveSpawnTarget("/elsewhere", undefined)).resolves.toEqual({ allowed: false, reason: "not-registered" });
+  });
+});

src/server/sessions/spawnTargetResolver.ts

@@ -0,0 +1,79 @@
+import type { Project, Workspace } from "../types.js";
+import { cwdPathsEqual } from "../workingDirectory.js";
+
+/**
+ * Decision describing whether a LLM-spawned session may target a given cwd.
+ *
+ * - `allowed: true` carries the canonical workspace path to start the session in
+ *   (always one of the project's known workspace paths, so it is guaranteed
+ *   visible in the web UI).
+ * - `not-registered` means the spawning session's cwd belongs to no registered
+ *   project, so spawning must be refused to preserve visibility.
+ * - `out-of-project` means the requested cwd is not a workspace of the spawning
+ *   session's project; `allowedCwds` lists the valid targets for the caller to
+ *   surface.
+ */
+export type SpawnTargetDecision =
+  | { allowed: true; cwd: string }
+  | { allowed: false; reason: "not-registered" }
+  | { allowed: false; reason: "out-of-project"; allowedCwds: string[] };
+
+/**
+ * Owns the rule that keeps LLM-spawned sessions visible: a spawned session may
+ * only target a workspace (worktree, or root) of the registered project that
+ * owns the spawning session. The rule is evaluated live so a worktree the agent
+ * just created with `git worktree add` is included.
+ */
+export interface SpawnTargetResolver {
+  /**
+   * Decide whether a session spawned from `spawningCwd` may target
+   * `requestedCwd` (defaulting to `spawningCwd` when omitted), returning the
+   * canonical target cwd when allowed.
+   */
+  resolveSpawnTarget(spawningCwd: string, requestedCwd: string | undefined): Promise<SpawnTargetDecision>;
+}
+
+interface ProjectLister {
+  list(): Promise<Project[]>;
+}
+
+interface WorkspaceLister {
+  list(project: Project): Promise<Workspace[]>;
+}
+
+export interface ProjectScopedSpawnTargetResolverDeps {
+  projects: ProjectLister;
+  workspaces: WorkspaceLister;
+}
+
+/**
+ * Default resolver composing the project registry and live worktree discovery.
+ * It finds the registered project whose current workspace set contains the
+ * spawning session's cwd, then validates the requested target against that set.
+ */
+export class ProjectScopedSpawnTargetResolver implements SpawnTargetResolver {
+  constructor(private readonly deps: ProjectScopedSpawnTargetResolverDeps) {}
+
+  async resolveSpawnTarget(spawningCwd: string, requestedCwd: string | undefined): Promise<SpawnTargetDecision> {
+    const allowedCwds = await this.allowedSpawnTargets(spawningCwd);
+    if (allowedCwds === undefined) return { allowed: false, reason: "not-registered" };
+    const target = requestedCwd === undefined || requestedCwd === "" ? spawningCwd : requestedCwd;
+    const match = allowedCwds.find((path) => cwdPathsEqual(path, target));
+    if (match === undefined) return { allowed: false, reason: "out-of-project", allowedCwds };
+    return { allowed: true, cwd: match };
+  }
+
+  /**
+   * Workspace paths of the registered project that owns `spawningCwd`, or
+   * `undefined` when no registered project contains it.
+   */
+  private async allowedSpawnTargets(spawningCwd: string): Promise<string[] | undefined> {
+    const projects = await this.deps.projects.list();
+    for (const project of projects) {
+      const workspaces = await this.deps.workspaces.list(project);
+      const paths = workspaces.map((workspace) => workspace.path);
+      if (paths.some((path) => cwdPathsEqual(path, spawningCwd))) return paths;
+    }
+    return undefined;
+  }
+}

src/server/sessions/subsessionTranscript.test.ts

@@ -0,0 +1,206 @@
+import { describe, expect, it } from "vitest";
+import { buildTranscriptView } from "./subsessionTranscript.js";
+
+const user = (text: string) => ({ role: "user", content: text });
+const assistant = (text: string) => ({ role: "assistant", content: [{ type: "text", text }] });
+const thinking = (text: string) => ({ role: "assistant", content: [{ type: "thinking", thinking: text }] });
+const toolCall = (name: string, args?: unknown) => ({ role: "assistant", content: [{ type: "toolCall", name, ...(args === undefined ? {} : { arguments: args }) }] });
+const toolResult = (text: string, toolName = "bash", isError = false) => ({ role: "toolResult", toolName, content: text, isError });
+const custom = (text: string) => ({ role: "custom", content: text, customType: "subsession.completion" });
+
+describe("buildTranscriptView", () => {
+  it("returns all entries with stable indices by default", () => {
+    const messages = [user("do it"), thinking("plan"), toolCall("bash"), toolResult("ok"), assistant("done")];
+    const view = buildTranscriptView(messages);
+
+    expect(view.total).toBe(5);
+    expect(view.matched).toBe(5);
+    expect(view.entries.map((entry) => entry.index)).toEqual([0, 1, 2, 3, 4]);
+    expect(view.hasMore).toBe(false);
+  });
+
+  it("filters by role", () => {
+    const messages = [user("do it"), thinking("plan"), assistant("done")];
+    const view = buildTranscriptView(messages, { roles: ["assistant"] });
+
+    expect(view.matched).toBe(2); // thinking + text are both assistant-role
+    expect(view.entries.every((entry) => entry.role === "assistant")).toBe(true);
+  });
+
+  it("filters by content kind, dropping entries left empty", () => {
+    const messages = [user("do it"), thinking("plan"), assistant("answer"), toolCall("bash")];
+    const view = buildTranscriptView(messages, { include: ["text"] });
+
+    // user text + assistant text survive; thinking-only and tool_call-only entries drop out
+    expect(view.matched).toBe(2);
+    expect(view.entries.flatMap((entry) => entry.parts.map((part) => part.kind))).toEqual(["text", "text"]);
+  });
+
+  it("does not truncate by default and omits tool args", () => {
+    const long = "x".repeat(800);
+    const messages = [assistant(long), toolCall("bash", { command: "ls", extra: "y" })];
+    const view = buildTranscriptView(messages);
+
+    const textPart = view.entries[0]?.parts[0];
+    if (textPart?.kind !== "text") throw new Error("expected text part");
+    expect(textPart.text).toBe(long);
+    expect(textPart.truncated).toBeUndefined();
+
+    const callPart = view.entries[1]?.parts[0];
+    if (callPart?.kind !== "tool_call") throw new Error("expected tool_call part");
+    expect(callPart.summary).toBe("ls");
+    expect("args" in callPart).toBe(false);
+  });
+
+  it("maxChars clips text and flags it with the full length", () => {
+    const long = "x".repeat(800);
+    const messages = [assistant(long)];
+    const view = buildTranscriptView(messages, { maxChars: 100 });
+
+    const textPart = view.entries[0]?.parts[0];
+    if (textPart?.kind !== "text") throw new Error("expected text part");
+    expect(textPart.text).toBe("x".repeat(100));
+    expect(textPart.truncated).toEqual({ shown: 100, full: 800 });
+  });
+
+  it("maxChars does not flag values at or under the cap", () => {
+    const messages = [assistant("short")];
+    const view = buildTranscriptView(messages, { maxChars: 100 });
+    const textPart = view.entries[0]?.parts[0];
+    if (textPart?.kind !== "text") throw new Error("expected text part");
+    expect(textPart.text).toBe("short");
+    expect(textPart.truncated).toBeUndefined();
+  });
+
+  it("includeToolArgs returns raw args alongside the summary", () => {
+    const messages = [toolCall("bash", { command: "ls" })];
+    const view = buildTranscriptView(messages, { includeToolArgs: true });
+    const callPart = view.entries[0]?.parts[0];
+    if (callPart?.kind !== "tool_call") throw new Error("expected tool_call part");
+    expect(callPart.summary).toBe("ls");
+    expect(callPart.args).toEqual({ command: "ls" });
+  });
+
+  it("search keeps only matching entries across text and tool names", () => {
+    const messages = [assistant("the auth flow"), assistant("unrelated"), toolResult("error in auth.ts", "read")];
+    const view = buildTranscriptView(messages, { search: "auth" });
+
+    expect(view.matched).toBe(2);
+    expect(view.entries.map((entry) => entry.index)).toEqual([0, 2]);
+  });
+
+  it("search runs against full content even when maxChars would clip the match away", () => {
+    // The match sits past the clip point; a window-first or clip-first search would miss it.
+    const text = `${"a".repeat(300)} NEEDLE ${"b".repeat(300)}`;
+    const messages = [assistant(text)];
+    const view = buildTranscriptView(messages, { search: "needle", maxChars: 50 });
+
+    expect(view.matched).toBe(1);
+    const textPart = view.entries[0]?.parts[0];
+    if (textPart?.kind !== "text") throw new Error("expected text part");
+    // The match is found, and the returned (clipped) text honestly flags truncation.
+    expect(textPart.truncated).toEqual({ shown: 50, full: text.length });
+  });
+
+  it("search matches tool-call arguments even without includeToolArgs", () => {
+    const messages = [toolCall("bash", { command: "grep NEEDLE src" })];
+    const view = buildTranscriptView(messages, { search: "needle" });
+    expect(view.matched).toBe(1);
+  });
+
+  it("search finds args the display summary would drop (edit/write content, nested, beyond first 3 keys)", () => {
+    // summarizeToolArgs collapses these to 'edit text replacement' / 'object' / first-3-keys,
+    // so matching must serialize the full args, not the summary.
+    const editArgs = { oldText: "before", newText: "NEEDLE_IN_NEWTEXT" };
+    const nestedArgs = { a: 1, b: 2, c: 3, payload: { deep: "NEEDLE_NESTED" } };
+    const messages = [toolCall("edit", editArgs), toolCall("write", nestedArgs)];
+
+    expect(buildTranscriptView(messages, { search: "needle_in_newtext" }).matched).toBe(1);
+    expect(buildTranscriptView(messages, { search: "needle_nested" }).matched).toBe(1);
+  });
+
+  it("maxChars boundary: exact length is not flagged, one over is", () => {
+    const exact = buildTranscriptView([assistant("x".repeat(50))], { maxChars: 50 }).entries[0]?.parts[0];
+    if (exact?.kind !== "text") throw new Error("expected text part");
+    expect(exact.truncated).toBeUndefined();
+
+    const over = buildTranscriptView([assistant("x".repeat(51))], { maxChars: 50 }).entries[0]?.parts[0];
+    if (over?.kind !== "text") throw new Error("expected text part");
+    expect(over.truncated).toEqual({ shown: 50, full: 51 });
+  });
+
+  it("maxChars: 0 clips everything and flags it (not treated as 'no cap')", () => {
+    const part = buildTranscriptView([assistant("abc")], { maxChars: 0 }).entries[0]?.parts[0];
+    if (part?.kind !== "text") throw new Error("expected text part");
+    expect(part.text).toBe("");
+    expect(part.truncated).toEqual({ shown: 0, full: 3 });
+  });
+
+  it("negative or fractional maxChars is coerced to a safe non-negative integer, never 'no cap'", () => {
+    const negative = buildTranscriptView([assistant("abc")], { maxChars: -5 }).entries[0]?.parts[0];
+    if (negative?.kind !== "text") throw new Error("expected text part");
+    expect(negative.text).toBe(""); // coerced to 0, still truncates
+    expect(negative.truncated).toEqual({ shown: 0, full: 3 });
+
+    const fractional = buildTranscriptView([assistant("abcdef")], { maxChars: 2.9 }).entries[0]?.parts[0];
+    if (fractional?.kind !== "text") throw new Error("expected text part");
+    expect(fractional.text).toBe("ab"); // floored to 2
+    expect(fractional.truncated).toEqual({ shown: 2, full: 6 });
+  });
+
+  it("empty window with matches reports matched > 0 (paged past all matches)", () => {
+    const messages = [assistant("a"), assistant("b"), assistant("c")];
+    const view = buildTranscriptView(messages, { before: 0 });
+    expect(view.entries).toEqual([]);
+    expect(view.matched).toBe(3); // matches exist, the window just excluded them
+    expect(view.start).toBe(0);
+    expect(view.hasMore).toBe(false);
+  });
+
+  it("pages from the end and reports hasMore", () => {
+    const messages = [assistant("a"), assistant("b"), assistant("c"), assistant("d")];
+    const view = buildTranscriptView(messages, { limit: 2 });
+
+    expect(view.entries.map((entry) => entry.index)).toEqual([2, 3]);
+    expect(view.matched).toBe(4);
+    expect(view.start).toBe(2);
+    expect(view.hasMore).toBe(true);
+  });
+
+  it("pages backward using before: previous start", () => {
+    const messages = [assistant("a"), assistant("b"), assistant("c"), assistant("d")];
+    const view = buildTranscriptView(messages, { limit: 2, before: 2 });
+
+    expect(view.entries.map((entry) => entry.index)).toEqual([0, 1]);
+    expect(view.start).toBe(0);
+    expect(view.hasMore).toBe(false);
+  });
+
+  it("limit bounds matched entries, not raw messages", () => {
+    const messages = [user("u1"), assistant("a1"), user("u2"), assistant("a2"), user("u3"), assistant("a3")];
+    const view = buildTranscriptView(messages, { roles: ["assistant"], limit: 2 });
+
+    expect(view.matched).toBe(3);
+    expect(view.entries.map((entry) => entry.index)).toEqual([3, 5]);
+    expect(view.hasMore).toBe(true);
+  });
+
+  it("reports start as before when nothing matches in the window", () => {
+    const messages = [assistant("a"), assistant("b")];
+    const view = buildTranscriptView(messages, { search: "absent" });
+
+    expect(view.entries).toEqual([]);
+    expect(view.matched).toBe(0);
+    expect(view.start).toBe(2);
+    expect(view.hasMore).toBe(false);
+  });
+
+  it("includes custom and system roles", () => {
+    const messages = [custom("subsession done"), { role: "system", source: "compaction", content: "Compacted history:\n\nstuff" }];
+    const all = buildTranscriptView(messages);
+    expect(all.entries.map((entry) => entry.role)).toEqual(["custom", "system"]);
+
+    const onlyCustom = buildTranscriptView(messages, { roles: ["custom"] });
+    expect(onlyCustom.matched).toBe(1);
+  });
+});

src/server/sessions/subsessionTranscript.ts

@@ -0,0 +1,312 @@
+/**
+ * Pure helpers for the `read_subsession` tool: turn a subsession's normalized
+ * history (as produced by `historyMessages`) into a filtered, projected,
+ * paginated view the parent agent can explore.
+ *
+ * The agent drives the read: it picks which roles and content kinds it cares
+ * about, how much detail it wants, and how far back to look. If a narrow read
+ * does not answer its question it can widen the filters or page further back,
+ * the same grep-then-read loop it already uses on files. Everything here is a
+ * pure transform over an array so it can be unit-tested without a live session.
+ */
+
+/** Message roles the parent can ask for, mapped from raw history roles. */
+export type TranscriptRole = "assistant" | "user" | "tool" | "system" | "custom";
+
+/** Content kinds the parent can keep within retained messages. */
+export type TranscriptContentKind = "text" | "thinking" | "tool_call" | "tool_result" | "image";
+
+/**
+ * Marks a text value that the caller's `maxChars` clipped. Carries the full
+ * length so the consumer knows *how much* was dropped and can re-read with a
+ * larger `maxChars` (or none). Truncation only ever happens when the caller
+ * passes `maxChars`, so a `truncated` marker is always something they asked
+ * for and should expect, never a silent surprise. Its presence (not a `…`
+ * glyph, which is indistinguishable from real content) is the reliable signal.
+ */
+export interface TranscriptTruncation {
+  /** Characters retained in `text`. */
+  shown: number;
+  /** Length of the original, untruncated text. */
+  full: number;
+}
+
+export type TranscriptPart =
+  | { kind: "text"; text: string; truncated?: TranscriptTruncation }
+  | { kind: "thinking"; text: string; truncated?: TranscriptTruncation }
+  | { kind: "tool_call"; toolName: string; summary: string; args?: unknown }
+  | { kind: "tool_result"; toolName?: string; text: string; isError: boolean; truncated?: TranscriptTruncation }
+  | { kind: "image" };
+
+export interface TranscriptEntry {
+  /** Position of this message in the full transcript (stable across reads). */
+  index: number;
+  role: TranscriptRole;
+  parts: TranscriptPart[];
+}
+
+export interface TranscriptQuery {
+  /** Message roles to include. Omit for all roles. */
+  roles?: TranscriptRole[];
+  /** Content kinds to keep within retained messages. Omit for all kinds. */
+  include?: TranscriptContentKind[];
+  /** Case-insensitive substring; keep only entries whose text matches. */
+  search?: string;
+  /**
+   * Truncate each text/thinking/tool_result value to this many characters,
+   * flagging clipped parts with `truncated`. Omit for full, untruncated text:
+   * there is deliberately no default, so truncation only happens when asked for
+   * and a `truncated` marker is always expected. `search` always runs against
+   * the full content regardless, so clipping never hides a match.
+   */
+  maxChars?: number;
+  /** Include raw tool-call arguments (can be large). The compact `summary` is always present. */
+  includeToolArgs?: boolean;
+  /** Upper bound (exclusive) on original index; page backward by passing the previous `start`. */
+  before?: number;
+  /** Keep at most this many of the most-recent matches in the window; entries are returned in chronological order. */
+  limit?: number;
+}
+
+export interface TranscriptView {
+  entries: TranscriptEntry[];
+  /** Total messages in the full transcript, before any filtering. */
+  total: number;
+  /** Entries matching the role/content/search filters across the whole transcript. */
+  matched: number;
+  /** Original index of the first returned entry, or `before` when nothing matched in-window. */
+  start: number;
+  /** True when matching entries exist before `start` (page back with `before: start`). */
+  hasMore: boolean;
+}
+
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 200;
+
+/**
+ * Build a filtered, projected, paginated view of a normalized transcript.
+ *
+ * Filtering happens before paging for *semantics*, not speed: `search`, the
+ * `matched` count, and "page backward through matches" all require scanning the
+ * whole transcript, so a window-first approach could not answer them. The
+ * tradeoff is an O(total) scan per call (paging a raw window first would be
+ * cheaper), but `total` is a single session's history and this runs once per
+ * tool call, so the scan is negligible. The cost that matters for an LLM tool,
+ * the tokens returned, is bounded by `limit` regardless of ordering; `matched`
+ * is only a count, so the agent learns whether widening or paging is worthwhile
+ * without paying to receive every match.
+ */
+export function buildTranscriptView(messages: readonly unknown[], query: TranscriptQuery = {}): TranscriptView {
+  const total = messages.length;
+  // Explicit, caller-owned truncation: only when provided, and a malformed
+  // value (negative/fractional) is coerced to a safe non-negative integer
+  // rather than silently meaning "no cap".
+  const maxChars = query.maxChars === undefined ? undefined : Math.max(0, Math.floor(query.maxChars));
+  const includeToolArgs = query.includeToolArgs === true;
+  const roleFilter = query.roles === undefined ? undefined : new Set(query.roles);
+  const includeFilter = query.include === undefined ? undefined : new Set(query.include);
+  const search = query.search !== undefined && query.search !== "" ? query.search.toLowerCase() : undefined;
+
+  // Extract *full* (untruncated) parts and run all filtering/search on them, so
+  // matching never depends on `maxChars`. Projection (clipping, arg dropping)
+  // happens later and only on the entries we actually return.
+  const matchedEntries: FullEntry[] = [];
+  for (let index = 0; index < total; index++) {
+    const role = roleOf(messages[index]);
+    if (role === undefined) continue;
+    if (roleFilter !== undefined && !roleFilter.has(role)) continue;
+
+    let parts = fullPartsOf(messages[index], role);
+    if (includeFilter !== undefined) parts = parts.filter((part) => includeFilter.has(part.kind));
+    if (parts.length === 0) continue;
+    if (search !== undefined && !partsMatchSearch(parts, search)) continue;
+
+    matchedEntries.push({ index, role, parts });
+  }
+
+  const matched = matchedEntries.length;
+  const before = clampInteger(query.before ?? total, 0, total);
+  const limit = clampInteger(query.limit ?? DEFAULT_LIMIT, 1, MAX_LIMIT);
+
+  const inWindow = matchedEntries.filter((entry) => entry.index < before);
+  const windowed = inWindow.slice(Math.max(0, inWindow.length - limit));
+  const entries = windowed.map((entry) => projectEntry(entry, maxChars, includeToolArgs));
+  const first = windowed[0];
+  const start = first === undefined ? before : first.index;
+  const hasMore = inWindow.length > windowed.length;
+
+  return { entries, total, matched, start, hasMore };
+}
+
+/**
+ * A part before projection: tool calls keep their raw `args`, text-bearing
+ * parts keep their full untruncated `text`. Search and filtering run on these
+ * so a match is never hidden by `summary` truncation.
+ */
+type FullPart =
+  | { kind: "text"; text: string }
+  | { kind: "thinking"; text: string }
+  | { kind: "tool_call"; toolName: string; args?: unknown }
+  | { kind: "tool_result"; toolName?: string; text: string; isError: boolean }
+  | { kind: "image" };
+
+interface FullEntry {
+  index: number;
+  role: TranscriptRole;
+  parts: FullPart[];
+}
+
+function partsMatchSearch(parts: readonly FullPart[], needle: string): boolean {
+  return parts.some((part) => {
+    if (part.kind === "text" || part.kind === "thinking") return part.text.toLowerCase().includes(needle);
+    if (part.kind === "tool_result") return part.text.toLowerCase().includes(needle) || (part.toolName?.toLowerCase().includes(needle) ?? false);
+    // Search the *full* serialized args, not the lossy one-line summary, so a
+    // term inside edit/write content, nested objects, or long values is found.
+    if (part.kind === "tool_call") return part.toolName.toLowerCase().includes(needle) || stringifyArgs(part.args).toLowerCase().includes(needle);
+    return false;
+  });
+}
+
+/** Full, search-friendly serialization of tool-call args (distinct from the lossy display summary). */
+function stringifyArgs(args: unknown): string {
+  if (args === undefined) return "";
+  if (typeof args === "string") return args;
+  try {
+    // JSON.stringify can return undefined at runtime (e.g. a function/symbol),
+    // despite its string-typed signature; normalize that to "".
+    const json: unknown = JSON.stringify(args);
+    return typeof json === "string" ? json : "";
+  } catch {
+    return "";
+  }
+}
+
+/** Project a fully-extracted entry into the returned shape, clipping only when `maxChars` is set. */
+function projectEntry(entry: FullEntry, maxChars: number | undefined, includeToolArgs: boolean): TranscriptEntry {
+  return { index: entry.index, role: entry.role, parts: entry.parts.map((part) => projectPart(part, maxChars, includeToolArgs)) };
+}
+
+function projectPart(part: FullPart, maxChars: number | undefined, includeToolArgs: boolean): TranscriptPart {
+  if (part.kind === "text") return { kind: "text", ...clip(part.text, maxChars) };
+  if (part.kind === "thinking") return { kind: "thinking", ...clip(part.text, maxChars) };
+  if (part.kind === "tool_result") {
+    return {
+      kind: "tool_result",
+      ...(part.toolName === undefined ? {} : { toolName: part.toolName }),
+      isError: part.isError,
+      ...clip(part.text, maxChars),
+    };
+  }
+  if (part.kind === "tool_call") {
+    return {
+      kind: "tool_call",
+      toolName: part.toolName,
+      summary: summarizeToolArgs(part.args),
+      ...(includeToolArgs && part.args !== undefined ? { args: part.args } : {}),
+    };
+  }
+  return { kind: "image" };
+}
+
+/** Clip text to `maxChars`, attaching a `truncated` marker when it actually shortens. */
+function clip(text: string, maxChars: number | undefined): { text: string; truncated?: TranscriptTruncation } {
+  if (maxChars === undefined || text.length <= maxChars) return { text };
+  return { text: text.slice(0, maxChars), truncated: { shown: maxChars, full: text.length } };
+}
+
+/** Map a raw history message to one of the agent-facing roles, or undefined to drop it. */
+function roleOf(message: unknown): TranscriptRole | undefined {
+  const role = getString(message, "role");
+  if (role === "assistant") return "assistant";
+  if (role === "user") return "user";
+  if (role === "toolResult") return "tool";
+  if (role === "custom") return "custom";
+  if (role === "system") return "system";
+  return undefined;
+}
+
+/** Extract a message's *full* (untruncated) parts; projection happens later. */
+function fullPartsOf(message: unknown, role: TranscriptRole): FullPart[] {
+  if (role === "tool") return toolResultParts(message);
+  const content = getProperty(message, "content");
+  if (typeof content === "string") return content === "" ? [] : [{ kind: "text", text: content }];
+  if (!Array.isArray(content)) return [];
+  return content.flatMap(contentPart);
+}
+
+function toolResultParts(message: unknown): FullPart[] {
+  const text = stringifyContent(getProperty(message, "content")) || (getString(message, "text") ?? "");
+  const toolName = getString(message, "toolName");
+  const isError = getProperty(message, "isError") === true;
+  return [{ kind: "tool_result", ...(toolName === undefined ? {} : { toolName }), text, isError }];
+}
+
+function contentPart(part: unknown): FullPart[] {
+  const type = getString(part, "type");
+  if (type === "text") {
+    const text = getString(part, "text") ?? "";
+    return text === "" ? [] : [{ kind: "text", text }];
+  }
+  if (type === "thinking") {
+    const text = getString(part, "thinking") ?? getString(part, "text") ?? "";
+    return text === "" ? [] : [{ kind: "thinking", text }];
+  }
+  if (type === "toolCall") {
+    const toolName = getString(part, "name") ?? "tool";
+    const args = getProperty(part, "arguments");
+    return [{ kind: "tool_call", toolName, ...(args === undefined ? {} : { args }) }];
+  }
+  if (type === "image") return [{ kind: "image" }];
+  return [];
+}
+
+/** Compact one-line description of tool arguments (mirrors the UI's summary). */
+function summarizeToolArgs(args: unknown): string {
+  if (!isRecord(args)) return typeof args === "string" ? args : "";
+  const command = getString(args, "command");
+  if (command !== undefined) return command;
+  const path = getString(args, "path");
+  if (path !== undefined) return path;
+  if (typeof args["oldText"] === "string" && typeof args["newText"] === "string") return "edit text replacement";
+  const edits = args["edits"];
+  if (Array.isArray(edits)) return `${String(edits.length)} edit${edits.length === 1 ? "" : "s"}`;
+  const entries = Object.entries(args).filter(([, value]) => value != null).slice(0, 3);
+  return entries.map(([key, value]) => `${key}: ${shortValue(value)}`).join(" · ");
+}
+
+function shortValue(value: unknown): string {
+  if (typeof value === "string") return value.length > 80 ? `${value.slice(0, 77)}…` : value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (Array.isArray(value)) return `${String(value.length)} item${value.length === 1 ? "" : "s"}`;
+  if (typeof value === "object" && value !== null) return "object";
+  return "";
+}
+
+function stringifyContent(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((part) => (getString(part, "type") === "image" ? "[image]" : getString(part, "text") ?? ""))
+      .filter((text) => text !== "")
+      .join("\n");
+  }
+  return "";
+}
+
+function clampInteger(value: number, min: number, max: number): number {
+  if (!Number.isFinite(value)) return max;
+  return Math.max(min, Math.min(max, Math.floor(value)));
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function getProperty(value: unknown, key: string): unknown {
+  return isRecord(value) ? value[key] : undefined;
+}
+
+function getString(value: unknown, key: string): string | undefined {
+  const property = getProperty(value, key);
+  return typeof property === "string" ? property : undefined;
+}

src/server/workspaceExplorerRoutes.ts

@@ -1,23 +1,26 @@
 import type { FastifyInstance } from "fastify";
-import type { ProjectService } from "./projects/projectService.js";
-import type { WorkspaceService } from "./workspaces/workspaceService.js";
 import type { WriteWorkspaceFileOptions } from "../shared/apiTypes.js";
-import { resolveWorkspaceContext } from "./workspaces/workspaceContext.js";
-import { listWorkspaceTree } from "./workspaces/fileTreeService.js";
+import type { PiWebConfigService } from "./configRoutes.js";
+import type { ProjectService } from "./projects/projectService.js";
 import { deleteWorkspaceFile, moveWorkspaceFile, readWorkspaceFile, writeWorkspaceFile } from "./workspaces/fileContentService.js";
+import { isAbsoluteishFileSuggestionQuery, listFileSuggestions, listPathSuggestions } from "./workspaces/fileSuggestions.js";
+import { listWorkspaceTree } from "./workspaces/fileTreeService.js";
 import { readWorkspaceImagePreview } from "./workspaces/imagePreviewService.js";
+import { resolveWorkspaceContext } from "./workspaces/workspaceContext.js";
+import { pathAccessForWorkspaceContext } from "./workspaces/effectivePathAccess.js";
+import type { WorkspaceService } from "./workspaces/workspaceService.js";
+
+export interface WorkspaceExplorerRouteOptions {
+  config?: Pick<PiWebConfigService, "read">;
+}
+
+export function registerWorkspaceExplorerRoutes(app: FastifyInstance, projects: ProjectService, workspaces: WorkspaceService, prefix = "/api", options: WorkspaceExplorerRouteOptions = {}): void {
+  registerWorkspaceFileContentParsers(app);
 
-export function registerWorkspaceExplorerRoutes(app: FastifyInstance, projects: ProjectService, workspaces: WorkspaceService, prefix = "/api"): void {
-  // Register content type parsers for workspace file writes.
-  // Fastify's default parser only handles application/json.
-  // Guard against re-registration since this function may be called multiple times.
-  try { app.addContentTypeParser("text/plain", { parseAs: "string" }, (_req, body, done) => { done(null, Buffer.from(body)); }); } catch { /* already registered */ }
-  try { app.addContentTypeParser("application/octet-stream", { parseAs: "buffer" }, (_req, body, done) => { done(null, body); }); } catch { /* already registered */ }
-  try { app.addContentTypeParser(/^([a-z]+\/[a-z0-9.+-]+)$/, { parseAs: "buffer" }, (_req, body, done) => { done(null, body); }); } catch { /* already registered */ }
   app.get<{ Params: { projectId: string; workspaceId: string }; Querystring: { path?: string } }>(`${prefix}/projects/:projectId/workspaces/:workspaceId/tree`, async (request, reply) => {
     try {
       const context = await resolveWorkspaceContext(projects, workspaces, request.params.projectId, request.params.workspaceId);
-      return await listWorkspaceTree(context.root, request.query.path);
+      return await listWorkspaceTree(context.root, request.query.path, await pathAccessForWorkspaceContext(context, options.config));
     } catch (error) {
       return reply.code(400).send({ error: error instanceof Error ? error.message : String(error) });
     }
@@ -26,7 +29,7 @@ export function registerWorkspaceExplorerRoutes(app: FastifyInstance, projects:
   app.get<{ Params: { projectId: string; workspaceId: string }; Querystring: { path?: string } }>(`${prefix}/projects/:projectId/workspaces/:workspaceId/file`, async (request, reply) => {
     try {
       const context = await resolveWorkspaceContext(projects, workspaces, request.params.projectId, request.params.workspaceId);
-      return await readWorkspaceFile(context.root, request.query.path);
+      return await readWorkspaceFile(context.root, request.query.path, await pathAccessForWorkspaceContext(context, options.config));
     } catch (error) {
       return reply.code(400).send({ error: error instanceof Error ? error.message : String(error) });
     }
@@ -35,11 +38,11 @@ export function registerWorkspaceExplorerRoutes(app: FastifyInstance, projects:
   app.put<{ Params: { projectId: string; workspaceId: string }; Body: Buffer; Querystring: { path?: string; createDirs?: string; overwrite?: string } }>(`${prefix}/projects/:projectId/workspaces/:workspaceId/file`, async (request, reply) => {
     try {
       const context = await resolveWorkspaceContext(projects, workspaces, request.params.projectId, request.params.workspaceId);
-      const options: WriteWorkspaceFileOptions = {
+      const writeOptions: WriteWorkspaceFileOptions = {
         createDirs: request.query.createDirs !== "false",
         overwrite: request.query.overwrite !== "false",
       };
-      return await writeWorkspaceFile(context.root, request.query.path, request.body, options);
+      return await writeWorkspaceFile(context.root, request.query.path, request.body, writeOptions);
     } catch (error) {
       return reply.code(400).send({ error: error instanceof Error ? error.message : String(error) });
     }
@@ -69,7 +72,7 @@ export function registerWorkspaceExplorerRoutes(app: FastifyInstance, projects:
   app.get<{ Params: { projectId: string; workspaceId: string }; Querystring: { path?: string } }>(`${prefix}/projects/:projectId/workspaces/:workspaceId/file/preview`, async (request, reply) => {
     try {
       const context = await resolveWorkspaceContext(projects, workspaces, request.params.projectId, request.params.workspaceId);
-      const preview = await readWorkspaceImagePreview(context.root, request.query.path);
+      const preview = await readWorkspaceImagePreview(context.root, request.query.path, await pathAccessForWorkspaceContext(context, options.config));
       return await reply
         .type(preview.mimeType)
         .header("Cache-Control", "private, max-age=3600")
@@ -82,4 +85,25 @@ export function registerWorkspaceExplorerRoutes(app: FastifyInstance, projects:
       return reply.code(400).send({ error: error instanceof Error ? error.message : String(error) });
     }
   });
+
+  app.get<{ Params: { projectId: string; workspaceId: string }; Querystring: { q?: string; kind?: "tracked" | "untracked" | "other"; mode?: "file" | "path"; scope?: "tracked" | "all" } }>(`${prefix}/projects/:projectId/workspaces/:workspaceId/files`, async (request, reply) => {
+    try {
+      const context = await resolveWorkspaceContext(projects, workspaces, request.params.projectId, request.params.workspaceId);
+      const query = request.query.q ?? "";
+      const pathAccess = isAbsoluteishFileSuggestionQuery(query) ? await pathAccessForWorkspaceContext(context, options.config) : undefined;
+      if (request.query.mode === "path") return await listPathSuggestions(context.root, query, pathAccess);
+      return await listFileSuggestions(context.root, query, { kind: request.query.kind, scope: request.query.scope, pathAccess });
+    } catch (error) {
+      return reply.code(400).send({ error: error instanceof Error ? error.message : String(error) });
+    }
+  });
+}
+
+function registerWorkspaceFileContentParsers(app: FastifyInstance): void {
+  // Fastify's default parser only handles JSON; workspace file writes need to
+  // accept text and arbitrary binary payloads. This route module is registered
+  // for both local aliases, so parser registration must tolerate repeats.
+  try { app.addContentTypeParser("text/plain", { parseAs: "string" }, (_request, body, done) => { done(null, Buffer.from(body)); }); } catch { /* already registered */ }
+  try { app.addContentTypeParser("application/octet-stream", { parseAs: "buffer" }, (_request, body, done) => { done(null, body); }); } catch { /* already registered */ }
+  try { app.addContentTypeParser(/^([a-z]+\/[a-z0-9.+-]+)$/u, { parseAs: "buffer" }, (_request, body, done) => { done(null, body); }); } catch { /* already registered */ }
 }

src/server/workspaces/effectivePathAccess.ts

@@ -0,0 +1,29 @@
+import type { PiWebPathAccessConfig } from "../../shared/apiTypes.js";
+import type { PiWebConfigService } from "../configRoutes.js";
+import type { ProjectService } from "../projects/projectService.js";
+import type { WorkspaceContext } from "./workspaceContext.js";
+import type { WorkspaceService } from "./workspaceService.js";
+import { cwdPathsEqual } from "../workingDirectory.js";
+import { loadEffectiveProjectPathAccess } from "./projectPiWebConfig.js";
+
+export async function pathAccessForWorkspaceContext(context: WorkspaceContext, config: Pick<PiWebConfigService, "read"> | undefined): Promise<PiWebPathAccessConfig | undefined> {
+  if (config === undefined) return undefined;
+  const response = await config.read();
+  return loadEffectiveProjectPathAccess(context.project.path, response.effectiveConfig);
+}
+
+export async function pathAccessForCwd(cwd: string, projects: ProjectService, workspaces: WorkspaceService, config: Pick<PiWebConfigService, "read"> | undefined): Promise<PiWebPathAccessConfig | undefined> {
+  if (config === undefined) return undefined;
+  const response = await config.read();
+  const projectPath = await projectPathForWorkspaceCwd(cwd, projects, workspaces);
+  if (projectPath === undefined) return response.effectiveConfig.pathAccess;
+  return loadEffectiveProjectPathAccess(projectPath, response.effectiveConfig);
+}
+
+async function projectPathForWorkspaceCwd(cwd: string, projects: ProjectService, workspaces: WorkspaceService): Promise<string | undefined> {
+  for (const project of await projects.list()) {
+    if (cwdPathsEqual(project.path, cwd)) return project.path;
+    if ((await workspaces.list(project)).some((workspace) => cwdPathsEqual(workspace.path, cwd))) return project.path;
+  }
+  return undefined;
+}

src/server/workspaces/fileContentService.test.ts

@@ -50,6 +50,23 @@ describe("readWorkspaceFile", () => {
     await expect(readWorkspaceFile(root, "/etc/passwd")).rejects.toThrow("Absolute paths are not allowed");
   });
 
+  it("reads allowed absolute files outside the workspace", async () => {
+    const root = await tempWorkspace();
+    const external = await tempWorkspace();
+    await writeFile(join(external, "README.md"), "external docs\n");
+
+    const file = await readWorkspaceFile(root, join(external, "README.md"), { allowedPaths: [external] });
+
+    expect(file).toMatchObject({
+      path: join(external, "README.md"),
+      language: "markdown",
+      content: "external docs\n",
+      truncated: false,
+      binary: false,
+    });
+    await expect(readWorkspaceFile(root, join(external, "README.md"))).rejects.toThrow("Absolute paths are not allowed");
+  });
+
   it("detects binary files and omits binary content", async () => {
     const root = await tempWorkspace();
     await writeFile(join(root, "image.bin"), Buffer.from([0x66, 0x6f, 0x00, 0x6f]));

src/server/workspaces/fileContentService.ts

@@ -1,23 +1,24 @@
 import { lstat, mkdir, open, realpath, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
-import type { DeleteWorkspaceFileResponse, FileContentResponse, MoveWorkspaceFileOptions, MoveWorkspaceFileResponse, WriteWorkspaceFileOptions, WriteWorkspaceFileResponse } from "../../shared/apiTypes.js";
+import type { DeleteWorkspaceFileResponse, FileContentResponse, MoveWorkspaceFileOptions, MoveWorkspaceFileResponse, PiWebPathAccessConfig, WriteWorkspaceFileOptions, WriteWorkspaceFileResponse } from "../../shared/apiTypes.js";
 import { imageMimeTypeForPath } from "./imagePreviewService.js";
+import { resolveWorkspacePathAccessTarget } from "./pathAccessPolicy.js";
 import { ensureInside, isNodeErrorWithCode, resolveInsideWorkspace, resolveParentInsideWorkspace } from "./pathSafety.js";
 
 const MAX_BYTES = 512 * 1024;
 
-export async function readWorkspaceFile(rootPath: string, path: string | undefined): Promise<FileContentResponse> {
+export async function readWorkspaceFile(rootPath: string, path: string | undefined, pathAccess?: PiWebPathAccessConfig): Promise<FileContentResponse> {
   if (path === undefined || path === "") throw new Error("path query parameter is required");
-  const { target, relativePath } = await resolveInsideWorkspace(rootPath, path);
+  const { target, displayPath } = await resolveWorkspacePathAccessTarget(rootPath, path, pathAccess);
   const s = await stat(target);
   if (!s.isFile()) throw new Error("Path is not a file");
   const bytesToRead = Math.min(s.size, MAX_BYTES);
   const buffer = await readFilePrefix(target, bytesToRead);
-  const media = mediaForPath(relativePath);
+  const media = mediaForPath(displayPath);
   const binary = media.mediaType === "image" || isProbablyBinary(buffer);
   return {
-    path: relativePath,
-    ...languageForPath(relativePath),
+    path: displayPath,
+    ...languageForPath(displayPath),
     ...media,
     encoding: "utf8",
     size: s.size,

src/server/workspaces/fileSuggestions.test.ts

@@ -1,8 +1,8 @@
-import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { mkdtemp, mkdir, rm, symlink, writeFile } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { basename, join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
-import { listFileSuggestions, type FileSuggestionDependencies } from "./fileSuggestions";
+import { listFileSuggestions, listPathSuggestions, type FileSuggestionDependencies } from "./fileSuggestions";
 
 const temporaryRoots: string[] = [];
 
@@ -12,6 +12,26 @@ async function tempWorkspace(): Promise<string> {
   return root;
 }
 
+function fzfRecords(input: string | Buffer | undefined): string[] {
+  if (typeof input === "string") return input.split("\0").filter(Boolean);
+  if (Buffer.isBuffer(input)) return input.toString("utf8").split("\0").filter(Boolean);
+  return [];
+}
+
+async function trySymlink(target: string, path: string): Promise<boolean> {
+  try {
+    await symlink(target, path, "dir");
+    return true;
+  } catch (error) {
+    if (isNodeErrorWithCode(error, "EPERM") || isNodeErrorWithCode(error, "EACCES")) return false;
+    throw error;
+  }
+}
+
+function isNodeErrorWithCode(error: unknown, code: string): error is NodeJS.ErrnoException {
+  return error instanceof Error && "code" in error && error.code === code;
+}
+
 afterEach(async () => {
   await Promise.all(temporaryRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
 });
@@ -86,6 +106,67 @@ describe("file suggestions", () => {
     expect(suggestions[0]).toEqual({ path: "MD PRojects here.md", kind: "tracked" });
   });
 
+  it("uses fzf to filter and rank file suggestions after candidates are gathered", async () => {
+    const fzfInputs: string[][] = [];
+    const deps: FileSuggestionDependencies = {
+      execFile: (file, args) => {
+        if (file === "git" && args.join(" ") === "ls-files -z") return Promise.resolve({ stdout: "src/server/app.ts\0scripts/start.ts\0docs/reference.md\0" });
+        return Promise.reject(new Error(`unexpected command: ${file} ${args.join(" ")}`));
+      },
+      fzf: (file, args, options) => {
+        expect(file).toBe("fzf");
+        expect(args).toEqual(["--filter", "st", "--read0", "--print0"]);
+        fzfInputs.push(fzfRecords(options.input));
+        return Promise.resolve({ stdout: "scripts/start.ts\0src/server/app.ts\0" });
+      },
+    };
+
+    await expect(listFileSuggestions("/repo", "st", { scope: "tracked" }, deps)).resolves.toEqual([
+      { path: "scripts/start.ts", kind: "tracked" },
+      { path: "src/server/app.ts", kind: "tracked" },
+    ]);
+    expect(fzfInputs).toEqual([[
+      "src/",
+      "src/server/",
+      "src/server/app.ts",
+      "scripts/",
+      "scripts/start.ts",
+      "docs/",
+      "docs/reference.md",
+    ]]);
+  });
+
+  it("falls back to TypeScript file ranking when fzf fails", async () => {
+    let fzfCalls = 0;
+    const deps: FileSuggestionDependencies = {
+      execFile: (file, args) => {
+        if (file === "git" && args.join(" ") === "ls-files -z") return Promise.resolve({ stdout: "klingit-go/cli/cmd/dev/main.go\0MD PRojects here.md\0" });
+        return Promise.reject(new Error(`unexpected command: ${file} ${args.join(" ")}`));
+      },
+      fzf: () => {
+        fzfCalls += 1;
+        return Promise.reject(Object.assign(new Error("spawn fzf ENOENT"), { code: "ENOENT" }));
+      },
+    };
+
+    const suggestions = await listFileSuggestions("/repo", "MD", { scope: "tracked" }, deps);
+
+    expect(fzfCalls).toBe(1);
+    expect(suggestions[0]).toEqual({ path: "MD PRojects here.md", kind: "tracked" });
+  });
+
+  it("treats an fzf no-match exit as an empty filtered result", async () => {
+    const deps: FileSuggestionDependencies = {
+      execFile: (file, args) => {
+        if (file === "git" && args.join(" ") === "ls-files -z") return Promise.resolve({ stdout: "src/app.ts\0" });
+        return Promise.reject(new Error(`unexpected command: ${file} ${args.join(" ")}`));
+      },
+      fzf: () => Promise.reject(Object.assign(new Error("no match"), { exitCode: 1 })),
+    };
+
+    await expect(listFileSuggestions("/repo", "app", { scope: "tracked" }, deps)).resolves.toEqual([]);
+  });
+
   it("preserves git filenames without trimming whitespace", async () => {
     const deps: FileSuggestionDependencies = {
       execFile: (file, args) => {
@@ -120,4 +201,132 @@ describe("file suggestions", () => {
       { path: "src/app.ts", kind: "other" },
     ]);
   });
+
+  it("uses allowed roots for absolute-ish file suggestion queries", async () => {
+    const root = await tempWorkspace();
+    const workspace = join(root, "workspace");
+    const external = join(root, "external-docs");
+    await mkdir(workspace);
+    await mkdir(external);
+    await writeFile(join(external, "sdk.md"), "external sdk\n");
+
+    await expect(listFileSuggestions(workspace, join(external, "s"), { pathAccess: { allowedPaths: [external] } })).resolves.toEqual([
+      { path: join(external, "sdk.md"), kind: "other" },
+    ]);
+  });
+
+  it("skips absolute-ish suggestions that would escape an allowed root through symlinks", async () => {
+    const root = await tempWorkspace();
+    const workspace = join(root, "workspace");
+    const external = join(root, "external-docs");
+    const secret = join(root, "secret");
+    await mkdir(workspace);
+    await mkdir(external);
+    await mkdir(secret);
+    await writeFile(join(external, "sdk.md"), "external sdk\n");
+    await writeFile(join(secret, "token.txt"), "secret\n");
+    if (!await trySymlink(secret, join(external, "escape"))) return;
+
+    await expect(listPathSuggestions(workspace, `${external}/`, { allowedPaths: [external] })).resolves.toEqual([
+      { path: join(external, "sdk.md"), kind: "other" },
+    ]);
+  });
+
+  it("keeps tilde-prefixed allowed-root suggestions matchable by fzf", async () => {
+    const workspace = await tempWorkspace();
+    const homeEntry = await mkdtemp(join(homedir(), ".pi-web-files-"));
+    temporaryRoots.push(homeEntry);
+    const expectedPath = `~/${basename(homeEntry)}/`;
+    const deps: FileSuggestionDependencies = {
+      fzf: (file, args, options) => {
+        expect(file).toBe("fzf");
+        expect(args).toEqual(["--filter", "~/", "--read0", "--print0"]);
+        expect(fzfRecords(options.input)).toContain(expectedPath);
+        return Promise.resolve({ stdout: `${expectedPath}\0` });
+      },
+    };
+
+    await expect(listFileSuggestions(workspace, "~/", { pathAccess: { allowedPaths: ["~/"] } }, deps)).resolves.toEqual([
+      { path: expectedPath, kind: "other" },
+    ]);
+  });
+
+  it("keeps normal file suggestions workspace-local even when allowed roots are configured", async () => {
+    const root = await tempWorkspace();
+    const workspace = join(root, "workspace");
+    const external = join(root, "external-docs");
+    await mkdir(workspace);
+    await mkdir(external);
+    await writeFile(join(external, "sdk.md"), "external sdk\n");
+
+    const deps: FileSuggestionDependencies = {
+      execFile: (file) => Promise.reject(Object.assign(new Error(`spawn ${file} ENOENT`), { code: "ENOENT" })),
+    };
+
+    await expect(listFileSuggestions(workspace, "sdk", { scope: "all", pathAccess: { allowedPaths: [external] } }, deps)).resolves.toEqual([]);
+  });
+
+  it("keeps relative path suggestions workspace-local and skips symlink escapes", async () => {
+    const root = await tempWorkspace();
+    const workspace = join(root, "workspace");
+    const outside = join(root, "outside");
+    await mkdir(workspace);
+    await mkdir(outside);
+    await writeFile(join(workspace, "local.md"), "local\n");
+    await writeFile(join(outside, "outside.txt"), "outside\n");
+
+    await expect(listPathSuggestions(workspace, "../out")).resolves.toEqual([]);
+    if (!await trySymlink(outside, join(workspace, "link"))) return;
+    await expect(listPathSuggestions(workspace, "link/")).resolves.toEqual([]);
+    await expect(listPathSuggestions(workspace, "")).resolves.toEqual([{ path: "local.md", kind: "other" }]);
+  });
+
+  it("uses fzf to filter path suggestions after directory candidates are gathered", async () => {
+    const root = await tempWorkspace();
+    await mkdir(join(root, "scripts"));
+    await mkdir(join(root, "src"));
+    await writeFile(join(root, "notes.md"), "notes\n");
+
+    const deps: FileSuggestionDependencies = {
+      fzf: (file, args, options) => {
+        expect(file).toBe("fzf");
+        expect(args).toEqual(["--filter", "sc", "--read0", "--print0"]);
+        expect(fzfRecords(options.input)).toEqual(["scripts/", "src/", "notes.md"]);
+        return Promise.resolve({ stdout: "../secret\0scripts/\0" });
+      },
+    };
+
+    await expect(listPathSuggestions(root, "sc", undefined, deps)).resolves.toEqual([
+      { path: "scripts/", kind: "other" },
+    ]);
+  });
+
+  it("falls back to path-prefix ordering when fzf fails", async () => {
+    const root = await tempWorkspace();
+    await mkdir(join(root, "scripts"));
+    await mkdir(join(root, "src"));
+    await writeFile(join(root, "server.md"), "server\n");
+
+    const deps: FileSuggestionDependencies = {
+      fzf: () => Promise.reject(Object.assign(new Error("fzf failed"), { exitCode: 2 })),
+    };
+
+    await expect(listPathSuggestions(root, "s", undefined, deps)).resolves.toEqual([
+      { path: "scripts/", kind: "other" },
+      { path: "src/", kind: "other" },
+      { path: "server.md", kind: "other" },
+    ]);
+  });
+
+  it("suggests configured allowed roots without reading parent directories", async () => {
+    const root = await tempWorkspace();
+    const workspace = join(root, "workspace");
+    const external = join(root, "external-docs");
+    await mkdir(workspace);
+    await mkdir(external);
+
+    await expect(listPathSuggestions(workspace, external.slice(0, -4), { allowedPaths: [external] })).resolves.toEqual([
+      { path: `${external}/`, kind: "other" },
+    ]);
+  });
 });

src/server/workspaces/fileSuggestions.ts

@@ -1,19 +1,36 @@
-import { execFile } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
 import { readdir, stat } from "node:fs/promises";
-import { basename, dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, sep, win32 } from "node:path";
 import { promisify } from "node:util";
 import { sanitizedGitEnv } from "../git/gitEnv.js";
+import type { PiWebPathAccessConfig } from "../../shared/apiTypes.js";
 import type { ClientFileSuggestion } from "../types.js";
+import { createPathAccessPolicy, isAbsoluteishPath, resolvePathAccessTarget, type PathAccessPolicy } from "./pathAccessPolicy.js";
 
 const execFileAsync = promisify(execFile);
 const commandMaxBuffer = 1024 * 1024 * 8;
 const maxFilesystemFallbackPaths = 20_000;
 const maxFileSuggestions = 80;
 
-interface ExecFileOptions {
+interface CommandRunnerOptions {
   cwd: string;
   maxBuffer: number;
   env?: NodeJS.ProcessEnv;
+  input?: string | Buffer;
+}
+
+type CommandRunner = (file: string, args: string[], options: CommandRunnerOptions) => Promise<{ stdout: string }>;
+
+class CommandExitError extends Error {
+  readonly exitCode?: number;
+
+  constructor(file: string, code: number | null, stderr: string) {
+    const codeText = code === null ? "unknown" : String(code);
+    super(`${file} exited with code ${codeText}${stderr === "" ? "" : `: ${stderr}`}`);
+    this.name = "CommandExitError";
+    if (code !== null) this.exitCode = code;
+  }
 }
 
 export type FileSuggestionScope = "tracked" | "all";
@@ -21,56 +38,221 @@ export type FileSuggestionScope = "tracked" | "all";
 export interface FileSuggestionOptions {
   kind?: ClientFileSuggestion["kind"] | undefined;
   scope?: FileSuggestionScope | undefined;
+  pathAccess?: PiWebPathAccessConfig | undefined;
 }
 
 export interface FileSuggestionDependencies {
-  execFile?: (file: string, args: string[], options: ExecFileOptions) => Promise<{ stdout: string }>;
+  execFile?: CommandRunner;
+  fzf?: CommandRunner;
+}
+
+export function isAbsoluteishFileSuggestionQuery(query = ""): boolean {
+  return isAbsoluteishPath(fileQueryText(query));
 }
 
 export async function listFileSuggestions(cwd: string, query = "", options: FileSuggestionOptions = {}, deps: FileSuggestionDependencies = {}): Promise<ClientFileSuggestion[]> {
+  const queryText = fileQueryText(query);
+  if (isAbsoluteishFileSuggestionQuery(query)) {
+    return (await listPathSuggestions(cwd, queryText, options.pathAccess, deps))
+      .filter((file) => options.kind === undefined || file.kind === options.kind)
+      .slice(0, maxFileSuggestions);
+  }
+
   const normalizedQuery = normalizeFileQuery(query);
-  const exec = deps.execFile ?? execFileAsync;
-  const files = await listFilesForScope(cwd, options.scope, exec);
-  return rankFileSuggestions(
+  const command = deps.execFile ?? runCommand;
+  const files = await listFilesForScope(cwd, options.scope, command);
+  return (await rankFileSuggestionsWithOptionalFzf(
+    cwd,
     files.filter((file) => options.kind === undefined || file.kind === options.kind),
     normalizedQuery,
-  ).slice(0, maxFileSuggestions);
+    fzfRunnerForDependencies(deps),
+  )).slice(0, maxFileSuggestions);
 }
 
-export async function listPathSuggestions(cwd: string, prefix = ""): Promise<ClientFileSuggestion[]> {
-  const normalizedPrefix = prefix.replace(/^@/, "").replace(/\\/g, "/");
+export async function listPathSuggestions(cwd: string, prefix = "", pathAccess?: PiWebPathAccessConfig, deps: FileSuggestionDependencies = {}): Promise<ClientFileSuggestion[]> {
+  const query = fileQueryText(prefix);
+  const fzf = fzfRunnerForDependencies(deps);
+  if (isAbsoluteishPath(query)) return listAllowedPathSuggestions(cwd, query, pathAccess, fzf);
+
+  const normalizedPrefix = query.replace(/\\/g, "/");
   const directoryPrefix = normalizedPrefix.endsWith("/") ? normalizedPrefix : dirname(normalizedPrefix) === "." ? "" : `${dirname(normalizedPrefix)}/`;
   const searchPrefix = normalizedPrefix.endsWith("/") ? "" : basename(normalizedPrefix);
-  const entries = await readdir(join(cwd, directoryPrefix), { withFileTypes: true });
-  const suggestions: ClientFileSuggestion[] = [];
-  for (const entry of entries) {
-    if (!entry.name.toLowerCase().startsWith(searchPrefix.toLowerCase())) continue;
-    let isDirectory = entry.isDirectory();
-    if (!isDirectory && entry.isSymbolicLink()) {
-      try {
-        isDirectory = (await stat(join(cwd, directoryPrefix, entry.name))).isDirectory();
-      } catch {
-        isDirectory = false;
-      }
-    }
-    suggestions.push({ path: `${directoryPrefix}${entry.name}${isDirectory ? "/" : ""}`, kind: "other" });
-  }
-  return suggestions
-    .sort((a, b) => Number(!a.path.endsWith("/")) - Number(!b.path.endsWith("/")) || a.path.localeCompare(b.path))
-    .slice(0, 80);
+  const candidates = await listDirectoryEntrySuggestions(cwd, directoryPrefix);
+  return (await rankPathSuggestionsWithOptionalFzf(
+    cwd,
+    candidates,
+    searchPrefix,
+    () => prefixPathSuggestions(candidates, searchPrefix),
+    fzf,
+  )).slice(0, maxFileSuggestions);
 }
 
-async function listFilesForScope(cwd: string, scope: FileSuggestionScope | undefined, exec: NonNullable<FileSuggestionDependencies["execFile"]>): Promise<ClientFileSuggestion[]> {
+async function listDirectoryEntrySuggestions(cwd: string, directoryPrefix: string): Promise<ClientFileSuggestion[]> {
+  const policy = await createPathAccessPolicy(cwd, undefined);
+  const resolved = await resolveWorkspaceSuggestionDirectory(policy, directoryPrefix);
+  if (resolved === undefined) return [];
+
+  const entries = await readdir(resolved.target, { withFileTypes: true });
+  const suggestions: ClientFileSuggestion[] = [];
+  for (const entry of entries.sort(compareDirectoryEntries)) {
+    const childPath = appendRequestPath(resolved.displayPath, entry.name);
+    const isDirectory = await suggestionEntryIsDirectory(policy, childPath, entry);
+    if (isDirectory === undefined) continue;
+    suggestions.push({ path: `${childPath}${isDirectory ? "/" : ""}`, kind: "other" });
+  }
+  return suggestions;
+}
+
+async function resolveWorkspaceSuggestionDirectory(policy: PathAccessPolicy, directoryPrefix: string) {
+  try {
+    const resolved = await resolvePathAccessTarget(policy, directoryPrefix);
+    return resolved.kind === "workspace" ? resolved : undefined;
+  } catch (error) {
+    if (isPathSuggestionMiss(error)) return undefined;
+    throw error;
+  }
+}
+
+async function listAllowedPathSuggestions(cwd: string, query: string, pathAccess: PiWebPathAccessConfig | undefined, fzf: CommandRunner | undefined): Promise<ClientFileSuggestion[]> {
+  const policy = await createPathAccessPolicy(cwd, pathAccess);
+  if (policy.allowedRoots.length === 0) throw new Error("Absolute paths are not allowed");
+  const rootCandidates = allowedRootSuggestionCandidates(policy, query);
+  const directoryCandidates = await listAllowedDirectoryEntryCandidates(policy, query);
+  return (await rankPathSuggestionsWithOptionalFzf(
+    cwd,
+    mergeSuggestions(rootCandidates, directoryCandidates),
+    query,
+    () => mergeSuggestions(allowedRootPrefixSuggestions(policy, query), prefixPathSuggestions(directoryCandidates, pathSuggestionPrefix(query).searchPrefix)).sort(compareFileSuggestions),
+    fzf,
+  )).slice(0, maxFileSuggestions);
+}
+
+function allowedRootPrefixSuggestions(policy: PathAccessPolicy, query: string): ClientFileSuggestion[] {
+  return allowedRootSuggestionCandidates(policy, query).filter((suggestion) => pathStartsWith(suggestion.path, query));
+}
+
+function allowedRootSuggestionCandidates(policy: PathAccessPolicy, query: string): ClientFileSuggestion[] {
+  const suggestions: ClientFileSuggestion[] = [];
+  const seen = new Set<string>();
+  for (const root of policy.allowedRoots) {
+    for (const displayPath of allowedRootDisplayPaths(root.path, query)) {
+      const path = ensureTrailingPathSeparator(displayPath);
+      if (hasTrailingPathSeparator(query) && stripTrailingPathSeparators(path) === stripTrailingPathSeparators(query)) continue;
+      if (seen.has(path)) continue;
+      seen.add(path);
+      suggestions.push({ path, kind: "other" });
+    }
+  }
+  return suggestions;
+}
+
+function allowedRootDisplayPaths(rootPath: string, query: string): string[] {
+  if (query !== "~" && !query.startsWith("~/") && !query.startsWith("~\\")) return [rootPath];
+
+  const home = homedir();
+  const homeRelativePath = relative(home, rootPath);
+  if (!isInsideRelativePath(homeRelativePath)) return [rootPath];
+  const separator = query.startsWith("~\\") ? "\\" : "/";
+  const tildePath = homeRelativePath === "" ? "~" : `~${separator}${homeRelativePath.split(/[\\/]+/u).join(separator)}`;
+  return [tildePath, rootPath];
+}
+
+async function listAllowedDirectoryEntryCandidates(policy: PathAccessPolicy, query: string): Promise<ClientFileSuggestion[]> {
+  const { directoryPrefix } = pathSuggestionPrefix(query);
+  const resolved = await resolveSuggestionDirectory(policy, directoryPrefix);
+  if (resolved === undefined) return [];
+
+  const entries = await readdir(resolved.target, { withFileTypes: true });
+  const suggestions: ClientFileSuggestion[] = [];
+  for (const entry of entries.sort(compareDirectoryEntries)) {
+    const childPath = appendRequestPath(directoryPrefix, entry.name);
+    const isDirectory = await suggestionEntryIsDirectory(policy, childPath, entry);
+    if (isDirectory === undefined) continue;
+    suggestions.push({ path: `${childPath}${isDirectory ? "/" : ""}`, kind: "other" });
+  }
+  return suggestions;
+}
+
+async function resolveSuggestionDirectory(policy: PathAccessPolicy, directoryPrefix: string) {
+  try {
+    const resolved = await resolvePathAccessTarget(policy, directoryPrefix);
+    return resolved.kind === "allowed" ? resolved : undefined;
+  } catch (error) {
+    if (isPathSuggestionMiss(error)) return undefined;
+    throw error;
+  }
+}
+
+async function suggestionEntryIsDirectory(policy: PathAccessPolicy, childPath: string, entry: { isDirectory(): boolean; isSymbolicLink(): boolean }): Promise<boolean | undefined> {
+  if (!entry.isSymbolicLink()) return entry.isDirectory();
+
+  try {
+    const resolved = await resolvePathAccessTarget(policy, childPath);
+    const result = await stat(resolved.target);
+    if (result.isDirectory()) return true;
+    if (result.isFile()) return false;
+    return undefined;
+  } catch (error) {
+    if (isPathSuggestionMiss(error)) return undefined;
+    throw error;
+  }
+}
+
+function pathSuggestionPrefix(query: string): { directoryPrefix: string; searchPrefix: string } {
+  if (query === "~" || hasTrailingPathSeparator(query)) return { directoryPrefix: query, searchPrefix: "" };
+  const directory = dirname(query);
+  return { directoryPrefix: directory === "." ? "" : directory, searchPrefix: basename(query) };
+}
+
+function appendRequestPath(base: string, name: string): string {
+  if (base === "") return name;
+  if (isAbsolute(base) || win32.isAbsolute(base)) return join(base, name);
+  if (hasTrailingPathSeparator(base)) return `${base}${name}`;
+  return `${base}/${name}`;
+}
+
+function pathStartsWith(path: string, query: string): boolean {
+  return path.toLowerCase().startsWith(query.toLowerCase());
+}
+
+function ensureTrailingPathSeparator(path: string): string {
+  return hasTrailingPathSeparator(path) ? path : `${path}/`;
+}
+
+function hasTrailingPathSeparator(path: string): boolean {
+  return path.endsWith("/") || path.endsWith("\\");
+}
+
+function stripTrailingPathSeparators(path: string): string {
+  let end = path.length;
+  while (end > 1 && (path[end - 1] === "/" || path[end - 1] === "\\")) end -= 1;
+  return path.slice(0, end);
+}
+
+function isInsideRelativePath(path: string): boolean {
+  return path === "" || (path !== ".." && !path.startsWith(`..${sep}`) && !isAbsolute(path));
+}
+
+function isPathSuggestionMiss(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  return error.message === "Path is outside allowed paths"
+    || error.message === "Path does not exist"
+    || error.message === "Path traversal is not allowed"
+    || error.message === "Path escapes workspace"
+    || error.message.startsWith("Path is not absolute:");
+}
+
+async function listFilesForScope(cwd: string, scope: FileSuggestionScope | undefined, exec: CommandRunner): Promise<ClientFileSuggestion[]> {
   if (scope === "all") return listAllFiles(cwd, exec);
   if (scope === "tracked") return listTrackedFiles(cwd, exec).catch(() => listPlainFiles(cwd, exec, true));
   return listGitFiles(cwd, exec).catch(() => listPlainFiles(cwd, exec, false));
 }
 
-async function listTrackedFiles(cwd: string, exec: NonNullable<FileSuggestionDependencies["execFile"]>): Promise<ClientFileSuggestion[]> {
+async function listTrackedFiles(cwd: string, exec: CommandRunner): Promise<ClientFileSuggestion[]> {
   return withDirectories(nulRecords(await git(cwd, ["ls-files", "-z"], exec)), "tracked");
 }
 
-async function listGitFiles(cwd: string, exec: NonNullable<FileSuggestionDependencies["execFile"]>): Promise<ClientFileSuggestion[]> {
+async function listGitFiles(cwd: string, exec: CommandRunner): Promise<ClientFileSuggestion[]> {
   const [tracked, untracked] = await Promise.all([
     git(cwd, ["ls-files", "-z"], exec),
     git(cwd, ["ls-files", "--others", "--exclude-standard", "-z"], exec),
@@ -81,7 +263,7 @@ async function listGitFiles(cwd: string, exec: NonNullable<FileSuggestionDepende
   ];
 }
 
-async function listAllFiles(cwd: string, exec: NonNullable<FileSuggestionDependencies["execFile"]>): Promise<ClientFileSuggestion[]> {
+async function listAllFiles(cwd: string, exec: CommandRunner): Promise<ClientFileSuggestion[]> {
   const [gitFiles, plainFiles] = await Promise.all([
     listGitFiles(cwd, exec).catch((): ClientFileSuggestion[] => []),
     listPlainFiles(cwd, exec, true),
@@ -89,7 +271,7 @@ async function listAllFiles(cwd: string, exec: NonNullable<FileSuggestionDepende
   return mergeSuggestions(gitFiles, plainFiles);
 }
 
-async function listPlainFiles(cwd: string, exec: NonNullable<FileSuggestionDependencies["execFile"]>, includeIgnored: boolean): Promise<ClientFileSuggestion[]> {
+async function listPlainFiles(cwd: string, exec: CommandRunner, includeIgnored: boolean): Promise<ClientFileSuggestion[]> {
   try {
     const args = includeIgnored ? ["--files", "--hidden", "--no-ignore", "--glob", "!.git", "--glob", "!.git/**"] : ["--files"];
     const { stdout } = await exec("rg", args, { cwd, maxBuffer: commandMaxBuffer });
@@ -138,13 +320,75 @@ async function isSymlinkedFile(cwd: string, relativePath: string, symbolicLink:
   }
 }
 
-async function git(cwd: string, args: string[], exec: NonNullable<FileSuggestionDependencies["execFile"]>): Promise<string> {
+async function git(cwd: string, args: string[], exec: CommandRunner): Promise<string> {
   const { stdout } = await exec("git", args, { cwd, env: sanitizedGitEnv(), maxBuffer: commandMaxBuffer });
   return stdout;
 }
 
 function normalizeFileQuery(query: string): string {
-  return query.replace(/^!@/, "").replace(/^@\s?/, "").replace(/^"/, "").toLowerCase();
+  return fileQueryText(query).toLowerCase();
+}
+
+function fileQueryText(query: string): string {
+  return query.replace(/^!@/, "").replace(/^@\s?/, "").replace(/^"/, "");
+}
+
+function fzfRunnerForDependencies(deps: FileSuggestionDependencies): CommandRunner | undefined {
+  return deps.fzf ?? (deps.execFile === undefined ? runCommand : undefined);
+}
+
+async function rankFileSuggestionsWithOptionalFzf(cwd: string, files: ClientFileSuggestion[], normalizedQuery: string, fzf: CommandRunner | undefined): Promise<ClientFileSuggestion[]> {
+  return rankSuggestionsWithOptionalFzf(cwd, files, normalizedQuery, () => rankFileSuggestions(files, normalizedQuery), fzf);
+}
+
+async function rankPathSuggestionsWithOptionalFzf(cwd: string, candidates: ClientFileSuggestion[], query: string, fallback: () => ClientFileSuggestion[], fzf: CommandRunner | undefined): Promise<ClientFileSuggestion[]> {
+  return rankSuggestionsWithOptionalFzf(cwd, candidates, query, fallback, fzf);
+}
+
+async function rankSuggestionsWithOptionalFzf(cwd: string, candidates: ClientFileSuggestion[], query: string, fallback: () => ClientFileSuggestion[], fzf: CommandRunner | undefined): Promise<ClientFileSuggestion[]> {
+  if (fzf === undefined || query === "" || candidates.length === 0) return fallback();
+
+  try {
+    return await fzfFilterSuggestions(cwd, candidates, query, fzf);
+  } catch {
+    return fallback();
+  }
+}
+
+async function fzfFilterSuggestions(cwd: string, candidates: ClientFileSuggestion[], query: string, fzf: CommandRunner): Promise<ClientFileSuggestion[]> {
+  const byPath = new Map(candidates.map((suggestion) => [suggestion.path, suggestion]));
+  const { stdout } = await runFzf(cwd, [...byPath.keys()], query, fzf);
+  const suggestions: ClientFileSuggestion[] = [];
+  const seen = new Set<string>();
+  for (const path of nulRecords(stdout)) {
+    const suggestion = byPath.get(path);
+    if (suggestion === undefined || seen.has(suggestion.path)) continue;
+    seen.add(suggestion.path);
+    suggestions.push(suggestion);
+  }
+  if (suggestions.length === 0 && stdout !== "") throw new Error("fzf returned paths outside the gathered suggestions");
+  return suggestions;
+}
+
+async function runFzf(cwd: string, candidates: string[], query: string, fzf: CommandRunner): Promise<{ stdout: string }> {
+  try {
+    return await fzf("fzf", ["--filter", query, "--read0", "--print0"], { cwd, maxBuffer: commandMaxBuffer, input: `${candidates.join("\0")}\0` });
+  } catch (error) {
+    if (errorExitCode(error) === 1) return { stdout: "" };
+    throw error;
+  }
+}
+
+function prefixPathSuggestions(candidates: ClientFileSuggestion[], searchPrefix: string): ClientFileSuggestion[] {
+  const normalizedSearchPrefix = searchPrefix.toLowerCase();
+  return candidates
+    .filter((suggestion) => pathSuggestionName(suggestion.path).toLowerCase().startsWith(normalizedSearchPrefix))
+    .sort(compareFileSuggestions);
+}
+
+function pathSuggestionName(path: string): string {
+  const stripped = stripTrailingPathSeparators(path);
+  return stripped.split(/[\\/]+/u).filter(Boolean).at(-1) ?? stripped;
 }
 
 function rankFileSuggestions(files: ClientFileSuggestion[], normalizedQuery: string): ClientFileSuggestion[] {
@@ -197,6 +441,10 @@ function compareFileSuggestions(a: ClientFileSuggestion, b: ClientFileSuggestion
   return Number(!a.path.endsWith("/")) - Number(!b.path.endsWith("/")) || a.path.localeCompare(b.path);
 }
 
+function compareDirectoryEntries(a: { isDirectory(): boolean; name: string }, b: { isDirectory(): boolean; name: string }): number {
+  return Number(!a.isDirectory()) - Number(!b.isDirectory()) || a.name.localeCompare(b.name);
+}
+
 function kindRank(kind: ClientFileSuggestion["kind"]): number {
   switch (kind) {
     case "tracked": return 0;
@@ -209,6 +457,72 @@ function pathDepth(path: string): number {
   return path.split("/").filter(Boolean).length;
 }
 
+async function runCommand(file: string, args: string[], options: CommandRunnerOptions): Promise<{ stdout: string }> {
+  const { input, ...execOptions } = options;
+  if (input === undefined) return execFileAsync(file, args, execOptions);
+  return runCommandWithInput(file, args, { ...execOptions, input });
+}
+
+async function runCommandWithInput(file: string, args: string[], options: CommandRunnerOptions & { input: string | Buffer }): Promise<{ stdout: string }> {
+  return await new Promise((resolve, reject) => {
+    const child = spawn(file, args, {
+      cwd: options.cwd,
+      ...(options.env === undefined ? {} : { env: options.env }),
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    let settled = false;
+    let stdout = "";
+    let stderr = "";
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+
+    const rejectOnce = (error: Error) => {
+      if (settled) return;
+      settled = true;
+      reject(error);
+    };
+
+    child.stdout.on("data", (chunk: Buffer) => {
+      stdoutBytes += chunk.length;
+      if (stdoutBytes > options.maxBuffer) {
+        child.kill();
+        rejectOnce(new Error(`${file} stdout exceeded maxBuffer`));
+        return;
+      }
+      stdout += chunk.toString("utf8");
+    });
+    child.stderr.on("data", (chunk: Buffer) => {
+      stderrBytes += chunk.length;
+      if (stderrBytes > options.maxBuffer) {
+        child.kill();
+        rejectOnce(new Error(`${file} stderr exceeded maxBuffer`));
+        return;
+      }
+      stderr += chunk.toString("utf8");
+    });
+    child.on("error", rejectOnce);
+    child.on("close", (code) => {
+      if (settled) return;
+      settled = true;
+      if (code === 0) {
+        resolve({ stdout });
+        return;
+      }
+      reject(new CommandExitError(file, code, stderr));
+    });
+    child.stdin.on("error", () => undefined);
+    child.stdin.end(options.input);
+  });
+}
+
+function errorExitCode(error: unknown): number | undefined {
+  if (error instanceof CommandExitError) return error.exitCode;
+  if (!(error instanceof Error)) return undefined;
+  if ("exitCode" in error && typeof error.exitCode === "number") return error.exitCode;
+  if ("code" in error && typeof error.code === "number") return error.code;
+  return undefined;
+}
+
 function textLines(text: string): string[] {
   return text.split("\n").map((line) => line.endsWith("\r") ? line.slice(0, -1) : line).filter((line) => line !== "");
 }

src/server/workspaces/fileTreeService.test.ts

@@ -55,6 +55,22 @@ describe("listWorkspaceTree", () => {
     expect(tree.entries[0]).toMatchObject({ name: "main.ts", path: "src/client/main.ts", type: "file" });
   });
 
+  it("lists allowed absolute directories outside the workspace", async () => {
+    const root = await tempWorkspace();
+    const external = await tempWorkspace();
+    await mkdir(join(external, "docs"));
+    await writeFile(join(external, "sdk.ts"), "export {};\n");
+
+    const tree = await listWorkspaceTree(root, external, { allowedPaths: [external] });
+
+    expect(tree.path).toBe(external);
+    expect(tree.entries.map((entry) => [entry.name, entry.path, entry.type])).toEqual([
+      ["docs", join(external, "docs"), "directory"],
+      ["sdk.ts", join(external, "sdk.ts"), "file"],
+    ]);
+    await expect(listWorkspaceTree(root, external)).rejects.toThrow("Absolute paths are not allowed");
+  });
+
   it("rejects non-directory targets and unsafe paths", async () => {
     const root = await tempWorkspace();
     await writeFile(join(root, "file.txt"), "content");

src/server/workspaces/fileTreeService.ts

@@ -1,12 +1,12 @@
 import { lstat, readdir } from "node:fs/promises";
-import { join } from "node:path";
-import type { FileTreeEntry, FileTreeResponse } from "../../shared/apiTypes.js";
-import { resolveInsideWorkspace } from "./pathSafety.js";
+import { isAbsolute, join, win32 } from "node:path";
+import type { FileTreeEntry, FileTreeResponse, PiWebPathAccessConfig } from "../../shared/apiTypes.js";
+import { resolveWorkspacePathAccessTarget } from "./pathAccessPolicy.js";
 
 const MAX_ENTRIES = 1000;
 
-export async function listWorkspaceTree(rootPath: string, path: string | undefined): Promise<FileTreeResponse> {
-  const { target, relativePath } = await resolveInsideWorkspace(rootPath, path);
+export async function listWorkspaceTree(rootPath: string, path: string | undefined, pathAccess?: PiWebPathAccessConfig): Promise<FileTreeResponse> {
+  const { target, displayPath } = await resolveWorkspacePathAccessTarget(rootPath, path, pathAccess);
   const stat = await lstat(target);
   if (!stat.isDirectory()) throw new Error("Path is not a directory");
 
@@ -18,11 +18,18 @@ export async function listWorkspaceTree(rootPath: string, path: string | undefin
   const selected = sorted.slice(0, MAX_ENTRIES);
   const entries = await Promise.all(selected.map(async (entry): Promise<FileTreeEntry> => {
     const absolute = join(target, entry.name);
-    const childRelative = relativePath === "" ? entry.name : `${relativePath}/${entry.name}`;
+    const childPath = appendRequestPath(displayPath, entry.name);
     const childStat = await lstat(absolute);
     const type: FileTreeEntry["type"] = entry.isDirectory() ? "directory" : entry.isSymbolicLink() ? "symlink" : "file";
-    return { name: entry.name, path: childRelative, type, size: childStat.size, modifiedAt: childStat.mtime.toISOString() };
+    return { name: entry.name, path: childPath, type, size: childStat.size, modifiedAt: childStat.mtime.toISOString() };
   }));
 
-  return { path: relativePath, entries, scannedAt: new Date().toISOString(), truncated: sorted.length > selected.length };
+  return { path: displayPath, entries, scannedAt: new Date().toISOString(), truncated: sorted.length > selected.length };
+}
+
+function appendRequestPath(base: string, name: string): string {
+  if (base === "") return name;
+  if (isAbsolute(base) || win32.isAbsolute(base)) return join(base, name);
+  if (base.endsWith("/") || base.endsWith("\\")) return `${base}${name}`;
+  return `${base}/${name}`;
 }

src/server/workspaces/imagePreviewService.ts

@@ -1,8 +1,9 @@
 import { createReadStream, type ReadStream } from "node:fs";
 import { stat } from "node:fs/promises";
 import { extname } from "node:path";
+import type { PiWebPathAccessConfig } from "../../shared/apiTypes.js";
 import { MAX_IMAGE_PREVIEW_BYTES, MAX_IMAGE_PREVIEW_LABEL } from "../../shared/workspaceFiles.js";
-import { resolveInsideWorkspace } from "./pathSafety.js";
+import { resolveWorkspacePathAccessTarget } from "./pathAccessPolicy.js";
 
 const IMAGE_MIME_TYPES: Record<string, string | undefined> = {
   ".avif": "image/avif",
@@ -28,16 +29,16 @@ export function imageMimeTypeForPath(path: string): string | undefined {
   return IMAGE_MIME_TYPES[extname(path).toLowerCase()];
 }
 
-export async function readWorkspaceImagePreview(rootPath: string, path: string | undefined): Promise<WorkspaceImagePreview> {
+export async function readWorkspaceImagePreview(rootPath: string, path: string | undefined, pathAccess?: PiWebPathAccessConfig): Promise<WorkspaceImagePreview> {
   if (path === undefined || path === "") throw new Error("path query parameter is required");
-  const { target, relativePath } = await resolveInsideWorkspace(rootPath, path);
+  const { target, displayPath } = await resolveWorkspacePathAccessTarget(rootPath, path, pathAccess);
   const s = await stat(target);
   if (!s.isFile()) throw new Error("Path is not a file");
-  const mimeType = imageMimeTypeForPath(relativePath);
+  const mimeType = imageMimeTypeForPath(displayPath);
   if (mimeType === undefined) throw new Error("Image preview is not supported for this file type");
   if (s.size > MAX_IMAGE_PREVIEW_BYTES) throw new Error(`Image is too large to preview (limit ${MAX_IMAGE_PREVIEW_LABEL})`);
   return {
-    path: relativePath,
+    path: displayPath,
     mimeType,
     size: s.size,
     modifiedAt: s.mtime.toISOString(),

src/server/workspaces/pathAccessPolicy.test.ts

@@ -0,0 +1,139 @@
+import { mkdtemp, mkdir, realpath, rm, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { createPathAccessPolicy, isAbsoluteishPath, resolvePathAccessTarget, resolveWorkspacePathAccessTarget } from "./pathAccessPolicy.js";
+
+const roots: string[] = [];
+
+async function tempRoot(prefix = "pi-web-path-access-"): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), prefix));
+  roots.push(root);
+  return root;
+}
+
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+describe("path access policy", () => {
+  it("keeps relative requests workspace-local and identifies absolute-ish paths", async () => {
+    const workspace = await tempRoot();
+    await mkdir(join(workspace, "src"));
+    await writeFile(join(workspace, "src", "main.ts"), "export {};\n");
+    const policy = await createPathAccessPolicy(workspace, undefined);
+
+    await expect(resolvePathAccessTarget(policy, "./src//main.ts")).resolves.toMatchObject({
+      kind: "workspace",
+      root: await realpath(workspace),
+      target: await realpath(join(workspace, "src", "main.ts")),
+      displayPath: "src/main.ts",
+    });
+
+    expect(isAbsoluteishPath("src/main.ts")).toBe(false);
+    expect(isAbsoluteishPath("/tmp/file.txt")).toBe(true);
+    expect(isAbsoluteishPath("~/SDKs/readme.md")).toBe(true);
+    expect(isAbsoluteishPath("C:\\Users\\dev\\file.txt")).toBe(true);
+    expect(isAbsoluteishPath("\\\\server\\share\\file.txt")).toBe(true);
+    await expect(resolvePathAccessTarget(policy, join(workspace, "src", "main.ts"))).rejects.toThrow("Absolute paths are not allowed");
+  });
+
+  it("expands and canonicalizes allowed roots before resolving absolute targets", async () => {
+    const root = await tempRoot();
+    const workspace = join(root, "workspace");
+    const home = join(root, "home");
+    const sdk = join(home, "SDKs");
+    await mkdir(workspace);
+    await mkdir(sdk, { recursive: true });
+    await writeFile(join(sdk, "readme.md"), "sdk docs\n");
+
+    const policy = await createPathAccessPolicy(workspace, { allowedPaths: ["~/SDKs"] }, { homeDir: home });
+
+    expect(policy.allowedRoots).toEqual([{ source: "~/SDKs", path: sdk, realPath: await realpath(sdk) }]);
+    await expect(resolvePathAccessTarget(policy, "~/SDKs/readme.md", { homeDir: home })).resolves.toMatchObject({
+      kind: "allowed",
+      root: await realpath(sdk),
+      target: await realpath(join(sdk, "readme.md")),
+      displayPath: join(sdk, "readme.md"),
+    });
+  });
+
+  it("validates configured roots as existing directories", async () => {
+    const root = await tempRoot();
+    const workspace = join(root, "workspace");
+    const fileRoot = join(root, "not-a-directory.txt");
+    await mkdir(workspace);
+    await writeFile(fileRoot, "not a directory");
+
+    await expect(createPathAccessPolicy(workspace, { allowedPaths: [join(root, "missing")] })).rejects.toThrow("does not exist");
+    await expect(createPathAccessPolicy(workspace, { allowedPaths: [fileRoot] })).rejects.toThrow("must be a directory");
+    await expect(createPathAccessPolicy(workspace, { allowedPaths: ["relative/root"] })).rejects.toThrow("Allowed path must be absolute or start with ~");
+  });
+
+  it("does not validate stale allowed roots for workspace-relative requests", async () => {
+    const root = await tempRoot();
+    const workspace = join(root, "workspace");
+    await mkdir(workspace);
+    await writeFile(join(workspace, "local.txt"), "local\n");
+
+    await expect(resolveWorkspacePathAccessTarget(workspace, "local.txt", { allowedPaths: [join(root, "missing")] })).resolves.toMatchObject({
+      kind: "workspace",
+      target: await realpath(join(workspace, "local.txt")),
+      displayPath: "local.txt",
+    });
+    await expect(resolveWorkspacePathAccessTarget(workspace, join(workspace, "local.txt"), { allowedPaths: [join(root, "missing")] })).rejects.toThrow("does not exist");
+  });
+
+  it("denies absolute targets outside allowed roots and through symlink escapes", async () => {
+    const root = await tempRoot();
+    const workspace = join(root, "workspace");
+    const allowed = join(root, "allowed");
+    const secret = join(root, "secret");
+    await mkdir(workspace);
+    await mkdir(allowed);
+    await mkdir(secret);
+    await writeFile(join(secret, "token.txt"), "secret\n");
+    const policy = await createPathAccessPolicy(workspace, { allowedPaths: [allowed] });
+
+    await expect(resolvePathAccessTarget(policy, join(secret, "token.txt"))).rejects.toThrow("Path is outside allowed paths");
+
+    if (await trySymlink(secret, join(allowed, "escape"))) {
+      await expect(resolvePathAccessTarget(policy, join(allowed, "escape", "token.txt"))).rejects.toThrow("Path is outside allowed paths");
+    }
+  });
+
+  it("allows roots configured through symlinks by checking canonical paths", async () => {
+    const root = await tempRoot();
+    const workspace = join(root, "workspace");
+    const realAllowed = join(root, "real-allowed");
+    const linkedAllowed = join(root, "linked-allowed");
+    await mkdir(workspace);
+    await mkdir(realAllowed);
+    await writeFile(join(realAllowed, "data.txt"), "allowed\n");
+    if (!await trySymlink(realAllowed, linkedAllowed)) return;
+
+    const policy = await createPathAccessPolicy(workspace, { allowedPaths: [linkedAllowed] });
+
+    expect(policy.allowedRoots).toEqual([{ source: linkedAllowed, path: linkedAllowed, realPath: await realpath(realAllowed) }]);
+    await expect(resolvePathAccessTarget(policy, join(linkedAllowed, "data.txt"))).resolves.toMatchObject({
+      kind: "allowed",
+      root: await realpath(realAllowed),
+      target: await realpath(join(realAllowed, "data.txt")),
+      displayPath: join(linkedAllowed, "data.txt"),
+    });
+  });
+});
+
+async function trySymlink(target: string, path: string): Promise<boolean> {
+  try {
+    await symlink(target, path, "dir");
+    return true;
+  } catch (error) {
+    if (isNodeErrorWithCode(error, "EPERM") || isNodeErrorWithCode(error, "EACCES")) return false;
+    throw error;
+  }
+}
+
+function isNodeErrorWithCode(error: unknown, code: string): error is NodeJS.ErrnoException {
+  return error instanceof Error && "code" in error && error.code === code;
+}

src/server/workspaces/pathAccessPolicy.ts

@@ -0,0 +1,122 @@
+import { realpath, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, relative, resolve, sep, win32 } from "node:path";
+import type { PiWebPathAccessConfig } from "../../shared/apiTypes.js";
+import { normalizeRelativePath } from "./pathSafety.js";
+
+export interface AllowedPathRoot {
+  /** Raw config value for diagnostics. */
+  source: string;
+  /** Host-absolute path after expanding ~ and normalizing syntax. */
+  path: string;
+  /** Canonical directory root used for containment checks. */
+  realPath: string;
+}
+
+export interface PathAccessPolicy {
+  workspaceRoot: string;
+  allowedRoots: AllowedPathRoot[];
+}
+
+export type PathAccessTargetKind = "workspace" | "allowed";
+
+export interface ResolvedPathAccessTarget {
+  kind: PathAccessTargetKind;
+  /** Canonical root that granted access: workspace root or allowed root. */
+  root: string;
+  /** Canonical existing target path. */
+  target: string;
+  /** Requestable path returned to clients and used to build child paths. */
+  displayPath: string;
+}
+
+export interface PathAccessPolicyOptions {
+  homeDir?: string;
+}
+
+export async function createPathAccessPolicy(workspaceRootPath: string, pathAccess: PiWebPathAccessConfig | undefined, options: PathAccessPolicyOptions = {}): Promise<PathAccessPolicy> {
+  return {
+    workspaceRoot: await canonicalDirectory(workspaceRootPath, "Workspace path"),
+    allowedRoots: await resolveAllowedRoots(pathAccess?.allowedPaths ?? [], options),
+  };
+}
+
+export async function resolveWorkspacePathAccessTarget(rootPath: string, requestedPath: string | undefined, pathAccess?: PiWebPathAccessConfig, options: PathAccessPolicyOptions = {}): Promise<ResolvedPathAccessTarget> {
+  const request = requestedPath ?? "";
+  const workspaceRoot = await canonicalDirectory(rootPath, "Workspace path");
+  const allowedRoots = isAbsoluteishPath(request) ? await resolveAllowedRoots(pathAccess?.allowedPaths ?? [], options) : [];
+  return resolvePathAccessTarget({ workspaceRoot, allowedRoots }, requestedPath, options);
+}
+
+export async function resolvePathAccessTarget(policy: PathAccessPolicy, requestedPath: string | undefined, options: PathAccessPolicyOptions = {}): Promise<ResolvedPathAccessTarget> {
+  const request = requestedPath ?? "";
+  if (isAbsoluteishPath(request)) return resolveAllowedTarget(policy, request, options);
+
+  const displayPath = normalizeRelativePath(request);
+  const target = await canonicalExistingPath(resolve(policy.workspaceRoot, displayPath));
+  ensureInside(policy.workspaceRoot, target, "Path escapes workspace");
+  return { kind: "workspace", root: policy.workspaceRoot, target, displayPath };
+}
+
+export function isAbsoluteishPath(path: string): boolean {
+  return path === "~" || path.startsWith("~/") || path.startsWith("~\\") || isAbsolute(path) || win32.isAbsolute(path);
+}
+
+async function resolveAllowedRoots(allowedPaths: readonly string[], options: PathAccessPolicyOptions): Promise<AllowedPathRoot[]> {
+  const roots: AllowedPathRoot[] = [];
+  for (const source of allowedPaths) {
+    const expanded = expandAbsoluteishPath(source, options, `Allowed path must be absolute or start with ~: ${source}`);
+    const realPath = await canonicalDirectory(expanded, `Allowed path ${source}`);
+    if (roots.some((root) => root.realPath === realPath)) continue;
+    roots.push({ source, path: expanded, realPath });
+  }
+  return roots;
+}
+
+async function resolveAllowedTarget(policy: PathAccessPolicy, request: string, options: PathAccessPolicyOptions): Promise<ResolvedPathAccessTarget> {
+  if (policy.allowedRoots.length === 0) throw new Error("Absolute paths are not allowed");
+
+  const displayPath = expandAbsoluteishPath(request, options, `Path is not absolute: ${request}`);
+  const target = await canonicalExistingPath(displayPath);
+  const root = policy.allowedRoots.find((allowedRoot) => isInsideOrSame(allowedRoot.realPath, target));
+  if (root === undefined) throw new Error("Path is outside allowed paths");
+  return { kind: "allowed", root: root.realPath, target, displayPath };
+}
+
+function expandAbsoluteishPath(path: string, options: PathAccessPolicyOptions, relativeMessage: string): string {
+  const home = options.homeDir ?? homedir();
+  if (path === "~") return home;
+  if (path.startsWith("~/") || path.startsWith("~\\")) return resolve(home, path.slice(2));
+  if (isAbsolute(path)) return resolve(path);
+  if (win32.isAbsolute(path)) throw new Error(`Absolute path is not valid on this host: ${path}`);
+  throw new Error(relativeMessage);
+}
+
+async function canonicalDirectory(path: string, label: string): Promise<string> {
+  const canonical = await canonicalExistingPath(path, `${label} does not exist`);
+  const result = await stat(canonical);
+  if (!result.isDirectory()) throw new Error(`${label} must be a directory`);
+  return canonical;
+}
+
+async function canonicalExistingPath(path: string, missingMessage = "Path does not exist"): Promise<string> {
+  try {
+    return await realpath(path);
+  } catch (error) {
+    if (isNodeErrorWithCode(error, "ENOENT")) throw new Error(missingMessage, { cause: error });
+    throw error;
+  }
+}
+
+function ensureInside(root: string, target: string, message: string): void {
+  if (!isInsideOrSame(root, target)) throw new Error(message);
+}
+
+function isInsideOrSame(root: string, target: string): boolean {
+  const rel = relative(root, target);
+  return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
+}
+
+function isNodeErrorWithCode(error: unknown, code: string): error is NodeJS.ErrnoException {
+  return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}

src/server/workspaces/projectPiWebConfig.test.ts

@@ -0,0 +1,74 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { tmpdir } from "node:os";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { loadEffectiveProjectPathAccess, loadProjectPiWebConfig, mergePathAccessConfigs, PROJECT_PI_WEB_CONFIG_PATH } from "./projectPiWebConfig.js";
+
+let tempDir: string;
+let projectPath: string;
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "pi-web-project-config-test-"));
+  projectPath = join(tempDir, "project");
+  await mkdir(projectPath, { recursive: true });
+});
+
+afterEach(async () => {
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+describe("project PI WEB config", () => {
+  it("returns an empty config when the project-local config is absent", async () => {
+    await expect(loadProjectPiWebConfig(projectPath)).resolves.toEqual({
+      path: join(projectPath, PROJECT_PI_WEB_CONFIG_PATH),
+      exists: false,
+      config: {},
+    });
+  });
+
+  it("loads project-local path access config", async () => {
+    await writeProjectConfig({ version: 1, pathAccess: { allowedPaths: ["/tmp", "~/SDKs"] } });
+
+    await expect(loadProjectPiWebConfig(projectPath)).resolves.toEqual({
+      path: join(projectPath, PROJECT_PI_WEB_CONFIG_PATH),
+      exists: true,
+      config: { version: 1, pathAccess: { allowedPaths: ["/tmp", "~/SDKs"] } },
+    });
+  });
+
+  it("rejects unsupported project config versions", async () => {
+    await writeProjectConfig({ version: 2 });
+
+    await expect(loadProjectPiWebConfig(projectPath)).rejects.toThrow("PI WEB project config version must be 1");
+  });
+
+  it("reuses PI WEB path access schema validation", async () => {
+    await writeProjectConfig({ version: 1, pathAccess: { allowedPaths: [""] } });
+
+    await expect(loadProjectPiWebConfig(projectPath)).rejects.toThrow("PI WEB config pathAccess.allowedPaths must be an array of non-empty strings");
+  });
+
+  it("merges global and project path access in order", async () => {
+    await writeProjectConfig({ version: 1, pathAccess: { allowedPaths: ["/project-sdk", "/shared"] } });
+
+    await expect(loadEffectiveProjectPathAccess(projectPath, { pathAccess: { allowedPaths: ["/global-sdk", "/shared"] } })).resolves.toEqual({
+      allowedPaths: ["/global-sdk", "/shared", "/project-sdk"],
+    });
+  });
+});
+
+describe("mergePathAccessConfigs", () => {
+  it("returns undefined when no roots are configured", () => {
+    expect(mergePathAccessConfigs(undefined, {})).toBeUndefined();
+  });
+
+  it("deduplicates configured roots", () => {
+    expect(mergePathAccessConfigs({ allowedPaths: ["/a", "/b"] }, { allowedPaths: ["/b", "/c"] })).toEqual({ allowedPaths: ["/a", "/b", "/c"] });
+  });
+});
+
+async function writeProjectConfig(value: unknown): Promise<void> {
+  const path = join(projectPath, PROJECT_PI_WEB_CONFIG_PATH);
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}

src/server/workspaces/projectPiWebConfig.ts

@@ -0,0 +1,71 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parsePathAccessConfig, type PiWebConfig } from "../../config.js";
+import type { PiWebPathAccessConfig } from "../../shared/apiTypes.js";
+
+export const PROJECT_PI_WEB_CONFIG_PATH = ".pi-web/config.json";
+
+export interface ProjectPiWebConfig {
+  version?: 1;
+  pathAccess?: PiWebPathAccessConfig;
+}
+
+export interface LoadedProjectPiWebConfig {
+  path: string;
+  exists: boolean;
+  config: ProjectPiWebConfig;
+}
+
+export async function loadProjectPiWebConfig(projectPath: string): Promise<LoadedProjectPiWebConfig> {
+  const path = join(projectPath, PROJECT_PI_WEB_CONFIG_PATH);
+  try {
+    const parsed: unknown = JSON.parse(await readFile(path, "utf8"));
+    if (!isRecord(parsed)) throw new Error(`PI WEB project config must be a JSON object: ${path}`);
+    return { path, exists: true, config: parseProjectPiWebConfig(parsed, path) };
+  } catch (error) {
+    if (isNodeErrorWithCode(error, "ENOENT")) return { path, exists: false, config: {} };
+    throw error;
+  }
+}
+
+export async function loadEffectiveProjectPathAccess(projectPath: string, globalConfig: PiWebConfig): Promise<PiWebPathAccessConfig | undefined> {
+  const projectConfig = await loadProjectPiWebConfig(projectPath);
+  return mergePathAccessConfigs(globalConfig.pathAccess, projectConfig.config.pathAccess);
+}
+
+export function mergePathAccessConfigs(...configs: (PiWebPathAccessConfig | undefined)[]): PiWebPathAccessConfig | undefined {
+  const allowedPaths = dedupe(configs.flatMap((config) => config?.allowedPaths ?? []));
+  return allowedPaths.length === 0 ? undefined : { allowedPaths };
+}
+
+function parseProjectPiWebConfig(value: Record<string, unknown>, path: string): ProjectPiWebConfig {
+  const version = value["version"];
+  return {
+    ...(version !== undefined ? { version: parseProjectConfigVersion(version, path) } : {}),
+    ...(value["pathAccess"] !== undefined ? { pathAccess: parsePathAccessConfig(value["pathAccess"], path) } : {}),
+  };
+}
+
+function parseProjectConfigVersion(value: unknown, path: string): 1 {
+  if (value !== 1) throw new Error(`PI WEB project config version must be 1: ${path}`);
+  return 1;
+}
+
+function dedupe(values: readonly string[]): string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const value of values) {
+    if (seen.has(value)) continue;
+    seen.add(value);
+    result.push(value);
+  }
+  return result;
+}
+
+function isNodeErrorWithCode(error: unknown, code: string): error is NodeJS.ErrnoException {
+  return error instanceof Error && "code" in error && error.code === code;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}