@codingame/monaco-vscode-api 26.1.1 → 26.1.2

package/vscode/src/vs/workbench/contrib/chat/common/promptSyntax/hookSchema.d.ts

@@ -0,0 +1,159 @@
+import { IJSONSchema } from "../../../../../base/common/jsonSchema.js";
+import { URI } from "../../../../../base/common/uri.js";
+import { OperatingSystem } from "../../../../../base/common/platform.js";
+/**
+ * Enum of available hook types that can be configured in hooks .json
+ */
+export declare enum HookType {
+    SessionStart = "SessionStart",
+    UserPromptSubmit = "UserPromptSubmit",
+    PreToolUse = "PreToolUse",
+    PostToolUse = "PostToolUse",
+    PreCompact = "PreCompact",
+    SubagentStart = "SubagentStart",
+    SubagentStop = "SubagentStop",
+    Stop = "Stop"
+}
+/**
+ * String literal type derived from HookType enum values.
+ */
+export type HookTypeValue = `${HookType}`;
+/**
+ * Metadata for hook types including localized labels and descriptions
+ */
+export declare const HOOK_TYPES: readonly [
+    {
+        readonly id: HookType.SessionStart;
+        readonly label: string;
+        readonly description: string;
+    },
+    {
+        readonly id: HookType.UserPromptSubmit;
+        readonly label: string;
+        readonly description: string;
+    },
+    {
+        readonly id: HookType.PreToolUse;
+        readonly label: string;
+        readonly description: string;
+    },
+    {
+        readonly id: HookType.PostToolUse;
+        readonly label: string;
+        readonly description: string;
+    },
+    {
+        readonly id: HookType.PreCompact;
+        readonly label: string;
+        readonly description: string;
+    },
+    {
+        readonly id: HookType.SubagentStart;
+        readonly label: string;
+        readonly description: string;
+    },
+    {
+        readonly id: HookType.SubagentStop;
+        readonly label: string;
+        readonly description: string;
+    },
+    {
+        readonly id: HookType.Stop;
+        readonly label: string;
+        readonly description: string;
+    }
+];
+/**
+ * A single hook command configuration.
+ */
+export interface IHookCommand {
+    readonly type: "command";
+    /** Cross-platform command to execute. */
+    readonly command?: string;
+    /** Windows-specific command override. */
+    readonly windows?: string;
+    /** Linux-specific command override. */
+    readonly linux?: string;
+    /** macOS-specific command override. */
+    readonly osx?: string;
+    /** Resolved working directory URI. */
+    readonly cwd?: URI;
+    readonly env?: Record<string, string>;
+    readonly timeout?: number;
+    /** Original JSON field name that provided the windows command. */
+    readonly windowsSource?: "windows" | "powershell";
+    /** Original JSON field name that provided the linux command. */
+    readonly linuxSource?: "linux" | "bash";
+    /** Original JSON field name that provided the osx command. */
+    readonly osxSource?: "osx" | "bash";
+}
+/**
+ * Collected hooks for a chat request, organized by hook type.
+ * This is passed to the extension host so it knows what hooks are available.
+ */
+export interface IChatRequestHooks {
+    readonly [HookType.SessionStart]?: readonly IHookCommand[];
+    readonly [HookType.UserPromptSubmit]?: readonly IHookCommand[];
+    readonly [HookType.PreToolUse]?: readonly IHookCommand[];
+    readonly [HookType.PostToolUse]?: readonly IHookCommand[];
+    readonly [HookType.PreCompact]?: readonly IHookCommand[];
+    readonly [HookType.SubagentStart]?: readonly IHookCommand[];
+    readonly [HookType.SubagentStop]?: readonly IHookCommand[];
+    readonly [HookType.Stop]?: readonly IHookCommand[];
+}
+export declare const hookFileSchema: IJSONSchema;
+/**
+ * URI for the hook schema registration.
+ */
+export declare const HOOK_SCHEMA_URI = "vscode://schemas/hooks";
+/**
+ * Glob pattern for hook files.
+ */
+export declare const HOOK_FILE_GLOB = ".github/hooks/*.json";
+/**
+ * Normalizes a raw hook type identifier to the canonical HookType enum value.
+ * Only matches exact enum values. For tool-specific naming conventions (e.g., Claude, Copilot CLI),
+ * use the corresponding compat module's resolver function.
+ */
+export declare function toHookType(rawHookTypeId: string): HookType | undefined;
+/**
+ * Gets a label for the given platform.
+ */
+export declare function getPlatformLabel(os: OperatingSystem): string;
+/**
+ * Resolves the effective command for the given platform.
+ * This applies OS-specific overrides (windows, linux, osx) to get the actual command that will be executed.
+ * Similar to how launch.json handles platform-specific configurations in debugAdapter.ts.
+ */
+export declare function resolveEffectiveCommand(hook: IHookCommand, os: OperatingSystem): string | undefined;
+/**
+ * Checks if the hook is using a platform-specific command override.
+ */
+export declare function isUsingPlatformOverride(hook: IHookCommand, os: OperatingSystem): boolean;
+/**
+ * Gets the source shell type for the effective command on the given platform.
+ * Returns 'powershell' if the Windows command came from a powershell field,
+ * 'bash' if the Linux/macOS command came from a bash field,
+ * or undefined for default shell handling.
+ */
+export declare function getEffectiveCommandSource(hook: IHookCommand, os: OperatingSystem): "powershell" | "bash" | undefined;
+/**
+ * Gets the original JSON field key name for the given platform's command.
+ * Returns the actual field name from the JSON (e.g., 'bash' instead of 'osx' if bash was used).
+ * This is used for editor focus to highlight the correct field.
+ */
+export declare function getEffectiveCommandFieldKey(hook: IHookCommand, os: OperatingSystem): string;
+/**
+ * Formats a hook command for display.
+ * Resolves OS-specific overrides to show the effective command for the given platform.
+ * If using a platform-specific override, includes the platform as a prefix badge.
+ */
+export declare function formatHookCommandLabel(hook: IHookCommand, os: OperatingSystem): string;
+/**
+ * Resolves a raw hook command object to the canonical IHookCommand format.
+ * Normalizes the command and resolves the cwd path relative to the workspace root.
+ * @param raw The raw hook command object from JSON
+ * @param workspaceRootUri The workspace root URI to resolve relative cwd paths against
+ * @param userHome The user's home directory path for tilde expansion
+ */
+export declare function resolveHookCommand(raw: Record<string, unknown>, workspaceRootUri: URI | undefined, userHome: string): IHookCommand | undefined;

package/vscode/src/vs/workbench/contrib/chat/common/promptSyntax/hookSchema.js

@@ -0,0 +1,387 @@
+
+import { localize } from '../../../../../nls.js';
+import { URI } from '../../../../../base/common/uri.js';
+import { joinPath } from '../../../../../base/common/resources.js';
+import { isAbsolute } from '../../../../../base/common/path.js';
+import { untildify } from '../../../../../base/common/labels.js';
+import { OperatingSystem } from '../../../../../base/common/platform.js';
+
+var HookType;
+(function(HookType) {
+    HookType["SessionStart"] = "SessionStart";
+    HookType["UserPromptSubmit"] = "UserPromptSubmit";
+    HookType["PreToolUse"] = "PreToolUse";
+    HookType["PostToolUse"] = "PostToolUse";
+    HookType["PreCompact"] = "PreCompact";
+    HookType["SubagentStart"] = "SubagentStart";
+    HookType["SubagentStop"] = "SubagentStop";
+    HookType["Stop"] = "Stop";
+})(HookType || (HookType = {}));
+const HOOK_TYPES = [{
+    id: HookType.SessionStart,
+    label: ( localize(6375, "Session Start")),
+    description: ( localize(6376, "Executed when a new agent session begins."))
+}, {
+    id: HookType.UserPromptSubmit,
+    label: ( localize(6377, "User Prompt Submit")),
+    description: ( localize(6378, "Executed when the user submits a prompt to the agent."))
+}, {
+    id: HookType.PreToolUse,
+    label: ( localize(6379, "Pre-Tool Use")),
+    description: ( localize(6380, "Executed before the agent uses any tool."))
+}, {
+    id: HookType.PostToolUse,
+    label: ( localize(6381, "Post-Tool Use")),
+    description: ( localize(6382, "Executed after a tool completes execution successfully."))
+}, {
+    id: HookType.PreCompact,
+    label: ( localize(6383, "Pre-Compact")),
+    description: ( localize(6384, "Executed before the agent compacts the conversation context."))
+}, {
+    id: HookType.SubagentStart,
+    label: ( localize(6385, "Subagent Start")),
+    description: ( localize(6386, "Executed when a subagent is started."))
+}, {
+    id: HookType.SubagentStop,
+    label: ( localize(6387, "Subagent Stop")),
+    description: ( localize(6388, "Executed when a subagent stops."))
+}, {
+    id: HookType.Stop,
+    label: ( localize(6389, "Stop")),
+    description: ( localize(6390, "Executed when the agent stops."))
+}];
+const hookCommandSchema = {
+    type: "object",
+    additionalProperties: true,
+    required: ["type"],
+    anyOf: [{
+        required: ["command"]
+    }, {
+        required: ["windows"]
+    }, {
+        required: ["linux"]
+    }, {
+        required: ["osx"]
+    }, {
+        required: ["bash"]
+    }, {
+        required: ["powershell"]
+    }],
+    errorMessage: ( localize(
+        6391,
+        "At least one of \"command\", \"windows\", \"linux\", or \"osx\" must be specified."
+    )),
+    properties: {
+        type: {
+            type: "string",
+            enum: ["command"],
+            description: ( localize(6392, "Must be \"command\"."))
+        },
+        command: {
+            type: "string",
+            description: ( localize(
+                6393,
+                "The command to execute. This is the default cross-platform command."
+            ))
+        },
+        windows: {
+            type: "string",
+            description: ( localize(
+                6394,
+                "Windows-specific command. If specified and running on Windows, this overrides the \"command\" field."
+            ))
+        },
+        linux: {
+            type: "string",
+            description: ( localize(
+                6395,
+                "Linux-specific command. If specified and running on Linux, this overrides the \"command\" field."
+            ))
+        },
+        osx: {
+            type: "string",
+            description: ( localize(
+                6396,
+                "macOS-specific command. If specified and running on macOS, this overrides the \"command\" field."
+            ))
+        },
+        cwd: {
+            type: "string",
+            description: ( localize(6397, "Working directory for the script (relative to repository root)."))
+        },
+        env: {
+            type: "object",
+            additionalProperties: {
+                type: "string"
+            },
+            description: ( localize(
+                6398,
+                "Additional environment variables that are merged with the existing environment."
+            ))
+        },
+        timeout: {
+            type: "number",
+            default: 30,
+            description: ( localize(6399, "Maximum execution time in seconds (default: 30)."))
+        }
+    }
+};
+const hookArraySchema = {
+    type: "array",
+    items: hookCommandSchema
+};
+const hookFileSchema = {
+    $schema: "http://json-schema.org/draft-07/schema#",
+    type: "object",
+    description: ( localize(
+        6400,
+        "GitHub Copilot hook configuration file. Hooks enable executing custom shell commands at strategic points in an agent's workflow."
+    )),
+    additionalProperties: true,
+    required: ["hooks"],
+    properties: {
+        hooks: {
+            type: "object",
+            description: ( localize(6401, "Hook definitions organized by type.")),
+            additionalProperties: true,
+            properties: {
+                SessionStart: {
+                    ...hookArraySchema,
+                    description: ( localize(
+                        6402,
+                        "Executed when a new agent session begins. Use to initialize environments, log session starts, validate project state, or set up temporary resources."
+                    ))
+                },
+                UserPromptSubmit: {
+                    ...hookArraySchema,
+                    description: ( localize(
+                        6403,
+                        "Executed when the user submits a prompt to the agent. Use to log user requests for auditing and usage analysis."
+                    ))
+                },
+                PreToolUse: {
+                    ...hookArraySchema,
+                    description: ( localize(
+                        6404,
+                        "Executed before the agent uses any tool. This is the most powerful hook as it can approve or deny tool executions. Use to block dangerous commands, enforce security policies, require approval for sensitive operations, or log tool usage."
+                    ))
+                },
+                PostToolUse: {
+                    ...hookArraySchema,
+                    description: ( localize(
+                        6405,
+                        "Executed after a tool completes execution successfully. Use to log execution results, track usage statistics, generate audit trails, or monitor performance."
+                    ))
+                },
+                PreCompact: {
+                    ...hookArraySchema,
+                    description: ( localize(
+                        6406,
+                        "Executed before the agent compacts the conversation context. Use to save conversation state, export important information, or prepare for context reduction."
+                    ))
+                },
+                SubagentStart: {
+                    ...hookArraySchema,
+                    description: ( localize(
+                        6407,
+                        "Executed when a subagent is started. Use to log subagent spawning, track nested agent usage, or initialize subagent-specific resources."
+                    ))
+                },
+                SubagentStop: {
+                    ...hookArraySchema,
+                    description: ( localize(
+                        6408,
+                        "Executed when a subagent stops. Use to log subagent completion, cleanup subagent resources, or aggregate subagent results."
+                    ))
+                },
+                Stop: {
+                    ...hookArraySchema,
+                    description: ( localize(
+                        6409,
+                        "Executed when the agent session stops. Use to cleanup resources, generate final reports, or send completion notifications."
+                    ))
+                }
+            }
+        }
+    },
+    defaultSnippets: [{
+        label: ( localize(6410, "Basic hook configuration")),
+        description: ( localize(6411, "A basic hook configuration with common hooks")),
+        body: {
+            hooks: {
+                SessionStart: [{
+                    type: "command",
+                    command: "${1:echo \"Session started\" >> session.log}"
+                }],
+                PreToolUse: [{
+                    type: "command",
+                    command: "${2:./scripts/validate.sh}",
+                    timeout: 15
+                }]
+            }
+        }
+    }]
+};
+const HOOK_SCHEMA_URI = "vscode://schemas/hooks";
+const HOOK_FILE_GLOB = ".github/hooks/*.json";
+function toHookType(rawHookTypeId) {
+    if (( Object.values(HookType)).includes(rawHookTypeId)) {
+        return rawHookTypeId;
+    }
+    return undefined;
+}
+function normalizeHookCommand(raw) {
+    if (raw.type !== "command") {
+        return undefined;
+    }
+    const hasCommand = typeof raw.command === "string" && raw.command.length > 0;
+    const hasBash = typeof raw.bash === "string" && raw.bash.length > 0;
+    const hasPowerShell = typeof raw.powershell === "string" && raw.powershell.length > 0;
+    const hasWindows = typeof raw.windows === "string" && raw.windows.length > 0;
+    const hasLinux = typeof raw.linux === "string" && raw.linux.length > 0;
+    const hasOsx = typeof raw.osx === "string" && raw.osx.length > 0;
+    const windows = hasWindows ? raw.windows : (hasPowerShell ? raw.powershell : undefined);
+    const linux = hasLinux ? raw.linux : (hasBash ? raw.bash : undefined);
+    const osx = hasOsx ? raw.osx : (hasBash ? raw.bash : undefined);
+    const windowsSource = hasWindows ? "windows" : (hasPowerShell ? "powershell" : undefined);
+    const linuxSource = hasLinux ? "linux" : (hasBash ? "bash" : undefined);
+    const osxSource = hasOsx ? "osx" : (hasBash ? "bash" : undefined);
+    return {
+        ...(hasCommand && {
+            command: raw.command
+        }),
+        ...(windows && {
+            windows
+        }),
+        ...(linux && {
+            linux
+        }),
+        ...(osx && {
+            osx
+        }),
+        ...(windowsSource && {
+            windowsSource
+        }),
+        ...(linuxSource && {
+            linuxSource
+        }),
+        ...(osxSource && {
+            osxSource
+        }),
+        ...(typeof raw.cwd === "string" && {
+            cwd: raw.cwd
+        }),
+        ...(typeof raw.env === "object" && raw.env !== null && {
+            env: raw.env
+        }),
+        ...(typeof raw.timeout !== "number" && typeof raw.timeoutSec === "number" && {
+            timeout: raw.timeoutSec
+        }),
+        ...(typeof raw.timeout === "number" && {
+            timeout: raw.timeout
+        })
+    };
+}
+function getPlatformLabel(os) {
+    if (os === OperatingSystem.Windows) {
+        return "Windows";
+    } else if (os === OperatingSystem.Macintosh) {
+        return "macOS";
+    } else if (os === OperatingSystem.Linux) {
+        return "Linux";
+    }
+    return "";
+}
+function resolveEffectiveCommand(hook, os) {
+    if (os === OperatingSystem.Windows && hook.windows) {
+        return hook.windows;
+    } else if (os === OperatingSystem.Macintosh && hook.osx) {
+        return hook.osx;
+    } else if (os === OperatingSystem.Linux && hook.linux) {
+        return hook.linux;
+    }
+    return hook.command;
+}
+function isUsingPlatformOverride(hook, os) {
+    if (os === OperatingSystem.Windows && hook.windows) {
+        return true;
+    } else if (os === OperatingSystem.Macintosh && hook.osx) {
+        return true;
+    } else if (os === OperatingSystem.Linux && hook.linux) {
+        return true;
+    }
+    return false;
+}
+function getEffectiveCommandFieldKey(hook, os) {
+    if (os === OperatingSystem.Windows && hook.windows) {
+        return hook.windowsSource ?? "windows";
+    } else if (os === OperatingSystem.Macintosh && hook.osx) {
+        return hook.osxSource ?? "osx";
+    } else if (os === OperatingSystem.Linux && hook.linux) {
+        return hook.linuxSource ?? "linux";
+    }
+    return "command";
+}
+function formatHookCommandLabel(hook, os) {
+    const command = resolveEffectiveCommand(hook, os);
+    if (!command) {
+        return "";
+    }
+    if (isUsingPlatformOverride(hook, os)) {
+        const platformLabel = getPlatformLabel(os);
+        return `[${platformLabel}] ${command}`;
+    }
+    return command;
+}
+function resolveHookCommand(raw, workspaceRootUri, userHome) {
+    const normalized = normalizeHookCommand(raw);
+    if (!normalized) {
+        return undefined;
+    }
+    let cwdUri;
+    if (normalized.cwd) {
+        const expandedCwd = untildify(normalized.cwd, userHome);
+        if (isAbsolute(expandedCwd)) {
+            cwdUri = URI.file(expandedCwd);
+        } else if (workspaceRootUri) {
+            cwdUri = joinPath(workspaceRootUri, expandedCwd);
+        }
+    } else {
+        cwdUri = workspaceRootUri;
+    }
+    return {
+        type: "command",
+        ...(normalized.command && {
+            command: normalized.command
+        }),
+        ...(normalized.windows && {
+            windows: normalized.windows
+        }),
+        ...(normalized.linux && {
+            linux: normalized.linux
+        }),
+        ...(normalized.osx && {
+            osx: normalized.osx
+        }),
+        ...(normalized.windowsSource && {
+            windowsSource: normalized.windowsSource
+        }),
+        ...(normalized.linuxSource && {
+            linuxSource: normalized.linuxSource
+        }),
+        ...(normalized.osxSource && {
+            osxSource: normalized.osxSource
+        }),
+        ...(cwdUri && {
+            cwd: cwdUri
+        }),
+        ...(normalized.env && {
+            env: normalized.env
+        }),
+        ...(normalized.timeout !== undefined && {
+            timeout: normalized.timeout
+        })
+    };
+}
+
+export { HOOK_FILE_GLOB, HOOK_SCHEMA_URI, HOOK_TYPES, HookType, formatHookCommandLabel, getEffectiveCommandFieldKey, getPlatformLabel, hookFileSchema, isUsingPlatformOverride, resolveEffectiveCommand, resolveHookCommand, toHookType };

package/vscode/src/vs/workbench/contrib/chat/common/promptSyntax/promptFileParser.d.ts

@@ -1,5 +1,6 @@
 import { URI } from "../../../../../base/common/uri.js";
 import { Range } from "../../../../../editor/common/core/range.js";
+import { Target } from "./service/promptsService.js";
 export declare class PromptFileParser {
     constructor();
     parse(uri: URI, content: string): ParsedPromptFile;
@@ -22,6 +23,7 @@ export declare namespace PromptHeaderAttributes {
     const mode = "mode";
     const model = "model";
     const applyTo = "applyTo";
+    const paths = "paths";
     const tools = "tools";
     const handOffs = "handoffs";
     const advancedOptions = "advancedOptions";
@@ -39,15 +41,16 @@ export declare namespace PromptHeaderAttributes {
 export declare namespace GithubPromptHeaderAttributes {
     const mcpServers = "mcp-servers";
 }
-export declare enum Target {
-    VSCode = "vscode",
-    GitHubCopilot = "github-copilot"
+export declare namespace ClaudeHeaderAttributes {
+    const disallowedTools = "disallowedTools";
 }
+export declare function isTarget(value: unknown): value is Target;
 export declare class PromptHeader {
     readonly range: Range;
+    readonly uri: URI;
     private readonly linesWithEOL;
     private _parsed;
-    constructor(range: Range, linesWithEOL: string[]);
+    constructor(range: Range, uri: URI, linesWithEOL: string[]);
     private get _parsedHeader();
     private asRange;
     private asValue;
@@ -60,6 +63,12 @@ export declare class PromptHeader {
     get agent(): string | undefined;
     get model(): readonly string[] | undefined;
     get applyTo(): string | undefined;
+    /**
+     * Gets the 'paths' attribute from the header.
+     * The `paths` field supports a list of glob patterns that scope the instruction
+     * to specific files (used by Claude rules). Returns a string array or undefined.
+     */
+    get paths(): readonly string[] | undefined;
     get argumentHint(): string | undefined;
     get target(): string | undefined;
     get infer(): boolean | undefined;
@@ -142,3 +151,11 @@ export interface IBodyVariableReference {
     readonly range: Range;
     readonly offset: number;
 }
+/**
+ * Parses a comma-separated list of values into an array of strings.
+ * Values can be unquoted or quoted (single or double quotes).
+ *
+ * @param input A string containing comma-separated values
+ * @returns An IArrayValue containing the parsed values and their ranges
+ */
+export declare function parseCommaSeparatedList(stringValue: IStringValue): IArrayValue;