@inneranimalmedia/agentsam-sdk 2.6.8 → 2.6.10

package/src/commands/machine.js

@@ -2,7 +2,9 @@
  * agentsam machine — deterministic native Machine lifecycle + perception.
  */
 
+import os from 'node:os';
 import path from 'node:path';
+import pc from 'picocolors';
 import { resolveMachineBinary, spawnMachine } from './machine-binary.js';
 import {
   installManagedMachine,
@@ -12,23 +14,35 @@ import {
 } from './machine-runtime.js';
 
 function usage() {
-  return 'agentsam machine — deterministic local perception (native engine)\n\n' +
-    'Usage:\n' +
-    '  agentsam machine status [--json]\n' +
-    '  agentsam machine doctor [--json]\n' +
-    '  agentsam machine install [--version <semver>] [--force] [--json]\n' +
-    '  agentsam machine update [--force] [--json]\n' +
-    '  agentsam machine inspect <path> [--json] [--run-id <id>] [--include-generated]\n' +
-    '  agentsam machine --help\n\n' +
-    'Runtime authority:\n' +
-    '  AgentSam manages one user-level Machine runtime under ~/.agentsam/runtimes/machine/.\n' +
-    '  Every repository uses that managed runtime first; PATH and SDK source are fallbacks only.\n' +
-    '  Install/update are explicit and never run merely because you entered a repository.\n\n' +
-    'Notes:\n' +
-    '  Default inspect is read-only and network-free.\n' +
-    '  Large detail is externalized under <target>/.agentsam/machine/runs/<run_id>/.\n' +
-    '  Generated/cache trees are summarized unless --include-generated is set.\n' +
-    '  Current registry distribution uses crates.io and therefore requires Cargo for install/update.\n';
+  return [
+    `${pc.bold('agentsam machine')} — deterministic local perception (native engine)`,
+    '',
+    pc.bold('Usage'),
+    `  ${pc.cyan('agentsam machine status')}                         Show the active runtime`,
+    `  ${pc.cyan('agentsam machine doctor')}                         Diagnose runtime resolution`,
+    `  ${pc.cyan('agentsam machine install')} [--version <semver>]   Install the managed runtime`,
+    `  ${pc.cyan('agentsam machine update')}                        Update the managed runtime`,
+    `  ${pc.cyan('agentsam machine inspect <path>')}                Inspect a repository or directory`,
+    '',
+    pc.bold('Options'),
+    `  ${pc.dim('--json')}                  Machine-readable output`,
+    `  ${pc.dim('--force')}                 Replace an existing managed version`,
+    `  ${pc.dim('--run-id <id>')}           Reuse an externalized inspection run`,
+    `  ${pc.dim('--include-generated')}    Include generated and cache trees`,
+    `  ${pc.dim('--help')}                 Show this help`,
+    '',
+    pc.bold('Runtime authority'),
+    '  AgentSam manages one user-level Machine runtime under ~/.agentsam/runtimes/machine/.',
+    '  Resolution order: managed runtime → explicit override → PATH → SDK source.',
+    '  Install and update are explicit; entering a repository never changes the host.',
+    '',
+    pc.bold('Behavior'),
+    '  Inspect is read-only and network-free by default.',
+    '  Large detail is externalized under <target>/.agentsam/machine/runs/<run_id>/.',
+    '  Generated and cache trees are summarized unless --include-generated is set.',
+    '  Install/update use the crates.io distribution and require Cargo.',
+    '',
+  ].join('\n');
 }
 
 function parseArgs(argv = []) {
@@ -86,44 +100,63 @@ function statusPayload() {
   };
 }
 
+function compactPath(value) {
+  const raw = String(value || '—');
+  const home = os.homedir();
+  return home && (raw === home || raw.startsWith(home + path.sep))
+    ? '~' + raw.slice(home.length)
+    : raw;
+}
+
+function stateLabel(installed) {
+  return installed ? pc.green('installed') : pc.yellow('not installed');
+}
+
 function printTextStatus(payload) {
-  console.log('AgentSam Machine');
+  const managed = payload.managed;
+  const effective = payload.effective;
+  console.log(pc.bold('AgentSam Machine'));
+  console.log(pc.dim('Deterministic local perception · native runtime'));
+  console.log('');
+  console.log(pc.bold('Managed runtime'));
+  console.log(`  status       ${stateLabel(managed.installed)}`);
+  console.log(`  version      ${managed.current_version || pc.dim('—')}`);
+  console.log(`  runtime      ${compactPath(managed.runtime_root)}`);
+  console.log(`  binary       ${compactPath(managed.binary)}`);
   console.log('');
-  console.log('  managed      ' + (payload.managed.installed ? 'installed' : 'not installed'));
-  console.log('  version      ' + (payload.managed.current_version || '—'));
-  console.log('  binary       ' + (payload.managed.binary || '—'));
-  console.log('  runtime      ' + payload.managed.runtime_root);
-  console.log('  effective    ' + payload.effective.source);
-  console.log('  effective v  ' + (payload.effective.version || 'unknown'));
-  console.log('  cargo        ' + (payload.managed.cargo.available ? payload.managed.cargo.path : 'not found'));
-  if (!payload.managed.installed) {
+  console.log(pc.bold('Active resolution'));
+  console.log(`  source       ${effective.source || pc.dim('unavailable')}`);
+  console.log(`  version      ${effective.version || pc.dim('unknown')}`);
+  console.log(`  cargo        ${managed.cargo.available ? compactPath(managed.cargo.path) : pc.dim('not found')}`);
+  if (!managed.installed) {
     console.log('');
-    console.log('  Run agentsam machine install to adopt the user-managed runtime.');
+    console.log(`  ${pc.yellow('Next step')}  agentsam machine install`);
   }
 }
 
 function printTextDoctor(payload) {
   printTextStatus(payload);
   console.log('');
+  console.log(pc.bold('Doctor'));
   if (payload.effective.kind === 'missing') {
-    console.log('  ✕ Machine unavailable');
-    console.log('  tried        ' + (payload.effective.tried || []).join(', '));
+    console.log(`  ${pc.red('✕')} Machine unavailable`);
+    console.log(`    tried      ${(payload.effective.tried || []).map(compactPath).join(', ') || pc.dim('none')}`);
   } else if (payload.managed.installed) {
-    console.log('  ✓ managed Machine runtime is available');
+    console.log(`  ${pc.green('✓')} Managed Machine runtime is available`);
   } else {
-    console.log('  ○ Machine works through fallback source: ' + payload.effective.source);
-    console.log('  ○ install the managed runtime to make resolution consistent across repositories');
+    console.log(`  ${pc.yellow('○')} Fallback runtime is active: ${payload.effective.source}`);
+    console.log('    install the managed runtime for consistent resolution across repositories');
   }
 }
 
 function printInstallResult(action, result) {
-  console.log('AgentSam Machine ' + action);
+  console.log(pc.bold(`AgentSam Machine · ${action}`));
   console.log('');
-  console.log('  version      ' + result.version);
-  console.log('  binary       ' + result.binary);
-  console.log('  alias        ' + result.alias);
-  console.log('  source       ' + result.source);
-  console.log('  changed      ' + (result.changed ? 'yes' : 'no'));
+  console.log(`  ${pc.green('✓')} Runtime ${result.changed ? 'installed' : 'already current'}`);
+  console.log(`  version      ${result.version}`);
+  console.log(`  source       ${result.source}`);
+  console.log(`  binary       ${compactPath(result.binary)}`);
+  console.log(`  alias        ${compactPath(result.alias)}`);
 }
 
 export async function runMachine(argv = []) {

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/package.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { execFile, spawnSync } from 'node:child_process';
 import { promisify } from 'node:util';
 import { fileURLToPath } from 'node:url';
+import { findCliProjectRoot } from '../lib/cli-preferences.js';
 
 const execFileAsync = promisify(execFile);
 const SDK_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
@@ -403,6 +404,10 @@ function parseArgs(argv) {
   return { positional, flags };
 }
 
+export function resolvePackageRoot(cwd = process.cwd()) {
+  return findCliProjectRoot(cwd);
+}
+
 function printHelp() {
   console.log(`agentsam package — audit and graduate distributable packages
 
@@ -474,6 +479,7 @@ export async function runPackage(argv = []) {
   const sub = positional[0];
   const json = flags.has('--json');
   const offline = flags.has('--offline');
+  const root = resolvePackageRoot(process.cwd());
 
   if (!sub || flags.has('--help') || flags.has('-h')) {
     printHelp();
@@ -482,6 +488,7 @@ export async function runPackage(argv = []) {
 
   if (sub === 'audit') {
     const report = await auditPackages({
+      root,
       publicOnly: flags.has('--public'),
       offline,
     });
@@ -495,7 +502,7 @@ export async function runPackage(argv = []) {
     const name = positional[1];
     if (!name) throw new Error('package status requires a package name');
 
-    const pkg = collectPackageManifests().find((item) => item.name === name);
+    const pkg = collectPackageManifests(root).find((item) => item.name === name);
     if (!pkg) throw new Error(`Unknown @inneranimalmedia package: ${name}`);
 
     const status = classifyPackage(pkg, await registryLookup(pkg, offline));
@@ -509,7 +516,7 @@ export async function runPackage(argv = []) {
     const name = positional[1];
     if (!name) throw new Error('package verify requires a package name');
 
-    const report = await verifyPackage(name, { offline });
+    const report = await verifyPackage(name, { root, offline });
 
     if (json) console.log(JSON.stringify(report, null, 2));
     else printVerify(report);
@@ -519,7 +526,7 @@ export async function runPackage(argv = []) {
   }
 
   if (sub === 'publish-plan') {
-    const plan = await buildPublishPlan({ offline });
+    const plan = await buildPublishPlan({ root, offline });
 
     if (json) console.log(JSON.stringify(plan, null, 2));
     else printPlan(plan);

package/src/commands/runtime.js

@@ -101,6 +101,15 @@ async function probeAgentsamd() {
   }
 }
 
+async function waitForAgentsamd({ attempts = 8, delayMs = 250 } = {}) {
+  let last = await probeAgentsamd();
+  for (let attempt = 1; attempt < attempts && !last.ok; attempt += 1) {
+    await new Promise((resolve) => setTimeout(resolve, delayMs));
+    last = await probeAgentsamd();
+  }
+  return last;
+}
+
 async function startAgentsamd(home, write) {
   const bin = agentsamdPath(home);
   if (!fs.existsSync(bin)) throw new Error('agentsamd_not_installed');
@@ -109,8 +118,7 @@ async function startAgentsamd(home, write) {
     try {
       await startWindowsScheduledTask();
       writeLine(write, `  Started Scheduled Task · ${listenAddr()}`);
-      await new Promise((r) => setTimeout(r, 600));
-      return probeAgentsamd();
+      return waitForAgentsamd();
     } catch (err) {
       writeLine(write, `  ○ Scheduled Task start failed (${err.message || err}); falling back to spawn`);
     }
@@ -122,8 +130,7 @@ async function startAgentsamd(home, write) {
       const boot = await bootstrapDarwinLaunchAgent(plist);
       if (boot.ok) {
         writeLine(write, `  Loaded LaunchAgent ${DARWIN_LAUNCH_LABEL}`);
-        await new Promise((r) => setTimeout(r, 400));
-        return probeAgentsamd();
+        return waitForAgentsamd();
       }
     }
   }
@@ -138,8 +145,7 @@ async function startAgentsamd(home, write) {
   ensureRuntimeStateDir(home);
   fs.writeFileSync(pidPath(home), String(child.pid));
   writeLine(write, `  Started agentsamd pid ${child.pid} · ${listenAddr()}`);
-  await new Promise((r) => setTimeout(r, 400));
-  return probeAgentsamd();
+  return waitForAgentsamd();
 }
 
 async function stopAgentsamd(home, write) {
@@ -218,12 +224,21 @@ export async function runRuntime(argv = [], options = {}) {
         writeLine(write, `  Impl       ${probe.body.implementation}`);
       }
       writeLine(write, '');
-      writeLine(write, '  Next');
-      writeLine(write, '    agentsam setup runtime');
-      writeLine(write, '    agentsam runtime install --yes');
+      if (probe.ok) {
+        writeLine(write, sub === 'doctor' ? '  Doctor     ✓ healthy; no repair needed' : '  State      ✓ ready');
+        writeLine(write, '  Next       agentsam terminal --help');
+      } else if (facts.agentsamd.installed) {
+        writeLine(write, '  Repair');
+        writeLine(write, '    agentsam runtime start');
+        writeLine(write, '    agentsam runtime install --yes   # rebuild only if start still fails');
+      } else {
+        writeLine(write, '  Next');
+        writeLine(write, '    agentsam setup runtime');
+        writeLine(write, '    agentsam runtime install --yes');
+      }
       writeLine(write, '');
     }
-    return probe.ok || facts.agentsamd.installed ? 0 : (sub === 'doctor' ? 2 : 0);
+    return sub === 'doctor' ? (probe.ok ? 0 : 2) : 0;
   }
 
   if (sub === 'probe') {

package/src/commands/setup.js

@@ -139,7 +139,7 @@ async function runSetupRuntime(argv = [], options = {}) {
   if (dryRun || !yes) {
     writeLine(write, `  Plan receipt  ${planPath}`);
     if (!yes) {
-      writeLine(write, '  Pass --yes to install agentsamd (when profile needs it) and write install receipt.');
+      writeLine(write, '  Pass --yes to apply the selected runtime profile; healthy agentsamd installs are reused.');
     }
     writeLine(write, '');
     return 0;
@@ -154,9 +154,26 @@ async function runSetupRuntime(argv = [], options = {}) {
 
   let installResult = null;
   if (recommended.target.runtime_adapter === 'agentsamd') {
-    const code = await runRuntime(['install', '--yes'], { write, home });
-    installResult = { code, adapter: 'agentsamd' };
-    if (code !== 0) return code;
+    if (plan.facts.agentsamd.installed) {
+      const doctorCode = await runRuntime(['doctor', '--json'], { write: () => {}, home });
+      if (doctorCode === 0) {
+        installResult = { code: 0, adapter: 'agentsamd', skipped: true, reason: 'already_installed_healthy' };
+        writeLine(write, '  ✓ agentsamd already installed and healthy; reusing current runtime');
+      } else {
+        const startCode = await runRuntime(['start'], { write, home });
+        if (startCode === 0) {
+          installResult = { code: 0, adapter: 'agentsamd', skipped: true, reason: 'existing_runtime_restarted' };
+        } else {
+          const code = await runRuntime(['install', '--yes'], { write, home });
+          installResult = { code, adapter: 'agentsamd', repaired: true };
+          if (code !== 0) return code;
+        }
+      }
+    } else {
+      const code = await runRuntime(['install', '--yes'], { write, home });
+      installResult = { code, adapter: 'agentsamd' };
+      if (code !== 0) return code;
+    }
   }
 
   const receiptPath = writeRuntimeInstallReceipt({
@@ -164,7 +181,12 @@ async function runSetupRuntime(argv = [], options = {}) {
     profile_id: recommended.profile.id,
     target: recommended.target,
     goap: recommended.goap,
-    install: installResult,
+    goap_execution: {
+      status: 'planned_only',
+      executed_action_ids: [],
+      pending_action_ids: recommended.goap.action_ids || [],
+    },
+    adapter_apply: installResult,
     plan_receipt: planPath,
   }, home);
 
@@ -175,7 +197,9 @@ async function runSetupRuntime(argv = [], options = {}) {
       plan,
       plan_receipt: planPath,
       install_receipt: receiptPath,
-      executed: true,
+      adapter_applied: true,
+      goap_execution: 'planned_only',
+      executed: false,
     }, null, 2) + '\n');
   }
   return 0;

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, {

package/src/commands/terminal.js

@@ -30,6 +30,21 @@ function printIdentity(identity, write) {
   write(`hw_model:  ${identity.model || 'unknown'}`);
 }
 
+function terminalUsage() {
+  return [
+    'agentsam terminal — device identity and ExecOS enrollment',
+    '',
+    'Usage:',
+    '  agentsam terminal identity [--json]',
+    '  agentsam terminal enroll --instance <id> [--endpoint <url>] [--pair] [--json]',
+    '  agentsam terminal --help',
+    '',
+    'Identity lanes:',
+    '  AGENTSAM_API_KEY      account/CLI identity used to mint enrollment',
+    '  AGENTSAM_BRIDGE_KEY   one terminal_connection credential written by --pair',
+  ].join('\n');
+}
+
 function defaultExecosEnrollBin() {
   return path.join(homedir(), 'ExecOS', 'bin', 'enroll.mjs');
 }
@@ -52,6 +67,10 @@ function pairWithExecos(enrollmentToken, options = {}) {
 
 export async function runTerminal(argv = [], options = {}) {
   const write = options.write || ((line) => console.log(line));
+  if (argv.includes('--help') || argv.includes('-h') || argv.includes('help')) {
+    write(terminalUsage());
+    return { ok: true, help: true };
+  }
   const sub = argv[0] && !argv[0].startsWith('--') ? argv[0] : 'identity';
   const json = argv.includes('--json') || options.json === true;
   const pair = argv.includes('--pair') || options.pair === true;
@@ -70,14 +89,7 @@ export async function runTerminal(argv = [], options = {}) {
   }
 
   if (sub !== 'enroll') {
-    write([
-      'Usage: agentsam terminal identity [--json]',
-      '       agentsam terminal enroll --instance <id> [--endpoint <url>] [--pair] [--json]',
-      '',
-      'Lanes:',
-      '  AGENTSAM_API_KEY      account (CLI / whoami / mint enrollment) — required for this command',
-      '  AGENTSAM_BRIDGE_KEY   one terminal_connection secret (written by --pair into ExecOS profile)',
-    ].join('\n'));
+    write(terminalUsage());
     return { ok: false, error: 'terminal_usage' };
   }
 

package/src/errors/contract.js

@@ -2,8 +2,8 @@
 import {
   ERROR_CODE,
   ERROR_REASON,
-} from '../../packages/agentsam-errors/src/vocabulary.js';
-import { canonicalCodeFromHttpStatus } from '../../packages/agentsam-errors/src/envelope.js';
+} from '@inneranimalmedia/agentsam-errors';
+import { canonicalCodeFromHttpStatus } from '@inneranimalmedia/agentsam-errors';
 
 export {
   ERROR_SCHEMA_VERSION,
@@ -15,7 +15,7 @@ export {
   ERROR_DOMAIN,
   REMEDIATION_ACTION,
   GRPC_STATUS,
-} from '../../packages/agentsam-errors/src/vocabulary.js';
+} from '@inneranimalmedia/agentsam-errors';
 
 export {
   canonicalCodeFromHttpStatus,
@@ -27,7 +27,7 @@ export {
   assertErrorEnvelope,
   serializeError,
   parseError,
-} from '../../packages/agentsam-errors/src/envelope.js';
+} from '@inneranimalmedia/agentsam-errors';
 
 // Legacy compact classifier shapes remain public here; richer envelope classifiers
 // live in packages/agentsam-errors and are available via the other adapter exports.