@hasna/hooks 0.3.11 → 0.4.1

package/bin/index.js

@@ -5346,41 +5346,83 @@ function formatInstallResults(results, extra) {
     }]
   };
 }
+function truncateText(value, max = 160) {
+  const text = String(value ?? "").replace(/\s+/g, " ").trim();
+  if (text.length <= max)
+    return text;
+  return `${text.slice(0, Math.max(0, max - 3))}...`;
+}
+function boundedLimit(value, fallback, max) {
+  if (!Number.isFinite(value) || !value || value <= 0)
+    return fallback;
+  return Math.min(Math.floor(value), max);
+}
+function compactHook(hook) {
+  return {
+    name: hook.name,
+    event: hook.event,
+    matcher: hook.matcher,
+    category: hook.category
+  };
+}
+function compactHookResult(hooks, limit, detail) {
+  const visible = hooks.slice(0, limit).map(compactHook);
+  const omitted = Math.max(0, hooks.length - visible.length);
+  return {
+    hooks: visible,
+    count: visible.length,
+    total: hooks.length,
+    omitted,
+    hint: omitted > 0 ? `Use limit, compact:false, or ${detail} for more detail.` : `Use compact:false or ${detail} for full details.`
+  };
+}
+function compactEvent(row) {
+  return {
+    id: row.id,
+    timestamp: row.timestamp,
+    hook_name: row.hook_name,
+    tool_name: row.tool_name ?? undefined,
+    session_id: row.session_id ? String(row.session_id).slice(0, 12) : undefined,
+    error: row.error ? truncateText(row.error, 180) : undefined,
+    tool_input_preview: row.tool_input ? truncateText(row.tool_input, 180) : undefined
+  };
+}
 function createHooksServer() {
   const server = new McpServer({
     name: "@hasna/hooks",
     version: pkg.version
   });
-  server.tool("hooks_list", "List all available hooks, optionally filtered by category. Use compact:true to get minimal output (name+event+matcher only) \u2014 saves tokens.", {
+  const defineTool = (name, description, schema, handler) => server.tool(name, description, schema, handler);
+  defineTool("hooks_list", "List available hooks. Compact by default; pass compact:false for full HookMeta objects.", {
     category: z.string().optional().describe("Filter by category name (e.g. 'Git Safety', 'Code Quality', 'Security')"),
-    compact: z.boolean().default(false).describe("Return minimal fields only: name, event, matcher. Reduces token usage.")
-  }, async ({ category, compact }) => {
-    const slim = (hooks) => compact ? hooks.map((h) => ({ name: h.name, event: h.event, matcher: h.matcher })) : hooks;
+    compact: z.boolean().default(true).describe("Return compact summaries by default. Set false for full fields."),
+    limit: z.number().default(25).describe("Max compact rows to return")
+  }, async ({ category, compact, limit }) => {
+    const maxRows = boundedLimit(limit, 25, 100);
     if (category) {
       const cat = CATEGORIES.find((c) => c.toLowerCase() === category.toLowerCase());
       if (!cat) {
         return { content: [{ type: "text", text: JSON.stringify({ error: `Unknown category: ${category}`, available: [...CATEGORIES] }) }] };
       }
-      return { content: [{ type: "text", text: JSON.stringify(slim(getHooksByCategory(cat))) }] };
-    }
-    if (compact) {
-      return { content: [{ type: "text", text: JSON.stringify(slim(HOOKS)) }] };
+      const hooks = getHooksByCategory(cat);
+      return { content: [{ type: "text", text: JSON.stringify(compact ? compactHookResult(hooks, maxRows, "hooks_info") : hooks) }] };
     }
     const result = {};
     for (const cat of CATEGORIES) {
       result[cat] = getHooksByCategory(cat);
     }
-    return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    return { content: [{ type: "text", text: JSON.stringify(compact ? compactHookResult(HOOKS, maxRows, "hooks_info") : result) }] };
   });
-  server.tool("hooks_search", "Search for hooks by name, description, or tags. Use compact:true for minimal output to save tokens.", {
+  defineTool("hooks_search", "Search hooks. Compact by default; pass compact:false for full HookMeta objects.", {
     query: z.string().describe("Search query"),
-    compact: z.boolean().default(false).describe("Return minimal fields only: name, event, matcher.")
-  }, async ({ query, compact }) => {
+    compact: z.boolean().default(true).describe("Return compact summaries by default. Set false for full fields."),
+    limit: z.number().default(10).describe("Max compact rows to return")
+  }, async ({ query, compact, limit }) => {
     const results = searchHooks(query);
-    const out = compact ? results.map((h) => ({ name: h.name, event: h.event, matcher: h.matcher })) : results;
+    const out = compact ? compactHookResult(results, boundedLimit(limit, 10, 100), "hooks_info") : results;
     return { content: [{ type: "text", text: JSON.stringify(out) }] };
   });
-  server.tool("hooks_info", "Get detailed information about a specific hook including install status", { name: z.string().describe("Hook name (e.g. 'gitguard', 'checkpoint')") }, async ({ name }) => {
+  defineTool("hooks_info", "Get detailed information about a specific hook including install status", { name: z.string().describe("Hook name (e.g. 'gitguard', 'checkpoint')") }, async ({ name }) => {
     const meta = getHook(name);
     if (!meta) {
       return { content: [{ type: "text", text: JSON.stringify({ error: `Hook '${name}' not found` }) }] };
@@ -5389,7 +5431,7 @@ function createHooksServer() {
     const projectInstalled = getRegisteredHooks("project").includes(meta.name);
     return { content: [{ type: "text", text: JSON.stringify({ ...meta, global: globalInstalled, project: projectInstalled }) }] };
   });
-  server.tool("hooks_install", "Install one or more hooks by registering them in agent settings", {
+  defineTool("hooks_install", "Install one or more hooks by registering them in agent settings", {
     hooks: z.array(z.string()).describe("Hook names to install"),
     scope: z.enum(["global", "project"]).default("global").describe("Install scope"),
     overwrite: z.boolean().default(false).describe("Overwrite if already installed"),
@@ -5398,7 +5440,7 @@ function createHooksServer() {
     const results = hooks.map((name) => installHook(name, { scope, overwrite, profile }));
     return formatInstallResults(results, { scope, profile });
   });
-  server.tool("hooks_install_category", "Install all hooks in a category", {
+  defineTool("hooks_install_category", "Install all hooks in a category", {
     category: z.string().describe("Category name"),
     scope: z.enum(["global", "project"]).default("global").describe("Install scope"),
     overwrite: z.boolean().default(false).describe("Overwrite if already installed")
@@ -5411,21 +5453,21 @@ function createHooksServer() {
     const results = hooks.map((name) => installHook(name, { scope, overwrite }));
     return formatInstallResults(results, { category: cat, scope });
   });
-  server.tool("hooks_install_all", "Install all available hooks", {
+  defineTool("hooks_install_all", "Install all available hooks", {
     scope: z.enum(["global", "project"]).default("global").describe("Install scope"),
     overwrite: z.boolean().default(false).describe("Overwrite if already installed")
   }, async ({ scope, overwrite }) => {
     const results = HOOKS.map((h) => installHook(h.name, { scope, overwrite }));
     return formatInstallResults(results, { scope });
   });
-  server.tool("hooks_remove", "Remove (unregister) a hook from agent settings", {
+  defineTool("hooks_remove", "Remove (unregister) a hook from agent settings", {
     name: z.string().describe("Hook name to remove"),
     scope: z.enum(["global", "project"]).default("global").describe("Scope to remove from")
   }, async ({ name, scope }) => {
     const removed = removeHook(name, scope);
     return { content: [{ type: "text", text: JSON.stringify({ hook: name, removed, scope }) }] };
   });
-  server.tool("hooks_doctor", "Check health of installed hooks \u2014 verifies hook source exists, settings are correct", {
+  defineTool("hooks_doctor", "Check health of installed hooks \u2014 verifies hook source exists, settings are correct", {
     scope: z.enum(["global", "project"]).default("global").describe("Scope to check")
   }, async ({ scope }) => {
     const settingsPath = getSettingsPath(scope);
@@ -5467,14 +5509,17 @@ function createHooksServer() {
     }
     return { content: [{ type: "text", text: JSON.stringify({ healthy: issues.length === 0, healthy_hooks: healthy, issues, registered, scope }) }] };
   });
-  server.tool("hooks_categories", "List all hook categories with counts", {}, async () => {
+  defineTool("hooks_categories", "List all hook categories with counts", {}, async () => {
     const result = CATEGORIES.map((cat) => ({
       name: cat,
       count: getHooksByCategory(cat).length
     }));
     return { content: [{ type: "text", text: JSON.stringify(result) }] };
   });
-  server.tool("hooks_docs", "Get documentation \u2014 general overview or README for a specific hook", { name: z.string().optional().describe("Hook name for specific docs, omit for general docs") }, async ({ name }) => {
+  defineTool("hooks_docs", "Get documentation. Hook README content is summarized by default; pass verbose:true for the full README.", {
+    name: z.string().optional().describe("Hook name for specific docs, omit for general docs"),
+    verbose: z.boolean().default(false).describe("Return full hook README when true")
+  }, async ({ name, verbose }) => {
     if (name) {
       const meta = getHook(name);
       if (!meta) {
@@ -5486,7 +5531,24 @@ function createHooksServer() {
       if (existsSync6(readmePath)) {
         readme = readFileSync4(readmePath, "utf-8");
       }
-      return { content: [{ type: "text", text: JSON.stringify({ ...meta, readme }) }] };
+      if (verbose) {
+        return { content: [{ type: "text", text: JSON.stringify({ ...meta, readme }) }] };
+      }
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            ...compactHook(meta),
+            displayName: meta.displayName,
+            version: meta.version,
+            description: truncateText(meta.description, 220),
+            readme_preview: truncateText(readme, 500),
+            readme_lines: readme ? readme.split(`
+`).length : 0,
+            hint: "Call hooks_docs with verbose:true for the full README or hooks_info for metadata."
+          })
+        }]
+      };
     }
     return {
       content: [{
@@ -5514,17 +5576,39 @@ function createHooksServer() {
       }]
     };
   });
-  server.tool("hooks_registered", "Get list of currently registered hooks for a scope", {
-    scope: z.enum(["global", "project"]).default("global").describe("Scope to check")
-  }, async ({ scope }) => {
+  defineTool("hooks_registered", "Get currently registered hooks for a scope. Compact by default.", {
+    scope: z.enum(["global", "project"]).default("global").describe("Scope to check"),
+    compact: z.boolean().default(true).describe("Return compact summaries by default. Set false for descriptions."),
+    limit: z.number().default(25).describe("Max compact rows to return")
+  }, async ({ scope, compact, limit }) => {
     const registered = getRegisteredHooks(scope);
     const result = registered.map((name) => {
       const meta = getHook(name);
       return { name, event: meta?.event, matcher: meta?.matcher ?? "", version: meta?.version, description: meta?.description };
     });
-    return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    if (!compact)
+      return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    const maxRows = boundedLimit(limit, 25, 100);
+    const visible = result.slice(0, maxRows).map((hook) => ({
+      name: hook.name,
+      event: hook.event,
+      matcher: hook.matcher,
+      version: hook.version
+    }));
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          hooks: visible,
+          count: visible.length,
+          total: result.length,
+          omitted: Math.max(0, result.length - visible.length),
+          hint: "Use compact:false for descriptions or hooks_info for one hook."
+        })
+      }]
+    };
   });
-  server.tool("hooks_run", "Execute a hook programmatically with the given input and return its output", {
+  defineTool("hooks_run", "Execute a hook programmatically with the given input and return its output", {
     name: z.string().describe("Hook name (e.g. 'gitguard', 'checkpoint')"),
     input: z.record(z.string(), z.unknown()).default(() => ({})).describe("Hook input as JSON object (HookInput)"),
     profile: z.string().optional().describe("Agent profile ID to inject into hook input"),
@@ -5588,7 +5672,7 @@ function createHooksServer() {
       }]
     };
   });
-  server.tool("hooks_update", "Re-register installed hooks to pick up new package version (reinstalls with overwrite)", {
+  defineTool("hooks_update", "Re-register installed hooks to pick up new package version (reinstalls with overwrite)", {
     hooks: z.array(z.string()).optional().describe("Hook names to update (omit to update all installed hooks)"),
     scope: z.enum(["global", "project"]).default("global").describe("Scope to update")
   }, async ({ hooks, scope }) => {
@@ -5607,10 +5691,11 @@ function createHooksServer() {
     const failed = results.filter((r) => !r.success).map((r) => ({ hook: r.hook, error: r.error }));
     return { content: [{ type: "text", text: JSON.stringify({ updated, failed, total: results.length }) }] };
   });
-  server.tool("hooks_context", "Get full agent context in one call: installed hooks (with event+matcher), active profile, settings path, and doctor status. Call this once at session start instead of making 4 separate calls.", {
+  defineTool("hooks_context", "Get compact agent context in one call: installed hooks, active profile summary, settings path, and doctor status.", {
     scope: z.enum(["global", "project"]).default("global").describe("Scope to inspect"),
-    profile: z.string().optional().describe("Agent profile ID to include in context")
-  }, async ({ scope, profile }) => {
+    profile: z.string().optional().describe("Agent profile ID to include in context"),
+    verbose: z.boolean().default(false).describe("Include full profile preferences/details when true")
+  }, async ({ scope, profile, verbose }) => {
     const settingsPath = getSettingsPath(scope);
     const registered = getRegisteredHooks(scope);
     const hooks = registered.map((name) => {
@@ -5636,11 +5721,13 @@ function createHooksServer() {
     };
     if (profile) {
       const p = getProfile(profile);
-      ctx.profile = p ?? null;
+      ctx.profile = p && !verbose ? { agent_id: p.agent_id, agent_type: p.agent_type, name: p.name } : p ?? null;
+      if (p && !verbose)
+        ctx.profile_hint = "Use verbose:true for profile preferences.";
     }
     return { content: [{ type: "text", text: JSON.stringify(ctx) }] };
   });
-  server.tool("hooks_preview", "Simulate which installed PreToolUse hooks would fire for a given tool call and what decision each returns. Use this to understand your hook environment before taking an action.", {
+  defineTool("hooks_preview", "Simulate which installed PreToolUse hooks would fire for a given tool call and what decision each returns. Use this to understand your hook environment before taking an action.", {
     tool_name: z.string().describe("Tool name to simulate (e.g. 'Bash', 'Write', 'Edit')"),
     tool_input: z.record(z.string(), z.unknown()).default(() => ({})).describe("Tool input to pass to matching hooks"),
     scope: z.enum(["global", "project"]).default("global").describe("Scope to check"),
@@ -5705,7 +5792,7 @@ function createHooksServer() {
       }]
     };
   });
-  server.tool("hooks_setup", "Single-shot agent onboarding: create an agent profile + install recommended hooks in one call. Ideal for agents setting up hooks at session start.", {
+  defineTool("hooks_setup", "Single-shot agent onboarding: create an agent profile + install recommended hooks in one call. Ideal for agents setting up hooks at session start.", {
     agent_type: z.enum(["claude", "gemini", "custom"]).default("claude").describe("Type of AI agent"),
     name: z.string().optional().describe("Optional display name for the agent"),
     hooks: z.array(z.string()).optional().describe("Hook names to install (omit for sensible defaults: gitguard, checkpoint, checktests, protectfiles)"),
@@ -5723,7 +5810,7 @@ function createHooksServer() {
       }]
     };
   });
-  server.tool("hooks_batch_run", "Run multiple hooks in parallel in a single call. Returns all results at once \u2014 more efficient than N separate hooks_run calls.", {
+  defineTool("hooks_batch_run", "Run multiple hooks in parallel in a single call. Returns all results at once \u2014 more efficient than N separate hooks_run calls.", {
     hooks: z.array(z.object({
       name: z.string().describe("Hook name"),
       input: z.record(z.string(), z.unknown()).default(() => ({})).describe("Hook input JSON")
@@ -5761,7 +5848,7 @@ function createHooksServer() {
     }));
     return { content: [{ type: "text", text: JSON.stringify({ results, count: results.length }) }] };
   });
-  server.tool("hooks_disable", "Temporarily disable a registered hook without removing it. Stores disabled list in settings under hooks.__disabled.", {
+  defineTool("hooks_disable", "Temporarily disable a registered hook without removing it. Stores disabled list in settings under hooks.__disabled.", {
     name: z.string().describe("Hook name to disable"),
     scope: z.enum(["global", "project"]).default("global").describe("Scope")
   }, async ({ name, scope }) => {
@@ -5784,7 +5871,7 @@ function createHooksServer() {
 `);
     return { content: [{ type: "text", text: JSON.stringify({ hook: name, disabled: true, scope }) }] };
   });
-  server.tool("hooks_enable", "Re-enable a previously disabled hook.", {
+  defineTool("hooks_enable", "Re-enable a previously disabled hook.", {
     name: z.string().describe("Hook name to enable"),
     scope: z.enum(["global", "project"]).default("global").describe("Scope")
   }, async ({ name, scope }) => {
@@ -5804,25 +5891,50 @@ function createHooksServer() {
     }
     return { content: [{ type: "text", text: JSON.stringify({ hook: name, disabled: false, scope }) }] };
   });
-  server.tool("hooks_init", "Register a new agent profile \u2014 returns a unique agent_id for use with hook installation and execution", {
+  defineTool("hooks_init", "Register a new agent profile \u2014 returns a unique agent_id for use with hook installation and execution", {
     agent_type: z.enum(["claude", "gemini", "custom"]).default("claude").describe("Type of AI agent"),
     name: z.string().optional().describe("Optional display name for the agent")
   }, async ({ agent_type, name }) => {
     const profile = createProfile({ agent_type, name });
     return { content: [{ type: "text", text: JSON.stringify(profile) }] };
   });
-  server.tool("hooks_profiles", "List all registered agent profiles", {}, async () => {
+  defineTool("hooks_profiles", "List registered agent profiles. Compact by default.", {
+    compact: z.boolean().default(true).describe("Return compact summaries by default. Set false for full profiles."),
+    limit: z.number().default(25).describe("Max compact rows to return")
+  }, async ({ compact, limit }) => {
     const profiles = listProfiles();
-    return { content: [{ type: "text", text: JSON.stringify(profiles) }] };
+    if (!compact)
+      return { content: [{ type: "text", text: JSON.stringify(profiles) }] };
+    const maxRows = boundedLimit(limit, 25, 100);
+    const visible = profiles.slice(0, maxRows).map((profile) => ({
+      agent_id: profile.agent_id,
+      agent_type: profile.agent_type,
+      name: profile.name,
+      last_seen_at: profile.last_seen_at
+    }));
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          profiles: visible,
+          count: visible.length,
+          total: profiles.length,
+          omitted: Math.max(0, profiles.length - visible.length),
+          hint: "Use compact:false for full profile preferences."
+        })
+      }]
+    };
   });
-  server.tool("hooks_log_list", "List hook events from SQLite (~/.hasna/hooks/hooks.db). Filter by hook name, session ID, or time range.", {
+  defineTool("hooks_log_list", "List hook events from SQLite. Compact summaries by default; set compact:false for full event rows.", {
     hook_name: z.string().optional().describe("Filter by hook name (e.g. 'sessionlog', 'costwatch')"),
     session_id: z.string().optional().describe("Filter by session ID prefix"),
-    limit: z.number().default(50).describe("Max number of events to return"),
-    since: z.string().optional().describe("ISO timestamp or duration string (e.g. '1h', '30m', '7d') to filter from")
-  }, async ({ hook_name, session_id, limit, since }) => {
+    limit: z.number().optional().describe("Max number of events to return. Defaults to 20 compact rows or 50 full rows."),
+    since: z.string().optional().describe("ISO timestamp or duration string (e.g. '1h', '30m', '7d') to filter from"),
+    compact: z.boolean().default(true).describe("Return compact event summaries by default. Set false for full rows.")
+  }, async ({ hook_name, session_id, limit, since, compact }) => {
     const { getDb: getDb2 } = await Promise.resolve().then(() => (init_db(), exports_db));
     const db = getDb2();
+    const maxRows = boundedLimit(limit, compact ? 20 : 50, compact ? 100 : 500);
     function parseDuration(s) {
       const m = s.match(/^(\d+)(s|m|h|d)$/);
       if (!m)
@@ -5849,24 +5961,48 @@ function createHooksServer() {
       }
     }
     sql += " ORDER BY timestamp DESC LIMIT ?";
-    params.push(limit);
+    params.push(maxRows);
     const rows = db.query(sql).all(...params);
-    return { content: [{ type: "text", text: JSON.stringify({ events: rows, count: rows.length }) }] };
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          events: compact ? rows.map(compactEvent) : rows,
+          count: rows.length,
+          compact,
+          hint: compact ? "Use compact:false for full tool_input/output fields." : undefined
+        })
+      }]
+    };
   });
-  server.tool("hooks_log_tail", "Show the most recent hook events from SQLite.", {
-    n: z.number().default(20).describe("Number of most recent events to return")
-  }, async ({ n }) => {
+  defineTool("hooks_log_tail", "Show recent hook events from SQLite. Compact summaries by default.", {
+    n: z.number().default(20).describe("Number of most recent events to return"),
+    compact: z.boolean().default(true).describe("Return compact event summaries by default. Set false for full rows.")
+  }, async ({ n, compact }) => {
     const { getDb: getDb2 } = await Promise.resolve().then(() => (init_db(), exports_db));
     const db = getDb2();
-    const rows = db.query("SELECT * FROM hook_events ORDER BY timestamp DESC LIMIT ?").all(n);
-    return { content: [{ type: "text", text: JSON.stringify({ events: rows, count: rows.length }) }] };
+    const maxRows = boundedLimit(n, 20, compact ? 100 : 500);
+    const rows = db.query("SELECT * FROM hook_events ORDER BY timestamp DESC LIMIT ?").all(maxRows);
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          events: compact ? rows.map(compactEvent) : rows,
+          count: rows.length,
+          compact,
+          hint: compact ? "Use compact:false for full tool_input/output fields." : undefined
+        })
+      }]
+    };
   });
-  server.tool("hooks_log_errors", "Show hook events that contain errors, optionally filtered by time range.", {
+  defineTool("hooks_log_errors", "Show hook events that contain errors. Compact summaries by default.", {
     since: z.string().default("24h").describe("Duration string (e.g. '1h', '30m', '7d') or ISO timestamp"),
-    limit: z.number().default(50).describe("Max number of error events to return")
-  }, async ({ since, limit }) => {
+    limit: z.number().optional().describe("Max number of error events to return. Defaults to 20 compact rows or 50 full rows."),
+    compact: z.boolean().default(true).describe("Return compact event summaries by default. Set false for full rows.")
+  }, async ({ since, limit, compact }) => {
     const { getDb: getDb2 } = await Promise.resolve().then(() => (init_db(), exports_db));
     const db = getDb2();
+    const maxRows = boundedLimit(limit, compact ? 20 : 50, compact ? 100 : 500);
     function parseDuration(s) {
       const m = s.match(/^(\d+)(s|m|h|d)$/);
       if (!m)
@@ -5876,10 +6012,20 @@ function createHooksServer() {
       return new Date(Date.now() - n * ms).toISOString();
     }
     const ts = since.match(/^\d{4}/) ? since : parseDuration(since);
-    const rows = db.query("SELECT * FROM hook_events WHERE error IS NOT NULL AND timestamp >= ? ORDER BY timestamp DESC LIMIT ?").all(ts, limit);
-    return { content: [{ type: "text", text: JSON.stringify({ events: rows, count: rows.length }) }] };
+    const rows = db.query("SELECT * FROM hook_events WHERE error IS NOT NULL AND timestamp >= ? ORDER BY timestamp DESC LIMIT ?").all(ts, maxRows);
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          events: compact ? rows.map(compactEvent) : rows,
+          count: rows.length,
+          compact,
+          hint: compact ? "Use compact:false for full tool_input/output fields." : undefined
+        })
+      }]
+    };
   });
-  server.tool("hooks_log_summary", "Summarize hook execution: counts per hook, error rates, and recent activity.", {
+  defineTool("hooks_log_summary", "Summarize hook execution: counts per hook, error rates, and recent activity.", {
     since: z.string().default("24h").describe("Duration string (e.g. '1h', '24h', '7d') or ISO timestamp")
   }, async ({ since }) => {
     const { getDb: getDb2 } = await Promise.resolve().then(() => (init_db(), exports_db));
@@ -5913,11 +6059,11 @@ function createHooksServer() {
       }]
     };
   });
-  server.tool("storage_status", "Show hooks storage sync configuration and local sync history.", {}, async () => ({ content: [{ type: "text", text: JSON.stringify(getStorageStatus()) }] }));
-  server.tool("storage_push", "Push local hook data to storage PostgreSQL.", { tables: z.array(z.string()).optional() }, async (params) => ({ content: [{ type: "text", text: JSON.stringify(await storagePush(params.tables ? { tables: params.tables } : undefined)) }] }));
-  server.tool("storage_pull", "Pull hook data from storage PostgreSQL to local SQLite.", { tables: z.array(z.string()).optional() }, async (params) => ({ content: [{ type: "text", text: JSON.stringify(await storagePull(params.tables ? { tables: params.tables } : undefined)) }] }));
-  server.tool("storage_sync", "Bidirectional hooks storage sync: pull then push.", { tables: z.array(z.string()).optional() }, async (params) => ({ content: [{ type: "text", text: JSON.stringify(await storageSync(params.tables ? { tables: params.tables } : undefined)) }] }));
-  server.tool("send_feedback", "Send feedback about this service", {
+  defineTool("storage_status", "Show hooks storage sync configuration and local sync history.", {}, async () => ({ content: [{ type: "text", text: JSON.stringify(getStorageStatus()) }] }));
+  defineTool("storage_push", "Push local hook data to storage PostgreSQL.", { tables: z.array(z.string()).optional() }, async (params) => ({ content: [{ type: "text", text: JSON.stringify(await storagePush(params.tables ? { tables: params.tables } : undefined)) }] }));
+  defineTool("storage_pull", "Pull hook data from storage PostgreSQL to local SQLite.", { tables: z.array(z.string()).optional() }, async (params) => ({ content: [{ type: "text", text: JSON.stringify(await storagePull(params.tables ? { tables: params.tables } : undefined)) }] }));
+  defineTool("storage_sync", "Bidirectional hooks storage sync: pull then push.", { tables: z.array(z.string()).optional() }, async (params) => ({ content: [{ type: "text", text: JSON.stringify(await storageSync(params.tables ? { tables: params.tables } : undefined)) }] }));
+  defineTool("send_feedback", "Send feedback about this service", {
     message: z.string(),
     email: z.string().optional(),
     category: z.enum(["bug", "feature", "general"]).optional()
@@ -5936,7 +6082,7 @@ function createHooksServer() {
       return { content: [{ type: "text", text: String(e) }], isError: true };
     }
   });
-  server.tool("register_agent", "Register an agent session. Returns agent_id. Auto-triggers a heartbeat.", {
+  defineTool("register_agent", "Register an agent session. Returns agent_id. Auto-triggers a heartbeat.", {
     name: z.string(),
     session_id: z.string().optional()
   }, async (params) => {
@@ -5952,7 +6098,7 @@ function createHooksServer() {
     _hooksAgents.set(id, ag);
     return { content: [{ type: "text", text: JSON.stringify(ag) }] };
   });
-  server.tool("heartbeat", "Update last_seen_at to signal agent is active.", {
+  defineTool("heartbeat", "Update last_seen_at to signal agent is active.", {
     agent_id: z.string()
   }, async (params) => {
     const ag = _hooksAgents.get(params.agent_id);
@@ -5961,7 +6107,7 @@ function createHooksServer() {
     ag.last_seen_at = new Date().toISOString();
     return { content: [{ type: "text", text: JSON.stringify({ agent_id: ag.id, last_seen_at: ag.last_seen_at }) }] };
   });
-  server.tool("set_focus", "Set active project context for this agent session.", {
+  defineTool("set_focus", "Set active project context for this agent session.", {
     agent_id: z.string(),
     project_id: z.string().optional()
   }, async (params) => {
@@ -5971,8 +6117,32 @@ function createHooksServer() {
     ag.project_id = params.project_id;
     return { content: [{ type: "text", text: JSON.stringify({ agent_id: ag.id, project_id: ag.project_id ?? null }) }] };
   });
-  server.tool("list_agents", "List all registered agents.", {}, async () => {
-    return { content: [{ type: "text", text: JSON.stringify([..._hooksAgents.values()]) }] };
+  defineTool("list_agents", "List registered agents. Compact by default.", {
+    compact: z.boolean().default(true).describe("Return compact agent summaries by default. Set false for full records."),
+    limit: z.number().default(25).describe("Max compact rows to return")
+  }, async ({ compact, limit }) => {
+    const agents = [..._hooksAgents.values()];
+    if (!compact)
+      return { content: [{ type: "text", text: JSON.stringify(agents) }] };
+    const maxRows = boundedLimit(limit, 25, 100);
+    const visible = agents.slice(0, maxRows).map((agent) => ({
+      id: agent.id,
+      name: agent.name,
+      project_id: agent.project_id,
+      last_seen_at: agent.last_seen_at
+    }));
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          agents: visible,
+          count: visible.length,
+          total: agents.length,
+          omitted: Math.max(0, agents.length - visible.length),
+          hint: "Use compact:false for session_id and full records."
+        })
+      }]
+    };
   });
   return server;
 }
@@ -8208,6 +8378,39 @@ function resolveTarget(options) {
     return "all";
   return "claude";
 }
+function parseLimit(value, fallback, max) {
+  const parsed = value ? parseInt(value, 10) : fallback;
+  if (!Number.isFinite(parsed) || parsed <= 0)
+    return fallback;
+  return Math.min(parsed, max);
+}
+function truncateText2(value, max = 96) {
+  const text = (value ?? "").replace(/\s+/g, " ").trim();
+  if (text.length <= max)
+    return text;
+  return `${text.slice(0, Math.max(0, max - 3))}...`;
+}
+function readmePreview(readme, max = 280) {
+  const blocks = readme.split(/\n\s*\n/).map((part) => part.trim()).filter(Boolean).filter((part) => !part.startsWith("#")).filter((part) => !part.startsWith("```")).filter((part) => !/^\[!\[/.test(part));
+  const preview = blocks[0] ?? readme.split(`
+`).map((line) => line.trim()).find((line) => line && !line.startsWith("#"));
+  return preview ? truncateText2(preview, max) : undefined;
+}
+function hookSummaryLine(hook, options = {}) {
+  const matcher = hook.matcher ? ` ${hook.matcher}` : "";
+  const description = options.verbose ? ` - ${truncateText2(hook.description, 110)}` : "";
+  return `  ${chalk2.cyan(hook.name.padEnd(17))} ${chalk2.dim(`[${hook.event}${matcher}]`)} ${chalk2.dim(hook.category)}${description}`;
+}
+function printDisclosureHint(hidden, detailCommand, options = {}) {
+  const rowControls = options.includeAll ? "--limit, --all, --verbose" : "--limit, --verbose";
+  if (hidden > 0) {
+    console.log(chalk2.dim(`
+  Showing a compact subset. ${hidden} more hidden; use ${rowControls}, or ${detailCommand}.`));
+  } else {
+    console.log(chalk2.dim(`
+  Use --verbose or ${detailCommand} for details.`));
+  }
+}
 function editDistance(a, b) {
   const m = a.length, n = b.length;
   const dp = Array.from({ length: m + 1 }, (_, i) => [i, ...Array(n).fill(0)]);
@@ -8417,8 +8620,9 @@ Installing hooks (${scope}, ${target})...
   console.log(chalk2.dim(`
 Registered in ${settingsFile}`));
 });
-program2.command("list").alias("ls").option("-c, --category <category>", "Filter by category").option("-a, --all", "Show all available hooks", false).option("-i, --installed", "Show only installed hooks", false).option("-r, --registered", "Show registered hooks", false).option("-g, --global", "Check global settings", false).option("-p, --project", "Check project settings", false).option("-t, --target <target>", "Agent target: claude, gemini, codewith (default: claude)", "claude").option("-j, --json", "Output as JSON", false).description("List available or installed hooks").action((options) => {
+program2.command("list").alias("ls").option("-c, --category <category>", "Filter by category").option("-a, --all", "Show all available hooks", false).option("-i, --installed", "Show only installed hooks", false).option("-r, --registered", "Show registered hooks", false).option("-g, --global", "Check global settings", false).option("-p, --project", "Check project settings", false).option("-t, --target <target>", "Agent target: claude, gemini, codewith (default: claude)", "claude").option("-n, --limit <n>", "Max rows to show in compact output", "20").option("--verbose", "Show descriptions and full detail columns", false).option("-j, --json", "Output as JSON", false).description("List available or installed hooks").action((options) => {
   const scope = resolveScope(options);
+  const limit = options.all ? Number.MAX_SAFE_INTEGER : parseLimit(options.limit, 20, 200);
   if (options.registered || options.installed) {
     const target = options.target === "gemini" ? "gemini" : options.target === "codewith" ? "codewith" : "claude";
     const registered = getRegisteredHooksForTarget(scope, target);
@@ -8433,13 +8637,18 @@ program2.command("list").alias("ls").option("-c, --category <category>", "Filter
       console.log(chalk2.dim(`No hooks registered (${scope}, ${target})`));
       return;
     }
+    const visible2 = registered.slice(0, limit);
     console.log(chalk2.bold(`
-Registered hooks \u2014 ${scope}/${target} (${registered.length}):
+Registered hooks \u2014 ${scope}/${target} (${registered.length}, showing ${visible2.length}):
 `));
-    for (const name of registered) {
+    for (const name of visible2) {
       const meta = getHook(name);
-      console.log(`  ${chalk2.cyan(name)} ${chalk2.dim(`[${meta?.event || "unknown"}]`)} - ${meta?.description || ""}`);
+      if (meta)
+        console.log(hookSummaryLine(meta, { verbose: options.verbose }));
+      else
+        console.log(`  ${chalk2.cyan(name)} ${chalk2.dim("[unknown]")}`);
     }
+    printDisclosureHint(registered.length - visible2.length, "hooks info <name>", { includeAll: true });
     return;
   }
   if (options.category) {
@@ -8458,12 +8667,13 @@ Registered hooks \u2014 ${scope}/${target} (${registered.length}):
       console.log(JSON.stringify(hooks));
       return;
     }
+    const visible2 = hooks.slice(0, limit);
     console.log(chalk2.bold(`
-${category} (${hooks.length}):
+${category} (${hooks.length}, showing ${visible2.length}):
 `));
-    for (const h of hooks) {
-      console.log(`  ${chalk2.cyan(h.name)} ${chalk2.dim(`[${h.event}]`)} - ${h.description}`);
-    }
+    for (const h of visible2)
+      console.log(hookSummaryLine(h, { verbose: options.verbose }));
+    printDisclosureHint(hooks.length - visible2.length, "hooks info <name>", { includeAll: true });
     return;
   }
   if (options.json) {
@@ -8474,19 +8684,15 @@ ${category} (${hooks.length}):
     console.log(JSON.stringify(result));
     return;
   }
+  const visible = HOOKS.slice(0, limit);
   console.log(chalk2.bold(`
-Available hooks (${HOOKS.length}):
+Available hooks (${HOOKS.length}, showing ${visible.length}):
 `));
-  for (const category of CATEGORIES) {
-    const hooks = getHooksByCategory(category);
-    console.log(chalk2.bold(`${category} (${hooks.length}):`));
-    for (const h of hooks) {
-      console.log(`  ${chalk2.cyan(h.name)} ${chalk2.dim(`[${h.event}]`)} - ${h.description}`);
-    }
-    console.log();
-  }
+  for (const h of visible)
+    console.log(hookSummaryLine(h, { verbose: options.verbose }));
+  printDisclosureHint(HOOKS.length - visible.length, "hooks info <name>", { includeAll: true });
 });
-program2.command("search").argument("<query>", "Search term").option("-j, --json", "Output as JSON", false).description("Search for hooks").action((query, options) => {
+program2.command("search").argument("<query>", "Search term").option("-n, --limit <n>", "Max rows to show in compact output", "10").option("--verbose", "Show descriptions for search results", false).option("-j, --json", "Output as JSON", false).description("Search for hooks").action((query, options) => {
   const results = searchHooks(query);
   if (options.json) {
     console.log(JSON.stringify(results));
@@ -8496,13 +8702,14 @@ program2.command("search").argument("<query>", "Search term").option("-j, --json
     console.log(chalk2.dim(`No hooks found for "${query}"`));
     return;
   }
+  const limit = parseLimit(options.limit, 10, 100);
+  const visible = results.slice(0, limit);
   console.log(chalk2.bold(`
-Found ${results.length} hook(s):
+Found ${results.length} hook(s), showing ${visible.length}:
 `));
-  for (const h of results) {
-    console.log(`  ${chalk2.cyan(h.name)} ${chalk2.dim(`[${h.event}] [${h.category}]`)}`);
-    console.log(`    ${h.description}`);
-  }
+  for (const h of visible)
+    console.log(hookSummaryLine(h, { verbose: options.verbose }));
+  printDisclosureHint(results.length - visible.length, "hooks info <name>");
 });
 program2.command("remove").alias("rm").argument("<hook>", "Hook to remove").option("-g, --global", "Remove from global settings", false).option("-p, --project", "Remove from project settings", false).option("-t, --target <target>", "Agent target: claude, gemini, codewith, all (default: claude)", "claude").option("-j, --json", "Output as JSON", false).description("Remove an installed hook").action((hook, options) => {
   const scope = resolveScope(options);
@@ -8698,7 +8905,7 @@ Updating hooks...
     }
   }
 });
-program2.command("docs").argument("[hook]", "Hook name (shows general docs if omitted)").option("-j, --json", "Output as JSON", false).description("Show documentation for hooks").action((hook, options) => {
+program2.command("docs").argument("[hook]", "Hook name (shows general docs if omitted)").option("--verbose", "Print full hook README content", false).option("-j, --json", "Output as JSON", false).description("Show documentation for hooks").action((hook, options) => {
   if (hook) {
     const meta = getHook(hook);
     if (!meta) {
@@ -8733,13 +8940,23 @@ ${meta.displayName} v${meta.version}
     console.log(`    hooks install ${meta.name}            # global`);
     console.log(`    hooks install ${meta.name} --project   # project only`);
     console.log();
-    if (readme) {
+    if (readme && options.verbose) {
       console.log(chalk2.bold(`  README:
 `));
       for (const line of readme.split(`
 `)) {
         console.log(`    ${line}`);
       }
+    } else if (readme) {
+      const preview = readmePreview(readme);
+      if (preview) {
+        console.log(chalk2.bold(`  README Preview:
+`));
+        console.log(`    ${preview}
+`);
+      }
+      console.log(chalk2.dim(`  README has ${readme.split(`
+`).length} lines. Use hooks docs ${meta.name} --verbose for the full README, or --json for machine-readable output.`));
     }
     return;
   }
@@ -8816,8 +9033,9 @@ ${meta.displayName} v${meta.version}
   console.log(chalk2.bold(`
   Hook-Specific Docs
 `));
-  console.log(`    hooks docs <name>     View README for a specific hook`);
-  console.log(`    hooks docs --json     Machine-readable documentation`);
+  console.log(`    hooks docs <name>              Compact hook docs`);
+  console.log(`    hooks docs <name> --verbose    Full hook README`);
+  console.log(`    hooks docs --json              Machine-readable documentation`);
   console.log();
 });
 program2.command("upgrade").option("-c, --check", "Check for updates without installing", false).option("-j, --json", "Output as JSON", false).description("Update the @hasna/hooks package to the latest version").action(async (options) => {
@@ -8963,11 +9181,12 @@ logCmd.command("list").description("List hook events").option("--hook <name>", "
 `));
   for (const row of rows) {
     const ts = row.timestamp.slice(0, 19).replace("T", " ");
-    const err = row.error ? chalk2.red(` ERR: ${row.error.slice(0, 60)}`) : "";
+    const err = row.error ? chalk2.red(` ERR: ${truncateText2(row.error, 60)}`) : "";
     const tool = row.tool_name ? chalk2.dim(` [${row.tool_name}]`) : "";
     console.log(`  ${chalk2.dim(ts)}  ${chalk2.cyan(row.hook_name.padEnd(14))}${tool}${err}`);
   }
-  console.log();
+  console.log(chalk2.dim(`
+  Compact rows shown. Use --json for full event records or --limit <n> to change row count.`));
 });
 logCmd.command("search <text>").description("Search hook events by tool_input or error text").option("-n, --limit <n>", "Number of rows to show", "50").option("-j, --json", "Output as JSON", false).action(async (text, options) => {
   const { getDb: getDb2 } = await Promise.resolve().then(() => (init_db(), exports_db));
@@ -8988,10 +9207,11 @@ logCmd.command("search <text>").description("Search hook events by tool_input or
 `));
   for (const row of rows) {
     const ts = row.timestamp.slice(0, 19).replace("T", " ");
-    const snippet = (row.tool_input || row.error || "").slice(0, 80);
+    const snippet = truncateText2(row.tool_input || row.error || "", 80);
     console.log(`  ${chalk2.dim(ts)}  ${chalk2.cyan(row.hook_name.padEnd(14))}  ${chalk2.dim(snippet)}`);
   }
-  console.log();
+  console.log(chalk2.dim(`
+  Compact rows shown. Use --json for full event records or --limit <n> to change row count.`));
 });
 logCmd.command("tail").description("Show most recent hook events").option("-n <n>", "Number of rows", "20").option("-j, --json", "Output as JSON", false).action(async (options) => {
   const { getDb: getDb2 } = await Promise.resolve().then(() => (init_db(), exports_db));
@@ -9011,11 +9231,12 @@ logCmd.command("tail").description("Show most recent hook events").option("-n <n
 `));
   for (const row of rows) {
     const ts = row.timestamp.slice(0, 19).replace("T", " ");
-    const err = row.error ? chalk2.red(` \u2717 ${row.error.slice(0, 60)}`) : "";
+    const err = row.error ? chalk2.red(` \u2717 ${truncateText2(row.error, 60)}`) : "";
     const tool = row.tool_name ? chalk2.dim(` [${row.tool_name}]`) : "";
     console.log(`  ${chalk2.dim(ts)}  ${chalk2.cyan(row.hook_name.padEnd(14))}${tool}${err}`);
   }
-  console.log();
+  console.log(chalk2.dim(`
+  Compact rows shown. Use --json for full event records or -n <n> to change row count.`));
 });
 logCmd.command("errors").description("Show hook events that contain errors").option("--since <duration>", "Only show errors since this duration (e.g. 1h, 30m, 7d)", "24h").option("-n, --limit <n>", "Number of rows to show", "50").option("-j, --json", "Output as JSON", false).action(async (options) => {
   const { getDb: getDb2 } = await Promise.resolve().then(() => (init_db(), exports_db));
@@ -9054,9 +9275,10 @@ logCmd.command("errors").description("Show hook events that contain errors").opt
 `));
   for (const row of rows) {
     const ts = row.timestamp.slice(0, 19).replace("T", " ");
-    console.log(`  ${chalk2.dim(ts)}  ${chalk2.cyan(row.hook_name.padEnd(14))}  ${chalk2.red(row.error.slice(0, 100))}`);
+    console.log(`  ${chalk2.dim(ts)}  ${chalk2.cyan(row.hook_name.padEnd(14))}  ${chalk2.red(truncateText2(row.error, 100))}`);
   }
-  console.log();
+  console.log(chalk2.dim(`
+  Compact rows shown. Use --json for full event records or --limit <n> to change row count.`));
 });
 logCmd.command("clear").description("Delete hook event logs").option("--hook <name>", "Only delete events for this hook").option("-y, --yes", "Skip confirmation prompt", false).action(async (options) => {
   const { getDb: getDb2 } = await Promise.resolve().then(() => (init_db(), exports_db));