maestro-agent-sdk 0.1.0

package/dist/tools/builtin/edit.js

@@ -0,0 +1,238 @@
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { isAbsolute } from "node:path";
+/**
+ * NOTE: filesystem sandboxing now lives in the `sandbox-fs` PreToolUse hook.
+ * Standalone callers (tests, scripts) without the registry get NO sandbox.
+ */
+/**
+ * Edit builtin — claude SDK `Edit` tool parity for maestro.
+ *
+ * Mirrors the upstream `Edit` tool's name + input schema so the model's
+ * pretrained instinct calls our handler with the right shape. Same as
+ * Read/Write, this benefits prompt cache when a topic is bridged across
+ * agents — the tool schemas line up byte-for-byte.
+ *
+ * Contract (matches claude SDK exactly):
+ *  - file_path must be absolute, the file must exist (Edit never creates).
+ *  - old_string must appear in the file. Same anchor for both modes.
+ *  - replace_all=false (default): old_string MUST appear exactly once, else
+ *    we reject. This is intentional: the model is forced to enlarge its
+ *    `old_string` until it pins a unique anchor, which is the strongest
+ *    safety against silent mis-edits. claude SDK's own description ("either
+ *    provide a larger string with more surrounding context to make it
+ *    unique or use replace_all") is what trains the model's intuition; we
+ *    error with the same shape so it self-corrects on the next turn.
+ *  - replace_all=true: every occurrence is swapped (useful for renames).
+ *  - old_string === new_string is a no-op and rejected as a model bug.
+ *
+ * Returns a short summary + line-numbered preview of the changed region
+ * (claude SDK does the same — the model uses this preview to confirm
+ * its own edit landed before continuing). Errors are JSON-stringified
+ * `{error}` for parity with bash/read/write.
+ */
+const MAX_FILE_BYTES = 10 * 1024 * 1024; // 10MB — same cap as Read
+const PREVIEW_LINES_AROUND = 3;
+export function createEditTool(opts = {}) {
+    const { tracker } = opts;
+    return {
+        schema: {
+            name: "Edit",
+            description: "Find-and-replace within a single file. " +
+                "file_path must be absolute. old_string must match exactly. " +
+                "By default old_string must occur exactly once — if it appears multiple " +
+                "times, either enlarge old_string with surrounding context to make it " +
+                "unique, or set replace_all=true. old_string and new_string must differ.",
+            input_schema: {
+                type: "object",
+                properties: {
+                    file_path: {
+                        type: "string",
+                        description: "Absolute path to the file. Edit never creates new files.",
+                    },
+                    old_string: {
+                        type: "string",
+                        description: "Exact string to find. Must be unique unless replace_all=true.",
+                    },
+                    new_string: {
+                        type: "string",
+                        description: "Replacement string. Must differ from old_string.",
+                    },
+                    replace_all: {
+                        type: "boolean",
+                        description: "When true, replace every occurrence. Default false (unique-match required).",
+                    },
+                },
+                required: ["file_path", "old_string", "new_string"],
+            },
+        },
+        async execute(input) {
+            const filePath = typeof input.file_path === "string" ? input.file_path : "";
+            if (!filePath) {
+                return JSON.stringify({ error: "Edit: missing 'file_path' argument" });
+            }
+            if (!isAbsolute(filePath)) {
+                return JSON.stringify({
+                    error: `Edit: file_path must be absolute, got '${filePath}'`,
+                });
+            }
+            // Read-before-Edit gate. No-op when no tracker is wired (standalone use).
+            if (tracker) {
+                const gateErr = tracker.checkBeforeMutate(filePath, "Edit");
+                if (gateErr) {
+                    return JSON.stringify({ error: gateErr });
+                }
+            }
+            if (typeof input.old_string !== "string") {
+                return JSON.stringify({
+                    error: `Edit: 'old_string' must be a string, got ${typeof input.old_string}`,
+                });
+            }
+            if (typeof input.new_string !== "string") {
+                return JSON.stringify({
+                    error: `Edit: 'new_string' must be a string, got ${typeof input.new_string}`,
+                });
+            }
+            const oldStr = input.old_string;
+            const newStr = input.new_string;
+            const replaceAll = Boolean(input.replace_all);
+            if (oldStr === newStr) {
+                return JSON.stringify({
+                    error: "Edit: old_string and new_string must differ (no-op edits are rejected)",
+                });
+            }
+            if (oldStr.length === 0) {
+                return JSON.stringify({
+                    error: "Edit: old_string must be non-empty",
+                });
+            }
+            if (!existsSync(filePath)) {
+                return JSON.stringify({
+                    error: `Edit: file does not exist: ${filePath}. Use Write to create new files.`,
+                });
+            }
+            let stat;
+            try {
+                stat = statSync(filePath);
+            }
+            catch (e) {
+                return JSON.stringify({
+                    error: `Edit: stat failed: ${e instanceof Error ? e.message : String(e)}`,
+                });
+            }
+            if (stat.isDirectory()) {
+                return JSON.stringify({
+                    error: `Edit: '${filePath}' is a directory, not a file.`,
+                });
+            }
+            if (stat.size > MAX_FILE_BYTES) {
+                return JSON.stringify({
+                    error: `Edit: file size ${stat.size} exceeds 10MB cap. Use bash sed/awk for large files.`,
+                });
+            }
+            let raw;
+            try {
+                raw = readFileSync(filePath, "utf-8");
+            }
+            catch (e) {
+                return JSON.stringify({
+                    error: `Edit: read failed: ${e instanceof Error ? e.message : String(e)}`,
+                });
+            }
+            const occurrences = countOccurrences(raw, oldStr);
+            if (occurrences === 0) {
+                return JSON.stringify({
+                    error: `Edit: old_string not found in ${filePath}. Re-read the file and verify the exact text (whitespace, indentation, etc.).`,
+                });
+            }
+            if (!replaceAll && occurrences > 1) {
+                return JSON.stringify({
+                    error: `Edit: old_string appears ${occurrences} times in ${filePath}. Either enlarge old_string with surrounding context to make it unique, or pass replace_all=true.`,
+                    occurrences,
+                });
+            }
+            // Perform the replacement.
+            let updated;
+            if (replaceAll) {
+                updated = raw.split(oldStr).join(newStr);
+            }
+            else {
+                const idx = raw.indexOf(oldStr);
+                updated = raw.slice(0, idx) + newStr + raw.slice(idx + oldStr.length);
+            }
+            try {
+                writeFileSync(filePath, updated, "utf-8");
+            }
+            catch (e) {
+                return JSON.stringify({
+                    error: `Edit: write failed: ${e instanceof Error ? e.message : String(e)}`,
+                });
+            }
+            // Forget the recorded state — file mtime + size just changed, so the
+            // next Edit must Re-read to refresh the line-numbered view.
+            tracker?.forget(filePath);
+            // Build a small line-numbered preview around the first changed location.
+            // The model uses this to confirm the change landed correctly — same shape
+            // claude SDK returns post-edit.
+            const replacedCount = replaceAll ? occurrences : 1;
+            const preview = buildEditPreview(raw, updated, oldStr, newStr);
+            return [
+                `File edited: ${filePath} (${replacedCount} replacement${replacedCount === 1 ? "" : "s"})`,
+                "",
+                preview,
+            ].join("\n");
+        },
+    };
+}
+/** Backwards-compatible singleton (no tracker — Read-before-Edit gate off). */
+export const editTool = createEditTool();
+/**
+ * Count non-overlapping occurrences of `needle` in `haystack`. We use this
+ * to drive the unique-match check; `indexOf` in a loop is fast enough for
+ * the 10MB cap and avoids the regex escaping the model would have to do.
+ */
+export function countOccurrences(haystack, needle) {
+    if (needle.length === 0)
+        return 0;
+    let count = 0;
+    let from = 0;
+    for (;;) {
+        const idx = haystack.indexOf(needle, from);
+        if (idx === -1)
+            return count;
+        count++;
+        from = idx + needle.length;
+    }
+}
+/**
+ * Build a line-numbered preview of the changed region. Locates the first
+ * occurrence of `newStr` in `updated`, shows ±N lines around it. Empty
+ * preview when we can't locate the change (defensive — never throws).
+ */
+function buildEditPreview(_original, updated, _oldStr, newStr) {
+    if (newStr.length === 0)
+        return "[change preview unavailable: replacement is empty]";
+    const idx = updated.indexOf(newStr);
+    if (idx < 0)
+        return "";
+    const allLines = updated.split("\n");
+    // Find the line containing the start of newStr.
+    let acc = 0;
+    let changedLine = 0;
+    for (let i = 0; i < allLines.length; i++) {
+        const next = acc + allLines[i].length + 1; // +1 for the dropped \n
+        if (next > idx) {
+            changedLine = i;
+            break;
+        }
+        acc = next;
+    }
+    const start = Math.max(0, changedLine - PREVIEW_LINES_AROUND);
+    const end = Math.min(allLines.length, changedLine + PREVIEW_LINES_AROUND + 1);
+    return allLines
+        .slice(start, end)
+        .map((line, i) => `${String(start + i + 1).padStart(6, " ")}\t${line}`)
+        .join("\n");
+}
+// Internal exports for tests.
+export const __MAX_FILE_BYTES = MAX_FILE_BYTES;
+//# sourceMappingURL=edit.js.map

package/dist/tools/builtin/edit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edit.js","sourceRoot":"","sources":["../../../src/tools/builtin/edit.ts"],"names":[],"mappings":"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"}

package/dist/tools/builtin/read.d.ts

@@ -0,0 +1,17 @@
+import type { FileStateTracker } from "../../tools/file-state.js";
+import type { ToolHandler } from "../../tools/registry.js";
+export interface ReadToolOptions {
+    /**
+     * Optional file-state tracker. When provided, a successful Read records
+     * the path's mtime + size so a subsequent Edit can verify the file hasn't
+     * drifted since (Read-before-Edit). Omit for standalone uses — the tool
+     * still works, the Edit gate just won't fire.
+     */
+    tracker?: FileStateTracker;
+}
+export declare function createReadTool(opts?: ReadToolOptions): ToolHandler;
+/** Backwards-compatible singleton (no tracker). */
+export declare const readTool: ToolHandler;
+export declare const __MAX_FILE_BYTES: number;
+export declare const __DEFAULT_LINE_LIMIT = 2000;
+//# sourceMappingURL=read.d.ts.map

package/dist/tools/builtin/read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../../src/tools/builtin/read.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAkCpD,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,gBAAgB,CAAC;CAC5B;AAED,wBAAgB,cAAc,CAAC,IAAI,GAAE,eAAoB,GAAG,WAAW,CAmGtE;AAED,mDAAmD;AACnD,eAAO,MAAM,QAAQ,EAAE,WAA8B,CAAC;AAUtD,eAAO,MAAM,gBAAgB,QAAiB,CAAC;AAC/C,eAAO,MAAM,oBAAoB,OAAqB,CAAC"}

package/dist/tools/builtin/read.js

@@ -0,0 +1,139 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute } from "node:path";
+/**
+ * NOTE: filesystem sandboxing now lives in the `sandbox-fs` PreToolUse hook.
+ * Standalone callers (tests, scripts) without the registry get NO sandbox.
+ */
+/**
+ * Read builtin — claude SDK `Read` tool parity for maestro.
+ *
+ * Mirrors the upstream claude-agent-sdk Read tool's name + input schema so the
+ * model's pretrained instinct about how to call it transfers cleanly. The
+ * line-numbered output format (`     1\t<content>`) is the same one claude SDK
+ * emits, which means we benefit from prompt caching when the same Read result
+ * recurs across turns (e.g. the model re-reads the same file).
+ *
+ * Bounds:
+ *  - file_path must be absolute (matches claude SDK contract — relative paths
+ *    are rejected so the model never gets surprised by an ambiguous cwd).
+ *  - 10MB hard cap on file size — claude SDK has the same ceiling. We bail
+ *    BEFORE reading bytes so a 1GB log doesn't blow heap.
+ *  - 2000-line default cap when `limit` is omitted. Claude SDK uses this
+ *    same default; without it a 50K-line file would dump the whole thing into
+ *    the model's context.
+ *  - `offset` is 1-based line number (claude SDK convention, NOT byte offset).
+ *
+ * Returns the line-numbered string on success or `JSON.stringify({error})`
+ * for every failure mode — matches `bashTool`'s convention so the model sees
+ * structured errors it can react to.
+ */
+const MAX_FILE_BYTES = 10 * 1024 * 1024; // 10MB
+const DEFAULT_LINE_LIMIT = 2000;
+export function createReadTool(opts = {}) {
+    const { tracker } = opts;
+    return {
+        parallelSafe: true,
+        schema: {
+            name: "Read",
+            description: "Read a file from the local filesystem. Returns line-numbered content. " +
+                "file_path must be absolute. Optional offset (1-based line number) and " +
+                "limit narrow the slice; without limit at most 2000 lines are returned. " +
+                "Files larger than 10MB are rejected — use the bash tool with head/tail for huge logs.",
+            input_schema: {
+                type: "object",
+                properties: {
+                    file_path: {
+                        type: "string",
+                        description: "Absolute path to the file. Relative paths are rejected.",
+                    },
+                    offset: {
+                        type: "number",
+                        description: "1-based line number to start reading from. Defaults to 1.",
+                    },
+                    limit: {
+                        type: "number",
+                        description: "Maximum number of lines to return. Defaults to 2000.",
+                    },
+                },
+                required: ["file_path"],
+            },
+        },
+        async execute(input) {
+            const filePath = typeof input.file_path === "string" ? input.file_path : "";
+            if (!filePath) {
+                return JSON.stringify({ error: "Read: missing 'file_path' argument" });
+            }
+            if (!isAbsolute(filePath)) {
+                return JSON.stringify({
+                    error: `Read: file_path must be absolute, got '${filePath}'`,
+                });
+            }
+            if (!existsSync(filePath)) {
+                return JSON.stringify({ error: `Read: file does not exist: ${filePath}` });
+            }
+            let stat;
+            try {
+                stat = statSync(filePath);
+            }
+            catch (e) {
+                return JSON.stringify({
+                    error: `Read: stat failed: ${e instanceof Error ? e.message : String(e)}`,
+                });
+            }
+            if (stat.isDirectory()) {
+                return JSON.stringify({
+                    error: `Read: '${filePath}' is a directory, not a file. Use bash 'ls' to list directories.`,
+                });
+            }
+            if (stat.size > MAX_FILE_BYTES) {
+                return JSON.stringify({
+                    error: `Read: file size ${stat.size} exceeds 10MB cap. Use bash head/tail for large files.`,
+                    size: stat.size,
+                    cap: MAX_FILE_BYTES,
+                });
+            }
+            let raw;
+            try {
+                raw = readFileSync(filePath, "utf-8");
+            }
+            catch (e) {
+                return JSON.stringify({
+                    error: `Read: read failed: ${e instanceof Error ? e.message : String(e)}`,
+                });
+            }
+            // Record post-stat state for the Read-before-Edit gate. We record even
+            // when the model paginated (offset/limit) — the gate cares about whether
+            // a Read was performed, not which slice was requested.
+            tracker?.recordRead(filePath, stat.mtimeMs, stat.size);
+            // Anthropic's Read result encodes lines as `     <n>\t<content>` where
+            // `<n>` is right-aligned in a 6-char field. Matching the format exactly
+            // keeps prompt-cache + pretrained intuition intact.
+            const offset = clampPositive(input.offset, 1);
+            const limit = clampPositive(input.limit, DEFAULT_LINE_LIMIT);
+            const allLines = raw.split("\n");
+            const start = Math.max(0, offset - 1);
+            const end = Math.min(allLines.length, start + limit);
+            const slice = allLines.slice(start, end);
+            const formatted = slice
+                .map((line, i) => {
+                const lineNum = start + i + 1;
+                return `${String(lineNum).padStart(6, " ")}\t${line}`;
+            })
+                .join("\n");
+            return formatted;
+        },
+    };
+}
+/** Backwards-compatible singleton (no tracker). */
+export const readTool = createReadTool();
+/** Coerce a value to a positive integer, falling back to `fallback` for
+ *  missing / non-numeric / non-positive inputs. */
+function clampPositive(v, fallback) {
+    if (typeof v !== "number" || !Number.isFinite(v) || v < 1)
+        return fallback;
+    return Math.floor(v);
+}
+// Internal exports for tests.
+export const __MAX_FILE_BYTES = MAX_FILE_BYTES;
+export const __DEFAULT_LINE_LIMIT = DEFAULT_LINE_LIMIT;
+//# sourceMappingURL=read.js.map

package/dist/tools/builtin/read.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.js","sourceRoot":"","sources":["../../../src/tools/builtin/read.ts"],"names":[],"mappings":"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"}

package/dist/tools/builtin/sandbox.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Check whether `filePath` is allowed by the sandbox. Returns null on allow,
+ * or an error message string on deny. Callers stringify the error into a
+ * `{error}` payload so the model sees a structured rejection.
+ *
+ * The path is normalized (`..` collapsed) but symlinks are NOT followed.
+ * Caller is responsible for ensuring `filePath` is already absolute — the
+ * Read/Write/Edit tools enforce that at the top of `execute`.
+ */
+export declare function checkFilesystemAccess(filePath: string): string | null;
+/** Whether the sandbox is currently active. Default is OFF; the operator
+ *  opts in by exporting `MAESTRO_FS_SANDBOX_ENABLED=1`. Read each call so a
+ *  test can toggle it without restarting the process. */
+export declare function isSandboxEnabled(): boolean;
+export declare const __ENV_ENABLED = "MAESTRO_FS_SANDBOX_ENABLED";
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/tools/builtin/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../../src/tools/builtin/sandbox.ts"],"names":[],"mappings":"AA8BA;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAYrE;AAED;;yDAEyD;AACzD,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAED,eAAO,MAAM,aAAa,+BAAc,CAAC"}

package/dist/tools/builtin/sandbox.js

@@ -0,0 +1,58 @@
+import { resolve as resolvePath } from "node:path";
+import { WORKSPACE_DIR } from "../../platform/config.js";
+/**
+ * Maestro builtin filesystem sandbox.
+ *
+ * Optional gate Read/Write/Edit (and any PreToolUse hook that consults it)
+ * can use to constrain file access to `${WORKSPACE_DIR}`. Default is
+ * **disabled** — claude/codex providers grant unconstrained FS access via
+ * `bypassPermissions` / `danger-full-access`, and forcing a stricter posture
+ * on maestro alone silently breaks any workflow that legitimately reaches
+ * outside the workspace (reading `~/.config`, writing into a sibling repo,
+ * etc.). The single-tenant Mac deployments maestro targets trust the model
+ * with the whole UID anyway.
+ *
+ * Opt-in: set `MAESTRO_FS_SANDBOX_ENABLED=1` to enforce. Only paths under
+ * `${WORKSPACE_DIR}` (`~/claude-code-workspace`) are allowed when enabled;
+ * system paths (`~/.ssh`, `/etc`, `/usr`, sibling clawgram clones, etc.)
+ * are rejected. Useful for multi-tenant or hardened setups where the
+ * model should not be trusted with arbitrary FS access.
+ *
+ * Symlink note: we resolve `..` segments via `path.resolve` but do NOT
+ * follow symlinks (no `realpathSync`) — a symlink inside the workspace
+ * pointing OUT is still considered inside (the link target is what gets
+ * written/read, and the user explicitly placed that link there). Tightening
+ * this is a follow-up if it ever matters.
+ */
+const ENV_ENABLED = "MAESTRO_FS_SANDBOX_ENABLED";
+/**
+ * Check whether `filePath` is allowed by the sandbox. Returns null on allow,
+ * or an error message string on deny. Callers stringify the error into a
+ * `{error}` payload so the model sees a structured rejection.
+ *
+ * The path is normalized (`..` collapsed) but symlinks are NOT followed.
+ * Caller is responsible for ensuring `filePath` is already absolute — the
+ * Read/Write/Edit tools enforce that at the top of `execute`.
+ */
+export function checkFilesystemAccess(filePath) {
+    if (!isSandboxEnabled())
+        return null;
+    const resolved = resolvePath(filePath);
+    // Allow path === root and any descendant. The separator suffix avoids
+    // `WORKSPACE_DIR-sibling` style false-allows.
+    if (resolved === WORKSPACE_DIR)
+        return null;
+    const prefix = WORKSPACE_DIR.endsWith("/") ? WORKSPACE_DIR : `${WORKSPACE_DIR}/`;
+    if (resolved.startsWith(prefix))
+        return null;
+    return (`Sandbox: path '${filePath}' is outside the workspace root (${WORKSPACE_DIR}). ` +
+        `Unset ${ENV_ENABLED} or scope the operation under the workspace.`);
+}
+/** Whether the sandbox is currently active. Default is OFF; the operator
+ *  opts in by exporting `MAESTRO_FS_SANDBOX_ENABLED=1`. Read each call so a
+ *  test can toggle it without restarting the process. */
+export function isSandboxEnabled() {
+    return process.env[ENV_ENABLED] === "1";
+}
+export const __ENV_ENABLED = ENV_ENABLED;
+//# sourceMappingURL=sandbox.js.map

package/dist/tools/builtin/sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.js","sourceRoot":"","sources":["../../../src/tools/builtin/sandbox.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,WAAW,GAAG,4BAA4B,CAAC;AAEjD;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAgB;IACpD,IAAI,CAAC,gBAAgB,EAAE;QAAE,OAAO,IAAI,CAAC;IACrC,MAAM,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;IACvC,sEAAsE;IACtE,8CAA8C;IAC9C,IAAI,QAAQ,KAAK,aAAa;QAAE,OAAO,IAAI,CAAC;IAC5C,MAAM,MAAM,GAAG,aAAa,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,GAAG,aAAa,GAAG,CAAC;IACjF,IAAI,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7C,OAAO,CACL,kBAAkB,QAAQ,oCAAoC,aAAa,KAAK;QAChF,SAAS,WAAW,8CAA8C,CACnE,CAAC;AACJ,CAAC;AAED;;yDAEyD;AACzD,MAAM,UAAU,gBAAgB;IAC9B,OAAO,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,KAAK,GAAG,CAAC;AAC1C,CAAC;AAED,MAAM,CAAC,MAAM,aAAa,GAAG,WAAW,CAAC"}

package/dist/tools/builtin/skill_view.d.ts

@@ -0,0 +1,37 @@
+import { type SkillEntry } from "../../skills/loader.js";
+import type { ToolHandler } from "../../tools/registry.js";
+/**
+ * `skill_view` builtin — progressive-disclosure entry point for skills.
+ *
+ * The Maestro system prompt advertises the catalog (name + 60-char summary).
+ * When the model decides a skill is relevant, it calls `skill_view(name=...)`
+ * to load the full SKILL.md body. We:
+ *
+ *   1. Look up the entry from the loaded skill set (case-insensitive
+ *      fallback handles model lowercasing).
+ *   2. Strip the YAML frontmatter so the model sees only the markdown body.
+ *   3. Apply `preprocessSkillContent` so `${MAESTRO_SKILL_DIR}` /
+ *      `${MAESTRO_SESSION_ID}` resolve to live values before the body is
+ *      handed to the model.
+ *   4. Prepend a `[Skill directory: ...]` hint so the model can resolve
+ *      relative paths in the body against the right cwd without needing to
+ *      ask. (Matches upstream `_build_skill_message` behavior.)
+ *
+ * Why a factory (not a module singleton): the loaded skill set + session
+ * id come from `maestroProvider` per turn, and we don't want a stale cache
+ * from a previous user's session leaking into this one. The factory closes
+ * over the per-turn skill list and session id, so multi-user safety falls
+ * out for free.
+ */
+export interface SkillViewToolOptions {
+    /** Already-loaded skill set for this turn. Comes from `loadSkills(rootDir)`. */
+    skills: SkillEntry[];
+    /** Active Maestro session id for `${MAESTRO_SESSION_ID}` substitution. */
+    sessionId?: string;
+    /** When true, enable `!\`cmd\`` inline-shell expansion during preprocessing.
+     *  Off by default — matches upstream's `skills.inline_shell: false` default
+     *  so an untrusted SKILL.md can't run code at load time. */
+    inlineShell?: boolean;
+}
+export declare function createSkillViewTool(opts: SkillViewToolOptions): ToolHandler;
+//# sourceMappingURL=skill_view.d.ts.map

package/dist/tools/builtin/skill_view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill_view.d.ts","sourceRoot":"","sources":["../../../src/tools/builtin/skill_view.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGpD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,WAAW,oBAAoB;IACnC,gFAAgF;IAChF,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;gEAE4D;IAC5D,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,oBAAoB,GAAG,WAAW,CAuE3E"}

package/dist/tools/builtin/skill_view.js

@@ -0,0 +1,82 @@
+import { findSkillByName } from "../../skills/loader.js";
+import { preprocessSkillContent } from "../../skills/preprocess.js";
+import { bumpView } from "../../skills/usage.js";
+import { logger } from "../../platform/logger.js";
+export function createSkillViewTool(opts) {
+    return {
+        // Pure catalog lookup + file read. `bumpView` mutates a usage counter
+        // on disk but it's idempotent and independent across skills, so parallel
+        // views never corrupt each other.
+        parallelSafe: true,
+        schema: {
+            name: "skill_view",
+            description: "Load the full SKILL.md body for a single skill by name. " +
+                "Call this whenever the Skills (mandatory) catalog lists a skill " +
+                "that matches or is partially relevant to your task — the body " +
+                "carries the actual commands, pitfalls, and workflows the index " +
+                "only summarizes.",
+            input_schema: {
+                type: "object",
+                properties: {
+                    name: {
+                        type: "string",
+                        description: "Skill name as shown in the <available_skills> list.",
+                    },
+                },
+                required: ["name"],
+            },
+        },
+        async execute(input) {
+            const wanted = typeof input.name === "string" ? input.name : "";
+            if (!wanted.trim()) {
+                return JSON.stringify({ error: "skill_view: missing 'name' argument" });
+            }
+            const entry = findSkillByName(opts.skills, wanted);
+            if (!entry) {
+                return JSON.stringify({
+                    error: `skill_view: no skill named '${wanted}' in the loaded catalog`,
+                    available: opts.skills.map((s) => s.name),
+                });
+            }
+            // Strip the leading `---\nYAML\n---\n` block — the model never needs
+            // to see the raw frontmatter, and including it wastes tokens.
+            const body = stripFrontmatter(entry.raw);
+            const resolved = preprocessSkillContent(body, {
+                skillDir: entry.skillDir,
+                sessionId: opts.sessionId ?? null,
+                inlineShell: opts.inlineShell ?? false,
+            });
+            const parts = [];
+            parts.push(`# ${entry.name}`);
+            if (entry.description)
+                parts.push(entry.description);
+            parts.push("");
+            parts.push(`[Skill directory: ${entry.skillDir}]`);
+            parts.push("Resolve any relative paths in this skill (e.g. `scripts/foo.js`, `templates/x.yaml`) " +
+                "against that directory, then run them with the bash tool using the absolute path.");
+            parts.push("");
+            parts.push(resolved.trim());
+            // Telemetry: bump the usage sidecar so the Curator can later spot
+            // skills the model never pulls. Fire-and-forget — a failed write
+            // (disk full / permission) must never break the tool call. We log
+            // the rejection at debug so operators can investigate if counters
+            // mysteriously stay at zero.
+            bumpView(entry.name).catch((err) => {
+                logger.debug({ err, skill: entry.name }, "skill_view: usage bump failed (continuing)");
+            });
+            return parts.join("\n");
+        },
+    };
+}
+/** Drop the leading `---\n...\n---\n` YAML block. No-op when the file has no
+ *  frontmatter (defensive — SKILL.md files in the wild are usually well-formed
+ *  but a malformed entry shouldn't crash the load). */
+function stripFrontmatter(raw) {
+    if (!raw.startsWith("---"))
+        return raw;
+    const closeMatch = /\n---[ \t]*(?:\n|$)/.exec(raw.slice(3));
+    if (!closeMatch)
+        return raw;
+    return raw.slice(closeMatch.index + 3 + closeMatch[0].length);
+}
+//# sourceMappingURL=skill_view.js.map

package/dist/tools/builtin/skill_view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill_view.js","sourceRoot":"","sources":["../../../src/tools/builtin/skill_view.ts"],"names":[],"mappings":"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"}