pi-mono-all 1.2.4 → 1.2.6

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # pi-mono-all
 
+## 1.2.6
+
+### Patch Changes
+
+- Bundle `pi-mono-sentinel@1.13.0` with smarter path-access prompts, session-scoped grants, and exact multi-file grants.
+
+## 1.2.5
+
+### Patch Changes
+
+- Bundle `pi-mono-linear@0.2.4` with automatic Markdown description image reading for `linear_get_issue` on vision-capable models.
+
 ## 1.2.4
 
 ### Patch Changes

package/node_modules/pi-mono-linear/CHANGELOG.md

@@ -1,5 +1,11 @@
 # pi-mono-linear
 
+## 0.2.4
+
+### Patch Changes
+
+- Added automatic Markdown description image reading to `linear_get_issue` for vision-capable models. Private `uploads.linear.app` images are streamed in memory with Linear auth and attached as native image blocks; text-only models skip downloads with a clear note.
+
 ## 0.2.3
 
 ### Patch Changes

package/node_modules/pi-mono-linear/README.md

@@ -132,11 +132,28 @@ Linear API keys are sent in the `Authorization` header as the raw key value; do
 - `linear_create_issue` accepts either a team UUID or a team key; keys are resolved to UUIDs before the Linear mutation.
 - Use `linear_search_issues` for keyword lookup.
 - Use `linear_get_issue` before updating an issue or creating a comment.
+- `linear_get_issue` automatically parses Markdown images embedded in the issue description. When the active model supports image input, private `uploads.linear.app` images are downloaded in memory with Linear auth and attached to the tool result; images are not written to disk.
+- If the active model does not support image input, `linear_get_issue` does not download images and returns a clear skipped-images note plus image metadata.
 - Use `linear_list_issues` for filtered issue lists by team, assignee, status, and limit.
 - Use `linear_upload_file` to upload a local image, video, or generic file and return a Linear asset URL.
 - Use `linear_upload_file_to_issue_comment` after `linear_get_issue` to upload a local file and post a Markdown comment. Images are rendered with image Markdown; other files use links.
 - File upload tool results return sanitized metadata and the stable Linear asset URL. They do not return local file bytes, signed upload URLs, or upload headers.
 
+## Issue description images
+
+Linear issue screenshots embedded in descriptions are stored as Markdown image links, for example:
+
+```md
+![Screenshot](https://uploads.linear.app/...)
+```
+
+These are part of the issue description Markdown, not GraphQL attachment objects. `linear_get_issue` reads them automatically when possible:
+
+- Vision-capable model: images are streamed into memory, base64-encoded, and returned as native image blocks alongside the Markdown description.
+- Text-only model: image downloads are skipped to avoid unnecessary network and payload work; the response includes a note explaining that a vision-capable model is required.
+- No files are saved locally by default.
+- The default safety limits are 10 description images and 10 MiB per image.
+
 ## Troubleshooting
 
 ### Missing auth key

package/node_modules/pi-mono-linear/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mono-linear",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Pi extension and skill for Linear GraphQL tools",
   "type": "module",
   "keywords": [

package/node_modules/pi-mono-linear/skills/linear/SKILL.md

@@ -27,6 +27,8 @@ If auth is missing, invalid, or expired, do **not** ask the user to paste the ke
 - Use `linear_workspace_metadata` first when team/project/state/label/user IDs are unknown.
 - Use `linear_search_issues` for keyword lookup.
 - Use `linear_get_issue` before updating or commenting.
+- Use `linear_get_issue` to inspect Linear issues; Markdown images embedded in the issue description are automatically included when the active model supports image input.
+- If `linear_get_issue` reports description images were skipped because the current model does not support images, ask the user to switch to a vision-capable model before interpreting screenshots.
 - Use `linear_list_issues` for filtered issue lists by team, assignee, status, or limit.
 - Use `linear_create_issue` to create issues once the team ID is known.
 - Use `linear_update_issue` to change title, description, priority, state, or assignee.
@@ -76,6 +78,14 @@ If auth is missing, invalid, or expired, do **not** ask the user to paste the ke
 - `linear_upload_file`
 - `linear_upload_file_to_issue_comment`
 
+## Issue Description Images
+
+- Linear issue screenshots embedded in descriptions are Markdown images, not necessarily GraphQL attachment objects.
+- `linear_get_issue` parses description Markdown image links like `![Screenshot](https://uploads.linear.app/...)`.
+- When the active model supports image input, `linear_get_issue` downloads private Linear image URLs in memory with Linear auth and attaches native image blocks to the result.
+- When the active model is text-only, image downloads are skipped and the tool returns a note plus image metadata.
+- Description images are not written to disk by default.
+
 ## File Upload Notes
 
 - Upload tools accept local file paths only; they do not read folders recursively.

package/node_modules/pi-mono-linear/src/linear-client.ts

@@ -5,6 +5,7 @@ import { createHttpClient, type HttpClient } from "pi-common/http-client";
 import { createRateLimiter, type RateLimiter } from "pi-common/rate-limiter";
 import { readFile, stat } from "node:fs/promises";
 import { basename, extname, resolve } from "node:path";
+import type { MarkdownImageReference } from "./linear-markdown-images.js";
 import * as queries from "./linear-queries.js";
 
 export interface LinearClientOptions {
@@ -46,6 +47,20 @@ export interface UploadFileInput {
 	makePublic?: boolean;
 }
 
+export interface DownloadIssueImageInput {
+	reference: MarkdownImageReference;
+	maxBytes?: number;
+	signal?: AbortSignal;
+}
+
+export interface DownloadedIssueImageResult {
+	reference: MarkdownImageReference;
+	filename: string;
+	mimeType: string;
+	size: number;
+	data: string;
+}
+
 interface UploadFileHeader {
 	key: string;
 	value: string;
@@ -98,6 +113,8 @@ interface GraphQlResponse<T> {
 
 const cache = createTtlCache<unknown>({ defaultTtlMs: 60_000, maxEntries: 100 });
 const DEFAULT_MAX_UPLOAD_BYTES = 50 * 1024 * 1024;
+const DEFAULT_MAX_DOWNLOAD_IMAGE_BYTES = 10 * 1024 * 1024;
+const SUPPORTED_INLINE_IMAGE_TYPES = new Set(["image/png", "image/jpeg", "image/webp", "image/gif"]);
 
 export class LinearClient {
 	private readonly http: HttpClient;
@@ -224,6 +241,10 @@ export class LinearClient {
 		};
 	}
 
+	async downloadIssueImage(input: DownloadIssueImageInput): Promise<DownloadedIssueImageResult> {
+		return downloadIssueImage(input);
+	}
+
 	listCycles(teamId?: string): Promise<unknown> {
 		return teamId
 			? this.cached(`teamCycles:${teamId}`, () => this.graphql(queries.LIST_TEAM_CYCLES, { id: teamId }))
@@ -344,6 +365,131 @@ async function safeUploadBody(response: Response): Promise<unknown> {
 	}
 }
 
+async function downloadIssueImage(input: DownloadIssueImageInput): Promise<DownloadedIssueImageResult> {
+	const url = validateLinearImageUrl(input.reference.url);
+	const maxBytes = input.maxBytes ?? DEFAULT_MAX_DOWNLOAD_IMAGE_BYTES;
+	if (!Number.isFinite(maxBytes) || maxBytes <= 0) {
+		throw new ApiError("maxImageBytes must be a positive number", 400, { maxBytes }, "Linear");
+	}
+
+	const token = await readLinearToken();
+	const response = await downloadLinearFile(url, token, input.signal);
+	if (!response.ok) {
+		throw new ApiError(response.statusText || `Image download failed with HTTP ${response.status}`, response.status, await safeUploadBody(response), "Linear");
+	}
+	if (!response.body) {
+		throw new ApiError("Image download response did not include a body", 502, { url }, "Linear");
+	}
+
+	const contentLength = response.headers.get("content-length");
+	if (contentLength && Number(contentLength) > maxBytes) {
+		throw new ApiError(`Image is too large (${contentLength} bytes). Limit is ${maxBytes} bytes.`, 400, { size: Number(contentLength), maxBytes }, "Linear");
+	}
+
+	const bytes = await readResponseBytes(response.body, maxBytes);
+	const mimeType = detectSupportedImageMimeType(bytes, response.headers.get("content-type"));
+	if (!mimeType) {
+		throw new ApiError("Downloaded file is not a supported inline image", 415, { contentType: response.headers.get("content-type"), supportedTypes: [...SUPPORTED_INLINE_IMAGE_TYPES] }, "Linear");
+	}
+
+	return {
+		reference: input.reference,
+		filename: filenameForImageUrl(url, mimeType, input.reference.index),
+		mimeType,
+		size: bytes.byteLength,
+		data: Buffer.from(bytes).toString("base64"),
+	};
+}
+
+async function downloadLinearFile(url: string, token: string, signal?: AbortSignal): Promise<Response> {
+	const normalizedToken = token.replace(/^Bearer\s+/i, "").trim();
+	const rawResponse = await fetch(url, { method: "GET", headers: { Authorization: normalizedToken }, signal });
+	if (rawResponse.status !== 401 && rawResponse.status !== 403) return rawResponse;
+
+	// Linear personal API keys use `Authorization: <API_KEY>`, while OAuth access
+	// tokens use `Authorization: Bearer <ACCESS_TOKEN>`. The extension normally
+	// stores personal API keys, but this fallback keeps file reads compatible with
+	// OAuth-style tokens without requiring a separate auth configuration.
+	await rawResponse.body?.cancel().catch(() => undefined);
+	return fetch(url, { method: "GET", headers: { Authorization: `Bearer ${normalizedToken}` }, signal });
+}
+
+function validateLinearImageUrl(value: string): string {
+	let url: URL;
+	try {
+		url = new URL(value);
+	} catch {
+		throw new ApiError("Invalid image URL in Linear issue description", 400, { url: value }, "Linear");
+	}
+	if (url.protocol !== "https:") {
+		throw new ApiError("Only HTTPS Linear image URLs are supported", 400, { url: value }, "Linear");
+	}
+	if (url.hostname !== "uploads.linear.app") {
+		throw new ApiError("Only uploads.linear.app issue description images are supported", 400, { url: value, hostname: url.hostname }, "Linear");
+	}
+	return url.toString();
+}
+
+async function readResponseBytes(body: ReadableStream<Uint8Array>, maxBytes: number): Promise<Uint8Array> {
+	const reader = body.getReader();
+	const chunks: Uint8Array[] = [];
+	let total = 0;
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			if (!value) continue;
+			total += value.byteLength;
+			if (total > maxBytes) {
+				throw new ApiError(`Image is too large. Limit is ${maxBytes} bytes.`, 400, { size: total, maxBytes }, "Linear");
+			}
+			chunks.push(value);
+		}
+	} finally {
+		reader.releaseLock();
+	}
+	return Buffer.concat(chunks, total);
+}
+
+function detectSupportedImageMimeType(bytes: Uint8Array, contentType: string | null): string | undefined {
+	const magic = detectImageMimeTypeFromMagicBytes(bytes);
+	if (magic && SUPPORTED_INLINE_IMAGE_TYPES.has(magic)) return magic;
+
+	const normalized = contentType?.split(";")[0]?.trim().toLowerCase();
+	if (normalized && SUPPORTED_INLINE_IMAGE_TYPES.has(normalized)) return normalized;
+	return undefined;
+}
+
+function detectImageMimeTypeFromMagicBytes(bytes: Uint8Array): string | undefined {
+	if (bytes.length >= 8 && bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47 && bytes[4] === 0x0d && bytes[5] === 0x0a && bytes[6] === 0x1a && bytes[7] === 0x0a) return "image/png";
+	if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return "image/jpeg";
+	if (bytes.length >= 6) {
+		const signature = Buffer.from(bytes.slice(0, 6)).toString("ascii");
+		if (signature === "GIF87a" || signature === "GIF89a") return "image/gif";
+	}
+	if (bytes.length >= 12) {
+		const riff = Buffer.from(bytes.slice(0, 4)).toString("ascii");
+		const webp = Buffer.from(bytes.slice(8, 12)).toString("ascii");
+		if (riff === "RIFF" && webp === "WEBP") return "image/webp";
+	}
+	return undefined;
+}
+
+function filenameForImageUrl(url: string, mimeType: string, index: number): string {
+	const pathname = new URL(url).pathname;
+	const leaf = basename(pathname);
+	const extension = extensionForMimeType(mimeType);
+	if (leaf && leaf.includes(".")) return leaf;
+	return `linear-description-image-${index}.${extension}`;
+}
+
+function extensionForMimeType(mimeType: string): string {
+	if (mimeType === "image/jpeg") return "jpg";
+	if (mimeType === "image/webp") return "webp";
+	if (mimeType === "image/gif") return "gif";
+	return "png";
+}
+
 function inferContentType(filePath: string): string {
 	const extension = extname(filePath).toLowerCase();
 	return CONTENT_TYPES[extension] ?? "application/octet-stream";

package/node_modules/pi-mono-linear/src/linear-markdown-images.ts

@@ -0,0 +1,91 @@
+export interface MarkdownImageReference {
+	index: number;
+	source: "description";
+	altText: string;
+	url: string;
+	rawMarkdown: string;
+	line: number;
+	start: number;
+	end: number;
+	contextSnippet: string;
+}
+
+export interface ExtractMarkdownImagesOptions {
+	source?: MarkdownImageReference["source"];
+	contextLines?: number;
+}
+
+const MARKDOWN_IMAGE_RE = /!\[([^\]]*)\]\(\s*(<[^>]+>|[^\s)]+)(?:\s+["'][^"']*["'])?\s*\)/g;
+
+export function extractMarkdownImages(markdown: string, options: ExtractMarkdownImagesOptions = {}): MarkdownImageReference[] {
+	const source = options.source ?? "description";
+	const contextLines = options.contextLines ?? 2;
+	const lineStarts = getLineStarts(markdown);
+	const lines = markdown.split("\n");
+	const references: MarkdownImageReference[] = [];
+
+	for (const match of markdown.matchAll(MARKDOWN_IMAGE_RE)) {
+		const rawMarkdown = match[0];
+		const rawUrl = match[2] ?? "";
+		const url = unwrapMarkdownUrl(rawUrl);
+		if (!url) continue;
+
+		const start = match.index ?? 0;
+		const end = start + rawMarkdown.length;
+		const line = lineForOffset(lineStarts, start);
+		references.push({
+			index: references.length + 1,
+			source,
+			altText: unescapeMarkdownText(match[1] ?? ""),
+			url,
+			rawMarkdown,
+			line,
+			start,
+			end,
+			contextSnippet: buildContextSnippet(lines, line, contextLines),
+		});
+	}
+
+	return references;
+}
+
+function unwrapMarkdownUrl(rawUrl: string): string {
+	const trimmed = rawUrl.trim();
+	if (trimmed.startsWith("<") && trimmed.endsWith(">")) return trimmed.slice(1, -1).trim();
+	return trimmed;
+}
+
+function unescapeMarkdownText(value: string): string {
+	return value.replace(/\\([\\\[\]])/g, "$1");
+}
+
+function getLineStarts(text: string): number[] {
+	const starts = [0];
+	for (let index = 0; index < text.length; index++) {
+		if (text[index] === "\n") starts.push(index + 1);
+	}
+	return starts;
+}
+
+function lineForOffset(lineStarts: number[], offset: number): number {
+	let low = 0;
+	let high = lineStarts.length - 1;
+	while (low <= high) {
+		const mid = Math.floor((low + high) / 2);
+		const start = lineStarts[mid] ?? 0;
+		const next = lineStarts[mid + 1] ?? Number.POSITIVE_INFINITY;
+		if (offset >= start && offset < next) return mid + 1;
+		if (offset < start) high = mid - 1;
+		else low = mid + 1;
+	}
+	return lineStarts.length;
+}
+
+function buildContextSnippet(lines: string[], line: number, contextLines: number): string {
+	const start = Math.max(1, line - contextLines);
+	const end = Math.min(lines.length, line + contextLines);
+	return lines
+		.slice(start - 1, end)
+		.map((text, index) => `${start + index}: ${text}`)
+		.join("\n");
+}

package/node_modules/pi-mono-linear/src/linear-schemas.ts

@@ -15,7 +15,13 @@ export const OptionalTeamParams = Type.Object({ teamId: Type.Optional(TeamIdSche
 export const IdParams = Type.Object({ id: Type.String({ description: "Linear object ID" }), maxResponseChars: MaxResponseCharsSchema });
 
 export const LinearGetTeamParams = Type.Object({ teamId: TeamIdSchema, maxResponseChars: MaxResponseCharsSchema });
-export const LinearGetIssueParams = Type.Object({ issueId: IssueIdSchema, maxResponseChars: MaxResponseCharsSchema });
+export const LinearGetIssueParams = Type.Object({
+	issueId: IssueIdSchema,
+	readDescriptionImages: Type.Optional(Type.Boolean({ description: "Read Markdown images embedded in the issue description when the active model supports image input. Defaults to true." })),
+	maxDescriptionImages: Type.Optional(Type.Number({ description: "Maximum number of description images to read. Defaults to 10.", minimum: 1, maximum: 50 })),
+	maxImageBytes: Type.Optional(Type.Number({ description: "Maximum bytes per description image before download is stopped. Defaults to 10 MiB.", minimum: 1 })),
+	maxResponseChars: MaxResponseCharsSchema,
+});
 export const LinearGetProjectParams = Type.Object({ projectId: ProjectIdSchema, maxResponseChars: MaxResponseCharsSchema });
 export const LinearGetUserParams = Type.Object({ userId: UserIdSchema, maxResponseChars: MaxResponseCharsSchema });
 export const LinearGetDocumentParams = Type.Object({ documentId: Type.String({ description: "Linear document UUID" }), maxResponseChars: MaxResponseCharsSchema });

package/node_modules/pi-mono-linear/src/linear-tools.ts

@@ -1,7 +1,8 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { registerAuthConfigurator, runWithAuthRetry, type AuthConfiguratorOptions } from "pi-common/auth-config";
 import { jsonToolResult } from "pi-common/tool-result";
-import { LinearClient, type UploadedFileResult } from "./linear-client.js";
+import { LinearClient, type DownloadedIssueImageResult, type UploadedFileResult } from "./linear-client.js";
+import { extractMarkdownImages, type MarkdownImageReference } from "./linear-markdown-images.js";
 import {
 	EmptyParams,
 	LinearCommentsParams,
@@ -23,6 +24,30 @@ import {
 	OptionalTeamParams,
 } from "./linear-schemas.js";
 
+type LinearToolContent = { type: "text"; text: string } | { type: "image"; data: string; mimeType: string };
+
+interface DescriptionImageManifestEntry {
+	index: number;
+	source: "description";
+	altText: string;
+	url: string;
+	line: number;
+	contextSnippet: string;
+	status: "downloaded" | "skipped";
+	mimeType?: string;
+	size?: number;
+	filename?: string;
+	reason?: string;
+}
+
+interface LinearIssueNodeLike {
+	id?: string;
+	identifier?: string;
+	title?: string;
+	url?: string;
+	description?: string | null;
+}
+
 const LINEAR_AUTH: AuthConfiguratorOptions = {
 	service: "linear",
 	displayName: "Linear",
@@ -57,6 +82,139 @@ function escapeMarkdownAltText(value: string): string {
 	return value.replaceAll("[", "\\[").replaceAll("]", "\\]");
 }
 
+function getIssueNode(result: unknown): LinearIssueNodeLike | undefined {
+	if (!result || typeof result !== "object") return undefined;
+	const issue = (result as { issue?: unknown }).issue;
+	if (!issue || typeof issue !== "object") return undefined;
+	return issue as LinearIssueNodeLike;
+}
+
+function modelSupportsImages(ctx: ExtensionContext): boolean {
+	return ctx.model?.input?.includes("image") ?? false;
+}
+
+function buildSkippedManifestEntry(reference: MarkdownImageReference, reason: string): DescriptionImageManifestEntry {
+	return {
+		index: reference.index,
+		source: reference.source,
+		altText: reference.altText,
+		url: reference.url,
+		line: reference.line,
+		contextSnippet: reference.contextSnippet,
+		status: "skipped",
+		reason,
+	};
+}
+
+function buildDownloadedManifestEntry(image: DownloadedIssueImageResult): DescriptionImageManifestEntry {
+	return {
+		index: image.reference.index,
+		source: image.reference.source,
+		altText: image.reference.altText,
+		url: image.reference.url,
+		line: image.reference.line,
+		contextSnippet: image.reference.contextSnippet,
+		status: "downloaded",
+		mimeType: image.mimeType,
+		size: image.size,
+		filename: image.filename,
+	};
+}
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+function appendImageReadingMetadata(result: unknown, imageReading: unknown): unknown {
+	if (!result || typeof result !== "object" || Array.isArray(result)) return { result, imageReading };
+	return { ...(result as Record<string, unknown>), imageReading };
+}
+
+function issueLabel(issue: LinearIssueNodeLike | undefined): string {
+	if (!issue) return "Linear issue";
+	return [issue.identifier, issue.title].filter(Boolean).join(" — ") || issue.id || "Linear issue";
+}
+
+function imageNote(reference: MarkdownImageReference, image: DownloadedIssueImageResult): string {
+	return [
+		`[Description image ${reference.index}: alt=${JSON.stringify(reference.altText || "image")}, line=${reference.line}, mimeType=${image.mimeType}, size=${image.size} bytes]`,
+		"Markdown context:",
+		reference.contextSnippet,
+	].join("\n");
+}
+
+async function buildIssueResultWithDescriptionImages(options: {
+	client: LinearClient;
+	result: unknown;
+	ctx: ExtensionContext;
+	readDescriptionImages?: boolean;
+	maxDescriptionImages?: number;
+	maxImageBytes?: number;
+	maxResponseChars?: number;
+	signal?: AbortSignal;
+}): Promise<{ content: LinearToolContent[]; details: Record<string, unknown> }> {
+	const issue = getIssueNode(options.result);
+	const description = issue?.description ?? "";
+	const references = typeof description === "string" ? extractMarkdownImages(description, { source: "description" }) : [];
+	const shouldReadImages = options.readDescriptionImages ?? true;
+	if (!references.length || !shouldReadImages) {
+		return jsonToolResult(options.result, { maxChars: options.maxResponseChars });
+	}
+
+	const maxImages = options.maxDescriptionImages ?? 10;
+	const selected = references.slice(0, maxImages);
+	const overflow = references.slice(maxImages);
+	const supportsImages = modelSupportsImages(options.ctx);
+	const manifest: DescriptionImageManifestEntry[] = [];
+	const imageContents: LinearToolContent[] = [];
+
+	if (!supportsImages) {
+		manifest.push(...references.map((reference) => buildSkippedManifestEntry(reference, "model_does_not_support_images")));
+		const note = `Description images detected but not downloaded because the current model does not support image input. Switch to a vision-capable model to inspect them.`;
+		const data = appendImageReadingMetadata(options.result, {
+			modelSupportsImages: false,
+			descriptionImagesFound: references.length,
+			descriptionImages: manifest,
+			note,
+		});
+		const base = jsonToolResult(data, { maxChars: options.maxResponseChars });
+		return {
+			content: [...base.content, { type: "text", text: `\n[${note}]` }],
+			details: { ...base.details, imageReading: { issue: issue ? { id: issue.id, identifier: issue.identifier, title: issue.title, url: issue.url } : undefined, descriptionImages: manifest } },
+		};
+	}
+
+	for (const reference of selected) {
+		try {
+			const image = await options.client.downloadIssueImage({ reference, maxBytes: options.maxImageBytes, signal: options.signal });
+			manifest.push(buildDownloadedManifestEntry(image));
+			imageContents.push({ type: "text", text: imageNote(reference, image) }, { type: "image", mimeType: image.mimeType, data: image.data });
+		} catch (error) {
+			manifest.push(buildSkippedManifestEntry(reference, errorMessage(error)));
+			imageContents.push({ type: "text", text: `[Description image ${reference.index} skipped: ${errorMessage(error)}]` });
+		}
+	}
+	for (const reference of overflow) {
+		manifest.push(buildSkippedManifestEntry(reference, `maxDescriptionImages limit (${maxImages}) reached`));
+	}
+
+	const data = appendImageReadingMetadata(options.result, {
+		modelSupportsImages: true,
+		descriptionImagesFound: references.length,
+		descriptionImagesRead: manifest.filter((entry) => entry.status === "downloaded").length,
+		descriptionImages: manifest,
+	});
+	const base = jsonToolResult(data, { maxChars: options.maxResponseChars });
+	const preamble: LinearToolContent = {
+		type: "text",
+		text: `\nRead ${manifest.filter((entry) => entry.status === "downloaded").length} of ${references.length} Markdown description image(s) for ${issueLabel(issue)}. Images are attached below in description order.`,
+	};
+	return {
+		content: [...base.content, preamble, ...imageContents],
+		details: { ...base.details, imageReading: { issue: issue ? { id: issue.id, identifier: issue.identifier, title: issue.title, url: issue.url } : undefined, descriptionImages: manifest } },
+	};
+}
+
 export function registerLinearTools(pi: ExtensionAPI): void {
 	const client = new LinearClient();
 	registerAuthConfigurator(pi, LINEAR_AUTH);
@@ -127,10 +285,24 @@ export function registerLinearTools(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "linear_get_issue",
 		label: "Linear Get Issue",
-		description: "Get full Linear issue details by UUID or identifier like ENG-123.",
+		description: "Get full Linear issue details by UUID or identifier like ENG-123. Markdown images embedded in the issue description are read and attached when the active model supports image input.",
+		promptGuidelines: [
+			"Use linear_get_issue to inspect Linear issues; if the issue description contains Markdown images and the active model supports image input, the images are downloaded in memory and attached to the tool result.",
+			"When linear_get_issue reports description images were skipped because the model does not support images, ask the user to switch to a vision-capable model before interpreting screenshots.",
+		],
 		parameters: LinearGetIssueParams,
-		async execute(_id, params, _signal, _onUpdate, ctx) {
-			return jsonToolResult(await withLinearAuth(ctx, () => client.getIssue(params.issueId)), { maxChars: params.maxResponseChars });
+		async execute(_id, params, signal, _onUpdate, ctx) {
+			const result = await withLinearAuth(ctx, () => client.getIssue(params.issueId));
+			return buildIssueResultWithDescriptionImages({
+				client,
+				result,
+				ctx,
+				readDescriptionImages: params.readDescriptionImages,
+				maxDescriptionImages: params.maxDescriptionImages,
+				maxImageBytes: params.maxImageBytes,
+				maxResponseChars: params.maxResponseChars,
+				signal,
+			});
 		},
 	});
 

package/node_modules/pi-mono-sentinel/CHANGELOG.md

@@ -1,5 +1,15 @@
 # pi-mono-sentinel
 
+## 1.13.0
+
+### Minor Changes
+
+### Enhanced: path-access grants
+
+- Added smarter path-access prompts that distinguish existing files, new files, directories, and multiple same-folder file targets.
+- Added session-only permission grants for `write` / `edit`, including recursive directory grants that reset with the session.
+- Added exact multi-file grants for bash commands that reference several outside-project files in the same directory.
+
 ## 1.12.0
 
 ### Changed

package/node_modules/pi-mono-sentinel/__tests__/path-access.test.ts

@@ -10,6 +10,7 @@ import {
 	directoryGrantFor,
 	isInsideCwd,
 	isPathAllowed,
+	pathAccessGrantsForChoice,
 	pathAccessGrantForChoice,
 	toStoragePath,
 } from "../path-access.ts";
@@ -78,4 +79,24 @@ describe("path-access helpers", () => {
 			rmSync(cwd, { recursive: true, force: true });
 		}
 	});
+
+	test("derives grants for multiple exact files", () => {
+		assert.deepEqual(
+			pathAccessGrantsForChoice("allow_files_session", ["/tmp/a/one.txt", "/tmp/a/two.txt"], CWD),
+			[
+				{
+					grant: "/tmp/a/one.txt",
+					broadCheckPath: "/tmp/a/one.txt",
+					scope: "memory",
+					directory: false,
+				},
+				{
+					grant: "/tmp/a/two.txt",
+					broadCheckPath: "/tmp/a/two.txt",
+					scope: "memory",
+					directory: false,
+				},
+			],
+		);
+	});
 });

package/node_modules/pi-mono-sentinel/__tests__/whitelist.test.ts

@@ -50,6 +50,17 @@ describe("SentinelSession whitelist", () => {
 		assert.equal(session.isWhitelisted("/persisted/path"), true);
 	});
 
+	test("session directory grants are recursive and reset-scoped", () => {
+		const session = new SentinelSession();
+		session.addToSessionWhitelist("/tmp/sentinel-session-dir/");
+		assert.equal(session.isWhitelisted("/tmp/sentinel-session-dir/file.md"), true);
+		assert.equal(session.isWhitelisted("/tmp/sentinel-session-dir/nested/file.md"), true);
+		assert.equal(session.isWhitelisted("/tmp/sentinel-session-dir-sibling/file.md"), false);
+
+		session.reset();
+		assert.equal(session.isWhitelisted("/tmp/sentinel-session-dir/file.md"), false);
+	});
+
 	test("read whitelist is separate from permission whitelist", () => {
 		const session = new SentinelSession();
 		session.addToReadWhitelist("/safe/example-doc.md");

package/node_modules/pi-mono-sentinel/guards/path-access.ts

@@ -1,12 +1,14 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { isToolCallEventType } from "@earendil-works/pi-coding-agent";
+import { existsSync, statSync } from "node:fs";
+import { dirname } from "node:path";
 
 import { configLoader, type ResolvedSentinelConfig } from "../config.js";
 import { blockToolCall } from "../events.js";
 import {
 	checkPathAccess,
 	isTooBroadGrant,
-	pathAccessGrantForChoice,
+	pathAccessGrantsForChoice,
 } from "../path-access.js";
 import { extractBashPathCandidates } from "../patterns/bash-paths.js";
 import { resolveTargetPath } from "../patterns/permissions.js";
@@ -14,19 +16,63 @@ import { resolveTargetPath } from "../patterns/permissions.js";
 type GrantChoice =
 	| "allow_once"
 	| "allow_file_session"
+	| "allow_files_session"
 	| "allow_directory_session"
 	| "allow_file_always"
+	| "allow_files_always"
 	| "allow_directory_always"
 	| "deny";
 
-const CHOICES: Array<{ value: GrantChoice; label: string }> = [
-	{ value: "allow_once", label: "Allow once" },
-	{ value: "allow_file_session", label: "Allow file this session" },
-	{ value: "allow_directory_session", label: "Allow directory this session" },
-	{ value: "allow_file_always", label: "Allow file always" },
-	{ value: "allow_directory_always", label: "Allow directory always" },
-	{ value: "deny", label: "Deny" },
-];
+type PathPromptKind = "existing_file" | "new_file" | "directory" | "multiple_files";
+
+function choicesForPathPrompt(kind: PathPromptKind): Array<{ value: GrantChoice; label: string }> {
+	switch (kind) {
+		case "new_file":
+			return [
+				{ value: "allow_once", label: "Allow once" },
+				{ value: "allow_directory_session", label: "Allow creating files in this folder for this session" },
+				{ value: "allow_directory_always", label: "Always allow creating files in this folder" },
+				{ value: "deny", label: "Deny" },
+			];
+		case "directory":
+			return [
+				{ value: "allow_once", label: "Allow once" },
+				{ value: "allow_directory_session", label: "Allow this folder for this session" },
+				{ value: "allow_directory_always", label: "Always allow this folder" },
+				{ value: "deny", label: "Deny" },
+			];
+		case "multiple_files":
+			return [
+				{ value: "allow_once", label: "Allow once" },
+				{ value: "allow_files_session", label: "Allow these files for this session" },
+				{ value: "allow_files_always", label: "Always allow these files" },
+				{ value: "deny", label: "Deny" },
+			];
+		case "existing_file":
+		default:
+			return [
+				{ value: "allow_once", label: "Allow once" },
+				{ value: "allow_file_session", label: "Allow this file for this session" },
+				{ value: "allow_file_always", label: "Always allow this file" },
+				{ value: "deny", label: "Deny" },
+			];
+	}
+}
+
+function promptKindForPath(absolutePath: string, toolName: string): PathPromptKind {
+	try {
+		if (existsSync(absolutePath) && statSync(absolutePath).isDirectory()) return "directory";
+	} catch {
+		// Fall through to operation-based classification.
+	}
+	return toolName === "write" && !existsSync(absolutePath) ? "new_file" : "existing_file";
+}
+
+function allInSameDirectory(paths: readonly string[]): boolean {
+	if (paths.length < 2) return false;
+	const first = dirname(paths[0]);
+	return paths.every((path) => dirname(path) === first);
+}
 
 const MAX_BASH_PATH_CANDIDATES = 50;
 const TOOL_PATH_NORMALIZERS = {
@@ -42,38 +88,63 @@ export function registerPathAccess(pi: ExtensionAPI): void {
 		toolName: string,
 		input: Record<string, unknown>,
 		ctx: { cwd: string; hasUI: boolean; ui: { select?: (title: string, options: string[]) => Promise<string | undefined> } },
+	): Promise<{ block: true; reason: string } | undefined> {
+		return guardPaths(config, [absolutePath], toolName, input, ctx);
+	}
+
+	async function guardPaths(
+		config: ResolvedSentinelConfig,
+		absolutePaths: readonly string[],
+		toolName: string,
+		input: Record<string, unknown>,
+		ctx: { cwd: string; hasUI: boolean; ui: { select?: (title: string, options: string[]) => Promise<string | undefined> } },
 	): Promise<{ block: true; reason: string } | undefined> {
 		if (!config.features.pathAccess || config.pathAccess.mode === "allow") return;
 
-		const check = checkPathAccess(absolutePath, ctx.cwd, config.pathAccess.allowedPaths);
-		if (check.allowed) return;
+		const denied = absolutePaths
+			.map((absolutePath) => checkPathAccess(absolutePath, ctx.cwd, config.pathAccess.allowedPaths))
+			.filter((check) => !check.allowed) as Array<{ allowed: false; absolutePath: string; reason: string }>;
+		if (denied.length === 0) return;
 
-		const reason = check.reason;
+		const deniedPaths = denied.map((check) => check.absolutePath);
+		const reason = denied.length === 1
+			? denied[0].reason
+			: `Paths are outside the current working directory: ${deniedPaths.join(", ")}`;
 		if (config.pathAccess.mode === "block" || !ctx.hasUI) {
 			return blockToolCall(pi, { feature: "pathAccess", toolName, input, reason }, `[sentinel] ${reason}`);
 		}
 
+		const promptKind = deniedPaths.length > 1 && allInSameDirectory(deniedPaths)
+			? "multiple_files"
+			: promptKindForPath(deniedPaths[0], toolName);
+		const choices = choicesForPathPrompt(promptKind);
+		const pathLines = deniedPaths.length === 1
+			? [`Path: ${deniedPaths[0]}`]
+			: ["Paths:", ...deniedPaths.map((path) => `  - ${path}`)];
+
 		const selectedLabel = await ctx.ui.select?.(
 			[
 				"[sentinel] Path access outside current project",
 				`Tool: ${toolName}`,
-				`Path: ${absolutePath}`,
+				...pathLines,
 				`Project: ${ctx.cwd}`,
 				"",
 				"Allow access?",
 			].join("\n"),
-			CHOICES.map((choice) => choice.label),
+			choices.map((choice) => choice.label),
 		);
-		const choice = CHOICES.find((item) => item.label === selectedLabel)?.value ?? "deny";
+		const choice = choices.find((item) => item.label === selectedLabel)?.value ?? "deny";
 
 		if (choice === "allow_once") return;
 
-		const grant = pathAccessGrantForChoice(choice, absolutePath, ctx.cwd);
-		if (grant) {
-			if (isTooBroadGrant(grant.broadCheckPath)) {
-				return { block: true, reason: `[sentinel] Refusing overly broad ${grant.directory ? "directory" : "path"} grant.` };
+		const grants = pathAccessGrantsForChoice(choice, deniedPaths, ctx.cwd);
+		if (grants.length > 0) {
+			for (const grant of grants) {
+				if (isTooBroadGrant(grant.broadCheckPath)) {
+					return { block: true, reason: `[sentinel] Refusing overly broad ${grant.directory ? "directory" : "path"} grant.` };
+				}
+				configLoader.addAllowedPath(grant.scope, grant.grant);
 			}
-			configLoader.addAllowedPath(grant.scope, grant.grant);
 			return;
 		}
 
@@ -94,8 +165,18 @@ export function registerPathAccess(pi: ExtensionAPI): void {
 		const command = event.input.command ?? "";
 		const config = configLoader.getConfig();
 		const candidates = extractBashPathCandidates(command, ctx.cwd).slice(0, MAX_BASH_PATH_CANDIDATES);
+		const pendingByDirectory = new Map<string, string[]>();
 		for (const absolutePath of candidates) {
-			const result = await guardPath(config, absolutePath, "bash", event.input, ctx);
+			const check = checkPathAccess(absolutePath, ctx.cwd, config.pathAccess.allowedPaths);
+			if (check.allowed) continue;
+			const paths = pendingByDirectory.get(dirname(absolutePath)) ?? [];
+			paths.push(absolutePath);
+			pendingByDirectory.set(dirname(absolutePath), paths);
+		}
+		for (const paths of pendingByDirectory.values()) {
+			const result = paths.length > 1
+				? await guardPaths(config, paths, "bash", event.input, ctx)
+				: await guardPath(config, paths[0], "bash", event.input, ctx);
 			if (result) return result;
 		}
 	});

package/node_modules/pi-mono-sentinel/guards/permission-gate.ts

@@ -18,9 +18,11 @@ import type {
 	ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import { isToolCallEventType } from "@earendil-works/pi-coding-agent";
+import { existsSync, statSync } from "node:fs";
 
 import { configLoader } from "../config.js";
 import { blockToolCall, emitDangerous } from "../events.js";
+import { directoryGrantFor, toStoragePath } from "../path-access.js";
 import type { SentinelSession } from "../session.js";
 import {
 	BASH_RISK_DESCRIPTIONS,
@@ -100,6 +102,43 @@ function registerBashGate(pi: ExtensionAPI): void {
 // Write / edit gating
 // ---------------------------------------------------------------------------
 
+type PathGateChoice = "allow_once" | "allow_session" | "allow_always" | "deny";
+
+function pathGateChoices(absolutePath: string, toolName: "write" | "edit"): Array<{ value: PathGateChoice; label: string; directoryGrant: boolean }> {
+	let isDirectory = false;
+	try {
+		isDirectory = existsSync(absolutePath) && statSync(absolutePath).isDirectory();
+	} catch {
+		isDirectory = false;
+	}
+	const isNewFile = toolName === "write" && !existsSync(absolutePath);
+
+	if (isNewFile) {
+		return [
+			{ value: "allow_once", label: "Allow once", directoryGrant: false },
+			{ value: "allow_session", label: "Allow creating files in this folder for this session", directoryGrant: true },
+			{ value: "allow_always", label: "Always allow creating files in this folder", directoryGrant: true },
+			{ value: "deny", label: "Deny", directoryGrant: false },
+		];
+	}
+
+	if (isDirectory) {
+		return [
+			{ value: "allow_once", label: "Allow once", directoryGrant: false },
+			{ value: "allow_session", label: "Allow this folder for this session", directoryGrant: true },
+			{ value: "allow_always", label: "Always allow this folder", directoryGrant: true },
+			{ value: "deny", label: "Deny", directoryGrant: false },
+		];
+	}
+
+	return [
+		{ value: "allow_once", label: "Allow once", directoryGrant: false },
+		{ value: "allow_session", label: "Allow this file for this session", directoryGrant: false },
+		{ value: "allow_always", label: "Always allow this file", directoryGrant: false },
+		{ value: "deny", label: "Deny", directoryGrant: false },
+	];
+}
+
 function registerPathGate(pi: ExtensionAPI, session: SentinelSession): void {
 	const handler = async (
 		rawPath: string | undefined,
@@ -132,18 +171,18 @@ function registerPathGate(pi: ExtensionAPI, session: SentinelSession): void {
 		].join("\n");
 
 		if (ctx.hasUI) {
-			const choice = await ctx.ui.select(title, [
-				"Allow once",
-				"Always allow this path",
-				"Deny",
-			]);
+			const choices = pathGateChoices(absolute, toolName);
+			const selectedLabel = await ctx.ui.select(title, choices.map((choice) => choice.label));
+			const choice = choices.find((item) => item.label === selectedLabel);
 
-			if (choice === "Allow once") {
+			if (choice?.value === "allow_once") {
 				return;
 			}
 
-			if (choice === "Always allow this path") {
-				session.addToWhitelist(absolute);
+			if (choice?.value === "allow_session" || choice?.value === "allow_always") {
+				const grant = choice.directoryGrant ? directoryGrantFor(absolute) : toStoragePath(absolute);
+				if (choice.value === "allow_session") session.addToSessionWhitelist(grant);
+				else session.addToWhitelist(grant);
 				return;
 			}
 

package/node_modules/pi-mono-sentinel/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mono-sentinel",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "Pi extension that guards against content-based secret leaks and indirect script execution",
   "keywords": [
     "pi-package",

package/node_modules/pi-mono-sentinel/path-access.ts

@@ -33,6 +33,24 @@ export function pathAccessGrantForChoice(choice: string, absolutePath: string, c
 	};
 }
 
+export function pathAccessGrantsForChoice(choice: string, absolutePaths: readonly string[], cwd: string): Array<{ grant: string; broadCheckPath: string; scope: "memory" | "local"; directory: boolean }> {
+	if (absolutePaths.length === 0) return [];
+	const match = /^allow_(file|directory|files)_(session|always)$/.exec(choice);
+	if (!match) return [];
+
+	if (match[1] === "files") {
+		return absolutePaths.map((absolutePath) => ({
+			grant: toStoragePath(absolutePath),
+			broadCheckPath: absolutePath,
+			scope: match[2] === "always" ? "local" : "memory",
+			directory: false,
+		}));
+	}
+
+	const grant = pathAccessGrantForChoice(choice, absolutePaths[0], cwd);
+	return grant ? [grant] : [];
+}
+
 export function isTooBroadGrant(absolutePath: string): boolean {
 	const normalized = normalize(absolutePath).replace(/[\\/]+$/, "");
 	return normalized === "/" || normalized === homedir();

package/node_modules/pi-mono-sentinel/session.ts

@@ -1,5 +1,6 @@
 import type { ScanResult, WriteEntry } from "./types.js";
 import { configLoader } from "./config.js";
+import { isPathAllowed } from "./path-access.js";
 import {
 	loadReadWhitelist,
 	loadWhitelist,
@@ -27,6 +28,9 @@ export class SentinelSession {
 	/** Persistent whitelist of paths the user chose to remember. */
 	private whitelist = loadWhitelist();
 
+	/** Session-only whitelist of paths the user allowed until reset. */
+	private sessionWhitelist = new Set<string>();
+
 	/** Persistent whitelist of read paths that are safe despite secret matches. */
 	private readWhitelist = loadReadWhitelist();
 
@@ -34,6 +38,7 @@ export class SentinelSession {
 	reset(): void {
 		this.writeRegistry.clear();
 		this.scanCache.clear();
+		this.sessionWhitelist.clear();
 		// whitelist is intentionally NOT cleared here so it persists across sessions
 	}
 
@@ -77,11 +82,18 @@ export class SentinelSession {
 	// -- Whitelist (permission-gate persistence) -------------------------------
 
 	isWhitelisted(absolutePath: string): boolean {
-		return this.whitelist.has(absolutePath);
+		return (
+			isPathAllowed(absolutePath, [...this.sessionWhitelist], process.cwd()) ||
+			isPathAllowed(absolutePath, [...this.whitelist], process.cwd())
+		);
+	}
+
+	addToSessionWhitelist(pathGrant: string): void {
+		this.sessionWhitelist.add(pathGrant);
 	}
 
-	addToWhitelist(absolutePath: string): void {
-		this.whitelist.add(absolutePath);
+	addToWhitelist(pathGrant: string): void {
+		this.whitelist.add(pathGrant);
 		saveWhitelist(this.whitelist);
 	}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mono-all",
-  "version": "1.2.4",
+  "version": "1.2.6",
   "description": "All pi-mono extensions and bundled skills",
   "type": "module",
   "keywords": [
@@ -9,24 +9,24 @@
     "pi-skill"
   ],
   "dependencies": {
-    "pi-mono-auto-fix": "0.3.1",
     "pi-mono-ask-user-question": "1.7.4",
+    "pi-mono-auto-fix": "0.3.1",
     "pi-mono-btw": "1.7.4",
     "pi-mono-clear": "1.7.3",
     "pi-mono-context": "0.1.1",
-    "pi-mono-context-guard": "1.7.3",
-    "pi-mono-linear": "0.2.3",
-    "pi-common": "0.1.1",
     "pi-mono-figma": "0.2.2",
+    "pi-mono-context-guard": "1.7.3",
+    "pi-mono-loop": "1.7.3",
     "pi-mono-multi-edit": "1.7.3",
-    "pi-mono-sentinel": "1.12.0",
+    "pi-mono-linear": "0.2.4",
     "pi-mono-simplify": "1.7.3",
-    "pi-mono-review": "1.8.2",
+    "pi-mono-sentinel": "1.13.0",
     "pi-mono-team-mode": "2.3.2",
-    "pi-mono-status-line": "1.7.3",
     "pi-mono-usage": "0.1.1",
     "pi-mono-web-search": "0.1.0",
-    "pi-mono-loop": "1.7.3"
+    "pi-mono-review": "1.8.2",
+    "pi-common": "0.1.1",
+    "pi-mono-status-line": "1.7.3"
   },
   "bundledDependencies": [
     "pi-mono-ask-user-question",