chainlesschain 0.162.34 → 0.162.36

package/src/lib/output-styles.js

@@ -0,0 +1,179 @@
+/**
+ * output-styles — Claude-Code `/output-style` parity. A named, reusable persona
+ * layered onto the agent's system prompt, so `cc agent` can act as a different
+ * kind of assistant while keeping its core coding capabilities.
+ *
+ * Styles are markdown files with frontmatter (`name`, `description`); the body
+ * is appended to the system prompt (after the base + `--append-system-prompt`).
+ * Discovered from `.chainlesschain/output-styles/` and `.claude/output-styles/`
+ * (project) + `~/.claude/output-styles/` (personal); a couple of built-ins ship
+ * so it works with no files. The active style comes from `--output-style`, then
+ * the `outputStyle` field in `.claude/settings.json`.
+ *
+ * Pure + zero-dep frontmatter parse (mirrors slash-commands — no js-yaml).
+ * `_deps` injection (fs / homedir) for tests.
+ */
+
+import fsDefault from "node:fs";
+import pathDefault from "node:path";
+import { homedir as homedirDefault } from "node:os";
+
+export const _deps = {
+  fs: fsDefault,
+  path: pathDefault,
+  homedir: homedirDefault,
+};
+
+/** Built-in styles (shadowed by a same-named file). `default` = no-op. */
+export const BUILTIN_OUTPUT_STYLES = Object.freeze({
+  default: {
+    name: "default",
+    description: "Standard coding assistant (no persona overlay).",
+    body: "",
+    builtin: true,
+  },
+  explanatory: {
+    name: "explanatory",
+    description: "Explains the reasoning and trade-offs behind changes.",
+    body: [
+      "## Output style: Explanatory",
+      "As you work, weave in brief `★ Insight` notes that explain *why* you chose",
+      "an approach and any non-obvious trade-offs, so the user learns from the",
+      "changes. Keep insights short (1–2 sentences) and tied to what you just did;",
+      "do not pad routine steps.",
+    ].join("\n"),
+    builtin: true,
+  },
+  learning: {
+    name: "learning",
+    description: "Collaborative — leaves small instructive pieces for the user.",
+    body: [
+      "## Output style: Learning",
+      "Work collaboratively. When a small, well-scoped piece of the task would be",
+      "instructive for the user to write themselves, pause and insert a",
+      "`TODO(you):` marker with a one-line explanation of what to do and why,",
+      "instead of writing that piece — then continue with the rest. Reserve this",
+      "for genuinely educational spots, not boilerplate.",
+    ].join("\n"),
+    builtin: true,
+  },
+});
+
+/** Parse `--- ... ---` frontmatter (zero-dep, camelCases keys). */
+function parseFrontmatter(content) {
+  const text = String(content || "");
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!m) return { data: {}, body: text.trim() };
+  const data = {};
+  for (const line of m[1].split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const colon = trimmed.indexOf(":");
+    if (colon <= 0) continue;
+    const key = trimmed.slice(0, colon).trim();
+    let value = trimmed.slice(colon + 1).trim();
+    value = value.replace(/^(['"])([\s\S]*)\1$/, "$2");
+    const camel = key.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    data[camel] = value;
+  }
+  return { data, body: (m[2] || "").trim() };
+}
+
+/** Directories scanned for style files (project first, then personal). */
+function styleDirs(cwd, home) {
+  const { path } = _deps;
+  return [
+    { dir: path.join(cwd, ".chainlesschain", "output-styles"), scope: "project" },
+    { dir: path.join(cwd, ".claude", "output-styles"), scope: "project" },
+    { dir: path.join(home, ".claude", "output-styles"), scope: "personal" },
+  ];
+}
+
+/** Discover all styles: built-ins + files (a file shadows a built-in by name). */
+export function discoverOutputStyles(cwd = process.cwd(), opts = {}) {
+  const { fs, path } = _deps;
+  const home = opts.home || _deps.homedir();
+  const byName = new Map();
+  for (const b of Object.values(BUILTIN_OUTPUT_STYLES)) {
+    byName.set(b.name, { ...b });
+  }
+  // Files win over built-ins; project wins over personal (scan personal first).
+  for (const { dir, scope } of styleDirs(cwd, home).reverse()) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      if (!e.isFile() || !e.name.endsWith(".md")) continue;
+      const file = path.join(dir, e.name);
+      let content;
+      try {
+        content = fs.readFileSync(file, "utf-8");
+      } catch {
+        continue;
+      }
+      const { data, body } = parseFrontmatter(content);
+      const name = (data.name || e.name.replace(/\.md$/, "")).trim();
+      if (!name) continue;
+      byName.set(name, {
+        name,
+        description: data.description || "",
+        body,
+        scope,
+        file,
+        builtin: false,
+      });
+    }
+  }
+  return [...byName.values()];
+}
+
+/** Get one style by name (case-insensitive), or null. */
+export function getOutputStyle(name, cwd = process.cwd(), opts = {}) {
+  if (!name) return null;
+  const target = String(name).trim().toLowerCase();
+  return (
+    discoverOutputStyles(cwd, opts).find(
+      (s) => s.name.toLowerCase() === target,
+    ) || null
+  );
+}
+
+/** Read the `outputStyle` default from the settings.json hierarchy (last wins). */
+export function settingsDefaultOutputStyle(cwd = process.cwd(), opts = {}) {
+  const { fs, path } = _deps;
+  const home = opts.home || _deps.homedir();
+  const files = [
+    path.join(home, ".claude", "settings.json"),
+    path.join(cwd, ".claude", "settings.json"),
+    path.join(cwd, ".claude", "settings.local.json"),
+  ];
+  let value = null;
+  for (const f of files) {
+    try {
+      if (!fs.existsSync(f)) continue;
+      const data = JSON.parse(fs.readFileSync(f, "utf-8"));
+      if (data && typeof data.outputStyle === "string" && data.outputStyle.trim()) {
+        value = data.outputStyle.trim();
+      }
+    } catch {
+      // ignore malformed
+    }
+  }
+  return value;
+}
+
+/**
+ * Resolve the active style's body to append to the system prompt.
+ * Precedence: explicit name → settings.json `outputStyle` → none.
+ * Returns `{ name, body }` (body may be "" for `default`) or null if unresolved.
+ */
+export function resolveOutputStyle(explicitName, cwd = process.cwd(), opts = {}) {
+  const name = (explicitName || settingsDefaultOutputStyle(cwd, opts) || "").trim();
+  if (!name) return null;
+  const style = getOutputStyle(name, cwd, opts);
+  if (!style) return { name, body: "", missing: true };
+  return { name: style.name, body: style.body || "" };
+}

package/src/lib/permission-rules.cjs

@@ -0,0 +1,325 @@
+"use strict";
+
+/**
+ * permission-rules — Claude-Code `permissions.{allow,ask,deny}` rule engine.
+ *
+ * A rule is a string `Tool(pattern)` (or a bare `Tool` matching every call of
+ * that tool). `Tool` may be written with the Claude-Code umbrella name (Bash,
+ * Read, Write, Edit, WebFetch, Task, …) or this CLI's own tool name (run_shell,
+ * read_file, write_file, …) — both resolve to the same family.
+ *
+ *   Bash(git push:*)      → run_shell whose command starts with "git push"
+ *   Bash(npm run test:*)  → run_shell starting with "npm run test"
+ *   Read(./src/**)        → read_file/list_dir on a path under <cwd>/src
+ *   Edit(//etc/**)        → edit_file on an absolute path under /etc
+ *   WebFetch(domain:example.com) → web_fetch of https://example.com/…
+ *   Bash                  → every run_shell call
+ *
+ * Pure + self-contained (no glob dependency — `globToRegExp` is built in, the
+ * repo avoids pulling minimatch/picomatch). Decision precedence is
+ * deny > ask > allow; no match returns `{ decision: null }` so callers fall
+ * back to the existing risk-tier / shell-policy logic unchanged.
+ *
+ * This module only *decides*; wiring it into the agent tool loop is a separate
+ * step (so it can ship + be unit-tested in isolation).
+ */
+
+const path = require("node:path");
+const os = require("node:os");
+
+const DECISIONS = Object.freeze({
+  DENY: "deny",
+  ASK: "ask",
+  ALLOW: "allow",
+});
+
+/**
+ * Umbrella (Claude-Code) tool name → the concrete CLI tool names it covers.
+ * A rule written with either side resolves to the same family.
+ */
+const TOOL_GROUPS = Object.freeze({
+  bash: ["run_shell"],
+  read: ["read_file", "list_dir"],
+  grep: ["search_files"],
+  glob: ["search_files"],
+  write: ["write_file"],
+  edit: ["edit_file", "edit_file_hashed"],
+  webfetch: ["web_fetch"],
+  websearch: ["web_search"],
+  task: ["spawn_sub_agent"],
+  skill: ["run_skill", "list_skills"],
+  runcode: ["run_code"],
+  git: ["git"],
+  todowrite: ["todo_write"],
+});
+
+/** Tools whose match target is a shell/command string (prefix-style matching). */
+const COMMAND_TOOLS = new Set(["run_shell", "run_code", "git"]);
+/** Tools whose match target is a filesystem path. */
+const PATH_TOOLS = new Set([
+  "read_file",
+  "list_dir",
+  "search_files",
+  "write_file",
+  "edit_file",
+  "edit_file_hashed",
+]);
+/** Tools whose match target is a URL. */
+const URL_TOOLS = new Set(["web_fetch"]);
+
+/**
+ * Does a rule's tool token apply to the concrete tool being evaluated?
+ * `Bash` → run_shell; `read_file` → read_file only; unknown tokens (e.g.
+ * `mcp__srv__do`) fall back to a case-insensitive exact match.
+ */
+function toolMatches(ruleTool, actualTool) {
+  const r = String(ruleTool || "").toLowerCase();
+  const a = String(actualTool || "");
+  if (Object.prototype.hasOwnProperty.call(TOOL_GROUPS, r)) {
+    return TOOL_GROUPS[r].includes(a);
+  }
+  return r === a.toLowerCase();
+}
+
+/**
+ * Parse a rule string into `{ raw, tool, pattern }` (pattern null = bare tool
+ * rule). Returns null for a malformed/empty rule so callers can skip it.
+ */
+function parseRule(rule) {
+  const raw = String(rule || "").trim();
+  if (!raw) return null;
+  const m = raw.match(/^([A-Za-z_][\w-]*)\s*(?:\(([\s\S]*)\))?$/);
+  if (!m) return null;
+  const tool = m[1];
+  const pattern = m[2] === undefined ? null : m[2].trim();
+  return { raw, tool, pattern };
+}
+
+/** Convert a glob (`*`, `**`, `?`) into an anchored RegExp. Slash-normalized. */
+function globToRegExp(glob) {
+  const s = String(glob || "");
+  let re = "";
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (c === "*") {
+      if (s[i + 1] === "*") {
+        re += ".*";
+        i++;
+        if (s[i + 1] === "/") i++; // `**/` also matches zero segments
+      } else {
+        re += "[^/]*";
+      }
+    } else if (c === "?") {
+      re += "[^/]";
+    } else {
+      re += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+  }
+  return new RegExp("^" + re + "$");
+}
+
+/** Normalize a filesystem path to forward slashes for glob comparison. */
+function toSlash(p) {
+  return String(p || "").replace(/\\/g, "/");
+}
+
+/**
+ * Resolve the concrete value a path-pattern should be matched against, and the
+ * pattern itself, both as absolute slash-normalized strings.
+ *   ./x or x   → relative to cwd
+ *   //abs/x    → absolute (leading `//` is Claude-Code's absolute marker)
+ *   ~/x        → home
+ */
+function resolvePathPattern(pattern, cwd) {
+  let pat = String(pattern || "");
+  if (pat.startsWith("//")) {
+    pat = pat.slice(1); // `//etc/**` → `/etc/**`
+  } else if (pat.startsWith("~/") || pat === "~") {
+    pat = path.join(os.homedir(), pat.slice(1));
+  } else {
+    pat = path.resolve(cwd || process.cwd(), pat);
+  }
+  return toSlash(pat);
+}
+
+/** Extract the match target (command / path / url) for a tool's args. */
+function extractTarget(actualTool, args, cwd) {
+  const a = args || {};
+  if (COMMAND_TOOLS.has(actualTool)) {
+    return { kind: "command", value: String(a.command || "").trim() };
+  }
+  if (PATH_TOOLS.has(actualTool)) {
+    const raw = a.path || a.file_path || a.dir || a.directory || "";
+    if (!raw) return { kind: "path", value: null };
+    return {
+      kind: "path",
+      value: toSlash(path.resolve(cwd || process.cwd(), String(raw))),
+    };
+  }
+  if (URL_TOOLS.has(actualTool)) {
+    return { kind: "url", value: String(a.url || "").trim() };
+  }
+  return { kind: "none", value: null };
+}
+
+/** Match a shell command against a Claude-Code Bash-style pattern. */
+function matchCommand(pattern, command) {
+  const cmd = String(command || "").trim();
+  // `prefix:*` → starts-with prefix (CC idiom: Bash(git push:*))
+  if (pattern.endsWith(":*")) {
+    const prefix = pattern.slice(0, -2).trim();
+    return cmd === prefix || cmd.startsWith(prefix);
+  }
+  if (pattern.includes("*")) {
+    return globToRegExp(pattern).test(cmd);
+  }
+  return cmd === pattern;
+}
+
+/** Match a URL against a `domain:host` or plain glob pattern. */
+function matchUrl(pattern, url) {
+  const u = String(url || "");
+  if (pattern.startsWith("domain:")) {
+    const host = pattern.slice("domain:".length).trim();
+    let actualHost = "";
+    try {
+      actualHost = new URL(u).host;
+    } catch {
+      return false;
+    }
+    return globToRegExp(host).test(actualHost);
+  }
+  return globToRegExp(pattern).test(u);
+}
+
+/**
+ * Does `pattern` (the inside of `Tool(...)`, or null for a bare rule) match the
+ * given tool call? `null` pattern always matches.
+ */
+function matchPattern(pattern, actualTool, args, cwd) {
+  if (pattern === null) return true;
+  const target = extractTarget(actualTool, args, cwd);
+  if (target.kind === "command") {
+    return target.value ? matchCommand(pattern, target.value) : false;
+  }
+  if (target.kind === "url") {
+    return target.value ? matchUrl(pattern, target.value) : false;
+  }
+  if (target.kind === "path") {
+    if (!target.value) return false;
+    return globToRegExp(resolvePathPattern(pattern, cwd)).test(target.value);
+  }
+  // Tool has no match target but the rule specified a pattern → no match.
+  return false;
+}
+
+/**
+ * Evaluate a tool call against a ruleset.
+ *
+ * @param {object} input
+ * @param {string} input.tool            concrete tool name (run_shell, …)
+ * @param {object} [input.args]          tool arguments
+ * @param {string} [input.cwd]           base dir for relative path patterns
+ * @param {object} input.rules           { allow:[], ask:[], deny:[] } of strings
+ * @returns {{ decision: 'deny'|'ask'|'allow'|null, rule: string|null }}
+ */
+function evaluatePermissionRules({ tool, args = {}, cwd, rules } = {}) {
+  const set = rules || {};
+  const order = [
+    [DECISIONS.DENY, set.deny],
+    [DECISIONS.ASK, set.ask],
+    [DECISIONS.ALLOW, set.allow],
+  ];
+  for (const [decision, list] of order) {
+    if (!Array.isArray(list)) continue;
+    for (const entry of list) {
+      const parsed = parseRule(entry);
+      if (!parsed) continue;
+      if (!toolMatches(parsed.tool, tool)) continue;
+      if (matchPattern(parsed.pattern, tool, args, cwd)) {
+        return { decision, rule: parsed.raw };
+      }
+    }
+  }
+  return { decision: null, rule: null };
+}
+
+/** Concrete tool name → the umbrella token a suggested rule should be written
+ *  with (Claude-Code style; what users expect to see in settings.json). */
+const SUGGEST_UMBRELLA = Object.freeze({
+  run_shell: "Bash",
+  run_code: "Bash",
+  git: "git",
+  read_file: "Read",
+  list_dir: "Read",
+  search_files: "Grep",
+  write_file: "Write",
+  edit_file: "Edit",
+  edit_file_hashed: "Edit",
+  web_fetch: "WebFetch",
+  web_search: "WebSearch",
+  spawn_sub_agent: "Task",
+  run_skill: "Skill",
+  list_skills: "Skill",
+  todo_write: "TodoWrite",
+});
+
+/** Commands whose first token is a dispatcher — keep 2 tokens in the prefix. */
+const MULTI_VERB = new Set([
+  "git", "npm", "npx", "yarn", "pnpm", "docker", "kubectl", "cargo",
+  "go", "pip", "pip3", "python", "python3", "node", "dotnet", "gh", "brew",
+]);
+
+/**
+ * Suggest a sensible `allow` rule string for a tool call, for the interactive
+ * "always allow" / don't-ask-again flow. Commands → `Bash(<1-2 token prefix>:*)`;
+ * paths → `<Umbrella>(<dir>/**)`; urls → `WebFetch(domain:<host>)`; otherwise a
+ * bare tool umbrella. Returns null if nothing meaningful can be derived.
+ */
+function suggestAllowRule(tool, args = {}) {
+  const umbrella = SUGGEST_UMBRELLA[tool] || tool;
+  if (COMMAND_TOOLS.has(tool)) {
+    const cmd = String(args.command || "").trim();
+    if (!cmd) return umbrella;
+    const tokens = cmd.split(/\s+/);
+    const keep = MULTI_VERB.has(tokens[0]) && tokens.length > 1 ? 2 : 1;
+    const prefix = tokens.slice(0, keep).join(" ");
+    return `${umbrella}(${prefix}:*)`;
+  }
+  if (PATH_TOOLS.has(tool)) {
+    const raw = args.path || args.file_path || args.dir || args.directory || "";
+    if (!raw) return umbrella;
+    const slash = String(raw).replace(/\\/g, "/");
+    const dir = slash.includes("/") ? slash.slice(0, slash.lastIndexOf("/")) : ".";
+    const base = dir === "" ? "/" : dir;
+    const norm = /^(\.|\/|~)/.test(base) ? base : `./${base}`;
+    return `${umbrella}(${norm}/**)`;
+  }
+  if (URL_TOOLS.has(tool)) {
+    try {
+      return `${umbrella}(domain:${new URL(String(args.url || "")).host})`;
+    } catch {
+      return umbrella;
+    }
+  }
+  return umbrella;
+}
+
+module.exports = {
+  DECISIONS,
+  TOOL_GROUPS,
+  COMMAND_TOOLS,
+  PATH_TOOLS,
+  URL_TOOLS,
+  toolMatches,
+  parseRule,
+  globToRegExp,
+  resolvePathPattern,
+  extractTarget,
+  matchCommand,
+  matchUrl,
+  matchPattern,
+  evaluatePermissionRules,
+  suggestAllowRule,
+  SUGGEST_UMBRELLA,
+};

package/src/lib/provider-options.js

@@ -6,12 +6,19 @@
  *   1. PROVIDER_DEFAULTS[provider]      — hand-curated baseline per provider
  *   2. MODEL_INFERENCE(modelId)         — model-specific overrides (e.g. o1
  *                                         disables temperature, claude-opus
- *                                         enables extended thinking)
+ *                                         gets a larger maxTokens)
  *   3. callOverrides                    — whatever the caller passes
  *
  * Later layers win at leaf keys; objects are merged recursively, arrays are
  * replaced (not concatenated) to keep behavior predictable.
  *
+ * NOTE: extended *thinking* is NOT decided here. It is opt-in via the agent's
+ * `--thinking` flag and resolved, model-aware, by `_anthropicThinkingParams`
+ * in agent-core.js — the single source of truth. This module contributes only
+ * `maxTokens` to the Anthropic request (chatWithTools destructures just that
+ * from the merge); a stray `anthropic.thinking` here was a second, divergent
+ * config that was never read, so it has been removed.
+ *
  * @module provider-options
  */
 
@@ -21,7 +28,6 @@ export const PROVIDER_DEFAULTS = Object.freeze({
   anthropic: {
     maxTokens: 8192,
     temperature: 1.0,
-    anthropic: { thinking: { type: "disabled" } },
   },
   openai: {
     maxTokens: 4096,
@@ -66,12 +72,10 @@ export function inferModelOverrides(modelId) {
     return { temperature: undefined, reasoning: { effort: "medium" } };
   }
 
-  // Claude Opus — enable extended thinking by default (users can turn off).
+  // Claude Opus — larger default output budget. (Extended thinking is opt-in
+  // via `--thinking`, decided by `_anthropicThinkingParams`, not here.)
   if (id.includes("opus-4") || id.includes("opus-3")) {
-    return {
-      maxTokens: 16384,
-      anthropic: { thinking: { type: "enabled", budgetTokens: 8000 } },
-    };
+    return { maxTokens: 16384 };
   }
 
   // Claude Haiku — cheaper, smaller output by default.

package/src/lib/settings-hook-events.cjs

@@ -0,0 +1,102 @@
+"use strict";
+
+/**
+ * settings-hook-events — fire non-tool `.claude/settings.json` hooks
+ * (UserPromptSubmit, SessionStart, and generic observe events) that live
+ * outside the executeTool seam.
+ *
+ * Reuses the same loader (collectHooks) + JSON protocol (hook-runner). Tool
+ * hooks (PreToolUse/PostToolUse) are dispatched inline in agent-core; this is
+ * the prompt/session lifecycle half. DB-backed session hooks (session-hooks.js
+ * `fireUserPromptSubmit`) stay separate + observe-only; these settings hooks
+ * are decision-capable (block) and can inject `additionalContext`.
+ *
+ * A hook's non-block stdout becomes context to inject: a JSON
+ * `{ "additionalContext": "..." }` field, or — for convenience — plain
+ * (non-JSON) stdout text. Exit 2 / `{decision:block}` aborts the turn.
+ */
+
+const { collectHooks } = require("./settings-hooks.cjs");
+const { runHooks } = require("./hook-runner.cjs");
+
+/** Join the context emitted by the hooks that ran (additionalContext / plain stdout). */
+function aggregateContext(results) {
+  const parts = [];
+  for (const r of results || []) {
+    if (r.additionalContext) {
+      parts.push(String(r.additionalContext));
+    } else if (r.exitCode === 0 && r.stdout) {
+      const s = String(r.stdout).trim();
+      if (s && s[0] !== "{") parts.push(s); // plain stdout = context to inject
+    }
+  }
+  return parts.length > 0 ? parts.join("\n") : null;
+}
+
+/**
+ * UserPromptSubmit settings hooks. A `block`/`ask` decision aborts the turn;
+ * otherwise any emitted context is returned for the caller to inject.
+ * @returns {{ blocked:boolean, reason?:string, hook?:string, additionalContext:string|null }}
+ */
+function runUserPromptSubmitHooks(settingsHooks, { prompt, cwd, sessionId } = {}) {
+  if (!settingsHooks) return { blocked: false, additionalContext: null };
+  const matched = collectHooks(settingsHooks, "UserPromptSubmit", "");
+  if (matched.length === 0) return { blocked: false, additionalContext: null };
+  const payload = {
+    hook_event_name: "UserPromptSubmit",
+    prompt: String(prompt || ""),
+    cwd,
+    session_id: sessionId || null,
+  };
+  const outcome = runHooks(matched, payload, { cwd, event: "UserPromptSubmit" });
+  if (outcome.decision === "block" || outcome.decision === "ask") {
+    return {
+      blocked: true,
+      reason: outcome.reason,
+      hook: outcome.hook,
+      additionalContext: null,
+    };
+  }
+  return { blocked: false, additionalContext: aggregateContext(outcome.results) };
+}
+
+/**
+ * SessionStart settings hooks (observe + context injection). The `source`
+ * (startup / resume / clear) is the matcher target.
+ * @returns {{ additionalContext:string|null }}
+ */
+function runSessionStartHooks(settingsHooks, { source, cwd, sessionId } = {}) {
+  if (!settingsHooks) return { additionalContext: null };
+  const matched = collectHooks(settingsHooks, "SessionStart", source || "");
+  if (matched.length === 0) return { additionalContext: null };
+  const payload = {
+    hook_event_name: "SessionStart",
+    source: source || "startup",
+    cwd,
+    session_id: sessionId || null,
+  };
+  const outcome = runHooks(matched, payload, { cwd, event: "SessionStart" });
+  return { additionalContext: aggregateContext(outcome.results) };
+}
+
+/**
+ * Generic observe-only fire (SessionEnd / Stop / PreCompact). Returns the raw
+ * runHooks outcome so callers can read a block reason; never gates flow here.
+ */
+function runObserveHooks(settingsHooks, event, payload = {}, { cwd, matchTarget } = {}) {
+  if (!settingsHooks) return { decision: "continue", results: [] };
+  const matched = collectHooks(settingsHooks, event, matchTarget || "");
+  if (matched.length === 0) return { decision: "continue", results: [] };
+  return runHooks(
+    matched,
+    { hook_event_name: event, cwd, ...payload },
+    { cwd, event },
+  );
+}
+
+module.exports = {
+  runUserPromptSubmitHooks,
+  runSessionStartHooks,
+  runObserveHooks,
+  aggregateContext,
+};