@kuznai/inception-engine 0.21.0 → 0.22.0

package/README.md

@@ -50,9 +50,10 @@ Before executing, the deploy command runs preflight analysis on instruction file
 | Skills (SKILL.md) | All agents via manifest and CLI | All agents |
 | File write | All agents via manifest and CLI | All agents |
 | Config patch (JSON merge) | All agents via manifest and CLI | All agents |
-| MCP Servers | claude-code (`scope: "global"` → `~/.claude.json`; `scope: "repo"` → `{repo}/.claude/mcp.json`; `scope: "workspace"` → `{workspace}/.claude/mcp.json`), gemini-cli, codex, antigravity, opencode; github-copilot with `scope: "repo"` deploys to `{repo}/.vscode/mcp.json` and `scope: "workspace"` deploys to `{workspace}/.vscode/mcp.json`; github-copilot with `scope: "global"` (default) is unsupported and warns | claude-code, gemini-cli, codex, antigravity, opencode, github-copilot |
+| MCP Servers | claude-code (`scope: "global"` → `~/.claude.json`; `scope: "repo"` → `{repo}/.claude/mcp.json`; `scope: "workspace"` → `{workspace}/.claude/mcp.json`), gemini-cli, codex, antigravity (`scope: "global"` → `~/.gemini/antigravity/mcp_config.json`; `scope: "repo"` → `{repo}/.agents/rules/{name}.md`), opencode; github-copilot with `scope: "repo"` deploys to `{repo}/.vscode/mcp.json` and `scope: "workspace"` deploys to `{workspace}/.vscode/mcp.json`; github-copilot with `scope: "global"` (default) is unsupported and warns | claude-code, gemini-cli, codex, antigravity, opencode, github-copilot |
 | Global/Repo/Workspace Rules Files | `scope: "global"` and `scope: "repo"` are supported on the implemented agent surfaces; `scope: "workspace"` is supported for `claude-code`, `codex`, and `gemini-cli`; `github-copilot` reads Claude-native rules via `claude-code` and has no separate rules deployment target | All supported agents |
 | Permissions / Approval Config | claude-code (`~/.claude/settings.json`), codex (`~/.codex/config.toml`), opencode (`~/.config/opencode/opencode.json` on POSIX, `%APPDATA%\\opencode\\opencode.json` on Windows); other agents are warned and skipped | claude-code, codex, opencode |
+| Execution Hooks | claude-code (`~/.claude/settings.json`), github-copilot (`planned`); other agents are warned and skipped | claude-code |
 | Agent Definitions | claude-code (`{repo}/.claude/agents/{name}.md`), gemini-cli (`{repo}/.gemini/agents/{name}.md` or `.toml`, plus `scope: "global"` to `~/.gemini/agents/{name}.md` or `.toml`), antigravity (`{repo}/.agents/rules/{name}.md`), opencode (`{repo}/.opencode/agents/{name}.md`, plus `scope: "global"` to the user config dir), github-copilot (`{repo}/.github/copilot/agents/{name}.md`, with migration from legacy `.github/agents/{name}.agent.md`); codex is warned and skipped | All supported agents |
 | `init` manifest generation | Scans `SKILL.md` directories (`skills`), `.md` files with Claude-first agent mapping (`agentRules`), `mcp-servers.json` (`mcpServers`), and agent-definition Markdown files (`agentDefinitions`); shared surfaces default to the primary deploy target instead of shared riders; emits hints for `files/` and `configs/` directories | N/A |
 | Instruction preflight analysis | Emits capability warnings for implementation-only, planned, unsupported, and shared-through surfaces used by the manifest; emits `precedence` warnings when an agent has multiple `agentRules` scopes active simultaneously or the same source file is deployed to multiple scopes; emits `budget` warnings when `agentRules` or `agentDefinitions` source files exceed 50 KB; emits GitHub Copilot enterprise-policy warnings when local configuration may be overridden; emits a `config-authority` warning when Gemini CLI's `settings.json` contains an `instructionFilename` override that differs from the deploy target | N/A |
@@ -135,6 +136,17 @@ Create an `inception.json` file at the root of your skills directory:
       "path": "agents/code-reviewer.md",
       "agents": ["claude-code", "opencode", "github-copilot"]
     }
+  ],
+  "hooks": [
+    {
+      "name": "pre-exec-check",
+      "agents": ["claude-code"],
+      "config": {
+        "hooks": {
+          "pre_exec": "scripts/check-env.sh"
+        }
+      }
+    }
   ]
 }
 ```
@@ -166,17 +178,18 @@ Each **mcpServer** entry registers an MCP server into the agent's config file by
 - **name** - Unique identifier (same format as skill names); used as the server's key in the config
 - **agents** - Array of agent IDs to register this server with
 - **config** - Raw server descriptor object. For the currently supported JSON-backed adapters, inception-engine requires at least one non-empty `command` or `url` field, validates `args` as an array of strings when present, and validates `env` as a string-to-string object when present. Additional keys are passed through verbatim.
-- **scope** - `"global"` (default), `"repo"`, or `"workspace"`. For most agents this field is ignored (they have only a single user-level config path). For `github-copilot`, `scope` selects the target file:
+- **scope** - `"global"` (default), `"repo"`, `"workspace"`, or `"devcontainer"`. For most agents this field is ignored (they have only a single user-level config path). For `github-copilot`, `scope` selects the target file:
   - `"global"` — unsupported; emits a warning and is skipped
   - `"repo"` — deploys to `{repo}/.vscode/mcp.json` under the `servers` key
   - `"workspace"` — deploys to `{workspace}/.vscode/mcp.json` under the `servers` key
+  - `"devcontainer"` — deploys to `{repo}/.devcontainer/devcontainer.json` under the `customizations.vscode.mcp.servers` key
 
   GitHub Copilot's `.vscode/mcp.json` uses `servers` (not `mcpServers`) as the top-level key and optionally accepts a `type` field (`"stdio"` | `"sse"` | `"http"`) in the server descriptor, which is passed through verbatim.
 
 MCP server registration is supported for all agents. Inception-engine automatically uses the correct adapter for each agent's configuration schema:
-- **JSON (Merge Patch)**: `claude-code` (`~/.claude.json` for `scope: "global"`; `{repo}/.claude/mcp.json` for `scope: "repo"`; `{workspace}/.claude/mcp.json` for `scope: "workspace"`), `gemini-cli` (`~/.gemini/settings.json`), `opencode` (`~/.config/opencode/opencode.json` using the custom `"mcp"` key), and `github-copilot` (`{repo}/.vscode/mcp.json` or `{workspace}/.vscode/mcp.json` using the `"servers"` key).
+- **JSON (Merge Patch)**: `claude-code` (`~/.claude.json` for `scope: "global"`; `{repo}/.claude/mcp.json` for `scope: "repo"`; `{workspace}/.claude/mcp.json` for `scope: "workspace"`), `gemini-cli` (`~/.gemini/settings.json`), `antigravity` (`~/.gemini/antigravity/mcp_config.json` for `scope: "global"`), `opencode` (`~/.config/opencode/opencode.json` using the custom `"mcp"` key), and `github-copilot` (`{repo}/.vscode/mcp.json`, `{workspace}/.vscode/mcp.json`, or `{repo}/.devcontainer/devcontainer.json`).
 - **TOML (Patch)**: `codex` (`~/.codex/config.toml`).
-- **Markdown Frontmatter (Emit)**: `antigravity` (repo-local `.agents/rules/{name}.md` files).
+- **Markdown Frontmatter (Emit)**: `antigravity` (`{repo}/.agents/rules/{name}.md` for `scope: "repo"`).
 
 For Markdown frontmatter targets, inception-engine now records patch-level provenance for the emitted frontmatter block. Deploy merges only the owned frontmatter keys, preserves unrelated frontmatter and Markdown body content, and `revert` removes only the engine-owned keys instead of deleting the whole file unless inception-engine originally created an otherwise-empty file.
 
@@ -248,6 +261,31 @@ Valid `approval_policy` values are `"auto"`, `"manual"`, `"suggest"`, and `"on-f
 
 Revert restores the previous config values using the undo patch recorded at deploy time.
 
+Each **hooks** entry deploys lifecycle-binding configurations to an agent's execution hook surface:
+
+- **name** - Unique identifier (same format as skill names)
+- **agents** - Array of agent IDs to deploy this entry to
+- **config** - Hook configuration payload; shape is validated per agent (see below)
+
+Hook deployment is currently supported for `claude-code`. For `github-copilot`, it is marked as `planned`. Other agents emit a warning and are skipped.
+
+For `claude-code`, the config is merged into `~/.claude/settings.json`. Only the `hooks` key is accepted:
+
+```json
+{
+  "name": "pre-exec-check",
+  "agents": ["claude-code"],
+  "config": {
+    "hooks": {
+      "pre_exec": "scripts/check-env.sh",
+      "post_exec": "scripts/notify.sh"
+    }
+  }
+}
+```
+
+Revert restores the previous config values using the undo patch recorded at deploy time.
+
 Each **agentDefinitions** entry deploys an agent-definition file to the agent-definition directory of each targeted agent. `scope: "repo"` is the default, and some agents also support `scope: "global"`:
 
 - **name** - Unique identifier (same format as skill names); used as the definition filename

package/dist/src/config/agents.js

@@ -18,6 +18,7 @@ export const AGENT_REGISTRY = [
             mcpConfig: "documented",
             agentRules: "documented",
             permissions: "documented",
+            hooks: "documented",
             agentDefinitions: "documented",
         },
         mcpSupport: {
@@ -68,6 +69,14 @@ export const AGENT_REGISTRY = [
                 windows: ["{home}", ".claude", "settings.json"],
             },
         },
+        hooksSupport: {
+            status: "supported",
+            schemaLabel: "JSON hooks config",
+            path: {
+                posix: ["{home}", ".claude", "settings.json"],
+                windows: ["{home}", ".claude", "settings.json"],
+            },
+        },
         agentDefinitionsRepoSupport: {
             status: "supported",
             schemaLabel: "repo-local agent definition Markdown file",
@@ -103,6 +112,7 @@ export const AGENT_REGISTRY = [
             detectBinary: "documented",
             agentRules: "documented",
             permissions: "documented",
+            hooks: "provisional",
         },
         mcpSupport: {
             status: "supported",
@@ -136,6 +146,11 @@ export const AGENT_REGISTRY = [
                 windows: ["{home}", ".codex", "config.toml"],
             },
         },
+        hooksSupport: {
+            status: "unsupported",
+            schemaLabel: "global hooks surface",
+            reason: "OpenAI Codex does not expose a documented lifecycle-hook config surface in config.toml",
+        },
         agentDefinitionsRepoSupport: {
             status: "unsupported",
             schemaLabel: "dedicated agent definition directory",
@@ -168,6 +183,7 @@ export const AGENT_REGISTRY = [
             detectBinary: "documented",
             mcpConfig: "documented",
             agentRules: "documented",
+            hooks: "provisional",
             agentDefinitions: "documented",
         },
         mcpSupport: {
@@ -202,6 +218,12 @@ export const AGENT_REGISTRY = [
             schemaLabel: "global permissions surface",
             reason: "Gemini CLI does not expose a documented global per-user permission or approval config surface",
         },
+        hooksSupport: {
+            status: "planned",
+            schemaLabel: "global hooks surface",
+            plannedSurface: "settings.json hooks field",
+            reason: "Gemini CLI execution hooks are emerging and not yet settled",
+        },
         agentDefinitionsSupport: {
             status: "supported",
             schemaLabel: "global agent definition Markdown file",
@@ -263,6 +285,14 @@ export const AGENT_REGISTRY = [
             agentDefinitions: "documented",
         },
         mcpSupport: {
+            status: "supported",
+            schemaLabel: "global mcp_config.json",
+            path: {
+                posix: ["{home}", ".gemini", "antigravity", "mcp_config.json"],
+                windows: ["{home}", ".gemini", "antigravity", "mcp_config.json"],
+            },
+        },
+        mcpRepoSupport: {
             status: "supported",
             schemaLabel: "repo-local frontmatter-emit MCP rules",
             path: {
@@ -296,6 +326,11 @@ export const AGENT_REGISTRY = [
             schemaLabel: "global permissions surface",
             reason: "Antigravity does not expose a documented global per-user permission or approval config surface",
         },
+        hooksSupport: {
+            status: "unsupported",
+            schemaLabel: "global hooks surface",
+            reason: "Antigravity does not expose a documented global per-user hook config surface",
+        },
         agentDefinitionsRepoSupport: {
             status: "supported",
             schemaLabel: "repo-local agent definition Markdown file",
@@ -330,6 +365,7 @@ export const AGENT_REGISTRY = [
             agentRules: "documented",
             agentDefinitions: "documented",
             permissions: "documented",
+            hooks: "provisional",
         },
         mcpSupport: {
             status: "supported",
@@ -364,6 +400,11 @@ export const AGENT_REGISTRY = [
                 windows: ["{appdata}", "opencode", "opencode.json"],
             },
         },
+        hooksSupport: {
+            status: "unsupported",
+            schemaLabel: "global hooks surface",
+            reason: "OpenCode does not expose a documented lifecycle-hook surface",
+        },
         agentDefinitionsSupport: {
             status: "supported",
             schemaLabel: "global agent definition Markdown file",
@@ -404,6 +445,7 @@ export const AGENT_REGISTRY = [
             detectBinary: "documented",
             agentDefinitions: "documented",
             mcpConfig: "documented",
+            hooks: "provisional",
         },
         mcpSupport: {
             status: "unsupported",
@@ -473,16 +515,25 @@ export const AGENT_REGISTRY = [
             },
         },
         mcpDevcontainerSupport: {
-            status: "planned",
+            status: "supported",
             schemaLabel: "devcontainer.json MCP surface",
-            plannedSurface: "devcontainer.json customizations.vscode.mcp.servers",
-            reason: 'devcontainer.json MCP support is planned — use scope: "repo" or scope: "workspace" to target .vscode/mcp.json in the meantime',
+            mcpPatchKey: "customizations.vscode.mcp.servers",
+            path: {
+                posix: ["{repo}", ".devcontainer", "devcontainer.json"],
+                windows: ["{repo}", ".devcontainer", "devcontainer.json"],
+            },
         },
         permissionsSupport: {
             status: "unsupported",
             schemaLabel: "global permissions surface",
             reason: "GitHub Copilot permissions are managed via organization policy, not a deployable per-user config surface",
         },
+        hooksSupport: {
+            status: "planned",
+            schemaLabel: "binary execution hooks",
+            plannedSurface: "agent frontmatter pre_exec/post_exec hooks",
+            reason: "GitHub Copilot binary hook support is planned and requires further validation of the stdin/stdout contract",
+        },
         agentDefinitionsRepoSupport: {
             status: "supported",
             schemaLabel: "repo-local agent definition Markdown file",
@@ -504,14 +555,7 @@ export const AGENT_REGISTRY = [
             },
         },
         policyNote: "Organization policies may override locally deployed configuration. Verify with your GitHub org admin if deployed skills or rules are not active.",
-        unsupportedSurfaces: [
-            {
-                status: "planned",
-                schemaLabel: "devcontainer.json MCP surface",
-                plannedSurface: "devcontainer.json customizations.vscode.mcp.servers",
-                reason: 'devcontainer.json MCP support is planned — use scope: "repo" or scope: "workspace" to target .vscode/mcp.json in the meantime',
-            },
-        ],
+        unsupportedSurfaces: [],
         instructionFrontmatterRequired: true,
         enterprisePolicyDetection: true,
     },

package/dist/src/core/adapters/hooks.d.ts

@@ -0,0 +1,8 @@
+import type { HookEntry } from "../../schemas/manifest.ts";
+import type { AgentId, ConfigPatchDeployAction, ConfigPatchRevertAction, PlanWarning, TomlPatchDeployAction, TomlPatchRevertAction } from "../../types.ts";
+export interface HooksAdapterResult {
+    actions: Array<ConfigPatchDeployAction | TomlPatchDeployAction>;
+    warnings: PlanWarning[];
+}
+export declare function compileHookActions(entry: HookEntry, detectedAgents: AgentId[], home: string): HooksAdapterResult;
+export declare function compileHookReverts(entry: HookEntry, agentFilter: AgentId[] | null, home: string): Array<ConfigPatchRevertAction | TomlPatchRevertAction>;

package/dist/src/core/adapters/hooks.js

@@ -0,0 +1,86 @@
+import path from "node:path";
+import { planCapabilityForDeploy, resolveCapabilitySurface, } from "../capabilities.js";
+import { getPlatformKey, resolvePlaceholders } from "../resolve.js";
+import { validateHookConfigShape } from "../validation.js";
+function isTomlTarget(targetPath) {
+    return path.extname(targetPath).toLowerCase() === ".toml";
+}
+export function compileHookActions(entry, detectedAgents, home) {
+    const actions = [];
+    const warnings = [];
+    const platform = getPlatformKey();
+    for (const agentId of entry.agents) {
+        if (!detectedAgents.includes(agentId))
+            continue;
+        const plan = planCapabilityForDeploy({
+            agentId,
+            capability: "hooks",
+            entryName: entry.name,
+            targetAgentIds: entry.agents,
+        });
+        if (plan.outcome === "warn") {
+            warnings.push(plan.warning);
+            continue;
+        }
+        if (plan.outcome === "native" || plan.outcome === "redundant")
+            continue;
+        const support = resolveCapabilitySurface(agentId, "hooks").support;
+        if (!support)
+            continue;
+        validateHookConfigShape(entry.config, entry.name, agentId);
+        const rawTarget = resolvePlaceholders(support.path[platform], entry.name, home);
+        const resolvedTarget = path.resolve(rawTarget);
+        const confidence = plan.confidence ?? "provisional";
+        if (isTomlTarget(resolvedTarget)) {
+            actions.push({
+                kind: "toml-patch",
+                skill: entry.name,
+                agent: agentId,
+                target: resolvedTarget,
+                config: entry.config,
+                confidence,
+            });
+        }
+        else {
+            actions.push({
+                kind: "config-patch",
+                skill: entry.name,
+                agent: agentId,
+                target: resolvedTarget,
+                patch: entry.config,
+                confidence,
+            });
+        }
+    }
+    return { actions, warnings };
+}
+export function compileHookReverts(entry, agentFilter, home) {
+    const actions = [];
+    const platform = getPlatformKey();
+    for (const agentId of entry.agents) {
+        if (agentFilter && !agentFilter.includes(agentId))
+            continue;
+        const support = resolveCapabilitySurface(agentId, "hooks").support;
+        if (!support)
+            continue;
+        const rawTarget = resolvePlaceholders(support.path[platform], entry.name, home);
+        const target = path.resolve(rawTarget);
+        if (isTomlTarget(target)) {
+            actions.push({
+                kind: "toml-patch",
+                skill: entry.name,
+                agent: agentId,
+                target,
+            });
+        }
+        else {
+            actions.push({
+                kind: "config-patch",
+                skill: entry.name,
+                agent: agentId,
+                target,
+            });
+        }
+    }
+    return actions;
+}

package/dist/src/core/adapters/index.d.ts

@@ -1,13 +1,14 @@
-import type { AgentDefinitionEntry, AgentRuleEntry, McpServerEntry, PermissionsEntry } from "../../schemas/manifest.ts";
+import type { AgentDefinitionEntry, AgentRuleEntry, HookEntry, McpServerEntry, PermissionsEntry } from "../../schemas/manifest.ts";
 import type { AgentId, ConfigPatchDeployAction, FileWriteDeployAction, FrontmatterEmitDeployAction, PlanWarning, TomlPatchDeployAction } from "../../types.ts";
 import { compileAgentDefinitionReverts } from "./agent-definitions.ts";
+import { compileHookReverts } from "./hooks.ts";
 import { compileMcpServerReverts } from "./mcp.ts";
 import { compilePermissionsReverts } from "./permissions.ts";
 import { compileAgentRuleReverts } from "./rules.ts";
-export { compileAgentDefinitionReverts, compileAgentRuleReverts, compileMcpServerReverts, compilePermissionsReverts, };
+export { compileAgentDefinitionReverts, compileAgentRuleReverts, compileHookReverts, compileMcpServerReverts, compilePermissionsReverts, };
 export type AdapterAction = ConfigPatchDeployAction | FileWriteDeployAction | TomlPatchDeployAction | FrontmatterEmitDeployAction;
 export interface AdapterResult {
     actions: AdapterAction[];
     warnings: PlanWarning[];
 }
-export declare function compileAdapterActions(mcpServers: McpServerEntry[], agentRules: AgentRuleEntry[], permissions: PermissionsEntry[], sourceDir: string, resolvedSourceDir: string, realRoot: string, detectedAgents: AgentId[], home: string, repo?: string, agentDefinitions?: AgentDefinitionEntry[], workspace?: string): Promise<AdapterResult>;
+export declare function compileAdapterActions(mcpServers: McpServerEntry[], agentRules: AgentRuleEntry[], permissions: PermissionsEntry[], sourceDir: string, resolvedSourceDir: string, realRoot: string, detectedAgents: AgentId[], home: string, repo?: string, agentDefinitions?: AgentDefinitionEntry[], workspace?: string, hooks?: HookEntry[]): Promise<AdapterResult>;

package/dist/src/core/adapters/index.js

@@ -1,8 +1,9 @@
 import { compileAgentDefinitionActions, compileAgentDefinitionReverts, } from "./agent-definitions.js";
+import { compileHookActions, compileHookReverts } from "./hooks.js";
 import { compileMcpServerActions, compileMcpServerReverts } from "./mcp.js";
 import { compilePermissionsActions, compilePermissionsReverts, } from "./permissions.js";
 import { compileAgentRuleActions, compileAgentRuleReverts } from "./rules.js";
-export { compileAgentDefinitionReverts, compileAgentRuleReverts, compileMcpServerReverts, compilePermissionsReverts, };
+export { compileAgentDefinitionReverts, compileAgentRuleReverts, compileHookReverts, compileMcpServerReverts, compilePermissionsReverts, };
 async function compileAll(entries, fn) {
     const results = await Promise.all(entries.map(fn));
     return {
@@ -10,16 +11,17 @@ async function compileAll(entries, fn) {
         warnings: results.flatMap((r) => r.warnings),
     };
 }
-export async function compileAdapterActions(mcpServers, agentRules, permissions, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, agentDefinitions, workspace) {
+export async function compileAdapterActions(mcpServers, agentRules, permissions, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, agentDefinitions, workspace, hooks = []) {
     const actions = [];
     const warnings = [];
-    const [mcp, rules, perms, defs] = await Promise.all([
+    const [mcp, rules, perms, defs, hookResults] = await Promise.all([
         compileAll(mcpServers, (entry) => compileMcpServerActions(entry, detectedAgents, home, repo, workspace)),
         compileAll(agentRules, (entry) => compileAgentRuleActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, workspace)),
         compileAll(permissions, (entry) => compilePermissionsActions(entry, detectedAgents, home)),
         compileAll(agentDefinitions ?? [], (entry) => compileAgentDefinitionActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, workspace)),
+        compileAll(hooks, (entry) => compileHookActions(entry, detectedAgents, home)),
     ]);
-    actions.push(...mcp.actions, ...rules.actions, ...perms.actions, ...defs.actions);
-    warnings.push(...mcp.warnings, ...rules.warnings, ...perms.warnings, ...defs.warnings);
+    actions.push(...mcp.actions, ...rules.actions, ...perms.actions, ...defs.actions, ...hookResults.actions);
+    warnings.push(...mcp.warnings, ...rules.warnings, ...perms.warnings, ...defs.warnings, ...hookResults.warnings);
     return { actions, warnings };
 }

package/dist/src/core/adapters/mcp.js

@@ -16,6 +16,20 @@ function isMarkdownTarget(targetPath) {
     const ext = path.extname(targetPath).toLowerCase();
     return ext === ".md" || ext === ".markdown";
 }
+/**
+ * Builds a nested object from a dot-separated key path.
+ * e.g. ("a.b", {c: 1}) -> {a: {b: {c: 1}}}
+ */
+function buildNestedPatch(keyPath, leafValue) {
+    const parts = keyPath.split(".");
+    let current = {
+        [parts[parts.length - 1]]: leafValue,
+    };
+    for (let i = parts.length - 2; i >= 0; i--) {
+        current = { [parts[i]]: current };
+    }
+    return current;
+}
 function buildMcpDeployAction(entry, agentId, resolvedTarget, confidence, mcpPatchKey) {
     if (isMarkdownTarget(resolvedTarget)) {
         return {
@@ -42,7 +56,7 @@ function buildMcpDeployAction(entry, agentId, resolvedTarget, confidence, mcpPat
         skill: entry.name,
         agent: agentId,
         target: resolvedTarget,
-        patch: { [mcpPatchKey]: { [entry.name]: entry.config } },
+        patch: buildNestedPatch(mcpPatchKey, { [entry.name]: entry.config }),
         confidence,
     };
 }

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

@@ -1,5 +1,5 @@
 import type { AgentId, AgentSurfaceSupport, CapabilityKind, Confidence, PlanWarning, SupportedAgentSurface } from "../types.ts";
-type CapabilityScope = "global" | "repo" | "workspace";
+type CapabilityScope = "global" | "repo" | "workspace" | "devcontainer";
 export interface ResolvedCapabilitySurface {
     agentId: AgentId;
     capability: CapabilityKind;

package/dist/src/core/capabilities.js

@@ -19,6 +19,11 @@ function resolveMcpSupport(agentId, scope) {
     if (scope === "workspace") {
         return (agent?.mcpWorkspaceSupport ?? agent?.mcpRepoSupport ?? agent?.mcpSupport);
     }
+    if (scope === "devcontainer") {
+        return (agent?.mcpDevcontainerSupport ??
+            agent?.mcpRepoSupport ??
+            agent?.mcpSupport);
+    }
     return agent?.mcpSupport;
 }
 function resolveAgentDefinitionsSupport(agentId, scope) {
@@ -45,6 +50,8 @@ function capabilityLabel(capability) {
             return "permissions";
         case "agentDefinitions":
             return "agentDefinitions";
+        case "hooks":
+            return "hooks";
     }
 }
 function capabilitySurfaceLabel(capability) {
@@ -59,6 +66,8 @@ function capabilitySurfaceLabel(capability) {
             return "permissions";
         case "agentDefinitions":
             return "agent-definitions";
+        case "hooks":
+            return "hooks";
     }
 }
 function resolveSkillsCapability(agentId) {
@@ -110,9 +119,15 @@ function getSurfaceRecordAndConfidence(agentId, capability, scope) {
             confidence: agent.provenance.permissions,
         };
     }
+    if (capability === "agentDefinitions") {
+        return {
+            supportRecord: resolveAgentDefinitionsSupport(agentId, scope),
+            confidence: agent.provenance.agentDefinitions,
+        };
+    }
     return {
-        supportRecord: resolveAgentDefinitionsSupport(agentId, scope),
-        confidence: agent.provenance.agentDefinitions,
+        supportRecord: agent.hooksSupport,
+        confidence: agent.provenance.hooks,
     };
 }
 function resolveUnsupportedSurface(agentId, capability, supportRecord, confidence) {

package/dist/src/core/deploy.js

@@ -280,7 +280,7 @@ export async function planDeploy(manifest, sourceDir, detectedAgents, home, repo
         ...(await planFileWriteActions(manifest, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repoDir, workspace)),
         ...planConfigPatchActions(manifest, detectedAgents, home, repoDir, workspace),
     ];
-    const adapterResult = await compileAdapterActions(manifest.mcpServers, manifest.agentRules, manifest.permissions ?? [], sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repoDir, manifest.agentDefinitions ?? [], workspace);
+    const adapterResult = await compileAdapterActions(manifest.mcpServers, manifest.agentRules, manifest.permissions ?? [], sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repoDir, manifest.agentDefinitions ?? [], workspace, manifest.hooks ?? []);
     actions.push(...adapterResult.actions);
     const warnings = [
         ...skillPlan.warnings,

package/dist/src/core/init.js

@@ -269,16 +269,24 @@ function agentsForDefinitionSubdir(subdir) {
  */
 async function isSkippedMcpFile(subdir, absPath, relPath) {
     const hasMcpSurfaceHere = AGENT_REGISTRY.some((agent) => {
-        const support = agent.mcpSupport;
-        if (support?.status !== "supported")
-            return false;
-        const tmpl = support.path.posix;
-        const repoIdx = tmpl.indexOf("{repo}");
-        const nameIdx = tmpl.findIndex((s) => s.includes("{name}"));
-        if (repoIdx === -1 || nameIdx === -1 || nameIdx <= repoIdx)
-            return false;
-        const prefix = tmpl.slice(repoIdx + 1, nameIdx).join("/");
-        return prefix === subdir;
+        const supports = [
+            agent.mcpSupport,
+            agent.mcpRepoSupport,
+            agent.mcpWorkspaceSupport,
+        ];
+        for (const support of supports) {
+            if (support?.status !== "supported")
+                continue;
+            const tmpl = support.path.posix;
+            const repoIdx = tmpl.indexOf("{repo}");
+            const nameIdx = tmpl.findIndex((s) => s.includes("{name}"));
+            if (repoIdx === -1 || nameIdx === -1 || nameIdx <= repoIdx)
+                continue;
+            const prefix = tmpl.slice(repoIdx + 1, nameIdx).join("/");
+            if (prefix === subdir)
+                return true;
+        }
+        return false;
     });
     if (!hasMcpSurfaceHere)
         return false;

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

@@ -4,6 +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 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,6 +163,10 @@ 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.
+}
 export function validateAgentRuleMarkdownPath(manifestPath, agentId) {
     const extension = path.extname(manifestPath).toLowerCase();
     if (extension !== ".md" && extension !== ".markdown") {

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

@@ -63,6 +63,7 @@ export declare const McpServerEntrySchema: z.ZodObject<{
         global: "global";
         repo: "repo";
         workspace: "workspace";
+        devcontainer: "devcontainer";
     }>>;
 }, z.core.$strip>;
 export declare const AgentRuleEntrySchema: z.ZodObject<{
@@ -111,6 +112,18 @@ export declare const AgentDefinitionEntrySchema: z.ZodObject<{
         workspace: "workspace";
     }>>;
 }, z.core.$strip>;
+export declare const HookEntrySchema: 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 ManifestSchema: z.ZodObject<{
     skills: z.ZodArray<z.ZodObject<{
         name: z.ZodString;
@@ -165,6 +178,7 @@ export declare const ManifestSchema: z.ZodObject<{
             global: "global";
             repo: "repo";
             workspace: "workspace";
+            devcontainer: "devcontainer";
         }>>;
     }, z.core.$strip>>>;
     agentRules: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -213,6 +227,18 @@ export declare const ManifestSchema: z.ZodObject<{
             workspace: "workspace";
         }>>;
     }, z.core.$strip>>>;
+    hooks: 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>;
@@ -221,6 +247,7 @@ export type McpServerEntry = z.infer<typeof McpServerEntrySchema>;
 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 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

@@ -88,7 +88,9 @@ export const McpServerEntrySchema = z.object({
     // config files for agents that support them (e.g. GitHub Copilot's
     // .vscode/mcp.json). For agents without scope-specific surfaces the
     // adapter falls back to the global surface or emits a warning.
-    scope: z.enum(["global", "repo", "workspace"]).default("global"),
+    scope: z
+        .enum(["global", "repo", "workspace", "devcontainer"])
+        .default("global"),
 });
 export const AgentRuleEntrySchema = z.object({
     name: nameField,
@@ -124,6 +126,13 @@ export const AgentDefinitionEntrySchema = z.object({
     // within the deployed repository (default).
     scope: z.enum(["global", "repo", "workspace"]).default("repo"),
 });
+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.
+    config: z.record(z.string(), z.unknown()),
+});
 export const ManifestSchema = z.object({
     skills: z.array(SkillEntrySchema).superRefine((skills, ctx) => {
         const seen = new Set();
@@ -144,6 +153,7 @@ export const ManifestSchema = z.object({
     agentRules: z.array(AgentRuleEntrySchema).default([]),
     permissions: z.array(PermissionsEntrySchema).default([]),
     agentDefinitions: z.array(AgentDefinitionEntrySchema).default([]),
+    hooks: z.array(HookEntrySchema).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, Manifest, SkillEntry, } from "./schemas/manifest.ts";
+export type { AgentDefinitionEntry, AgentId, ConfigEntry, 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" | "agentDefinitions";
+export type CapabilityKind = "skills" | "mcpServers" | "agentRules" | "permissions" | "hooks" | "agentDefinitions";
 export interface SupportedAgentSurface {
     status: "supported";
     /**
@@ -67,6 +67,7 @@ export interface AgentProvenance {
     mcpConfig?: Confidence;
     agentRules?: Confidence;
     permissions?: Confidence;
+    hooks?: Confidence;
     agentDefinitions?: Confidence;
 }
 export interface AgentConfig {
@@ -97,6 +98,9 @@ export interface AgentConfig {
     agentRulesRepoSupport?: AgentSurfaceSupport;
     agentRulesWorkspaceSupport?: AgentSurfaceSupport;
     permissionsSupport?: AgentSurfaceSupport;
+    hooksSupport?: AgentSurfaceSupport;
+    hooksRepoSupport?: AgentSurfaceSupport;
+    hooksWorkspaceSupport?: AgentSurfaceSupport;
     agentDefinitionsSupport?: AgentSurfaceSupport;
     agentDefinitionsRepoSupport?: AgentSurfaceSupport;
     agentDefinitionsWorkspaceSupport?: AgentSurfaceSupport;

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

@@ -137,13 +137,13 @@ describe("compileMcpServerActions", () => {
             servers: { "my-mcp": { command: "s" } },
         });
     });
-    it("returns a frontmatter-emit action for antigravity MCP", () => {
+    it("returns a frontmatter-emit action for antigravity MCP with scope: repo", () => {
         const home = "/home/test";
         const { actions, warnings } = compileMcpServerActions({
             name: "my-mcp",
             agents: ["antigravity"],
             config: { command: "s" },
-            scope: "global",
+            scope: "repo",
         }, ["antigravity"], home, "/repo/test");
         assert.equal(actions.length, 1);
         assert.equal(warnings.length, 0);
@@ -151,6 +151,20 @@ describe("compileMcpServerActions", () => {
         assert.equal(actions[0]?.agent, "antigravity");
         assertPathEndsWith(actions[0]?.target ?? "", ".agents/rules/my-mcp.md", `expected target to end with .agents/rules/my-mcp.md, got ${actions[0]?.target}`);
     });
+    it("returns a config-patch action for antigravity MCP with scope: global", () => {
+        const home = "/home/test";
+        const { actions, warnings } = compileMcpServerActions({
+            name: "my-mcp",
+            agents: ["antigravity"],
+            config: { command: "s" },
+            scope: "global",
+        }, ["antigravity"], home);
+        assert.equal(actions.length, 1);
+        assert.equal(warnings.length, 0);
+        assert.equal(actions[0]?.kind, "config-patch");
+        assert.equal(actions[0]?.agent, "antigravity");
+        assertPathEndsWith(actions[0]?.target ?? "", ".gemini/antigravity/mcp_config.json", `expected target to end with .gemini/antigravity/mcp_config.json, got ${actions[0]?.target}`);
+    });
     it("throws when a supported MCP target is missing both command and url", () => {
         assert.throws(() => compileMcpServerActions({
             name: "my-mcp",

package/dist/test/unit/deploy.test.js

@@ -30,6 +30,7 @@ const testManifest = {
     agentRules: [],
     permissions: [],
     agentDefinitions: [],
+    hooks: [],
 };
 describe("planDeploy", () => {
     it("creates actions for detected agents only", async () => {
@@ -647,8 +648,9 @@ describe("planDeploy", () => {
             assert.ok(geminiAction, "expected a gemini-cli action");
             assert.match(geminiAction.target, /[\\/]\.gemini[\\/]settings\.json$/);
             assert.ok(antigravityAction, "expected an antigravity action");
-            // Antigravity's target for mcpServer is .agents/rules/{name}.md
-            assert.match(antigravityAction.target, /[\\/]\.agents[\\/]rules[\\/]my-mcp\.md$/);
+            // Antigravity's target for global mcpServer is .gemini/antigravity/mcp_config.json
+            assert.equal(antigravityAction.kind, "config-patch");
+            assert.match(antigravityAction.target, /[\\/]\.gemini[\\/]antigravity[\\/]mcp_config\.json$/);
         }
         finally {
             await rm(sourceDir, { recursive: true });
@@ -802,7 +804,7 @@ describe("planDeploy", () => {
                     name: "my-tool",
                     agents: ["antigravity"],
                     config: { command: "npx", args: ["-y", "my-tool"] },
-                    scope: "global",
+                    scope: "repo",
                 },
             ],
             agentRules: [],

package/dist/test/unit/preflight.test.js

@@ -125,24 +125,22 @@ describe("runPreflight", () => {
         assert.equal(implementationOnlyWarning, undefined, `expected no implementation-only warning, got: ${implementationOnlyWarning?.message}`);
     });
 });
-describe("github-copilot planned surfaces", () => {
-    it("emits a planned surface info notice for devcontainer MCP when Copilot is detected and MCP is targeted", async () => {
+describe("github-copilot devcontainer support", () => {
+    it("emits no capability warning for devcontainer MCP when Copilot is detected and devcontainer scope is targeted", async () => {
         const manifestWithMcp = {
             ...emptyManifest,
             mcpServers: [
                 {
                     name: "test-mcp",
-                    scope: "repo",
+                    scope: "devcontainer",
                     agents: ["github-copilot"],
                     config: { command: "node", args: ["server.js"] },
                 },
             ],
         };
         const warnings = await runPreflight(baseOptions, manifestWithMcp, "/home/test", ["github-copilot"]);
-        const plannedWarning = warnings.find((w) => w.kind === "info" &&
-            /devcontainer\.json MCP support is planned/.test(w.message));
-        assert.ok(plannedWarning, "expected a planned surface warning for Copilot devcontainer when MCP is targeted");
-        assert.match(plannedWarning.message, /planned/);
+        const capabilityWarning = warnings.find((w) => w.kind === "info" && /mcpServers/.test(w.message));
+        assert.equal(capabilityWarning, undefined, `expected no MCP capability warning for devcontainer scope, got: ${capabilityWarning?.message}`);
     });
 });
 describe("instruction precedence warnings", () => {

package/dist/test/unit/revert.test.js

@@ -46,6 +46,7 @@ describe("planRevertAll", () => {
             agentRules: [],
             permissions: [],
             agentDefinitions: [],
+            hooks: [],
         };
         const actions = planRevertAll(multiAgentManifest, "/home/test");
         assert.equal(actions.length, 3);
@@ -75,6 +76,7 @@ describe("planRevertAll", () => {
             agentRules: [],
             permissions: [],
             agentDefinitions: [],
+            hooks: [],
         };
         const actions = planRevertAll(manifest, "/home/test");
         assert.equal(actions.length, 5);
@@ -712,6 +714,7 @@ describe("planRevert — mcpServers and agentRules", () => {
             agentRules: [],
             permissions: [],
             agentDefinitions: [],
+            hooks: [],
         };
         const actions = planRevert(manifest, ["claude-code"], home);
         assert.equal(actions.length, 1);
@@ -735,6 +738,7 @@ describe("planRevert — mcpServers and agentRules", () => {
             agentRules: [],
             permissions: [],
             agentDefinitions: [],
+            hooks: [],
         };
         const actions = planRevert(manifest, ["codex"], home);
         assert.equal(actions.length, 0);
@@ -755,6 +759,7 @@ describe("planRevert — mcpServers and agentRules", () => {
             ],
             permissions: [],
             agentDefinitions: [],
+            hooks: [],
         };
         const actions = planRevert(manifest, ["claude-code"], home);
         assert.equal(actions.length, 1);
@@ -778,6 +783,7 @@ describe("planRevert — mcpServers and agentRules", () => {
             ],
             permissions: [],
             agentDefinitions: [],
+            hooks: [],
         };
         const actions = planRevert(manifest, ["codex"], home);
         assert.equal(actions.length, 0);
@@ -801,6 +807,7 @@ describe("planRevertAll — mcpServers and agentRules", () => {
             agentRules: [],
             permissions: [],
             agentDefinitions: [],
+            hooks: [],
         };
         const actions = planRevertAll(manifest, home);
         assert.equal(actions.length, 2);
@@ -824,6 +831,7 @@ describe("planRevertAll — mcpServers and agentRules", () => {
             ],
             permissions: [],
             agentDefinitions: [],
+            hooks: [],
         };
         const actions = planRevertAll(manifest, home);
         assert.equal(actions.length, 2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuznai/inception-engine",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Deploy AI agent skills from a git repo to user home directories",
   "license": "MIT",
   "author": "Damian Piątkowski",