hey-axi 0.2.0 → 0.3.0

package/src/errors.js

@@ -1,28 +1,91 @@
-// Turn a failed HEY run into hey-axi's error shape, keeping HEY's own error envelope
-// ({ok:false,error,code,hint,meta}, written to stderr in --json mode) when there is one.
-// HEY may print plain warning lines (e.g. about the keyring) before the envelope; those
-// are kept as `warning`. Suggestions name hey-axi commands, and when HEY gives no hint
-// a `help` line for the exit code says what to do next.
+// Turn a failed HEY run into hey-axi's error shape (AXI principle 6):
+//   - HEY's own error envelope ({ok:false,error,code,hint,meta}) is kept, with hints
+//     rewritten to name hey-axi commands
+//   - anything else is translated: one cleaned line of HEY's text (no warnings, stack
+//     frames or terminal escapes) under a hey-axi message for the failure kind
+//   - plain warning lines HEY prints first (e.g. about the keyring) go to stderr, not stdout
+//   - exit codes follow AXI: 2 for usage errors, 1 for everything else that failed
+// A `help` line always says what to do next.
 
 import { heyToAxi } from "./text.js";
 
-// HEY's exit codes (`hey help exit-codes`) → the next step for an agent.
-const NEXT_STEP = {
-  1: "Run `hey-axi <command> --help` to check the arguments",
-  2: "Check the id; list commands such as `hey-axi box view imbox` show valid ids (threads use topic_id)",
-  3: "Ask the user to run `hey auth login` in their terminal, then `hey-axi auth status`",
-  4: "This account can't do that; check `hey-axi account list` and --account",
-  5: "Rate limited by HEY: wait a minute, then retry",
-  6: "Network problem reaching HEY: check the connection, then retry",
-  7: "HEY's API returned an error: retry later, or run `hey-axi doctor`",
-  8: "More than one match: pass an exact id instead of a name",
-  127: "Install the HEY CLI (curl -fsSL https://hey.com/install-cli | bash) or set HEY_BIN",
+// HEY's exit codes (`hey help exit-codes`) → a kind, a message and the next step.
+const KINDS = {
+  1: { kind: "command_error", message: "the command failed", help: "Run `hey-axi <command> --help` to check the arguments" },
+  2: { kind: "not_found", message: "not found", help: "Check the id; list commands such as `hey-axi box view imbox` show valid ids (threads use topic_id)" },
+  3: { kind: "auth", message: "not signed in to HEY", help: "Run `hey-axi auth login --token <token>` if you have a token; otherwise ask the user to run `hey-axi auth login --interactive` in their terminal. Check with `hey-axi auth status`" },
+  4: { kind: "forbidden", message: "this account can't do that", help: "Check `hey-axi account list` and --account" },
+  5: { kind: "rate_limited", message: "rate limited by HEY", help: "Wait a minute, then retry" },
+  6: { kind: "network", message: "couldn't reach HEY", help: "Check the network connection, then retry" },
+  7: { kind: "api_error", message: "HEY's API returned an error", help: "Retry later, or run `hey-axi doctor`" },
+  8: { kind: "ambiguous", message: "more than one match", help: "Pass an exact id instead of a name" },
+  127: { kind: "hey_missing", message: "HEY CLI not found", help: "Install the HEY CLI (curl -fsSL https://hey.com/install-cli | bash) or set HEY_BIN" },
 };
 
-function withHelp(failure) {
-  if (failure.hint) failure.hint = heyToAxi(failure.hint);
-  else if (NEXT_STEP[failure.exit_code]) failure.help = NEXT_STEP[failure.exit_code];
-  return failure;
+const USAGE_CODES = new Set(["usage", "invalid_argument", "invalid_flag", "validation"]);
+
+// AXI exit code for a failed HEY run.
+export function axiExitCode(status, code) {
+  if (status === 0) return 0;
+  if (USAGE_CODES.has(code)) return 2;
+  return 1;
+}
+
+const ANSI = /\u001b\[[0-9;?]*[ -/]*[@-~]/g;
+const NOISE = /^(warning:|panic:|fatal error:|\[signal |runtime error|\s+at |goroutine \d|\s*[\w./-]+\.go:\d+|exit status \d+$|\[\w+\]\s)/i;
+
+// The one line of HEY's plain-text output worth showing an agent.
+// Programming-language errors from inside HEY or its libraries say nothing an agent can
+// act on: they are dropped, and the failure's own message (by kind) stands alone.
+const INTERNAL = /^(Uncaught )?(TypeError|ReferenceError|SyntaxError|RangeError|InternalError|AssertionError|panic|fatal|runtime error|invalid memory address|nil pointer|unexpected end of JSON|json: |SIGSEGV)\b/i;
+// Low-level network codes become plain words.
+const NETWORK = [
+  [/\bECONNRESET\b/, "the connection was reset"], [/\bECONNREFUSED\b/, "the connection was refused"],
+  [/\bETIMEDOUT\b|\bi\/o timeout\b|context deadline exceeded/i, "the request timed out"], [/\bENOTFOUND\b|no such host/i, "the server name could not be resolved"],
+  [/\bEAI_AGAIN\b/, "DNS lookup failed"], [/\bcertificate\b|\bx509\b|\bTLS\b/i, "a TLS/certificate problem"],
+];
+
+export function cleanLine(text) {
+  const lines = String(text || "").replace(ANSI, "").split(/\r?\n/).map((line) => line.trimEnd()).filter((line) => line.trim() && !NOISE.test(line));
+  if (!lines.length) return "";
+  let line = lines[0].trim().replace(/^(error|Error|ERROR):\s*/, "");
+  const network = NETWORK.find(([pattern]) => pattern.test(line));
+  if (network) return network[1];
+  if (INTERNAL.test(line)) return "";
+  // Library prefixes ("axios:", "fetch failed:", "Get \"https://…\":") and raw URLs add nothing.
+  line = line.replace(/^(axios|undici|fetch failed|request failed|(get|post|put|patch|delete) "[^"]*"):?\s*/i, "").replace(/\bhttps?:\/\/\S+/g, "the HEY server").trim();
+  if (!line) return "";
+  return heyToAxi(line.length > 200 ? `${line.slice(0, 200)}…` : line);
+}
+
+// HEY's stderr after a successful run, minus terminal escapes and debug noise (stack
+// frames, panics): warnings and notices such as `next_page: …` stay, on stderr.
+export function warningLines(text) {
+  return String(text || "").replace(ANSI, "").split(/\r?\n/).map((line) => line.trimEnd())
+    .filter((line) => line.trim() && (/^warning:/i.test(line.trim()) || !NOISE.test(line)))
+    .map((line) => heyToAxi(line));
+}
+
+// Keys in HEY's error meta that only carry debugging detail.
+const DEBUG_KEYS = /stack|trace|backtrace|panic|goroutine|debug|caller|frames?$/i;
+
+// HEY's error meta without debugging detail: stack-like keys are dropped and
+// multi-line strings are cut to their one meaningful line.
+export function cleanMeta(value, depth = 0) {
+  if (typeof value === "string") return /[\r\n\u001b]/.test(value) || value.length > 200 ? cleanLine(value) : value;
+  if (!value || typeof value !== "object" || depth > 3) return depth > 3 ? undefined : value;
+  if (Array.isArray(value)) return value.slice(0, 20).map((item) => cleanMeta(item, depth + 1)).filter((item) => item !== undefined && item !== "");
+  const out = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (DEBUG_KEYS.test(key)) continue;
+    const cleaned = cleanMeta(item, depth + 1);
+    if (cleaned !== undefined && cleaned !== "") out[key] = cleaned;
+  }
+  return Object.keys(out).length ? out : undefined;
+}
+
+function warnings(text) {
+  return String(text || "").replace(ANSI, "").split(/\r?\n/).filter((line) => /^warning:/i.test(line.trim())).map((line) => line.trim());
 }
 
 function findEnvelope(text) {
@@ -43,19 +106,36 @@ function findEnvelope(text) {
   return null;
 }
 
-export function heyFailure(result) {
-  if (result.error) return withHelp({ ok: false, error: result.error, exit_code: result.status });
+// Returns { failure, exitCode, warnings }: the object to print, hey-axi's exit code,
+// and diagnostic lines for stderr.
+export function translateFailure(result, { path } = {}) {
+  const raw = KINDS[result.status] || KINDS[1];
+  const info = path ? { ...raw, help: raw.help.replace("<command>", path) } : raw;
+  if (result.error) {
+    return { failure: { ok: false, error: result.error, kind: info.kind, help: info.help }, exitCode: 1, warnings: [] };
+  }
   for (const text of [result.stderr, result.stdout]) {
     const found = findEnvelope(text);
     if (!found) continue;
-    const failure = { ok: false, error: found.envelope.error };
-    for (const key of ["code", "hint", "meta"]) {
-      if (found.envelope[key] !== undefined && found.envelope[key] !== "") failure[key] = found.envelope[key];
-    }
-    if (found.prefix) failure.warning = found.prefix;
-    failure.exit_code = result.status;
-    return withHelp(failure);
+    const { envelope } = found;
+    // Even HEY's own envelope is translated: one clean line, no stack frames or escapes.
+    const failure = { ok: false, error: cleanLine(String(envelope.error)) || info.message, kind: info.kind };
+    if (envelope.code !== undefined && envelope.code !== "" && envelope.code !== "unknown") failure.code = String(envelope.code);
+    const meta = envelope.meta === undefined || envelope.meta === "" ? undefined : cleanMeta(envelope.meta);
+    if (meta !== undefined) failure.meta = meta;
+    const usage = USAGE_CODES.has(envelope.code) || /^usage: /i.test(String(envelope.error));
+    if (usage) failure.kind = "usage";
+    const hint = envelope.hint ? cleanLine(String(envelope.hint)) : "";
+    if (hint && !/^Run 'hey(-axi)? --help'/.test(hint)) failure.hint = hint;
+    failure.help = usage ? `Run \`hey-axi ${path || "<command>"} --help\` for its arguments and flags` : info.help;
+    return { failure, exitCode: usage ? 2 : axiExitCode(result.status, envelope.code), warnings: warnings(found.prefix) };
   }
-  const message = (result.stderr || "").trim() || (result.stdout || "").trim() || "hey command failed";
-  return withHelp({ ok: false, error: message, exit_code: result.status });
+  const detail = cleanLine(result.stderr) || cleanLine(result.stdout);
+  const failure = { ok: false, error: detail ? `${info.message}: ${detail}` : info.message, kind: info.kind, help: info.help };
+  return { failure, exitCode: axiExitCode(result.status), warnings: [...warnings(result.stderr), ...warnings(result.stdout)] };
+}
+
+// Kept for callers that only need the object (the home view).
+export function heyFailure(result) {
+  return translateFailure(result).failure;
 }

package/src/examples.js

@@ -0,0 +1,57 @@
+// Per-command help details (AXI principle 10): every flag's default, and two or three
+// usage examples for every command. HEY's own examples come first; commands HEY gives
+// fewer than two for get examples built from their USAGE line and flags.
+
+import { heyToAxi } from "./text.js";
+import { patternsFor } from "./arity.js";
+import { LIST_FIELDS, parseField } from "./shape.js";
+import { userOnlyPaths } from "./policy.js";
+
+// "(default …)" text for one flag, including zero, false and empty defaults.
+export function flagDefault(flag) {
+  const value = flag.default;
+  if (!flag.value) return `default ${value === "true" ? "true" : "false"}`;
+  if (value === undefined || value === "" || value === "[]") return "default: none";
+  if (flag.name === "limit" && value === "0") return "default 0: no limit set, HEY returns its first page";
+  if (value === "0s") return "default 0s: no timeout";
+  return `default ${value}`;
+}
+
+const placeholder = (flag) => {
+  if (flag.type === "int") return "10";
+  if (flag.type === "duration") return "10m";
+  return `<${flag.name}>`;
+};
+
+function synthesized(node) {
+  const pattern = patternsFor(node)[0];
+  const args = (pattern?.args || []).filter((arg) => arg.required).map((arg) => `<${arg.name}>`);
+  const oneOf = pattern?.oneOf?.[0]?.[0];
+  const fromHey = (node.examples || [])[0];
+  const base = fromHey ? heyToAxi(fromHey) : ["hey-axi", node.path, ...args, ...(oneOf ? [oneOf] : [])].join(" ");
+  const out = [base];
+  const own = (node.flags || []).filter((flag) => !(pattern?.oneOf || []).flat().includes(`--${flag.name}`));
+  const valued = own.find((flag) => flag.value && !/\(required\)$/.test(flag.desc || ""));
+  const required = own.filter((flag) => /\(required\)$/.test(flag.desc || ""));
+  if (required.length && !fromHey) {
+    out[0] = `${base} ${required.map((flag) => `--${flag.name} ${placeholder(flag)}`).join(" ")}`;
+  }
+  if (valued && !out[0].includes(`--${valued.name}`)) out.push(`${out[0]} --${valued.name} ${placeholder(valued)}`);
+  const list = LIST_FIELDS[node.path];
+  if (list) out.push(`${out[0]} --fields ${list.slice(0, 2).map((spec) => parseField(spec).key).join(",")}`);
+  out.push(`${out[0]} --json`);
+  out.push(`${out[0]} --account <id>`);
+  return out;
+}
+
+// Two or three examples, HEY's own first.
+export function examplesFor(node) {
+  const examples = (node.examples || []).map(heyToAxi);
+  for (const example of synthesized(node)) {
+    if (examples.length >= 3 || (examples.length >= 2 && (node.examples || []).length >= 2)) break;
+    if (!examples.includes(example)) examples.push(example);
+  }
+  // Person-only commands run only with --interactive, so their examples say so.
+  const person = userOnlyPaths().includes(node.path);
+  return examples.slice(0, 3).map((example) => (person && !/--(interactive|token|cookie)\b/.test(example) ? `${example} --interactive` : example));
+}

package/src/guide.js

@@ -1,9 +1,11 @@
 // Static guidance shared by the no-args home view and the generated part of
 // skills/hey-axi/SKILL.md (scripts/gen-skill.js), so the two never drift.
 
+import { withSelectors } from "./shape.js";
+
 export const DESCRIPTION = "HEY email, calendars and todos for agents: compact TOON over Basecamp's HEY CLI; outgoing mail is saved as a draft unless --allow-send";
 
-// How many Imbox threads the home view (and the session hook) shows.
+// How many threads the home view (and the session hook) shows by default.
 export const HOME_LIMIT = 10;
 
 export const HOME_HELP = [
@@ -15,13 +17,30 @@ export const HOME_HELP = [
   "Run `hey-axi --help` for all commands; lists take --fields a,b / --fields all, long text --full",
 ];
 
+// The live home view's help: the static lines, pointed at the scope's command, with the
+// scope's --account carried into every suggestion, plus "see the rest" / --full /
+// review-drafts hints when they apply.
+export function homeHelp({ base = "hey-axi box view imbox", carry = [], more = false, total, truncated = false, drafts = false, search = false } = {}) {
+  const lines = HOME_HELP.map((line) => {
+    if (line.includes("box view imbox --limit 50")) {
+      if (!more) return `Run \`${withSelectors("hey-axi box list", carry)}\` for other boxes (feed, papertrail, aside, later)`;
+      const count = total !== undefined ? `all ${total}` : "more";
+      return search ? `Run \`${base}\` for ${count}` : `Run \`${base} --all\` for ${count} (or --limit <n>)`;
+    }
+    return line.replace(/`(hey-axi [^`]*)`/, (_, command) => (command === "hey-axi --help" ? `\`${command}\`` : `\`${withSelectors(command, carry)}\``));
+  }).filter(Boolean);
+  if (truncated) lines.push(`Run \`${base} --full\` to see complete content`);
+  if (drafts) lines.unshift(`Run \`${withSelectors("hey-axi draft list", carry)}\` to review drafts saved last session (not sent)`);
+  return lines;
+}
+
 export const SETUP_HELP = {
   missing: [
     "Install the HEY CLI: curl -fsSL https://hey.com/install-cli | bash (or brew install --cask basecamp/tap/hey)",
     "If it is installed outside PATH, set HEY_BIN=/path/to/hey",
   ],
   auth: [
-    "Ask the user to run `hey auth login` in their own terminal (it opens a browser)",
+    "Ask the user to run `hey-axi auth login --interactive` in their own terminal (it opens a browser), or run `hey-axi auth login --token <token>`",
     "Run `hey-axi auth status` to check afterwards",
   ],
   other: ["Run `hey-axi doctor` to find login and configuration problems"],

package/src/home-path.js

@@ -0,0 +1,12 @@
+// The absolute path of a file, with the user's home directory collapsed to `~`, for
+// paths shown to agents.
+import { homedir } from "node:os";
+import { resolve, sep } from "node:path";
+
+export function collapse(path, home = homedir()) {
+  if (!path) return path;
+  const absolute = resolve(path);
+  if (!home) return absolute;
+  if (absolute === home) return "~";
+  return absolute.startsWith(home.endsWith(sep) ? home : home + sep) ? `~${absolute.slice(home.replace(/[\\/]$/, "").length)}` : absolute;
+}

package/src/home.js

@@ -1,21 +1,36 @@
-// The no-args home view (AXI principles 8 and 10): who this is, then live Imbox state,
-// then the next commands. Also what the session hook prints. It never fails hard:
+// The no-args home view (AXI principles 7, 8 and 10): who this is, the directory scope,
+// live mail for that scope with its count, what the last session in this directory did,
+// then the next commands. It is also what the session hook prints. It never fails hard:
 // a missing or signed-out HEY is reported as `status` with the fix (exit 0), so a
 // session hook still gives the agent something useful.
 
-import { homedir } from "node:os";
-import { DESCRIPTION, HOME_HELP, HOME_LIMIT, SETUP_HELP } from "./guide.js";
-import { shapeData } from "./shape.js";
+import { DESCRIPTION, SETUP_HELP, homeHelp } from "./guide.js";
+import { carrySelectors, countLine, listSize, shapeData, findList } from "./shape.js";
 import { heyFailure } from "./errors.js";
 import { heyToAxi } from "./text.js";
+import { ScopeError, findScope, scopeQuery } from "./scope.js";
+import { lastSession } from "./activity.js";
+import { collapse } from "./home-path.js";
 
-export function collapse(path, home = homedir()) {
-  return path && home && path.startsWith(home) ? `~${path.slice(home.length)}` : path;
-}
+export { collapse };
 
-export async function homeView(runHey, { execPath = process.argv[1] } = {}) {
+export async function homeView(runHey, { execPath = process.argv[1], cwd = process.cwd() } = {}) {
   const out = { bin: collapse(execPath), description: DESCRIPTION };
-  const result = await runHey(["box", "view", "imbox", "--limit", String(HOME_LIMIT)], ["--json"]);
+  let scope = null;
+  try {
+    scope = findScope(cwd);
+  } catch (error) {
+    if (!(error instanceof ScopeError)) throw error;
+    out.status = error.message;
+    out.help = ["Fix or delete that file, then run `hey-axi` again", "Run `hey-axi setup scope --help` for the format"];
+    return out;
+  }
+  const query = scopeQuery(scope);
+  out.scope = query.label;
+  const previous = lastSession(scope?.dir || cwd);
+  if (previous) out.last_session = previous.line;
+
+  const result = await runHey(query.argv, ["--json"]);
   if (result.status === 127) {
     out.status = result.error || "HEY CLI not found";
     out.help = SETUP_HELP.missing;
@@ -30,6 +45,7 @@ export async function homeView(runHey, { execPath = process.argv[1] } = {}) {
       out.status = `HEY error: ${heyToAxi(failure.error)}`;
       out.help = [...(failure.hint ? [heyToAxi(failure.hint)] : []), ...SETUP_HELP.other];
     }
+    out.help = out.help.map((line) => carrySelectors(line, query.carry || []));
     return out;
   }
   let envelope;
@@ -40,11 +56,27 @@ export async function homeView(runHey, { execPath = process.argv[1] } = {}) {
     out.help = SETUP_HELP.other;
     return out;
   }
-  const { data, empty } = shapeData(envelope.data, { path: "box view" });
-  const threads = Array.isArray(data) ? data : data?.postings;
-  out.imbox = envelope.summary || `${threads?.length ?? 0} threads`;
-  if (empty || !threads?.length) out.imbox = "0 threads: the Imbox is empty";
-  else out.threads = threads;
-  out.help = HOME_HELP;
+  const body = envelope && typeof envelope === "object" && "data" in envelope ? envelope.data : envelope;
+  const found = findList(body);
+  const size = listSize(envelope, found ? found.list.length : 0, found?.container);
+  // search has no --limit: keep the first `limit` rows here.
+  if (found && found.list.length > query.limit) {
+    // More rows than shown, but no total unless HEY gave one.
+    size.more = true;
+  }
+  const { data, truncated } = shapeData(body, { path: query.path });
+  let threads = Array.isArray(data) ? data : data?.[found?.key];
+  if (threads && threads.length > query.limit) threads = threads.slice(0, query.limit);
+  size.shown = threads?.length ?? 0;
+  if (!threads?.length && (size.more || size.total > 0)) {
+    // An empty page while HEY reports more: say exactly that, not "nothing".
+    out.count = countLine(size);
+    out.mail = `0 threads on this page; HEY reports ${size.total > 0 ? `${size.total} in total` : "more"}`;
+  } else if (!threads?.length) out.mail = `0 threads: nothing in ${query.label.split(" (")[0]}`;
+  else {
+    out.count = countLine(size);
+    out.threads = threads;
+  }
+  out.help = homeHelp({ base: query.base, carry: query.carry, more: size.more, total: size.total, truncated, drafts: previous?.drafts > 0, search: query.path === "search" });
   return out;
 }

package/src/hooks.js

@@ -1,32 +1,40 @@
-// `hey-axi setup hooks`: register the no-args home view as session-start context for
-// Claude Code, Codex and OpenCode (AXI principle 7), using axi-sdk-js's hook installer.
-// Only this explicit command writes agent config; nothing else ever does.
+// `hey-axi setup hooks`: register hey-axi in the agent session lifecycle for Claude Code,
+// Codex and OpenCode (AXI principle 7). Only this explicit command writes agent config;
+// nothing else ever does.
+//   - session start: the no-args home view (via axi-sdk-js's hook installer)
+//   - session end:   `hey-axi hook session-end`, which folds what hey-axi did this
+//                    session into the summary the next home view shows (src/activity.js)
 //
 //   hey-axi setup hooks              install or repair (user scope: ~/.claude, ~/.codex, ~/.config/opencode)
 //   hey-axi setup hooks --project    the same, for the current directory (.claude/, .codex/, .opencode/)
 //   hey-axi setup hooks --status     report only, no writes
 //   hey-axi setup hooks --remove     remove hey-axi's managed hooks (other hooks are left alone)
 
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { collapse } from "./home.js";
+import { dirname, join, resolve } from "node:path";
+import { collapse } from "./home-path.js";
+import { disableCapture, enableCapture } from "./activity.js";
 
 const MARKER = "hey-axi";
 export const HOOK_FLAGS = ["--project", "--status", "--remove", "--help", "-h"];
+const END_ARGS = "hook session-end";
+const END_PLUGIN_MARKER = "hey-axi managed opencode session-end plugin";
 
 export const HOOKS_HELP = [
-  "hey-axi setup hooks — show the hey-axi home view (Imbox summary + next commands) at the start of every agent session",
+  "hey-axi setup hooks — show the hey-axi home view at the start of every agent session, and remember what each session did",
   "",
   "usage: hey-axi setup hooks [--project] [--status | --remove]",
   "",
   "flags:",
-  "  --project   target this directory (.claude/settings.json, .codex/hooks.json, .opencode/plugins/) instead of your user config",
-  "  --status    report what is installed; writes nothing",
-  "  --remove    remove hey-axi's managed hooks; other hooks are left alone",
+  "  --project   target this directory (.claude/settings.json, .codex/hooks.json, .opencode/plugins/) instead of your user config (default: user config)",
+  "  --status    report what is installed; writes nothing (default false)",
+  "  --remove    remove hey-axi's managed hooks and its session journal; other hooks are left alone (default false: install or repair)",
   "",
-  "agents: Claude Code (SessionStart hook), Codex (SessionStart hook; also sets [features].hooks = true in ~/.codex/config.toml), OpenCode (managed plugin)",
+  "agents: Claude Code (SessionStart + SessionEnd hooks), Codex (SessionStart + SessionEnd hooks; also sets [features].hooks = true in ~/.codex/config.toml), OpenCode (managed plugins)",
+  "Session end: hey-axi keeps a local journal of what it did (command names and numeric ids only) and the next session's home view summarizes it (e.g. drafts waiting to be reviewed).",
   "Re-running is a no-op when nothing changed, and repairs the command path after hey-axi moves.",
-  "Note: the hook puts Imbox senders and subjects into every session's context. Use --project to limit it to one directory.",
+  "Note: the start hook puts subjects and senders from the directory's scope into every session's context. `hey-axi setup scope` narrows it; --project limits it to one directory.",
   "",
   "examples:",
   "  hey-axi setup hooks",
@@ -38,16 +46,144 @@ function snapshot(paths) {
   return paths.map((path) => (existsSync(path) ? readFileSync(path, "utf8") : null));
 }
 
-function describe(status) {
+function readJson(path) {
+  return existsSync(path) ? JSON.parse(readFileSync(path, "utf8")) : {};
+}
+
+const isMine = (hook) => typeof hook?.command === "string" && hook.command.includes(MARKER) && hook.command.endsWith(END_ARGS);
+
+function endTargets(scope, root, home) {
+  return {
+    claude: join(root, ".claude", "settings.json"),
+    codex: join(root, ".codex", "hooks.json"),
+    opencode: join(scope === "project" ? join(root, ".opencode", "plugins") : join(home, ".config", "opencode", "plugins"), "axi-hey-axi-session-end.js"),
+  };
+}
+
+// The command the start hook runs (portable name or absolute path, chosen by axi-sdk-js).
+function startCommand(paths) {
+  for (const path of paths) {
+    try {
+      for (const group of readJson(path).hooks?.SessionStart || []) {
+        for (const hook of group.hooks || []) if (typeof hook.command === "string" && hook.command.includes(MARKER)) return hook.command;
+      }
+    } catch {
+      // unreadable config: try the next one
+    }
+  }
+  return null;
+}
+
+function setEndHook(path, command, onError) {
+  try {
+    const settings = readJson(path);
+    settings.hooks ||= {};
+    const groups = Array.isArray(settings.hooks.SessionEnd) ? settings.hooks.SessionEnd : [];
+    const wanted = { type: "command", command, timeout: 5 };
+    let found = false;
+    for (const group of groups) {
+      for (const hook of group.hooks || []) {
+        if (!isMine(hook)) continue;
+        found = true;
+        Object.assign(hook, wanted);
+      }
+    }
+    if (!found) groups.push({ hooks: [wanted] });
+    settings.hooks.SessionEnd = groups;
+    const next = `${JSON.stringify(settings, null, 2)}\n`;
+    if (!existsSync(path) || readFileSync(path, "utf8") !== next) {
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, next);
+    }
+  } catch (error) {
+    onError(`${path}: ${error.message}`);
+  }
+}
+
+function removeEndHook(path, onError) {
+  try {
+    if (!existsSync(path)) return;
+    const settings = readJson(path);
+    const groups = settings.hooks?.SessionEnd;
+    if (!Array.isArray(groups)) return;
+    const kept = groups.map((group) => ({ ...group, hooks: (group.hooks || []).filter((hook) => !isMine(hook)) })).filter((group) => group.hooks.length);
+    if (kept.length === groups.length && kept.every((group, index) => group.hooks.length === groups[index].hooks.length)) return;
+    if (kept.length) settings.hooks.SessionEnd = kept;
+    else delete settings.hooks.SessionEnd;
+    writeFileSync(path, `${JSON.stringify(settings, null, 2)}\n`);
+  } catch (error) {
+    onError(`${path}: ${error.message}`);
+  }
+}
+
+function hasEndHook(path) {
+  try {
+    return (readJson(path).hooks?.SessionEnd || []).some((group) => (group.hooks || []).some(isMine));
+  } catch {
+    return false;
+  }
+}
+
+function openCodeEndPlugin(command) {
+  return `// ${END_PLUGIN_MARKER}
+// Generated by \`hey-axi setup hooks\`. \`hey-axi setup hooks --remove\` deletes it.
+import { spawn } from "node:child_process";
+
+const command = ${JSON.stringify(command)};
+
+function capture(directory, sessionID) {
+  return new Promise((resolve) => {
+    const child = spawn(command, ["hook", "session-end"], { cwd: directory || process.cwd(), shell: false, stdio: ["pipe", "ignore", "ignore"] });
+    const timer = setTimeout(() => child.kill("SIGTERM"), 5000);
+    child.on("error", () => { clearTimeout(timer); resolve(); });
+    child.on("close", () => { clearTimeout(timer); resolve(); });
+    child.stdin.end(JSON.stringify({ session_id: sessionID, cwd: directory }));
+  });
+}
+
+export const HeyAxiSessionEndPlugin = async ({ directory }) => ({
+  event: async ({ event }) => {
+    const idle = event.type === "session.idle" || (event.type === "session.status" && event.properties?.status?.type === "idle");
+    if (idle || event.type === "session.deleted") await capture(directory, event.properties?.sessionID ?? event.properties?.info?.id);
+  },
+});
+`;
+}
+
+function setEndPlugin(path, command, onError) {
+  try {
+    const next = openCodeEndPlugin(command);
+    if (existsSync(path)) {
+      const current = readFileSync(path, "utf8");
+      if (!current.includes(END_PLUGIN_MARKER)) return onError(`${path}: refusing to overwrite an unmanaged OpenCode plugin`);
+      if (current === next) return;
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, next);
+  } catch (error) {
+    onError(`${path}: ${error.message}`);
+  }
+}
+
+function removeEndPlugin(path, onError) {
+  try {
+    if (existsSync(path) && readFileSync(path, "utf8").includes(END_PLUGIN_MARKER)) rmSync(path);
+  } catch (error) {
+    onError(`${path}: ${error.message}`);
+  }
+}
+
+function describe(status, end) {
+  const state = (start, finish) => (start ? `installed ${finish ? "with" : "without"} session end` : finish ? "not installed (session end only)" : "not installed");
   return {
-    claude: `${status.claude.installed ? "installed" : "not installed"} (${collapse(status.claude.path)})`,
-    codex: `${status.codex.installed ? "installed" : "not installed"} (${collapse(status.codex.path)}; hooks feature ${status.codex.userFeatureEnabled ? "on" : "off"} in ${collapse(status.codex.userFeaturePath)})`,
-    opencode: `${status.opencode.installed ? "installed" : "not installed"} (${collapse(status.opencode.path)})`,
+    claude: `${state(status.claude.installed, hasEndHook(end.claude))} (${collapse(status.claude.path)})`,
+    codex: `${state(status.codex.installed, hasEndHook(end.codex))} (${collapse(status.codex.path)}; hooks feature ${status.codex.userFeatureEnabled ? "on" : "off"} in ${collapse(status.codex.userFeaturePath)})`,
+    opencode: `${state(status.opencode.installed, existsSync(end.opencode))} (${collapse(status.opencode.path)})`,
   };
 }
 
 // Returns { output, code }.
-export async function setupHooks(flags, { execPath = process.argv[1] } = {}) {
+export async function setupHooks(flags, { execPath = process.argv[1], cwd = process.cwd(), home = homedir() } = {}) {
   const unknown = [...flags].filter((flag) => !HOOK_FLAGS.includes(flag));
   if (unknown.length) {
     return { code: 2, output: { ok: false, error: `unknown flag ${unknown.join(", ")} for \`setup hooks\``, help: "valid flags for `setup hooks`: --project, --status, --remove" } };
@@ -57,19 +193,27 @@ export async function setupHooks(flags, { execPath = process.argv[1] } = {}) {
   }
   const sdk = await import("axi-sdk-js");
   const scope = flags.has("--project") ? "project" : "user";
-  const options = { marker: MARKER, scope, projectDir: process.cwd(), homeDir: homedir() };
+  const root = scope === "project" ? resolve(cwd) : home;
+  const options = { marker: MARKER, scope, projectDir: cwd, homeDir: home };
+  const end = endTargets(scope, root, home);
   const before = sdk.sessionStartHookStatus(options);
-  const files = [before.claude.path, before.codex.path, before.codex.userFeaturePath, before.opencode.path];
+  const files = [before.claude.path, before.codex.path, before.codex.userFeaturePath, before.opencode.path, end.opencode];
   const errors = [];
   const onError = (message) => errors.push(message);
 
   if (flags.has("--status")) {
-    return { code: 0, output: { hooks: `status (${scope} scope)`, ...describe(before) } };
+    return { code: 0, output: { hooks: `status (${scope} scope)`, ...describe(before, end) } };
   }
 
   const was = snapshot(files);
+  let captureChanged = false;
   if (flags.has("--remove")) {
     sdk.uninstallSessionStartHooks({ ...options, onError });
+    removeEndHook(end.claude, onError);
+    removeEndHook(end.codex, onError);
+    removeEndPlugin(end.opencode, onError);
+    const otherScope = sdk.sessionStartHookStatus({ ...options, scope: scope === "project" ? "user" : "project" });
+    if (!otherScope.claude.installed && !otherScope.codex.installed && !otherScope.opencode.installed) captureChanged = disableCapture();
   } else {
     sdk.installSessionStartHooks({
       ...options,
@@ -78,16 +222,25 @@ export async function setupHooks(flags, { execPath = process.argv[1] } = {}) {
       distEntrypoints: ["src/hey-axi.js"],
       onError,
     });
+    const command = startCommand([before.claude.path, before.codex.path]);
+    if (command) {
+      // Claude Code and Codex run hook commands through a shell: quote a path with spaces.
+      const shellCommand = /\s/.test(command) && existsSync(command) ? `'${command.replace(/'/g, "'\\''")}'` : command;
+      setEndHook(end.claude, `${shellCommand} ${END_ARGS}`, onError);
+      setEndHook(end.codex, `${shellCommand} ${END_ARGS}`, onError);
+      setEndPlugin(end.opencode, command, onError);
+      captureChanged = enableCapture();
+    }
   }
   const after = sdk.sessionStartHookStatus(options);
-  const changed = snapshot(files).some((content, index) => content !== was[index]);
-  const verb = flags.has("--remove") ? (changed ? "removed" : "nothing to remove") : changed ? "installed or updated" : "already up to date (no changes)";
-  const output = { hooks: `${verb} (${scope} scope)`, ...describe(after) };
+  const changed = captureChanged || snapshot(files).some((content, index) => content !== was[index]);
+  const verb = flags.has("--remove") ? (changed ? "removed" : "nothing to remove (no-op)") : changed ? "installed or updated" : "already up to date (no changes)";
+  const output = { hooks: `${verb} (${scope} scope)`, ...describe(after, end) };
   if (!flags.has("--remove") && !after.claude.installed && !after.codex.installed && !after.opencode.installed) {
     output.ok = false;
     output.error = "no hook was installed";
   }
   if (errors.length) output.errors = errors;
-  if (!flags.has("--remove")) output.help = ["Start a new agent session to see the home view", "Run `hey-axi setup hooks --remove` to undo"];
+  if (!flags.has("--remove")) output.help = ["Start a new agent session to see the home view", "Run `hey-axi setup scope --label <name>` to focus this directory", "Run `hey-axi setup hooks --remove` to undo"];
   return { code: errors.length || output.ok === false ? 1 : 0, output };
 }