@inneranimalmedia/agentsam-sdk 2.6.8 → 2.6.10

package/src/agent/responses-runner.js

@@ -7,6 +7,11 @@ import { searchToolCards, hydrateToolSchemas } from '../tools/index.js';
 import { createAgentEvent } from '../telemetry/index.js';
 import { diagnosticFromError } from '../errors/index.js';
 import { runAgentSamModelTurn } from './model-turn.js';
+import {
+  createHookedCapabilityAdapter,
+  createHookedProviderAdapter,
+  ensureHookRuntime,
+} from '../../packages/agentsam-hooks/src/index.js';
 
 const RUNTIME_OWNED_KEYS = new Set(['account_id', 'user_id', 'tenant_id', 'workspace_id', 'connection_id', 'runtime_lease_id', 'execution_id']);
 
@@ -229,7 +234,7 @@ function toolOutputInput(outputs) {
   }));
 }
 
-export async function runAgentSamTurn(options = {}) {
+async function runAgentSamTurnCore(options = {}) {
   const provider = options.provider;
   if (!provider?.create || !provider?.continueWithToolOutputs) throw new TypeError('Responses provider adapter is required');
   if (!options.capabilityAdapter) throw new TypeError('capabilityAdapter is required');
@@ -615,5 +620,144 @@ export async function runAgentSamTurn(options = {}) {
   });
 }
 
+function hookInvocation(options = {}) {
+  return {
+    session_id: options.sessionId,
+    run_id: options.runId,
+    turn_id: options.turnId,
+    message_id: options.messageId,
+    agent_id: options.agentId,
+    source: options.source || 'agentsam-sdk',
+    metadata: options.hookMetadata,
+  };
+}
+
+/**
+ * Provider-neutral AgentSam turn with optional lifecycle instrumentation.
+ *
+ * Passing `hookRuntime` (or a plain `hooks` registry) instruments the model
+ * and capability adapters without teaching the orchestration loop any
+ * provider, MCP, LSP, or sub-agent wire format. An agent_stop hook may request
+ * another bounded turn; continuation reuses provider state and cumulative
+ * usage instead of constructing a hidden second session.
+ */
+export async function runAgentSamTurn(options = {}) {
+  const hookSource = options.hookRuntime || options.hooks;
+  if (!hookSource) return runAgentSamTurnCore(options);
+
+  const hooks = ensureHookRuntime(hookSource);
+  const cwd = path.resolve(options.cwd || process.cwd());
+  const invocation = hookInvocation(options);
+  const submitted = await hooks.dispatch('user_prompt_submitted', {
+    prompt: clean(options.prompt),
+    cwd,
+  }, invocation, { cwd });
+  const submittedPrompt = clean(submitted.input.prompt);
+  if (!submittedPrompt) throw new TypeError('prompt is required');
+  const transformed = await hooks.dispatch('user_prompt_transformed', {
+    original_prompt: clean(options.prompt),
+    transformed_prompt: submittedPrompt,
+    cwd,
+  }, invocation, { cwd });
+  const prompt = clean(transformed.input.transformed_prompt);
+  if (!prompt) throw new TypeError('transformed prompt is required');
+  const additionalContext = [submitted.output.additional_context, transformed.output.additional_context]
+    .filter(Boolean).join('\n\n');
+  const instrumented = {
+    ...options,
+    prompt,
+    provider: createHookedProviderAdapter(options.provider, {
+      hookRuntime: hooks,
+      invocation,
+      cwd,
+      requestPermission: options.requestPermission,
+      maxRetries: options.maxHookRetries,
+    }),
+    capabilityAdapter: createHookedCapabilityAdapter(options.capabilityAdapter, {
+      hookRuntime: hooks,
+      invocation,
+      cwd,
+      requestPermission: options.requestPermission,
+      maxRetries: options.maxHookRetries,
+    }),
+    ...(additionalContext && options.instructions != null
+      ? { instructions: [String(options.instructions), additionalContext].filter(Boolean).join('\n\n') }
+      : {}),
+    ...(additionalContext && options.instructions == null
+      ? {
+          contextItems: [
+            ...(options.contextItems || []),
+            { kind: 'hook', ref: 'hook://user-prompt/context', priority: 95, content: additionalContext },
+          ],
+        }
+      : {}),
+  };
+
+  const maxContinuations = Number.isInteger(options.maxHookContinuations)
+    ? Math.max(0, Math.min(options.maxHookContinuations, 8))
+    : 4;
+  const continuationReceipts = [];
+  let current = instrumented;
+  let result;
+  let totalCost = 0;
+  let totalRounds = 0;
+  let totalCalls = 0;
+  let totalElapsedMs = 0;
+  let hookContinuations = 0;
+  const costBreakdown = { input: 0, cached_input: 0, cache_write: 0, output: 0 };
+  const allToolReceipts = [];
+  const allContinuationCompactions = [];
+
+  for (let continuationIndex = 0; ; continuationIndex += 1) {
+    result = await runAgentSamTurnCore(current);
+    totalCost += Number(result.total_cost_usd || 0);
+    totalRounds += Number(result.run_budget?.tool_rounds || 0);
+    totalCalls += Number(result.run_budget?.tool_calls || 0);
+    totalElapsedMs += Number(result.run_budget?.elapsed_ms || 0);
+    for (const key of Object.keys(costBreakdown)) costBreakdown[key] += Number(result.cost_breakdown_usd?.[key] || 0);
+    allToolReceipts.push(...(result.tool_receipts || []));
+    allContinuationCompactions.push(...(result.continuation_compactions || []));
+    const stopped = await hooks.dispatch('agent_stop', {
+      stop_reason: result.output_text ? 'completed' : 'no_output',
+      stop_hook_active: continuationIndex > 0,
+      output_text: result.output_text,
+      continuation_index: continuationIndex,
+      run_budget: result.run_budget,
+    }, invocation, { cwd });
+    continuationReceipts.push(...stopped.receipts);
+    if (stopped.output.decision !== 'block') break;
+    if (continuationIndex >= maxContinuations) throw new Error(`hook_continuation_limit_exceeded:${maxContinuations}`);
+    const reason = clean(stopped.output.reason);
+    if (!reason) throw new Error('hook_continuation_reason_required');
+    hookContinuations += 1;
+    current = {
+      ...instrumented,
+      prompt: reason,
+      previousProviderState: result.provider_state,
+      previousUsageSnapshot: result.usage_snapshot,
+      cumulativeUsage: result.cumulative_usage,
+    };
+  }
+
+  return Object.freeze({
+    ...result,
+    ...(submitted.output.suppress_output === true || transformed.output.suppress_output === true
+      ? { output_text: '', suppressed_by_hook: true } : {}),
+    total_cost_usd: totalCost,
+    cost_breakdown_usd: Object.freeze(costBreakdown),
+    tool_receipts: Object.freeze(allToolReceipts),
+    continuation_compactions: Object.freeze(allContinuationCompactions),
+    run_budget: Object.freeze({
+      ...result.run_budget,
+      tool_rounds: totalRounds,
+      tool_calls: totalCalls,
+      elapsed_ms: totalElapsedMs,
+      hook_continuations: hookContinuations,
+      max_hook_continuations: maxContinuations,
+    }),
+    hook_receipts: Object.freeze([...submitted.receipts, ...transformed.receipts, ...continuationReceipts]),
+  });
+}
+
 /** @deprecated Use runAgentSamTurn(). */
 export const runResponsesAgent = runAgentSamTurn;

package/src/cli/command-catalog.js

@@ -14,6 +14,7 @@ export const CLI_COMMAND_CATALOG = Object.freeze([
   { id: 'dev', summary: 'Run this project’s npm dev script', topic: 'work', skill: 'agentsam-app-fundamentals' },
   { id: 'inspect', summary: 'Bounded repository inspect / authority view', topic: 'work', skill: 'agentsam-app-fundamentals', operation: 'repository.inspect', common: true },
   { id: 'machine', summary: 'Deterministic local machine perception (inspect / asset discovery)', topic: 'work', skill: 'agentsam-app-fundamentals', operation: 'machine.inspect', common: true },
+  { id: 'engine', summary: 'Discover, audit, benchmark, and govern local AI engines', topic: 'runtime', skill: 'agentsam-app-fundamentals', operation: 'engine.audit', common: true },
   { id: 'package', summary: 'Audit, verify, and plan publication of distributable packages', topic: 'work', skill: 'agentsam-progression-guard', operation: 'package.audit', common: true, usage: ['agentsam package audit [--public] [--offline] [--json]', 'agentsam package status <name> [--offline] [--json]', 'agentsam package verify <name> [--offline] [--json]', 'agentsam package publish-plan [--offline] [--json]'] },
   { id: 'capabilities', summary: 'Inspect capability contracts', topic: 'create', skill: 'agentsam-app-fundamentals' },
   {
@@ -46,6 +47,7 @@ export const CLI_COMMAND_CATALOG = Object.freeze([
   },
   { id: 'db', summary: 'Project-local SQLite status/init', topic: 'runtime', skill: 'agentsam-app-fundamentals' },
   { id: 'models', summary: 'Probe hosted/local model availability', topic: 'start', skill: 'agentsam-app-fundamentals', common: true },
+  { id: 'hooks', aliases: ['hook'], summary: 'Inspect lifecycle hooks, sources, and execution receipts', topic: 'runtime', skill: 'agentsam-app-fundamentals', common: true, usage: ['agentsam hooks status', 'agentsam hooks list', 'agentsam hooks executions [--limit N]', 'agentsam hooks init'] },
   { id: 'providers', summary: 'Configure machine provider credentials', topic: 'start', skill: 'agentsam-app-fundamentals' },
   { id: 'credentials', aliases: ['credential'], summary: 'Audit credentials, drift, and failure remediation (never prints secrets)', topic: 'start', skill: 'agentsam-app-fundamentals', common: true },
   { id: 'cheat-sheet', aliases: ['cheatsheet'], summary: 'Organized command groups (gcloud-like)', topic: 'start', skill: 'agentsam-app-fundamentals', common: true },

package/src/cli.js

@@ -36,6 +36,7 @@ import { runPackage } from './commands/package.js';
 import { runRecon } from './commands/recon.js';
 import { runCad } from './commands/cad.js';
 import { runMachine } from './commands/machine.js';
+import { runEngine } from './commands/engine.js';
 import { runSkills } from './commands/skills.js';
 import { runSkill } from './commands/skill.js';
 import { runEval } from './commands/eval.js';
@@ -51,6 +52,7 @@ import { runLogin, runLogout } from './commands/account-auth.js';
 import { runPlugins } from './commands/plugins.js';
 import { runCredentials } from './commands/credentials.js';
 import { runCheatSheet } from './commands/cheat-sheet.js';
+import { runHooks } from './commands/hooks.js';
 import { runCompute } from './commands/compute.js';
 import { runGoogleCloud } from './commands/google-cloud.js';
 import { runBilling } from './commands/billing.js';
@@ -99,6 +101,7 @@ function printLegacyHelp() {
     agentsam dev               Run this project's existing npm dev script
     agentsam inspect [--json]  Bounded repository index by default; use --view full for authority envelope
     agentsam machine inspect   Native deterministic perception + asset discovery (--json)
+    agentsam engine status|audit|benchmark|assets  Local AI engine + compute tooling
     agentsam brand [scan|…]    Deterministic brand intelligence on repository.snapshot authority
     agentsam plan brand        Composable brand normalization plan (--goap optional)
     agentsam deploy            Graduate an AgentSam project intentionally
@@ -454,6 +457,14 @@ if (command === '--version' || command === '-v') {
 } else if (command === 'inspect') {
   try { await runInspect(rest); }
   catch (e) { reportCliError(e); process.exitCode = 1; }
+} else if (command === 'engine') {
+  try {
+    const code = await runEngine(rest);
+    if (typeof code === 'number' && code !== 0) process.exitCode = code;
+  } catch (e) {
+    reportCliError(e);
+    process.exitCode = e?.exitCode || 1;
+  }
 } else if (command === 'machine') {
   try {
     const code = await runMachine(rest);
@@ -493,6 +504,14 @@ if (command === '--version' || command === '-v') {
     reportCliError(e);
     process.exit(1);
   }
+} else if (command === 'hooks' || command === 'hook') {
+  try {
+    const code = await runHooks(rest);
+    if (typeof code === 'number' && code !== 0) process.exitCode = code;
+  } catch (e) {
+    reportCliError(e);
+    process.exitCode = 1;
+  }
 } else if (command === 'app' || command === 'apps') {
   try {
     await runApp(rest);

package/src/commands/app.js

@@ -365,6 +365,7 @@ export async function runApp(argv = [], options = {}) {
       'agentsam app doctor <id>',
       'agentsam app preview <id>',
       'agentsam app scaffold <id> <dir>',
+      'agentsam app package <id> [--dry-run]',
       '',
     ].join('\n'));
     return;
@@ -424,6 +425,15 @@ export async function runApp(argv = [], options = {}) {
     write('  app_id is stable product identity. Pass --app-id explicitly; no AGENTSAM_DEFAULT_APP.\n\n');
     return { id: app.id, curl, command: npmCmd };
   }
+  if (command === 'package') {
+    const dryRun = rest.includes('--dry-run') || !rest.includes('--write');
+    const packArgs = ['pack', ...(dryRun ? ['--dry-run', '--ignore-scripts'] : []), '--json'];
+    const result = spawnSync('npm', packArgs, { cwd: app.dir, encoding: 'utf8', env: process.env });
+    if (result.status !== 0) throw new Error(String(result.stderr || result.stdout || `npm pack failed for ${app.id}`).trim());
+    const metadata = JSON.parse(result.stdout)[0];
+    write(`${JSON.stringify({ app_id: app.id, package: metadata.name, version: metadata.version, filename: metadata.filename, size: metadata.size, dry_run: dryRun }, null, 2)}\n`);
+    return metadata;
+  }
   if (command === 'doctor' || command === 'preview') {
     runAppBin(app, [command, ...rest], options);
     return;

package/src/commands/cheat-sheet.js

@@ -75,6 +75,7 @@ const GROUPS = Object.freeze([
     label: 'AI',
     commands: [
       ['models', 'Hosted + local model probes'],
+      ['hooks', 'Lifecycle sources, dispatch order, and receipts'],
       ['skills', 'Portable skill vocabulary'],
       ['context', 'Context economics + git bridge'],
       ['usage / session', 'Spend and resume receipts'],

package/src/commands/engine.js

@@ -0,0 +1,10 @@
+import path from 'node:path';
+import { createLocalEngineRegistry } from '../local-engine/index.js';
+import { auditLocalCompute } from '../local-engine/audit.js';
+import { auditAssets } from '../local-engine/assets.js';
+import { benchmarkEngine } from '../local-engine/benchmark.js';
+
+function parse(argv = []) { const out = { action: argv[0] || 'status', engine: null, model: null, json: argv.includes('--json'), runs: 1, cwd: process.cwd() }; for (let i = 1; i < argv.length; i += 1) { const arg = argv[i]; if (arg === '--model') out.model = argv[++i]; else if (arg === '--runs') out.runs = Number(argv[++i]) || 1; else if (arg === '--cwd') out.cwd = path.resolve(argv[++i] || out.cwd); else if (arg === '--engine') out.engine = argv[++i]; } return out; }
+function emit(value, json) { if (json) console.log(JSON.stringify(value)); else console.log(JSON.stringify(value, null, 2)); }
+function usage() { return `agentsam engine <status|audit|benchmark|assets> [options]\n\n  status                 Discover local engines and models\n  audit                  Read-only Apple hardware + engine inventory\n  benchmark              Measure a selected engine/model\n  assets audit           Audit adopted model references without copying weights\n\n  --engine <id>          ollama | mlx-lm | llama.cpp\n  --model <id>           Engine model identifier\n  --runs <n>             Benchmark repetitions (default 1)\n  --cwd <path>           Project context\n  --json                 Machine-readable output\n`; }
+export async function runEngine(argv = []) { const args = parse(argv); if (args.action === '--help' || args.action === 'help') { console.log(usage()); return 0; } const registry = createLocalEngineRegistry(); if (args.action === 'status') { emit({ schema_version: 'agentsam.local-engine.v1', engines: await registry.discover() }, args.json); return 0; } if (args.action === 'audit') { emit(auditLocalCompute(), args.json); return 0; } if (args.action === 'assets' && argv[1] === 'audit') { emit(auditAssets(), args.json); return 0; } if (args.action === 'benchmark') { if (!args.engine || !args.model) throw new Error('engine benchmark requires --engine <id> and --model <id>'); const result = await benchmarkEngine(registry.get(args.engine), { model: args.model, runs: args.runs }); emit(result, args.json); return 0; } console.log(usage()); return 1; }

package/src/commands/hooks.js

@@ -0,0 +1,260 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  HOOK_CONFIG_SCHEMA,
+  createHookRuntime,
+  createHookRuntimeFromConfig,
+  findHookConfig,
+  loadHookConfig,
+  registerStoredHooks,
+} from '../../packages/agentsam-hooks/src/index.js';
+import { findCliProjectRoot } from '../lib/cli-preferences.js';
+import { readAccountSession } from '../lib/account-session.js';
+import {
+  listRuntimeHooks,
+  listRuntimeHookExecutions,
+  recordRuntimeHookReceipt,
+  setRuntimeHookActive,
+} from '../local/runtime-store.js';
+
+function clean(value) { return value == null ? '' : String(value).trim(); }
+function writeLine(write, value = '') { write(`${value}\n`); }
+function countConfigured(config) {
+  return Object.values(config?.hooks || {}).reduce((sum, rows) => sum + rows.length, 0);
+}
+
+function registerCodeHooks(runtime, hooks = {}) {
+  for (const [event, definitions] of Object.entries(hooks || {})) {
+    for (const definition of Array.isArray(definitions) ? definitions : [definitions]) {
+      if (typeof definition === 'function') {
+        runtime.register(event, { handler: definition, metadata: { hook_source: 'code' } });
+      } else {
+        runtime.register(event, {
+          ...definition,
+          metadata: { ...(definition?.metadata || {}), hook_source: 'code' },
+        });
+      }
+    }
+  }
+}
+
+/**
+ * Resolve code, project config, and stored definitions into one ordered runtime.
+ * The source changes authoring/ownership only; dispatch semantics stay identical.
+ */
+export async function createProjectHookRuntime(options = {}) {
+  const cwd = path.resolve(options.cwd || process.cwd());
+  const projectRoot = path.resolve(options.projectRoot || findCliProjectRoot(cwd));
+  const accountId = clean(options.ownerId || readAccountSession({ home: options.home })?.account_id) || 'local';
+  const sourceByHook = new Map();
+  const persistReceipts = options.persistReceipts !== false;
+  const runtime = createHookRuntime({
+    clock: options.clock,
+    async onReceipt(receipt) {
+      const definition = sourceByHook.get(`${receipt.hook}:${receipt.hook_id}`) || { source: 'code', stored_hook_id: null };
+      if (persistReceipts) {
+        await recordRuntimeHookReceipt({
+          projectRoot,
+          owner_id: accountId,
+          receipt,
+          source_kind: definition.source,
+          hook_id: definition.stored_hook_id,
+          session_id: options.sessionId,
+          conversation_id: options.conversationId,
+        });
+      }
+      if (typeof options.onReceipt === 'function') await options.onReceipt(receipt);
+    },
+  });
+
+  registerCodeHooks(runtime, options.hooks);
+  const configFile = options.configFile || findHookConfig(cwd, { stopAt: projectRoot });
+  let config = null;
+  if (configFile) {
+    ({ config } = createHookRuntimeFromConfig(configFile, {
+      runtime,
+      cwd,
+      env: options.env,
+      fetchImpl: options.fetchImpl,
+      restrictCommandCwd: options.restrictCommandCwd,
+    }));
+  }
+
+  const stored = await registerStoredHooks(runtime, {
+    listHooks: (query) => listRuntimeHooks({
+      projectRoot,
+      owner_id: accountId,
+      ...query,
+    }),
+  }, {
+    cwd: projectRoot,
+    env: options.env,
+    fetchImpl: options.fetchImpl,
+    restrictCommandCwd: options.restrictCommandCwd,
+    resolveHandler: options.resolveHandler,
+    context: {
+      owner_id: accountId,
+      account_id: accountId,
+      project_id: options.projectId,
+      project_root: projectRoot,
+      repository_id: options.repositoryId,
+      session_id: options.sessionId,
+    },
+  });
+
+  for (const definition of runtime.list()) {
+    sourceByHook.set(`${definition.hook}:${definition.id}`, {
+      source: clean(definition.metadata?.hook_source) || (definition.metadata?.stored_hook_id ? 'stored' : definition.metadata?.config_source ? 'config' : 'code'),
+      stored_hook_id: clean(definition.metadata?.stored_hook_id) || null,
+    });
+  }
+  return Object.freeze({
+    runtime,
+    owner_id: accountId,
+    project_root: projectRoot,
+    config,
+    config_file: configFile || null,
+    stored,
+    definitions: runtime.list(),
+  });
+}
+
+function hookTemplate() {
+  return {
+    schema: HOOK_CONFIG_SCHEMA,
+    adapters: {},
+    hooks: {},
+  };
+}
+
+function parseLimit(argv, fallback = 30) {
+  const index = argv.indexOf('--limit');
+  if (index === -1) return fallback;
+  const value = Number(argv[index + 1]);
+  if (!Number.isInteger(value) || value < 1 || value > 500) throw new Error('hooks_limit_must_be_between_1_and_500');
+  return value;
+}
+
+function renderHookRows(rows, write) {
+  if (!rows.length) {
+    writeLine(write, '  No hooks configured. Run `agentsam hooks init` or add a stored hook.');
+    return;
+  }
+  for (const row of rows) {
+    const source = clean(row.metadata?.hook_source || row.source_kind) || 'code';
+    const state = row.enabled === false || row.is_active === false ? 'disabled' : 'active';
+    const handler = clean(row.handler_type || row.metadata?.adapter) || 'callback';
+    writeLine(write, `  ${String(row.hook || row.event_type).padEnd(25)} ${String(row.id || row.hook_key).padEnd(28)} ${source.padEnd(7)} ${handler.padEnd(10)} ${state} · p${row.priority ?? 100}`);
+  }
+}
+
+export async function runHooks(argv = [], options = {}) {
+  const write = options.write || ((text) => process.stdout.write(text));
+  const cwd = path.resolve(options.cwd || process.cwd());
+  const projectRoot = findCliProjectRoot(cwd);
+  const jsonOutput = argv.includes('--json');
+  const command = argv.find((arg) => !arg.startsWith('-')) || 'status';
+  if (argv.includes('--help') || argv.includes('-h') || command === 'help') {
+    write([
+      'agentsam hooks [status|list|executions|validate|init|enable|disable] [--json]',
+      '',
+      'One hook concept, three authoring sources: code, project config, and stored rows.',
+      '  status                  Show active sources and execution evidence',
+      '  list                    Show the merged dispatch order with source badges',
+      '  executions [--limit N]  Show recent value-free receipts',
+      '  validate [config]       Validate a portable hook config',
+      '  init                    Create .agentsam/hooks.json (idempotent)',
+      '  enable|disable <key>    Toggle a stored hook without editing code/config',
+      '',
+    ].join('\n'));
+    return 0;
+  }
+
+  if (command === 'init') {
+    const filename = path.join(projectRoot, '.agentsam', 'hooks.json');
+    fs.mkdirSync(path.dirname(filename), { recursive: true });
+    const created = !fs.existsSync(filename);
+    if (created) fs.writeFileSync(filename, `${JSON.stringify(hookTemplate(), null, 2)}\n`, { mode: 0o600 });
+    const loaded = loadHookConfig(filename);
+    const result = { ok: true, created, source: filename, schema: loaded.schema };
+    if (jsonOutput) writeLine(write, JSON.stringify(result, null, 2));
+    else writeLine(write, `  Hooks config ready · ${filename}`);
+    return result;
+  }
+
+  if (command === 'validate') {
+    const commandIndex = argv.indexOf(command);
+    const candidate = argv.slice(commandIndex + 1).find((arg) => !arg.startsWith('-'));
+    const filename = candidate || findHookConfig(cwd, { stopAt: projectRoot });
+    if (!filename) throw new Error('agentsam_hook_config_not_found');
+    const config = loadHookConfig(filename);
+    const result = { ok: true, schema: config.schema, source: config.source, adapters: Object.keys(config.adapters).length, hooks: countConfigured(config) };
+    if (jsonOutput) writeLine(write, JSON.stringify(result, null, 2));
+    else writeLine(write, `  Valid · ${result.hooks} hooks · ${result.adapters} adapters · ${result.source}`);
+    return result;
+  }
+
+  const ownerId = clean(options.ownerId || readAccountSession({ home: options.home })?.account_id) || 'local';
+  if (command === 'enable' || command === 'disable') {
+    const key = argv[argv.indexOf(command) + 1];
+    if (!key || key.startsWith('-')) throw new Error(`hooks_${command}_requires_key`);
+    const changed = await setRuntimeHookActive({ projectRoot, owner_id: ownerId, hook_key: key, active: command === 'enable' });
+    if (!changed) throw new Error(`stored_hook_not_found:${key}`);
+    const result = { ok: true, hook_key: key, active: command === 'enable' };
+    if (jsonOutput) writeLine(write, JSON.stringify(result, null, 2));
+    else writeLine(write, `  ${key} → ${result.active ? 'enabled' : 'disabled'}`);
+    return result;
+  }
+
+  if (command === 'executions') {
+    const executions = await listRuntimeHookExecutions({ projectRoot, owner_id: ownerId, limit: parseLimit(argv) });
+    if (jsonOutput) writeLine(write, JSON.stringify({ schema: 'agentsam.hook.executions.v1', executions }, null, 2));
+    else {
+      writeLine(write, '\n  Recent hook executions');
+      if (!executions.length) writeLine(write, '  No hook receipts recorded yet.');
+      for (const row of executions) {
+        const at = new Date(Number(row.ran_at_unix) * 1000).toISOString();
+        writeLine(write, `  ${at} ${String(row.status).padEnd(9)} ${String(row.event_type).padEnd(24)} ${row.hook_key} · ${row.duration_ms}ms`);
+      }
+      writeLine(write);
+    }
+    return executions;
+  }
+
+  if (!['status', 'list'].includes(command)) throw new Error(`unknown_hooks_command:${command}`);
+  const resolved = await createProjectHookRuntime({
+    cwd,
+    projectRoot,
+    ownerId,
+    home: options.home,
+    hooks: options.hooks,
+    persistReceipts: false,
+  });
+  const storedAll = await listRuntimeHooks({ projectRoot, owner_id: ownerId, activeOnly: false });
+  const result = {
+    schema: 'agentsam.hooks.status.v1',
+    project_root: projectRoot,
+    owner_id: ownerId,
+    config: resolved.config ? { source: resolved.config_file, hooks: countConfigured(resolved.config), adapters: Object.keys(resolved.config.adapters).length } : null,
+    sources: {
+      code: resolved.definitions.filter((row) => row.metadata?.hook_source === 'code').length,
+      config: resolved.definitions.filter((row) => row.metadata?.hook_source === 'config').length,
+      stored_active: resolved.definitions.filter((row) => row.metadata?.hook_source === 'stored').length,
+      stored_total: storedAll.length,
+    },
+    hooks: resolved.definitions,
+  };
+  if (jsonOutput) writeLine(write, JSON.stringify(result, null, 2));
+  else {
+    writeLine(write, '\n  Agent Sam · hooks');
+    writeLine(write, '  One ordered lifecycle contract · code is read-only · config/stored hooks are portable.');
+    writeLine(write, `  project  ${projectRoot}`);
+    writeLine(write, `  config   ${result.config ? `${result.config.hooks} hooks · ${result.config.source}` : 'not configured'}`);
+    writeLine(write, `  stored   ${result.sources.stored_active} active · ${result.sources.stored_total} total`);
+    writeLine(write, '');
+    if (command === 'list') renderHookRows([...resolved.definitions, ...storedAll.filter((row) => !row.is_active)], write);
+    else writeLine(write, '  Use `agentsam hooks list` for dispatch order and `agentsam hooks executions` for receipts.');
+    writeLine(write);
+  }
+  return result;
+}