@inneranimalmedia/agentsam-sdk 2.6.9 → 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

@@ -47,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

@@ -52,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';
@@ -503,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/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/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;
+}

package/src/commands/models.js

@@ -17,7 +17,7 @@ export const API_PROVIDERS = Object.freeze([
   { id: 'openai', label: 'OpenAI', credential: 'OPENAI_API_KEY' },
   { id: 'anthropic', label: 'Anthropic', credential: 'ANTHROPIC_API_KEY' },
   { id: 'gemini', label: 'Gemini', credential: 'GEMINI_API_KEY' },
-  { id: 'grok', label: 'Grok / xAI', credential: 'XAI_API_KEY' },
+  { id: 'xai', label: 'Grok / xAI', credential: 'XAI_API_KEY' },
   { id: 'cursor', label: 'Cursor', credential: 'CURSOR_API_KEY' },
   { id: 'cloudflare', label: 'Cloudflare', credential: 'CLOUDFLARE_API_TOKEN' },
 ]);

package/src/commands/shell.js

@@ -33,6 +33,7 @@ import { grantExecutionApproval, isExecutionApproved, toolApprovalKey } from '..
 import { runWhoami } from './whoami.js';
 import { runCredentials } from './credentials.js';
 import { runCheatSheet } from './cheat-sheet.js';
+import { createProjectHookRuntime, runHooks } from './hooks.js';
 import pkg from '../../package.json' with { type: 'json' };
 import { runLogin, runLogout } from './account-auth.js';
 import { runHelp } from '../ui/cli/help.js';
@@ -262,21 +263,48 @@ function spawnGit(cwd, args) {
   if (result.status !== 0) throw new Error(`git exited ${result.status}`);
 }
 
-function selectedModel(cwd) {
-  const preferences = readCliPreferences(cwd) || {};
-  const snapshot = preferences.modelSnapshot?.model_key === preferences.modelPreference
-    ? mergeModelReference(preferences.modelSnapshot)
+function selectedModel(cwd, state = null) {
+  const saved = readCliPreferences(cwd) || {};
+  const sessionConfig = state?.hookEffectiveConfig || {};
+  const preferences = {
+    ...saved,
+    ...(sessionConfig.model_key ? { modelPreference: sessionConfig.model_key } : {}),
+    ...(sessionConfig.reasoning_effort ? { reasoningEffort: sessionConfig.reasoning_effort } : {}),
+    ...(sessionConfig.requested_service_tier ? { serviceTier: sessionConfig.requested_service_tier } : {}),
+  };
+  const snapshot = saved.modelSnapshot?.model_key === preferences.modelPreference
+    ? mergeModelReference(saved.modelSnapshot)
     : null;
   let model = snapshot || getModelRecord(preferences.modelPreference);
+  if (!model && sessionConfig.model_key && sessionConfig.model_key.includes(':')) {
+    const [provider, ...modelParts] = sessionConfig.model_key.split(':');
+    const providerModelId = modelParts.join(':');
+    if (provider && providerModelId) {
+      model = {
+        model_key: sessionConfig.model_key,
+        provider,
+        provider_model_id: providerModelId,
+        label: providerModelId,
+        context_window: null,
+        context_window_source: 'unknown',
+        max_output_tokens: null,
+        max_output_tokens_source: 'unknown',
+        reasoning_efforts: ['auto'],
+        default_reasoning_effort: null,
+        service_tiers: ['default'],
+        capabilities: {},
+      };
+    }
+  }
   if (!model && (preferences.modelPreference === 'auto' || !preferences.modelPreference)) {
-    model = mergeModelReference(preferences.modelSnapshot) || listModelCatalog()[0];
+    model = mergeModelReference(saved.modelSnapshot) || listModelCatalog()[0];
   }
   if (!model) throw new Error('Select an exact provider-verified model with /model first so Agent Sam can verify supported runtime controls.');
   return { preferences, model };
 }
 
 async function resolveModelForTurn(cwd, state) {
-  const selected = selectedModel(cwd);
+  const selected = selectedModel(cwd, state);
   const { preferences } = selected;
   let model = selected.model;
 
@@ -291,7 +319,7 @@ async function resolveModelForTurn(cwd, state) {
       capabilities: { ...(model.capabilities || {}), local_runtime: true, ...(Object.fromEntries((probe.capabilities || []).map((name) => [name, true]))) },
     };
     updateCliPreferences(cwd, { modelPreference: model.model_key, modelSnapshot: model });
-    return { preferences: readCliPreferences(cwd) || preferences, model, credential: null, verification: 'local_runtime' };
+    return { preferences: { ...(readCliPreferences(cwd) || preferences), reasoningEffort: preferences.reasoningEffort, serviceTier: preferences.serviceTier }, model, credential: null, verification: 'local_runtime' };
   }
 
   const credential = resolveProviderCredential(model.provider, { home: state.home });
@@ -305,7 +333,7 @@ async function resolveModelForTurn(cwd, state) {
     if (!live) throw new Error(`selected_model_not_available_for_credential:${model.provider}:${model.provider_model_id}`);
     model = live;
     updateCliPreferences(cwd, { modelPreference: live.model_key, modelSnapshot: live });
-    return { preferences: readCliPreferences(cwd) || preferences, model, credential, verification: 'provider_api' };
+    return { preferences: { ...(readCliPreferences(cwd) || preferences), reasoningEffort: preferences.reasoningEffort, serviceTier: preferences.serviceTier }, model, credential, verification: 'provider_api' };
   }
 
   if (preferences.modelSnapshot?.availability === 'available') {
@@ -595,7 +623,47 @@ function checkpointCompaction(state, model, result) {
   return receipt;
 }
 
+async function ensureShellHookExperience(state) {
+  if (state.hookExperience) return state.hookExperience;
+  const experience = await createProjectHookRuntime({
+    cwd: state.cwd,
+    projectRoot: state.projectRoot,
+    home: state.home,
+    sessionId: state.session?.id,
+    conversationId: state.session?.conversation_id,
+    hooks: state.codeHooks,
+  });
+  state.hookExperience = experience;
+  if (!state.hookSessionStarted) {
+    const config = {
+      model_key: state.session?.model_key || null,
+      reasoning_effort: state.session?.reasoning_effort || null,
+      requested_service_tier: state.session?.requested_service_tier || 'default',
+      auto_compact: state.session?.auto_compact !== false,
+    };
+    const started = await experience.runtime.dispatch('session_start', {
+      config,
+      project_root: state.projectRoot,
+      cwd: state.cwd,
+    }, {
+      session_id: state.session?.id,
+      source: 'agentsam-cli',
+    }, { cwd: state.cwd });
+    const modified = started.input.config || config;
+    const allowed = {};
+    for (const key of ['model_key', 'reasoning_effort', 'requested_service_tier', 'auto_compact']) {
+      if (modified[key] !== undefined) allowed[key] = modified[key];
+    }
+    state.hookEffectiveConfig = { ...config, ...allowed };
+    if (state.session && Object.keys(allowed).length) persistSession(state, allowed);
+    state.hookSessionContext = started.output.additional_context || null;
+    state.hookSessionStarted = true;
+  }
+  return experience;
+}
+
 async function runInteractiveModelTurn(prompt, state) {
+  const hookExperience = await ensureShellHookExperience(state);
   const resolved = await resolveModelForTurn(state.cwd, state);
   const { preferences, model, credential } = resolved;
   const provider = createProviderAdapter({
@@ -660,7 +728,13 @@ async function runInteractiveModelTurn(prompt, state) {
       autoCompact: state.session?.auto_compact !== false,
       onCompaction: result => { if (state.session) checkpointCompaction(state, model, result); },
       promptCacheKey: state.session?.id || undefined,
+      hookRuntime: hookExperience.runtime,
+      sessionId: state.session?.id || undefined,
       runId: runtimeRunId || state.session?.id || undefined,
+      source: 'agentsam-cli',
+      ...(state.hookSessionContext ? {
+        contextItems: [{ kind: 'hook', ref: 'hook://session-start/context', priority: 96, content: state.hookSessionContext }],
+      } : {}),
       beforeRequest: (preflight) => approveModelRequest(preflight, state),
       beforeTool: (request) => approveToolExecution(request, state),
       emit(event) {
@@ -793,7 +867,7 @@ export async function dispatchShellLine(line, state = {}) {
       'help', 'exit', 'quit', 'clear', 'status', 'models', 'model',
       'whoami', 'cf', 'cloudflare', 'db', 'tunnel', 'connections',
       'connect', 'usage', 'session', 'providers', 'credentials', 'cheatsheet',
-      'settings', 'logs',
+      'settings', 'logs', 'hooks', 'hook',
       'git', 'diff', 'pwd', 'cd', 'fast', 'flex', 'standard', 'reasoning',
     ];
     if (commonVerbs.includes(bare)) {
@@ -862,6 +936,22 @@ export async function dispatchShellLine(line, state = {}) {
           state.rl?.resume?.();
         }
         break;
+      case '/hooks':
+      case '/hook': {
+        const hookCommand = args[0] || 'status';
+        await runHooks(args.length ? args : ['status'], { cwd: state.cwd, write, home: state.home, hooks: state.codeHooks });
+        if (['init', 'enable', 'disable'].includes(hookCommand)) {
+          if (state.hookExperience && state.hookSessionStarted) {
+            await state.hookExperience.runtime.dispatch('session_end', {
+              status: 'reloading_hooks',
+              elapsed_ms: state.session ? localSessionElapsedMs(state.session) : 0,
+            }, { session_id: state.session?.id, source: 'agentsam-cli' }, { cwd: state.cwd });
+          }
+          state.hookExperience = null;
+          state.hookSessionStarted = false;
+        }
+        break;
+      }
       case '/providers':
         state.rl?.pause?.();
         try {
@@ -1113,6 +1203,7 @@ export async function runShell(argv = [], options = {}) {
     session: options.session || null,
     home: options.home,
     providerFetchImpl: options.providerFetchImpl,
+    codeHooks: options.hooks || null,
     persistFooter: options.persistFooter === true,
   };
   const sub = argv[0] || '';
@@ -1201,6 +1292,20 @@ export async function runShell(argv = [], options = {}) {
     restorePaste();
     state.rl = null;
   }
+  if (state.hookExperience && state.hookSessionStarted) {
+    try {
+      await state.hookExperience.runtime.dispatch('session_end', {
+        status: interrupted ? 'interrupted' : 'paused',
+        elapsed_ms: state.session ? localSessionElapsedMs(state.session) : 0,
+        cumulative_usage: state.session?.cumulative_usage || {},
+      }, {
+        session_id: state.session?.id,
+        source: 'agentsam-cli',
+      }, { cwd: state.cwd });
+    } catch (error) {
+      writeLine(write, `  Hook cleanup warning: ${error?.message || error}`);
+    }
+  }
   if (state.session) {
     const activeElapsedMs = localSessionElapsedMs(state.session);
     persistSession(state, {