@oh-my-pi/pi-coding-agent 15.12.4 → 15.13.0

package/src/tools/manage-skill.ts

@@ -0,0 +1,104 @@
+import * as path from "node:path";
+import type { AgentTool, AgentToolResult } from "@oh-my-pi/pi-agent-core";
+import { z } from "zod/v4";
+import {
+	deleteManagedSkill,
+	getManagedSkillsDir,
+	sanitizeSkillName,
+	writeManagedSkill,
+} from "../autolearn/managed-skills";
+import { isNameClaimedByAuthoredSkill } from "../extensibility/skills";
+import manageSkillDescription from "../prompts/tools/manage-skill.md" with { type: "text" };
+import type { ToolSession } from ".";
+
+const manageSkillSchema = z
+	.object({
+		action: z.enum(["create", "update", "delete"]),
+		name: z.string().describe("kebab-case skill name"),
+		description: z
+			.string()
+			.describe("one-line description of when to use the skill (required for create/update)")
+			.optional(),
+		body: z
+			.string()
+			.describe("the SKILL.md body in markdown, no frontmatter (required for create/update)")
+			.optional(),
+	})
+	// Enforce the action/field contract at validation time rather than only in
+	// execute. Kept as a cross-field refine (not a discriminated union) so the
+	// wire schema stays a single root object — strict structured-output mode and
+	// the Anthropic tool-schema builder both require that.
+	.refine(p => p.action === "delete" || (p.description !== undefined && p.body !== undefined), {
+		message: '"create" and "update" require both "description" and "body".',
+		path: ["description"],
+	});
+
+export type ManageSkillParams = z.infer<typeof manageSkillSchema>;
+
+/**
+ * Direct create/update/delete of isolated managed skills. Gated behind
+ * `autolearn.enabled`; backend-independent (the skill side is standalone).
+ */
+export class ManageSkillTool implements AgentTool<typeof manageSkillSchema> {
+	readonly name = "manage_skill";
+	readonly approval = "write" as const;
+	readonly label = "Manage Skill";
+	readonly description = manageSkillDescription;
+	readonly parameters = manageSkillSchema;
+	readonly strict = true;
+	readonly loadMode = "essential" as const;
+	readonly summary = "Create, update, or delete an isolated managed skill";
+
+	// No session state needed: createIf reads settings; writes target the
+	// home-based managed-skills dir directly.
+	static createIf(session: ToolSession): ManageSkillTool | null {
+		if (!session.settings.get("autolearn.enabled")) return null;
+		return new ManageSkillTool();
+	}
+
+	async execute(_id: string, params: ManageSkillParams): Promise<AgentToolResult> {
+		if (params.action === "delete") {
+			await deleteManagedSkill(params.name);
+			return {
+				content: [{ type: "text", text: `Deleted managed skill "${params.name}".` }],
+				details: { action: "delete", name: params.name },
+			};
+		}
+
+		// Defensive narrowing: the schema refine already rejects create/update
+		// without both fields, so this is unreachable for valid input — it only
+		// proves the strings are present to `writeManagedSkill`'s typed contract.
+		if (!params.description || !params.body) {
+			throw new Error(`"${params.action}" requires both "description" and "body".`);
+		}
+		// A managed skill resolves below any authored skill of the same name
+		// (authored always wins in discovery), so creating one under a name an
+		// authored skill already claims writes a file that never surfaces. Refuse
+		// up front rather than report a false "Created". `sanitizeSkillName`
+		// normalizes to the on-disk name the discovery scan compares against.
+		if (params.action === "create" && isNameClaimedByAuthoredSkill(sanitizeSkillName(params.name))) {
+			return {
+				content: [
+					{
+						type: "text",
+						text: `Cannot create managed skill "${params.name}": an authored skill of that name already exists, and managed skills cannot override authored ones. Choose a different name.`,
+					},
+				],
+				isError: true,
+				details: { action: "create", name: params.name, shadowed: true },
+			};
+		}
+		const { path: skillPath } = await writeManagedSkill({
+			action: params.action,
+			name: params.name,
+			description: params.description,
+			body: params.body,
+		});
+		const relativePath = path.relative(getManagedSkillsDir(), skillPath);
+		const verb = params.action === "create" ? "Created" : "Updated";
+		return {
+			content: [{ type: "text", text: `${verb} managed skill "${params.name}" (managed-skills/${relativePath}).` }],
+			details: { action: params.action, name: params.name },
+		};
+	}
+}

package/src/tools/plan-mode-guard.ts

@@ -1,5 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { HL_FILE_HASH_LENGTH, HL_FILE_HASH_SEP, HL_FILE_PREFIX, HL_FILE_SUFFIX } from "@oh-my-pi/hashline";
 import { resolveLocalRoot, resolveLocalUrlToPath, resolveVaultUrlToPath } from "../internal-urls";
 import type { ToolSession } from ".";
 import { normalizeLocalScheme, resolveToCwd } from "./path-utils";
@@ -7,6 +8,7 @@ import { ToolError } from "./tool-errors";
 
 const VAULT_SCHEME_PREFIX = "vault:";
 const LOCAL_SCHEME_PREFIX = "local:";
+const HL_TRAILING_TAG_RE = new RegExp(`${HL_FILE_HASH_SEP}[0-9A-Fa-f]{${HL_FILE_HASH_LENGTH}}$`);
 
 /** Resolve the absolute path of the session's `local://` artifact sandbox.
  *  Returns `null` when the session has no artifact wiring (e.g. tests). */
@@ -30,29 +32,57 @@ function isWithinRoot(absolutePath: string, root: string): boolean {
 	return absolutePath.startsWith(sep);
 }
 
-/** True when `targetPath` addresses the session-local artifact sandbox.
- *  Accepts both `local://…` URLs and absolute paths pointing inside the
- *  resolved sandbox root — the latter is what `read local://…` echoes back
- *  in the `[path#tag]` header. Those files are not part of the working tree,
- *  so plan mode treats them as freely writable scratch/plan space. */
+/** Strip the hashline `[path#TAG]` wrapper from a write/edit target so the inner
+ *  filesystem path drives both authorization and resolution. Only unwraps inputs
+ *  that match the strict hashline header shape (`[path]` or `[path#XXXX]` with a
+ *  4-hex tag); anything else returns the original string so the downstream
+ *  resolver surfaces the real error. Exported for callers (e.g. `write`) that
+ *  make scheme/bridge-routing decisions before {@link resolvePlanPath} runs. */
+export function unwrapHashlineHeaderPath(targetPath: string): string {
+	const trimmed = targetPath.trimEnd();
+	if (
+		trimmed.length < HL_FILE_PREFIX.length + HL_FILE_SUFFIX.length ||
+		trimmed[0] !== HL_FILE_PREFIX ||
+		trimmed[trimmed.length - 1] !== HL_FILE_SUFFIX
+	) {
+		return targetPath;
+	}
+	const inner = trimmed.slice(HL_FILE_PREFIX.length, trimmed.length - HL_FILE_SUFFIX.length);
+	const tagMatch = HL_TRAILING_TAG_RE.exec(inner);
+	const pathPart = tagMatch ? inner.slice(0, tagMatch.index) : inner;
+	// A valid header is exactly `PATH` or `PATH#XXXX`; reject any other shape
+	// (selectors, non-hex tags, embedded `#`) so we never silently rewrite a
+	// path the model did not author.
+	if (pathPart.length === 0 || pathPart.includes(HL_FILE_HASH_SEP)) return targetPath;
+	return pathPart;
+}
+
+/** True when `targetPath` resolves into the session-local artifact sandbox.
+ *  Routes through {@link resolvePlanPath} so the guard and the eventual write
+ *  always agree on the absolute target (including bracketed hashline headers,
+ *  `local://` URLs, and bare absolute paths). Files inside the sandbox are not
+ *  part of the working tree, so plan mode treats them as freely writable
+ *  scratch/plan space. */
 function targetsLocalSandbox(session: ToolSession, targetPath: string): boolean {
-	const normalized = normalizeLocalScheme(targetPath);
-	if (normalized.startsWith(LOCAL_SCHEME_PREFIX)) return true;
-	if (!path.isAbsolute(normalized)) return false;
 	const root = localSandboxRoot(session);
 	if (!root) return false;
-	// Compare both raw and realpath-normalized forms so that
-	// `/tmp/…` vs `/private/tmp/…` (macOS) and other symlink-collapsed
-	// roots both resolve to the same sandbox identity.
-	const resolved = path.resolve(normalized);
-	if (isWithinRoot(resolved, root)) return true;
+	let resolved: string;
+	try {
+		resolved = resolvePlanPath(session, targetPath);
+	} catch {
+		return false;
+	}
+	if (!path.isAbsolute(resolved)) return false;
+	const absolute = path.resolve(resolved);
+	if (isWithinRoot(absolute, root)) return true;
+	// Compare realpath-normalized forms so that `/tmp/…` vs `/private/tmp/…`
+	// (macOS) and other symlink-collapsed roots both resolve to the same
+	// sandbox identity.
 	try {
 		const realRoot = fs.realpathSync.native(root);
-		if (isWithinRoot(resolved, realRoot)) return true;
-		// `resolved` itself may live in `/tmp/...` while `realRoot` is `/private/tmp/...`;
-		// realpath the parent dir of `resolved` so we catch that direction too.
-		const realParent = fs.realpathSync.native(path.dirname(resolved));
-		return isWithinRoot(path.join(realParent, path.basename(resolved)), realRoot);
+		if (isWithinRoot(absolute, realRoot)) return true;
+		const realParent = fs.realpathSync.native(path.dirname(absolute));
+		return isWithinRoot(path.join(realParent, path.basename(absolute)), realRoot);
 	} catch {
 		return false;
 	}
@@ -61,9 +91,13 @@ function targetsLocalSandbox(session: ToolSession, targetPath: string): boolean
 /**
  * Resolve a write/edit target to its absolute filesystem path, honoring the
  * `local://` and `vault://` schemes. Plain paths resolve against the session cwd.
+ * Bracketed hashline headers (`[path#TAG]`) are unwrapped first so the inner
+ * filesystem path drives resolution — keeping the plan-mode guard and the
+ * eventual write in lockstep.
  */
 export function resolvePlanPath(session: ToolSession, targetPath: string): string {
-	const normalized = normalizeLocalScheme(targetPath);
+	const unwrapped = unwrapHashlineHeaderPath(targetPath);
+	const normalized = normalizeLocalScheme(unwrapped);
 	if (normalized.startsWith(LOCAL_SCHEME_PREFIX)) {
 		return resolveLocalUrlToPath(normalized, {
 			getArtifactsDir: session.getArtifactsDir,

package/src/tools/renderers.ts

@@ -44,18 +44,14 @@ export type ToolRenderer = {
 	/** Render without background box, inline in the response flow */
 	inline?: boolean;
 	/**
-	 * Collapsed pending preview is provisional — a tail-window or otherwise
-	 * re-anchored view the result render replaces wholesale (an edit's
-	 * streamed-diff tail, bash/ssh command caps, eval cells whose outputs
-	 * interleave under each cell). Its rows must never commit to native
-	 * scrollback mid-run; see
-	 * `ToolExecutionComponent.isTranscriptBlockCommitStable`. Absent = the
-	 * pending preview streams top-anchored append-shaped rows the result
-	 * render preserves (task context/assignment, write content), which stay
-	 * commit-eligible so a call taller than the viewport scrolls into history
-	 * instead of reading as cut off.
+	 * Whether pending-call rows are provisional: useful on screen while a tool is
+	 * streaming, but not durable transcript history. `true` means every pending
+	 * shape is provisional. `"collapsed"` means only the collapsed pending shape
+	 * is provisional; expanded rendering is top-anchored/append-shaped enough to
+	 * let the transcript commit its settled prefix. Absent = the pending preview
+	 * streams rows the result render preserves.
 	 */
-	provisionalPendingPreview?: boolean;
+	provisionalPendingPreview?: boolean | "collapsed";
 };
 
 export const toolRenderers: Record<string, ToolRenderer> = {

package/src/tools/ssh.ts

@@ -346,7 +346,8 @@ export const sshToolRenderer = {
 		});
 	},
 	mergeCallAndResult: true,
-	// Pending preview caps the command to a viewport-sized tail window that
-	// shifts while args stream; keep it out of native scrollback mid-run.
-	provisionalPendingPreview: true,
+	// Collapsed pending preview caps the command to a viewport-sized tail window
+	// that shifts while args stream. Expanded output is top-anchored enough for
+	// the transcript to commit its settled prefix.
+	provisionalPendingPreview: "collapsed",
 };

package/src/tools/todo.ts

@@ -8,7 +8,7 @@ import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme } from "../modes/theme/theme";
 import todoDescription from "../prompts/tools/todo.md" with { type: "text" };
 import type { ToolSession } from "../sdk";
-import type { SessionEntry } from "../session/session-manager";
+import type { SessionEntry } from "../session/session-entries";
 import { framedBlock, renderStatusLine, renderTreeList } from "../tui";
 import { formatErrorDetail, PREVIEW_LIMITS } from "./render-utils";
 

package/src/tools/tts.ts

@@ -1,10 +1,17 @@
 // Ported from NousResearch/hermes-agent (MIT) — tools/tts_tool.py L167-171, L896-959.
+// The xAI Grok Voice path below is preserved intact; a local on-device neural TTS
+// backend (Kokoro-82M via kokoro-js on the shared ONNX worker) is layered on behind
+// the `providers.tts` switch.
 
 import type { AgentToolResult } from "@oh-my-pi/pi-agent-core";
 import { type ApiKey, ProviderHttpError, withAuth } from "@oh-my-pi/pi-ai";
 import { z } from "zod/v4";
+import { settings } from "../config/settings";
 import type { CustomTool, CustomToolContext } from "../extensibility/custom-tools/types";
 import { ohMyPiXAIUserAgent, resolveXAIHttpCredentials } from "../lib/xai-http";
+import { DEFAULT_TTS_LOCAL_MODEL_KEY, DEFAULT_TTS_VOICE, isTtsLocalModelKey, KOKORO_VOICES } from "../tts/models";
+import { ttsClient } from "../tts/tts-client";
+import { encodeWav } from "../tts/wav";
 import { formatPathRelativeToCwd, resolveToCwd } from "./path-utils";
 
 // Hermes tts_tool.py L167-171
@@ -22,6 +29,7 @@ const formatVoiceList = (): string =>
 	XAI_BUILTIN_VOICES.map(v => (v === DEFAULT_XAI_VOICE_ID ? `${v} (default)` : v)).join(", ");
 
 type TtsCodec = "mp3" | "wav";
+type TtsBackend = "local" | "xai";
 
 const ttsSchema = z.object({
 	text: z.string().min(1).max(XAI_MAX_TEXT_LENGTH),
@@ -36,16 +44,200 @@ interface TtsToolDetails {
 	bytes: number;
 	voiceId: string;
 	codec: TtsCodec;
+	backend: TtsBackend;
+}
+
+/**
+ * Pick the synthesis backend. Pure for testability.
+ *
+ * - `xai` / `local` are honored verbatim (the xAI path still surfaces its own
+ *   "no credentials" error when creds are missing).
+ * - `auto` prefers the local on-device backend, except when the caller asked for
+ *   an `.mp3` and xAI credentials exist — only the cloud path can emit MP3, so we
+ *   route there to satisfy the requested container rather than substituting WAV.
+ */
+export function resolveTtsBackend(opts: { preference: string; wantsMp3: boolean; hasXaiCreds: boolean }): TtsBackend {
+	if (opts.preference === "xai") return "xai";
+	if (opts.preference === "local") return "local";
+	if (opts.wantsMp3 && opts.hasXaiCreds) return "xai";
+	return "local";
+}
+
+/**
+ * Resolve the on-disk path for local synthesis. Local output is always WAV (no
+ * MP3 encoder is bundled), so an `.mp3` (or any non-`.wav`) request is rewritten
+ * to a sibling `.wav` and flagged so the tool result can note the substitution.
+ */
+export function resolveLocalWavPath(outputPath: string): { wavPath: string; substituted: boolean } {
+	const lower = outputPath.toLowerCase();
+	if (lower.endsWith(".wav")) return { wavPath: outputPath, substituted: false };
+	const slash = Math.max(outputPath.lastIndexOf("/"), outputPath.lastIndexOf("\\"));
+	const dot = outputPath.lastIndexOf(".");
+	const base = dot > slash ? outputPath.slice(0, dot) : outputPath;
+	return { wavPath: `${base}.wav`, substituted: true };
+}
+
+function readStringSetting(key: "providers.tts" | "tts.localModel" | "tts.localVoice"): string | undefined {
+	try {
+		const value = settings.get(key);
+		return typeof value === "string" ? value : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+async function synthesizeXai(
+	params: z.infer<typeof ttsSchema>,
+	ctx: CustomToolContext,
+	outputPath: string,
+	displayPath: string,
+	codec: TtsCodec,
+	signal: AbortSignal | undefined,
+): Promise<AgentToolResult<TtsToolDetails, typeof ttsSchema>> {
+	const creds = await resolveXAIHttpCredentials(ctx.modelRegistry);
+	if (!creds) {
+		return {
+			isError: true,
+			content: [
+				{
+					type: "text",
+					text: "No xAI credentials. Run /login → xAI Grok OAuth (SuperGrok Subscription) or set XAI_API_KEY.",
+				},
+			],
+		};
+	}
+
+	const voiceId = params.voice_id;
+	const language = params.language;
+	const sampleRate = params.sample_rate ?? DEFAULT_XAI_SAMPLE_RATE;
+	const bitRate = params.bit_rate ?? DEFAULT_XAI_BIT_RATE;
+
+	const payload: Record<string, unknown> = {
+		text: params.text,
+		voice_id: voiceId,
+		language,
+	};
+	// Hermes tts_tool.py L926-940 — only send output_format when caller overrides a default.
+	const codecOverridden = codec !== "mp3";
+	const sampleRateOverridden = sampleRate !== DEFAULT_XAI_SAMPLE_RATE;
+	const bitRateOverridden = codec === "mp3" && bitRate !== DEFAULT_XAI_BIT_RATE;
+	if (codecOverridden || sampleRateOverridden || bitRateOverridden) {
+		const fmt: Record<string, unknown> = { codec };
+		if (sampleRate) fmt.sample_rate = sampleRate;
+		if (codec === "mp3" && bitRate) fmt.bit_rate = bitRate;
+		payload.output_format = fmt;
+	}
+
+	// Compose the caller signal with a 60 s timeout fence.
+	const timeoutSignal = AbortSignal.timeout(60_000);
+	const combinedSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+
+	const sessionId = ctx.sessionManager.getSessionId();
+	const apiKey: ApiKey = ctx.modelRegistry.resolver(creds.provider, {
+		sessionId,
+		baseUrl: creds.baseURL,
+	});
+
+	let response: Response;
+	try {
+		response = await withAuth(
+			apiKey,
+			async key => {
+				const resp = await fetch(`${creds.baseURL}/tts`, {
+					method: "POST",
+					headers: {
+						Authorization: `Bearer ${key}`,
+						"Content-Type": "application/json",
+						"User-Agent": ohMyPiXAIUserAgent(),
+					},
+					body: JSON.stringify(payload),
+					signal: combinedSignal,
+				});
+				if (!resp.ok) {
+					const detail = await resp.text();
+					throw new ProviderHttpError(`xAI TTS failed (${resp.status}): ${detail.slice(0, 300)}`, resp.status, {
+						headers: resp.headers,
+					});
+				}
+				return resp;
+			},
+			{ signal: combinedSignal },
+		);
+	} catch (error) {
+		const status = (error as { status?: unknown }).status;
+		if (error instanceof Error && typeof status === "number") {
+			return {
+				isError: true,
+				content: [{ type: "text", text: error.message }],
+			};
+		}
+		throw error;
+	}
+	const bytes = new Uint8Array(await response.arrayBuffer());
+	await Bun.write(outputPath, bytes);
+	return {
+		content: [
+			{
+				type: "text",
+				text: `Saved ${bytes.length} bytes to ${displayPath} (voice=${voiceId}, codec=${codec}, backend=xai).`,
+			},
+		],
+		details: { bytes: bytes.length, voiceId, codec, backend: "xai" },
+	};
+}
+
+async function synthesizeLocal(
+	params: z.infer<typeof ttsSchema>,
+	cwd: string,
+	outputPath: string,
+	signal: AbortSignal | undefined,
+): Promise<AgentToolResult<TtsToolDetails, typeof ttsSchema>> {
+	const modelSetting = readStringSetting("tts.localModel");
+	const modelKey = modelSetting && isTtsLocalModelKey(modelSetting) ? modelSetting : DEFAULT_TTS_LOCAL_MODEL_KEY;
+	const voice = readStringSetting("tts.localVoice") || DEFAULT_TTS_VOICE;
+
+	const audio = await ttsClient.synthesize(modelKey, params.text, { voice, signal });
+	if (!audio) {
+		return {
+			isError: true,
+			content: [
+				{
+					type: "text",
+					text: `Local TTS synthesis failed (model=${modelKey}). The on-device worker may be unavailable or the model download was interrupted.`,
+				},
+			],
+		};
+	}
+
+	const { wavPath, substituted } = resolveLocalWavPath(outputPath);
+	const wav = encodeWav(audio.pcm, audio.sampleRate);
+	await Bun.write(wavPath, wav);
+	const displayPath = formatPathRelativeToCwd(wavPath, cwd);
+	const note = substituted
+		? ` No local MP3 encoder is bundled, so WAV (PCM16) was written instead of the requested container.`
+		: "";
+	return {
+		content: [
+			{
+				type: "text",
+				text: `Saved ${wav.length} bytes to ${displayPath} (voice=${modelKey}/${voice}, codec=wav, backend=local, ${audio.sampleRate} Hz).${note}`,
+			},
+		],
+		details: { bytes: wav.length, voiceId: `${modelKey}/${voice}`, codec: "wav", backend: "local" },
+	};
 }
 
 export const ttsTool: CustomTool<typeof ttsSchema, TtsToolDetails> = {
 	name: "tts",
-	label: "TextToSpeech",
+	label: "Speech Generation",
 	strict: false,
 	approval: "write",
 	description:
-		`Synthesize speech from text using xAI Grok Voice. Built-in voices: ${formatVoiceList()}. ` +
-		"Custom voice IDs also accepted. Output codec inferred from output_path suffix (.wav → wav, else mp3). " +
+		"Generate a speech audio file from text and write it to output_path. Two backends, selected by the providers.tts setting (auto|local|xai): " +
+		`local = on-device neural TTS (Kokoro-82M via the bundled ONNX runtime, no network, output is always WAV/PCM16; voice set by the tts.localVoice setting — ${KOKORO_VOICES.map(v => (v.id === DEFAULT_TTS_VOICE ? `${v.id} (default)` : v.id)).join(", ")}); ` +
+		`xai = xAI Grok Voice cloud (built-in voices: ${formatVoiceList()}; custom voice IDs accepted; MP3 or WAV). ` +
+		"auto prefers local, but routes an .mp3 request to xAI when credentials exist (only the cloud path emits MP3); " +
+		"otherwise an .mp3 path is written as a sibling .wav. xAI codec is inferred from the output_path suffix. " +
 		`Max ${XAI_MAX_TEXT_LENGTH.toLocaleString("en-US")} characters.`,
 	parameters: ttsSchema,
 	async execute(
@@ -55,99 +247,18 @@ export const ttsTool: CustomTool<typeof ttsSchema, TtsToolDetails> = {
 		ctx: CustomToolContext,
 		signal?: AbortSignal,
 	): Promise<AgentToolResult<TtsToolDetails, typeof ttsSchema>> {
-		const creds = await resolveXAIHttpCredentials(ctx.modelRegistry);
-		if (!creds) {
-			return {
-				isError: true,
-				content: [
-					{
-						type: "text",
-						text: "No xAI credentials. Run /login → xAI Grok OAuth (SuperGrok Subscription) or set XAI_API_KEY.",
-					},
-				],
-			};
-		}
-
 		const cwd = ctx.sessionManager.getCwd();
 		const outputPath = resolveToCwd(params.output_path, cwd);
 		const displayPath = formatPathRelativeToCwd(outputPath, cwd);
 		const codec: TtsCodec = outputPath.toLowerCase().endsWith(".wav") ? "wav" : "mp3";
-		const voiceId = params.voice_id;
-		const language = params.language;
-		const sampleRate = params.sample_rate ?? DEFAULT_XAI_SAMPLE_RATE;
-		const bitRate = params.bit_rate ?? DEFAULT_XAI_BIT_RATE;
-
-		const payload: Record<string, unknown> = {
-			text: params.text,
-			voice_id: voiceId,
-			language,
-		};
-		// Hermes tts_tool.py L926-940 — only send output_format when caller overrides a default.
-		const codecOverridden = codec !== "mp3";
-		const sampleRateOverridden = sampleRate !== DEFAULT_XAI_SAMPLE_RATE;
-		const bitRateOverridden = codec === "mp3" && bitRate !== DEFAULT_XAI_BIT_RATE;
-		if (codecOverridden || sampleRateOverridden || bitRateOverridden) {
-			const fmt: Record<string, unknown> = { codec };
-			if (sampleRate) fmt.sample_rate = sampleRate;
-			if (codec === "mp3" && bitRate) fmt.bit_rate = bitRate;
-			payload.output_format = fmt;
-		}
 
-		// Compose the caller signal with a 60 s timeout fence.
-		const timeoutSignal = AbortSignal.timeout(60_000);
-		const combinedSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
-
-		const sessionId = ctx.sessionManager.getSessionId();
-		const apiKey: ApiKey = ctx.modelRegistry.resolver(creds.provider, {
-			sessionId,
-			baseUrl: creds.baseURL,
-		});
-
-		let response: Response;
-		try {
-			response = await withAuth(
-				apiKey,
-				async key => {
-					const resp = await fetch(`${creds.baseURL}/tts`, {
-						method: "POST",
-						headers: {
-							Authorization: `Bearer ${key}`,
-							"Content-Type": "application/json",
-							"User-Agent": ohMyPiXAIUserAgent(),
-						},
-						body: JSON.stringify(payload),
-						signal: combinedSignal,
-					});
-					if (!resp.ok) {
-						const detail = await resp.text();
-						throw new ProviderHttpError(`xAI TTS failed (${resp.status}): ${detail.slice(0, 300)}`, resp.status, {
-							headers: resp.headers,
-						});
-					}
-					return resp;
-				},
-				{ signal: combinedSignal },
-			);
-		} catch (error) {
-			const status = (error as { status?: unknown }).status;
-			if (error instanceof Error && typeof status === "number") {
-				return {
-					isError: true,
-					content: [{ type: "text", text: error.message }],
-				};
-			}
-			throw error;
-		}
-		const bytes = new Uint8Array(await response.arrayBuffer());
-		await Bun.write(outputPath, bytes);
-		return {
-			content: [
-				{
-					type: "text",
-					text: `Saved ${bytes.length} bytes to ${displayPath} (voice=${voiceId}, codec=${codec}).`,
-				},
-			],
-			details: { bytes: bytes.length, voiceId, codec },
-		};
+		const preference = readStringSetting("providers.tts") ?? "auto";
+		// Only resolve xAI creds when they can affect routing (skip for an explicit local preference).
+		const hasXaiCreds =
+			preference === "local" ? false : (await resolveXAIHttpCredentials(ctx.modelRegistry)) !== null;
+		const backend = resolveTtsBackend({ preference, wantsMp3: codec === "mp3", hasXaiCreds });
+
+		if (backend === "local") return synthesizeLocal(params, cwd, outputPath, signal);
+		return synthesizeXai(params, ctx, outputPath, displayPath, codec, signal);
 	},
 };

package/src/tools/write.ts

@@ -35,7 +35,7 @@ import {
 import { invalidateFsScanAfterWrite } from "./fs-cache-invalidation";
 import { type OutputMeta, outputMeta } from "./output-meta";
 import { formatPathRelativeToCwd, isInternalUrlPath } from "./path-utils";
-import { enforcePlanModeWrite, resolvePlanPath } from "./plan-mode-guard";
+import { enforcePlanModeWrite, resolvePlanPath, unwrapHashlineHeaderPath } from "./plan-mode-guard";
 import {
 	cachedRenderedString,
 	createRenderedStringCache,
@@ -63,6 +63,7 @@ import { ToolError } from "./tool-errors";
 import { toolResult } from "./tool-result";
 
 const LOOSE_HASHLINE_HEADER_RE = /^\s*\[[^#\r\n]+#[^ \t\r\n]*\]\s*$/;
+const EXECUTABLE_NOTICE = "[Notice: Made executable via chmod +x]";
 
 let fflateModulePromise: Promise<typeof import("fflate")> | undefined;
 async function loadFflate(): Promise<typeof import("fflate")> {
@@ -818,11 +819,20 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 	}
 	async execute(
 		_toolCallId: string,
-		{ path, content }: WriteParams,
+		{ path: rawPath, content }: WriteParams,
 		signal?: AbortSignal,
 		_onUpdate?: AgentToolUpdateCallback<WriteToolDetails>,
 		context?: AgentToolContext,
 	): Promise<AgentToolResult<WriteToolDetails>> {
+		// Strip a hashline `[path#TAG]` wrapper up front so every downstream
+		// decision (scheme routing, internal-URL handler dispatch, plan-mode
+		// guard, plan path resolution, ACP bridge routing) sees the same
+		// filesystem target. Without this, a model that pastes a `read`
+		// header as the `path` arg would slip past `isInternalUrlPath`
+		// (which fails on a leading `[`) and the bridge router would send a
+		// `[local://scratch.md#ABCD]` write to the editor instead of the
+		// session-local sandbox.
+		const path = unwrapHashlineHeaderPath(rawPath);
 		return untilAborted(signal, async () => {
 			// Strip hashline display prefixes ([PATH#HASH] + LINE:) if the model copied them from read output
 			const { text: cleanContent, stripped } = stripWriteContent(this.session, content);
@@ -932,6 +942,9 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 				if (stripped) {
 					resultText += `\nNote: auto-stripped hashline display prefixes from content before writing.`;
 				}
+				if (madeExecutable) {
+					resultText += `\n${EXECUTABLE_NOTICE}`;
+				}
 				return {
 					content: [{ type: "text", text: resultText }],
 					details: { resolvedPath: absolutePath, madeExecutable: madeExecutable || undefined },
@@ -950,6 +963,9 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 			if (stripped) {
 				resultText += `\nNote: auto-stripped hashline display prefixes from content before writing.`;
 			}
+			if (madeExecutable) {
+				resultText += `\n${EXECUTABLE_NOTICE}`;
+			}
 			if (!diagnostics) {
 				return {
 					content: [{ type: "text", text: resultText }],