feat(mcp): native harness formats, scoped install, and PalamHealth leak guards

CHANGELOG.md

@@ -1,3 +1,19 @@
+## [Unreleased]
+
+### Features
+
+* **mcp:** Grok and ZCode adapters with native formats (`.grok/config.toml`, `.zcode/mcp.json`, `~/.zcode/cli/config.json`)
+* **mcp:** `layer` and `whenPathContains` so PalamHealth servers stay project-local
+* **mcp:** `audit` finds PalamHealth / interactive-1Password leaks in user-global configs
+* **mcp:** `sync` installs from `mcp.config.ts` only and no longer union-copies imported servers between tools
+
+### Bug Fixes
+
+* **plugins:** host capability flags match actual adapters (zcode hooks true after the ZCode hook adapter landed; antigravity no longer claims missing MCP/hooks; add cline, droid, amp, continue, gemini-cli, roo-code)
+* **plugins:** install honors `layer`/`whenPathContains` instead of copying every MCP server onto a host
+* **cli:** canonical `install` records tool-directory targets instead of `targets: []`
+* add an MIT `LICENSE` file to match the published badge
+
 ## [1.1.10](https://github.com/itz4blitz/ai-tools/compare/v1.1.9...v1.1.10) (2026-08-26)
 
 

CONTRIBUTING.md

@@ -31,6 +31,7 @@ packages/
   skills/
   rules/
   sessions/
+  ui/         # interactive TUI (not a separately published engine)
 ```
 
 ## Conventions

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 itz4blitz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -23,8 +23,8 @@ Primary fleet is Claude Code, Cursor, OpenCode, Codex, plus Grok and zcode next.
 | [Cursor](https://cursor.com) | ✓ | ✓ | ✓ | ✓ | ✓ |
 | [OpenCode](https://opencode.ai) | ✓ | ✓ | ✓ | ✓ | ✓ |
 | [Codex](https://openai.com/codex/) | ✓ | ✓ | ✓ | ✓ | ✓ |
-| Grok / grok build | | | | | |
-| zcode | | | | | |
+| Grok / grok build | ✓ | ✓ | ✓ | ✓ | ✓ |
+| zcode | ✓ | ✓ | ✓ | ✓ | ✓ |
 | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | ✓ | ✓ | ✓ | ✓ | ✓ |
 | [Antigravity CLI](https://www.antigravity.google/product/antigravity-cli) | | | ✓ | ✓ | ✓ |
 | [Kiro](https://kiro.dev) | ✓ | ✓ | ✓ | ✓ | ✓ |
@@ -36,7 +36,7 @@ Primary fleet is Claude Code, Cursor, OpenCode, Codex, plus Grok and zcode next.
 | [Roo Code](https://roocode.com) | | ✓ | ✓ | ✓ | ✓ |
 | [Windsurf](https://windsurf.com) | | ✓ | | ✓ | ✓ |
 
-<sub>✱ VS Code 1.109+ agent hooks use the Claude Code format. Grok and zcode adapters are not in yet.</sub>
+<sub>✱ VS Code 1.109+ agent hooks use the Claude Code format. Grok and ZCode adapters cover hooks/MCP/agents/skills/rules.</sub>
 
 ## 60-second path
 
@@ -179,21 +179,34 @@ export default defineConfig({
 ### MCP
 
 ```ts
-// ai-mcp.config.ts
+// mcp.config.ts
 import { defineConfig } from "@itz4blitz/ai-tools/mcp";
 
 export default defineConfig({
   servers: [
     {
+      id: "filesystem",
       name: "filesystem",
-      command: "npx",
-      args: ["-y", "@modelcontextprotocol/server-filesystem", "./src"],
-      transport: "stdio",
+      transport: {
+        type: "stdio",
+        command: "npx",
+        args: ["-y", "@modelcontextprotocol/server-filesystem", "./src"],
+      },
+      layer: "project",
+    },
+    {
+      id: "palamhealth",
+      name: "PalamHealth",
+      transport: { type: "stdio", command: "palamhealth-mcp" },
+      layer: "project",
+      whenPathContains: ["PalamHealth"],
     },
   ],
 });
 ```
 
+`ai-tools mcp install --layer=project` writes only matching servers. `ai-tools mcp sync` never copies imported servers between tools. `ai-tools mcp audit` reports PalamHealth leaks in user-global configs.
+
 ### Rules
 
 ```ts
@@ -203,9 +216,10 @@ import { defineRulesConfig } from "@itz4blitz/ai-tools/rules";
 export default defineRulesConfig({
   rules: [
     {
+      id: "typescript-strict",
       name: "typescript-strict",
       content: "Always use strict TypeScript. No `any` types.",
-      scope: "always",
+      scope: { type: "always" },
       priority: 1,
     },
   ],

package.json

@@ -17,7 +17,7 @@
     "lint:fix": "oxlint --fix --tsconfig tsconfig.base.json packages/",
     "fmt": "oxfmt packages/",
     "fmt:check": "oxfmt --check packages/",
-    "audit": "npm audit --audit-level high",
+    "audit": "npm audit --omit=dev --audit-level high",
     "check": "npm run audit && npm run lint && npm run fmt:check && npm run typecheck && npm run test:coverage && npm run test:smoke",
     "release:preflight": "npm run check",
     "release:publish:dry": "npm publish --workspace @itz4blitz/ai-tools --access public --dry-run",

packages/agents/src/adapters/all.ts

@@ -5,8 +5,10 @@ import "./cursor.js";
 import "./cline.js";
 import "./codex.js";
 import "./gemini-cli.js";
+import "./grok.js";
 import "./kiro.js";
 import "./opencode.js";
 import "./droid.js";
 import "./copilot.js";
 import "./roo-code.js";
+import "./zcode.js";

packages/agents/src/adapters/grok.test.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import type { AgentDefinition } from "../types/index.js";
+
+vi.mock("./index.js", () => {
+  const registry = { register: vi.fn() };
+  abstract class BaseAgentAdapter {
+    abstract readonly id: string;
+    abstract readonly name: string;
+    abstract readonly nativeSupport: boolean;
+    abstract readonly configDir: string;
+    abstract generate(agents: AgentDefinition[]): Promise<unknown[]>;
+    abstract import(cwd?: string): Promise<AgentDefinition[]>;
+    async detect() {
+      return false;
+    }
+    async install() {}
+    async uninstall() {}
+  }
+  return { BaseAgentAdapter, registry };
+});
+
+vi.mock("node:fs", () => ({ existsSync: vi.fn(() => false) }));
+vi.mock("node:fs/promises", () => ({ readFile: vi.fn(), readdir: vi.fn() }));
+
+import { GrokAgentAdapter } from "./grok.js";
+
+describe("GrokAgentAdapter", () => {
+  let adapter: GrokAgentAdapter;
+
+  beforeEach(() => {
+    adapter = new GrokAgentAdapter();
+  });
+
+  it("writes markdown agents under .grok/agents", async () => {
+    expect(adapter.id).toBe("grok");
+    expect(adapter.configDir).toBe(".grok/agents");
+    const files = await adapter.generate([
+      { id: "explore", name: "Explore", instructions: "Search the repo." },
+    ]);
+    expect(files[0]?.path).toBe(".grok/agents/explore.md");
+    expect(String(files[0]?.content)).toContain("# Explore");
+    expect(String(files[0]?.content)).toContain("Search the repo.");
+  });
+});

packages/agents/src/adapters/grok.ts

@@ -0,0 +1,11 @@
+import { createMarkdownAdapter } from "./markdown-adapter.js";
+
+const { Adapter: GrokAgentAdapter, adapter } = createMarkdownAdapter({
+  id: "grok",
+  name: "Grok",
+  configDir: ".grok/agents",
+  command: "grok",
+});
+
+export { GrokAgentAdapter };
+export default adapter;

packages/agents/src/adapters/opencode.test.ts

@@ -1,4 +1,8 @@
 import { describe, it, expect, vi, beforeEach } from "vitest";
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import type { AgentDefinition } from "../types/index.js";
 
 vi.mock("./index.js", () => {
@@ -19,19 +23,17 @@ vi.mock("./index.js", () => {
   return { BaseAgentAdapter, registry };
 });
 
-vi.mock("node:fs", () => ({
-  existsSync: vi.fn(() => false),
-}));
-
-vi.mock("node:fs/promises", () => ({
-  readFile: vi.fn(),
-  readdir: vi.fn(),
-}));
-
-import { existsSync } from "node:fs";
-import { readFile, readdir } from "node:fs/promises";
 import { OpenCodeAgentAdapter } from "./opencode.js";
 
+async function withTempDir(fn: (dir: string) => Promise<void>): Promise<void> {
+  const dir = await mkdtemp(join(tmpdir(), "ai-tools-agents-opencode-"));
+  try {
+    await fn(dir);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
 describe("OpenCodeAgentAdapter", () => {
   let adapter: OpenCodeAgentAdapter;
 
@@ -43,7 +45,6 @@ describe("OpenCodeAgentAdapter", () => {
   };
 
   beforeEach(() => {
-    vi.clearAllMocks();
     adapter = new OpenCodeAgentAdapter();
   });
 
@@ -61,7 +62,9 @@ describe("OpenCodeAgentAdapter", () => {
     });
 
     it("has correct configDir", () => {
-      expect(adapter.configDir).toBe(".opencode/agents");
+      // Live OpenCode dir is agent/ (singular). Observed ~/.config/opencode/agent/crash.md
+      // and OpenCode binary docs: `.opencode/agent/<name>.md`.
+      expect(adapter.configDir).toBe(".opencode/agent");
     });
   });
 
@@ -71,9 +74,9 @@ describe("OpenCodeAgentAdapter", () => {
       expect(files).toEqual([]);
     });
 
-    it("generates file at correct path", async () => {
+    it("generates file at the live OpenCode agent path", async () => {
       const files = await adapter.generate([testAgent]);
-      expect(files[0]!.path).toBe(".opencode/agents/reviewer.md");
+      expect(files[0]!.path).toBe(".opencode/agent/reviewer.md");
     });
 
     it("generates file with md format", async () => {
@@ -82,29 +85,51 @@ describe("OpenCodeAgentAdapter", () => {
     });
   });
 
+  describe("install", () => {
+    it("writes markdown into .opencode/agent, not .opencode/agents", async () => {
+      await withTempDir(async (dir) => {
+        const files = await adapter.generate([testAgent]);
+        await adapter.install(files, dir);
+
+        const agentPath = join(dir, ".opencode/agent/reviewer.md");
+        expect(existsSync(agentPath)).toBe(true);
+        expect(existsSync(join(dir, ".opencode/agents/reviewer.md"))).toBe(false);
+        expect(await readFile(agentPath, "utf-8")).toContain("# Code Reviewer");
+      });
+    });
+  });
+
   describe("import", () => {
     it("returns empty array when config dir does not exist", async () => {
-      vi.mocked(existsSync).mockReturnValue(false);
-      const agents = await adapter.import("/project");
-      expect(agents).toEqual([]);
+      await withTempDir(async (dir) => {
+        expect(await adapter.import(dir)).toEqual([]);
+      });
     });
 
     it("imports without cwd argument", async () => {
-      vi.mocked(existsSync).mockReturnValue(false);
-      const agents = await adapter.import();
-      expect(agents).toEqual([]);
+      await withTempDir(async (dir) => {
+        const cwdSpy = vi.spyOn(process, "cwd").mockReturnValue(dir);
+        try {
+          expect(await adapter.import()).toEqual([]);
+        } finally {
+          cwdSpy.mockRestore();
+        }
+      });
     });
 
     it("parses agent from markdown file", async () => {
-      vi.mocked(existsSync).mockReturnValue(true);
-      vi.mocked(readdir).mockResolvedValue(["reviewer.md"] as never);
-      vi.mocked(readFile).mockResolvedValue(
-        "---\ndescription: Reviews code\n---\n\n# Code Reviewer\n\nReview.\n",
-      );
-
-      const agents = await adapter.import("/project");
-      expect(agents).toHaveLength(1);
-      expect(agents[0]!.id).toBe("reviewer");
+      await withTempDir(async (dir) => {
+        await mkdir(join(dir, ".opencode/agent"), { recursive: true });
+        await writeFile(
+          join(dir, ".opencode/agent/reviewer.md"),
+          "---\ndescription: Reviews code\n---\n\n# Code Reviewer\n\nReview.\n",
+        );
+
+        const agents = await adapter.import(dir);
+        expect(agents).toHaveLength(1);
+        expect(agents[0]!.id).toBe("reviewer");
+        expect(agents[0]!.name).toBe("Code Reviewer");
+      });
     });
   });
 });

packages/agents/src/adapters/opencode.ts

@@ -3,7 +3,7 @@ import { createMarkdownAdapter } from "./markdown-adapter.js";
 const { Adapter: OpenCodeAgentAdapter, adapter } = createMarkdownAdapter({
   id: "opencode",
   name: "OpenCode",
-  configDir: ".opencode/agents",
+  configDir: ".opencode/agent",
   command: "opencode",
 });
 

packages/agents/src/adapters/zcode.test.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import type { AgentDefinition } from "../types/index.js";
+
+vi.mock("./index.js", () => {
+  const registry = { register: vi.fn() };
+  abstract class BaseAgentAdapter {
+    abstract readonly id: string;
+    abstract readonly name: string;
+    abstract readonly nativeSupport: boolean;
+    abstract readonly configDir: string;
+    abstract generate(agents: AgentDefinition[]): Promise<unknown[]>;
+    abstract import(cwd?: string): Promise<AgentDefinition[]>;
+    async detect() {
+      return false;
+    }
+    async install() {}
+    async uninstall() {}
+  }
+  return { BaseAgentAdapter, registry };
+});
+
+vi.mock("node:fs", () => ({ existsSync: vi.fn(() => false) }));
+vi.mock("node:fs/promises", () => ({ readFile: vi.fn(), readdir: vi.fn() }));
+
+import { ZcodeAgentAdapter } from "./zcode.js";
+
+describe("ZcodeAgentAdapter", () => {
+  it("writes markdown agents under .zcode/agents", async () => {
+    const adapter = new ZcodeAgentAdapter();
+    expect(adapter.id).toBe("zcode");
+    expect(adapter.configDir).toBe(".zcode/agents");
+    const files = await adapter.generate([
+      { id: "reviewer", name: "Reviewer", instructions: "Review diffs." },
+    ]);
+    expect(files[0]?.path).toBe(".zcode/agents/reviewer.md");
+  });
+});

packages/agents/src/adapters/zcode.ts

@@ -0,0 +1,11 @@
+import { createMarkdownAdapter } from "./markdown-adapter.js";
+
+const { Adapter: ZcodeAgentAdapter, adapter } = createMarkdownAdapter({
+  id: "zcode",
+  name: "ZCode",
+  configDir: ".zcode/agents",
+  command: "zcode",
+});
+
+export { ZcodeAgentAdapter };
+export default adapter;