pi-studio 0.9.52 → 0.9.53

package/index.ts

@@ -32,6 +32,7 @@ import { escapeStudioPdfLatexTextFragment } from "./shared/studio-pdf-escape.js"
 import { parseStudioLocalPreviewPage, parseStudioPdfLaunchTarget } from "./shared/studio-local-preview-path.js";
 import { resolveStudioPdfResourceFile } from "./shared/studio-pdf-resource.js";
 import { createStudioPandocHtmlResourceFlagResolver } from "./shared/studio-pandoc-resource-flag.js";
+import { createStudioResourceGrantRegistry } from "./shared/studio-resource-grants.js";
 import { prepareStudioLatexForPandoc } from "./shared/studio-latex-pandoc-compat.js";
 import { isStudioCmuxSession, openStudioUrlInBrowser } from "./shared/studio-browser-launcher.js";
 import { buildStudioReplTmuxStartArgs } from "./shared/studio-repl-tmux.js";
@@ -75,6 +76,7 @@ import {
 } from "./shared/studio-side-question.js";
 import {
 	STUDIO_SIDE_CONTEXT_MAX_OUTPUT_CHARS,
+	assertStudioSideQuestionRootStable,
 	formatStudioSideQuestionContextMap,
 	listStudioSideQuestionContext,
 	readStudioSideQuestionContextText,
@@ -451,6 +453,8 @@ interface StudioSideQuestionToolDescriptor {
 	gateway: boolean;
 }
 
+type StudioSideQuestionContextRootInput = Pick<StudioSideQuestionContextInput, "sourcePath" | "resourceDir" | "gatherScope" | "contextPath">;
+
 interface StudioSideQuestionContextInput {
 	focusKind: StudioSideQuestionFocusKind;
 	focusLabel: string;
@@ -3103,12 +3107,13 @@ function buildStudioCompanionLabel(_label: string | undefined): string {
 }
 
 const STUDIO_HTML_PREVIEW_RESOURCE_MAX_BYTES = 25 * 1024 * 1024;
-const STUDIO_HTML_PREVIEW_IMAGE_MIME_BY_EXT = new Map<string, string>([
+const STUDIO_HTML_PREVIEW_MEDIA_MIME_BY_EXT = new Map<string, string>([
 	[".png", "image/png"],
 	[".jpg", "image/jpeg"],
 	[".jpeg", "image/jpeg"],
 	[".gif", "image/gif"],
 	[".webp", "image/webp"],
+	[".pdf", "application/pdf"],
 ]);
 const STUDIO_LOCAL_LINK_TEXT_EXTENSIONS = new Set([
 	".md", ".markdown", ".mdx", ".qmd", ".txt", ".tex", ".latex", ".rst", ".adoc",
@@ -3133,9 +3138,37 @@ const STUDIO_FILE_BROWSER_IGNORED_DIRS = new Set([
 
 type StudioLocalPreviewResourceKind = "pdf" | "text" | "image" | "office" | "other";
 type StudioFileBrowserSortMode = "name" | "mtime-desc" | "mtime-asc" | "size-desc" | "size-asc";
+type StudioResourceGrantRegistry = ReturnType<typeof createStudioResourceGrantRegistry>;
+
+class StudioResourceGrantRequiredError extends Error {
+	readonly code = "studio-resource-grant-required";
+	readonly filePath: string;
+	readonly directoryPath: string;
+	readonly resourceKind: StudioLocalPreviewResourceKind;
+
+	constructor(filePath: string, resourceKind: StudioLocalPreviewResourceKind) {
+		super("This local resource is outside the locations currently available to Studio.");
+		this.name = "StudioResourceGrantRequiredError";
+		this.filePath = filePath;
+		this.directoryPath = dirname(filePath);
+		this.resourceKind = resourceKind;
+	}
+}
+
+class StudioDirectoryGrantRequiredError extends Error {
+	readonly code = "studio-resource-directory-grant-required";
+	readonly directoryPath: string;
+
+	constructor(directoryPath: string) {
+		super("This folder is not available to the current Studio session.");
+		this.name = "StudioDirectoryGrantRequiredError";
+		this.directoryPath = directoryPath;
+	}
+}
 
 interface StudioLocalPreviewResource {
 	filePath: string;
+	referencePath: string;
 	label: string;
 	extension: string;
 	kind: StudioLocalPreviewResourceKind;
@@ -3154,6 +3187,11 @@ interface StudioFileBrowserEntry {
 	hidden: boolean;
 }
 
+interface StudioFileBrowserLocation {
+	path: string;
+	label: string;
+}
+
 function normalizeStudioFileBrowserSortMode(sort: string | null | undefined): StudioFileBrowserSortMode {
 	const value = typeof sort === "string" ? sort.trim().toLowerCase() : "";
 	if (value === "mtime-desc" || value === "modified-desc" || value === "newest") return "mtime-desc";
@@ -3177,25 +3215,34 @@ function compareStudioFileBrowserEntries(a: StudioFileBrowserEntry, b: StudioFil
 	return compareStudioFileBrowserEntryNames(a, b);
 }
 
-function resolveStudioPdfResourcePath(pdfPath: string | undefined, sourcePath: string | undefined, resourceDir: string | undefined, fallbackCwd: string): string {
+function resolveStudioPdfResourcePath(
+	pdfPath: string | undefined,
+	sourcePath: string | undefined,
+	resourceDir: string | undefined,
+	fallbackCwd: string,
+	resourceGrants?: StudioResourceGrantRegistry,
+): string {
 	const rawPath = typeof pdfPath === "string" ? pdfPath.trim() : "";
 	if (!rawPath) throw new Error("Missing PDF path.");
 	if (/\0/.test(rawPath)) throw new Error("Invalid PDF path.");
-	if (/^[a-z][a-z0-9+.-]*:/i.test(rawPath) && !/^[a-z]:[\\/]/i.test(rawPath)) {
+	if (/^[a-z][a-z0-9+.-]*:/i.test(rawPath) && !/^file:/i.test(rawPath) && !/^[a-z]:[\\/]/i.test(rawPath)) {
 		throw new Error("Only local PDF paths are supported.");
 	}
 
 	const context = resolveStudioPreviewResourceContext(sourcePath, resourceDir, fallbackCwd);
-	const cleanedPath = decodeStudioHtmlPreviewResourcePath(stripStudioHtmlPreviewResourceUrlSuffix(rawPath));
+	const cleanedPath = decodeStudioLocalPreviewResourceReference(rawPath);
 	const expandedPath = recoverLikelyDroppedLeadingSlashPath(expandHome(cleanedPath));
 	const candidate = isAbsolute(expandedPath) ? expandedPath : resolve(context.baseDir, expandedPath);
 	if (extname(candidate).toLowerCase() !== ".pdf") throw new Error("Only .pdf files can be embedded.");
 
-	const boundaryReal = realpathSync(context.boundaryDir);
 	const candidateReal = realpathSync(candidate);
-	const rel = relative(boundaryReal, candidateReal);
-	if (rel.startsWith("..") || isAbsolute(rel)) {
-		throw new Error("PDF path must stay within the current Studio resource directory.");
+	if (resourceGrants) {
+		if (!resourceGrants.allows(candidateReal)) throw new StudioResourceGrantRequiredError(candidateReal, "pdf");
+	} else {
+		const boundaryReal = realpathSync(context.boundaryDir);
+		if (!isPathInsideOrEqualDirectory(candidateReal, boundaryReal)) {
+			throw new Error("PDF path must stay within the current Studio resource directory.");
+		}
 	}
 
 	const stat = statSync(candidateReal);
@@ -3216,6 +3263,22 @@ function decodeStudioHtmlPreviewResourcePath(resourcePath: string): string {
 	}
 }
 
+function decodeStudioLocalPreviewResourceReference(resourcePath: string): string {
+	const raw = String(resourcePath ?? "").trim();
+	if (!/^file:/i.test(raw)) {
+		return decodeStudioHtmlPreviewResourcePath(stripStudioHtmlPreviewResourceUrlSuffix(raw));
+	}
+	try {
+		const url = new URL(raw);
+		if (url.protocol !== "file:") throw new Error("Not a file URL.");
+		url.hash = "";
+		url.search = "";
+		return fileURLToPath(url);
+	} catch {
+		throw new Error("Invalid local file URL.");
+	}
+}
+
 function getStudioLocalPreviewResourceKind(extension: string, filePathOrName?: string): StudioLocalPreviewResourceKind {
 	const ext = extension.toLowerCase();
 	const name = basename(String(filePathOrName || "")).toLowerCase();
@@ -3231,60 +3294,128 @@ function resolveStudioLocalPreviewResourcePath(
 	sourcePath: string | undefined,
 	resourceDir: string | undefined,
 	fallbackCwd: string,
+	resourceGrants?: StudioResourceGrantRegistry,
 ): StudioLocalPreviewResource {
 	const rawPath = typeof resourcePath === "string" ? resourcePath.trim() : "";
 	if (!rawPath) throw new Error("Missing local resource path.");
 	if (/\0/.test(rawPath)) throw new Error("Invalid local resource path.");
 	if (/^\/\//.test(rawPath)) throw new Error("Network resources are not local Studio resources.");
-	if (/^[a-z][a-z0-9+.-]*:/i.test(rawPath) && !/^[a-z]:[\\/]/i.test(rawPath)) {
-		throw new Error("Only local relative resources are supported.");
+	if (/^[a-z][a-z0-9+.-]*:/i.test(rawPath) && !/^file:/i.test(rawPath) && !/^[a-z]:[\\/]/i.test(rawPath)) {
+		throw new Error("Only local file paths and file URLs are supported.");
 	}
 
 	const context = resolveStudioPreviewResourceContext(sourcePath, resourceDir, fallbackCwd);
-	const cleanedPath = decodeStudioHtmlPreviewResourcePath(stripStudioHtmlPreviewResourceUrlSuffix(rawPath));
+	const cleanedPath = decodeStudioLocalPreviewResourceReference(rawPath);
 	if (!cleanedPath || cleanedPath.startsWith("#")) throw new Error("Missing local resource path.");
 	const expandedPath = recoverLikelyDroppedLeadingSlashPath(expandHome(cleanedPath));
 	const candidate = isAbsolute(expandedPath) ? expandedPath : resolve(context.baseDir, expandedPath);
 	const extension = extname(candidate).toLowerCase();
-	const boundaryReal = realpathSync(context.boundaryDir);
 	const candidateReal = realpathSync(candidate);
-	const rel = relative(boundaryReal, candidateReal);
-	if (rel.startsWith("..") || isAbsolute(rel)) {
-		throw new Error("Local resource path must stay within the current Studio resource directory.");
-	}
-
 	const stat = statSync(candidateReal);
 	if (!stat.isFile()) throw new Error("Local resource path does not refer to a file.");
+
+	const kind = getStudioLocalPreviewResourceKind(extension, candidateReal);
+	const matchingGrant = resourceGrants?.findGrant(candidateReal);
+	let effectiveDirectory: string;
+	if (resourceGrants) {
+		if (!matchingGrant) throw new StudioResourceGrantRequiredError(candidateReal, kind);
+		effectiveDirectory = matchingGrant.kind === "directory" ? matchingGrant.path : dirname(candidateReal);
+	} else {
+		const boundaryReal = realpathSync(context.boundaryDir);
+		if (!isPathInsideOrEqualDirectory(candidateReal, boundaryReal)) {
+			throw new Error("Local resource path must stay within the current Studio resource directory.");
+		}
+		effectiveDirectory = boundaryReal;
+	}
+	const relativePath = relative(effectiveDirectory, candidateReal);
+	const useRelativeReference = isPathInsideOrEqualDirectory(candidateReal, effectiveDirectory);
 	return {
 		filePath: candidateReal,
-		label: rel && rel !== "" ? rel : basename(candidateReal),
+		referencePath: useRelativeReference ? (relativePath || basename(candidateReal)) : candidateReal,
+		label: useRelativeReference ? (relativePath || basename(candidateReal)) : basename(candidateReal),
 		extension,
-		kind: getStudioLocalPreviewResourceKind(extension, candidateReal),
+		kind,
 		page: parseStudioLocalPreviewPage(rawPath),
-		resourceDir: boundaryReal,
+		resourceDir: effectiveDirectory,
 	};
 }
 
+function getStudioFileBrowserGrantLocations(resourceGrants: StudioResourceGrantRegistry): {
+	locations: StudioFileBrowserLocation[];
+	exactFiles: StudioFileBrowserEntry[];
+} {
+	const grants = resourceGrants.snapshot();
+	const directoryPaths: string[] = [];
+	for (const grant of grants) {
+		if (grant.kind !== "directory") continue;
+		try {
+			const currentReal = realpathSync(grant.path);
+			if (currentReal === grant.path && statSync(currentReal).isDirectory()) directoryPaths.push(currentReal);
+		} catch {
+			// Missing or replaced directory grants are omitted rather than followed.
+		}
+	}
+	const locations = directoryPaths
+		.map((path) => ({ path, label: basename(path) || path }))
+		.sort((a, b) => a.path.localeCompare(b.path));
+	const exactFiles: StudioFileBrowserEntry[] = [];
+	for (const grant of grants) {
+		if (grant.kind !== "file") continue;
+		if (directoryPaths.some((directoryPath) => isPathInsideOrEqualDirectory(grant.path, directoryPath))) continue;
+		try {
+			const currentReal = realpathSync(grant.path);
+			if (currentReal !== grant.path) continue;
+			const stat = statSync(currentReal);
+			if (!stat.isFile()) continue;
+			const name = basename(currentReal);
+			const extension = extname(currentReal).toLowerCase();
+			exactFiles.push({
+				name,
+				path: currentReal,
+				type: "file",
+				extension,
+				kind: getStudioLocalPreviewResourceKind(extension, currentReal),
+				size: stat.size,
+				mtimeMs: stat.mtimeMs,
+				hidden: name.startsWith("."),
+			});
+		} catch {
+			// Missing exact-file grants remain bounded but are omitted from the Files view.
+		}
+	}
+	exactFiles.sort((a, b) => compareStudioFileBrowserEntries(a, b, "name"));
+	return { locations, exactFiles };
+}
+
 function resolveStudioFileBrowserDirectory(
 	dirPath: string | undefined,
+	rootPath: string | undefined,
 	sourcePath: string | undefined,
 	resourceDir: string | undefined,
 	fallbackCwd: string,
+	resourceGrants: StudioResourceGrantRegistry,
 ): { rootDir: string; currentDir: string; relativeDir: string; parentDir: string | null } {
 	const context = resolveStudioPreviewResourceContext(sourcePath, resourceDir, fallbackCwd);
-	const rootReal = realpathSync(context.boundaryDir);
+	const rawRoot = typeof rootPath === "string" ? rootPath.trim() : "";
+	const expandedRoot = recoverLikelyDroppedLeadingSlashPath(expandHome(rawRoot || context.boundaryDir));
+	const requestedRoot = isAbsolute(expandedRoot) ? expandedRoot : resolve(fallbackCwd, expandedRoot);
+	const requestedRootReal = realpathSync(requestedRoot);
+	if (!statSync(requestedRootReal).isDirectory()) throw new Error("File browser root does not refer to a directory.");
+	const matchingRootGrant = resourceGrants.findGrant(requestedRootReal, { cwd: fallbackCwd });
+	if (!matchingRootGrant || matchingRootGrant.kind !== "directory") {
+		throw new StudioDirectoryGrantRequiredError(requestedRootReal);
+	}
+	const rootReal = matchingRootGrant.path;
 	const rawDir = typeof dirPath === "string" ? dirPath.trim() : "";
-	const baseDir = context.baseDir;
+	const expandedDir = recoverLikelyDroppedLeadingSlashPath(expandHome(rawDir));
 	const requested = rawDir
-		? (isAbsolute(recoverLikelyDroppedLeadingSlashPath(expandHome(rawDir)))
-			? recoverLikelyDroppedLeadingSlashPath(expandHome(rawDir))
-			: resolve(baseDir, recoverLikelyDroppedLeadingSlashPath(expandHome(rawDir))))
-		: baseDir;
+		? (isAbsolute(expandedDir) ? expandedDir : resolve(rootReal, expandedDir))
+		: rootReal;
 	const currentReal = realpathSync(requested);
 	const currentStat = statSync(currentReal);
 	if (!currentStat.isDirectory()) throw new Error("File browser path does not refer to a directory.");
 	if (!isPathInsideOrEqualDirectory(currentReal, rootReal)) {
-		throw new Error("File browser path must stay within the current Studio resource directory.");
+		throw new Error("File browser path must stay within an allowed Studio folder.");
 	}
 	const parent = dirname(currentReal);
 	const parentDir = parent !== currentReal && isPathInsideOrEqualDirectory(parent, rootReal) ? parent : null;
@@ -3294,12 +3425,14 @@ function resolveStudioFileBrowserDirectory(
 
 function listStudioFileBrowserDirectory(
 	dirPath: string | undefined,
+	rootPath: string | undefined,
 	sourcePath: string | undefined,
 	resourceDir: string | undefined,
 	fallbackCwd: string,
+	resourceGrants: StudioResourceGrantRegistry,
 	sortMode?: string | null,
-): { rootDir: string; currentDir: string; relativeDir: string; parentDir: string | null; entries: StudioFileBrowserEntry[]; omitted: number; omittedIgnored: number; sort: StudioFileBrowserSortMode } {
-	const context = resolveStudioFileBrowserDirectory(dirPath, sourcePath, resourceDir, fallbackCwd);
+): { rootDir: string; currentDir: string; relativeDir: string; parentDir: string | null; entries: StudioFileBrowserEntry[]; exactFiles: StudioFileBrowserEntry[]; locations: StudioFileBrowserLocation[]; omitted: number; omittedIgnored: number; sort: StudioFileBrowserSortMode } {
+	const context = resolveStudioFileBrowserDirectory(dirPath, rootPath, sourcePath, resourceDir, fallbackCwd, resourceGrants);
 	const sort = normalizeStudioFileBrowserSortMode(sortMode);
 	const entries: StudioFileBrowserEntry[] = [];
 	let omitted = 0;
@@ -3342,7 +3475,7 @@ function listStudioFileBrowserDirectory(
 	entries.sort((a, b) => compareStudioFileBrowserEntries(a, b, sort));
 	const limitedEntries = entries.slice(0, STUDIO_FILE_BROWSER_MAX_ENTRIES);
 	omitted += Math.max(0, entries.length - limitedEntries.length);
-	return { ...context, entries: limitedEntries, omitted, omittedIgnored, sort };
+	return { ...context, ...getStudioFileBrowserGrantLocations(resourceGrants), entries: limitedEntries, omitted, omittedIgnored, sort };
 }
 
 function resolveStudioHtmlPreviewResourcePath(
@@ -3350,27 +3483,32 @@ function resolveStudioHtmlPreviewResourcePath(
 	sourcePath: string | undefined,
 	resourceDir: string | undefined,
 	fallbackCwd: string,
+	resourceGrants?: StudioResourceGrantRegistry,
 ): { filePath: string; mimeType: string } {
 	const rawPath = typeof resourcePath === "string" ? resourcePath.trim() : "";
 	if (!rawPath) throw new Error("Missing HTML preview resource path.");
 	if (/\0/.test(rawPath)) throw new Error("Invalid HTML preview resource path.");
-	if (/^[a-z][a-z0-9+.-]*:/i.test(rawPath) && !/^[a-z]:[\\/]/i.test(rawPath)) {
+	if (/^[a-z][a-z0-9+.-]*:/i.test(rawPath) && !/^file:/i.test(rawPath) && !/^[a-z]:[\\/]/i.test(rawPath)) {
 		throw new Error("Only local HTML preview resources are supported.");
 	}
 
 	const context = resolveStudioPreviewResourceContext(sourcePath, resourceDir, fallbackCwd);
-	const cleanedPath = decodeStudioHtmlPreviewResourcePath(stripStudioHtmlPreviewResourceUrlSuffix(rawPath));
+	const cleanedPath = decodeStudioLocalPreviewResourceReference(rawPath);
 	const expandedPath = recoverLikelyDroppedLeadingSlashPath(expandHome(cleanedPath));
 	const candidate = isAbsolute(expandedPath) ? expandedPath : resolve(context.baseDir, expandedPath);
 	const ext = extname(candidate).toLowerCase();
-	const mimeType = STUDIO_HTML_PREVIEW_IMAGE_MIME_BY_EXT.get(ext);
-	if (!mimeType) throw new Error("Only local PNG, JPEG, GIF, and WebP images can be embedded in HTML previews.");
+	const mimeType = STUDIO_HTML_PREVIEW_MEDIA_MIME_BY_EXT.get(ext);
+	if (!mimeType) throw new Error("Only local PNG, JPEG, GIF, WebP, and PDF media can be embedded in Studio previews.");
 
-	const boundaryReal = realpathSync(context.boundaryDir);
 	const candidateReal = realpathSync(candidate);
-	const rel = relative(boundaryReal, candidateReal);
-	if (rel.startsWith("..") || isAbsolute(rel)) {
-		throw new Error("HTML preview resource path must stay within the current Studio resource directory.");
+	const kind: StudioLocalPreviewResourceKind = ext === ".pdf" ? "pdf" : "image";
+	if (resourceGrants) {
+		if (!resourceGrants.allows(candidateReal)) throw new StudioResourceGrantRequiredError(candidateReal, kind);
+	} else {
+		const boundaryReal = realpathSync(context.boundaryDir);
+		if (!isPathInsideOrEqualDirectory(candidateReal, boundaryReal)) {
+			throw new Error("HTML preview resource path must stay within the current Studio resource directory.");
+		}
 	}
 
 	const stat = statSync(candidateReal);
@@ -3381,6 +3519,39 @@ function resolveStudioHtmlPreviewResourcePath(
 	return { filePath: candidateReal, mimeType };
 }
 
+function resolveStudioAuthorizedPreviewRenderContext(
+	sourcePath: string | undefined,
+	resourceDir: string | undefined,
+	fallbackCwd: string,
+	resourceGrants: StudioResourceGrantRegistry,
+): { resourcePath?: string; sourcePath?: string } {
+	const context = resolveStudioPreviewResourceContext(sourcePath, resourceDir, fallbackCwd);
+	let resourcePath: string;
+	try {
+		resourcePath = realpathSync(context.baseDir);
+		if (!statSync(resourcePath).isDirectory()) return {};
+	} catch {
+		return {};
+	}
+	const directoryGrant = resourceGrants.findGrant(resourcePath, { cwd: fallbackCwd });
+	if (!directoryGrant || directoryGrant.kind !== "directory") return {};
+
+	const rawSource = typeof sourcePath === "string" ? sourcePath.trim() : "";
+	if (!rawSource) return { resourcePath };
+	try {
+		const expandedSource = recoverLikelyDroppedLeadingSlashPath(expandHome(rawSource));
+		const requestedSource = isAbsolute(expandedSource) ? expandedSource : resolve(fallbackCwd, expandedSource);
+		const canonicalSource = realpathSync(requestedSource);
+		const sourceGrant = resourceGrants.findGrant(dirname(canonicalSource), { cwd: fallbackCwd });
+		if (statSync(canonicalSource).isFile() && sourceGrant?.kind === "directory") {
+			return { resourcePath, sourcePath: canonicalSource };
+		}
+	} catch {
+		// The submitted Markdown can still render without file-adjacent metadata.
+	}
+	return { resourcePath };
+}
+
 function resolveStudioPandocWorkingDir(baseDir: string | undefined): string | undefined {
 	const normalized = typeof baseDir === "string" ? baseDir.trim() : "";
 	if (!normalized) return undefined;
@@ -5191,11 +5362,34 @@ function hasStudioYamlHeaderIncludes(markdown: string): boolean {
 	return /^\s*header-includes\s*:/im.test(split.frontMatter);
 }
 
+function encodeStudioLocalFileUrlForPandoc(resourceUrl: string): string {
+	try {
+		const url = new URL(resourceUrl);
+		if (url.protocol !== "file:" || (url.hostname && url.hostname !== "localhost")) return resourceUrl;
+		const suffix = `${url.search}${url.hash}`;
+		url.search = "";
+		url.hash = "";
+		const localPath = fileURLToPath(url);
+		return encodeURI(localPath).replace(/\?/g, "%3F").replace(/#/g, "%23") + suffix;
+	} catch {
+		return resourceUrl;
+	}
+}
+
+function normalizeStudioMarkdownFileUrlDestinationsForPandoc(markdown: string): string {
+	return transformStudioMarkdownOutsideFences(markdown, (segment: string) => (
+		segment.replace(/(\]\(\s*<?)(file:\/\/(?:localhost)?\/[^<>\s)]+)/gi, (_match, prefix: string, resourceUrl: string) => (
+			`${prefix}${encodeStudioLocalFileUrlForPandoc(resourceUrl)}`
+		))
+	));
+}
+
 function prepareStudioMarkdownForPandoc(markdown: string, options?: { preserveLiteralLatexCommands?: boolean }): string {
 	const shouldPreserveLiteralLatexCommands = options?.preserveLiteralLatexCommands !== false;
 	return mapStudioMarkdownBodyPreservingYamlFrontMatter(markdown, (body) => {
 		const normalizedFences = normalizeStudioMarkdownSmartFences(body);
-		const normalizedMath = normalizeMathDelimiters(normalizedFences);
+		const normalizedFileUrls = normalizeStudioMarkdownFileUrlDestinationsForPandoc(normalizedFences);
+		const normalizedMath = normalizeMathDelimiters(normalizedFileUrls);
 		const latexReady = shouldPreserveLiteralLatexCommands
 			? preserveLiteralLatexCommandsInMarkdown(normalizedMath)
 			: normalizedMath;
@@ -6413,7 +6607,13 @@ function preprocessStudioLatexFootnotemarksForPreview(latex: string): string {
 	});
 }
 
-async function renderStudioMarkdownWithPandoc(markdown: string, isLatex?: boolean, resourcePath?: string, sourcePath?: string): Promise<string> {
+async function renderStudioMarkdownWithPandoc(
+	markdown: string,
+	isLatex?: boolean,
+	resourcePath?: string,
+	sourcePath?: string,
+	options?: { embedResources?: boolean },
+): Promise<string> {
 	const pandocCommand = process.env.PANDOC_PATH?.trim() || "pandoc";
 	const pandocWorkingDir = resolveStudioPandocWorkingDir(resourcePath)
 		?? resolveStudioPandocWorkingDir(sourcePath ? dirname(sourcePath) : undefined);
@@ -6451,7 +6651,9 @@ async function renderStudioMarkdownWithPandoc(markdown: string, isLatex?: boolea
 		await mkdir(htmlTemplateDir, { recursive: true });
 		const htmlTemplatePath = join(htmlTemplateDir, "template.html");
 		await writeFile(htmlTemplatePath, STUDIO_PANDOC_HTML_FRAGMENT_TEMPLATE, "utf-8");
-		if (resourcePath) args.push(await resolveStudioPandocHtmlResourceFlag(pandocCommand));
+		if (resourcePath && options?.embedResources !== false) {
+			args.push(await resolveStudioPandocHtmlResourceFlag(pandocCommand));
+		}
 		args.push("--standalone", `--template=${htmlTemplatePath}`);
 	}
 	const normalizedMarkdown = isLatex
@@ -7599,6 +7801,29 @@ function respondStudioPendingError(res: ServerResponse, status: number, text: st
 	res.end(text);
 }
 
+function respondStudioResourceGrantRequiredJson(res: ServerResponse, error: StudioResourceGrantRequiredError): void {
+	respondJson(res, 403, {
+		ok: false,
+		code: error.code,
+		error: error.message,
+		path: error.filePath,
+		directoryPath: error.directoryPath,
+		label: basename(error.filePath),
+		resourceKind: error.resourceKind,
+	});
+}
+
+function respondStudioDirectoryGrantRequiredJson(res: ServerResponse, error: StudioDirectoryGrantRequiredError): void {
+	respondJson(res, 403, {
+		ok: false,
+		code: error.code,
+		error: error.message,
+		path: error.directoryPath,
+		directoryPath: error.directoryPath,
+		label: basename(error.directoryPath) || error.directoryPath,
+	});
+}
+
 function respondPdfFile(req: IncomingMessage, res: ServerResponse, filePath: string): void {
 	const method = (req.method ?? "GET").toUpperCase();
 	if (method !== "GET" && method !== "HEAD") {
@@ -7661,7 +7886,7 @@ function sanitizeStudioPreviewBlockLine(value: string): string {
 
 function buildStudioLocalResourcePreviewDocument(resource: StudioLocalPreviewResource, options?: { watchPdf?: boolean }): InitialStudioDocument {
 	const label = basename(resource.filePath) || resource.label || "local preview";
-	const resourcePath = resource.label || basename(resource.filePath) || resource.filePath;
+	const resourcePath = resource.referencePath || resource.label || basename(resource.filePath) || resource.filePath;
 	const title = sanitizeStudioPreviewBlockLine(label);
 	let text = "";
 	if (resource.kind === "pdf") {
@@ -7720,7 +7945,14 @@ async function convertStudioOfficeDocumentToMarkdown(resource: StudioLocalPrevie
 	return { text: `${note}\n\n${body}\n`, label };
 }
 
-async function respondLocalPreviewLinkJson(req: IncomingMessage, res: ServerResponse, requestUrl: URL, resource: StudioLocalPreviewResource, serverState: StudioServerState): Promise<void> {
+async function respondLocalPreviewLinkJson(
+	req: IncomingMessage,
+	res: ServerResponse,
+	requestUrl: URL,
+	resource: StudioLocalPreviewResource,
+	serverState: StudioServerState,
+	resourceGrants?: StudioResourceGrantRegistry,
+): Promise<void> {
 	const method = (req.method ?? "GET").toUpperCase();
 	if (method !== "GET" && method !== "HEAD") {
 		res.setHeader("Allow", "GET, HEAD");
@@ -7770,6 +8002,7 @@ async function respondLocalPreviewLinkJson(req: IncomingMessage, res: ServerResp
 	let document: InitialStudioDocument;
 	let responseText = "";
 	let converted = false;
+	let documentResourceDir = resource.resourceDir;
 	if (resource.kind === "office") {
 		let conversion: { text: string; label: string };
 		try {
@@ -7793,12 +8026,18 @@ async function respondLocalPreviewLinkJson(req: IncomingMessage, res: ServerResp
 			return;
 		}
 		responseText = file.text;
+		try {
+			const documentGrant = resourceGrants?.grantDocument(file.resolvedPath, { source: "document" });
+			if (documentGrant?.path) documentResourceDir = documentGrant.path;
+		} catch {
+			// The exact-file grant remains usable if the bounded registry cannot add the document directory.
+		}
 		document = {
 			text: file.text,
 			label: resource.label || file.label,
 			source: "file",
 			path: file.resolvedPath,
-			resourceDir: resource.resourceDir,
+			resourceDir: documentResourceDir,
 		};
 	}
 	if (action === "document") {
@@ -7807,7 +8046,7 @@ async function respondLocalPreviewLinkJson(req: IncomingMessage, res: ServerResp
 			text: responseText,
 			label: document.label,
 			converted,
-			resourceDir: resource.resourceDir,
+			resourceDir: documentResourceDir,
 		});
 		return;
 	}
@@ -7816,6 +8055,7 @@ async function respondLocalPreviewLinkJson(req: IncomingMessage, res: ServerResp
 	respondJson(res, 200, {
 		...basePayload,
 		converted,
+		resourceDir: documentResourceDir,
 		relativeUrl: buildStudioRelativeUrl(serverState.token, "editor-only", document, docId, { skipWorkspaceRestore: true }),
 	});
 }
@@ -7906,7 +8146,61 @@ async function handleImportStudioFileCopyRequest(req: IncomingMessage, res: Serv
 	});
 }
 
-async function handleRevealLocalPreviewResourceRequest(req: IncomingMessage, res: ServerResponse, studioCwd: string): Promise<void> {
+async function handleStudioResourceGrantRequest(
+	req: IncomingMessage,
+	res: ServerResponse,
+	resourceGrants: StudioResourceGrantRegistry,
+	studioCwd: string,
+): Promise<void> {
+	const method = (req.method ?? "GET").toUpperCase();
+	if (method !== "POST") {
+		res.setHeader("Allow", "POST");
+		respondJson(res, 405, { ok: false, error: "Method not allowed. Use POST." });
+		return;
+	}
+
+	const rawBody = await readRequestBody(req, REQUEST_BODY_MAX_BYTES);
+	let payload: Record<string, unknown> = {};
+	try {
+		payload = rawBody ? JSON.parse(rawBody) : {};
+	} catch {
+		respondJson(res, 400, { ok: false, error: "Invalid JSON body." });
+		return;
+	}
+
+	const grantKind = payload.grantKind === "directory" ? "directory" : payload.grantKind === "file" ? "file" : "";
+	const path = typeof payload.path === "string" ? payload.path.trim() : "";
+	if (!grantKind || !path) {
+		respondJson(res, 400, { ok: false, error: "Choose an exact file or folder to allow." });
+		return;
+	}
+
+	try {
+		const grant = grantKind === "directory"
+			? resourceGrants.grantDirectory(path, { cwd: studioCwd, source: "explicit-directory" })
+			: resourceGrants.grantFile(path, { cwd: studioCwd, source: "explicit-file" });
+		respondJson(res, 200, {
+			ok: true,
+			grant,
+			resourceGrants: resourceGrants.snapshot(),
+			message: grantKind === "directory"
+				? `Allowed this folder for the current Studio session: ${grant.path}`
+				: `Allowed this file for the current Studio session: ${grant.path}`,
+		});
+	} catch (error) {
+		respondJson(res, 400, {
+			ok: false,
+			error: `Could not allow this ${grantKind}: ${error instanceof Error ? error.message : String(error)}`,
+		});
+	}
+}
+
+async function handleRevealLocalPreviewResourceRequest(
+	req: IncomingMessage,
+	res: ServerResponse,
+	studioCwd: string,
+	resourceGrants?: StudioResourceGrantRegistry,
+): Promise<void> {
 	const method = (req.method ?? "GET").toUpperCase();
 	if (method !== "POST") {
 		res.setHeader("Allow", "POST");
@@ -7929,6 +8223,7 @@ async function handleRevealLocalPreviewResourceRequest(req: IncomingMessage, res
 			typeof payload.sourcePath === "string" ? payload.sourcePath : undefined,
 			typeof payload.resourceDir === "string" ? payload.resourceDir : undefined,
 			studioCwd,
+			resourceGrants,
 		);
 		const result = revealStudioLocalFile(resource.filePath);
 		if (!result.ok) {
@@ -7937,11 +8232,20 @@ async function handleRevealLocalPreviewResourceRequest(req: IncomingMessage, res
 		}
 		respondJson(res, 200, { ok: true, message: result.message, path: resource.filePath, label: resource.label });
 	} catch (error) {
+		if (error instanceof StudioResourceGrantRequiredError) {
+			respondStudioResourceGrantRequiredJson(res, error);
+			return;
+		}
 		respondJson(res, 404, { ok: false, error: `Local resource unavailable: ${error instanceof Error ? error.message : String(error)}` });
 	}
 }
 
-async function handleOpenLocalPreviewResourceRequest(req: IncomingMessage, res: ServerResponse, studioCwd: string): Promise<void> {
+async function handleOpenLocalPreviewResourceRequest(
+	req: IncomingMessage,
+	res: ServerResponse,
+	studioCwd: string,
+	resourceGrants?: StudioResourceGrantRegistry,
+): Promise<void> {
 	const method = (req.method ?? "GET").toUpperCase();
 	if (method !== "POST") {
 		res.setHeader("Allow", "POST");
@@ -7968,6 +8272,7 @@ async function handleOpenLocalPreviewResourceRequest(req: IncomingMessage, res:
 			typeof payload.sourcePath === "string" ? payload.sourcePath : undefined,
 			typeof payload.resourceDir === "string" ? payload.resourceDir : undefined,
 			studioCwd,
+			resourceGrants,
 		);
 		if (resource.kind !== "pdf") {
 			respondJson(res, 400, { ok: false, error: "Only local PDF previews can be opened in the system PDF viewer." });
@@ -7981,6 +8286,10 @@ async function handleOpenLocalPreviewResourceRequest(req: IncomingMessage, res:
 			label: resource.label,
 		});
 	} catch (error) {
+		if (error instanceof StudioResourceGrantRequiredError) {
+			respondStudioResourceGrantRequiredJson(res, error);
+			return;
+		}
 		respondJson(res, 404, { ok: false, error: `Local PDF unavailable: ${error instanceof Error ? error.message : String(error)}` });
 	}
 }
@@ -8006,7 +8315,12 @@ function openPathInDefaultViewer(path: string): Promise<void> {
 	});
 }
 
-async function handleOpenStudioFileBrowserDirectoryRequest(req: IncomingMessage, res: ServerResponse, studioCwd: string): Promise<void> {
+async function handleOpenStudioFileBrowserDirectoryRequest(
+	req: IncomingMessage,
+	res: ServerResponse,
+	studioCwd: string,
+	resourceGrants: StudioResourceGrantRegistry,
+): Promise<void> {
 	const method = (req.method ?? "GET").toUpperCase();
 	if (method !== "POST") {
 		res.setHeader("Allow", "POST");
@@ -8030,13 +8344,25 @@ async function handleOpenStudioFileBrowserDirectoryRequest(req: IncomingMessage,
 	try {
 		const directory = resolveStudioFileBrowserDirectory(
 			typeof payload.dir === "string" ? payload.dir : undefined,
+			typeof payload.root === "string" ? payload.root : undefined,
 			typeof payload.sourcePath === "string" ? payload.sourcePath : undefined,
 			typeof payload.resourceDir === "string" ? payload.resourceDir : undefined,
 			studioCwd,
+			resourceGrants,
 		);
 		await openPathInDefaultViewer(directory.currentDir);
 		respondJson(res, 200, { ok: true, message: "Opened folder in file manager.", path: directory.currentDir, rootDir: directory.rootDir });
 	} catch (error) {
+		if (error instanceof StudioDirectoryGrantRequiredError) {
+			respondJson(res, 403, {
+				ok: false,
+				code: error.code,
+				error: error.message,
+				path: error.directoryPath,
+				directoryPath: error.directoryPath,
+			});
+			return;
+		}
 		respondJson(res, 404, { ok: false, error: `Could not open file-browser folder: ${error instanceof Error ? error.message : String(error)}` });
 	}
 }
@@ -8504,10 +8830,11 @@ async function searchStudioSideQuestionLocalContext(
 	const query = String(queryInput || "").trim();
 	if (!query) throw new Error("Local context search query is empty.");
 	if (query.length > 500) throw new Error("Local context search query is too long.");
+	const stableRoot = assertStudioSideQuestionRootStable(contextRoot);
 	const target = options.path
-		? resolveStudioSideQuestionPath(contextRoot, options.path, { directory: true }).path
-		: contextRoot;
-	const targetRelative = relative(contextRoot, target) || ".";
+		? resolveStudioSideQuestionPath(stableRoot, options.path, { directory: true }).path
+		: stableRoot;
+	const targetRelative = relative(stableRoot, target) || ".";
 	const maxResults = Math.max(1, Math.min(200, Math.floor(Number(options.maxResults) || 60)));
 	const args = [
 		"--fixed-strings",
@@ -8527,7 +8854,7 @@ async function searchStudioSideQuestionLocalContext(
 	args.push("--", query, targetRelative);
 	try {
 		const result = await runStudioSubprocess("rg", args, {
-			cwd: contextRoot,
+			cwd: stableRoot,
 			signal: options.signal,
 			timeoutMs: 20_000,
 			stdoutMaxBytes: 250_000,
@@ -8541,11 +8868,11 @@ async function searchStudioSideQuestionLocalContext(
 			if (!match) return [];
 			return [{ path: match[1].split("\\").join("/"), line: Number(match[2]), text: match[3].trim().slice(0, 1_000) }];
 		}).slice(0, maxResults);
-		return { root: contextRoot, query, results: matches, truncated: result.stdoutTruncated || matches.length >= maxResults };
+		return { root: stableRoot, query, results: matches, truncated: result.stdoutTruncated || matches.length >= maxResults };
 	} catch (error) {
 		if (options.signal?.aborted) throw new Error("Local context search was cancelled.");
 		if (!(error instanceof Error) || !error.message.includes("__PI_STUDIO_RG_NOT_FOUND__")) throw error;
-		return searchStudioSideQuestionContext(contextRoot, query, {
+		return searchStudioSideQuestionContext(stableRoot, query, {
 			path: targetRelative,
 			caseSensitive: options.caseSensitive,
 			maxResults,
@@ -8647,7 +8974,12 @@ function formatStudioSideQuestionGitSnapshotResult(
 	};
 }
 
-function createStudioSideQuestionTools(contextRoot: string, webEnabled: boolean, gitSnapshot: StudioSideQuestionGitSnapshot | null = null) {
+function createStudioSideQuestionTools(
+	contextRoot: string,
+	webEnabled: boolean,
+	gitSnapshot: StudioSideQuestionGitSnapshot | null = null,
+	assertContextRoot?: () => string,
+) {
 	const mapTool = defineTool({
 		name: "studio_context_map",
 		label: "Map local context",
@@ -8658,6 +8990,7 @@ function createStudioSideQuestionTools(contextRoot: string, webEnabled: boolean,
 		}),
 		async execute(_toolCallId, params, signal) {
 			if (signal?.aborted) throw new Error("Context map was cancelled.");
+			if (assertContextRoot) assertContextRoot();
 			const target = params.path
 				? resolveStudioSideQuestionPath(contextRoot, params.path, { directory: true }).path
 				: contextRoot;
@@ -8680,6 +9013,7 @@ function createStudioSideQuestionTools(contextRoot: string, webEnabled: boolean,
 		}),
 		async execute(_toolCallId, params, signal) {
 			if (signal?.aborted) throw new Error("Context read was cancelled.");
+			if (assertContextRoot) assertContextRoot();
 			const result = readStudioSideQuestionContextText(contextRoot, params.path, { offset: params.offset, limit: params.limit, maxChars: STUDIO_SIDE_CONTEXT_MAX_OUTPUT_CHARS });
 			const extractableResult = result as { path: string; relativePath: string; extension?: string };
 			const content: { text: string; startLine: number; endLine: number; totalLines: number; truncated: boolean } = result.requiresExtraction
@@ -8703,6 +9037,7 @@ function createStudioSideQuestionTools(contextRoot: string, webEnabled: boolean,
 			maxResults: Type.Optional(Type.Integer({ minimum: 1, maximum: 200 })),
 		}),
 		async execute(_toolCallId, params, signal) {
+			if (assertContextRoot) assertContextRoot();
 			const result = await searchStudioSideQuestionLocalContext(contextRoot, params.query, {
 				path: params.path,
 				caseSensitive: params.caseSensitive,
@@ -11671,7 +12006,7 @@ ${cssVarsBlock}
     <section id="rightPane">
       <div id="rightSectionHeader" class="section-header">
         <div class="section-header-main">
-          <select id="rightViewSelect" aria-label="Response view mode" title="Right pane view mode. F7 cycles when the right pane is active; Cmd/Ctrl+Alt+1–8 switches directly between all right-pane views. Cmd/Ctrl+Alt+P/E/W/Q keep their mnemonic Preview/Editor Preview/Working/Side questions shortcuts.">
+          <select id="rightViewSelect" aria-label="Response view mode" title="Right pane view mode. F7 cycles when the right pane is active; Cmd/Ctrl+Alt+1–8 switches directly between all right-pane views. Cmd/Ctrl+Alt+P/E/W/F/Q keep mnemonic shortcuts for Preview, Editor Preview, Working, Files, and Side questions.">
             <option value="markdown">Response (Raw)</option>
             <option value="preview" selected>Response (Preview)</option>
             <option value="editor-preview">Editor (Preview)</option>
@@ -11780,6 +12115,7 @@ ${cssVarsBlock}
             <div><dt>Cmd/Ctrl+Alt+P</dt><dd>Switch the right pane directly to Response Preview; in editor-only views, Editor Preview</dd></div>
             <div><dt>Cmd/Ctrl+Alt+E</dt><dd>Switch the right pane directly to Editor Preview</dd></div>
             <div><dt>Cmd/Ctrl+Alt+W</dt><dd>Switch the right pane directly to Working</dd></div>
+            <div><dt>Cmd/Ctrl+Alt+F</dt><dd>Switch the right pane directly to Files</dd></div>
             <div><dt>Cmd/Ctrl+Alt+Q</dt><dd>Switch the right pane directly to Side questions</dd></div>
             <div><dt>F8</dt><dd>Focus editor text</dd></div>
             <div><dt>Shift+F8</dt><dd>Focus right-pane content</dd></div>
@@ -11876,6 +12212,7 @@ ${cssVarsBlock}
 export default function (pi: ExtensionAPI) {
 	let serverState: StudioServerState | null = null;
 	const studioWorkspaceStateStore = createStudioWorkspaceStateStore();
+	const studioResourceGrantRegistry = createStudioResourceGrantRegistry();
 	let activeRequest: ActiveStudioRequest | null = null;
 	let studioDirectRunChain: StudioDirectRunChain | null = null;
 	let queuedStudioDirectRequests: QueuedStudioDirectRequest[] = [];
@@ -11936,6 +12273,23 @@ export default function (pi: ExtensionAPI) {
 		actionRequestId: null,
 	};
 
+	const recordStudioDocumentResourceGrants = (document: InitialStudioDocument, cwd = studioCwd) => {
+		if (document.path) {
+			try {
+				studioResourceGrantRegistry.grantDocument(document.path, { cwd, source: "document" });
+			} catch {
+				// A failed grant must not broaden access or prevent an otherwise valid launch.
+			}
+		}
+		if (document.resourceDir) {
+			try {
+				studioResourceGrantRegistry.grantDirectory(document.resourceDir, { cwd, source: "workspace" });
+			} catch {
+				// A failed workspace grant must not broaden access or prevent an otherwise valid launch.
+			}
+		}
+	};
+
 	const selectStudioReplSessionForTool = (params: { sessionName?: string; target?: string }): { session: StudioReplSessionInfo | null; error?: string; sessions: StudioReplSessionInfo[] } => {
 		const state = listStudioReplSessions();
 		const sessions = state.sessions;
@@ -13604,7 +13958,7 @@ export default function (pi: ExtensionAPI) {
 		await closeStudioSideQuestionRuntime(runtime);
 	};
 
-	const resolveStudioSideQuestionContextRoot = (context: StudioSideQuestionContextInput): string => {
+	const resolveStudioSideQuestionContextRoot = (context: StudioSideQuestionContextRootInput): string => {
 		if (context.gatherScope === "none") return "";
 		const sourcePath = resolveStudioQuizContextPath(context.sourcePath, studioCwd);
 		const resourceDir = resolveStudioQuizContextPath(context.resourceDir, studioCwd);
@@ -13627,6 +13981,51 @@ export default function (pi: ExtensionAPI) {
 		return resolveStudioSideQuestionRoot(root, studioCwd);
 	};
 
+	const assertStudioSideQuestionContextRootAuthorized = (contextRoot: string): string => {
+		if (!contextRoot) return "";
+		const stableRoot = assertStudioSideQuestionRootStable(contextRoot);
+		const grant = studioResourceGrantRegistry.findGrant(stableRoot, { cwd: studioCwd });
+		if (!grant || grant.kind !== "directory") throw new StudioDirectoryGrantRequiredError(stableRoot);
+		return stableRoot;
+	};
+
+	const resolveAuthorizedStudioSideQuestionContextRoot = (context: StudioSideQuestionContextRootInput): string => (
+		assertStudioSideQuestionContextRootAuthorized(resolveStudioSideQuestionContextRoot(context))
+	);
+
+	const handleStudioSideQuestionContextRootRequest = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+		const method = (req.method ?? "GET").toUpperCase();
+		if (method !== "POST") {
+			res.setHeader("Allow", "POST");
+			respondJson(res, 405, { ok: false, error: "Method not allowed. Use POST." });
+			return;
+		}
+		const rawBody = await readRequestBody(req, REQUEST_BODY_MAX_BYTES);
+		let payload: Record<string, unknown> = {};
+		try {
+			payload = rawBody ? JSON.parse(rawBody) as Record<string, unknown> : {};
+		} catch {
+			respondJson(res, 400, { ok: false, error: "Invalid JSON body." });
+			return;
+		}
+		const context: StudioSideQuestionContextRootInput = {
+			gatherScope: normalizeStudioSideQuestionGatherScope(payload.gatherScope) as StudioSideQuestionGatherScope,
+			sourcePath: typeof payload.sourcePath === "string" ? payload.sourcePath.slice(0, 16_384) : undefined,
+			resourceDir: typeof payload.resourceDir === "string" ? payload.resourceDir.slice(0, 16_384) : undefined,
+			contextPath: typeof payload.contextPath === "string" ? payload.contextPath.slice(0, 16_384) : undefined,
+		};
+		try {
+			const contextRoot = resolveAuthorizedStudioSideQuestionContextRoot(context);
+			respondJson(res, 200, { ok: true, contextRoot, authorized: Boolean(contextRoot) });
+		} catch (error) {
+			if (error instanceof StudioDirectoryGrantRequiredError) {
+				respondStudioDirectoryGrantRequiredJson(res, error);
+				return;
+			}
+			respondJson(res, 400, { ok: false, error: `Side-question context unavailable: ${error instanceof Error ? error.message : String(error)}` });
+		}
+	};
+
 	const describeStudioSideQuestionActivity = (toolName: string, args: unknown): string => {
 		const value = args && typeof args === "object" ? args as Record<string, unknown> : {};
 		if (toolName === "studio_context_read") return `Reading ${String(value.path || "local context")}`;
@@ -13729,19 +14128,20 @@ export default function (pi: ExtensionAPI) {
 	const createStudioSideQuestionRuntime = async (context: StudioSideQuestionContextInput): Promise<StudioSideQuestionRuntime> => {
 		const ctx = lastCommandCtx;
 		if (!ctx) throw new Error("No active Studio command context is available. Re-open Studio and try again.");
-		const model = latestModelRequestCtx?.model ?? ctx.model;
-		if (!model) throw new Error("No active Pi model is available for side questions.");
-		await resolveStudioModelRequestAuth({ model, modelRegistry: ctx.modelRegistry }, model);
-		const contextRoot = resolveStudioSideQuestionContextRoot(context);
+		const contextRoot = resolveAuthorizedStudioSideQuestionContextRoot(context);
 		if (context.gitContext && context.gatherScope !== "repo") {
 			throw new Error("Git context requires Related files to be set to Repository.");
 		}
+		const model = latestModelRequestCtx?.model ?? ctx.model;
+		if (!model) throw new Error("No active Pi model is available for side questions.");
+		await resolveStudioModelRequestAuth({ model, modelRegistry: ctx.modelRegistry }, model);
 		const gitSnapshot = context.gitContext
 			? await captureStudioSideQuestionGitSnapshot(contextRoot, { runGit: runStudioSideQuestionGitCommand }) as StudioSideQuestionGitSnapshot
 			: null;
 		const webAvailable = Boolean(String(process.env.BRAVE_API_KEY || "").trim());
 		const webEnabled = context.webSearch && webAvailable;
-		const { tools, toolNames } = createStudioSideQuestionTools(contextRoot || studioCwd, webEnabled, gitSnapshot);
+		const assertContextRoot = contextRoot ? () => assertStudioSideQuestionContextRootAuthorized(contextRoot) : undefined;
+		const { tools, toolNames } = createStudioSideQuestionTools(contextRoot || studioCwd, webEnabled, gitSnapshot, assertContextRoot);
 		const localActiveToolNames = context.gatherScope === "none" ? (webEnabled ? ["studio_web_search"] : []) : toolNames;
 		const toolSelection = selectStudioSideQuestionTools(getStudioSideQuestionToolCatalog(), context.toolIds);
 		if (toolSelection.missing.length > 0) {
@@ -13924,6 +14324,7 @@ export default function (pi: ExtensionAPI) {
 		sendStudioSideQuestionState();
 		try {
 			const context = msg.context;
+			if (runtime.contextRoot) assertStudioSideQuestionContextRootAuthorized(runtime.contextRoot);
 			let prompt: string;
 			if (isFollowUp) {
 				prompt = buildStudioSideQuestionFollowUpPrompt(msg.question);
@@ -14040,6 +14441,7 @@ export default function (pi: ExtensionAPI) {
 				responseHistory: studioResponseHistory,
 				traceState: studioTraceState,
 				initialDocument: initialStudioDocument,
+				resourceGrants: studioResourceGrantRegistry.snapshot(),
 				quartoPreview: getStudioQuartoPreviewSnapshot(),
 				sideQuestion: getStudioSideQuestionPublicState(),
 				webSearchAvailable: Boolean(String(process.env.BRAVE_API_KEY || "").trim()),
@@ -14996,6 +15398,7 @@ export default function (pi: ExtensionAPI) {
 				path: result.resolvedPath,
 				resourceDir: dirname(result.resolvedPath),
 			};
+			recordStudioDocumentResourceGrants(initialStudioDocument);
 
 			sendToClient(client, {
 				type: "saved",
@@ -15088,6 +15491,7 @@ export default function (pi: ExtensionAPI) {
 			};
 			if (!requestedPath || initialStudioDocument?.path === refreshed.resolvedPath) {
 				initialStudioDocument = refreshedDocument;
+				recordStudioDocumentResourceGrants(refreshedDocument);
 			}
 
 			sendToClient(client, {
@@ -15592,14 +15996,25 @@ export default function (pi: ExtensionAPI) {
 				parsedBody && typeof parsedBody === "object" && typeof (parsedBody as { editorLanguage?: unknown }).editorLanguage === "string"
 					? (parsedBody as { editorLanguage: string }).editorLanguage
 					: "";
-			const resourcePath = resolveStudioBaseDir(sourcePath || undefined, userResourceDir || undefined, studioCwd);
+			const authorizedContext = resolveStudioAuthorizedPreviewRenderContext(
+				sourcePath || undefined,
+				userResourceDir || undefined,
+				studioCwd,
+				studioResourceGrantRegistry,
+			);
 			const editorPreviewLanguage = normalizeStudioEditorLanguage(requestedEditorLanguage);
 			const isLatex = editorPreviewLanguage === "latex"
 				|| (
 					(editorPreviewLanguage === undefined || editorPreviewLanguage === "markdown")
 					&& isLikelyStandaloneLatexPreview(markdown)
 				);
-			const html = await renderStudioMarkdownWithPandoc(markdown, isLatex, resourcePath, sourcePath || undefined);
+			const html = await renderStudioMarkdownWithPandoc(
+				markdown,
+				isLatex,
+				authorizedContext.resourcePath,
+				authorizedContext.sourcePath,
+				{ embedResources: false },
+			);
 			respondJson(res, 200, { ok: true, html, renderer: "pandoc" });
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
@@ -16342,13 +16757,31 @@ export default function (pi: ExtensionAPI) {
 			try {
 				const listing = listStudioFileBrowserDirectory(
 					requestUrl.searchParams.get("dir") ?? undefined,
+					requestUrl.searchParams.get("root") ?? undefined,
 					requestUrl.searchParams.get("sourcePath") ?? undefined,
 					requestUrl.searchParams.get("resourceDir") ?? undefined,
 					studioCwd,
+					studioResourceGrantRegistry,
 					requestUrl.searchParams.get("sort") ?? undefined,
 				);
-				respondJson(res, 200, { ok: true, ...listing, entries: method === "HEAD" ? [] : listing.entries });
+				respondJson(res, 200, {
+					ok: true,
+					...listing,
+					entries: method === "HEAD" ? [] : listing.entries,
+					exactFiles: method === "HEAD" ? [] : listing.exactFiles,
+				});
 			} catch (error) {
+				if (error instanceof StudioDirectoryGrantRequiredError) {
+					respondJson(res, 403, {
+						ok: false,
+						code: error.code,
+						error: error.message,
+						path: error.directoryPath,
+						directoryPath: error.directoryPath,
+						...getStudioFileBrowserGrantLocations(studioResourceGrantRegistry),
+					});
+					return;
+				}
 				respondJson(res, 404, { ok: false, error: `File browser unavailable: ${error instanceof Error ? error.message : String(error)}` });
 			}
 			return;
@@ -16361,7 +16794,7 @@ export default function (pi: ExtensionAPI) {
 				return;
 			}
 
-			void handleOpenStudioFileBrowserDirectoryRequest(req, res, studioCwd).catch((error) => {
+			void handleOpenStudioFileBrowserDirectoryRequest(req, res, studioCwd, studioResourceGrantRegistry).catch((error) => {
 				respondJson(res, 500, { ok: false, error: `Open folder failed: ${error instanceof Error ? error.message : String(error)}` });
 			});
 			return;
@@ -16380,6 +16813,32 @@ export default function (pi: ExtensionAPI) {
 			return;
 		}
 
+		if (requestUrl.pathname === "/resource-grants") {
+			const token = requestUrl.searchParams.get("token") ?? "";
+			if (token !== serverState.token) {
+				respondJson(res, 403, { ok: false, error: "Invalid or expired studio token. Re-run /studio." });
+				return;
+			}
+
+			void handleStudioResourceGrantRequest(req, res, studioResourceGrantRegistry, studioCwd).catch((error) => {
+				respondJson(res, 500, { ok: false, error: `Resource grant failed: ${error instanceof Error ? error.message : String(error)}` });
+			});
+			return;
+		}
+
+		if (requestUrl.pathname === "/side-question-context-root") {
+			const token = requestUrl.searchParams.get("token") ?? "";
+			if (token !== serverState.token) {
+				respondJson(res, 403, { ok: false, error: "Invalid or expired studio token. Re-run /studio." });
+				return;
+			}
+
+			void handleStudioSideQuestionContextRootRequest(req, res).catch((error) => {
+				respondJson(res, 500, { ok: false, error: `Side-question context check failed: ${error instanceof Error ? error.message : String(error)}` });
+			});
+			return;
+		}
+
 		if (requestUrl.pathname === "/local-preview-link") {
 			const token = requestUrl.searchParams.get("token") ?? "";
 			if (token !== serverState.token) {
@@ -16394,9 +16853,14 @@ export default function (pi: ExtensionAPI) {
 						requestUrl.searchParams.get("sourcePath") ?? undefined,
 						requestUrl.searchParams.get("resourceDir") ?? undefined,
 						studioCwd,
+						studioResourceGrantRegistry,
 					);
-					await respondLocalPreviewLinkJson(req, res, requestUrl, resource, serverState);
+					await respondLocalPreviewLinkJson(req, res, requestUrl, resource, serverState, studioResourceGrantRegistry);
 				} catch (error) {
+					if (error instanceof StudioResourceGrantRequiredError) {
+						respondStudioResourceGrantRequiredJson(res, error);
+						return;
+					}
 					respondJson(res, 404, { ok: false, error: `Local resource unavailable: ${error instanceof Error ? error.message : String(error)}` });
 				}
 			})();
@@ -16410,7 +16874,7 @@ export default function (pi: ExtensionAPI) {
 				return;
 			}
 
-			void handleRevealLocalPreviewResourceRequest(req, res, studioCwd).catch((error) => {
+			void handleRevealLocalPreviewResourceRequest(req, res, studioCwd, studioResourceGrantRegistry).catch((error) => {
 				respondJson(res, 500, { ok: false, error: `Reveal failed: ${error instanceof Error ? error.message : String(error)}` });
 			});
 			return;
@@ -16423,7 +16887,7 @@ export default function (pi: ExtensionAPI) {
 				return;
 			}
 
-			void handleOpenLocalPreviewResourceRequest(req, res, studioCwd).catch((error) => {
+			void handleOpenLocalPreviewResourceRequest(req, res, studioCwd, studioResourceGrantRegistry).catch((error) => {
 				respondJson(res, 500, { ok: false, error: `Open in system viewer failed: ${error instanceof Error ? error.message : String(error)}` });
 			});
 			return;
@@ -16442,9 +16906,14 @@ export default function (pi: ExtensionAPI) {
 					requestUrl.searchParams.get("sourcePath") ?? undefined,
 					requestUrl.searchParams.get("resourceDir") ?? undefined,
 					studioCwd,
+					studioResourceGrantRegistry,
 				);
 				respondPdfFile(req, res, filePath);
 			} catch (error) {
+				if (error instanceof StudioResourceGrantRequiredError) {
+					respondStudioResourceGrantRequiredJson(res, error);
+					return;
+				}
 				respondText(res, 404, `PDF resource unavailable: ${error instanceof Error ? error.message : String(error)}`);
 			}
 			return;
@@ -16463,10 +16932,15 @@ export default function (pi: ExtensionAPI) {
 					requestUrl.searchParams.get("sourcePath") ?? undefined,
 					requestUrl.searchParams.get("resourceDir") ?? undefined,
 					studioCwd,
+					studioResourceGrantRegistry,
 				);
 				respondHtmlPreviewResourceJson(req, res, resource.filePath, resource.mimeType);
 			} catch (error) {
-				respondJson(res, 404, { ok: false, error: `HTML preview resource unavailable: ${error instanceof Error ? error.message : String(error)}` });
+				if (error instanceof StudioResourceGrantRequiredError) {
+					respondStudioResourceGrantRequiredJson(res, error);
+					return;
+				}
+				respondJson(res, 404, { ok: false, error: `Studio preview resource unavailable: ${error instanceof Error ? error.message : String(error)}` });
 			}
 			return;
 		}
@@ -16675,6 +17149,7 @@ export default function (pi: ExtensionAPI) {
 			state.server.close(() => resolve());
 		});
 		studioWorkspaceStateStore.clear();
+		studioResourceGrantRegistry.clear();
 	};
 
 	const hydrateLatestAssistant = (entries: SessionEntry[]) => {
@@ -17489,6 +17964,7 @@ export default function (pi: ExtensionAPI) {
 			ctx.ui.notify(`Failed to start Studio server${portText}: ${message}`, "error");
 			return;
 		}
+		recordStudioDocumentResourceGrants(selected, ctx.cwd);
 		const docId = selection.transient ? storeTransientStudioDocument(selected) : undefined;
 		const url = buildStudioUrl(state.port, state.token, launchMode, selected, docId, {
 			skipWorkspaceRestore: selection.skipWorkspaceRestore,
@@ -17983,6 +18459,7 @@ export default function (pi: ExtensionAPI) {
 				path: file.resolvedPath,
 			};
 			initialStudioDocument = nextDoc;
+			recordStudioDocumentResourceGrants(nextDoc, ctx.cwd);
 
 			broadcastState();
 			broadcastResponseHistory();