dsh-agent-plugins-market 0.7.2 → 0.8.0

package/lib/application/catalog.js

@@ -12,6 +12,7 @@
 import { qualifiedSuiteId } from '../catalog/paths.js';
 import { loadUserMcpSuite } from '../runtime/mcp-direct-config.js';
 import { loadSuiteOverrides } from '../runtime/mcp-overrides.js';
+import { loadUserHooksSuite } from '../runtime/user-hooks.js';
 import { applyLspOverrides } from '../runtime/server-config.js';
 import { buildSuiteDetail, readSkillContent } from './details.js';
 import { CatalogContext } from './catalog-context.js';
@@ -103,8 +104,14 @@ export class Catalog {
             .map(([key]) => key.slice(0, key.indexOf('/'))));
         const sources = state.sources.filter(source => enabledSources.has(source.id));
         const suites = sources.length === 0 ? [] : (await this.snapshots.build({ ...state, sources }, 'user', this.context.userRoot)).enabledSuites;
-        const direct = await loadUserMcpSuite(this.context.agentsRoot);
-        return applyLspOverrides(this.context.dataRoot, Object.keys(direct.mcp.servers).length === 0 ? suites : [...suites, direct]);
+        // The user's own Agent layout declarations ride the same mount registries
+        // as an installed suite: each direct suite joins the list only when it
+        // declares the content its surface count reports, so an absent or empty
+        // file costs no mount pass.
+        const mcp = await loadUserMcpSuite(this.context.agentsRoot);
+        const hooks = await loadUserHooksSuite(this.context.agentsRoot);
+        const direct = [...(Object.keys(mcp.mcp.servers).length === 0 ? [] : [mcp]), ...(hooks.surfaces.hooks === 0 ? [] : [hooks])];
+        return applyLspOverrides(this.context.dataRoot, direct.length === 0 ? suites : [...suites, ...direct]);
     }
     /** The full market overview from one user snapshot. */
     async overview() {

package/lib/catalog/component-files.js

@@ -1,6 +1,7 @@
 /** Resolve declared component files once; all consumers use the same contained resource paths. */
 import { readFile, readdir, realpath, stat } from 'node:fs/promises';
 import { extname, join, relative, resolve } from 'node:path';
+import { commandCallName } from '../model/command-names.js';
 import { PLUGIN_ROOT_VARIABLES } from '../model/layouts.js';
 import { isFile } from './fs-probes.js';
 import { isWithin } from './paths.js';
@@ -154,6 +155,7 @@ export async function defaultMarkdownResources(root, component) {
 export async function resourceText(resource) {
     return resource.content ?? (await readFile(resource.file, 'utf8'));
 }
+/** Registration name of a command resource; one rule governs suite, project-native, and user-panel commands. */
 export function resourceCommandName(name) {
-    return name.replaceAll('/', '-').replaceAll('\\', '-').toLowerCase();
+    return commandCallName(name);
 }

package/lib/catalog/native-project.js

@@ -47,7 +47,7 @@ export async function discoverNativeProjectSuites(projectRoot, dimension) {
             lspFiles.push('lsp.json');
         for (const path of lspFiles) {
             if (await isFile(join(projectRoot, path))) {
-                errors.push(`${path}: project LSP configuration is not mounted; the host LSP registry does not isolate projects`);
+                errors.push(`${path.replace(/\\/g, '/')}: project LSP configuration is not mounted; the host LSP registry does not isolate projects`);
             }
         }
         // Skills live in `<dir>/skills/<name>/SKILL.md` — the same shape as the

package/lib/catalog/project-config.js

@@ -47,8 +47,6 @@ export async function discoverProjectMcp(projectRoot, files, errors, format = 'm
         found = true;
         Object.assign(servers, table);
     }
-    if (format === 'zcode' && Object.keys(servers).length === 0)
-        return discoverProjectMcp(projectRoot, ['.agents/mcp.json'], errors);
     if (!found)
         return undefined;
     for (const [key, server] of Object.entries(servers)) {

package/lib/catalog/project-hooks.js

@@ -16,9 +16,10 @@ function declarationText(value) {
  * a standalone hook file may carry the bare event table instead of a `hooks`
  * key. A recognized top-level event name is the marker — a document with no
  * event name at the top stays verbatim, so an ordinary settings file missing
- * `hooks` is still not accepted as a bare event table.
+ * `hooks` is still not accepted as a bare event table. Exported because the
+ * user Agent layout root reads the same standalone file shapes.
  */
-function settingsDocument(settings, format) {
+export function standaloneHookDocument(settings, format = 'claude') {
     if (format !== 'claude' || settings.hooks !== undefined)
         return settings;
     const isEventTable = Object.keys(settings).some(key => EVENTS.has(key));
@@ -32,11 +33,15 @@ export async function discoverProjectHooks(projectRoot, files, errors, format =
         if (settings === null)
             return undefined;
         if (settings !== undefined)
-            documents.push({ file, settings: settingsDocument(settings, format) });
+            documents.push({ file, settings: standaloneHookDocument(settings, format) });
     }
     return normalizeHookDocuments(projectRoot, documents, errors, format);
 }
-/** Pure validation shared by native settings and plugin file/inline declarations. */
+/**
+ * Pure validation shared by native settings and plugin file/inline
+ * declarations. `projectRoot` is absent for hooks declared in the user Agent
+ * layout root, which belong to no project.
+ */
 export function normalizeHookDocuments(projectRoot, documents, errors, format = 'claude') {
     const events = Object.create(null);
     const seen = new Set();
@@ -64,7 +69,7 @@ export function normalizeHookDocuments(projectRoot, documents, errors, format =
         }
         for (const [event, groups] of Object.entries(eventTable)) {
             if (!EVENTS.has(event)) {
-                errors.push(`${file}: unsupported project hook event ${event}`);
+                errors.push(`${file}: unsupported hook event ${event}`);
                 continue;
             }
             if (!Array.isArray(groups)) {
@@ -105,7 +110,7 @@ export function normalizeHookDocuments(projectRoot, documents, errors, format =
                         return undefined;
                     }
                     if (hook.async === true || hook.asyncRewake === true) {
-                        errors.push(`${file}: asynchronous project hooks are unsupported`);
+                        errors.push(`${file}: asynchronous hooks are unsupported`);
                         continue;
                     }
                     const key = JSON.stringify([event, matcher, hook.command]);
@@ -125,5 +130,5 @@ export function normalizeHookDocuments(projectRoot, documents, errors, format =
             }
         }
     }
-    return !disabled && Object.keys(events).length > 0 ? { projectRoot, events } : undefined;
+    return !disabled && Object.keys(events).length > 0 ? { ...(projectRoot === undefined ? {} : { projectRoot }), events } : undefined;
 }

package/lib/catalog/surfaces.js

@@ -4,7 +4,8 @@
  *
  * Skills honor any path the winning manifest declares (`skills` may be a
  * string, an array, or absent), scan up to three levels of nesting, and
- * dedupe by frontmatter name. MCP reads both `mcp.json` and the dot-prefixed
+ * dedupe by frontmatter name. A path carrying its own `SKILL.md` is one skill
+ * and nothing else inside it is read. MCP reads both `mcp.json` and the dot-prefixed
  * `.mcp.json`, tolerating unknown transports per server. Every read is
  * fail-closed: broken files produce a diagnostic and are skipped, never a
  * thrown discovery.
@@ -40,10 +41,12 @@ async function declaredSkillDirs(root, declared, errors) {
 }
 /**
  * Discover SKILL.md files under the suite's skills directory, up to 3 levels
- * deep. Portable v1 suites (§7.1) instead discover exactly one level of
- * `skills/` subdirectories each carrying a `SKILL.md` — the spec forbids
- * recursive deeper search and root-level or flat skill files are outside the
- * portable discovery shape.
+ * deep. A path that carries `SKILL.md` is one skill directory — a manifest may
+ * list those individually — and only that document is read from it. Portable
+ * v1 suites (§7.1) instead discover exactly one level of `skills/`
+ * subdirectories each carrying a `SKILL.md` — the spec forbids recursive
+ * deeper search and root-level or flat skill files are outside the portable
+ * discovery shape.
  */
 export async function discoverSkills(root, errors, declared, portable = false) {
     const skills = [];
@@ -96,16 +99,20 @@ export async function discoverSkills(root, errors, declared, portable = false) {
             pushUnique(await parseOneSkill(skillsDir, dirname(skillsDir), '', errors));
             continue;
         }
-        for (const name of await listMdFiles(skillsDir)) {
-            pushUnique(await parseOneSkill(join(skillsDir, name), skillsDir, name.replace(/\.md$/, ''), errors));
-        }
-        // A declared path may be one skill directory (a manifest listing
-        // individual skills, e.g. mattpocock) or a container of skills.
+        // A directory carrying its own `SKILL.md` is one skill, whether a manifest
+        // declared it individually (mattpocock lists every skill directory) or the
+        // conventional container happens to be one. Everything beside that
+        // `SKILL.md` — `references/`, `scripts/`, the notes and formats a skill
+        // attaches — belongs to it, so those documents are neither parsed as flat
+        // skills nor reported as malformed ones.
         if (await isFile(join(skillsDir, 'SKILL.md'))) {
             const name = skillsDir.split(/[\\/]/).at(-1) ?? '';
             pushUnique(await parseOneSkill(join(skillsDir, 'SKILL.md'), skillsDir, name, errors));
             continue;
         }
+        for (const name of await listMdFiles(skillsDir)) {
+            pushUnique(await parseOneSkill(join(skillsDir, name), skillsDir, name.replace(/\.md$/, ''), errors));
+        }
         for (const child of await listChildDirs(skillsDir)) {
             const name = child.split(/[\\/]/).at(-1) ?? '';
             pushUnique(await parseOneSkill(join(child, 'SKILL.md'), child, name, errors));

package/lib/model/command-names.js

@@ -0,0 +1,14 @@
+/**
+ * The call name a command resource registers under.
+ *
+ * A command resource may live at any depth under its `commands/` directory,
+ * but the host's slash-command grammar accepts single-segment names only, so
+ * registration flattens the path separators: `git/commit` registers as
+ * `git-commit`. The user panel renders the same call name, so a card never
+ * advertises a slash name the host cannot accept.
+ * @module model/command-names
+ */
+/** Flatten a resource path into the single-segment name a slash command registers under. */
+export function commandCallName(name) {
+    return name.replaceAll('/', '-').replaceAll('\\', '-').toLowerCase();
+}

package/lib/model/layouts.js

@@ -47,6 +47,7 @@ export const PROJECT_LAYOUTS = [
         dirName: '.agents',
         label: 'agents',
         subdirs: ['skills', 'agents', 'commands'],
+        mcpFiles: ['.agents/mcp.json'],
         hookFiles: ['.agents/hooks/hooks.json', '.agents/hooks.json']
     },
     { dirName: '.codex', label: 'Codex', subdirs: ['skills'], mcpFiles: ['.codex/config.toml'], mcpFormat: 'codex' },

package/lib/runtime/commands-mounts.js

@@ -7,6 +7,7 @@ import { expandPluginPaths, pluginRootOf } from '../catalog/plugin-variables.js'
 import { defaultMarkdownResources, resourceText, resourceCommandName } from '../catalog/component-files.js';
 import { bindHostLocale } from './host-locale.js';
 import { injectDynamicContext, shellSeamOf } from './dynamic-context.js';
+import { pluginMarketSource } from './plugin-message-source.js';
 const COMMAND_NAME = /^[a-z][a-z0-9_-]*$/;
 export class CommandMountRegistry {
     ctx;
@@ -89,7 +90,7 @@ export class CommandMountRegistry {
                         if (shell === undefined) {
                             agent.followup(createUserMessage({
                                 content: [{ type: 'text', text: body }],
-                                source: { kind: 'plugin', plugin: 'dsh-agent-plugins-market' }
+                                source: pluginMarketSource()
                             }));
                             return { kind: 'success', text: this.t('commandAcknowledged', { command: spec.name }) };
                         }
@@ -102,7 +103,7 @@ export class CommandMountRegistry {
                         }
                         agent.followup(createUserMessage({
                             content: [{ type: 'text', text }],
-                            source: { kind: 'plugin', plugin: 'dsh-agent-plugins-market' }
+                            source: pluginMarketSource()
                         }));
                         return { kind: 'success', text: this.t('commandAcknowledged', { command: spec.name }) };
                     }

package/lib/runtime/hooks-mounts.js

@@ -6,9 +6,12 @@
  *
  * The bridge is a cordis function plugin (`inject: ['shell']`) whose config
  * is a single `configPath` plus `pluginRoot` for `${CLAUDE_PLUGIN_ROOT}`
- * substitution — exactly the shape a suite hook file needs. Mounts reconcile
- * on every enable/disable/install/uninstall; a missing bridge package, a
- * broken hook file, or a mount failure is contained per suite.
+ * substitution — exactly the shape a suite hook file needs. `projectDir` is
+ * forwarded only for hooks declared by a project layout; user Agent layout
+ * hooks carry none, so the bridge defaults `${CLAUDE_PROJECT_DIR}` to the
+ * calling session's workspace. Mounts reconcile on every
+ * enable/disable/install/uninstall; a missing bridge package, a broken hook
+ * file, or a mount failure is contained per suite.
  */
 import { mkdtemp, readFile, rm, stat } from 'node:fs/promises';
 import { writeFileAtomic } from '@deepseek-ai/dsh-atomic-write';
@@ -96,7 +99,7 @@ export class HooksMountRegistry {
             handle = mountCtx.plugin(bridge, {
                 configPath,
                 pluginRoot: suite.root,
-                ...(suite.hooks === undefined ? {} : { projectDir: suite.hooks.projectRoot })
+                ...(suite.hooks?.projectRoot === undefined ? {} : { projectDir: suite.hooks.projectRoot })
             });
             await handle.await();
             this.live.set(key, handle);

package/lib/runtime/mcp-direct-config.js

@@ -6,11 +6,7 @@ import { effectiveSurfaces } from '../model/types.js';
 export const USER_MCP_SOURCE = '@user-mcp';
 export const USER_MCP_SUITE = 'user-mcp';
 /**
- * User-created services reuse the owned bridge lifecycle without changing host configuration.
- *
- * The declarations live in the shared Agent layout root
- * (`~/.agents/mcp.json`), so a service the user adds by hand is ordinary
- * `mcpServers` JSON in the same place other Agent tools look.
+ * Load the user's own MCP declaration file.
  *
  * The suite always carries an `mcp` document — an absent or malformed
  * `mcp.json` leaves an empty one — so callers read `.mcp.servers` directly
@@ -37,9 +33,10 @@ export async function loadUserMcpSuite(agentsRoot) {
         surfaces: { skills: 0, mcp: Object.keys(mcp.servers).length, commands: 0, agents: 0, hooks: 0, lsp: 0 },
         dimension: 'user',
         enabled: true,
-        // A user-created suite has no install entry and no overrides, so every
-        // surface keeps its enabled default.
-        activeSurfaces: effectiveSurfaces(undefined),
+        // The suite declares MCP only: the other surfaces would otherwise make the
+        // command registry read this root a second time beside the user-command
+        // panel registry.
+        activeSurfaces: effectiveSurfaces({ skills: false, hooks: false, commands: false, agents: false, lsp: false }),
         installedAt: 'user',
         errors
     };
@@ -49,13 +46,25 @@ export async function loadUserMcpSuite(agentsRoot) {
  * keys this client does not know ride along untouched rather than failing the
  * whole file, and the closed-set rule the package schema applies to suites
  * does not apply here.
+ *
+ * A hand-written file may omit `$schema` entirely, so the baseline identifier
+ * is filled in before validation: the document then reads as the baseline
+ * release while every shape and required field the client does know is still
+ * validated. A rejected document keeps the file's own declarations out of the
+ * mount and reports the reason, the same fail-closed rule the write paths
+ * apply.
  */
 async function validateUserMcp(agentsRoot, raw) {
-    const result = await validateMcpJson(agentsRoot, raw, { packageRules: false });
+    const document = isRecord(raw) && raw['$schema'] === undefined ? { ...raw, $schema: MCP_SCHEMA_ID } : raw;
+    const result = await validateMcpJson(agentsRoot, document, { packageRules: false });
     if (result.config === undefined || result.errors.length > 0)
         throw new Error(`invalid MCP configuration: ${result.errors.join('; ')}`);
     return result.config;
 }
+/** Whether a parsed user document is the JSON object the MCP validator reads. */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 /** Add one service atomically; reject collisions and malformed config before writing. */
 export async function addUserMcpServer(agentsRoot, name, server) {
     if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(name))

package/lib/runtime/plugin-message-source.js

@@ -0,0 +1,4 @@
+/** Build the source for one follow-up message; fresh per message, no shared state. */
+export function pluginMarketSource() {
+    return { kind: 'plugin-market', form: 'instructions' };
+}

package/lib/runtime/project-runtime.js

@@ -125,16 +125,19 @@ function mountProjectSurface(ctx, catalog, service, create, withoutProject = fal
         mounts.delete(agent);
         await mount?.fiber.dispose();
     };
-    const unwatchCreated = ctx.on('agent/created', ({ agent }) => attach(agent));
-    const unwatchDisposed = ctx.on('agent/disposed', ({ agent }) => {
-        void detach(agent).catch(warn);
-    });
-    const unwatchStart = ctx.on('agent/session-start', ({ agent }) => {
-        attach(agent);
+    // One lifecycle listener covers every startup path: the host merged the old
+    // agent/session-start emit into agent/created (which now carries the
+    // startup/resume/clear/compact source) and fires it serially.
+    const unwatchCreated = ctx.on('agent/created', ({ agent }) => {
+        const projectAgent = agent;
+        attach(projectAgent);
         // The refresh chain can reject — its queue body re-reads the project
         // catalog — and the host emits this event without awaiting the listener,
         // so an unhandled rejection here would surface at every session start.
-        void mounts.get(agent)?.refresh().catch(warn);
+        void mounts.get(projectAgent)?.refresh().catch(warn);
+    });
+    const unwatchDisposed = ctx.on('agent/disposed', ({ agent }) => {
+        void detach(agent).catch(warn);
     });
     for (const agent of host.agents.list())
         attach(agent);
@@ -146,7 +149,6 @@ function mountProjectSurface(ctx, catalog, service, create, withoutProject = fal
             disposed = true;
             unwatchCreated();
             unwatchDisposed();
-            unwatchStart();
             await Promise.all([...mounts.keys()].map(detach));
         }
     };

package/lib/runtime/user-commands.js

@@ -2,12 +2,17 @@
  * User command mounting: every enabled entry of the user commands panel
  * registers as a dsh slash command, so user-authored quick replies behave
  * exactly like suite commands — the body with `$ARGUMENTS` substituted rides
- * one follow-up message on the receiving agent. Reconciled on every catalog
- * change, keyed `user/<name>`.
+ * one follow-up message on the receiving agent. A nested entry registers
+ * under its flattened call name (`git/commit` → `git-commit`) while the panel
+ * keeps addressing it by path; when two entries flatten to one call name the
+ * first registers and the other is reported. Reconciled on every catalog
+ * change, keyed by the call name.
  * @module runtime/user-commands
  */
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
-import { USER_ENTRY_NAME } from './user-store.js';
+import { commandCallName } from '../model/command-names.js';
+import { USER_ENTRY_PATH } from './user-store.js';
+import { pluginMarketSource } from './plugin-message-source.js';
 /** Register/unregister user-panel commands to match the panel's enabled entries. */
 export class UserCommandMountRegistry {
     ctx;
@@ -25,14 +30,24 @@ export class UserCommandMountRegistry {
         const diagnostics = [];
         const entries = await this.store.list();
         const wanted = new Map();
+        // Registration is keyed by call name, so two entries that flatten to the
+        // same one cannot silently shadow each other.
+        const owners = new Map();
         for (const entry of entries) {
             if (entry.disabled)
                 continue;
-            if (!USER_ENTRY_NAME.test(entry.name))
+            if (!USER_ENTRY_PATH.test(entry.name))
                 continue;
-            wanted.set(entry.name, {
-                name: entry.name,
-                description: entry.description === '' ? `[${this.t('userCommandSourceLabel')}] ${entry.name}` : `[${this.t('userCommandSourceLabel')}] ${entry.description}`,
+            const callName = commandCallName(entry.name);
+            const owner = owners.get(callName);
+            if (owner !== undefined) {
+                diagnostics.push(`command "${callName}": "${entry.name}" is shadowed by "${owner}" — both flatten to the same call name`);
+                continue;
+            }
+            owners.set(callName, entry.name);
+            wanted.set(callName, {
+                name: callName,
+                description: entry.description === '' ? `[${this.t('userCommandSourceLabel')}] ${callName}` : `[${this.t('userCommandSourceLabel')}] ${entry.description}`,
                 ...(typeof entry.metadata['argument-hint'] === 'string' && entry.metadata['argument-hint'] !== '' ? { hint: entry.metadata['argument-hint'] } : {}),
                 body: entry.content
             });
@@ -66,7 +81,7 @@ export class UserCommandMountRegistry {
                         const text = spec.body.replaceAll('$ARGUMENTS', invocation.rawInput.trim());
                         agent.followup(createUserMessage({
                             content: [{ type: 'text', text }],
-                            source: { kind: 'plugin', plugin: 'dsh-agent-plugins-market' }
+                            source: pluginMarketSource()
                         }));
                         return { kind: 'success', text: this.t('commandAcknowledged', { command: spec.name }) };
                     }

package/lib/runtime/user-hooks.js

@@ -0,0 +1,102 @@
+/**
+ * Direct user configuration for command hooks: the Agent layout root's own
+ * hook files, mounted through the same bridge lifecycle a suite's hooks use.
+ *
+ * The files live at `~/.agents/hooks/hooks.json` and `~/.agents/hooks.json`
+ * and are read in that order, merged additively exactly like the project
+ * `.agents` layout reads them. A malformed file fails the suite closed with a
+ * diagnostic, never a thrown discovery, and the hooks carry no
+ * `projectRoot`: the bridge defaults `${CLAUDE_PROJECT_DIR}` to the calling
+ * session's workspace.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { normalizeHookDocuments, standaloneHookDocument } from '../catalog/project-hooks.js';
+import { effectiveSurfaces } from '../model/types.js';
+export const USER_HOOKS_SOURCE = '@user-hooks';
+export const USER_HOOKS_SUITE = 'user-hooks';
+/**
+ * The Agent layout root's hook documents, relative to that root and read in
+ * order. Later files merge additively over earlier ones, the same order and
+ * semantics the project `.agents` layout applies. The first entry is also the
+ * suite's manifest path and the file a suite with no documents is addressed by.
+ */
+export const USER_HOOK_FILES = [join('hooks', 'hooks.json'), 'hooks.json'];
+/** Resolve one Agent-layout-relative hook document against the layout root. */
+export function userHookPath(agentsRoot, file) {
+    return join(agentsRoot, file);
+}
+/**
+ * Load the user's Agent layout hooks as one synthetic suite.
+ *
+ * The suite is always built, so one call answers with both the events and the
+ * reasons a document was rejected: an absent, malformed, or event-free set of
+ * hook files leaves `surfaces.hooks` at 0 and carries the diagnostics.
+ * {@link ../application/catalog.ts} merges the suite into the enabled set only
+ * when it declares events.
+ */
+export async function loadUserHooksSuite(agentsRoot) {
+    const errors = [];
+    const documents = [];
+    for (const file of USER_HOOK_FILES) {
+        const settings = await readHookDocument(agentsRoot, file, errors);
+        // A malformed file fails the whole set closed, the same way one malformed
+        // project hook layer drops every hook the layout declared.
+        if (settings === null)
+            return userHooksSuite(agentsRoot, undefined, errors);
+        // A standalone hook file may carry the bare event table; the shared rule
+        // that recognizes it is the same one the project `.agents` layout applies.
+        if (settings !== undefined)
+            documents.push({ file, settings: standaloneHookDocument(settings) });
+    }
+    return userHooksSuite(agentsRoot, normalizeHookDocuments(undefined, documents, errors), errors);
+}
+/** One synthetic suite for the Agent layout root's hook files. */
+function userHooksSuite(agentsRoot, hooks, errors) {
+    return {
+        sourceId: USER_HOOKS_SOURCE,
+        id: USER_HOOKS_SUITE,
+        root: agentsRoot,
+        manifest: { layout: 'agent-plugin-v1', path: userHookPath(agentsRoot, USER_HOOK_FILES[0]), id: USER_HOOKS_SUITE, name: USER_HOOKS_SUITE },
+        skills: [],
+        ...(hooks === undefined ? {} : { hooks }),
+        surfaces: { skills: 0, mcp: 0, hooks: hookCount(hooks), commands: 0, agents: 0, lsp: 0 },
+        dimension: 'user',
+        enabled: true,
+        // The suite declares hooks only; the other surfaces would otherwise make
+        // the command and LSP registries read this root a second time.
+        activeSurfaces: effectiveSurfaces({ skills: false, mcp: false, commands: false, agents: false, lsp: false }),
+        installedAt: 'user',
+        errors
+    };
+}
+/** One hook file's parsed document: absent is undefined, malformed is null plus a diagnostic. */
+async function readHookDocument(agentsRoot, file, errors) {
+    let text;
+    try {
+        text = await readFile(userHookPath(agentsRoot, file), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        errors.push(`${file}: hook file is unreadable`);
+        return null;
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        errors.push(`${file}: hook file is invalid JSON`);
+        return null;
+    }
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        errors.push(`${file}: hook file must be an object`);
+        return null;
+    }
+    return raw;
+}
+/** Declared hook commands, the same count a native suite reports for `surfaces.hooks`. */
+function hookCount(hooks) {
+    return Object.values(hooks?.events ?? {}).reduce((total, groups) => total + groups.reduce((count, group) => count + group.hooks.length, 0), 0);
+}