agentsmesh 0.27.0 → 0.29.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.29.0
+
+### Minor Changes
+
+- 663f0e6: Strip elevated artifacts from remote `extends` sources by default
+
+  `hooks`, `permissions`, and `mcp` contributed by a **remote** `extends` source (`github:`, `gitlab:`, `git+…`, including `git+file://`) are now stripped during config load unless the entry opts in with `accept: [hooks, permissions, mcp]`. This closes a gap where a remote `extends` could inject shell-executing config (settings hooks, MCP launch specs) without the per-artifact consent that `agentsmesh install` already requires. Local `extends` remain trusted as-is, and a warning reports anything that was stripped.
+
+### Patch Changes
+
+- 11f90bc: Harden plugin source containment against intermediate-symlink escapes
+
+  The plugin loader now canonicalizes an unresolvable source path against its nearest existing ancestor instead of falling back to the raw path. This closes a gap where a local plugin `source` routed through a symlinked directory that resolves outside the project root could slip past the trust-boundary check when its entry file did not exist yet. Legitimate in-project plugins are unaffected.
+
+- c647c9b: Docs: the README now leads with lessons (the shared agent memory), adds a head-to-head comparison with Ruler and rulesync, embeds demo GIFs, leads the quickstart with the import-first path for existing repos, and documents the new `extends` `accept:` consent. Documentation-only — no behavior change.
+
+## 0.28.0
+
+### Minor Changes
+
+- e148490: Deterministic pre-edit lesson recall via a `PreToolUse` hook.
+
+  `agentsmesh init --lessons` now wires the recall hook under **both** `PreToolUse` and `PostToolUse`, and `agentsmesh lessons hook` is event-aware (it echoes the harness `hook_event_name`). On targets whose hooks can inject context before a tool call (e.g. Claude Code), matching lessons are now surfaced **before the first edit/command** — guarding the "first touch" the previous PostToolUse-only design left unguarded — with no extra model turn and no compliance dependence. Session dedup keeps each lesson injected at most once per session, and `PostToolUse` remains as the fallback for harnesses that support only post-call context injection. Existing projects pick this up by re-running `agentsmesh init --lessons` (idempotent) and `agentsmesh generate`; behavior is unchanged when no `hook_event_name` is supplied (defaults to `PostToolUse`).
+
 ## 0.27.0
 
 ### Minor Changes

package/README.md

@@ -1,8 +1,10 @@
 <div align="center">
 
-# AgentsMesh — One `.agentsmesh/` Directory for Every AI Coding Tool
+# AgentsMesh
 
-<img src="https://raw.githubusercontent.com/sampleXbro/agentsmesh/master/assets/agentsmesh-banner.jpeg" alt="AgentsMesh — One source. Every AI coding tool. Always in sync." width="100%" />
+### One source for every AI coding tool — with a shared agent memory that learns from your repo.
+
+<img src="https://raw.githubusercontent.com/sampleXbro/agentsmesh/master/assets/agentsmesh-banner.jpeg" alt="AgentsMesh — One source. Every AI coding tool. Agents that learn." width="100%" />
 
 [![CI](https://github.com/sampleXbro/agentsmesh/actions/workflows/ci.yml/badge.svg)](https://github.com/sampleXbro/agentsmesh/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/agentsmesh.svg)](https://www.npmjs.com/package/agentsmesh)
@@ -23,6 +25,28 @@ Every AI coding assistant has its own config format — `CLAUDE.md`, `AGENTS.md`
 > [!NOTE]
 > Full documentation, guides, and the per-tool reference live at **[samplexbro.github.io/agentsmesh](https://samplexbro.github.io/agentsmesh/)**.
 
+## How AgentsMesh compares
+
+Most config tools stop at copying rule files into each assistant's folder. AgentsMesh is the only one that also gives your agents a **shared memory that learns**, round-trips **losslessly** in both directions, and lets anyone **add a new tool as a plugin** — no release required.
+
+| Capability | AgentsMesh | [Ruler](https://github.com/intellectronica/ruler) | [rulesync](https://github.com/dyoshikawa/rulesync) |
+|---|:---:|:---:|:---:|
+| Generate native config for many tools | ✅ | ✅ | ✅ |
+| Import existing tool config back to source | ✅ | — | ✅ |
+| **Lossless round-trip** (re-import restores originals) | ✅ | — | partial |
+| Convert one tool's config directly to another | ✅ | — | ✅ |
+| **Automatic cross-tool link rebasing** | ✅ | — | — |
+| **Lessons — a shared agent memory that learns** | ✅ | — | — |
+| **Plugins — add a target without a release** | ✅ | — | — |
+| Cross-target lint (warn before silent data loss) | ✅ | — | — |
+| CI drift gate + git-merge recovery | ✅ | partial | partial |
+| Self-serve MCP server (agent-operable config) | ✅ | — | — |
+| `--json` everywhere + typed programmatic API | ✅ | — | partial |
+
+<sub>Reflects the public projects as of June 2026 — see the [alternatives guide](https://samplexbro.github.io/agentsmesh/reference/alternatives/) for sources and detail. Corrections welcome.</sub>
+
+Built to be depended on: **8,000+ tests** run on Linux, macOS, and Windows CI (Node 22 & 24), configs are JSON-Schema-validated, npm releases ship with [provenance](https://docs.npmjs.com/generating-provenance-statements), and standalone binaries are published with SHA-256 checksums.
+
 ## Install
 
 Every install method ships the same CLI (`agentsmesh`, plus the shorter `amsh` alias) and the same TypeScript library.
@@ -45,11 +69,14 @@ Standalone binaries are also on [GitHub Releases](https://github.com/sampleXbro/
 
 ## 60-second quickstart
 
-Works on Linux, macOS, and Windows. After [installing](#install):
+Works on Linux, macOS, and Windows. After [installing](#install), `agentsmesh init` adapts to your repo:
+
+- **Already using AI tools?** It detects your existing `.cursor/`, `.claude/`, `.github/copilot-instructions.md`, and more, and offers to import them all into one `.agentsmesh/` source — nothing rewritten by hand. (`agentsmesh init --yes` does it non-interactively.)
+- **Starting fresh?** It scaffolds a minimal `.agentsmesh/` to grow from.
 
 ```bash
-agentsmesh init       # scaffold .agentsmesh/ + agentsmesh.yaml
-agentsmesh generate   # write native configs for every enabled tool
+agentsmesh init       # detect & import existing configs, or scaffold fresh
+agentsmesh generate   # write each tool's native config from the one source
 agentsmesh check      # CI-friendly drift gate against .agentsmesh/.lock
 ```
 
@@ -99,20 +126,40 @@ AGENTS.md
 
 Edit canonical sources, run `agentsmesh generate`, and every native file above is (re)written for you — always in sync. Alongside the directory, `agentsmesh.yaml` selects which targets and features are enabled, `agentsmesh.local.yaml` holds per-developer overrides (gitignored), and `.agentsmesh/.lock` records the checksums that `agentsmesh check` enforces.
 
+<div align="center">
+  <img src="https://raw.githubusercontent.com/sampleXbro/agentsmesh/master/assets/generate-demo.gif" alt="agentsmesh detects existing tool configs, imports them into one source, and generates native config for every tool" width="100%" />
+</div>
+
 ## Teach your agents: lessons
 
-Lessons give your AI agents a **memory of past mistakes** — read *before* they touch anything, written *after* something goes wrong, so the same mistake doesn't happen twice in any tool.
+This is the part no other config-sync tool has. Lessons give your AI agents a **memory of past mistakes** — read *before* they touch anything, written *after* something goes wrong, so the same mistake doesn't happen twice in any tool. It's what turns a static pile of rules into an agent that gets better at *your* codebase over time.
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/sampleXbro/agentsmesh/master/assets/lessons-demo.gif" alt="an AI agent captures a lesson after a failure, then recalls it before editing the same file — triggered by file, command, or keyword" width="100%" />
+</div>
 
 The memory is one git-tracked file, `.agentsmesh/lessons/lessons.json`, and every agent talks to it through two commands:
 
 - **Recall** — before an edit or a state-changing command, the agent runs `agentsmesh lessons query --file <path> --cmd <command>` and follows the rules that match.
 - **Capture** — right after a failure (red test, lint error, review comment, wrong assumption), it saves the rule with `agentsmesh lessons add "<rule>" --topic <id> --trigger-file <glob>`.
 
+In practice:
+
+```bash
+# An agent breaks the Windows build, finds the cause, and writes the lesson down:
+agentsmesh lessons add "Normalize CLI display paths to forward slashes" \
+  --topic windows-paths --trigger-file "src/cli/**/*.ts"
+
+# Days later, any agent — in any tool — about to touch that path recalls it first:
+agentsmesh lessons query --file src/cli/output.ts
+# → "Normalize CLI display paths to forward slashes"
+```
+
 ```bash
 agentsmesh init --lessons && agentsmesh generate   # wire the recall/capture loop once
 ```
 
-`init --lessons` drops a small always-on rule into `.agentsmesh/rules/_root.md` (so every target gets the habit), seeds the full operating manual as a `lessons` skill where supported, and wires a `PostToolUse` recall hook on hook-capable tools; agents without shell access use the matching MCP tools (`lessons_query` / `lessons_add`). Because the graph is a normal git-tracked file, a lesson one agent learns today helps every teammate's agent tomorrow, and every change is reviewable like any other diff.
+`init --lessons` drops a small always-on rule into `.agentsmesh/rules/_root.md` (so every target gets the habit), seeds the full operating manual as a `lessons` skill where supported, and wires a recall hook (a `PreToolUse` first-touch guard plus a `PostToolUse` fallback) on hook-capable tools; agents without shell access use the matching MCP tools (`lessons_query` / `lessons_add`). Because the graph is a normal git-tracked file, a lesson one agent learns today helps every teammate's agent tomorrow, and every change is reviewable like any other diff.
 
 Full walkthrough: [Teach your AI agents with lessons](https://samplexbro.github.io/agentsmesh/guides/lessons/) · [`agentsmesh lessons` reference](https://samplexbro.github.io/agentsmesh/cli/lessons/).
 
@@ -125,8 +172,8 @@ Full walkthrough: [Teach your AI agents with lessons](https://samplexbro.github.
 - **Migrate between tools** — `convert --from <a> --to <b>` rewrites one tool's config directly into another's native format. [convert →](https://samplexbro.github.io/agentsmesh/cli/convert/)
 - **Global mode** — `~/.agentsmesh/` syncs your personal config to `~/.claude/`, `~/.cursor/`, `~/.codex/`, and more. Every command accepts `--global`. [Global paths →](https://samplexbro.github.io/agentsmesh/reference/supported-tools/#global-mode)
 - **Team-safe and CI-ready** — `check` is a drift gate against `.agentsmesh/.lock`, `diff` previews changes, `merge` rebuilds the lock after a 3-way Git conflict, and `lock_features` + per-feature `strategy` prevent accidental overrides. `lint` adds cross-target warnings (`silent-drop-guard`, `hook-script-references`, `rule-scope-inversion`) for content a tool would silently mishandle. [check →](https://samplexbro.github.io/agentsmesh/cli/check/) · [lint →](https://samplexbro.github.io/agentsmesh/cli/lint/)
-- **Community packs and `extends`** — install shared rules, skills, agents, and commands from any git repo (`install`, `--sync`, `refresh`, remote `extends`); a multi-signal classifier auto-detects Anthropic-style skill packs. Elevated artifacts (hooks, permissions, MCP) from remote sources are stripped unless you opt in with `--accept-*`. [Install reference →](https://samplexbro.github.io/agentsmesh/cli/install/)
-- **Plugins** — ship support for a new tool as a standalone npm package, with full parity to built-in targets (project + global, conversions, lint hooks, hook post-processing). [Build a plugin →](https://samplexbro.github.io/agentsmesh/guides/building-plugins/)
+- **Community packs and `extends`** — install shared rules, skills, agents, and commands from any git repo (`install`, `--sync`, `refresh`, remote `extends`); a multi-signal classifier auto-detects Anthropic-style skill packs. Elevated artifacts (hooks, permissions, MCP) from remote sources are stripped unless you opt in — with `--accept-*` on `install`, or `accept:` on a remote `extends` entry. [Install reference →](https://samplexbro.github.io/agentsmesh/cli/install/)
+- **Plugins — add a tool without waiting for a release** — ship support for a new AI tool as a standalone npm package, with full parity to built-in targets (project + global, conversions, lint hooks, hook post-processing). When a tool ships or changes its format, you don't file an issue and wait on the maintainer — you publish a plugin. [Build a plugin →](https://samplexbro.github.io/agentsmesh/guides/building-plugins/)
 - **Schema-validated configs** — each config ships a JSON Schema, so editors give you autocomplete and validation out of the box. [JSON schemas →](https://samplexbro.github.io/agentsmesh/reference/json-schemas/)
 - **Typed programmatic API** — drive `generate` / `import` / `lint` / `diff` / `check` from scripts or CI via `agentsmesh`, `/engine`, `/canonical`, `/targets`, `/lessons`. [API reference →](https://samplexbro.github.io/agentsmesh/reference/programmatic-api/)
 - **Self-serve MCP server** — `agentsmesh mcp` (seeded by `init`) exposes canonical config as MCP tools so agents can introspect rules, commands, and skills and trigger `generate` in-conversation. [MCP server →](https://samplexbro.github.io/agentsmesh/reference/mcp-server/)
@@ -135,9 +182,11 @@ Full walkthrough: [Teach your AI agents with lessons](https://samplexbro.github.
 > [!TIP]
 > Commit **both** `.agentsmesh/` and the generated tool files, the same way you commit `package-lock.json`: they're deterministic build output that the AI tools read directly, and `agentsmesh check` guards the two from drifting.
 
-## Why not just `AGENTS.md`?
+## Why not Ruler, rulesync, or just `AGENTS.md`?
+
+**vs. `AGENTS.md`** — [`AGENTS.md`](https://agents.md) is a great shared instruction file, and AgentsMesh emits it natively wherever a tool supports it. But a single markdown file isn't enough on its own: most assistants expose configuration *beyond* it — Cursor's `.cursor/rules/*.mdc` and MCP config, Claude Code's agents/skills/commands/hooks/permissions, Copilot's `.github/instructions/`, Gemini's `.gemini/settings.json`, and so on — and those surfaces don't overlap. AgentsMesh canonicalizes all of them so you never have to pick one tool's surface as the lowest common denominator.
 
-[`AGENTS.md`](https://agents.md) is a great shared instruction file, and AgentsMesh emits it natively wherever a tool supports it. But a single markdown file isn't enough on its own: most assistants expose configuration *beyond* it — Cursor's `.cursor/rules/*.mdc` and MCP config, Claude Code's agents/skills/commands/hooks/permissions, Copilot's `.github/instructions/`, Gemini's `.gemini/settings.json`, and so on — and those surfaces don't overlap. AgentsMesh canonicalizes all of them so you never have to pick one tool's surface as the lowest common denominator.
+**vs. other sync tools** — [Ruler](https://github.com/intellectronica/ruler) and [rulesync](https://github.com/dyoshikawa/rulesync) solve the rules-distribution half well. AgentsMesh goes further on the parts that are hardest to keep in sync: a shared [lessons](#teach-your-agents-lessons) memory your agents learn from, lossless two-way [import](https://samplexbro.github.io/agentsmesh/cli/import/), automatic cross-tool [link rebasing](https://samplexbro.github.io/agentsmesh/reference/generation-pipeline/), [plugins](https://samplexbro.github.io/agentsmesh/guides/building-plugins/) so a new tool ships without a release, and [lint](https://samplexbro.github.io/agentsmesh/cli/lint/) that warns before a tool would silently drop content. See the [full comparison](#how-agentsmesh-compares) and the [alternatives guide](https://samplexbro.github.io/agentsmesh/reference/alternatives/).
 
 ## Commands
 

package/dist/canonical.d.ts

@@ -1,5 +1,5 @@
-import { b as CanonicalFiles, V as ValidatedConfig } from './schema-CzaoYJlG.js';
-export { C as CanonicalAgent, a as CanonicalCommand, c as CanonicalRule, d as CanonicalSkill, H as HookEntry, e as Hooks, I as IgnorePatterns, M as McpConfig, f as McpServer, P as Permissions, S as SkillSupportingFile, g as StdioMcpServer, U as UrlMcpServer } from './schema-CzaoYJlG.js';
+import { b as CanonicalFiles, V as ValidatedConfig } from './schema-CH_JJep8.js';
+export { C as CanonicalAgent, a as CanonicalCommand, c as CanonicalRule, d as CanonicalSkill, H as HookEntry, e as Hooks, I as IgnorePatterns, M as McpConfig, f as McpServer, P as Permissions, S as SkillSupportingFile, g as StdioMcpServer, U as UrlMcpServer } from './schema-CH_JJep8.js';
 import 'zod';
 
 interface UnrecognizedFormatsWarningOptions {

package/dist/canonical.js

@@ -20874,7 +20874,9 @@ async function resolveExtendPaths(config, configDir, options = {}) {
         as: ext.as,
         version: fetched.version,
         path: ext.path,
-        pick: ext.pick
+        pick: ext.pick,
+        isRemote: true,
+        accept: ext.accept
       });
       continue;
     }
@@ -20891,7 +20893,9 @@ async function resolveExtendPaths(config, configDir, options = {}) {
       target: ext.target,
       as: ext.as,
       path: ext.path,
-      pick: ext.pick
+      pick: ext.pick,
+      isRemote: false,
+      accept: ext.accept
     });
   }
   return result;
@@ -22421,6 +22425,47 @@ function applyExtendPick(canonical, features, pick, extendName) {
   return next;
 }
 
+// src/install/core/elevated-artifacts.ts
+function stripUntrustedElevatedArtifacts(canonical, options) {
+  if (options.sourceKind === "local") {
+    return { canonical, stripped: [] };
+  }
+  const stripped = [];
+  let hooks = canonical.hooks;
+  let permissions = canonical.permissions;
+  let mcp = canonical.mcp;
+  if (hooks !== null && !options.acceptHooks) {
+    hooks = null;
+    stripped.push("hooks");
+  }
+  if (permissions !== null && !options.acceptPermissions) {
+    permissions = null;
+    stripped.push("permissions");
+  }
+  if (mcp !== null && !options.acceptMcp) {
+    mcp = null;
+    stripped.push("mcp");
+  }
+  if (stripped.length === 0) {
+    return { canonical, stripped: [] };
+  }
+  return {
+    canonical: { ...canonical, hooks, permissions, mcp },
+    stripped
+  };
+}
+
+// src/canonical/extends/extend-elevated.ts
+function gateExtendElevatedArtifacts(canonical, ext) {
+  const accept = ext.accept ?? [];
+  return stripUntrustedElevatedArtifacts(canonical, {
+    sourceKind: ext.isRemote ? "git" : "local",
+    acceptHooks: accept.includes("hooks"),
+    acceptPermissions: accept.includes("permissions"),
+    acceptMcp: accept.includes("mcp")
+  });
+}
+
 // src/install/pack/pack-reader.ts
 init_fs();
 
@@ -22454,7 +22499,14 @@ var extendSourceSchema = z.object({
   features: z.array(featureSchema),
   /** Repo-relative POSIX path for discovery (skill packs, nested .agentsmesh). */
   path: z.string().optional(),
-  pick: extendPickSchema.optional()
+  pick: extendPickSchema.optional(),
+  /**
+   * Per-entry consent for "elevated" artifacts (`hooks`, `permissions`, `mcp`)
+   * from a remote source. These control local code execution at generate time,
+   * so for non-local extends they are stripped by default and only merged for
+   * the artifacts listed here. Local extends are trusted and ignore this field.
+   */
+  accept: z.array(z.enum(["hooks", "permissions", "mcp"])).optional()
 });
 var collaborationSchema = z.object({
   strategy: z.enum(["merge", "lock", "last-wins"]).default("merge"),
@@ -22646,7 +22698,14 @@ async function loadCanonicalWithExtends(config, configDir, options = {}, canonic
   for (const ext of resolvedExtends) {
     const extCanonical = await loadCanonicalForExtend(ext);
     const filtered = filterCanonicalByFeatures(extCanonical, ext.features);
-    const picked = applyExtendPick(filtered, ext.features, ext.pick, ext.name);
+    const gated = gateExtendElevatedArtifacts(filtered, ext);
+    if (gated.stripped.length > 0) {
+      const list = gated.stripped.join(", ");
+      logger.warn(
+        `[agentsmesh] Extend "${ext.name}": stripped elevated artifacts from a remote source: ${list}. Add \`accept: [${list}]\` to this extends entry in agentsmesh.yaml to keep them.`
+      );
+    }
+    const picked = applyExtendPick(gated.canonical, ext.features, ext.pick, ext.name);
     merged = mergeCanonicalFiles(merged, picked);
   }
   const packsCanonical = await loadPacksCanonical(canonicalDir);