@dzhechkov/harness-core 0.8.10 → 0.8.20

package/src/setup.ts

@@ -17,10 +17,17 @@
  */
 
 import { existsSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs';
-import { join } from 'node:path';
-import { execSync } from 'node:child_process';
+import { basename, dirname, join } from 'node:path';
+import { execSync, spawnSync } from 'node:child_process';
 
 import { mergeManagedHookEntries } from './managed-hooks.js';
+import {
+  CLAUDE_DESTRUCTIVE_HOOK_COMMAND,
+  CLAUDE_DESTRUCTIVE_HOOK_MATCHER,
+  CLAUDE_DESTRUCTIVE_HOOK_RELPATH,
+  generateClaudeDestructiveHook,
+  isDzManagedHookBody,
+} from './claude-hooks-assets.js';
 import { applyIntegrationFragments, IntegrationApplyError } from './integration-apply.js';
 
 /** Memory backend type. */
@@ -251,6 +258,102 @@ export function commandsOf(entry: unknown): string[] {
   return [String(e?.command ?? '')];
 }
 
+export interface GuardInstallReceipt {
+  /** True ONLY when the installed file was RUN and refused a command it must refuse. */
+  readonly ok: boolean;
+  /** What was observed — an exit code and the first line it printed, or why it could not run. */
+  readonly detail: string;
+}
+
+/**
+ * Prove the installed hook WORKS, by running it (feature `destructive-command-guard`, review
+ * round 4, P2).
+ *
+ * Presence is not proof and a successful write is not proof either: the body must load its decider
+ * (which lives in another package directory), and that resolution is exactly what broke in the
+ * global-install layout one round ago. So the receipt is POSITIVE and end-to-end — the file is
+ * spawned with a payload it is obliged to refuse, and only `exit 2` carrying our marker counts.
+ * Anything else — a crash, a silent pass, a missing file, a spawn that could not happen — is `ok:
+ * false` with the observation named, never an assumption about the cause.
+ *
+ * The registry entry is written only when this returns `ok`. A hook that is registered but cannot
+ * run is worse than no hook at all: the breakage lands on EVERY Bash call instead of on none.
+ *
+ * SAFETY PRECONDITION (round 11): this SPAWNS the file, so the caller must only ever call it on a
+ * body dz owns — one carrying the ownership marker, or one dz has just written itself. Calling it
+ * on a preserved foreign body turns `dz setup` into a runner for whatever a cloned repository
+ * committed at that path.
+ */
+export function probeInstalledGuard(
+  hookPath: string,
+  opts: { projectRoot?: string } = {},
+): GuardInstallReceipt {
+  const payload = JSON.stringify({
+    hook_event_name: 'PreToolUse',
+    tool_name: 'Bash',
+    tool_input: { command: 'rm -rf .agentic-qe' },
+  });
+  let run;
+  try {
+    // DZ_GUARD_TRUSTED_ONLY makes the hook resolve its decision module from the INSTALLED
+    // harness-core alone. Without it the probe imports the project's own copy first, so a cloned
+    // repository that commits `packages/@dzhechkov/harness-core/dist/destructive-guard-hook.js`
+    // gets its top-level JavaScript executed by `dz setup` — the round-11 protection ("a foreign
+    // BODY is never spawned") one resolution step further in (cross-family review, gpt-5.6-sol,
+    // round 13). MEASURED before the fix: the planted module's marker reached stderr and its
+    // decider answered `allow`.
+    const env: NodeJS.ProcessEnv = { ...process.env, DZ_GUARD_TRUSTED_ONLY: '1' };
+    if (opts.projectRoot !== undefined) env.CLAUDE_PROJECT_DIR = opts.projectRoot;
+    run = spawnSync(process.execPath, [hookPath], {
+      input: payload,
+      encoding: 'utf-8',
+      timeout: 15_000,
+      env,
+    });
+  } catch (err) {
+    return { ok: false, detail: `не удалось запустить хук: ${String((err as Error).message)}` };
+  }
+  if (run.error !== undefined) return { ok: false, detail: `не удалось запустить хук: ${run.error.message}` };
+  const firstLine = String(run.stderr ?? '').split('\n')[0] ?? '';
+  if (run.status !== 2 || !firstLine.includes('DZ-DESTRUCTIVE:')) {
+    return {
+      ok: false,
+      detail: `установленный хук НЕ отказал на контрольной команде (код выхода ${String(run.status)}; ${firstLine || 'пустой stderr'})`,
+    };
+  }
+  return { ok: true, detail: 'живая проба: отказ на контрольной команде, код выхода 2' };
+}
+
+/**
+ * The destructive-command guard's registry entry (feature `destructive-command-guard`, task T8).
+ *
+ * Emitted for EVERY backend, because the guard has nothing to do with where learning memory is
+ * stored. MEASURED 2026-09-05, before this existed: `dz setup --target claude-code` into a clean
+ * project wrote no `PreToolUse` key at all and created no `.claude/hooks/` — the guard we document
+ * protected only our own checkout.
+ */
+const CLAUDE_DESTRUCTIVE_HOOK_TIMEOUT_MS = 5000;
+const LEGACY_CLAUDE_DESTRUCTIVE_HOOK_COMMANDS: ReadonlySet<string> = new Set([
+  `node "\${CLAUDE_PROJECT_DIR:-.}/${CLAUDE_DESTRUCTIVE_HOOK_RELPATH}"`,
+]);
+
+/** Attribute only commands dz actually emitted, never arbitrary text that mentions the path. */
+function isManagedClaudeDestructiveHookCommand(command: string): boolean {
+  return command === CLAUDE_DESTRUCTIVE_HOOK_COMMAND
+    || LEGACY_CLAUDE_DESTRUCTIVE_HOOK_COMMANDS.has(command);
+}
+
+function destructiveGuardHookEntry(): { matcher: string; hooks: { type: string; command: string; timeout: number }[] } {
+  return {
+    matcher: CLAUDE_DESTRUCTIVE_HOOK_MATCHER,
+    hooks: [{
+      type: 'command',
+      command: CLAUDE_DESTRUCTIVE_HOOK_COMMAND,
+      timeout: CLAUDE_DESTRUCTIVE_HOOK_TIMEOUT_MS,
+    }],
+  };
+}
+
 export function generateHooksConfig(projectRoot: string, backend: MemoryBackend): string {
   const dzDir = join(projectRoot, '.dz');
 
@@ -272,6 +375,7 @@ export function generateHooksConfig(projectRoot: string, backend: MemoryBackend)
         SessionStart: [{ hooks: [{ type: 'command', command: `node ${JSON.stringify(writer)} start` }] }],
         SessionEnd: [{ hooks: [{ type: 'command', command: `node ${JSON.stringify(writer)} end` }] }],
         PreCompact: [{ hooks: [{ type: 'command', command: `node ${JSON.stringify(writer)} precompact`, runInBackground: true }] }],
+        PreToolUse: [destructiveGuardHookEntry()],
       },
     }, null, 2);
   }
@@ -289,6 +393,7 @@ export function generateHooksConfig(projectRoot: string, backend: MemoryBackend)
       SessionStart: [{ hooks: [{ type: 'command', command: jsonlCmd('start') }] }],
       SessionEnd: [{ hooks: [{ type: 'command', command: jsonlCmd('end') }] }],
       PreCompact: [{ hooks: [{ type: 'command', command: jsonlCmd('precompact'), runInBackground: true }] }],
+      PreToolUse: [destructiveGuardHookEntry()],
     },
   }, null, 2);
 }
@@ -614,10 +719,125 @@ export function runSetup(opts: SetupOptions): SetupResult {
   if (!opts.noHooks) {
     const settingsDir = join(opts.projectRoot, '.claude');
     const settingsPath = join(settingsDir, 'settings.json');
+
+    // The BODY goes in first, and the ENTRY goes in only after a LIVE receipt that the body runs
+    // and refuses. Written from the INSTALLED package, never copied out of our repository — a
+    // consumer has no `packages/@dzhechkov/...` above their project.
+    //
+    // Round 4, P2: these two used to be independent. A failed write was recorded as an error and
+    // the entry was merged anyway, so a consumer whose install failed got a `PreToolUse` entry
+    // pointing at something that is not a runnable hook — and that breaks EVERY Bash call, not one.
+    //
+    // Round 5, P1: the write was also UNCONDITIONAL. Setup is additive everywhere else — the
+    // settings merge keeps the user's own hooks, `.gitignore` is appended to, an existing skill is
+    // skipped — and this path overwrote a well-known filename with no ownership check, so a
+    // consumer's hand-authored `.claude/hooks/destructive-guard.cjs` was destroyed by a routine
+    // run. A body we wrote carries a MARKER; a file without it is the consumer's, and only an
+    // explicit `--force` may replace it, after a timestamped backup.
+    const hookPath = join(opts.projectRoot, ...CLAUDE_DESTRUCTIVE_HOOK_RELPATH.split('/'));
+    let installError: string | null = null;
+    let preserved: string | null = null;
+    let backupPath: string | null = null;
+
+    // Unreadable (absent, or something that is not a file at all) is NOT a claim of ownership: it
+    // falls through to the write, whose failure the round-4 receipt below already reports.
+    let current: string | null = null;
+    try {
+      current = readFileSync(hookPath, 'utf-8');
+    } catch {
+      current = null;
+    }
+    const foreign = current !== null && !isDzManagedHookBody(current);
+
+    if (foreign && opts.force !== true) {
+      preserved =
+        'файл на этом пути не наш (нет маркера dz) — ОСТАВЛЕН нетронутым и НЕ ЗАПУСКАЛСЯ; запись в settings.json на этот путь тоже не трогаем (ни своей не добавляем, ни вашу не снимаем); заменить: dz setup --force';
+    } else {
+      try {
+        if (foreign && current !== null) {
+          // Same shape as the codex `hooks.json` backup: the original beside the original, stamped,
+          // so `--force` is recoverable rather than merely loud.
+          backupPath = `${hookPath}.bak-${new Date().toISOString().replace(/[:.]/g, '-')}`;
+          writeFileSync(backupPath, current);
+        }
+        mkdirSync(dirname(hookPath), { recursive: true });
+        writeFileSync(hookPath, generateClaudeDestructiveHook(), { mode: 0o755 });
+      } catch (err) {
+        installError = String((err as Error).message);
+      }
+    }
+    const foreignBodyKept = preserved !== null;
+
+    // The receipt SPAWNS the file, so it may only ever be taken on a body dz owns.
+    //
+    // Round 11, P1 SECURITY — correcting my own round-5 sentence, "the receipt is taken from the
+    // file that IS there". Combined with round 6, which preserves a body dz does not own, that made
+    // `dz setup` EXECUTE whatever a repository had committed at this path: clone a hostile repo,
+    // run the documented setup command, and its `.claude/hooks/destructive-guard.cjs` ran — with
+    // none of the host's hook-trust prompting in between. MEASURED: a foreign body writing a marker
+    // file had written it by the time setup returned.
+    //
+    // So a preserved foreign body is NOT probed, NOT registered, and NOT run. `--force` is consent
+    // to REPLACE it (our body is written above, before this line) — never consent to execute it.
+    // The receipt is still taken whether or not the write threw, because a failed write over an
+    // OLDER BODY OF OURS leaves something we may legitimately run.
+    const receipt: GuardInstallReceipt = foreignBodyKept
+      ? { ok: false, detail: 'проба не проводилась — запускать чужой файл не наше право' }
+      : probeInstalledGuard(hookPath);
+    // Round 8, P2: ownership of the ENTRY follows ownership of the BODY, never the filename.
+    //
+    // Round 6 preserved a consumer's hook file; attribution of its registry entry stayed path-only,
+    // so a routine run deleted the registration of the very file it had just decided not to touch —
+    // their hook left on disk and switched off (MEASURED: their `PreToolUse` entry came back `[]`).
+    // The reverse was just as wrong: a foreign body that happened to refuse made dz ADD an entry
+    // for somebody else's file (MEASURED), taking responsibility for code it may neither read as
+    // its own nor replace.
+    //
+    // So when a foreign body is kept, dz stands down from the whole event: it adds nothing, and
+    // `isManaged` below stops claiming an entry that points at that path. Whether the foreign hook
+    // refuses is not merely the consumer's business — it is a question dz no longer ASKS, because
+    // asking meant running their file (round 11). All of it is said in one line rather than left
+    // for them to find by diffing settings.json.
+    const guardArmed = receipt.ok && !foreignBodyKept;
+    // The receipt is taken from the file that IS at the path — ours, or the one we preserved. A
+    // foreign hook that demonstrably refuses is registered on its own merits; a foreign hook that
+    // does not refuse gets no entry, exactly like a failed install (round 4).
+    const notes = [
+      preserved === null ? '' : `${preserved}; `,
+      backupPath === null ? '' : `прежний файл сохранён: ${basename(backupPath)}; `,
+      installError === null ? '' : `${installError}; `,
+    ].join('');
+    steps.push(
+      guardArmed
+        ? { name: 'Install destructive guard', status: 'done', detail: `${notes}${CLAUDE_DESTRUCTIVE_HOOK_RELPATH} — ${receipt.detail}` }
+        : {
+            name: 'Install destructive guard',
+            status: preserved === null ? 'error' : 'skipped',
+            detail: `${notes}${receipt.detail} — запись в settings.json НЕ добавлена`,
+          },
+    );
     const generated = JSON.parse(generateHooksConfig(opts.projectRoot, backend)) as {
       hooks: Record<string, { hooks: { type: string; command: string; runInBackground?: boolean }[] }[]>;
     };
 
+    // No working body ⇒ no entry, and the EVENT KEY STAYS — as an empty managed list when nothing
+    // else of ours belongs there.
+    //
+    // CORRECTION OF RECORD (round 7, P1). The round-5 version DELETED the key and this comment
+    // claimed the merge would then also drop a guard entry left by an earlier setup. That was
+    // asserted without measuring and it is false: `mergeManagedHookEntries` iterates
+    // `Object.keys(managed)`, so an event absent from the managed input is copied through
+    // UNTOUCHED — a project whose guard used to be armed kept invoking it on every Bash call while
+    // the report said the entry was not added. Handing the event an EMPTY list is what makes the
+    // merge EXAMINE it: our entries are dropped by `isManaged`, the user's are preserved in order,
+    // and nothing is appended. The round-5 test passed for the wrong reason — its project had no
+    // pre-existing settings.json, so there was no stale entry for the claim to be wrong about.
+    if (!guardArmed) {
+      generated.hooks['PreToolUse'] = (generated.hooks['PreToolUse'] ?? []).filter(
+        (entry) => !entry.hooks.some((h) => isManagedClaudeDestructiveHookCommand(h.command)),
+      );
+    }
+
     if (!existsSync(settingsPath)) {
       mkdirSync(settingsDir, { recursive: true });
       writeFileSync(settingsPath, JSON.stringify({ hooks: generated.hooks }, null, 2));
@@ -625,9 +845,18 @@ export function runSetup(opts: SetupOptions): SetupResult {
     } else {
       try {
         const existing = JSON.parse(readFileSync(settingsPath, 'utf-8')) as Record<string, unknown>;
-        // ONE merge implementation, shared with the Codex target (AM-3 / G-E). The Claude path's
-        // historical SUBSTRING attribution is passed IN verbatim rather than reimplemented, so the
-        // emitted bytes, the report tail string and the no-write path all stay identical (AM-37).
+        // ONE merge implementation, shared with the Codex target (AM-3 / G-E). Claude's exact
+        // command attribution is passed in rather than reimplemented, so emitted bytes, report
+        // tail text, and the no-write path stay on the shared merge contract (AM-37).
+        const isManagedCommand = (cmd: string): boolean =>
+          cmd.includes('agentdb add') ||
+          cmd.includes('agentdb-writer.mjs') ||
+          cmd.includes('sessions.jsonl') ||
+          // Ours ONLY while the body at that path is ours (round 8, P2). Without the
+          // path clause a second `dz setup` would append a duplicate guard entry instead of
+          // replacing the first; without the ownership clause it would delete the entry a
+          // consumer wrote for their own preserved hook.
+          (!foreignBodyKept && isManagedClaudeDestructiveHookCommand(cmd));
         const plan = mergeManagedHookEntries(
           (existing['hooks'] ?? {}) as Record<string, unknown[]>,
           generated.hooks as unknown as Record<string, unknown[]>,
@@ -635,13 +864,21 @@ export function runSetup(opts: SetupOptions): SetupResult {
             // Drop dz-generated entries (any vintage, either shape) — keep the user's own hooks
             // untouched. Flat dz entries (≤0.3.43) are dropped too, migrating them to the valid
             // matcher-group shape appended below.
-            isManaged: (entry) =>
-              commandsOf(entry).some(
-                (cmd) => cmd.includes('agentdb add') || cmd.includes('agentdb-writer.mjs') || cmd.includes('sessions.jsonl'),
-              ),
+            isManaged: (entry) => commandsOf(entry).some(isManagedCommand),
             isLegacy: (entry) =>
               !Array.isArray((entry as { hooks?: unknown[] })?.hooks) ||
               commandsOf(entry).some((cmd) => cmd.includes('agentdb add')),
+            // Ownership is per HANDLER, not per matcher group. A user's handler may deliberately
+            // share the Bash group with dz's guard; replacing ours must retain their handler object
+            // and every surrounding group field byte-for-byte through JSON serialization.
+            retainForeign: (entry) => {
+              const grouped = entry as { hooks?: { command?: unknown }[] };
+              if (!Array.isArray(grouped?.hooks)) return null;
+              const kept = grouped.hooks.filter((hook) => !isManagedCommand(String(hook?.command ?? '')));
+              return kept.length === 0
+                ? null
+                : { ...(entry as Record<string, unknown>), hooks: kept };
+            },
             reportLabel: backend,
           },
         );

package/src/sign.ts

@@ -504,7 +504,24 @@ export function verifyManifest(
       continue;
     }
     if (digest !== entry.sha256) {
-      failures.push({ path: entry.path, reason: 'content does not match its signed hash' });
+      // ПРИЧИНА НАЗЫВАЕТСЯ ТОЧНО, А НЕ ОБОБЩЁННО. Для файла, который переписывает упаковщик,
+      // расхождение чаще означает НЕ подделку, а сверку двух РАЗНЫХ объектов: манифест снят с
+      // байтов упакованного пакета, а здесь читается исходный каталог. ИЗМЕРЕНО 2026-09-03: так
+      // расходятся ВСЕ 56 подписанных пакетов, ни один не проверяется — на свежеподписанном
+      // манифест хранит cd7bd97a…, а хэш байтов с диска при любой версии канонизации даёт
+      // 40d926ff…, потому что pnpm вырезает из package.json блок scripts.
+      //
+      // Вердикт НЕ меняется: расхождение остаётся расхождением и выход остаётся ненулевым.
+      // Меняется только прочтение — «подделали» против «сверяете не то». Полное лечение (два
+      // режима проверки: исходный каталог упаковывать, установленный сверять напрямую) —
+      // запись бэклога 58dc4d58, решение владельца получено, работа не сделана.
+      const packerRewritten = CANONICALISED_PACK_FILES.has(entry.path);
+      failures.push({
+        path: entry.path,
+        reason: packerRewritten
+          ? 'content does not match its signed hash — NOTE: this file is rewritten by the packer, so a mismatch here may mean the manifest was built from PACKED bytes while a SOURCE directory is being verified, not tampering (backlog 58dc4d58)'
+          : 'content does not match its signed hash',
+      });
     }
   }
 

package/src/skill-selection.ts

@@ -0,0 +1,111 @@
+/**
+ * `--select` resolution: one provider per requested skill, decided ONCE (backlog 9d15b9b6, PR-A).
+ *
+ * THE DEFECT THIS REPLACES. `installSkills` looped the installer once PER ROOT, handing each root
+ * the same select list. Asking each root independently produces two failures that look like
+ * opposites but share one cause — the REQUEST was never resolved, only re-asked:
+ *
+ *   - a skill present in two roots was installed TWICE and counted twice. The field report's
+ *     observed `2 skill(s)` was ONE skill installed twice, read by everyone as an orchestrator plus
+ *     its stage skill (features/digitize-book-codex-init-research/00_research/00-root-cause.md);
+ *   - a skill present in NO root produced a warning and exit 0. `0 skill(s)` read as success, which
+ *     is the same class as a health check reporting clean because it could not look.
+ *
+ * WHY A PURE MODULE. The decision must happen BEFORE anything is written — an exit 1 that arrives
+ * after hooks and memory are installed leaves a half-configured project, which is worse than either
+ * outcome. A pure resolver can be called at the top of the seam and interrogated without side
+ * effects; a resolver tangled with the filesystem cannot.
+ *
+ * DELIBERATELY NOT HERE: dependency closure (an orchestrator pulling its stage skills). That is
+ * PR-B. Mixing the two would put a correctness fix and a semantic change in one unreviewable
+ * change, and the exit-contract fix is what unblocks the rest.
+ */
+
+/** One skill root and the ids it offers, in the order discovery returned them. */
+export interface SkillRoot {
+  readonly dir: string;
+  readonly ids: readonly string[];
+}
+
+/** The single root chosen to provide one requested id. */
+export interface ChosenProvider {
+  readonly id: string;
+  readonly dir: string;
+}
+
+/**
+ * A requested id offered by more than one root. NOT an error: precedence resolves it. But it is
+ * NAMED, because an operator who sees one install where two roots offer the skill must be able to
+ * learn which root lost — otherwise the precedence is folklore, and the next person re-derives it.
+ */
+export interface ShadowedProvider {
+  readonly id: string;
+  readonly chosen: string;
+  readonly alsoIn: readonly string[];
+}
+
+export interface SelectResolution {
+  /** One entry per DISTINCT requested id that resolved, in request order. */
+  readonly chosen: readonly ChosenProvider[];
+  /** Requested ids no root offers. Non-empty means the caller must refuse and write nothing. */
+  readonly missing: readonly string[];
+  /** Requested ids offered by several roots, with the losers named. */
+  readonly shadowed: readonly ShadowedProvider[];
+  /** True only when EVERY requested id resolved. Shadowing does not make it false. */
+  readonly ok: boolean;
+}
+
+/**
+ * PRECEDENCE IS ROOT ORDER, and that is a promise, not an implementation detail: the first root in
+ * `roots` that offers an id provides it. Callers pass roots in discovery order, so the rule the
+ * operator can state ("the earlier root wins") is the rule that runs. The previous behaviour
+ * depended on `readdir` order inside each root and on the loop visiting roots — an order nobody
+ * documented and nobody could rely on.
+ *
+ * Asking for the same id twice is asking once: a request is a SET of skills, and duplicating a name
+ * in the argument does not duplicate an installation.
+ */
+export function resolveSelection(
+  select: readonly string[],
+  roots: readonly SkillRoot[],
+): SelectResolution {
+  const chosen: ChosenProvider[] = [];
+  const missing: string[] = [];
+  const shadowed: ShadowedProvider[] = [];
+  const seen = new Set<string>();
+
+  for (const id of select) {
+    if (seen.has(id)) continue;
+    seen.add(id);
+    const providers = roots.filter((root) => root.ids.includes(id)).map((root) => root.dir);
+    const first = providers[0];
+    if (first === undefined) {
+      missing.push(id);
+      continue;
+    }
+    chosen.push({ id, dir: first });
+    // EVERY losing root is listed, not just the second: with three providers, naming one of the two
+    // losers would send the reader to fix the wrong copy.
+    if (providers.length > 1) shadowed.push({ id, chosen: first, alsoIn: providers.slice(1) });
+  }
+
+  return { chosen, missing, shadowed, ok: missing.length === 0 };
+}
+
+/**
+ * The refusal an explicit `--select` owes its caller. Returns null when there is nothing to refuse.
+ *
+ * Shaped as text rather than an exception so the seam can print it and return a code without a
+ * try/catch that a later edit might swallow — the failure mode this whole change exists to remove
+ * is a problem that produced a warning and kept going.
+ */
+export function formatSelectRefusal(resolution: SelectResolution, roots: readonly SkillRoot[]): string | null {
+  if (resolution.ok) return null;
+  const lines = [
+    `dz: --select refused — ${resolution.missing.length} requested skill(s) exist in none of the ${roots.length} skill root(s):`,
+  ];
+  for (const id of resolution.missing) lines.push(`  missing: ${id}`);
+  for (const root of roots) lines.push(`  searched: ${root.dir} (${root.ids.length} skill(s))`);
+  lines.push('Nothing was written. Fix the id, or install the pack that provides it, then re-run.');
+  return lines.join('\n');
+}

package/src/skills-verify.ts

@@ -23,7 +23,9 @@ import { basename, isAbsolute, join, resolve } from 'node:path';
 export type SkillIssueKind =
   | 'no-skill-md'          // a skill dir with no SKILL.md at depth 1 → never registers
   | 'buried-skill-md'      // a SKILL.md at depth >= 2 → the loader does not scan that deep
-  | 'plugin-manifest-trap'; // .claude-plugin/plugin.json under .claude/skills → does NOT auto-register
+  | 'plugin-manifest-trap' // .claude-plugin/plugin.json under .claude/skills → does NOT auto-register
+  | 'wildcard-allowed-tools' // `allowed-tools: *` → every tool granted; a FINDING (see below)
+  | 'empty-allowed-tools';   // `allowed-tools:` with no value → looks restrictive, restricts nothing
 
 export interface SkillLayoutFinding {
   readonly dir: string;
@@ -170,6 +172,98 @@ export function looksLikeSkillDir(dir: string): boolean {
   return walk(dir, 1);
 }
 
+/**
+ * What a SKILL.md's front matter says about the tools it may use.
+ *
+ * Three states, and they are NOT the same thing:
+ *   `absent`   — no `allowed-tools` key. The skill honestly inherits; this is the ordinary case
+ *                (7 170 SKILL.md files in this tree, MEASURED 2026-09-03).
+ *   `empty`    — the key is present with no value. It LOOKS like a restriction and restricts
+ *                nothing. Reported, never failed: 70 files are in this state today, and a gate
+ *                that goes red on the day it is introduced gets switched off — taking the
+ *                wildcard check down with it.
+ *   `listed`   — actual values, which may include a wildcard.
+ */
+export type AllowedToolsState =
+  | { readonly state: 'absent' }
+  | { readonly state: 'empty' }
+  | { readonly state: 'listed'; readonly values: readonly string[]; readonly wildcard: boolean };
+
+/**
+ * Read `allowed-tools` from the FRONT MATTER only.
+ *
+ * Scanning the whole file would turn `allowed-tools: *` written inside a skill's own documentation
+ * into a violation — and a gate that INVENTS violations is worse than no gate: it teaches people to
+ * ignore it. So the parse stops at the closing `---`.
+ *
+ * Both YAML spellings are accepted, because both appear in this tree: an inline list
+ * (`allowed-tools: Read, Write`) and a flow sequence (`allowed-tools: [Read, Write]`). Quotes are
+ * stripped before the wildcard test — `allowed-tools: "*"` grants exactly as much as a bare one.
+ */
+export function parseAllowedTools(markdown: string): AllowedToolsState {
+  const lines = markdown.split(/\r?\n/);
+  if (lines[0]?.trim() !== '---') return { state: 'absent' };
+  let raw: string | null = null;
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i] ?? '';
+    if (line.trim() === '---') break;                       // конец заголовка
+    const m = /^allowed-tools:(.*)$/.exec(line);
+    if (m) { raw = m[1] ?? ''; break; }
+  }
+  if (raw === null) return { state: 'absent' };
+
+  // ЯВНО ПУСТОЙ МАССИВ — НЕ ТО ЖЕ, ЧТО ПУСТОЕ ПОЛЕ. `allowed-tools: []` — это утверждение
+  // («никаких инструментов»), а `allowed-tools:` — незаполненное поле, которое ВЫГЛЯДИТ
+  // ограничением и ничего не ограничивает. Свалить их в одно состояние значило бы сказать про
+  // первый случай неправду в тексте предупреждения.
+  const trimmed = raw.trim();
+  if (trimmed === '') return { state: 'empty' };
+  const bracketed = /^\[(.*)\]$/s.exec(trimmed);
+  const body = (bracketed ? bracketed[1] ?? '' : trimmed).trim();
+  if (body === '') return { state: 'listed', values: [], wildcard: false };
+
+  const values = body.split(',')
+    .map((v) => v.trim().replace(/^["']|["']$/g, '').trim())
+    .filter((v) => v !== '');
+  return { state: 'listed', values, wildcard: values.includes('*') };
+}
+
+/**
+ * Privilege findings for one skill directory.
+ *
+ * WHY THIS FAILS RATHER THAN WARNS. The advisory carve-out in this module exists for layout classes
+ * whose support this gate CANNOT observe (workspace trust). A wildcard grant is not that: the text
+ * is right there in the file, the reading is unambiguous, and nothing about the environment can make
+ * it narrow. It is also a pure regression guard — MEASURED 2026-09-03: zero wildcards exist in this
+ * tree, so introducing it breaks no one.
+ */
+function scanSkillPrivileges(
+  dir: string, label: string, findings: SkillLayoutFinding[], advisories: SkillLayoutFinding[],
+): void {
+  let text: string;
+  try {
+    text = readFileSync(join(dir, 'SKILL.md'), 'utf8');
+  } catch {
+    return;   // нечитаемый файл — забота других проверок этого же слоя, не этой
+  }
+  const tools = parseAllowedTools(text);
+  if (tools.state === 'empty') {
+    advisories.push({
+      dir: label,
+      kind: 'empty-allowed-tools',
+      detail: 'allowed-tools is present but empty — it looks like a restriction and grants everything; either list the tools or drop the key',
+    });
+    return;
+  }
+  if (tools.state === 'listed' && tools.wildcard) {
+    findings.push({
+      dir: label,
+      kind: 'wildcard-allowed-tools',
+      detail: `allowed-tools grants every tool via "*" (${tools.values.join(', ')}) — name the tools this skill actually needs`,
+    });
+  }
+}
+
 /**
  * A directory registers only if `SKILL.md` is a regular FILE. `existsSync` also answers true for a
  * DIRECTORY named SKILL.md, which registers nothing yet suppressed every other check (QE2 #4).
@@ -332,6 +426,10 @@ export function scanSkillsLayout(projectDir: string): StaticScan {
     const isPluginContainer = hasPluginManifest(dir);
     const bucket = isPluginContainer ? advisories : findings;
 
+    // Права проверяются у КАЖДОГО навыка с читаемым SKILL.md, включая одно-навыковый плагин: щедрая
+    // выдача не становится безопаснее оттого, что навык лежит в контейнере.
+    if (registers) scanSkillPrivileges(dir, name, findings, advisories);
+
     if (registers && !isPluginContainer) {
       registrable.push(name);
     } else if (registers && isPluginContainer) {