@hasna/hooks 0.6.3 → 0.6.4

package/dist/lib/db-writer.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Shared hook DB writer — single write path for all observability hooks.
+ * Never throws: errors are written to stderr only.
+ */
+import type { HookEventRow } from "../db/schema";
+export type HookEventInput = Omit<HookEventRow, "id" | "timestamp"> & {
+    timestamp?: string;
+};
+export declare function writeHookEvent(event: HookEventInput): void;
+/** Normalize a hook_event_name from hook input to a value the schema accepts. */
+export declare function normalizeEventType(value: unknown): string | null;
+/**
+ * Pick the event type for a run record: the hook input's hook_event_name when
+ * it is valid, else the hook's declared event. Guarantees a row lands for
+ * every execution even when the agent passes an unknown event name.
+ */
+export declare function resolveEventType(inputEvent: unknown, fallbackEvent: string | null | undefined): string | null;
+/**
+ * Record one hook execution in hook_events — the row `hooks log` reads.
+ * Written by every run path (CLI run, SDK runHook, MCP run tools) so a real
+ * fire is always observable (bug ef58dcb7: 0 rows after real fires).
+ *
+ * Never throws: observability must not break execution. An invalid event type
+ * or a missing DB is reported on stderr and skipped.
+ */
+export declare function recordHookRun(record: {
+    hookName: string;
+    eventType: string | null;
+    version?: string | null;
+    sha256?: string | null;
+    sessionId?: string | null;
+    toolName?: string | null;
+    toolInput?: unknown;
+    result?: "continue" | "block" | null;
+    error?: string | null;
+    exitCode: number;
+    durationMs: number;
+    projectDir?: string | null;
+    metadata?: Record<string, unknown>;
+}): void;

package/dist/lib/installer.d.ts

@@ -54,4 +54,41 @@ export declare function getRegisteredHooks(scope?: Scope): string[];
 /** @deprecated Use getRegisteredHooks instead */
 export declare const getInstalledHooks: typeof getRegisteredHooks;
 export declare function removeHook(name: string, scope?: Scope, target?: Target): boolean;
+export interface UninstallResult {
+    name: string;
+    removed: boolean;
+    source: "custom" | "bundled" | "registered-only" | null;
+    settingsScopes: Scope[];
+    storeDirRemoved: boolean;
+    pinRemoved: boolean;
+    dbRecordRemoved: boolean;
+    /** Targets whose config still registers the hook after removal (e.g. codewith TOML the caller must edit itself). */
+    registrationsRemaining: string[];
+    error?: string;
+}
+/**
+ * Lossless removal of a `hooks run <name>` entry from a Codewith config.toml.
+ *
+ * Works on sections split by blank lines — the shape buildCodewithTomlFragment
+ * writes: a `[[hooks.EVENT]]` header section (with optional matcher), then one
+ * `[[hooks.EVENT.hooks]]` entry section per hook containing
+ * `command = "hooks run <name>"`. Only sections positively identified as this
+ * hook's entries are removed; the enclosing EVENT header is dropped only when
+ * every one of its entries belonged to this hook. Anything ambiguous is
+ * preserved verbatim.
+ */
+export declare function removeCodewithHookEntry(configText: string, name: string): {
+    text: string;
+    removed: boolean;
+};
+/**
+ * Full uninstall — the settings registration, the store directory (custom
+ * hooks), the lock pin and the DB record are all removed. Bundled hooks keep
+ * their package files (they belong to the package, not the store).
+ *
+ * Resolves custom and registry-synced hooks, which live in the custom store
+ * dir, as well as bundled ones (QA-1 BUG-A / QA-4: remove was bundled-only
+ * and never cleaned the store/lock/DB).
+ */
+export declare function uninstallHook(name: string, scope?: Scope, target?: Target): UninstallResult;
 export {};

package/dist/lib/resolve.d.ts

@@ -12,6 +12,8 @@ export interface ResolvedHook {
     description: string;
     scriptPath: string;
     meta: HookMeta;
+    /** The hook's own declared timeout (manifest timeout_ms), or null. */
+    timeoutMs: number | null;
 }
 /**
  * Locate the bundled hooks directory at runtime from the executing module's

package/dist/lib/run.d.ts

@@ -34,4 +34,12 @@ export interface VerifiedRunResult {
     stderr: string;
     exitCode: number;
 }
+/**
+ * Raised when a verified script exceeds its timeout. The whole process group
+ * was killed, so no descendant survives (see executeVerifiedScript).
+ */
+export declare class HookTimeoutError extends Error {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
 export declare function executeVerifiedScript(options: VerifiedRunOptions): Promise<VerifiedRunResult>;

package/dist/lib/store.d.ts

@@ -44,6 +44,21 @@ export declare function writeLock(lock: LockFile): string;
 export declare function setPinnedHook(name: string, entry: LockEntry): string;
 export declare function getPinnedHook(name: string): LockEntry | undefined;
 export declare function removePinnedHook(name: string): boolean;
+/**
+ * Pin a hook at install time — the ACTUAL installed version and sha, so the
+ * first run is trusted with real provenance instead of a 0.0.0 placeholder
+ * (QA-1 P3: install pinned 0.0.0 until trust).
+ */
+export declare function pinInstalledHook(name: string, version: string, sha256: string, source: string, sourceRef?: string | null): void;
+/**
+ * Remove every store-side record of a hook: the lock pin and the DB row.
+ * Does not touch hook files on disk — callers decide whether the hook lives
+ * in the package (bundled, keep) or the custom store dir (remove).
+ */
+export declare function removeHookFromStore(name: string): {
+    removedPin: boolean;
+    removedRecord: boolean;
+};
 export interface TrustCheck {
     ok: boolean;
     pinned: boolean;

package/dist/lib/sync.d.ts

@@ -33,3 +33,22 @@ export declare function planSync(): Promise<SyncPlan>;
 export declare function syncHooks(options?: {
     dryRun?: boolean;
 }): Promise<SyncPlan>;
+export interface PinnedHookInstall {
+    name: string;
+    version: string;
+    sha256: string;
+    source: string;
+    source_ref: string;
+    artifact: ArtifactResponse;
+    scriptPath: string;
+}
+/**
+ * Fetch one exact hook version from the remote registry, verify its sha
+ * against the remote lock, write it to the custom store, and pin it.
+ * Powers `hooks install <name>@<version>` / `hooks update <name>@<version>`
+ * (QA-2 finding: pinned-version install/update was unsupported).
+ *
+ * Requires an api_url (remote registry). The sha check is against the remote
+ * lock — the exact version named by the user, never a mutable latest.
+ */
+export declare function fetchPinnedHook(name: string, version: string, apiUrl: string): Promise<PinnedHookInstall>;

package/dist/storage.js

@@ -22,7 +22,7 @@ var CREATE_HOOK_EVENTS_TABLE = `
     timestamp    TEXT NOT NULL,
     session_id   TEXT NOT NULL,
     hook_name    TEXT NOT NULL,
-    event_type   TEXT NOT NULL CHECK (event_type IN ('PreToolUse', 'PostToolUse', 'Stop', 'Notification', 'SessionStart', 'SessionEnd', 'UserPromptSubmit')),
+    event_type   TEXT NOT NULL CHECK (event_type IN ('PreToolUse', 'PostToolUse', 'Stop', 'Notification', 'SessionStart', 'SessionEnd', 'UserPromptSubmit', 'SubagentStart')),
     tool_name    TEXT,
     tool_input   TEXT,
     result       TEXT CHECK (result IN ('continue', 'block', NULL)),
@@ -137,6 +137,35 @@ var init_004_hooks_table = __esm(() => {
   ];
 });
 
+// src/db/migrations/005_subagent_start_event.ts
+function up5(db) {
+  const row = db.query("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = ?").get("hook_events");
+  if (!row?.sql)
+    return;
+  if (row.sql.includes("SubagentStart"))
+    return;
+  db.exec("BEGIN");
+  try {
+    db.exec("ALTER TABLE hook_events RENAME TO hook_events_old");
+    db.exec(CREATE_HOOK_EVENTS_TABLE);
+    db.exec(`INSERT INTO hook_events
+         (id, timestamp, session_id, hook_name, event_type, tool_name, tool_input, result, error, duration_ms, project_dir, metadata)
+       SELECT id, timestamp, session_id, hook_name, event_type, tool_name, tool_input, result, error, duration_ms, project_dir, metadata
+       FROM hook_events_old`);
+    db.exec("DROP TABLE hook_events_old");
+    for (const idx of CREATE_INDEXES) {
+      db.exec(idx);
+    }
+    db.exec("COMMIT");
+  } catch (err) {
+    db.exec("ROLLBACK");
+    throw err;
+  }
+}
+var init_005_subagent_start_event = __esm(() => {
+  init_schema();
+});
+
 // src/db/migrations/index.ts
 function ensureMigrationsTable(db) {
   db.exec(`
@@ -169,11 +198,13 @@ var init_migrations = __esm(() => {
   init_002_session_events();
   init_003_user_prompt_submit_event();
   init_004_hooks_table();
+  init_005_subagent_start_event();
   MIGRATIONS = [
     { version: "001_initial", up },
     { version: "002_session_events", up: up2 },
     { version: "003_user_prompt_submit_event", up: up3 },
-    { version: "004_hooks_table", up: up4 }
+    { version: "004_hooks_table", up: up4 },
+    { version: "005_subagent_start_event", up: up5 }
   ];
 });
 
@@ -343,6 +374,7 @@ function getDb() {
   const isNew = dbPath === ":memory:" || !existsSync2(dbPath);
   ensureDir(dbPath);
   instance = new Database(dbPath);
+  instance.exec("PRAGMA busy_timeout=5000");
   instance.exec("PRAGMA journal_mode=WAL");
   instance.exec("PRAGMA foreign_keys=ON");
   runMigrations(instance);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/hooks",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "Open source hooks library for AI coding agents - Install safety, quality, and automation hooks with a single command",
   "type": "module",
   "bin": {