ethagent 4.1.1 → 4.2.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ethagent",
-  "version": "4.1.1",
+  "version": "4.2.0",
   "description": "Portable Ethereum identity for your AI agent. Its soul, memory, and skills live onchain via ERC-8004 + IPFS and snap back into any session.",
   "author": { "name": "bairon.dev" },
   "homepage": "https://github.com/baairon/ethagent",
@@ -19,7 +19,7 @@
       {
         "matcher": "Edit|Write|MultiEdit",
         "hooks": [
-          { "type": "command", "command": "npx -y ethagent --memory-guard" }
+          { "type": "command", "command": "npx -y ethagent --pretool-guard" }
         ]
       }
     ],

package/README.md

@@ -42,7 +42,7 @@ That's the whole setup. You'll only open `ethagent` again to hand-edit your agen
 
 - **Soul** (`SOUL.md`): who it is, your standards, your voice, the way you work.
 - **Memory** (`MEMORY.md`): what it has learned about you, your preferences, and your projects, so context survives the move to a new machine.
-- **Skills:** the commands, tools, and prompts you teach it. Public by default, so other agents can discover them; mark one private to keep it off your public Agent Card (the profile your token publishes).
+- **Skills:** the commands, tools, and prompts you teach it. **Private by default** — yours alone, encrypted in your vault and mirrored into your harnesses so you can use them locally, but kept off your public Agent Card. Make one **public** when you want other agents to discover it; then only its name and description go on the card your token publishes.
 
 You grow these mostly by talking: with the plugin on, your agent updates its own soul and memory as you converse, and the changes sync automatically. To edit them by hand, open `ethagent`. To save your agent onchain so it can come back on any machine, choose **Save Snapshot** and sign.
 
@@ -63,7 +63,7 @@ Using another harness? You can still sync, but only Claude Code does it automati
 npx ethagent --sync
 ```
 
-It syncs files between `ethagent` and your harness on this machine, but only when you run it. To back it up so you can restore it anywhere, open `ethagent` and choose **Save Snapshot**.
+One command syncs it into every harness on this machine — soul, memory, and skills (public and private) — but only when you run it. To back it up so you can restore it anywhere, open `ethagent` and choose **Save Snapshot**.
 
 ## 🔒 What stays private
 
@@ -95,6 +95,22 @@ Built on open standards, so your agent is never tied to one harness.
 | Naming | ENS | A human-readable name that resolves to your agent and restores it from the name alone. |
 | Backup | IPFS snapshot | The encrypted bundle of soul, memory, and skills, pinned offchain and unlocked only by your wallet. |
 
+## 🔄 Updating
+
+ethagent ships as two pieces, and a full update can touch both:
+
+- **The npm package** (the engine: sync, skills, the guards). The plugin's hooks call `npx -y ethagent`, which resolves the latest published release, so **publishing a new version is the update** — nothing for most people to run. If you installed it globally, or call a bare `ethagent` in a hook or your shell, refresh that copy:
+
+  ```bash
+  npm i -g ethagent@latest
+  ```
+
+  Confirm what you're running with `ethagent --version`.
+
+- **The Claude Code plugin** (the hook wiring). New hooks ship in the plugin manifest, so to pick them up, update the plugin from the marketplace with `/plugin`.
+
+Rule of thumb: new sync and skill behavior rides your existing hooks as soon as the package is published; a brand-new hook also needs a plugin update.
+
 ## ⌨️ Commands
 
 Run with `npx ethagent`:
@@ -102,7 +118,7 @@ Run with `npx ethagent`:
 | Command | What it does |
 | --- | --- |
 | `ethagent` | Open the interactive identity manager: create, ENS, custody, snapshots, transfer. |
-| `--sync` | Sync soul, memory, and public skills into every harness it detects. |
+| `--sync` | Sync soul, memory, and skills (public and private) into every harness it detects. |
 | `--sync-list` | List sync adapters and which ones detect in the current environment. |
 | `--status` | Print a one-line identity summary. |
 | `--demo` | Walk the manager with synthetic data, no wallet needed. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ethagent",
-  "version": "4.1.1",
+  "version": "4.2.0",
   "description": "Portable Ethereum identity for your AI agent. Its soul, memory, and skills live onchain via ERC-8004 + IPFS and snap back into any session.",
   "type": "module",
   "bin": {

package/src/cli/main.tsx

@@ -13,6 +13,8 @@ import type { IdentityManagerResult } from '../identity/manager/IdentityManager.
 import { loadConfig, saveConfig, type EthagentConfig } from '../storage/config.js'
 import { runSync, runSyncList, runSyncOnEdit } from './sync.js'
 import { runMemoryGuard } from './memoryGuard.js'
+import { runSkillGuard } from './skillGuard.js'
+import { runPreToolGuard } from './pretoolGuard.js'
 import { runSessionStart } from './sessionStart.js'
 import { runStatus } from './status.js'
 import { runResetCommand } from './reset.js'
@@ -46,7 +48,9 @@ function printHelp(): void {
     '',
     'plugin hooks (invoked automatically, not meant to be run by hand):',
     '  ethagent --session-start    sync, then tell the agent where to record memory',
+    '  ethagent --pretool-guard    one PreToolUse guard combining --memory-guard + --skill-guard',
     '  ethagent --memory-guard     keep agent memory in the portable markers, not local notes',
+    '  ethagent --skill-guard      keep skills in the portable vault, not the harness mirror',
   ]
   for (const line of lines) process.stdout.write(line + '\n')
 }
@@ -149,7 +153,9 @@ async function main(): Promise<number> {
   }
   if (flags.has('--sync-on-edit')) return runSyncOnEdit()
   if (flags.has('--session-start')) return runSessionStart()
+  if (flags.has('--pretool-guard')) return runPreToolGuard()
   if (flags.has('--memory-guard')) return runMemoryGuard()
+  if (flags.has('--skill-guard')) return runSkillGuard()
   if (flags.has('--sync-list')) return runSyncList()
   if (flags.has('--sync')) return runSync()
   if (flags.has('--status')) return runStatus(version)

package/src/cli/pretoolGuard.ts

@@ -0,0 +1,32 @@
+import { loadConfig } from '../storage/config.js'
+import { hookFilePath, readHookPayload } from './hookIo.js'
+import { decideMemoryGuard } from './memoryGuard.js'
+import { decideSkillGuard } from './skillGuard.js'
+
+/**
+ * Combined PreToolUse guard: runs the memory-dir guard and the skills-mirror
+ * guard from a single process, so each Edit/Write/MultiEdit spawns one `npx`
+ * (one config load, one stdin read) instead of two. The two guards check
+ * disjoint directories, so at most one denies.
+ */
+export async function runPreToolGuard(): Promise<number> {
+  try {
+    const config = await loadConfig()
+    const filePath = hookFilePath(await readHookPayload())
+    const opts = { identityPresent: !!config?.identity }
+    const memory = decideMemoryGuard(filePath, opts)
+    const decision = memory.deny ? memory : decideSkillGuard(filePath, opts)
+    if (decision.deny) {
+      process.stdout.write(
+        JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'deny',
+            permissionDecisionReason: decision.reason,
+          },
+        }) + '\n',
+      )
+    }
+  } catch {}
+  return 0
+}

package/src/cli/skillGuard.ts

@@ -0,0 +1,47 @@
+import { loadConfig } from '../storage/config.js'
+import { hookFilePath, isWithinDir, readHookPayload } from './hookIo.js'
+import { claudeSkillsDir } from './syncAdapters/claude-code.js'
+
+export const SKILL_REDIRECT_REASON =
+  "ethagent keeps this agent's skills in its portable continuity vault and generates the ~/.claude/skills " +
+  'mirror from it. Skills you create or edit directly here do not travel with the agent, and ethagent-managed ' +
+  'mirror copies are regenerated from the vault on the next sync. Author or edit skills in the vault instead: ' +
+  'run `ethagent` and open Skills (create, edit, set visibility) so they are versioned, encrypted, and synced ' +
+  'into every harness automatically. New skills are private by default; switch one to public only when you want ' +
+  'it listed on your Agent Card.'
+
+export function decideSkillGuard(
+  filePath: string | null | undefined,
+  opts: { identityPresent: boolean },
+): { deny: boolean; reason?: string } {
+  if (!opts.identityPresent) return { deny: false }
+  if (!filePath) return { deny: false }
+  // Scope: this guards the Claude Code skills mirror only. The Codex
+  // ~/.codex/AGENTS.md skill mirror is intentionally left unguarded, matching
+  // the Claude-only --memory-guard — the PreToolUse hook is registered only in
+  // the Claude Code plugin manifest.
+  if (isWithinDir(claudeSkillsDir(), filePath)) {
+    return { deny: true, reason: SKILL_REDIRECT_REASON }
+  }
+  return { deny: false }
+}
+
+export async function runSkillGuard(): Promise<number> {
+  try {
+    const config = await loadConfig()
+    const filePath = hookFilePath(await readHookPayload())
+    const decision = decideSkillGuard(filePath, { identityPresent: !!config?.identity })
+    if (decision.deny) {
+      process.stdout.write(
+        JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'deny',
+            permissionDecisionReason: decision.reason,
+          },
+        }) + '\n',
+      )
+    }
+  } catch {}
+  return 0
+}

package/src/cli/sync.ts

@@ -5,6 +5,7 @@ import { continuityWorkingTreeStatus } from '../identity/continuity/storage/stat
 import { listPublishedContinuitySnapshots } from '../identity/continuity/snapshots.js'
 import { changedContinuitySnapshotFiles } from '../identity/manager/continuity/state.js'
 import { listSkills } from '../identity/continuity/skills/loadSkills.js'
+import { isDraftScaffold } from '../identity/continuity/skills/scaffold.js'
 import { hashManagedBody, normalizeBody, reconstructVaultFile, sectionKey } from './syncAdapters/managedBlock.js'
 import { hookFilePath, readHookPayload, samePath } from './hookIo.js'
 import {
@@ -16,6 +17,15 @@ import type { PublicSkill } from './syncAdapters/shared.js'
 
 export type SyncOptions = { quiet?: boolean }
 
+/**
+ * Skills mirrored into local harnesses: every real skill (public AND private),
+ * so private skills are usable locally. The public Agent Card stays public-only
+ * (built separately via derivePublicSkillEntries). Drafts/scaffolds are skipped.
+ */
+export function selectMirrorSkills(all: readonly PublicSkill[]): PublicSkill[] {
+  return all.filter(s => !isDraftScaffold(s))
+}
+
 export async function runSync(opts: SyncOptions = {}): Promise<number> {
   const config = await loadConfig()
   if (!config?.identity) return 0
@@ -27,7 +37,7 @@ export async function runSync(opts: SyncOptions = {}): Promise<number> {
     process.stderr.write(`ethagent: could not load skills, skipping sync to avoid removing managed files (${(err as Error).message})\n`)
     return 1
   }
-  const publicSkills: PublicSkill[] = all.filter(s => s.visibility === 'public')
+  const mirrorSkills: PublicSkill[] = selectMirrorSkills(all)
 
   const targets: SyncAdapter[] = []
   for (const adapter of BUILT_IN_ADAPTERS) {
@@ -52,7 +62,7 @@ export async function runSync(opts: SyncOptions = {}): Promise<number> {
   const summaries: string[] = []
   for (const adapter of targets) {
     try {
-      const { count, skipped } = await adapter.mirror(publicSkills, context)
+      const { count, skipped } = await adapter.mirror(mirrorSkills, context)
       let summary = `${adapter.name}: ${count} skill${count === 1 ? '' : 's'}`
       if (skipped > 0) summary += `, skipped ${skipped} unmanaged`
       summaries.push(summary)

package/src/cli/syncAdapters/claude-code.ts

@@ -9,7 +9,7 @@ function claudeDir(): string {
   return path.join(os.homedir(), '.claude')
 }
 
-function claudeSkillsDir(): string {
+export function claudeSkillsDir(): string {
   return path.join(claudeDir(), 'skills')
 }
 
@@ -44,7 +44,7 @@ export async function projectMemoryMirrorsUnder(claudeRoot: string): Promise<str
 
 export const claudeCodeAdapter = {
   name: 'claude-code' as const,
-  description: 'Mirror public skills into ~/.claude/skills and inject soul/memory into ~/.claude/CLAUDE.md and the project MEMORY.md.',
+  description: 'Mirror skills (public and private) into ~/.claude/skills and inject soul/memory into ~/.claude/CLAUDE.md and the project MEMORY.md.',
   async detect(): Promise<boolean> {
     return pathExists(claudeDir())
   },

package/src/cli/syncAdapters/codex.ts

@@ -33,7 +33,7 @@ function neutralizeManagedMarkers(text: string): string {
 }
 
 function renderSkillsText(skills: EnrichedSkill[]): string {
-  if (skills.length === 0) return '_no public skills published yet._'
+  if (skills.length === 0) return '_no skills synced yet._'
   const lines: string[] = []
   for (const skill of skills) {
     lines.push(`## ${neutralizeManagedMarkers(skill.displayName ?? skill.name)}`, '')
@@ -45,7 +45,7 @@ function renderSkillsText(skills: EnrichedSkill[]): string {
 
 export const codexAdapter = {
   name: 'codex' as const,
-  description: 'Merge soul, memory, and public skill content into ~/.codex/AGENTS.md between ethagent markers.',
+  description: 'Merge soul, memory, and skill content (public and private) into ~/.codex/AGENTS.md between ethagent markers.',
   async detect(): Promise<boolean> {
     return pathExists(path.join(codexDir(), 'config.toml'))
   },

package/src/cli/syncAdapters/shared.ts

@@ -1,6 +1,15 @@
 import fs from 'node:fs/promises'
 import path from 'node:path'
 import type { SkillIndexEntry } from '../../identity/continuity/skills/types.js'
+import {
+  isReservedWindowsSegment,
+  isValidFilenameSegment,
+  isValidSegment,
+  MAX_FOLDER_DEPTH,
+} from '../../identity/continuity/skills/skillPaths.js'
+
+// Cap copied files at the same size the vault loader enforces.
+const MAX_MIRROR_FILE_BYTES = 256 * 1024
 
 export type PublicSkill = SkillIndexEntry
 
@@ -30,6 +39,39 @@ export async function pathExists(file: string): Promise<boolean> {
   try { await fs.access(file); return true } catch { return false }
 }
 
+/**
+ * Copy a vault skill folder into the harness, applying the SAME vetting the
+ * vault loader uses (skip symlinks, dotfiles, reserved Windows names, invalid
+ * segments, and oversize files) so the mirror never copies a superset of — or a
+ * symlink escaping — the vault's recognized file set.
+ */
+async function copyVettedSkillTree(srcDir: string, destDir: string, depth = 0): Promise<void> {
+  if (depth > MAX_FOLDER_DEPTH) return
+  await fs.mkdir(destDir, { recursive: true })
+  let entries: import('node:fs').Dirent[]
+  try {
+    entries = await fs.readdir(srcDir, { withFileTypes: true })
+  } catch {
+    return
+  }
+  for (const ent of entries) {
+    if (ent.isSymbolicLink()) continue
+    if (ent.name.startsWith('.')) continue
+    if (isReservedWindowsSegment(ent.name)) continue
+    const srcPath = path.join(srcDir, ent.name)
+    const destPath = path.join(destDir, ent.name)
+    if (ent.isDirectory()) {
+      if (!isValidSegment(ent.name)) continue
+      await copyVettedSkillTree(srcPath, destPath, depth + 1)
+    } else if (ent.isFile()) {
+      if (!isValidFilenameSegment(ent.name)) continue
+      const stat = await fs.stat(srcPath).catch(() => null)
+      if (!stat || stat.size > MAX_MIRROR_FILE_BYTES) continue
+      await fs.copyFile(srcPath, destPath)
+    }
+  }
+}
+
 export async function mirrorAsSkillFolders(
   root: string,
   skills: PublicSkill[],
@@ -41,16 +83,25 @@ export async function mirrorAsSkillFolders(
   let skipped = 0
   for (const skill of skills) {
     const targetDir = path.join(root, skill.name)
-    const targetFile = path.join(targetDir, 'SKILL.md')
     const exists = await pathExists(targetDir)
     const isOurs = manifest.skills.includes(skill.name)
     if (exists && !isOurs) { skipped++; continue }
+    const srcDir = path.dirname(skill.absolutePath)
+    const tmpDir = path.join(root, `.${skill.name}.ethagent-tmp`)
     try {
-      const body = await fs.readFile(skill.absolutePath, 'utf8')
-      await fs.mkdir(targetDir, { recursive: true })
-      await fs.writeFile(targetFile, body, 'utf8')
+      // Stage the new copy in a temp sibling, then swap it in. This keeps the
+      // existing managed copy intact if the copy fails (no destructive
+      // rm-before-write window), and refreshes the whole folder (scripts/,
+      // assets/), dropping files removed upstream.
+      await fs.rm(tmpDir, { recursive: true, force: true })
+      await copyVettedSkillTree(srcDir, tmpDir)
+      await fs.rm(targetDir, { recursive: true, force: true })
+      await fs.rename(tmpDir, targetDir)
       owned.push(skill.name)
-    } catch {}
+    } catch (err) {
+      await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => null)
+      process.stderr.write(`ethagent: failed to mirror skill "${skill.name}": ${(err as Error).message}\n`)
+    }
   }
   const keep = new Set<string>(owned)
   for (const name of manifest.skills) if (incoming.has(name)) keep.add(name)

package/src/identity/continuity/skills/loadSkills.ts

@@ -517,7 +517,7 @@ async function pathExists(file: string): Promise<boolean> {
   }
 }
 
-const DEFAULT_PASTED_VISIBILITY: SkillVisibility = 'public'
+const DEFAULT_SKILL_VISIBILITY: SkillVisibility = 'private'
 const LEGACY_DISCOVERABLE_RE = /^\s*visibility\s*:\s*['"]?discoverable['"]?\s*$/im
 
 async function ensureSkillVisibilityWritten(skillFile: string, raw: string): Promise<string> {
@@ -531,7 +531,7 @@ async function ensureSkillVisibilityWritten(skillFile: string, raw: string): Pro
   if (LEGACY_DISCOVERABLE_RE.test(raw)) {
     target = 'private'
   } else if (parsed.frontmatter.visibility === undefined) {
-    target = DEFAULT_PASTED_VISIBILITY
+    target = DEFAULT_SKILL_VISIBILITY
   }
   if (target === null) return raw
   const next = rewriteVisibility(raw, target)
@@ -587,7 +587,7 @@ function buildIndexEntry(args: {
   const derivedName = folder || segments.join('/')
   const fm = args.parsed.frontmatter
   const description = pickDescription(fm.description, args.parsed.body)
-  const visibility: SkillVisibility = fm.visibility ?? DEFAULT_PASTED_VISIBILITY
+  const visibility: SkillVisibility = fm.visibility ?? DEFAULT_SKILL_VISIBILITY
   return {
     name: derivedName,
     ...(fm.name ? { displayName: fm.name } : {}),

package/src/identity/continuity/skills/scaffold.ts

@@ -5,7 +5,7 @@ export type SkillScaffoldArgs = {
   visibility?: SkillVisibility
 }
 
-export function defaultSkillScaffold({ name, visibility = 'public' }: SkillScaffoldArgs): string {
+export function defaultSkillScaffold({ name, visibility = 'private' }: SkillScaffoldArgs): string {
   return [
     '---',
     `name: ${name}`,

package/src/identity/manager/continuity/skills/NewSkillVisibilityScreen.tsx

@@ -22,7 +22,7 @@ export const NewSkillVisibilityScreen: React.FC<NewSkillVisibilityScreenProps> =
 }) => (
   <Surface
     title={`Visibility · ${name}`}
-    subtitle="Public is the default."
+    subtitle="Private is the default."
     footer={footer}
   >
     {error && (
@@ -39,7 +39,7 @@ export const NewSkillVisibilityScreen: React.FC<NewSkillVisibilityScreenProps> =
           { value: 'back', label: 'Back', role: 'utility' },
         ]}
         hintLayout="inline"
-        initialIndex={1}
+        initialIndex={0}
         onSubmit={choice => {
           if (choice === 'back') return onCancel()
           return onSelect(choice)