Merge pull request #2085 from dyoshikawa/resolve-issue-2079-copilotcli-skill-hint-hook

feat(copilotcli): support skill argument-hint frontmatter and preMcpToolCall hook event

Author: dyoshikawa

docs/reference/file-formats.md

@@ -143,7 +143,7 @@ Events present in the shared `hooks` block but unsupported by a given tool are s
 | `afterFileEdit`        |   ✅   |      —      |    ✅    |  ✅  |    —    |      —      |       —       |     —      |     —     |     —      |  —   |        —        |        —        |  ✅   |      —      |  ✅   |
 | `beforeShellExecution` |   ✅   |      —      |    —     |  —   |    —    |      —      |       —       |     —      |     —     |     —      |  —   |        —        |        —        |  ✅   |      —      |  ✅   |
 | `afterShellExecution`  |   ✅   |      —      |    ✅    |  ✅  |    —    |      —      |       —       |     —      |     —     |     —      |  —   |        —        |        —        |  ✅   |      —      |  ✅   |
-| `beforeMCPExecution`   |   ✅   |      —      |    —     |  —   |    —    |      —      |       —       |     —      |     —     |     —      |  —   |        —        |        —        |  ✅   |      —      |   —   |
+| `beforeMCPExecution`   |   ✅   |      —      |    —     |  —   |    —    |     ✅      |       —       |     —      |     —     |     —      |  —   |        —        |        —        |  ✅   |      —      |   —   |
 | `afterMCPExecution`    |   ✅   |      —      |    —     |  —   |    —    |      —      |       —       |     —      |     —     |     —      |  —   |        —        |        —        |  ✅   |      —      |   —   |
 | `beforeReadFile`       |   ✅   |      —      |    —     |  —   |    —    |      —      |       —       |     —      |     —     |     —      |  —   |        —        |        —        |  ✅   |      —      |  ✅   |
 | `beforeAgentResponse`  |   —    |      —      |    —     |  —   |    —    |      —      |       —       |     ✅     |     —     |     —      |  —   |        —        |        —        |  ✅   |      —      |   —   |
@@ -183,7 +183,7 @@ Events present in the shared `hooks` block but unsupported by a given tool are s
 > **Note:** Hook file paths per tool:
 >
 > - **Copilot (cloud agent)** — `<project>/.github/hooks/copilot-hooks.json`.
-> - **Copilot CLI** — project: `<project>/.github/hooks/copilotcli-hooks.json`; global: `~/.copilot/hooks/copilot-hooks.json`. The Copilot CLI docs let you choose any filename inside `.github/hooks/`, so Rulesync uses the CLI-specific name to avoid colliding with the cloud-agent file when both targets are enabled. The global path is a Rulesync convention; the official Copilot CLI documentation does not currently enumerate a global hooks location, so this placement may change if the spec later mandates an alternate layout. Copilot CLI uses a **wider event surface** than the shared cloud-agent set (`sessionStart`, `sessionEnd`, `userPromptSubmitted`, `preToolUse`, `postToolUse`, `postToolUseFailure`, `agentStop` ← `stop`, `subagentStart`, `subagentStop`, `errorOccurred` ← `afterError`, `preCompact`, `permissionRequest`, `notification`) and supports three hook types: **`command`** (`bash`/`powershell` with optional `timeoutSec`, plus pass-through `cwd`/`env`), **`prompt`** (a `prompt` string — Copilot CLI only honors prompt hooks on `sessionStart`, so prompt hooks on other events are dropped), and **`http`** (`url`/`headers`/`allowedEnvVars` with optional `timeoutSec`). On `preToolUse` / `postToolUse`, an entry's optional `matcher` field (a regex compiled as `^(?:PATTERN)$`, tested against the tool name) is emitted and round-tripped; on any other event a matcher is dropped (with a warning) because the CLI does not honor it there ([changelog v1.0.36, 2026-04-24](https://github.com/github/copilot-cli) and [v1.0.63, 2026-06-15](https://github.com/github/copilot-cli)).
+> - **Copilot CLI** — project: `<project>/.github/hooks/copilotcli-hooks.json`; global: `~/.copilot/hooks/copilot-hooks.json`. The Copilot CLI docs let you choose any filename inside `.github/hooks/`, so Rulesync uses the CLI-specific name to avoid colliding with the cloud-agent file when both targets are enabled. The global path is a Rulesync convention; the official Copilot CLI documentation does not currently enumerate a global hooks location, so this placement may change if the spec later mandates an alternate layout. Copilot CLI uses a **wider event surface** than the shared cloud-agent set (`sessionStart`, `sessionEnd`, `userPromptSubmitted`, `preToolUse`, `postToolUse`, `postToolUseFailure`, `agentStop` ← `stop`, `subagentStart`, `subagentStop`, `errorOccurred` ← `afterError`, `preCompact`, `permissionRequest`, `notification`, `preMcpToolCall` ← `beforeMCPExecution`) and supports three hook types: **`command`** (`bash`/`powershell` with optional `timeoutSec`, plus pass-through `cwd`/`env`), **`prompt`** (a `prompt` string — Copilot CLI only honors prompt hooks on `sessionStart`, so prompt hooks on other events are dropped), and **`http`** (`url`/`headers`/`allowedEnvVars` with optional `timeoutSec`). On `preToolUse` / `postToolUse`, an entry's optional `matcher` field (a regex compiled as `^(?:PATTERN)$`, tested against the tool name) is emitted and round-tripped; on any other event a matcher is dropped (with a warning) because the CLI does not honor it there ([changelog v1.0.36, 2026-04-24](https://github.com/github/copilot-cli) and [v1.0.63, 2026-06-15](https://github.com/github/copilot-cli)).
 > - **Antigravity IDE / Antigravity CLI** — project: `<project>/.agents/hooks.json`; global: `~/.gemini/config/hooks.json`. Both targets share the same dedicated `hooks.json` (a Claude-Code-style matcher map nested under a generated `rulesync` hook name), so enabling both writes the same file.
 > - **Devin Desktop (formerly Windsurf)** — project: `<project>/.windsurf/hooks.json`; global: `~/.codeium/windsurf/hooks.json`. The Cascade Hooks file location is unchanged by the Devin Desktop rebrand.
 > - **AugmentCode** — project: `<project>/.augment/settings.json`; global: `~/.augment/settings.json`. Hooks are merged under the top-level `hooks` key of the shared settings file (which also holds `toolPermissions`).
@@ -506,6 +506,7 @@ copilot: # for GitHub Copilot-specific parameters (optional)
 copilotcli: # for GitHub Copilot CLI-specific parameters (optional; project .github/skills/, global ~/.copilot/skills/)
   license: MIT # (optional)
   allowed-tools: "shell" # (optional) tools pre-approved without per-use confirmation
+  argument-hint: "[message]" # (optional) hint shown for the skill's expected arguments
 rovodev: # for Rovo Dev CLI-specific parameters (optional; Agent Skills standard)
   allowed-tools: "grep bash" # (optional) space-separated string (a YAML list is also accepted)
   license: MIT # (optional)

skills/rulesync/file-formats.md

@@ -143,7 +143,7 @@ Events present in the shared `hooks` block but unsupported by a given tool are s
 | `afterFileEdit`        |   ✅   |      —      |    ✅    |  ✅  |    —    |      —      |       —       |     —      |     —     |     —      |  —   |        —        |        —        |  ✅   |      —      |  ✅   |
 | `beforeShellExecution` |   ✅   |      —      |    —     |  —   |    —    |      —      |       —       |     —      |     —     |     —      |  —   |        —        |        —        |  ✅   |      —      |  ✅   |
 | `afterShellExecution`  |   ✅   |      —      |    ✅    |  ✅  |    —    |      —      |       —       |     —      |     —     |     —      |  —   |        —        |        —        |  ✅   |      —      |  ✅   |
-| `beforeMCPExecution`   |   ✅   |      —      |    —     |  —   |    —    |      —      |       —       |     —      |     —     |     —      |  —   |        —        |        —        |  ✅   |      —      |   —   |
+| `beforeMCPExecution`   |   ✅   |      —      |    —     |  —   |    —    |     ✅      |       —       |     —      |     —     |     —      |  —   |        —        |        —        |  ✅   |      —      |   —   |
 | `afterMCPExecution`    |   ✅   |      —      |    —     |  —   |    —    |      —      |       —       |     —      |     —     |     —      |  —   |        —        |        —        |  ✅   |      —      |   —   |
 | `beforeReadFile`       |   ✅   |      —      |    —     |  —   |    —    |      —      |       —       |     —      |     —     |     —      |  —   |        —        |        —        |  ✅   |      —      |  ✅   |
 | `beforeAgentResponse`  |   —    |      —      |    —     |  —   |    —    |      —      |       —       |     ✅     |     —     |     —      |  —   |        —        |        —        |  ✅   |      —      |   —   |
@@ -183,7 +183,7 @@ Events present in the shared `hooks` block but unsupported by a given tool are s
 > **Note:** Hook file paths per tool:
 >
 > - **Copilot (cloud agent)** — `<project>/.github/hooks/copilot-hooks.json`.
-> - **Copilot CLI** — project: `<project>/.github/hooks/copilotcli-hooks.json`; global: `~/.copilot/hooks/copilot-hooks.json`. The Copilot CLI docs let you choose any filename inside `.github/hooks/`, so Rulesync uses the CLI-specific name to avoid colliding with the cloud-agent file when both targets are enabled. The global path is a Rulesync convention; the official Copilot CLI documentation does not currently enumerate a global hooks location, so this placement may change if the spec later mandates an alternate layout. Copilot CLI uses a **wider event surface** than the shared cloud-agent set (`sessionStart`, `sessionEnd`, `userPromptSubmitted`, `preToolUse`, `postToolUse`, `postToolUseFailure`, `agentStop` ← `stop`, `subagentStart`, `subagentStop`, `errorOccurred` ← `afterError`, `preCompact`, `permissionRequest`, `notification`) and supports three hook types: **`command`** (`bash`/`powershell` with optional `timeoutSec`, plus pass-through `cwd`/`env`), **`prompt`** (a `prompt` string — Copilot CLI only honors prompt hooks on `sessionStart`, so prompt hooks on other events are dropped), and **`http`** (`url`/`headers`/`allowedEnvVars` with optional `timeoutSec`). On `preToolUse` / `postToolUse`, an entry's optional `matcher` field (a regex compiled as `^(?:PATTERN)$`, tested against the tool name) is emitted and round-tripped; on any other event a matcher is dropped (with a warning) because the CLI does not honor it there ([changelog v1.0.36, 2026-04-24](https://github.com/github/copilot-cli) and [v1.0.63, 2026-06-15](https://github.com/github/copilot-cli)).
+> - **Copilot CLI** — project: `<project>/.github/hooks/copilotcli-hooks.json`; global: `~/.copilot/hooks/copilot-hooks.json`. The Copilot CLI docs let you choose any filename inside `.github/hooks/`, so Rulesync uses the CLI-specific name to avoid colliding with the cloud-agent file when both targets are enabled. The global path is a Rulesync convention; the official Copilot CLI documentation does not currently enumerate a global hooks location, so this placement may change if the spec later mandates an alternate layout. Copilot CLI uses a **wider event surface** than the shared cloud-agent set (`sessionStart`, `sessionEnd`, `userPromptSubmitted`, `preToolUse`, `postToolUse`, `postToolUseFailure`, `agentStop` ← `stop`, `subagentStart`, `subagentStop`, `errorOccurred` ← `afterError`, `preCompact`, `permissionRequest`, `notification`, `preMcpToolCall` ← `beforeMCPExecution`) and supports three hook types: **`command`** (`bash`/`powershell` with optional `timeoutSec`, plus pass-through `cwd`/`env`), **`prompt`** (a `prompt` string — Copilot CLI only honors prompt hooks on `sessionStart`, so prompt hooks on other events are dropped), and **`http`** (`url`/`headers`/`allowedEnvVars` with optional `timeoutSec`). On `preToolUse` / `postToolUse`, an entry's optional `matcher` field (a regex compiled as `^(?:PATTERN)$`, tested against the tool name) is emitted and round-tripped; on any other event a matcher is dropped (with a warning) because the CLI does not honor it there ([changelog v1.0.36, 2026-04-24](https://github.com/github/copilot-cli) and [v1.0.63, 2026-06-15](https://github.com/github/copilot-cli)).
 > - **Antigravity IDE / Antigravity CLI** — project: `<project>/.agents/hooks.json`; global: `~/.gemini/config/hooks.json`. Both targets share the same dedicated `hooks.json` (a Claude-Code-style matcher map nested under a generated `rulesync` hook name), so enabling both writes the same file.
 > - **Devin Desktop (formerly Windsurf)** — project: `<project>/.windsurf/hooks.json`; global: `~/.codeium/windsurf/hooks.json`. The Cascade Hooks file location is unchanged by the Devin Desktop rebrand.
 > - **AugmentCode** — project: `<project>/.augment/settings.json`; global: `~/.augment/settings.json`. Hooks are merged under the top-level `hooks` key of the shared settings file (which also holds `toolPermissions`).
@@ -506,6 +506,7 @@ copilot: # for GitHub Copilot-specific parameters (optional)
 copilotcli: # for GitHub Copilot CLI-specific parameters (optional; project .github/skills/, global ~/.copilot/skills/)
   license: MIT # (optional)
   allowed-tools: "shell" # (optional) tools pre-approved without per-use confirmation
+  argument-hint: "[message]" # (optional) hint shown for the skill's expected arguments
 rovodev: # for Rovo Dev CLI-specific parameters (optional; Agent Skills standard)
   allowed-tools: "grep bash" # (optional) space-separated string (a YAML list is also accepted)
   license: MIT # (optional)

src/features/hooks/copilotcli-hooks.test.ts

@@ -156,6 +156,7 @@ describe("CopilotcliHooks", () => {
           preCompact: [{ command: "echo compact" }],
           permissionRequest: [{ command: "echo perm" }],
           notification: [{ command: "echo notify" }],
+          beforeMCPExecution: [{ command: "echo mcp" }],
         },
       };
       const rulesyncHooks = new RulesyncHooks({
@@ -177,6 +178,47 @@ describe("CopilotcliHooks", () => {
       expect(parsed.hooks.preCompact).toBeDefined();
       expect(parsed.hooks.permissionRequest).toBeDefined();
       expect(parsed.hooks.notification).toBeDefined();
+      // `beforeMCPExecution` maps to Copilot CLI's `preMcpToolCall` (v1.0.51).
+      expect(parsed.hooks.preMcpToolCall).toBeDefined();
+    });
+
+    it("round-trips the preMcpToolCall hook event", async () => {
+      const copilotConfig = {
+        version: 1,
+        hooks: {
+          preMcpToolCall: [{ type: "command", bash: "echo mcp" }],
+        },
+      };
+      const imported = new CopilotcliHooks({
+        outputRoot: testDir,
+        relativeDirPath: ".github/hooks",
+        relativeFilePath: "copilotcli-hooks.json",
+        fileContent: JSON.stringify(copilotConfig),
+        validate: false,
+      });
+
+      // Import maps `preMcpToolCall` back to canonical `beforeMCPExecution`.
+      const canonical = JSON.parse(imported.toRulesyncHooks().getFileContent());
+      expect(canonical.hooks.beforeMCPExecution).toBeDefined();
+      expect(canonical.hooks.beforeMCPExecution[0]).toMatchObject({
+        type: "command",
+        command: "echo mcp",
+      });
+
+      // Re-export emits the Copilot CLI event name again.
+      const rulesyncHooks = new RulesyncHooks({
+        outputRoot: testDir,
+        relativeDirPath: RULESYNC_RELATIVE_DIR_PATH,
+        relativeFilePath: "hooks.json",
+        fileContent: JSON.stringify(canonical),
+        validate: false,
+      });
+      const reExported = await CopilotcliHooks.fromRulesyncHooks({
+        outputRoot: testDir,
+        rulesyncHooks,
+      });
+      const parsed = JSON.parse(reExported.getFileContent());
+      expect(parsed.hooks.preMcpToolCall).toBeDefined();
     });
 
     it("emits prompt and http hook types and preserves cwd/env", async () => {

src/features/hooks/copilotcli-hooks.ts

@@ -38,7 +38,7 @@ import {
  * (`sessionStart`, `sessionEnd`, `userPromptSubmitted`, `preToolUse`,
  * `postToolUse`, `postToolUseFailure`, `agentStop`, `subagentStart`,
  * `subagentStop`, `errorOccurred`, `preCompact`, `permissionRequest`,
- * `notification`). Each entry supports three hook types:
+ * `notification`, `preMcpToolCall`). Each entry supports three hook types:
  *
  * - `command` — the `bash` / `powershell` command-field shape with optional
  *   `timeoutSec`, plus optional `cwd` / `env`.

src/features/skills/copilotcli-skill.test.ts

@@ -230,6 +230,26 @@ Skill content goes here.`,
       const roundTripped = CopilotcliSkill.fromRulesyncSkill({ rulesyncSkill });
       expect(roundTripped.getFrontmatter()["allowed-tools"]).toBe("shell");
     });
+
+    it("should round-trip the argument-hint skill frontmatter", () => {
+      const skill = new CopilotcliSkill({
+        dirName: "hint-skill",
+        frontmatter: {
+          name: "hint-skill",
+          description: "Takes an argument",
+          "argument-hint": "[message]",
+        },
+        body: "body",
+      });
+
+      const rulesyncSkill = skill.toRulesyncSkill();
+      expect(rulesyncSkill.getFrontmatter().copilotcli).toEqual({
+        "argument-hint": "[message]",
+      });
+
+      const roundTripped = CopilotcliSkill.fromRulesyncSkill({ rulesyncSkill });
+      expect(roundTripped.getFrontmatter()["argument-hint"]).toBe("[message]");
+    });
   });
 
   describe("isTargetedByRulesyncSkill", () => {

src/features/skills/copilotcli-skill.ts

@@ -26,6 +26,9 @@ export const CopilotcliSkillFrontmatterSchema = z.looseObject({
   // Pre-approved tools the agent may run without per-use confirmation.
   // https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills
   "allowed-tools": z.optional(z.union([z.string(), z.array(z.string())])),
+  // Hint shown for the skill's expected arguments. Added in Copilot CLI v1.0.62
+  // (2026-06-13). https://github.com/github/copilot-cli/blob/main/changelog.md
+  "argument-hint": z.optional(z.string()),
 });
 
 export type CopilotcliSkillFrontmatter = z.infer<typeof CopilotcliSkillFrontmatterSchema>;
@@ -129,6 +132,9 @@ export class CopilotcliSkill extends ToolSkill {
       ...(frontmatter["allowed-tools"] !== undefined && {
         "allowed-tools": frontmatter["allowed-tools"],
       }),
+      ...(frontmatter["argument-hint"] !== undefined && {
+        "argument-hint": frontmatter["argument-hint"],
+      }),
     };
     const rulesyncFrontmatter: RulesyncSkillFrontmatterInput = {
       name: frontmatter.name,
@@ -167,6 +173,9 @@ export class CopilotcliSkill extends ToolSkill {
       ...(rulesyncFrontmatter.copilotcli?.["allowed-tools"] !== undefined && {
         "allowed-tools": rulesyncFrontmatter.copilotcli["allowed-tools"],
       }),
+      ...(rulesyncFrontmatter.copilotcli?.["argument-hint"] !== undefined && {
+        "argument-hint": rulesyncFrontmatter.copilotcli["argument-hint"],
+      }),
     };
 
     return new CopilotcliSkill({

src/features/skills/rulesync-skill.ts

@@ -114,6 +114,7 @@ const RulesyncSkillFrontmatterSchemaInternal = z.looseObject({
     z.looseObject({
       license: z.optional(z.string()),
       "allowed-tools": z.optional(z.union([z.string(), z.array(z.string())])),
+      "argument-hint": z.optional(z.string()),
     }),
   ),
   pi: z.optional(
@@ -265,6 +266,7 @@ export type RulesyncSkillFrontmatterInput = {
   copilotcli?: {
     license?: string;
     "allowed-tools"?: string | string[];
+    "argument-hint"?: string;
   };
   pi?: {
     "allowed-tools"?: string[];