@gajae-code/coding-agent 0.12.0 → 0.12.1

package/src/tools/find.ts

@@ -158,6 +158,7 @@ export class FindTool implements AgentTool<typeof findSchema, FindToolDetails> {
 				const resource = await internalRouter.resolve(rawPattern, {
 					cwd: this.session.cwd,
 					getArtifactsDir: this.session.getArtifactsDir,
+					getAuthorizedArtifactsDirs: this.session.getAuthorizedArtifactsDirs,
 				});
 				if (!resource.sourcePath) {
 					throw new ToolError(`Cannot find internal URL without a backing file: ${rawPattern}`);

package/src/tools/image-gen.ts

@@ -12,7 +12,7 @@ import {
 	URL_PATHS,
 } from "@gajae-code/ai/providers/openai-codex/constants";
 import {
-	$env,
+	$credentialEnv,
 	isEnoent,
 	parseImageMetadata,
 	prompt,
@@ -794,6 +794,23 @@ async function findAlibabaImageCredentials(
 	return { provider: "alibaba", apiKey };
 }
 
+/**
+ * Google image-provider key fallback, from trusted environment sources only.
+ *
+ * `$env` merges the caller's `cwd/.env`, so reading the key there would let
+ * repository content supply the credential these image requests authenticate
+ * with. Provider credentials resolve from the launching shell plus GJC/user-owned
+ * `.env` files, never the project `.env`.
+ */
+function googleImageApiKeyFromEnv(): string | undefined {
+	return $credentialEnv("GOOGLE_API_KEY");
+}
+
+/** Test seam: the Google image key fallback as resolved from trusted env. */
+export function googleImageApiKeyFromEnvForTest(): string | undefined {
+	return googleImageApiKeyFromEnv();
+}
+
 async function findImageApiKey(
 	modelRegistry?: ModelRegistry,
 	activeModel?: Model,
@@ -827,7 +844,7 @@ async function findImageApiKey(
 		if (config.provider === "gemini") {
 			const geminiKey = getEnvApiKey("google");
 			if (geminiKey) return { provider: "gemini", apiKey: geminiKey };
-			const googleKey = $env.GOOGLE_API_KEY;
+			const googleKey = googleImageApiKeyFromEnv();
 			return googleKey ? { provider: "gemini", apiKey: googleKey } : null;
 		}
 		if (config.provider === "openrouter") {
@@ -850,7 +867,7 @@ async function findImageApiKey(
 	} else if (preferredImageProvider === "gemini") {
 		const geminiKey = getEnvApiKey("google");
 		if (geminiKey) return { provider: "gemini", apiKey: geminiKey };
-		const googleKey = $env.GOOGLE_API_KEY;
+		const googleKey = googleImageApiKeyFromEnv();
 		return googleKey ? { provider: "gemini", apiKey: googleKey } : null;
 	} else if (preferredImageProvider === "openrouter") {
 		const openRouterKey = getEnvApiKey("openrouter");
@@ -874,7 +891,7 @@ async function findImageApiKey(
 	const geminiKey = getEnvApiKey("google");
 	if (geminiKey) return { provider: "gemini", apiKey: geminiKey };
 
-	const googleKey = $env.GOOGLE_API_KEY;
+	const googleKey = googleImageApiKeyFromEnv();
 	if (googleKey) return { provider: "gemini", apiKey: googleKey };
 
 	const alibaba = await findAlibabaImageCredentials(modelRegistry, sessionId);
@@ -1106,7 +1123,9 @@ function getOpenAIBaseUrl(model: Model, authCredentialType?: "api_key" | "oauth"
 		return (model.baseUrl || CODEX_BASE_URL).replace(/\/+$/, "");
 	}
 	if (authCredentialType === "oauth") return DEFAULT_OPENAI_BASE_URL;
-	const envBaseUrl = $env.OPENAI_BASE_URL?.trim();
+	// Trusted sources only: this base URL becomes the endpoint for authenticated
+	// image requests, and `$env` merges the caller's `cwd/.env`.
+	const envBaseUrl = $credentialEnv("OPENAI_BASE_URL");
 	const configuredBaseUrl = model.baseUrl?.trim();
 	if (envBaseUrl && (!configuredBaseUrl || configuredBaseUrl.toLowerCase().includes("api.openai.com"))) {
 		return envBaseUrl.replace(/\/+$/, "");
@@ -1114,6 +1133,11 @@ function getOpenAIBaseUrl(model: Model, authCredentialType?: "api_key" | "oauth"
 	return (configuredBaseUrl || envBaseUrl || DEFAULT_OPENAI_BASE_URL).replace(/\/+$/, "");
 }
 
+/** Test seam: the image-request base URL as resolved from trusted env. */
+export function getOpenAIImageBaseUrlForTest(model: Model, authCredentialType?: "api_key" | "oauth"): string {
+	return getOpenAIBaseUrl(model, authCredentialType);
+}
+
 function getOpenAIResponsesUrl(model: Model, authCredentialType?: "api_key" | "oauth"): string {
 	const baseUrl = getOpenAIBaseUrl(model, authCredentialType);
 	if (model.api !== "openai-codex-responses" && model.provider !== "openai-codex") {

package/src/tools/index.ts

@@ -292,6 +292,8 @@ export interface ToolSession {
 	strictToolNames?: boolean;
 	/** Get artifacts directory for artifact:// URLs */
 	getArtifactsDir?: () => string | null;
+	/** Additional artifacts directories explicitly authorized for this session's tree (parent/child/sibling reads). Derived only from the explicitly adopted/shared `ArtifactManager`; never enumerates unrelated live sessions. */
+	getAuthorizedArtifactsDirs?: () => readonly string[];
 	/** Get the ArtifactManager backing this session (shared across parent + subagents). */
 	getArtifactManager?: () => ArtifactManager | null;
 	/** Allocate a new artifact path and ID for session-scoped truncated output. */
@@ -314,6 +316,8 @@ export interface ToolSession {
 	settings: Settings;
 	/** Live service-tier intent of the parent session, inherited by `inherit` subagents. */
 	serviceTier?: ServiceTier;
+	/** Whether the effective subagent tier grants fast mode for a resolved provider. */
+	isFastForSubagentProvider?: (provider?: string) => boolean;
 	/** Plan mode state (if active) */
 	getPlanModeState?: () => PlanModeState | undefined;
 	/** Goal mode state (if active or paused) */

package/src/tools/output-meta.ts

@@ -53,8 +53,12 @@ export interface TruncationMeta {
 	elidedBytes?: number;
 	/** Lines elided from the middle. */
 	elidedLines?: number;
-	/** Artifact ID if full output was saved */
+	/** Artifact ID when output was persisted; completeness is tracked separately below. */
 	artifactId?: string;
+	/** Bytes omitted from an artifact after its hard storage cap was reached. */
+	artifactTruncatedBytes?: number;
+	/** Bounded diagnostic when artifact writer creation, write, or finalization failed. */
+	artifactFailureDiagnostic?: string;
 	/** Next offset for pagination (head truncation only) */
 	nextOffset?: number;
 }
@@ -323,13 +327,30 @@ export class OutputMetaBuilder {
 		return this;
 	}
 
-	/** Add truncation info from OutputSummary. No-op if not truncated. */
+	/** Add truncation info from OutputSummary. No-op if not truncated or artifact evidence is absent. */
 	truncationFromSummary(summary: OutputSummary, options: TruncationSummaryOptions): this {
-		if (!summary.truncated) return this;
+		const artifactFailureDiagnostic = summary.artifactFailureDiagnostic;
+		const artifactTruncatedBytes =
+			summary.artifactTruncatedBytes != null && summary.artifactTruncatedBytes > 0
+				? summary.artifactTruncatedBytes
+				: undefined;
+		const hasArtifactEvidence =
+			summary.artifactId !== undefined ||
+			artifactFailureDiagnostic !== undefined ||
+			artifactTruncatedBytes !== undefined;
+		if (!summary.truncated && !hasArtifactEvidence) return this;
 
 		const { direction, startLine = 1, totalFileLines, noticeOwner } = options;
 		const totalLines = totalFileLines ?? summary.totalLines;
-		const owner = noticeOwner !== undefined ? { noticeOwner } : {};
+		const bodyHasArtifact =
+			summary.artifactId !== undefined && summary.output.includes(`artifact://${summary.artifactId}`);
+		const bodyOwnsArtifact =
+			bodyHasArtifact &&
+			(artifactTruncatedBytes === undefined ||
+				(summary.artifactId !== undefined &&
+					summary.output.includes(formatArtifactReference(summary.artifactId, artifactTruncatedBytes))));
+		const owner =
+			noticeOwner !== undefined ? { noticeOwner } : bodyOwnsArtifact ? { noticeOwner: "body" as const } : {};
 
 		// Middle elision: the sink retained head + tail with an elision marker.
 		if (summary.elidedBytes != null && summary.elidedBytes > 0) {
@@ -350,6 +371,8 @@ export class OutputMetaBuilder {
 				elidedBytes: summary.elidedBytes,
 				elidedLines,
 				artifactId: summary.artifactId,
+				artifactTruncatedBytes,
+				artifactFailureDiagnostic,
 			};
 			return this;
 		}
@@ -382,6 +405,8 @@ export class OutputMetaBuilder {
 			outputBytes: summary.outputBytes,
 			shownRange: { start: shownStart, end: shownEnd },
 			artifactId: summary.artifactId,
+			artifactTruncatedBytes,
+			artifactFailureDiagnostic,
 			nextOffset: direction === "head" ? shownEnd + 1 : undefined,
 		};
 
@@ -524,6 +549,37 @@ export function formatFullOutputReference(artifactId: string): string {
 	return `Read artifact://${artifactId} for full output`;
 }
 
+/**
+ * Format an artifact reference without claiming completeness when storage was hard-capped.
+ */
+export function formatArtifactReference(artifactId: string, artifactTruncatedBytes?: number): string {
+	if (artifactTruncatedBytes != null && artifactTruncatedBytes > 0) {
+		return `Read artifact://${artifactId} for retained output (at least ${formatBytes(artifactTruncatedBytes)} omitted by the artifact storage cap)`;
+	}
+	return formatFullOutputReference(artifactId);
+}
+
+function formatTruncationArtifactNotice(truncation: TruncationMeta): string {
+	const reference = truncation.artifactId
+		? formatArtifactReference(truncation.artifactId, truncation.artifactTruncatedBytes)
+		: undefined;
+	if (truncation.artifactFailureDiagnostic) {
+		const failure = `Artifact storage failed: ${truncation.artifactFailureDiagnostic}`;
+		if (reference) return `${reference}; ${failure}`;
+		return failure;
+	}
+	if (reference) return reference;
+	return `Artifact storage omitted at least ${formatBytes(truncation.artifactTruncatedBytes ?? 0)}; no artifact reference is available`;
+}
+
+function hasArtifactNotice(truncation: TruncationMeta): boolean {
+	return (
+		truncation.artifactId != null ||
+		(truncation.artifactTruncatedBytes ?? 0) > 0 ||
+		truncation.artifactFailureDiagnostic != null
+	);
+}
+
 function formatTruncationRangeTotal(truncation: TruncationMeta): string {
 	return truncation.rangeBase === "window"
 		? `the selected ${truncation.totalLines}-line range`
@@ -537,8 +593,8 @@ export function formatTruncationMetaNotice(truncation: TruncationMeta): string {
 		if (truncation.partialLine.sourceBytes > truncation.partialLine.bytes) {
 			notice += ` (line is ${formatBytes(truncation.partialLine.sourceBytes)})`;
 		}
-		if (truncation.artifactId != null) {
-			notice += `. ${formatFullOutputReference(truncation.artifactId)}`;
+		if (hasArtifactNotice(truncation)) {
+			notice += `. ${formatTruncationArtifactNotice(truncation)}`;
 		}
 		return notice;
 	}
@@ -553,13 +609,15 @@ export function formatTruncationMetaNotice(truncation: TruncationMeta): string {
 		const elidedLines = truncation.elidedLines ?? Math.max(0, totalLines - truncation.outputLines);
 		const headPart = head ? `lines ${head.start}-${head.end}` : "";
 		const tailPart = tail ? `${tail.start}-${tail.end}` : "";
-		if (headPart && tailPart) {
+		if (head && tail && elidedLines === 0 && head.start === tail.start && head.end === tail.end) {
+			notice = `Showing head and tail of line ${head.start} of ${rangeTotal}; ${formatBytes(elidedBytes)} middle bytes elided`;
+		} else if (headPart && tailPart) {
 			notice = `Showing ${headPart} and ${tailPart} of ${rangeTotal}; ${elidedLines.toLocaleString()} middle line${elidedLines === 1 ? "" : "s"} (${formatBytes(elidedBytes)}) elided`;
 		} else {
-			notice = `Showing ${truncation.outputLines} of ${rangeTotal}${truncation.rangeBase === "window" ? "" : " lines"}; middle elided`;
+			notice = `Showing ${truncation.outputLines} of ${rangeTotal}${truncation.rangeBase === "window" ? "" : " lines"}; ${formatBytes(elidedBytes)} middle bytes elided`;
 		}
-		if (truncation.artifactId != null) {
-			notice += `. ${formatFullOutputReference(truncation.artifactId)}`;
+		if (hasArtifactNotice(truncation)) {
+			notice += `. ${formatTruncationArtifactNotice(truncation)}`;
 		}
 		return notice;
 	}
@@ -580,8 +638,8 @@ export function formatTruncationMetaNotice(truncation: TruncationMeta): string {
 		notice += `. Use :${truncation.nextOffset} to continue`;
 	}
 
-	if (truncation.artifactId != null) {
-		notice += `. ${formatFullOutputReference(truncation.artifactId)}`;
+	if (hasArtifactNotice(truncation)) {
+		notice += `. ${formatTruncationArtifactNotice(truncation)}`;
 	}
 
 	return notice;
@@ -642,8 +700,25 @@ export function formatOutputNotice(meta: OutputMeta | undefined): string {
  * Returns null if no truncation metadata present.
  */
 export function formatStyledTruncationWarning(meta: OutputMeta | undefined, theme: Theme): string | null {
-	if (!meta?.truncation) return null;
-	const message = formatTruncationMetaNotice(meta.truncation);
+	const truncation = meta?.truncation;
+	if (!truncation) return null;
+	if (
+		truncation.noticeOwner === "body" &&
+		truncation.totalBytes === truncation.outputBytes &&
+		truncation.totalLines === truncation.outputLines
+	) {
+		return null;
+	}
+	const warningMeta =
+		truncation.noticeOwner === "body"
+			? {
+					...truncation,
+					artifactId: undefined,
+					artifactTruncatedBytes: undefined,
+					artifactFailureDiagnostic: undefined,
+				}
+			: truncation;
+	const message = formatTruncationMetaNotice(warningMeta);
 	return theme.fg("warning", wrapBrackets(message, theme));
 }
 
@@ -735,6 +810,25 @@ export function resolveOutputSinkHeadBytes(s: Settings | undefined): number {
 	return getSpillConfig(s).headBytes;
 }
 
+export const BASH_DEFAULT_OUTPUT_TAIL_BYTES = 1024;
+
+/**
+ * Bash uses a deliberately small tail window to nudge callers toward focused
+ * commands and dedicated search tools. An explicitly configured shared tail
+ * budget still wins.
+ */
+export function resolveBashOutputSinkTailBytes(s: Settings): number {
+	return s.has("tools.artifactTailBytes") ? s.get("tools.artifactTailBytes") * 1024 : BASH_DEFAULT_OUTPUT_TAIL_BYTES;
+}
+/**
+ * Bash keeps only the tail unless the user explicitly opts into the shared
+ * head-retention setting. Schema defaults still apply to other streaming
+ * tools without silently turning Bash back into middle-elision mode.
+ */
+export function resolveBashOutputSinkHeadBytes(s: Settings): number {
+	return s.has("tools.artifactHeadBytes") ? resolveOutputSinkHeadBytes(s) : 0;
+}
+
 /**
  * Resolve the per-line column cap from session settings. Shared by streaming
  * executors (bash/python/ssh/eval via OutputSink) and the `read` tool's

package/src/tools/path-utils.ts

@@ -637,6 +637,7 @@ export interface ToolScopeOptions {
 	rawPaths: string[];
 	cwd: string;
 	getArtifactsDir?: () => string | null;
+	getAuthorizedArtifactsDirs?: () => readonly string[];
 	/** Verb used in the "Cannot {action} internal URL without a backing file: …" message. */
 	internalUrlAction: string;
 	/** Collect absolute paths flagged immutable by their internal-URL handler. */
@@ -667,7 +668,7 @@ export interface ToolScopeResolution {
  *  5. stat the resolved base path so callers can branch on directory vs file scope.
  */
 export async function resolveToolSearchScope(opts: ToolScopeOptions): Promise<ToolScopeResolution> {
-	const { rawPaths: inputs, cwd, internalUrlAction, getArtifactsDir } = opts;
+	const { rawPaths: inputs, cwd, internalUrlAction, getArtifactsDir, getAuthorizedArtifactsDirs } = opts;
 	const rawPaths = inputs.map(normalizePathLikeInput);
 	if (rawPaths.some(rawPath => rawPath.length === 0)) {
 		throw new ToolError("`paths` must contain non-empty paths or globs");
@@ -683,7 +684,7 @@ export async function resolveToolSearchScope(opts: ToolScopeOptions): Promise<To
 		if (hasGlobPathChars(rawPath)) {
 			throw new ToolError(`Glob patterns are not supported for internal URLs: ${rawPath}`);
 		}
-		const resource = await internalRouter.resolve(rawPath, { cwd, getArtifactsDir });
+		const resource = await internalRouter.resolve(rawPath, { cwd, getArtifactsDir, getAuthorizedArtifactsDirs });
 		if (!resource.sourcePath) {
 			throw new ToolError(`Cannot ${internalUrlAction} internal URL without a backing file: ${rawPath}`);
 		}

package/src/tools/read.ts

@@ -1419,6 +1419,21 @@ interface ResolvedSqliteReadPath {
  * Reads files with support for images, converted documents (via markit), and text.
  * Directories return a formatted listing with modification times.
  */
+/**
+ * A client-authority denial is a decision, not a transport failure: falling back to
+ * disk would bypass the permission the client just refused. Availability failures
+ * still fall back so an unreachable bridge cannot break local reads.
+ */
+function isClientAuthorityDenial(error: unknown): boolean {
+	const code =
+		typeof error === "object" && error !== null && "code" in error ? (error as { code?: unknown }).code : undefined;
+	// ACP clients surface refusals as an application error; -32001 is the reserved
+	// client-authority denial code and -32603 covers hosts without a dedicated code.
+	if (code === "permission_denied" || code === "forbidden" || code === -32001 || code === -32603) return true;
+	const message = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+	return /permission denied|not permitted|access denied|forbidden/i.test(message);
+}
+
 export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 	readonly name = "read";
 	readonly label = "Read";
@@ -1991,6 +2006,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 				}
 				return { outputText: "", contentLineCount: 0, columnTruncated: 0, bridgeResult };
 			} catch (error) {
+				if (isClientAuthorityDenial(error)) throw error;
 				logger.warn("ACP fs readTextFile failed; falling back to disk", { path: absolutePath, error });
 			}
 		}
@@ -2893,6 +2909,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 							}
 							return bridgeResult;
 						} catch (error) {
+							if (isClientAuthorityDenial(error)) throw error;
 							logger.warn("ACP fs readTextFile failed; falling back to disk", { path: absolutePath, error });
 						}
 					}
@@ -3396,6 +3413,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		const resource = await internalRouter.resolve(url, {
 			cwd: this.session.cwd,
 			getArtifactsDir: this.session.getArtifactsDir,
+			getAuthorizedArtifactsDirs: this.session.getAuthorizedArtifactsDirs,
 			settings: this.session.settings,
 			signal,
 		});

package/src/tools/review.ts

@@ -188,15 +188,13 @@ export interface SubmitReviewDetails {
 // Re-export types for external use
 export type { ReportFindingDetails };
 /**
- * Coerce a tool-side `ReportFindingDetails` into the cross-boundary
- * `ReviewFinding` shape consumed by the reviewer agent's JTD output schema.
+ * Convert tool-side `ReportFindingDetails` into the numeric-priority
+ * `ReviewFinding` shape used by caller-owned reviewer payloads.
  *
  * The `report_finding` tool exposes `priority` as a string enum (`"P0".."P3"`)
- * for ergonomics, but the bundled reviewer schema (and every custom review
- * agent that mirrors it) declares `priority: number`. Without this coercion
- * the auto-populated `findings[]` fails JTD validation and every review run
- * that surfaces a finding is rejected with `findings.0.priority: expected
- * number, received string`.
+ * for ergonomics, while reviewer schemas may explicitly declare numeric
+ * priorities. This pure conversion does not add findings to completion data;
+ * callers that include `findings` own both that field and its output schema.
  */
 export function toReviewFinding(details: ReportFindingDetails): ReviewFinding {
 	return {

package/src/tools/search.ts

@@ -287,6 +287,7 @@ export class SearchTool implements AgentTool<typeof searchSchema, SearchToolDeta
 					rawPaths: resolvedPaths,
 					cwd: this.session.cwd,
 					getArtifactsDir: this.session.getArtifactsDir,
+					getAuthorizedArtifactsDirs: this.session.getAuthorizedArtifactsDirs,
 					internalUrlAction: "search",
 					trackImmutableSources: true,
 					surfaceExactFilePaths: true,

package/src/tools/subagent-render.ts

@@ -192,6 +192,9 @@ function renderSubagentSnapshotBody(
 	}
 	if (snapshot.description) lines.push(`  ${theme.fg("dim", `Description: ${snapshot.description}`)}`);
 	if (snapshot.outputRef) lines.push(`  ${theme.fg("dim", `Output: ${snapshot.outputRef}`)}`);
+	if (snapshot.setupFailureSummary) {
+		lines.push(`  ${theme.fg("error", `Setup failure: ${snapshot.setupFailureSummary}`)}`);
+	}
 	if (snapshot.assignment) {
 		lines.push(`  ${theme.fg("dim", "Assignment:")}`);
 		for (const al of snapshot.assignment.split("\n")) lines.push(`    ${theme.fg("toolOutput", replaceTabs(al))}`);
@@ -312,8 +315,9 @@ export const subagentToolRenderer = {
 					);
 				}
 
-				snapshotSignatures ??= subagents.map(snapshot =>
-					subagentAwaitRenderedStateSignature([snapshot], result.details),
+				snapshotSignatures ??= subagents.map(
+					snapshot =>
+						`${subagentAwaitRenderedStateSignature([snapshot], result.details)}:${snapshot.setupFailureSummary ?? ""}`,
 				);
 				subagents.forEach((snapshot, index) => {
 					// Fresh per-subagent status line (cheap), then a cached or dynamic body.

package/src/tools/subagent.ts

@@ -65,6 +65,8 @@ export interface SubagentSnapshot {
 	durationMs: number;
 	resultText?: string;
 	errorText?: string;
+	/** Safe setup failure cause retained from the executor launch path. */
+	setupFailureSummary?: string;
 	resultPreview?: string;
 	outputRef?: string;
 	truncated?: boolean;
@@ -603,6 +605,7 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 			}
 			if (snapshot.description) lines.push(`Description: ${snapshot.description}`);
 			if (snapshot.outputRef) lines.push(`Output: ${snapshot.outputRef}`);
+			if (snapshot.setupFailureSummary) lines.push(`Setup failure: ${snapshot.setupFailureSummary}`);
 			if (snapshot.assignment) lines.push("Assignment:", "```", snapshot.assignment, "```");
 			if (snapshot.steerMessage) {
 				lines.push(`Steer (${snapshot.steerState ?? "queued"}):`, "```", snapshot.steerMessage, "```");
@@ -731,6 +734,9 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 						truncated: output.truncated,
 					}
 				: {}),
+			...(job.setupFailureSummary
+				? { setupFailureSummary: sanitizeText(job.setupFailureSummary, RECEIPT_PREVIEW_WIDTH) }
+				: {}),
 			...(outputRef ? { outputRef } : {}),
 			...(runningTimeoutGuidance ? { guidance: runningTimeoutGuidance } : {}),
 			...this.#modelFields(record),

package/src/tools/telegram-send.ts

@@ -31,8 +31,10 @@ export class TelegramSendTool implements AgentTool<typeof telegramSendSchema, Te
 	readonly summary = "Send a workspace file to Telegram";
 	readonly loadMode = "discoverable";
 	readonly description =
-		"Send a file from the current workspace to the connected Telegram chat as a document. The path must resolve " +
-		"(after following symlinks) to a regular file inside the project root; paths outside the workspace are rejected.";
+		"Send a file from the current workspace to the connected Telegram chat. Recognized images are converted to " +
+		"Telegram-compatible photos when possible, including WebP; other files are sent as documents with their MIME " +
+		"type preserved. The path must resolve (after following symlinks) to a regular file inside the project root; " +
+		"paths outside the workspace are rejected.";
 	readonly parameters = telegramSendSchema;
 	readonly strict = true;
 
@@ -109,6 +111,7 @@ export class TelegramSendTool implements AgentTool<typeof telegramSendSchema, Te
 			};
 		}
 		const abs = contained.path;
+		const mime = Bun.file(abs).type;
 
 		const sink = getTelegramFileSink(sessionId);
 		if (!sink) {
@@ -126,7 +129,7 @@ export class TelegramSendTool implements AgentTool<typeof telegramSendSchema, Te
 			};
 		}
 
-		const result = await sink({ path: abs, caption: params.caption });
+		const result = await sink({ path: abs, caption: params.caption, mime });
 		if (result.ok) {
 			return {
 				content: [{ type: "text", text: `Sent ${path.basename(abs)} to Telegram.` }],

package/src/utils/gh.ts

@@ -0,0 +1,39 @@
+const DEFAULT_GH_TIMEOUT_MS = 5_000;
+
+export interface GhResult {
+	exitCode: number;
+	stdout: string;
+	stderr: string;
+	timedOut?: boolean;
+}
+
+export type RunGh = (args: string[], options?: { timeoutMs?: number }) => Promise<GhResult>;
+
+/** Run GitHub CLI without allowing it to consume the parent terminal's input. */
+export async function runGhDefault(args: string[], options?: { timeoutMs?: number }): Promise<GhResult> {
+	const ghPath = Bun.which("gh");
+	if (!ghPath) {
+		return { exitCode: -1, stdout: "", stderr: "gh not found", timedOut: false };
+	}
+	const timeoutMs = options?.timeoutMs ?? DEFAULT_GH_TIMEOUT_MS;
+	let timedOut = false;
+	try {
+		const proc = Bun.spawn([ghPath, ...args], { stdout: "pipe", stderr: "pipe", stdin: "ignore" });
+		const timer = setTimeout(() => {
+			timedOut = true;
+			proc.kill();
+		}, timeoutMs);
+		try {
+			const [stdout, stderr] = await Promise.all([
+				new Response(proc.stdout).text(),
+				new Response(proc.stderr).text(),
+			]);
+			const exitCode = await proc.exited;
+			return { exitCode, stdout, stderr, timedOut };
+		} finally {
+			clearTimeout(timer);
+		}
+	} catch (err) {
+		return { exitCode: -1, stdout: "", stderr: err instanceof Error ? err.message : String(err), timedOut };
+	}
+}

package/src/utils/image-resize.ts

@@ -6,6 +6,7 @@ export interface ImageResizeOptions {
 	maxBytes?: number;
 	jpegQuality?: number;
 	excludeWebP?: boolean;
+	forceReencode?: boolean;
 }
 
 export interface ResizedImage {
@@ -30,6 +31,7 @@ const DEFAULT_OPTIONS: Required<Omit<ImageResizeOptions, "excludeWebP">> = {
 	maxHeight: 1568,
 	maxBytes: DEFAULT_IMAGE_RESIZE_MAX_BYTES,
 	jpegQuality: 80,
+	forceReencode: false,
 };
 
 /**
@@ -94,6 +96,7 @@ export async function resizeImageBuffer(
 			originalWidth <= opts.maxWidth &&
 			originalHeight <= opts.maxHeight &&
 			originalSize <= comfortableSize &&
+			!opts.forceReencode &&
 			!(opts.excludeWebP && sourceMime === "image/webp")
 		) {
 			return {

package/src/web/search/providers/anthropic.ts

@@ -14,7 +14,7 @@ import {
 	buildAnthropicUrl,
 	stripClaudeToolPrefix,
 } from "@gajae-code/ai";
-import { $env } from "@gajae-code/utils";
+import { $credentialEnv, $env } from "@gajae-code/utils";
 import type {
 	AnthropicApiResponse,
 	AnthropicCitation,
@@ -275,8 +275,8 @@ export async function searchAnthropic(
 	params: SearchParams | AnthropicSearchParams,
 	_legacyStorage?: unknown,
 ): Promise<SearchResponse> {
-	const searchApiKey = $env.ANTHROPIC_SEARCH_API_KEY;
-	const searchBaseUrl = $env.ANTHROPIC_SEARCH_BASE_URL;
+	const searchApiKey = $credentialEnv("ANTHROPIC_SEARCH_API_KEY");
+	const searchBaseUrl = $credentialEnv("ANTHROPIC_SEARCH_BASE_URL");
 	let auth: AnthropicAuthConfig | undefined;
 	// When reusing the active model's own credentials (native search over a
 	// proxy), prefer its wire model id and carry its request headers through.
@@ -360,7 +360,7 @@ export class AnthropicProvider extends SearchProvider {
 	readonly label = "Anthropic";
 
 	isAvailable(authStorage: AuthStorage): Promise<boolean> | boolean {
-		return Boolean($env.ANTHROPIC_SEARCH_API_KEY) || authStorage.hasAuth("anthropic");
+		return Boolean($credentialEnv("ANTHROPIC_SEARCH_API_KEY")) || authStorage.hasAuth("anthropic");
 	}
 
 	search(params: SearchParams): Promise<SearchResponse> {

package/src/web/search/providers/kimi.ts

@@ -5,7 +5,7 @@
  * Endpoint: POST https://api.kimi.com/coding/v1/search
  */
 import type { AuthStorage } from "@gajae-code/ai";
-import { $env } from "@gajae-code/utils";
+import { $credentialEnv } from "@gajae-code/utils";
 
 import type { SearchResponse, SearchSource } from "../../../web/search/types";
 import { SearchProviderError } from "../../../web/search/types";
@@ -55,8 +55,17 @@ function asTrimmed(value: string | undefined): string | undefined {
 	return trimmed.length > 0 ? trimmed : undefined;
 }
 
+/** Test seam: the Kimi search base URL as resolved from trusted env. */
+export function resolveKimiSearchBaseUrlForTest(): string {
+	return resolveBaseUrl();
+}
+
 function resolveBaseUrl(): string {
-	return asTrimmed($env.MOONSHOT_SEARCH_BASE_URL) ?? asTrimmed($env.KIMI_SEARCH_BASE_URL) ?? KIMI_SEARCH_URL;
+	return (
+		asTrimmed($credentialEnv("MOONSHOT_SEARCH_BASE_URL")) ??
+		asTrimmed($credentialEnv("KIMI_SEARCH_BASE_URL")) ??
+		KIMI_SEARCH_URL
+	);
 }
 
 /** Find Kimi search credentials from environment or AuthStorage. */
@@ -65,7 +74,8 @@ async function findApiKey(
 	sessionId: string | undefined,
 	signal: AbortSignal | undefined,
 ): Promise<string | null> {
-	const envKey = asTrimmed($env.MOONSHOT_SEARCH_API_KEY) ?? asTrimmed($env.KIMI_SEARCH_API_KEY);
+	const envKey =
+		asTrimmed($credentialEnv("MOONSHOT_SEARCH_API_KEY")) ?? asTrimmed($credentialEnv("KIMI_SEARCH_API_KEY"));
 	if (envKey) return envKey;
 
 	return (
@@ -157,8 +167,8 @@ export class KimiProvider extends SearchProvider {
 
 	isAvailable(authStorage: AuthStorage): boolean {
 		return (
-			!!asTrimmed($env.MOONSHOT_SEARCH_API_KEY) ||
-			!!asTrimmed($env.KIMI_SEARCH_API_KEY) ||
+			!!asTrimmed($credentialEnv("MOONSHOT_SEARCH_API_KEY")) ||
+			!!asTrimmed($credentialEnv("KIMI_SEARCH_API_KEY")) ||
 			authStorage.hasAuth("moonshot") ||
 			authStorage.hasAuth("kimi-code")
 		);