@kuznai/inception-engine 0.22.0 → 0.23.0

package/dist/src/core/preflight.js

@@ -118,12 +118,37 @@ function detectMultipleActiveInstructionScopes(agentId, rulesForAgent) {
         },
     ];
 }
+/**
+ * Warns when github-copilot has both a shared-via CLAUDE.md agentRules entry
+ * (scope: "repo" or "global") AND a native Copilot instruction entry
+ * (scope: "copilot-repo" or "copilot-scoped"). GitHub Copilot merges all
+ * active instruction sources at runtime, so duplicate or conflicting rules
+ * across these surfaces may cause unexpected agent behavior.
+ */
+function detectCopilotInstructionPrecedence(rulesForAgent) {
+    const hasSharedVia = (rulesForAgent ?? []).some((e) => e.scope === "repo" || e.scope === "global");
+    const hasNative = (rulesForAgent ?? []).some((e) => e.scope === "copilot-repo" || e.scope === "copilot-scoped");
+    if (!(hasSharedVia && hasNative))
+        return [];
+    return [
+        {
+            kind: "precedence",
+            message: `Agent "github-copilot" will load both a CLAUDE.md-shared instruction file` +
+                ` and a native Copilot instruction file (.github/copilot-instructions.md or` +
+                ` .github/instructions/). GitHub Copilot merges all active instruction` +
+                ` sources - ensure content is non-conflicting and does not duplicate rules.`,
+        },
+    ];
+}
 function detectInstructionPrecedence(detectedAgents, manifest) {
     const warnings = [];
     for (const agentId of detectedAgents) {
         const rulesForAgent = (manifest.agentRules ?? []).filter((e) => e.agents.includes(agentId));
         warnings.push(...detectScopeOverlaps(agentId, rulesForAgent));
         warnings.push(...detectMultipleActiveInstructionScopes(agentId, rulesForAgent));
+        if (agentId === "github-copilot") {
+            warnings.push(...detectCopilotInstructionPrecedence(rulesForAgent));
+        }
     }
     return warnings;
 }
@@ -239,6 +264,9 @@ function collectManifestCapabilityWarnings(manifest, detectedAgents) {
     for (const entry of manifest.agentDefinitions ?? []) {
         collectCapabilityWarningsForTargets(acc, entry.agents.filter((agentId) => detectedAgents.includes(agentId)), "agentDefinitions", entry.name, entry.scope);
     }
+    for (const entry of manifest.executionConfigs ?? []) {
+        collectCapabilityWarningsForTargets(acc, entry.agents.filter((agentId) => detectedAgents.includes(agentId)), "executionConfigs", entry.name);
+    }
     return acc.warnings;
 }
 function detectCapabilityPlanningWarnings(manifest, detectedAgents) {

package/dist/src/core/revert.js

@@ -2,7 +2,7 @@ import { lstat, readFile, rm, unlink, writeFile } from "node:fs/promises";
 import { AGENT_REGISTRY_BY_ID } from "../config/agents.js";
 import { logger } from "../logger.js";
 import * as frontmatterAdapter from "./adapters/frontmatter.js";
-import { compileAgentDefinitionReverts, compileAgentRuleReverts, compileMcpServerReverts, compilePermissionsReverts, } from "./adapters/index.js";
+import { compileAgentDefinitionReverts, compileAgentRuleReverts, compileExecutionConfigReverts, compileHookReverts, compileMcpServerReverts, compilePermissionsReverts, } from "./adapters/index.js";
 import { revertTomlMcpPatch } from "./adapters/toml.js";
 import { applyUndoPatch } from "./merge-patch.js";
 import { lookupDeployment, unregisterDeployment, } from "./ownership.js";
@@ -75,6 +75,8 @@ export function planRevert(manifest, detectedAgents, home, repo) {
         ...(manifest.mcpServers ?? []).flatMap((e) => compileMcpServerReverts(e, detectedAgents, home, repo)),
         ...(manifest.agentRules ?? []).flatMap((e) => compileAgentRuleReverts(e, detectedAgents, home, repo)),
         ...(manifest.permissions ?? []).flatMap((e) => compilePermissionsReverts(e, detectedAgents, home)),
+        ...(manifest.hooks ?? []).flatMap((e) => compileHookReverts(e, detectedAgents, home)),
+        ...(manifest.executionConfigs ?? []).flatMap((e) => compileExecutionConfigReverts(e, detectedAgents, home)),
         ...(manifest.agentDefinitions ?? []).flatMap((e) => compileAgentDefinitionReverts(e, detectedAgents, home, repo)),
     ];
 }
@@ -86,6 +88,8 @@ export function planRevertAll(manifest, home, repo) {
         ...(manifest.mcpServers ?? []).flatMap((e) => compileMcpServerReverts(e, null, home, repo)),
         ...(manifest.agentRules ?? []).flatMap((e) => compileAgentRuleReverts(e, null, home, repo)),
         ...(manifest.permissions ?? []).flatMap((e) => compilePermissionsReverts(e, null, home)),
+        ...(manifest.hooks ?? []).flatMap((e) => compileHookReverts(e, null, home)),
+        ...(manifest.executionConfigs ?? []).flatMap((e) => compileExecutionConfigReverts(e, null, home)),
         ...(manifest.agentDefinitions ?? []).flatMap((e) => compileAgentDefinitionReverts(e, null, home, repo)),
     ];
 }

package/dist/src/core/validation.d.ts

@@ -4,7 +4,7 @@ export declare function validateSourcePath(source: string, skillPath: string, re
 export declare function validateSourceFile(sourcePath: string, manifestPath: string): Promise<void>;
 export declare function validateMcpServerConfigShape(config: Record<string, unknown>, entryName: string, agentId: string): void;
 export declare function validatePermissionsConfigShape(config: Record<string, unknown>, entryName: string, agentId: string): void;
-export declare function validateHookConfigShape(_config: Record<string, unknown>, _entryName: string, _agentId: string): void;
+export declare function validateHookConfigShape(config: Record<string, unknown>, entryName: string, agentId: string): void;
 export declare function validateAgentRuleMarkdownPath(manifestPath: string, agentId: string): void;
 export declare function validateSkillDefinitionFile(sourcePath: string, manifestPath: string): Promise<{
     attributes: Record<string, unknown>;

package/dist/src/core/validation.js

@@ -163,9 +163,62 @@ export function validatePermissionsConfigShape(config, entryName, agentId) {
         validateOpenCodePermissions(config, entryName);
     }
 }
-export function validateHookConfigShape(_config, _entryName, _agentId) {
-    // Placeholder for agent-specific hook validation logic.
-    // Currently allows any record as a hook payload.
+function validateClaudeHookCommand(cmd, path) {
+    if (typeof cmd !== "object" || cmd === null || Array.isArray(cmd)) {
+        throw new UserError("DEPLOY_FAILED", `hooks entry ${path} must be an object`);
+    }
+    const cmdObj = cmd;
+    if (cmdObj.type !== "command") {
+        throw new UserError("DEPLOY_FAILED", `hooks entry ${path}.type must be "command"`);
+    }
+    if (typeof cmdObj.command !== "string") {
+        throw new UserError("DEPLOY_FAILED", `hooks entry ${path}.command must be a string`);
+    }
+}
+function validateClaudeHookMatcher(matcher, path) {
+    if (typeof matcher !== "object" ||
+        matcher === null ||
+        Array.isArray(matcher)) {
+        throw new UserError("DEPLOY_FAILED", `hooks entry ${path} must be an object`);
+    }
+    const matcherObj = matcher;
+    if (matcherObj.matcher !== undefined &&
+        typeof matcherObj.matcher !== "string") {
+        throw new UserError("DEPLOY_FAILED", `hooks entry ${path}.matcher must be a string when present`);
+    }
+    const matcherHooks = matcherObj.hooks;
+    if (!Array.isArray(matcherHooks)) {
+        throw new UserError("DEPLOY_FAILED", `hooks entry ${path}.hooks must be an array`);
+    }
+    for (const [cmdIdx, cmd] of matcherHooks.entries()) {
+        validateClaudeHookCommand(cmd, `${path}.hooks[${cmdIdx}]`);
+    }
+}
+function validateClaudeCodeHooks(config, entryName) {
+    const unknownKeys = Object.keys(config).filter((k) => k !== "hooks");
+    if (unknownKeys.length > 0) {
+        throw new UserError("DEPLOY_FAILED", `hooks entry "${entryName}" for agent "claude-code" contains unrecognized keys: ${unknownKeys.join(", ")}. Only "hooks" is allowed.`);
+    }
+    const hooks = config.hooks;
+    if (hooks === undefined)
+        return;
+    if (typeof hooks !== "object" || hooks === null || Array.isArray(hooks)) {
+        throw new UserError("DEPLOY_FAILED", `hooks entry "${entryName}" for agent "claude-code" must define "hooks" as an object`);
+    }
+    const hooksObj = hooks;
+    for (const [eventName, matchers] of Object.entries(hooksObj)) {
+        if (!Array.isArray(matchers)) {
+            throw new UserError("DEPLOY_FAILED", `hooks entry "${entryName}" for agent "claude-code": "hooks.${eventName}" must be an array`);
+        }
+        for (const [idx, matcher] of matchers.entries()) {
+            validateClaudeHookMatcher(matcher, `"${entryName}" for agent "claude-code": "hooks.${eventName}[${idx}]"`);
+        }
+    }
+}
+export function validateHookConfigShape(config, entryName, agentId) {
+    if (agentId === "claude-code") {
+        validateClaudeCodeHooks(config, entryName);
+    }
 }
 export function validateAgentRuleMarkdownPath(manifestPath, agentId) {
     const extension = path.extname(manifestPath).toLowerCase();

package/dist/src/schemas/manifest.d.ts

@@ -81,7 +81,10 @@ export declare const AgentRuleEntrySchema: z.ZodObject<{
         global: "global";
         repo: "repo";
         workspace: "workspace";
+        "copilot-repo": "copilot-repo";
+        "copilot-scoped": "copilot-scoped";
     }>>;
+    targetDir: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const PermissionsEntrySchema: z.ZodObject<{
     name: z.ZodString;
@@ -95,6 +98,18 @@ export declare const PermissionsEntrySchema: z.ZodObject<{
     }>>>, z.ZodTransform<("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[], ("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[]>>;
     config: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 }, z.core.$strip>;
+export declare const ExecutionConfigEntrySchema: z.ZodObject<{
+    name: z.ZodString;
+    agents: z.ZodPipe<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodEnum<{
+        "claude-code": "claude-code";
+        codex: "codex";
+        "gemini-cli": "gemini-cli";
+        antigravity: "antigravity";
+        opencode: "opencode";
+        "github-copilot": "github-copilot";
+    }>>>, z.ZodTransform<("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[], ("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[]>>;
+    config: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
 export declare const AgentDefinitionEntrySchema: z.ZodObject<{
     name: z.ZodString;
     agents: z.ZodPipe<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodEnum<{
@@ -196,7 +211,10 @@ export declare const ManifestSchema: z.ZodObject<{
             global: "global";
             repo: "repo";
             workspace: "workspace";
+            "copilot-repo": "copilot-repo";
+            "copilot-scoped": "copilot-scoped";
         }>>;
+        targetDir: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
     permissions: z.ZodDefault<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
@@ -239,6 +257,18 @@ export declare const ManifestSchema: z.ZodObject<{
         }>>>, z.ZodTransform<("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[], ("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[]>>;
         config: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     }, z.core.$strip>>>;
+    executionConfigs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        agents: z.ZodPipe<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodEnum<{
+            "claude-code": "claude-code";
+            codex: "codex";
+            "gemini-cli": "gemini-cli";
+            antigravity: "antigravity";
+            opencode: "opencode";
+            "github-copilot": "github-copilot";
+        }>>>, z.ZodTransform<("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[], ("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[]>>;
+        config: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type SkillEntry = z.infer<typeof SkillEntrySchema>;
 export type FileEntry = z.infer<typeof FileEntrySchema>;
@@ -248,6 +278,7 @@ export type AgentRuleEntry = z.infer<typeof AgentRuleEntrySchema>;
 export type PermissionsEntry = z.infer<typeof PermissionsEntrySchema>;
 export type AgentDefinitionEntry = z.infer<typeof AgentDefinitionEntrySchema>;
 export type HookEntry = z.infer<typeof HookEntrySchema>;
+export type ExecutionConfigEntry = z.infer<typeof ExecutionConfigEntrySchema>;
 export type Manifest = z.infer<typeof ManifestSchema>;
 export declare const AgentListSchema: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string[], string>>, z.ZodArray<z.ZodPipe<z.ZodString, z.ZodEnum<{
     "claude-code": "claude-code";

package/dist/src/schemas/manifest.js

@@ -92,7 +92,8 @@ export const McpServerEntrySchema = z.object({
         .enum(["global", "repo", "workspace", "devcontainer"])
         .default("global"),
 });
-export const AgentRuleEntrySchema = z.object({
+export const AgentRuleEntrySchema = z
+    .object({
     name: nameField,
     agents: agentsField,
     // Relative path to the rules/instruction file within the source bundle.
@@ -103,7 +104,33 @@ export const AgentRuleEntrySchema = z.object({
     // file (default), "repo" targets the project-root instruction file within the
     // deployed repository (e.g. {repo}/CLAUDE.md for claude-code), and "workspace"
     // targets the agent's workspace-local instruction surface.
-    scope: z.enum(["global", "repo", "workspace"]).default("global"),
+    // "copilot-repo" targets GitHub Copilot's native repo-level instruction file
+    // at {repo}/.github/copilot-instructions.md (github-copilot only).
+    // "copilot-scoped" targets {repo}/.github/instructions/{name}.instructions.md
+    // where {name} is the manifest entry name (github-copilot only).
+    scope: z
+        .enum(["global", "repo", "workspace", "copilot-repo", "copilot-scoped"])
+        .default("global"),
+    // Optional relative directory within the repo/workspace where the rule
+    // should be deployed. Only supported for scope: "repo" and scope: "workspace".
+    targetDir: z
+        .string()
+        .optional()
+        .refine((p) => !(p && nodePath.isAbsolute(p)), {
+        message: "targetDir must be a relative path",
+    })
+        .refine((p) => !(p && nodePath.normalize(p).startsWith("..")), {
+        message: "targetDir must not escape the target root",
+    }),
+})
+    .superRefine((data, ctx) => {
+    if (data.targetDir && data.scope !== "repo" && data.scope !== "workspace") {
+        ctx.addIssue({
+            code: "custom",
+            path: ["targetDir"],
+            message: 'targetDir is only supported for scope "repo" or "workspace"',
+        });
+    }
 });
 export const PermissionsEntrySchema = z.object({
     name: nameField,
@@ -114,6 +141,13 @@ export const PermissionsEntrySchema = z.object({
     // For opencode: { permissions: { allow?: string[], ask?: string[], deny?: string[] } }
     config: z.record(z.string(), z.unknown()),
 });
+export const ExecutionConfigEntrySchema = z.object({
+    name: nameField,
+    agents: agentsField,
+    // Raw execution config payload validated per agent by the execution-config adapter.
+    // For gemini-cli: { safeMode?: boolean, ... }
+    config: z.record(z.string(), z.unknown()),
+});
 export const AgentDefinitionEntrySchema = z.object({
     name: nameField,
     agents: agentsField,
@@ -130,7 +164,8 @@ export const HookEntrySchema = z.object({
     name: nameField,
     agents: agentsField,
     // Raw hook config payload validated per agent by the hooks adapter.
-    // Supports lifecycle-binding hooks (e.g. pre-exec, post-exec) for various agents.
+    // For claude-code: { hooks: { "<EventName>": [{ matcher?: string, hooks: [{ type: "command", command: string }] }] } }
+    // Event names follow Claude Code's settings.json hooks surface (e.g. PreToolUse, PostToolUse, Notification, Stop, SubagentStop).
     config: z.record(z.string(), z.unknown()),
 });
 export const ManifestSchema = z.object({
@@ -154,6 +189,7 @@ export const ManifestSchema = z.object({
     permissions: z.array(PermissionsEntrySchema).default([]),
     agentDefinitions: z.array(AgentDefinitionEntrySchema).default([]),
     hooks: z.array(HookEntrySchema).optional(),
+    executionConfigs: z.array(ExecutionConfigEntrySchema).optional(),
 });
 // Parses the --agents CLI flag: comma-separated agent IDs → AgentId[]
 export const AgentListSchema = z

package/dist/src/types.d.ts

@@ -1,11 +1,11 @@
 import type { AgentId } from "./schemas/manifest.ts";
-export type { AgentDefinitionEntry, AgentId, ConfigEntry, FileEntry, HookEntry, Manifest, SkillEntry, } from "./schemas/manifest.ts";
+export type { AgentDefinitionEntry, AgentId, ConfigEntry, ExecutionConfigEntry, FileEntry, HookEntry, Manifest, SkillEntry, } from "./schemas/manifest.ts";
 export interface AgentPaths {
     posix: string[];
     windows: string[];
 }
 export type Confidence = "documented" | "implementation-only" | "provisional";
-export type CapabilityKind = "skills" | "mcpServers" | "agentRules" | "permissions" | "hooks" | "agentDefinitions";
+export type CapabilityKind = "skills" | "mcpServers" | "agentRules" | "permissions" | "hooks" | "executionConfigs" | "agentDefinitions";
 export interface SupportedAgentSurface {
     status: "supported";
     /**
@@ -68,6 +68,7 @@ export interface AgentProvenance {
     agentRules?: Confidence;
     permissions?: Confidence;
     hooks?: Confidence;
+    executionConfig?: Confidence;
     agentDefinitions?: Confidence;
 }
 export interface AgentConfig {
@@ -97,6 +98,8 @@ export interface AgentConfig {
     agentRulesSupport?: AgentSurfaceSupport;
     agentRulesRepoSupport?: AgentSurfaceSupport;
     agentRulesWorkspaceSupport?: AgentSurfaceSupport;
+    agentRulesCopilotRepoSupport?: AgentSurfaceSupport;
+    agentRulesCopilotScopedSupport?: AgentSurfaceSupport;
     permissionsSupport?: AgentSurfaceSupport;
     hooksSupport?: AgentSurfaceSupport;
     hooksRepoSupport?: AgentSurfaceSupport;
@@ -106,6 +109,7 @@ export interface AgentConfig {
     agentDefinitionsWorkspaceSupport?: AgentSurfaceSupport;
     agentDefinitionsTomlSupport?: AgentSurfaceSupport;
     agentDefinitionsTomlRepoSupport?: AgentSurfaceSupport;
+    executionConfigSupport?: AgentSurfaceSupport;
     mcpDevcontainerSupport?: AgentSurfaceSupport;
     mcpAgentFrontmatterSupport?: AgentSurfaceSupport;
     policyNote?: string;

package/dist/test/unit/adapters.test.js

@@ -3,8 +3,9 @@ import { realpath, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { describe, it } from "node:test";
 import { compileMcpServerActions } from "../../src/core/adapters/mcp.js";
+import { compileHookActions } from "../../src/core/adapters/hooks.js";
 import { compilePermissionsActions } from "../../src/core/adapters/permissions.js";
-import { compileAgentRuleActions } from "../../src/core/adapters/rules.js";
+import { compileAgentRuleActions, compileAgentRuleReverts, } from "../../src/core/adapters/rules.js";
 import { makeTmpDir } from "../helpers/fs.js";
 import { assertPathEndsWith, normalizeSlashes } from "../helpers/path.js";
 describe("compileMcpServerActions", () => {
@@ -354,6 +355,115 @@ describe("compileAgentRuleActions", () => {
             await rm(dir, { recursive: true });
         }
     });
+    it("scope copilot-repo: returns file-write action targeting {repo}/.github/copilot-instructions.md", async () => {
+        const dir = await makeTmpDir();
+        try {
+            await writeFile(path.join(dir, "copilot.md"), "# Copilot rules");
+            const repo = "/repo/myproject";
+            const realRoot = await realpath(dir);
+            const { actions, warnings } = await compileAgentRuleActions({
+                name: "copilot-main",
+                agents: ["github-copilot"],
+                path: "copilot.md",
+                scope: "copilot-repo",
+            }, dir, dir, realRoot, ["github-copilot"], "/home/test", repo);
+            assert.equal(actions.length, 1);
+            assert.equal(warnings.length, 0);
+            const action = actions[0];
+            assert.equal(action.kind, "file-write");
+            assert.equal(action.agent, "github-copilot");
+            assert.equal(normalizeSlashes(action.target), `${repo}/.github/copilot-instructions.md`, `expected target at {repo}/.github/copilot-instructions.md, got: ${action.target}`);
+            assert.equal(action.confidence, "documented");
+        }
+        finally {
+            await rm(dir, { recursive: true });
+        }
+    });
+    it("scope copilot-scoped: returns file-write action with {name} substituted in path", async () => {
+        const dir = await makeTmpDir();
+        try {
+            await writeFile(path.join(dir, "typescript.md"), "# TypeScript rules");
+            const repo = "/repo/myproject";
+            const realRoot = await realpath(dir);
+            const { actions, warnings } = await compileAgentRuleActions({
+                name: "typescript",
+                agents: ["github-copilot"],
+                path: "typescript.md",
+                scope: "copilot-scoped",
+            }, dir, dir, realRoot, ["github-copilot"], "/home/test", repo);
+            assert.equal(actions.length, 1);
+            assert.equal(warnings.length, 0);
+            const action = actions[0];
+            assert.equal(action.kind, "file-write");
+            assert.equal(action.agent, "github-copilot");
+            assert.equal(normalizeSlashes(action.target), `${repo}/.github/instructions/typescript.instructions.md`, `expected target at {repo}/.github/instructions/typescript.instructions.md, got: ${action.target}`);
+            assert.equal(action.confidence, "documented");
+        }
+        finally {
+            await rm(dir, { recursive: true });
+        }
+    });
+    it("scope copilot-repo: returns warning when no repo path provided", async () => {
+        const dir = await makeTmpDir();
+        try {
+            await writeFile(path.join(dir, "copilot.md"), "# Copilot rules");
+            const realRoot = await realpath(dir);
+            const { actions, warnings } = await compileAgentRuleActions({
+                name: "copilot-main",
+                agents: ["github-copilot"],
+                path: "copilot.md",
+                scope: "copilot-repo",
+            }, dir, dir, realRoot, ["github-copilot"], "/home/test");
+            assert.equal(actions.length, 0);
+            assert.equal(warnings.length, 1);
+            assert.equal(warnings[0]?.kind, "confidence");
+            assert.match(warnings[0]?.message ?? "", /copilot-repo/);
+            assert.match(warnings[0]?.message ?? "", /repository path/);
+        }
+        finally {
+            await rm(dir, { recursive: true });
+        }
+    });
+    it("scope copilot-repo: non-github-copilot agents get unsupported warning", async () => {
+        const dir = await makeTmpDir();
+        try {
+            await writeFile(path.join(dir, "copilot.md"), "# Copilot rules");
+            const realRoot = await realpath(dir);
+            const { actions, warnings } = await compileAgentRuleActions({
+                name: "copilot-main",
+                agents: ["claude-code"],
+                path: "copilot.md",
+                scope: "copilot-repo",
+            }, dir, dir, realRoot, ["claude-code"], "/home/test", "/repo/test");
+            assert.equal(actions.length, 0);
+            assert.equal(warnings.length, 1);
+            assert.equal(warnings[0]?.kind, "confidence");
+        }
+        finally {
+            await rm(dir, { recursive: true });
+        }
+    });
+    it("scope copilot-repo: plain markdown without frontmatter succeeds (no instructionFrontmatterRequired check)", async () => {
+        const dir = await makeTmpDir();
+        try {
+            // Plain markdown with no frontmatter — should NOT throw despite github-copilot
+            // having instructionFrontmatterRequired: true (native agentRules scopes skip that check)
+            await writeFile(path.join(dir, "plain.md"), "# Plain rules\n\nNo frontmatter.");
+            const repo = "/repo/myproject";
+            const realRoot = await realpath(dir);
+            const { actions, warnings } = await compileAgentRuleActions({
+                name: "plain-rules",
+                agents: ["github-copilot"],
+                path: "plain.md",
+                scope: "copilot-repo",
+            }, dir, dir, realRoot, ["github-copilot"], "/home/test", repo);
+            assert.equal(actions.length, 1);
+            assert.equal(warnings.length, 0);
+        }
+        finally {
+            await rm(dir, { recursive: true });
+        }
+    });
     it("throws when rules source file does not exist", async () => {
         const dir = await makeTmpDir();
         try {
@@ -469,6 +579,29 @@ describe("compileAgentRuleActions", () => {
             await rm(dir, { recursive: true });
         }
     });
+    it("scope repo with targetDir: injects targetDir into path for claude-code", async () => {
+        const dir = await makeTmpDir();
+        try {
+            const rulesFile = path.join(dir, "CLAUDE.md");
+            await writeFile(rulesFile, "# Rules");
+            const repo = "/repo/myproject";
+            const realRoot = await realpath(dir);
+            const { actions, warnings } = await compileAgentRuleActions({
+                name: "my-rule",
+                agents: ["claude-code"],
+                path: "CLAUDE.md",
+                scope: "repo",
+                targetDir: "apps/frontend",
+            }, dir, dir, realRoot, ["claude-code"], "/home/test", repo);
+            assert.equal(actions.length, 1);
+            assert.equal(warnings.length, 0);
+            const action = actions[0];
+            assert.equal(normalizeSlashes(action.target), `${repo}/apps/frontend/CLAUDE.md`, `expected target at {repo}/apps/frontend/CLAUDE.md, got: ${action.target}`);
+        }
+        finally {
+            await rm(dir, { recursive: true });
+        }
+    });
     it("scope repo: emits a warning and skips when repo path is not provided", async () => {
         const dir = await makeTmpDir();
         try {
@@ -552,6 +685,21 @@ describe("compileAgentRuleActions", () => {
         }
     });
 });
+describe("compileAgentRuleReverts", () => {
+    it("injects targetDir into revert path", () => {
+        const home = "/home/test";
+        const repo = "/repo/test";
+        const actions = compileAgentRuleReverts({
+            name: "my-rule",
+            agents: ["claude-code"],
+            path: "CLAUDE.md",
+            scope: "repo",
+            targetDir: "apps/frontend",
+        }, ["claude-code"], home, repo);
+        assert.equal(actions.length, 1);
+        assert.equal(normalizeSlashes(actions[0]?.target ?? ""), `${repo}/apps/frontend/CLAUDE.md`);
+    });
+});
 describe("compilePermissionsActions", () => {
     it("returns zero actions and warnings when no detected agents overlap", () => {
         const { actions, warnings } = compilePermissionsActions({
@@ -683,6 +831,121 @@ describe("compilePermissionsActions", () => {
         assert.ok(agents.includes("codex"));
     });
 });
+describe("compileHookActions", () => {
+    const validClaudeHookConfig = {
+        hooks: {
+            PreToolUse: [
+                {
+                    matcher: "Bash",
+                    hooks: [{ type: "command", command: "scripts/check.sh" }],
+                },
+            ],
+        },
+    };
+    it("returns zero actions and warnings when no detected agents overlap", () => {
+        const { actions, warnings } = compileHookActions({ name: "check", agents: ["claude-code"], config: validClaudeHookConfig }, ["codex"], "/home/test");
+        assert.equal(actions.length, 0);
+        assert.equal(warnings.length, 0);
+    });
+    it("returns a config-patch action for claude-code targeting settings.json", () => {
+        const home = "/home/test";
+        const { actions, warnings } = compileHookActions({ name: "check", agents: ["claude-code"], config: validClaudeHookConfig }, ["claude-code"], home);
+        assert.equal(warnings.length, 0);
+        assert.equal(actions.length, 1);
+        const action = actions[0];
+        assert.equal(action.kind, "config-patch");
+        assert.ok(action.target.endsWith(".claude/settings.json".replace("/", path.sep)));
+        assert.equal(action.agent, "claude-code");
+        assert.equal(action.confidence, "documented");
+    });
+    it("accepts a hooks entry with no matcher property on the matcher object", () => {
+        const { actions, warnings } = compileHookActions({
+            name: "check",
+            agents: ["claude-code"],
+            config: {
+                hooks: {
+                    Stop: [{ hooks: [{ type: "command", command: "notify.sh" }] }],
+                },
+            },
+        }, ["claude-code"], "/home/test");
+        assert.equal(warnings.length, 0);
+        assert.equal(actions.length, 1);
+    });
+    it("emits a warning and skips for agents without a hooks surface", () => {
+        const { actions, warnings } = compileHookActions({ name: "check", agents: ["gemini-cli"], config: {} }, ["gemini-cli"], "/home/test");
+        assert.equal(actions.length, 0);
+        assert.equal(warnings.length, 1);
+    });
+    it("throws on unknown top-level key in config for claude-code", () => {
+        assert.throws(() => compileHookActions({ name: "bad", agents: ["claude-code"], config: { bad_key: {} } }, ["claude-code"], "/home/test"), /unrecognized keys/);
+    });
+    it("throws when hooks value is not an object for claude-code", () => {
+        assert.throws(() => compileHookActions({ name: "bad", agents: ["claude-code"], config: { hooks: "string" } }, ["claude-code"], "/home/test"), /must define "hooks" as an object/);
+    });
+    it("throws when an event value is not an array", () => {
+        assert.throws(() => compileHookActions({
+            name: "bad",
+            agents: ["claude-code"],
+            config: { hooks: { PreToolUse: "not-array" } },
+        }, ["claude-code"], "/home/test"), /must be an array/);
+    });
+    it("throws when a matcher element is not an object", () => {
+        assert.throws(() => compileHookActions({
+            name: "bad",
+            agents: ["claude-code"],
+            config: { hooks: { PreToolUse: ["string"] } },
+        }, ["claude-code"], "/home/test"), /must be an object/);
+    });
+    it("throws when matcher.hooks is missing", () => {
+        assert.throws(() => compileHookActions({
+            name: "bad",
+            agents: ["claude-code"],
+            config: { hooks: { PreToolUse: [{ matcher: "Bash" }] } },
+        }, ["claude-code"], "/home/test"), /must be an array/);
+    });
+    it("throws when a hook command type is not 'command'", () => {
+        assert.throws(() => compileHookActions({
+            name: "bad",
+            agents: ["claude-code"],
+            config: {
+                hooks: {
+                    PreToolUse: [
+                        {
+                            hooks: [{ type: "script", command: "check.sh" }],
+                        },
+                    ],
+                },
+            },
+        }, ["claude-code"], "/home/test"), /must be "command"/);
+    });
+    it("throws when a hook command is not a string", () => {
+        assert.throws(() => compileHookActions({
+            name: "bad",
+            agents: ["claude-code"],
+            config: {
+                hooks: {
+                    PreToolUse: [{ hooks: [{ type: "command", command: 123 }] }],
+                },
+            },
+        }, ["claude-code"], "/home/test"), /must be a string/);
+    });
+    it("throws when matcher.matcher is not a string", () => {
+        assert.throws(() => compileHookActions({
+            name: "bad",
+            agents: ["claude-code"],
+            config: {
+                hooks: {
+                    PreToolUse: [
+                        {
+                            matcher: 42,
+                            hooks: [{ type: "command", command: "check.sh" }],
+                        },
+                    ],
+                },
+            },
+        }, ["claude-code"], "/home/test"), /must be a string when present/);
+    });
+});
 describe("compileAgentDefinitionActions", () => {
     // Import is added inline to avoid modifying the top-level imports block
     // (the function is async so we do a dynamic import once and reuse).