@f5-sales-demo/xcsh 19.87.1 → 19.89.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "19.87.1",
+	"version": "19.89.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5-sales-demo/xcsh",
 	"author": "Can Boluk",
@@ -56,13 +56,13 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@f5-sales-demo/xcsh-stats": "19.87.1",
-		"@f5-sales-demo/pi-agent-core": "19.87.1",
-		"@f5-sales-demo/pi-ai": "19.87.1",
-		"@f5-sales-demo/pi-natives": "19.87.1",
-		"@f5-sales-demo/pi-resource-management": "19.87.1",
-		"@f5-sales-demo/pi-tui": "19.87.1",
-		"@f5-sales-demo/pi-utils": "19.87.1",
+		"@f5-sales-demo/xcsh-stats": "19.89.0",
+		"@f5-sales-demo/pi-agent-core": "19.89.0",
+		"@f5-sales-demo/pi-ai": "19.89.0",
+		"@f5-sales-demo/pi-natives": "19.89.0",
+		"@f5-sales-demo/pi-resource-management": "19.89.0",
+		"@f5-sales-demo/pi-tui": "19.89.0",
+		"@f5-sales-demo/pi-utils": "19.89.0",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.20",

package/src/browser/chat-handler.ts

@@ -1,4 +1,7 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
 import type { AssistantMessage, ImageContent } from "@f5-sales-demo/pi-ai";
+import { settings } from "../config/settings";
 import { DEFAULT_MODEL_ROLE } from "../config/settings-schema";
 import {
 	isRpcHostToolResult,
@@ -24,11 +27,13 @@ import {
 	isChatRequest,
 	isChatStop,
 	isConfigure,
+	isListSkills,
 	isSetHostTools,
 	type PageContextSnapshot,
 	type SetHostTools,
 	type SetHostToolsAck,
 	type SetHostToolsError,
+	type SkillsList,
 } from "./chat-protocol";
 import { CONSOLE_ROUTES } from "./console-routes.generated";
 import type { BridgeServer } from "./extension-bridge";
@@ -101,6 +106,9 @@ export class ChatHandler {
 			// Provider configuration channel (#2095): swap the LLM provider/model in
 			// session memory at runtime (never persisted), then ack or nack.
 			else if (isConfigure(msg)) this.#handleConfigure(msg as unknown as Configure);
+			// Skills enumeration (#2311): the pane asks for the loaded skills to populate
+			// the composer's Skills submenu.
+			else if (isListSkills(msg)) this.#handleListSkills();
 			else if (isRpcHostToolResult(msg)) this.#hostToolBridge.handleResult(msg as unknown as HostToolResult);
 			else if (isRpcHostToolUpdate(msg)) this.#hostToolBridge.handleUpdate(msg as unknown as HostToolUpdate);
 		});
@@ -164,7 +172,13 @@ export class ChatHandler {
 		});
 		chat.unsubscribe = unsubscribe;
 
-		const prompt = composeChatPrompt(req.text, req.context, req.mode, this.#server.clientHost);
+		// Sanitize the attached paths (absolute, `..`-collapsed, confined to the user's
+		// own space, no control chars) — the engine must not blindly widen its sandbox to
+		// a client-supplied path. Grant the safe set BEFORE composing the prompt so the
+		// model's read/grep/bash calls pass the gate. Session-scoped, in-memory, deduped.
+		const contextPaths = Array.isArray(req.contextPaths) ? sanitizeContextPaths(req.contextPaths) : [];
+		if (contextPaths.length > 0) grantSandboxPaths(contextPaths);
+		const prompt = composeChatPrompt(req.text, req.context, req.mode, this.#server.clientHost, contextPaths);
 		// Photo/image attachments ride as base64 vision blocks (the model is
 		// vision-capable); text attachments are already folded into req.text upstream.
 		const images: ImageContent[] | undefined = req.images?.map(img => ({
@@ -172,10 +186,16 @@ export class ChatHandler {
 			data: img.data,
 			mimeType: img.mimeType,
 		}));
+		// "Search the web" toggle → add Anthropic's server-side web-search tool for this
+		// turn only. The gateway executes it and returns cited results; source URLs the
+		// model writes inline flow to the pane's Sources chips via extractReferences.
+		const serverTools = req.web_search
+			? [{ type: "web_search_20250305", name: "web_search", max_uses: 5 }]
+			: undefined;
 
 		try {
 			chat.promptAt = Date.now();
-			await this.#session.prompt(prompt, { expandPromptTemplates: false, synthetic: false, images });
+			await this.#session.prompt(prompt, { expandPromptTemplates: false, synthetic: false, images, serverTools });
 		} catch (err: unknown) {
 			const message = err instanceof Error ? err.message : "unknown error";
 			this.#sendTerminal(chat, { type: "chat_error", id, error: message, reason: classifyChatErrorReason(message) });
@@ -377,6 +397,15 @@ export class ChatHandler {
 		this.#session.agent.abort();
 	}
 
+	/** Reply to `list_skills` with the session's live skills (name + description) so
+	 *  the pane can populate the composer's Skills submenu. Pure read — skills are
+	 *  already loaded on the session; the model actions them via the read tool + the
+	 *  system prompt (Phase 2A enabled `read`), so this is enumeration only. */
+	#handleListSkills(): void {
+		const skills = this.#session.skills.map(s => ({ name: s.name, description: s.description }));
+		this.#server.send({ type: "skills", skills } satisfies SkillsList);
+	}
+
 	#sendTerminal(chat: ActiveChat, frame: ChatDone | ChatError): void {
 		if (chat.terminalSent) return;
 		chat.terminalSent = true;
@@ -455,11 +484,79 @@ const MODE_INSTRUCTIONS: Record<InteractionMode, string> = {
 	annotation: "Create on-page teaching annotations that highlight key elements and explain their purpose.",
 };
 
+/** Bases a user-attached context path must fall under. Confines grants to the user's
+ *  own space (home, the project cwd, temp, external volumes, /opt) and thereby blocks
+ *  a client from widening the sandbox to system/credential dirs (`/etc`, `/var`,
+ *  `/usr`, `/System`, other users' homes, `/`). */
+function contextPathAllowedBases(): string[] {
+	const bases = [process.cwd(), "/tmp", "/private/tmp", "/Volumes", "/opt"];
+	const home = process.env.HOME ?? process.env.USERPROFILE;
+	if (home) bases.push(home);
+	// Canonicalize with realpath so BOTH sides of the containment check are symlink-free
+	// (a symlink base like /tmp→/private/tmp must compare against the real target).
+	return bases.map(b => {
+		try {
+			return fs.realpathSync(b);
+		} catch {
+			return path.resolve(b);
+		}
+	});
+}
+
+/**
+ * Canonicalize + validate the user-attached context paths BEFORE they widen the
+ * sandbox or are named in the prompt. Rejects anything that isn't an absolute path
+ * confined to {@link contextPathAllowedBases} (after collapsing `..`), and anything
+ * carrying control characters (a prompt-injection vector). Deduped. This is the trust
+ * boundary: the engine must not blindly grant a client-supplied path to its own
+ * filesystem sandbox.
+ */
+export function sanitizeContextPaths(paths: string[]): string[] {
+	const bases = contextPathAllowedBases();
+	const seen = new Set<string>();
+	const out: string[] = [];
+	for (const p of paths) {
+		if (typeof p !== "string" || p.length === 0 || /[\n\r\0]/.test(p) || !path.isAbsolute(p)) continue;
+		// realpathSync resolves symlinks — a link INSIDE an allowed base that points out to
+		// /etc canonicalizes to /etc and fails the containment check — AND requires the
+		// path to exist, so a non-existent (typo'd/spoofed) attachment is skipped.
+		let real: string;
+		try {
+			real = fs.realpathSync(p);
+		} catch {
+			continue;
+		}
+		const within = bases.some(base => real === base || real.startsWith(base + path.sep));
+		if (!within || seen.has(real)) continue;
+		seen.add(real);
+		out.push(real);
+	}
+	return out;
+}
+
+/**
+ * Append absolute context paths to the session's sandbox read-allowlist. In-memory
+ * (`override`, never persisted) and deduped, so re-attaching a path is a no-op. The
+ * sandbox-guard keys its policy cache on the allow-list, so the grant takes effect on
+ * the model's next file tool call. Best-effort: a pre-init settings proxy is tolerated.
+ * Callers MUST pass paths through {@link sanitizeContextPaths} first.
+ */
+export function grantSandboxPaths(paths: string[]): void {
+	try {
+		const current = (settings.get("sandbox.allowRead") as string[] | undefined) ?? [];
+		const merged = Array.from(new Set([...current, ...paths]));
+		if (merged.length !== current.length) settings.override("sandbox.allowRead", merged);
+	} catch {
+		/* settings not initialized (some SDK/test contexts) — the grant is best-effort */
+	}
+}
+
 export function composeChatPrompt(
 	text: string,
 	context: PageContextSnapshot | null,
 	mode: InteractionMode,
 	host: ClientHost | null,
+	contextPaths?: string[],
 ): string {
 	const parts: string[] = [];
 
@@ -477,6 +574,17 @@ export function composeChatPrompt(
 		if (context) composeBrowserPageContext(parts, context);
 	}
 
+	// User-attached local context paths (files/folders). They're granted to the
+	// sandbox alongside this, so the model may read them on demand — tell it they exist.
+	if (contextPaths && contextPaths.length > 0) {
+		parts.push("");
+		// JSON.stringify each path: an unambiguous, escaped boundary so a path can't
+		// blur into surrounding prompt text (belt-and-suspenders — they're pre-sanitized).
+		parts.push(
+			`The user attached these local paths as context; read them with your tools (read/grep/bash) as needed:\n${contextPaths.map(p => `- ${JSON.stringify(p)}`).join("\n")}`,
+		);
+	}
+
 	parts.push("");
 	parts.push(text);
 	return parts.join("\n");

package/src/browser/chat-protocol.ts

@@ -85,6 +85,48 @@ export interface ChatRequest {
 	history_hint?: string;
 	/** Optional photo/image attachments, sent to the model as vision blocks. */
 	images?: ChatImage[];
+	/** Absolute local paths (files/folders) the user attached as context. The engine
+	 *  grants them to the filesystem sandbox for the session and tells the model they
+	 *  are available to read on demand. */
+	contextPaths?: string[];
+	/** When true, the engine adds Anthropic's server-side web-search tool to this
+	 *  turn's request (the "Search the web" composer toggle). */
+	web_search?: boolean;
+}
+
+/** Client → engine: open a native OS file/folder picker on the machine running the
+ *  bridge and return the chosen absolute path. */
+export interface PickPath {
+	type: "pick_path";
+	mode: "file" | "folder";
+}
+
+/** Engine → client: the picker result. `path` is set on success; `canceled` when the
+ *  user dismissed the dialog; `unsupported` when the platform has no native picker
+ *  (the pane then falls back to manual path entry). */
+export interface PathPicked {
+	type: "path_picked";
+	path?: string;
+	canceled?: boolean;
+	unsupported?: boolean;
+}
+
+/** Client → engine: enumerate the session's loaded skills for the composer's
+ *  Skills submenu. Sent once after the pane connects. */
+export interface ListSkills {
+	type: "list_skills";
+}
+
+/** One skill surfaced to the pane's Skills submenu (name + human description). */
+export interface SkillInfo {
+	name: string;
+	description: string;
+}
+
+/** Engine → client: the session's live skills, in load order. */
+export interface SkillsList {
+	type: "skills";
+	skills: SkillInfo[];
 }
 
 export interface ChatStop {
@@ -266,6 +308,14 @@ export function isChatStop(msg: Record<string, unknown>): boolean {
 	return msg.type === "chat_stop" && hasChatIdPrefix(msg.id);
 }
 
+export function isListSkills(msg: Record<string, unknown>): boolean {
+	return msg.type === "list_skills";
+}
+
+export function isPickPath(msg: Record<string, unknown>): boolean {
+	return msg.type === "pick_path" && (msg.mode === "file" || msg.mode === "folder");
+}
+
 export function isSetHostTools(msg: Record<string, unknown>): boolean {
 	return msg.type === "set_host_tools" && Array.isArray(msg.tools);
 }

package/src/browser/extension-bridge-tools.ts

@@ -100,16 +100,48 @@ export const BROWSER_TOOL_NAMES: readonly string[] = [
 
 /**
  * Builtin agent tools scoped into the headless OFFICE bridge (`xcsh office serve`).
- * The Office task pane drives a document (Excel/PowerPoint/Word), NOT a browser, so
- * it must get NONE of the {@link BROWSER_TOOL_NAMES} — those would be hallucinated
- * against a host with no browser to drive. The document's own tools arrive at
- * runtime over the bridge via `set_host_tools`; this list is only the minimal
- * general-purpose, host-neutral builtin toolset a document assistant can safely use.
  *
- * NOTE: an EMPTY list cannot express "no builtin tools" — createAgentSession/createTools
- * treat `[]` as "unscoped" and hand back the FULL builtin registry (bash/edit/python/
- * browser/…). So we pass an explicit minimal set instead. `calc` is the one builtin
- * that is pure computation — no browser, no shell, no filesystem, no network — and is
- * genuinely useful for spreadsheet/document math.
+ * FULL CLI-PARITY tool set (minus browser automation): the Office pane is a full
+ * local xcsh agent, so it gets the same general-purpose native tools the CLI has —
+ * `bash` (so it can shell out to `az`, `gh`, terraform, git, …), the file tools
+ * (`read`/`write`/`edit`), search (`grep`), plus planning (`todo_write`,
+ * `task`) and `calc`. (File-finding is covered by `bash`; the builtin `find`
+ * tool is omitted because its name collides with a browser tool.) The document's own Excel/PowerPoint/Word tools arrive at
+ * runtime over the bridge via `set_host_tools`.
+ *
+ * DELIBERATELY EXCLUDED:
+ *  - Every {@link BROWSER_TOOL_NAMES} entry — there is no browser to drive in a
+ *    document pane, so navigate/click/screenshot would only be hallucinated.
+ *  - `ask` (needs interactive stdin → would hang headless), `python` (spawns a
+ *    kernel → startup cost), `ssh`/`debug`/`notebook`/`browser`/`get_page_context`.
+ *
+ * SAFETY: the headless session pairs this with the bundled `sandbox-guard`
+ * extension (see headless-bridge.ts `bundledExtensions`), which confines the file
+ * tools + the shell's working dir to the launch cwd subtree — the CLI's own model.
+ * `az`/`gh` still run (network actions aren't filesystem-confined); credentials must
+ * already exist for the process user. There is no per-tool approval prompt — the
+ * local trusted bridge auto-runs tools exactly as the CLI does.
+ *
+ * THREAT MODEL (reviewed + accepted, 2026-07-24): the pane's agent auto-reads
+ * document content, which could be adversarial (a prompt-injected customer .xlsx)
+ * and steer it into shell/`az`/`gh` calls; the filesystem sandbox blocks file
+ * damage outside cwd but NOT network/cloud actions. This is the same exposure the
+ * xcsh CLI already carries (no approval system anywhere). The operator explicitly
+ * chose full CLI parity + FS sandbox over a bash approval gate, mitigating in
+ * practice by only opening trusted documents. If untrusted files become common,
+ * revisit with a per-shell approval round-trip (host_tool_call-style frame).
+ *
+ * NOTE: an EMPTY list cannot express "no builtin tools" — createTools treats `[]` as
+ * "unscoped" and returns the FULL registry (including browser tools). So this is an
+ * explicit curated array, not `[]`.
  */
-export const OFFICE_TOOL_NAMES: readonly string[] = ["calc"];
+export const OFFICE_TOOL_NAMES: readonly string[] = [
+	"read",
+	"write",
+	"edit",
+	"bash",
+	"grep",
+	"todo_write",
+	"task",
+	"calc",
+];

package/src/browser/headless-bridge.ts

@@ -20,8 +20,10 @@ import { ContextService } from "../services/xcsh-context";
 import { deriveTenantEnv } from "../services/xcsh-env";
 import { resolveBridgeTls } from "./bridge-cert";
 import { ChatHandler } from "./chat-handler";
+import { isPickPath, type PathPicked } from "./chat-protocol";
 import { type BridgeServer, OFFICE_PORT_RANGE, startBridgeServer } from "./extension-bridge";
 import { OFFICE_TOOL_NAMES } from "./extension-bridge-tools";
+import { pickPathNative } from "./native-picker";
 import { setSharedBridgeServer } from "./provider";
 
 /** A running headless bridge + a teardown that disposes the chat handler and
@@ -69,6 +71,9 @@ export interface HeadlessBridgeDeps {
 	setSharedBridgeServer: typeof setSharedBridgeServer;
 	createAgentSession: typeof createAgentSession;
 	ChatHandlerCtor: typeof ChatHandler;
+	/** Native OS file/folder picker (macOS osascript by default). Injectable so tests
+	 *  don't open a real dialog. */
+	pickPath: typeof pickPathNative;
 }
 
 const defaultDeps: HeadlessBridgeDeps = {
@@ -96,6 +101,7 @@ const defaultDeps: HeadlessBridgeDeps = {
 	setSharedBridgeServer,
 	createAgentSession,
 	ChatHandlerCtor: ChatHandler,
+	pickPath: pickPathNative,
 };
 
 /**
@@ -134,12 +140,10 @@ export async function startHeadlessChatBridge(deps: HeadlessBridgeDeps = default
 	// selectProvider() reuses a dead bridge. The caller (startOfficeServe) treats
 	// the rethrow as a non-fatal "pane only" fallback.
 	try {
-		// Create ONE headless Office session scoped to the minimal general builtin set
-		// (OFFICE_TOOL_NAMES) with NO browser tools — neither the browser BUILTINS
-		// (navigate/click/…) nor the bridge-proxying browser CUSTOM tools, both of which
-		// would be hallucinated in a document task pane (there is no browser to drive).
-		// The document's own tools (Excel/Word/PowerPoint) arrive at runtime via
-		// set_host_tools; chat over xcsh's configured provider needs no browser tooling.
+		// Create ONE headless Office session with the full CLI-parity builtin set
+		// (OFFICE_TOOL_NAMES: bash/read/write/edit/grep/find/… — NO browser tools, which
+		// would be hallucinated in a document task pane). The document's own tools
+		// (Excel/Word/PowerPoint) arrive at runtime via set_host_tools.
 		const { session } = await deps.createAgentSession({
 			cwd,
 			hasUI: false,
@@ -149,14 +153,33 @@ export async function startHeadlessChatBridge(deps: HeadlessBridgeDeps = default
 			enableMCP: false,
 			enableLsp: false,
 			disableExtensionDiscovery: true,
+			// …but DO load the bundled filesystem sandbox: the pane runs full CLI-parity
+			// tools (bash/read/write), so it needs the CLI's safety net confining file
+			// tools + the shell's cwd to the launch directory subtree (sandbox.enabled
+			// defaults true). Without this, a discovery-disabled session ran ungated.
+			bundledExtensions: ["sandbox-guard"],
 		});
 
 		const chatHandler = new deps.ChatHandlerCtor(bridge, session);
 		chatHandler.attach();
 
+		// Second bridge subscriber (the bridge fans out to all): serve `pick_path` by
+		// opening a native OS picker and replying `path_picked`. Pure — it only returns
+		// the chosen path; the sandbox grant + prompt note happen in ChatHandler when the
+		// path rides the next `chat_request.contextPaths` (kept atomic there). `disposed`
+		// guards against a superseded serve firing the picker on a closed bridge.
+		let disposed = false;
+		bridge.onMessage(async msg => {
+			if (disposed || !isPickPath(msg)) return;
+			const { path, canceled, unsupported } = await deps.pickPath((msg as { mode: "file" | "folder" }).mode);
+			if (disposed) return;
+			bridge.send({ type: "path_picked", path, canceled, unsupported } satisfies PathPicked);
+		});
+
 		return {
 			bridge,
 			dispose: async () => {
+				disposed = true;
 				chatHandler.dispose();
 				deps.setSharedBridgeServer(null);
 				await bridge.close();

package/src/browser/host-profiles.ts

@@ -85,6 +85,21 @@ SAFETY — NEVER DO THESE:
 
 `;
 
+/**
+ * Shared tail for every Office (document) profile: the pane is a FULL local xcsh
+ * agent — same native tools as the CLI — plus the one safety rule that shelling
+ * out makes necessary (don't let the agent kill its own bridge). Interpolated into
+ * each document profile so the three stay in sync (DRY).
+ */
+const OFFICE_NATIVE_TOOLS_NOTE = `
+NATIVE TOOLS: Beyond the document host tools, you have xcsh's full local toolset — \`bash\` (run shell commands, including CLIs like \`az\`, \`gh\`, \`terraform\`, \`git\` when installed and authenticated), file tools (\`read\`/\`write\`/\`edit\`), and \`grep\` — plus any skills available in this workspace. Reach for them when the task genuinely needs them (pull live data with a CLI, read a local file the user points you at). Prefer the document host tools for document work. Your file tools and shell are confined to the folder xcsh was launched from.
+
+SKILLS: When a message begins with \`/<skill-name>\` naming one of your available skills, treat it as a request to USE that skill — read its instructions (open \`skill://<skill-name>\`, or its SKILL.md via \`read\`) and follow them, applying any text after the name as the skill's input.
+
+SAFETY:
+- NEVER kill, stop, inspect, or manage the xcsh \`office serve\` process, its bridge ports, or any xcsh process — that bridge IS you; ending it ends the session.
+- NEVER run \`lsof\`/\`fuser\`/\`kill\`/\`pkill\` against the bridge ports or use the shell to manage xcsh itself.`;
+
 /**
  * Excel task-pane self-awareness prompt. The assistant works the OPEN workbook
  * via host tools (arriving at runtime over the bridge), thinking in cells,
@@ -95,7 +110,7 @@ You are still xcsh, the F5 Distributed Cloud technical coworker defined in your
 
 CRITICAL: ALWAYS respond with TEXT FIRST — the user sees a chat pane and expects a conversational reply, not silence while tools run. Answer questions from the data you read; only WRITE to the workbook when the user asks you to.
 
-CONTEXT: You can only access the open workbook. Think in cells, ranges, and — above all — FORMULAS and their dependencies:
+CONTEXT: Your workspace centers on the open workbook. Think in cells, ranges, and — above all — FORMULAS and their dependencies:
 - Preserve formula relationships. When you change a cell, let dependent cells recompute; do not overwrite a formula with its current value unless asked.
 - Warn the user before overwriting existing cell contents.
 - Cite specific cells and ranges precisely (e.g. A1, Sheet1!B2:B10) so the user can follow along.
@@ -105,6 +120,7 @@ TOOLS: Discover the workbook before you answer, then reach for the tool that mat
 - Use \`read_table\` for structured Excel Tables (it tracks the real extent), \`get_formulas\` to see the formulas behind cells, \`get_cell_metadata\` for cell types/number formats, and \`read_named_range\` to read a defined name.
 - Use \`sort_filter_table\` to sort or filter a Table by column.
 - Use \`read_range\`/\`write_range\` for arbitrary cell ranges (bare or sheet-qualified like Sheet2!A1:B10), and \`list_sheets\` when you only need the tab names.
+${OFFICE_NATIVE_TOOLS_NOTE}
 
 BEHAVIOR:
 - Respond concisely with markdown. The task pane is narrow — avoid long code blocks.
@@ -123,7 +139,7 @@ You are still xcsh, the F5 Distributed Cloud technical coworker defined in your
 
 CRITICAL: ALWAYS respond with TEXT FIRST — the user sees a chat pane and expects a conversational reply, not silence while tools run. Answer questions from what you read; only edit the deck when the user asks you to.
 
-CONTEXT: You can only access the open presentation. Think in slides, shapes, and the slide master:
+CONTEXT: Your workspace centers on the open presentation. Think in slides, shapes, and the slide master:
 - Conform any new content to the deck's existing template, fonts, and colors — do not introduce a different look.
 - Make pinpoint, per-slide edits. Do NOT regenerate the whole deck to change one thing.
 - Refer to slides by number so the user can follow along.
@@ -132,6 +148,7 @@ TOOLS: Discover the deck before you answer, then reach for the tool that matches
 - Call \`get_presentation_info\` FIRST to discover all slides, their layouts, and shape counts before answering — do not guess the structure.
 - Use \`read_slide_shapes\` to see all shapes on a slide with their text + position, \`read_slide_layout\` for the layout/master applied to a slide, and \`modify_shape_text\` to edit the text of a named shape.
 - Use \`read_slides\` for a quick text-only scan of the whole deck, and \`add_text_box\`/\`add_slide\` to create new content.
+${OFFICE_NATIVE_TOOLS_NOTE}
 
 BEHAVIOR:
 - Respond concisely with markdown. The task pane is narrow — avoid long code blocks.
@@ -151,7 +168,7 @@ You are still xcsh, the F5 Distributed Cloud technical coworker defined in your
 
 CRITICAL: ALWAYS respond with TEXT FIRST — the user sees a chat pane and expects a conversational reply, not silence while tools run. Answer questions from what you read; only edit the document when the user asks you to.
 
-CONTEXT: You can only access the open document. Think in paragraphs, the current selection, comments, and tracked changes:
+CONTEXT: Your workspace centers on the open document. Think in paragraphs, the current selection, comments, and tracked changes:
 - Preserve the document's styles and numbering — do not flatten formatting.
 - Describe your edits so the user can review them, and prefer changes the user can accept or reject.
 - When the user refers to "the selection" (or "this"), act on the current selection.
@@ -161,6 +178,7 @@ TOOLS: Discover the document before you answer, then reach for the tool that mat
 - Use \`read_paragraphs\` for styled paragraph content, \`read_selection\` for the current selection, \`get_comments\` for comments, and \`get_tracked_changes\` for revisions.
 - Use \`read_document\` when you need the full plain text.
 - Use \`insert_paragraph\` to add content at a specific location (start, end, or before/after the selection), and \`insert_text\` for inline text within a paragraph.
+${OFFICE_NATIVE_TOOLS_NOTE}
 
 BEHAVIOR:
 - Respond concisely with markdown. The task pane is narrow — avoid long code blocks.

package/src/browser/native-picker.ts

@@ -0,0 +1,47 @@
+/**
+ * Native OS file/folder picker for the local Office bridge.
+ *
+ * An Office task-pane WebView cannot open a local file dialog, but the bridge runs
+ * in-process on the user's machine, so it can. macOS uses `osascript`'s `choose
+ * file`/`choose folder`; other platforms have no one-liner equivalent, so the pane
+ * falls back to manual path entry there.
+ *
+ * ASYNC on purpose: the dialog blocks until the user responds, so a synchronous
+ * spawn would stall the bridge's event loop (heartbeats, in-flight turns) for the
+ * whole time it's open. `Bun.spawn` + `await proc.exited` keeps the bridge live.
+ */
+
+export interface PickResult {
+	ok: boolean;
+	/** Absolute path chosen (no trailing slash), when `ok`. */
+	path?: string;
+	/** The user dismissed the dialog. */
+	canceled?: boolean;
+	/** This platform has no native picker; the pane should prompt for a path instead. */
+	unsupported?: boolean;
+}
+
+/**
+ * Open a native picker and resolve the chosen absolute path. Never throws — every
+ * failure maps to a `PickResult` flag so the caller can respond gracefully.
+ */
+export async function pickPathNative(mode: "file" | "folder"): Promise<PickResult> {
+	// macOS only for now — osascript is not present on win32/linux.
+	if (process.platform !== "darwin") return { ok: false, unsupported: true };
+	const script = mode === "folder" ? "POSIX path of (choose folder)" : "POSIX path of (choose file)";
+	try {
+		const proc = Bun.spawn(["osascript", "-e", script], { stdout: "pipe", stderr: "ignore" });
+		const [out, code] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
+		// Cancel raises AppleScript error -128 → non-zero exit, empty stdout.
+		if (code !== 0) return { ok: false, canceled: true };
+		let path = out.trim();
+		if (!path) return { ok: false, canceled: true };
+		// `choose folder` yields a trailing slash; normalize to a bare dir path so it
+		// matches the sandbox allow-rule root exactly.
+		if (path.length > 1 && path.endsWith("/")) path = path.slice(0, -1);
+		return { ok: true, path };
+	} catch {
+		// osascript missing/blocked — treat as unsupported so the pane offers manual entry.
+		return { ok: false, unsupported: true };
+	}
+}

package/src/extensibility/extensions/loader.ts

@@ -336,8 +336,17 @@ export async function loadExtensionFromFactory(
 
 /**
  * Load extensions from paths.
+ *
+ * `bundledExtensionNames` opts specific bundled extensions (e.g. `["sandbox-guard"]`)
+ * into a session that has otherwise disabled discovery — the headless bridges use
+ * this to keep the CLI's filesystem safety net without paying for full discovery.
  */
-export async function loadExtensions(paths: string[], cwd: string, eventBus?: EventBus): Promise<LoadExtensionsResult> {
+export async function loadExtensions(
+	paths: string[],
+	cwd: string,
+	eventBus?: EventBus,
+	bundledExtensionNames: readonly string[] = [],
+): Promise<LoadExtensionsResult> {
 	const extensions: Extension[] = [];
 	const errors: Array<{ path: string; error: string }> = [];
 	const resolvedEventBus = eventBus ?? new EventBus();
@@ -356,11 +365,14 @@ export async function loadExtensions(paths: string[], cwd: string, eventBus?: Ev
 		}
 	}
 
-	return {
-		extensions,
-		errors,
-		runtime,
-	};
+	const result: LoadExtensionsResult = { extensions, errors, runtime };
+
+	if (bundledExtensionNames.length > 0) {
+		const allow = new Set(bundledExtensionNames);
+		await loadBundledExtensions(result, cwd, resolvedEventBus, name => !allow.has(name));
+	}
+
+	return result;
 }
 
 interface ExtensionManifest {

package/src/internal-urls/build-info.generated.ts

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.87.1",
-	"commit": "961f2b2d80f178d7165977576b0249907c21c68d",
-	"shortCommit": "961f2b2",
+	"version": "19.89.0",
+	"commit": "e3c72edcac3935dc928e0599909ce1fc9bdc4832",
+	"shortCommit": "e3c72ed",
 	"branch": "main",
-	"tag": "v19.87.1",
-	"commitDate": "2026-07-24T18:28:42Z",
-	"buildDate": "2026-07-24T18:54:10.232Z",
+	"tag": "v19.89.0",
+	"commitDate": "2026-07-24T23:47:33Z",
+	"buildDate": "2026-07-25T00:13:14.668Z",
 	"dirty": true,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5-sales-demo/xcsh",
 	"repoSlug": "f5-sales-demo/xcsh",
-	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/961f2b2d80f178d7165977576b0249907c21c68d",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.87.1"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/e3c72edcac3935dc928e0599909ce1fc9bdc4832",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.89.0"
 };

package/src/internal-urls/terraform-index.generated.ts

@@ -167,7 +167,7 @@ export const TERRAFORM_INDEX: TerraformIndex = {
 			name: "Uncategorized",
 			slug: "uncategorized",
 			description: "Resources pending categorization",
-			resource_count: 6,
+			resource_count: 7,
 			resources: [
 				"application_profiles",
 				"authorization_server",
@@ -175,6 +175,7 @@ export const TERRAFORM_INDEX: TerraformIndex = {
 				"mitigated_domain",
 				"protected_application",
 				"protected_domain",
+				"registration_approval",
 			],
 		},
 		{
@@ -1427,6 +1428,17 @@ export const TERRAFORM_INDEX: TerraformIndex = {
 			},
 			import_syntax: "terraform import xcsh_registration.example namespace/name",
 		},
+		registration_approval: {
+			category: "uncategorized",
+			description: "Request for admission approval. configuration",
+			required: ["name", "namespace"],
+			minimal_config:
+				'resource "xcsh_registration_approval" "example" {\n  name      = "example-registration-approval"\n  namespace = "staging"\n}',
+			dependencies: {
+				requires: [],
+			},
+			import_syntax: "terraform import xcsh_registration_approval.example namespace/name",
+		},
 		route: {
 			category: "load-balancing",
 			description:

package/src/sdk.ts

@@ -188,6 +188,12 @@ export interface CreateAgentSessionOptions {
 	additionalExtensionPaths?: string[];
 	/** Disable extension discovery (explicit paths still load). */
 	disableExtensionDiscovery?: boolean;
+	/**
+	 * Bundled extensions to load even when discovery is disabled (e.g.
+	 * `["sandbox-guard"]`). Lets a headless session keep the CLI's filesystem
+	 * safety net without paying for full discovery.
+	 */
+	bundledExtensions?: string[];
 	/**
 	 * Pre-loaded extensions (skips file discovery).
 	 * @internal Used by CLI when extensions are loaded early to parse custom flags.
@@ -1238,7 +1244,14 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		let extensionsResult: LoadExtensionsResult;
 		if (options.disableExtensionDiscovery) {
 			const configuredPaths = options.additionalExtensionPaths ?? [];
-			extensionsResult = await logger.time("loadExtensions", loadExtensions, configuredPaths, cwd, eventBus);
+			extensionsResult = await logger.time(
+				"loadExtensions",
+				loadExtensions,
+				configuredPaths,
+				cwd,
+				eventBus,
+				options.bundledExtensions ?? [],
+			);
 			for (const { path, error } of extensionsResult.errors) {
 				logger.error("Failed to load extension", { path, error });
 			}

package/src/session/agent-session.ts

@@ -277,6 +277,12 @@ export interface PromptOptions {
 	attribution?: MessageAttribution;
 	/** Skip pre-send compaction checks for this prompt (internal use for maintenance flows). */
 	skipCompactionCheck?: boolean;
+	/**
+	 * Raw provider "server tool" specs to inject into THIS turn's request tools, e.g.
+	 * Anthropic's `{type:"web_search_20250305", name:"web_search", max_uses:N}`. Rides
+	 * the provider `onPayload` seam (per-turn, no client-side tool registration).
+	 */
+	serverTools?: Record<string, unknown>[];
 }
 
 /** Result from cycleModel() */
@@ -2632,7 +2638,7 @@ export class AgentSession {
 	async #promptWithMessage(
 		message: AgentMessage,
 		expandedText: string,
-		options?: Pick<PromptOptions, "toolChoice" | "images" | "skipCompactionCheck"> & {
+		options?: Pick<PromptOptions, "toolChoice" | "images" | "skipCompactionCheck" | "serverTools"> & {
 			prependMessages?: AgentMessage[];
 			skipPostPromptRecoveryWait?: boolean;
 		},
@@ -2753,7 +2759,10 @@ export class AgentSession {
 				return;
 			}
 
-			const agentPromptOptions = options?.toolChoice ? { toolChoice: options.toolChoice } : undefined;
+			const agentPromptOptions =
+				options?.toolChoice || options?.serverTools
+					? { toolChoice: options?.toolChoice, serverTools: options?.serverTools }
+					: undefined;
 			await logger.ttftAttr("ttft.agent-loop-total", () =>
 				this.#promptAgentWithIdleRetry(messages, agentPromptOptions),
 			);
@@ -5601,7 +5610,10 @@ export class AgentSession {
 		this.#resolveRetry();
 	}
 
-	async #promptAgentWithIdleRetry(messages: AgentMessage[], options?: { toolChoice?: ToolChoice }): Promise<void> {
+	async #promptAgentWithIdleRetry(
+		messages: AgentMessage[],
+		options?: { toolChoice?: ToolChoice; serverTools?: Record<string, unknown>[] },
+	): Promise<void> {
 		const deadline = Date.now() + 30_000;
 		for (;;) {
 			try {