@contextstream/mcp-server 0.4.81 → 0.4.82

package/dist/hooks/runner.js

@@ -1,19 +1,51 @@
 #!/usr/bin/env node
+var __create = Object.create;
 var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
   get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
 }) : x)(function(x) {
   if (typeof require !== "undefined") return require.apply(this, arguments);
   throw Error('Dynamic require of "' + x + '" is not supported');
 });
-var __esm = (fn, res) => function __init() {
-  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
+};
+var __commonJS = (cb, mod) => function __require2() {
+  try {
+    return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  } catch (e) {
+    throw mod = 0, e;
+  }
 };
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
 };
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 
 // src/hooks/prompt-state.ts
 import * as fs from "node:fs";
@@ -597,14 +629,638 @@ var init_pre_tool_use = __esm({
   }
 });
 
+// node_modules/ignore/index.js
+var require_ignore = __commonJS({
+  "node_modules/ignore/index.js"(exports, module) {
+    function makeArray(subject) {
+      return Array.isArray(subject) ? subject : [subject];
+    }
+    var UNDEFINED = void 0;
+    var EMPTY = "";
+    var SPACE = " ";
+    var ESCAPE = "\\";
+    var REGEX_TEST_BLANK_LINE = /^\s+$/;
+    var REGEX_INVALID_TRAILING_BACKSLASH = /(?:[^\\]|^)\\$/;
+    var REGEX_REPLACE_LEADING_EXCAPED_EXCLAMATION = /^\\!/;
+    var REGEX_REPLACE_LEADING_EXCAPED_HASH = /^\\#/;
+    var REGEX_SPLITALL_CRLF = /\r?\n/g;
+    var REGEX_TEST_INVALID_PATH = /^\.{0,2}\/|^\.{1,2}$/;
+    var REGEX_TEST_TRAILING_SLASH = /\/$/;
+    var SLASH = "/";
+    var TMP_KEY_IGNORE = "node-ignore";
+    if (typeof Symbol !== "undefined") {
+      TMP_KEY_IGNORE = /* @__PURE__ */ Symbol.for("node-ignore");
+    }
+    var KEY_IGNORE = TMP_KEY_IGNORE;
+    var define = (object, key, value) => {
+      Object.defineProperty(object, key, { value });
+      return value;
+    };
+    var REGEX_REGEXP_RANGE = /([0-z])-([0-z])/g;
+    var RETURN_FALSE = () => false;
+    var sanitizeRange = (range) => range.replace(
+      REGEX_REGEXP_RANGE,
+      (match, from, to) => from.charCodeAt(0) <= to.charCodeAt(0) ? match : EMPTY
+    );
+    var cleanRangeBackSlash = (slashes) => {
+      const { length } = slashes;
+      return slashes.slice(0, length - length % 2);
+    };
+    var REPLACERS = [
+      [
+        // Remove BOM
+        // TODO:
+        // Other similar zero-width characters?
+        /^\uFEFF/,
+        () => EMPTY
+      ],
+      // > Trailing spaces are ignored unless they are quoted with backslash ("\")
+      [
+        // (a\ ) -> (a )
+        // (a  ) -> (a)
+        // (a ) -> (a)
+        // (a \ ) -> (a  )
+        /((?:\\\\)*?)(\\?\s+)$/,
+        (_, m1, m2) => m1 + (m2.indexOf("\\") === 0 ? SPACE : EMPTY)
+      ],
+      // Replace (\ ) with ' '
+      // (\ ) -> ' '
+      // (\\ ) -> '\\ '
+      // (\\\ ) -> '\\ '
+      [
+        /(\\+?)\s/g,
+        (_, m1) => {
+          const { length } = m1;
+          return m1.slice(0, length - length % 2) + SPACE;
+        }
+      ],
+      // Escape metacharacters
+      // which is written down by users but means special for regular expressions.
+      // > There are 12 characters with special meanings:
+      // > - the backslash \,
+      // > - the caret ^,
+      // > - the dollar sign $,
+      // > - the period or dot .,
+      // > - the vertical bar or pipe symbol |,
+      // > - the question mark ?,
+      // > - the asterisk or star *,
+      // > - the plus sign +,
+      // > - the opening parenthesis (,
+      // > - the closing parenthesis ),
+      // > - and the opening square bracket [,
+      // > - the opening curly brace {,
+      // > These special characters are often called "metacharacters".
+      [
+        /[\\$.|*+(){^]/g,
+        (match) => `\\${match}`
+      ],
+      [
+        // > a question mark (?) matches a single character
+        /(?!\\)\?/g,
+        () => "[^/]"
+      ],
+      // leading slash
+      [
+        // > A leading slash matches the beginning of the pathname.
+        // > For example, "/*.c" matches "cat-file.c" but not "mozilla-sha1/sha1.c".
+        // A leading slash matches the beginning of the pathname
+        /^\//,
+        () => "^"
+      ],
+      // replace special metacharacter slash after the leading slash
+      [
+        /\//g,
+        () => "\\/"
+      ],
+      [
+        // > A leading "**" followed by a slash means match in all directories.
+        // > For example, "**/foo" matches file or directory "foo" anywhere,
+        // > the same as pattern "foo".
+        // > "**/foo/bar" matches file or directory "bar" anywhere that is directly
+        // >   under directory "foo".
+        // Notice that the '*'s have been replaced as '\\*'
+        /^\^*\\\*\\\*\\\//,
+        // '**/foo' <-> 'foo'
+        () => "^(?:.*\\/)?"
+      ],
+      // starting
+      [
+        // there will be no leading '/'
+        //   (which has been replaced by section "leading slash")
+        // If starts with '**', adding a '^' to the regular expression also works
+        /^(?=[^^])/,
+        function startingReplacer() {
+          return !/\/(?!$)/.test(this) ? "(?:^|\\/)" : "^";
+        }
+      ],
+      // two globstars
+      [
+        // Use lookahead assertions so that we could match more than one `'/**'`
+        /\\\/\\\*\\\*(?=\\\/|$)/g,
+        // Zero, one or several directories
+        // should not use '*', or it will be replaced by the next replacer
+        // Check if it is not the last `'/**'`
+        (_, index, str) => index + 6 < str.length ? "(?:\\/[^\\/]+)*" : "\\/.+"
+      ],
+      // normal intermediate wildcards
+      [
+        // Never replace escaped '*'
+        // ignore rule '\*' will match the path '*'
+        // 'abc.*/' -> go
+        // 'abc.*'  -> skip this rule,
+        //    coz trailing single wildcard will be handed by [trailing wildcard]
+        /(^|[^\\]+)(\\\*)+(?=.+)/g,
+        // '*.js' matches '.js'
+        // '*.js' doesn't match 'abc'
+        (_, p1, p2) => {
+          const unescaped = p2.replace(/\\\*/g, "[^\\/]*");
+          return p1 + unescaped;
+        }
+      ],
+      [
+        // unescape, revert step 3 except for back slash
+        // For example, if a user escape a '\\*',
+        // after step 3, the result will be '\\\\\\*'
+        /\\\\\\(?=[$.|*+(){^])/g,
+        () => ESCAPE
+      ],
+      [
+        // '\\\\' -> '\\'
+        /\\\\/g,
+        () => ESCAPE
+      ],
+      [
+        // > The range notation, e.g. [a-zA-Z],
+        // > can be used to match one of the characters in a range.
+        // `\` is escaped by step 3
+        /(\\)?\[([^\]/]*?)(\\*)($|\])/g,
+        (match, leadEscape, range, endEscape, close) => leadEscape === ESCAPE ? `\\[${range}${cleanRangeBackSlash(endEscape)}${close}` : close === "]" ? endEscape.length % 2 === 0 ? `[${sanitizeRange(range)}${endEscape}]` : "[]" : "[]"
+      ],
+      // ending
+      [
+        // 'js' will not match 'js.'
+        // 'ab' will not match 'abc'
+        /(?:[^*])$/,
+        // WTF!
+        // https://git-scm.com/docs/gitignore
+        // changes in [2.22.1](https://git-scm.com/docs/gitignore/2.22.1)
+        // which re-fixes #24, #38
+        // > If there is a separator at the end of the pattern then the pattern
+        // > will only match directories, otherwise the pattern can match both
+        // > files and directories.
+        // 'js*' will not match 'a.js'
+        // 'js/' will not match 'a.js'
+        // 'js' will match 'a.js' and 'a.js/'
+        (match) => /\/$/.test(match) ? `${match}$` : `${match}(?=$|\\/$)`
+      ]
+    ];
+    var REGEX_REPLACE_TRAILING_WILDCARD = /(^|\\\/)?\\\*$/;
+    var MODE_IGNORE = "regex";
+    var MODE_CHECK_IGNORE = "checkRegex";
+    var UNDERSCORE = "_";
+    var TRAILING_WILD_CARD_REPLACERS = {
+      [MODE_IGNORE](_, p1) {
+        const prefix = p1 ? `${p1}[^/]+` : "[^/]*";
+        return `${prefix}(?=$|\\/$)`;
+      },
+      [MODE_CHECK_IGNORE](_, p1) {
+        const prefix = p1 ? `${p1}[^/]*` : "[^/]*";
+        return `${prefix}(?=$|\\/$)`;
+      }
+    };
+    var makeRegexPrefix = (pattern) => REPLACERS.reduce(
+      (prev, [matcher, replacer]) => prev.replace(matcher, replacer.bind(pattern)),
+      pattern
+    );
+    var isString = (subject) => typeof subject === "string";
+    var checkPattern = (pattern) => pattern && isString(pattern) && !REGEX_TEST_BLANK_LINE.test(pattern) && !REGEX_INVALID_TRAILING_BACKSLASH.test(pattern) && pattern.indexOf("#") !== 0;
+    var splitPattern = (pattern) => pattern.split(REGEX_SPLITALL_CRLF).filter(Boolean);
+    var IgnoreRule = class {
+      constructor(pattern, mark, body, ignoreCase, negative, prefix) {
+        this.pattern = pattern;
+        this.mark = mark;
+        this.negative = negative;
+        define(this, "body", body);
+        define(this, "ignoreCase", ignoreCase);
+        define(this, "regexPrefix", prefix);
+      }
+      get regex() {
+        const key = UNDERSCORE + MODE_IGNORE;
+        if (this[key]) {
+          return this[key];
+        }
+        return this._make(MODE_IGNORE, key);
+      }
+      get checkRegex() {
+        const key = UNDERSCORE + MODE_CHECK_IGNORE;
+        if (this[key]) {
+          return this[key];
+        }
+        return this._make(MODE_CHECK_IGNORE, key);
+      }
+      _make(mode, key) {
+        const str = this.regexPrefix.replace(
+          REGEX_REPLACE_TRAILING_WILDCARD,
+          // It does not need to bind pattern
+          TRAILING_WILD_CARD_REPLACERS[mode]
+        );
+        const regex = this.ignoreCase ? new RegExp(str, "i") : new RegExp(str);
+        return define(this, key, regex);
+      }
+    };
+    var createRule = ({
+      pattern,
+      mark
+    }, ignoreCase) => {
+      let negative = false;
+      let body = pattern;
+      if (body.indexOf("!") === 0) {
+        negative = true;
+        body = body.substr(1);
+      }
+      body = body.replace(REGEX_REPLACE_LEADING_EXCAPED_EXCLAMATION, "!").replace(REGEX_REPLACE_LEADING_EXCAPED_HASH, "#");
+      const regexPrefix = makeRegexPrefix(body);
+      return new IgnoreRule(
+        pattern,
+        mark,
+        body,
+        ignoreCase,
+        negative,
+        regexPrefix
+      );
+    };
+    var RuleManager = class {
+      constructor(ignoreCase) {
+        this._ignoreCase = ignoreCase;
+        this._rules = [];
+      }
+      _add(pattern) {
+        if (pattern && pattern[KEY_IGNORE]) {
+          this._rules = this._rules.concat(pattern._rules._rules);
+          this._added = true;
+          return;
+        }
+        if (isString(pattern)) {
+          pattern = {
+            pattern
+          };
+        }
+        if (checkPattern(pattern.pattern)) {
+          const rule = createRule(pattern, this._ignoreCase);
+          this._added = true;
+          this._rules.push(rule);
+        }
+      }
+      // @param {Array<string> | string | Ignore} pattern
+      add(pattern) {
+        this._added = false;
+        makeArray(
+          isString(pattern) ? splitPattern(pattern) : pattern
+        ).forEach(this._add, this);
+        return this._added;
+      }
+      // Test one single path without recursively checking parent directories
+      //
+      // - checkUnignored `boolean` whether should check if the path is unignored,
+      //   setting `checkUnignored` to `false` could reduce additional
+      //   path matching.
+      // - check `string` either `MODE_IGNORE` or `MODE_CHECK_IGNORE`
+      // @returns {TestResult} true if a file is ignored
+      test(path12, checkUnignored, mode) {
+        let ignored = false;
+        let unignored = false;
+        let matchedRule;
+        this._rules.forEach((rule) => {
+          const { negative } = rule;
+          if (unignored === negative && ignored !== unignored || negative && !ignored && !unignored && !checkUnignored) {
+            return;
+          }
+          const matched = rule[mode].test(path12);
+          if (!matched) {
+            return;
+          }
+          ignored = !negative;
+          unignored = negative;
+          matchedRule = negative ? UNDEFINED : rule;
+        });
+        const ret = {
+          ignored,
+          unignored
+        };
+        if (matchedRule) {
+          ret.rule = matchedRule;
+        }
+        return ret;
+      }
+    };
+    var throwError = (message, Ctor) => {
+      throw new Ctor(message);
+    };
+    var checkPath = (path12, originalPath, doThrow) => {
+      if (!isString(path12)) {
+        return doThrow(
+          `path must be a string, but got \`${originalPath}\``,
+          TypeError
+        );
+      }
+      if (!path12) {
+        return doThrow(`path must not be empty`, TypeError);
+      }
+      if (checkPath.isNotRelative(path12)) {
+        const r = "`path.relative()`d";
+        return doThrow(
+          `path should be a ${r} string, but got "${originalPath}"`,
+          RangeError
+        );
+      }
+      return true;
+    };
+    var isNotRelative = (path12) => REGEX_TEST_INVALID_PATH.test(path12);
+    checkPath.isNotRelative = isNotRelative;
+    checkPath.convert = (p) => p;
+    var Ignore2 = class {
+      constructor({
+        ignorecase = true,
+        ignoreCase = ignorecase,
+        allowRelativePaths = false
+      } = {}) {
+        define(this, KEY_IGNORE, true);
+        this._rules = new RuleManager(ignoreCase);
+        this._strictPathCheck = !allowRelativePaths;
+        this._initCache();
+      }
+      _initCache() {
+        this._ignoreCache = /* @__PURE__ */ Object.create(null);
+        this._testCache = /* @__PURE__ */ Object.create(null);
+      }
+      add(pattern) {
+        if (this._rules.add(pattern)) {
+          this._initCache();
+        }
+        return this;
+      }
+      // legacy
+      addPattern(pattern) {
+        return this.add(pattern);
+      }
+      // @returns {TestResult}
+      _test(originalPath, cache, checkUnignored, slices) {
+        const path12 = originalPath && checkPath.convert(originalPath);
+        checkPath(
+          path12,
+          originalPath,
+          this._strictPathCheck ? throwError : RETURN_FALSE
+        );
+        return this._t(path12, cache, checkUnignored, slices);
+      }
+      checkIgnore(path12) {
+        if (!REGEX_TEST_TRAILING_SLASH.test(path12)) {
+          return this.test(path12);
+        }
+        const slices = path12.split(SLASH).filter(Boolean);
+        slices.pop();
+        if (slices.length) {
+          const parent = this._t(
+            slices.join(SLASH) + SLASH,
+            this._testCache,
+            true,
+            slices
+          );
+          if (parent.ignored) {
+            return parent;
+          }
+        }
+        return this._rules.test(path12, false, MODE_CHECK_IGNORE);
+      }
+      _t(path12, cache, checkUnignored, slices) {
+        if (path12 in cache) {
+          return cache[path12];
+        }
+        if (!slices) {
+          slices = path12.split(SLASH).filter(Boolean);
+        }
+        slices.pop();
+        if (!slices.length) {
+          return cache[path12] = this._rules.test(path12, checkUnignored, MODE_IGNORE);
+        }
+        const parent = this._t(
+          slices.join(SLASH) + SLASH,
+          cache,
+          checkUnignored,
+          slices
+        );
+        return cache[path12] = parent.ignored ? parent : this._rules.test(path12, checkUnignored, MODE_IGNORE);
+      }
+      ignores(path12) {
+        return this._test(path12, this._ignoreCache, false).ignored;
+      }
+      createFilter() {
+        return (path12) => !this.ignores(path12);
+      }
+      filter(paths) {
+        return makeArray(paths).filter(this.createFilter());
+      }
+      // @returns {TestResult}
+      test(path12) {
+        return this._test(path12, this._testCache, true);
+      }
+    };
+    var factory = (options) => new Ignore2(options);
+    var isPathValid = (path12) => checkPath(path12 && checkPath.convert(path12), path12, RETURN_FALSE);
+    var setupWindows = () => {
+      const makePosix = (str) => /^\\\\\?\\/.test(str) || /["<>|\u0000-\u001F]+/u.test(str) ? str : str.replace(/\\/g, "/");
+      checkPath.convert = makePosix;
+      const REGEX_TEST_WINDOWS_PATH_ABSOLUTE = /^[a-z]:\//i;
+      checkPath.isNotRelative = (path12) => REGEX_TEST_WINDOWS_PATH_ABSOLUTE.test(path12) || isNotRelative(path12);
+    };
+    if (
+      // Detect `process` so that it can run in browsers.
+      typeof process !== "undefined" && process.platform === "win32"
+    ) {
+      setupWindows();
+    }
+    module.exports = factory;
+    factory.default = factory;
+    module.exports.isPathValid = isPathValid;
+    define(module.exports, /* @__PURE__ */ Symbol.for("setupWindows"), setupWindows);
+  }
+});
+
+// src/ignore.ts
+import * as fs3 from "fs";
+import * as path3 from "path";
+function isInvariantIgnoredPath(pathname) {
+  const normalized = pathname.replace(/\\/g, "/").replace(/^\.\//, "");
+  const segments = normalized.split("/").filter(Boolean);
+  if (segments.some((segment) => INVARIANT_IGNORED_DIRECTORIES.has(segment.toLowerCase()))) {
+    return true;
+  }
+  const basename2 = (segments.at(-1) || "").toLowerCase();
+  if (INVARIANT_SECRET_FILENAMES.has(basename2)) return true;
+  if (INVARIANT_SECRET_SUFFIXES.some((suffix) => basename2.endsWith(suffix))) return true;
+  return (basename2 === ".env" || basename2.startsWith(".env.")) && !ENV_TEMPLATE_ALLOWLIST.has(basename2);
+}
+function loadIgnorePatternsSync(projectRoot) {
+  const ig = (0, import_ignore.default)();
+  const patterns = [...DEFAULT_IGNORE_PATTERNS];
+  ig.add(DEFAULT_IGNORE_PATTERNS);
+  let hasUserPatterns = false;
+  for (const filename of IGNORE_FILENAMES) {
+    try {
+      const content = fs3.readFileSync(path3.join(projectRoot, filename), "utf-8");
+      const userPatterns = content.split("\n").map((line) => line.trim()).filter((line) => line && !line.startsWith("#"));
+      if (userPatterns.length > 0) {
+        ig.add(userPatterns);
+        patterns.push(...userPatterns);
+        hasUserPatterns = true;
+      }
+    } catch {
+    }
+  }
+  return {
+    ignores: (pathname) => isInvariantIgnoredPath(pathname) || ig.ignores(pathname),
+    patterns,
+    hasUserPatterns
+  };
+}
+var import_ignore, IGNORE_FILENAMES, INVARIANT_IGNORED_DIRECTORIES, INVARIANT_SECRET_FILENAMES, INVARIANT_SECRET_SUFFIXES, ENV_TEMPLATE_ALLOWLIST, DEFAULT_IGNORE_PATTERNS;
+var init_ignore = __esm({
+  "src/ignore.ts"() {
+    "use strict";
+    import_ignore = __toESM(require_ignore(), 1);
+    IGNORE_FILENAMES = [".gitignore", ".contextignore", ".contextstream/ignore"];
+    INVARIANT_IGNORED_DIRECTORIES = /* @__PURE__ */ new Set([
+      ".contextstream",
+      ".claude",
+      ".codex",
+      ".cursor",
+      ".windsurf",
+      ".roo",
+      ".kilocode",
+      ".ssh",
+      ".aws",
+      ".gnupg",
+      ".kube",
+      ".docker"
+    ]);
+    INVARIANT_SECRET_FILENAMES = /* @__PURE__ */ new Set([
+      ".npmrc",
+      ".pypirc",
+      ".netrc",
+      ".pgpass",
+      ".git-credentials",
+      "id_rsa",
+      "id_ed25519",
+      "id_ecdsa",
+      "known_hosts",
+      "credentials.json",
+      "serviceaccountkey.json",
+      "auth.json"
+    ]);
+    INVARIANT_SECRET_SUFFIXES = [".pem", ".key", ".p12", ".pfx", ".jks"];
+    ENV_TEMPLATE_ALLOWLIST = /* @__PURE__ */ new Set([
+      ".env.example",
+      ".env.sample",
+      ".env.template",
+      ".env.dist",
+      ".env.defaults"
+    ]);
+    DEFAULT_IGNORE_PATTERNS = [
+      // Version control
+      ".git/",
+      ".svn/",
+      ".hg/",
+      // ContextStream and AI editor/agent state. These directories can contain
+      // credentials, generated rules, caches, and nested worktrees.
+      ".contextstream/",
+      ".claude/",
+      ".codex/",
+      ".cursor/",
+      ".windsurf/",
+      ".roo/",
+      ".kilocode/",
+      // Package managers / dependencies
+      "node_modules/",
+      "vendor/",
+      ".pnpm/",
+      // Build outputs
+      "target/",
+      "dist/",
+      "build/",
+      "out/",
+      ".next/",
+      ".nuxt/",
+      ".svelte-kit/",
+      ".parcel-cache/",
+      ".turbo/",
+      ".gradle/",
+      ".cache/",
+      "bin/",
+      "obj/",
+      // Python
+      "__pycache__/",
+      ".pytest_cache/",
+      ".mypy_cache/",
+      "venv/",
+      ".venv/",
+      "env/",
+      ".env/",
+      // IDE
+      ".idea/",
+      ".vscode/",
+      ".vs/",
+      // Credential stores
+      ".ssh/",
+      ".aws/",
+      ".gnupg/",
+      ".kube/",
+      ".docker/",
+      // Coverage
+      "coverage/",
+      ".coverage/",
+      // Lock files
+      "package-lock.json",
+      "yarn.lock",
+      "pnpm-lock.yaml",
+      "Cargo.lock",
+      "poetry.lock",
+      "Gemfile.lock",
+      "composer.lock",
+      "*.min.js",
+      "*.min.css",
+      "*.pem",
+      "*.key",
+      "*.p12",
+      "*.pfx",
+      "*.jks",
+      ".npmrc",
+      ".pypirc",
+      ".netrc",
+      ".pgpass",
+      ".git-credentials",
+      "id_rsa",
+      "id_ed25519",
+      "id_ecdsa",
+      "credentials.json",
+      "serviceAccountKey.json",
+      "auth.json",
+      // OS files
+      ".DS_Store",
+      "Thumbs.db"
+    ];
+  }
+});
+
 // src/hooks/post-write.ts
 var post_write_exports = {};
 __export(post_write_exports, {
-  runPostWriteHook: () => runPostWriteHook
+  runPostWriteHook: () => runPostWriteHook,
+  shouldIgnoreHookPath: () => shouldIgnoreHookPath
 });
-import * as fs3 from "node:fs";
-import * as path3 from "node:path";
+import * as fs4 from "node:fs";
+import * as path4 from "node:path";
 import { homedir as homedir3 } from "node:os";
+import { execFileSync } from "node:child_process";
 function extractFilePath(input) {
   if (input.tool_input) {
     const filePath = input.tool_input.file_path || input.tool_input.notebook_path || input.tool_input.path;
@@ -629,17 +1285,17 @@ function extractCwd2(input) {
   return process.cwd();
 }
 function findLocalConfig(startDir) {
-  let currentDir = path3.resolve(startDir);
+  let currentDir = path4.resolve(startDir);
   for (let i = 0; i < 10; i++) {
-    const configPath = path3.join(currentDir, ".contextstream", "config.json");
-    if (fs3.existsSync(configPath)) {
+    const configPath = path4.join(currentDir, ".contextstream", "config.json");
+    if (fs4.existsSync(configPath)) {
       try {
-        const content = fs3.readFileSync(configPath, "utf-8");
+        const content = fs4.readFileSync(configPath, "utf-8");
         return JSON.parse(content);
       } catch {
       }
     }
-    const parentDir = path3.dirname(currentDir);
+    const parentDir = path4.dirname(currentDir);
     if (parentDir === currentDir) break;
     currentDir = parentDir;
   }
@@ -651,12 +1307,12 @@ function loadApiConfig(startDir) {
   if (apiKey) {
     return { apiUrl, apiKey };
   }
-  let currentDir = path3.resolve(startDir);
+  let currentDir = path4.resolve(startDir);
   for (let i = 0; i < 10; i++) {
-    const mcpPath = path3.join(currentDir, ".mcp.json");
-    if (fs3.existsSync(mcpPath)) {
+    const mcpPath = path4.join(currentDir, ".mcp.json");
+    if (fs4.existsSync(mcpPath)) {
       try {
-        const content = fs3.readFileSync(mcpPath, "utf-8");
+        const content = fs4.readFileSync(mcpPath, "utf-8");
         const config = JSON.parse(content);
         const csEnv = config.mcpServers?.contextstream?.env;
         if (csEnv?.CONTEXTSTREAM_API_KEY) {
@@ -669,15 +1325,15 @@ function loadApiConfig(startDir) {
       } catch {
       }
     }
-    const parentDir = path3.dirname(currentDir);
+    const parentDir = path4.dirname(currentDir);
     if (parentDir === currentDir) break;
     currentDir = parentDir;
   }
   if (!apiKey) {
-    const homeMcpPath = path3.join(homedir3(), ".mcp.json");
-    if (fs3.existsSync(homeMcpPath)) {
+    const homeMcpPath = path4.join(homedir3(), ".mcp.json");
+    if (fs4.existsSync(homeMcpPath)) {
       try {
-        const content = fs3.readFileSync(homeMcpPath, "utf-8");
+        const content = fs4.readFileSync(homeMcpPath, "utf-8");
         const config = JSON.parse(content);
         const csEnv = config.mcpServers?.contextstream?.env;
         if (csEnv?.CONTEXTSTREAM_API_KEY) {
@@ -693,15 +1349,15 @@ function loadApiConfig(startDir) {
   return { apiUrl, apiKey };
 }
 function shouldIndexFile(filePath) {
-  const ext = path3.extname(filePath).toLowerCase();
+  const ext = path4.extname(filePath).toLowerCase();
   if (!INDEXABLE_EXTENSIONS.has(ext)) {
-    const basename2 = path3.basename(filePath).toLowerCase();
+    const basename2 = path4.basename(filePath).toLowerCase();
     if (!["dockerfile", "makefile", "rakefile", "gemfile", "procfile"].includes(basename2)) {
       return false;
     }
   }
   try {
-    const stats = fs3.statSync(filePath);
+    const stats = fs4.statSync(filePath);
     if (stats.size > MAX_FILE_SIZE) {
       return false;
     }
@@ -710,8 +1366,31 @@ function shouldIndexFile(filePath) {
   }
   return true;
 }
+function shouldIgnoreHookPath(projectRoot, filePath) {
+  const root = path4.resolve(projectRoot);
+  const absolutePath = path4.resolve(filePath);
+  if (isInvariantIgnoredPath(absolutePath)) {
+    return true;
+  }
+  const relativePath = path4.relative(root, absolutePath).replace(/\\/g, "/");
+  if (!relativePath || relativePath === ".." || relativePath.startsWith("../")) {
+    return true;
+  }
+  if (loadIgnorePatternsSync(root).ignores(relativePath)) {
+    return true;
+  }
+  try {
+    execFileSync("git", ["-C", root, "check-ignore", "-q", "--", relativePath], {
+      stdio: "ignore",
+      timeout: 2e3
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
 function detectLanguage(filePath) {
-  const ext = path3.extname(filePath).toLowerCase();
+  const ext = path4.extname(filePath).toLowerCase();
   const langMap = {
     ".ts": "typescript",
     ".tsx": "typescript",
@@ -780,8 +1459,8 @@ function detectLanguage(filePath) {
   return langMap[ext] || "text";
 }
 async function indexFile(filePath, projectId, apiUrl, apiKey, projectRoot) {
-  const content = fs3.readFileSync(filePath, "utf-8");
-  const relativePath = path3.relative(projectRoot, filePath);
+  const content = fs4.readFileSync(filePath, "utf-8");
+  const relativePath = path4.relative(projectRoot, filePath);
   const payload = {
     files: [
       {
@@ -813,13 +1492,13 @@ async function indexFile(filePath, projectId, apiUrl, apiKey, projectRoot) {
   }
 }
 function findProjectRoot(filePath) {
-  let currentDir = path3.dirname(path3.resolve(filePath));
+  let currentDir = path4.dirname(path4.resolve(filePath));
   for (let i = 0; i < 10; i++) {
-    const configPath = path3.join(currentDir, ".contextstream", "config.json");
-    if (fs3.existsSync(configPath)) {
+    const configPath = path4.join(currentDir, ".contextstream", "config.json");
+    if (fs4.existsSync(configPath)) {
       return currentDir;
     }
-    const parentDir = path3.dirname(currentDir);
+    const parentDir = path4.dirname(currentDir);
     if (parentDir === currentDir) break;
     currentDir = parentDir;
   }
@@ -847,14 +1526,17 @@ async function runPostWriteHook() {
     process.exit(0);
   }
   const cwd = extractCwd2(input);
-  const absolutePath = path3.isAbsolute(filePath) ? filePath : path3.resolve(cwd, filePath);
-  if (!fs3.existsSync(absolutePath) || !shouldIndexFile(absolutePath)) {
+  const absolutePath = path4.isAbsolute(filePath) ? filePath : path4.resolve(cwd, filePath);
+  if (!fs4.existsSync(absolutePath) || !shouldIndexFile(absolutePath)) {
     process.exit(0);
   }
   const projectRoot = findProjectRoot(absolutePath);
   if (!projectRoot) {
     process.exit(0);
   }
+  if (shouldIgnoreHookPath(projectRoot, absolutePath)) {
+    process.exit(0);
+  }
   const localConfig = findLocalConfig(projectRoot);
   if (!localConfig?.project_id) {
     process.exit(0);
@@ -873,6 +1555,7 @@ var API_URL, API_KEY, ENABLED2, INDEXABLE_EXTENSIONS, MAX_FILE_SIZE, isDirectRun
 var init_post_write = __esm({
   "src/hooks/post-write.ts"() {
     "use strict";
+    init_ignore();
     API_URL = process.env.CONTEXTSTREAM_API_URL || "https://api.contextstream.io";
     API_KEY = process.env.CONTEXTSTREAM_API_KEY || "";
     ENABLED2 = process.env.CONTEXTSTREAM_POSTWRITE_ENABLED !== "false";
@@ -953,9 +1636,9 @@ var init_post_write = __esm({
 
 // src/version.ts
 import { createRequire } from "module";
-import { existsSync as existsSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2 } from "fs";
+import { existsSync as existsSync3, readFileSync as readFileSync5, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2 } from "fs";
 import { homedir as homedir4, platform } from "os";
-import { join as join4 } from "path";
+import { join as join5 } from "path";
 import { spawn } from "child_process";
 function getVersion() {
   if (typeof __CONTEXTSTREAM_VERSION__ !== "undefined" && __CONTEXTSTREAM_VERSION__) {
@@ -982,13 +1665,13 @@ function compareVersions(v1, v2) {
   return 0;
 }
 function getCacheFilePath() {
-  return join4(homedir4(), ".contextstream", "version-cache.json");
+  return join5(homedir4(), ".contextstream", "version-cache.json");
 }
 function readCache() {
   try {
     const cacheFile = getCacheFilePath();
     if (!existsSync3(cacheFile)) return null;
-    const data = JSON.parse(readFileSync4(cacheFile, "utf-8"));
+    const data = JSON.parse(readFileSync5(cacheFile, "utf-8"));
     if (Date.now() - data.checkedAt > CACHE_TTL_MS) return null;
     return data;
   } catch {
@@ -997,7 +1680,7 @@ function readCache() {
 }
 function writeCache(latestVersion) {
   try {
-    const configDir = join4(homedir4(), ".contextstream");
+    const configDir = join5(homedir4(), ".contextstream");
     if (!existsSync3(configDir)) {
       mkdirSync2(configDir, { recursive: true });
     }
@@ -1113,9 +1796,9 @@ function isAutoUpdateEnabled() {
     return false;
   }
   try {
-    const configPath = join4(homedir4(), ".contextstream", "config.json");
+    const configPath = join5(homedir4(), ".contextstream", "config.json");
     if (existsSync3(configPath)) {
-      const config = JSON.parse(readFileSync4(configPath, "utf-8"));
+      const config = JSON.parse(readFileSync5(configPath, "utf-8"));
       if (config.auto_update === false) {
         return false;
       }
@@ -1218,8 +1901,8 @@ async function runUpdate(method) {
 }
 function writeUpdateMarker(previousVersion, newVersion) {
   try {
-    const markerPath = join4(homedir4(), ".contextstream", "update-pending.json");
-    const configDir = join4(homedir4(), ".contextstream");
+    const markerPath = join5(homedir4(), ".contextstream", "update-pending.json");
+    const configDir = join5(homedir4(), ".contextstream");
     if (!existsSync3(configDir)) {
       mkdirSync2(configDir, { recursive: true });
     }
@@ -1233,9 +1916,9 @@ function writeUpdateMarker(previousVersion, newVersion) {
 }
 function checkUpdateMarker() {
   try {
-    const markerPath = join4(homedir4(), ".contextstream", "update-pending.json");
+    const markerPath = join5(homedir4(), ".contextstream", "update-pending.json");
     if (!existsSync3(markerPath)) return null;
-    const marker = JSON.parse(readFileSync4(markerPath, "utf-8"));
+    const marker = JSON.parse(readFileSync5(markerPath, "utf-8"));
     const updatedAt = new Date(marker.updatedAt);
     const hourAgo = new Date(Date.now() - 60 * 60 * 1e3);
     if (updatedAt < hourAgo) {
@@ -1252,7 +1935,7 @@ function checkUpdateMarker() {
 }
 function clearUpdateMarker() {
   try {
-    const markerPath = join4(homedir4(), ".contextstream", "update-pending.json");
+    const markerPath = join5(homedir4(), ".contextstream", "update-pending.json");
     if (existsSync3(markerPath)) {
       __require("fs").unlinkSync(markerPath);
     }
@@ -1282,17 +1965,17 @@ var user_prompt_submit_exports = {};
 __export(user_prompt_submit_exports, {
   runUserPromptSubmitHook: () => runUserPromptSubmitHook
 });
-import * as fs4 from "node:fs";
-import * as path4 from "node:path";
+import * as fs5 from "node:fs";
+import * as path5 from "node:path";
 import { homedir as homedir5 } from "node:os";
 function loadConfigFromMcpJson(cwd) {
-  let searchDir = path4.resolve(cwd);
+  let searchDir = path5.resolve(cwd);
   for (let i = 0; i < 5; i++) {
     if (!API_KEY2) {
-      const mcpPath = path4.join(searchDir, ".mcp.json");
-      if (fs4.existsSync(mcpPath)) {
+      const mcpPath = path5.join(searchDir, ".mcp.json");
+      if (fs5.existsSync(mcpPath)) {
         try {
-          const content = fs4.readFileSync(mcpPath, "utf-8");
+          const content = fs5.readFileSync(mcpPath, "utf-8");
           const config = JSON.parse(content);
           const csEnv = config.mcpServers?.contextstream?.env;
           if (csEnv?.CONTEXTSTREAM_API_KEY) {
@@ -1309,10 +1992,10 @@ function loadConfigFromMcpJson(cwd) {
       }
     }
     if (!WORKSPACE_ID || !PROJECT_ID) {
-      const csConfigPath = path4.join(searchDir, ".contextstream", "config.json");
-      if (fs4.existsSync(csConfigPath)) {
+      const csConfigPath = path5.join(searchDir, ".contextstream", "config.json");
+      if (fs5.existsSync(csConfigPath)) {
         try {
-          const content = fs4.readFileSync(csConfigPath, "utf-8");
+          const content = fs5.readFileSync(csConfigPath, "utf-8");
           const csConfig = JSON.parse(content);
           if (csConfig.workspace_id && !WORKSPACE_ID) {
             WORKSPACE_ID = csConfig.workspace_id;
@@ -1324,15 +2007,15 @@ function loadConfigFromMcpJson(cwd) {
         }
       }
     }
-    const parentDir = path4.dirname(searchDir);
+    const parentDir = path5.dirname(searchDir);
     if (parentDir === searchDir) break;
     searchDir = parentDir;
   }
   if (!API_KEY2) {
-    const homeMcpPath = path4.join(homedir5(), ".mcp.json");
-    if (fs4.existsSync(homeMcpPath)) {
+    const homeMcpPath = path5.join(homedir5(), ".mcp.json");
+    if (fs5.existsSync(homeMcpPath)) {
       try {
-        const content = fs4.readFileSync(homeMcpPath, "utf-8");
+        const content = fs5.readFileSync(homeMcpPath, "utf-8");
         const config = JSON.parse(content);
         const csEnv = config.mcpServers?.contextstream?.env;
         if (csEnv?.CONTEXTSTREAM_API_KEY) {
@@ -1348,7 +2031,7 @@ function loadConfigFromMcpJson(cwd) {
 }
 function readTranscriptFile(transcriptPath) {
   try {
-    const content = fs4.readFileSync(transcriptPath, "utf-8");
+    const content = fs5.readFileSync(transcriptPath, "utf-8");
     const lines = content.trim().split("\n");
     const messages = [];
     for (const line of lines) {
@@ -1822,9 +2505,10 @@ var init_user_prompt_submit = __esm({
     API_KEY2 = process.env.CONTEXTSTREAM_API_KEY || "";
     WORKSPACE_ID = null;
     PROJECT_ID = null;
-    REMINDER = `[CONTEXTSTREAM] On the first message in every session call mcp__contextstream__init(...), then call mcp__contextstream__context(user_message="...", save_exchange=true, session_id="<session-id>") FIRST before any other tool. On subsequent messages, default to context first. Narrow bypass is allowed only for immediate read-only ContextStream calls when prior context is fresh and no state-changing tool has run. Response contains dynamic rules, lessons, preferences.
+    REMINDER = `[CONTEXTSTREAM] On the first message in every session call mcp__contextstream__init(...), then call mcp__contextstream__context(user_message="...", save_exchange=true, session_id="<session-id>") FIRST before any other tool. On subsequent messages, default to context first. The fresh-context direct-read lane is limited to workspace list/get; memory list_*; help version/tools/auth; project list/get/index_status; and reminder list/active. Recall, decisions, searches, specific reads, writes, and indexing require context first. Fresh [GROUNDING] is the first continuation retrieval; do not immediately duplicate it with recall. Response contains dynamic rules, lessons, preferences.
 SEARCH-FIRST: Use mcp__contextstream__search(mode="auto") before Glob/Grep/Read/Explore/Task/EnterPlanMode. In planning, never use EnterPlanMode or Task(Explore) for file-by-file discovery.
 COMMON MEMORY CALLS: list docs via memory(action="list_docs"), list lessons via session(action="get_lessons"), list plans via session(action="list_plans"), list tasks/todos via memory(action="list_tasks"|"list_todos").
+HANDOFFS: A generic handoff must create entity(kind="handoff", action="create", body={title,summary,scope,next_steps}); add capsule only for a requested portable bundle/share link. HANDOFF.md or prose alone is not the canonical handoff.
 [END]`;
     FULL_REMINDER = `[CONTEXTSTREAM RULES - MANDATORY]
 
@@ -1833,7 +2517,8 @@ COMMON MEMORY CALLS: list docs via memory(action="list_docs"), list lessons via
    - Check response for: [LESSONS_WARNING], [RULES_NOTICE], preferences
    - save_exchange=true saves each conversation turn for later retrieval
    - Use a consistent session_id for the entire conversation (generate once on first message)
-   - On subsequent messages, default to context() first. Narrow bypass: immediate read-only ContextStream calls when context is fresh and no state-changing tool has run.
+   - On subsequent messages, default to context() first. Direct-read bypass is limited to workspace list/get; memory list_*; help version/tools/auth; project list/get/index_status; and reminder list/active when context is fresh and no state-changing tool has run.
+   - Fresh [GROUNDING] is the first continuation retrieval. Do not immediately duplicate sufficient grounding with session(action="recall").
 
 2. FOR CODE SEARCH: Check index status, then search appropriately
    \u2705 Use mcp__contextstream__search(mode="auto", query="...") BEFORE Glob/Grep/Read/Explore/Task/EnterPlanMode
@@ -1851,13 +2536,18 @@ COMMON MEMORY CALLS: list docs via memory(action="list_docs"), list lessons via
    \u274C DO NOT use EnterPlanMode or Task(subagent_type="Explore") for file-by-file discovery
    \u2705 For planning discovery: mcp__contextstream__search(mode="auto", query="...", output_format="paths")
 
-5. CHECK THESE from context() response:
+5. FOR HANDOFFS: Create the canonical durable handoff entity
+   \u2705 mcp__contextstream__entity(kind="handoff", action="create", body={title,summary,scope,next_steps})
+   \u2705 Add a capsule only when a portable bundle or share link is requested
+   \u274C HANDOFF.md, a scratch prompt, or prose alone is not the canonical handoff
+
+6. CHECK THESE from context() response:
    - Lessons: Past mistakes to avoid (shown as warnings)
    - Reminders: Active reminders for this project
    - Preferences: User's coding style and preferences
    - Rules: Dynamic rules matched to current task
 
-6. SKIP CONTEXTSTREAM: If user preference says "skip contextstream", use local tools instead
+7. SKIP CONTEXTSTREAM: If user preference says "skip contextstream", use local tools instead
 [END]`;
     ENHANCED_REMINDER_HEADER = `\u2B21 ContextStream \u2014 Smart Context & Memory
 
@@ -1888,17 +2578,17 @@ var pre_compact_exports = {};
 __export(pre_compact_exports, {
   runPreCompactHook: () => runPreCompactHook
 });
-import * as fs5 from "node:fs";
-import * as path5 from "node:path";
+import * as fs6 from "node:fs";
+import * as path6 from "node:path";
 import { homedir as homedir6 } from "node:os";
 function loadConfigFromMcpJson2(cwd) {
-  let searchDir = path5.resolve(cwd);
+  let searchDir = path6.resolve(cwd);
   for (let i = 0; i < 5; i++) {
     if (!API_KEY3) {
-      const mcpPath = path5.join(searchDir, ".mcp.json");
-      if (fs5.existsSync(mcpPath)) {
+      const mcpPath = path6.join(searchDir, ".mcp.json");
+      if (fs6.existsSync(mcpPath)) {
         try {
-          const content = fs5.readFileSync(mcpPath, "utf-8");
+          const content = fs6.readFileSync(mcpPath, "utf-8");
           const config = JSON.parse(content);
           const csEnv = config.mcpServers?.contextstream?.env;
           if (csEnv?.CONTEXTSTREAM_API_KEY) {
@@ -1912,10 +2602,10 @@ function loadConfigFromMcpJson2(cwd) {
       }
     }
     if (!WORKSPACE_ID2) {
-      const csConfigPath = path5.join(searchDir, ".contextstream", "config.json");
-      if (fs5.existsSync(csConfigPath)) {
+      const csConfigPath = path6.join(searchDir, ".contextstream", "config.json");
+      if (fs6.existsSync(csConfigPath)) {
         try {
-          const content = fs5.readFileSync(csConfigPath, "utf-8");
+          const content = fs6.readFileSync(csConfigPath, "utf-8");
           const csConfig = JSON.parse(content);
           if (csConfig.workspace_id) {
             WORKSPACE_ID2 = csConfig.workspace_id;
@@ -1924,15 +2614,15 @@ function loadConfigFromMcpJson2(cwd) {
         }
       }
     }
-    const parentDir = path5.dirname(searchDir);
+    const parentDir = path6.dirname(searchDir);
     if (parentDir === searchDir) break;
     searchDir = parentDir;
   }
   if (!API_KEY3) {
-    const homeMcpPath = path5.join(homedir6(), ".mcp.json");
-    if (fs5.existsSync(homeMcpPath)) {
+    const homeMcpPath = path6.join(homedir6(), ".mcp.json");
+    if (fs6.existsSync(homeMcpPath)) {
       try {
-        const content = fs5.readFileSync(homeMcpPath, "utf-8");
+        const content = fs6.readFileSync(homeMcpPath, "utf-8");
         const config = JSON.parse(content);
         const csEnv = config.mcpServers?.contextstream?.env;
         if (csEnv?.CONTEXTSTREAM_API_KEY) {
@@ -1954,7 +2644,7 @@ function parseTranscript(transcriptPath) {
   let startedAt = (/* @__PURE__ */ new Date()).toISOString();
   let firstTimestamp = true;
   try {
-    const content = fs5.readFileSync(transcriptPath, "utf-8");
+    const content = fs6.readFileSync(transcriptPath, "utf-8");
     const lines = content.split("\n");
     for (const line of lines) {
       if (!line.trim()) continue;
@@ -2155,7 +2845,7 @@ async function runPreCompactHook() {
     messages: [],
     startedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
-  if (transcriptPath && fs5.existsSync(transcriptPath)) {
+  if (transcriptPath && fs6.existsSync(transcriptPath)) {
     transcriptData = parseTranscript(transcriptPath);
   }
   let autoSaveStatus = "";
@@ -2211,17 +2901,17 @@ var post_compact_exports = {};
 __export(post_compact_exports, {
   runPostCompactHook: () => runPostCompactHook
 });
-import * as fs6 from "node:fs";
-import * as path6 from "node:path";
+import * as fs7 from "node:fs";
+import * as path7 from "node:path";
 import { homedir as homedir7 } from "node:os";
 function loadConfigFromMcpJson3(cwd) {
-  let searchDir = path6.resolve(cwd);
+  let searchDir = path7.resolve(cwd);
   for (let i = 0; i < 5; i++) {
     if (!API_KEY4) {
-      const mcpPath = path6.join(searchDir, ".mcp.json");
-      if (fs6.existsSync(mcpPath)) {
+      const mcpPath = path7.join(searchDir, ".mcp.json");
+      if (fs7.existsSync(mcpPath)) {
         try {
-          const content = fs6.readFileSync(mcpPath, "utf-8");
+          const content = fs7.readFileSync(mcpPath, "utf-8");
           const config = JSON.parse(content);
           const csEnv = config.mcpServers?.contextstream?.env;
           if (csEnv?.CONTEXTSTREAM_API_KEY) {
@@ -2235,10 +2925,10 @@ function loadConfigFromMcpJson3(cwd) {
       }
     }
     if (!WORKSPACE_ID3) {
-      const csConfigPath = path6.join(searchDir, ".contextstream", "config.json");
-      if (fs6.existsSync(csConfigPath)) {
+      const csConfigPath = path7.join(searchDir, ".contextstream", "config.json");
+      if (fs7.existsSync(csConfigPath)) {
         try {
-          const content = fs6.readFileSync(csConfigPath, "utf-8");
+          const content = fs7.readFileSync(csConfigPath, "utf-8");
           const csConfig = JSON.parse(content);
           if (csConfig.workspace_id) {
             WORKSPACE_ID3 = csConfig.workspace_id;
@@ -2247,15 +2937,15 @@ function loadConfigFromMcpJson3(cwd) {
         }
       }
     }
-    const parentDir = path6.dirname(searchDir);
+    const parentDir = path7.dirname(searchDir);
     if (parentDir === searchDir) break;
     searchDir = parentDir;
   }
   if (!API_KEY4) {
-    const homeMcpPath = path6.join(homedir7(), ".mcp.json");
-    if (fs6.existsSync(homeMcpPath)) {
+    const homeMcpPath = path7.join(homedir7(), ".mcp.json");
+    if (fs7.existsSync(homeMcpPath)) {
       try {
-        const content = fs6.readFileSync(homeMcpPath, "utf-8");
+        const content = fs7.readFileSync(homeMcpPath, "utf-8");
         const config = JSON.parse(content);
         const csEnv = config.mcpServers?.contextstream?.env;
         if (csEnv?.CONTEXTSTREAM_API_KEY) {
@@ -2428,7 +3118,7 @@ ${options.workspaceId ? `# Workspace ID: ${options.workspaceId}` : ""}
     content: content.trim() + "\n"
   };
 }
-var DEFAULT_CLAUDE_MCP_SERVER_NAME, RULES_VERSION, CONTEXTSTREAM_TOOL_NAMES, CONTEXTSTREAM_RULES_BOOTSTRAP, CONTEXTSTREAM_RULES_DYNAMIC, CONTEXTSTREAM_RULES_FULL, CONTEXTSTREAM_RULES_MINIMAL, NO_HOOKS_SUPPLEMENT, ANTIGRAVITY_SUPPLEMENT, NO_HOOKS_EDITORS, TEMPLATES;
+var DEFAULT_CLAUDE_MCP_SERVER_NAME, RULES_VERSION, CONTEXTSTREAM_TOOL_NAMES, FAST_DIRECT_READ_LANE, CANONICAL_HANDOFF_RULES, CONTEXTSTREAM_RULES_BOOTSTRAP, CONTEXTSTREAM_RULES_DYNAMIC, CONTEXTSTREAM_RULES_FULL, CONTEXTSTREAM_RULES_MINIMAL, NO_HOOKS_SUPPLEMENT, ANTIGRAVITY_SUPPLEMENT, NO_HOOKS_EDITORS, TEMPLATES;
 var init_rules_templates = __esm({
   "src/rules-templates.ts"() {
     "use strict";
@@ -2475,6 +3165,28 @@ var init_rules_templates = __esm({
       "help"
       // Actions: tools, auth, version, editor_rules, enable_bundle
     ];
+    FAST_DIRECT_READ_LANE = `
+## Fast Direct-Read Lane
+
+After the required first-session \`init(...)\` + \`context(...)\`, these exact read-only calls may run without another grounding preamble only when no state-changing tool has run since the last grounding:
+- \`workspace(action="list"|"get")\`
+- \`memory(action="list_docs"|"list_events"|"list_todos"|"list_tasks"|"list_transcripts"|"list_nodes"|"list_diagrams")\`
+- \`help(action="version"|"tools"|"auth")\`
+- \`project(action="list"|"get"|"index_status")\`
+- \`reminder(action="list"|"active")\`
+
+Do not use this lane for recall, decisions, searches, reading a specific record, media queries, or any create/update/delete/index operation; ground those with \`context(...)\` first.
+`.trim();
+    CANONICAL_HANDOFF_RULES = `
+## Canonical Agent Handoffs
+
+When the user asks to create/prepare a handoff, hand work over, or continue in another agent/session, create the durable record immediately with:
+\`entity(kind="handoff", action="create", body={title, summary, scope, next_steps})\`
+
+- Add \`to_user_id\` only when the recipient is known; never invent it.
+- If a portable bundle, capsule, or share link is requested, also create a session capsule and return both artifacts.
+- \`HANDOFF.md\`, a scratch prompt, a generic doc/event, or prose alone is not the canonical handoff. If a local file is explicitly requested, create the entity first and treat the file as an additional artifact.
+`.trim();
     CONTEXTSTREAM_RULES_BOOTSTRAP = `
 <contextstream_rules>
 | Message | Required |
@@ -2498,6 +3210,10 @@ var init_rules_templates = __esm({
 - "find media" / "search photos/videos/audio/docs" / "what's in this PDF/video/audio?" \u2192 \`media(action="search", query="...", content_types=["document"])\`
 - "index media" / "upload asset" / "read this photo/video/audio/PDF" \u2192 \`media(action="index", file_path="...", content_type="image")\` or \`media(action="index", external_url="...", content_type="document")\`
 
+${FAST_DIRECT_READ_LANE}
+
+${CANONICAL_HANDOFF_RULES}
+
 ## Skills, Docs & Lessons First
 
 Before guessing, improvising, or struggling through a workflow you do not fully know, check whether ContextStream already has guidance for it.
@@ -2527,12 +3243,12 @@ Before guessing, improvising, or struggling through a workflow you do not fully
 
 ## Past Sessions Are Queryable \u2014 USE THEM
 
-Transcripts of every prior session are captured + indexed. Before asking the user what you did last time, or re-deriving context you built together previously, check the transcript + snapshot layer.
+When \`context()\` returns fresh, relevant \`[GROUNDING]\`, read those ranked prior-work hits first. If they are sufficient, stop there\u2014do not immediately call \`session(action="recall")\` for the same request. Escalate to recall only when grounding is absent, thin, stale, off-topic, or the user explicitly requests broader history.
 
 Triggers: user says "last time"/"previous"/"yesterday"/"pick up where we left off", the task is clearly a continuation, or you're about to ask a clarifying question whose answer is likely in a prior session.
 
 Exact calls:
-- Ranked past-session context: \`session(action="recall", query="<what you're continuing>")\`
+- First explicit escalation after insufficient grounding: \`session(action="recall", query="<what you're continuing>")\`
 - Chronological list of recent sessions: \`memory(action="list_transcripts", limit=10)\`
 - Full-text search across ALL past transcripts: \`memory(action="search_transcripts", query="<keyword>")\`
 - Save a snapshot of the current session so the NEXT session can pick up: \`session(action="capture", event_type="session_snapshot", title="...", content="...")\`
@@ -2558,6 +3274,10 @@ v${RULES_VERSION}
 
 Use \`context()\` by default to get task-specific rules, lessons from past mistakes, and relevant decisions.
 
+${FAST_DIRECT_READ_LANE}
+
+${CANONICAL_HANDOFF_RULES}
+
 ---
 
 ## Why Default Context-First
@@ -3091,6 +3811,10 @@ See full documentation: https://contextstream.io/docs/mcp/tools
 **HOOKS: \`<system-reminder>\` tags contain instructions \u2014 FOLLOW THEM**
 </contextstream_protocol>
 
+${FAST_DIRECT_READ_LANE}
+
+${CANONICAL_HANDOFF_RULES}
+
 Rules Version: ${RULES_VERSION}
 
 ---
@@ -3413,7 +4137,7 @@ curl -fsSL https://contextstream.io/scripts/setup.sh | bash
 irm https://contextstream.io/scripts/setup.ps1 | iex
 \`\`\`
 
-**npm (requires Node.js 18+):**
+**npm (requires Node.js 20+):**
 \`\`\`bash
 npm install -g @contextstream/mcp-server@latest
 \`\`\`
@@ -3549,17 +4273,17 @@ var session_init_exports = {};
 __export(session_init_exports, {
   runSessionInitHook: () => runSessionInitHook
 });
-import * as fs7 from "node:fs";
-import * as path7 from "node:path";
+import * as fs8 from "node:fs";
+import * as path8 from "node:path";
 import { homedir as homedir8 } from "node:os";
 function loadConfigFromMcpJson4(cwd) {
-  let searchDir = path7.resolve(cwd);
+  let searchDir = path8.resolve(cwd);
   for (let i = 0; i < 5; i++) {
     if (!API_KEY5) {
-      const mcpPath = path7.join(searchDir, ".mcp.json");
-      if (fs7.existsSync(mcpPath)) {
+      const mcpPath = path8.join(searchDir, ".mcp.json");
+      if (fs8.existsSync(mcpPath)) {
         try {
-          const content = fs7.readFileSync(mcpPath, "utf-8");
+          const content = fs8.readFileSync(mcpPath, "utf-8");
           const config = JSON.parse(content);
           const csEnv = config.mcpServers?.contextstream?.env;
           if (csEnv?.CONTEXTSTREAM_API_KEY) {
@@ -3576,10 +4300,10 @@ function loadConfigFromMcpJson4(cwd) {
       }
     }
     if (!WORKSPACE_ID4 || !PROJECT_ID2) {
-      const csConfigPath = path7.join(searchDir, ".contextstream", "config.json");
-      if (fs7.existsSync(csConfigPath)) {
+      const csConfigPath = path8.join(searchDir, ".contextstream", "config.json");
+      if (fs8.existsSync(csConfigPath)) {
         try {
-          const content = fs7.readFileSync(csConfigPath, "utf-8");
+          const content = fs8.readFileSync(csConfigPath, "utf-8");
           const csConfig = JSON.parse(content);
           if (csConfig.workspace_id && !WORKSPACE_ID4) {
             WORKSPACE_ID4 = csConfig.workspace_id;
@@ -3591,15 +4315,15 @@ function loadConfigFromMcpJson4(cwd) {
         }
       }
     }
-    const parentDir = path7.dirname(searchDir);
+    const parentDir = path8.dirname(searchDir);
     if (parentDir === searchDir) break;
     searchDir = parentDir;
   }
   if (!API_KEY5) {
-    const homeMcpPath = path7.join(homedir8(), ".mcp.json");
-    if (fs7.existsSync(homeMcpPath)) {
+    const homeMcpPath = path8.join(homedir8(), ".mcp.json");
+    if (fs8.existsSync(homeMcpPath)) {
       try {
-        const content = fs7.readFileSync(homeMcpPath, "utf-8");
+        const content = fs8.readFileSync(homeMcpPath, "utf-8");
         const config = JSON.parse(content);
         const csEnv = config.mcpServers?.contextstream?.env;
         if (csEnv?.CONTEXTSTREAM_API_KEY) {
@@ -3737,10 +4461,10 @@ function regenerateRuleFiles(folderPath) {
   for (const editor of editors) {
     const rule = generateRuleContent(editor, { mode: "bootstrap" });
     if (!rule) continue;
-    const filePath = path7.join(folderPath, rule.filename);
-    if (!fs7.existsSync(filePath)) continue;
+    const filePath = path8.join(folderPath, rule.filename);
+    if (!fs8.existsSync(filePath)) continue;
     try {
-      const existing = fs7.readFileSync(filePath, "utf8");
+      const existing = fs8.readFileSync(filePath, "utf8");
       const startIdx = existing.indexOf(CONTEXTSTREAM_START_MARKER);
       const endIdx = existing.indexOf(CONTEXTSTREAM_END_MARKER);
       if (startIdx === -1 || endIdx === -1 || endIdx <= startIdx) continue;
@@ -3750,7 +4474,7 @@ function regenerateRuleFiles(folderPath) {
 ${rule.content.trim()}
 ${CONTEXTSTREAM_END_MARKER}`;
       const merged = [before, newBlock, after].filter((p) => p.length > 0).join("\n\n");
-      fs7.writeFileSync(filePath, merged.trim() + "\n", "utf8");
+      fs8.writeFileSync(filePath, merged.trim() + "\n", "utf8");
       updated++;
     } catch {
     }
@@ -3823,12 +4547,12 @@ var init_session_init = __esm({
 });
 
 // src/hooks/common.ts
-import * as fs8 from "node:fs";
-import * as path8 from "node:path";
+import * as fs9 from "node:fs";
+import * as path9 from "node:path";
 import { homedir as homedir9 } from "node:os";
 function readHookInput() {
   try {
-    return JSON.parse(fs8.readFileSync(0, "utf8"));
+    return JSON.parse(fs9.readFileSync(0, "utf8"));
   } catch {
     return {};
   }
@@ -3857,13 +4581,13 @@ function loadHookConfig(cwd) {
   let jwt = process.env.CONTEXTSTREAM_JWT || "";
   let workspaceId = process.env.CONTEXTSTREAM_WORKSPACE_ID || null;
   let projectId = process.env.CONTEXTSTREAM_PROJECT_ID || null;
-  let searchDir = path8.resolve(cwd);
+  let searchDir = path9.resolve(cwd);
   for (let i = 0; i < 6; i++) {
     if (!apiKey && !jwt) {
-      const mcpPath = path8.join(searchDir, ".mcp.json");
-      if (fs8.existsSync(mcpPath)) {
+      const mcpPath = path9.join(searchDir, ".mcp.json");
+      if (fs9.existsSync(mcpPath)) {
         try {
-          const config = JSON.parse(fs8.readFileSync(mcpPath, "utf8"));
+          const config = JSON.parse(fs9.readFileSync(mcpPath, "utf8"));
           const env = config.mcpServers?.contextstream?.env;
           if (env?.CONTEXTSTREAM_API_KEY) apiKey = env.CONTEXTSTREAM_API_KEY;
           if (env?.CONTEXTSTREAM_JWT) jwt = env.CONTEXTSTREAM_JWT;
@@ -3875,25 +4599,25 @@ function loadHookConfig(cwd) {
       }
     }
     if (!workspaceId || !projectId) {
-      const localConfigPath = path8.join(searchDir, ".contextstream", "config.json");
-      if (fs8.existsSync(localConfigPath)) {
+      const localConfigPath = path9.join(searchDir, ".contextstream", "config.json");
+      if (fs9.existsSync(localConfigPath)) {
         try {
-          const localConfig = JSON.parse(fs8.readFileSync(localConfigPath, "utf8"));
+          const localConfig = JSON.parse(fs9.readFileSync(localConfigPath, "utf8"));
           if (localConfig.workspace_id && !workspaceId) workspaceId = localConfig.workspace_id;
           if (localConfig.project_id && !projectId) projectId = localConfig.project_id;
         } catch {
         }
       }
     }
-    const parentDir = path8.dirname(searchDir);
+    const parentDir = path9.dirname(searchDir);
     if (parentDir === searchDir) break;
     searchDir = parentDir;
   }
   if (!apiKey && !jwt) {
-    const homeMcpPath = path8.join(homedir9(), ".mcp.json");
-    if (fs8.existsSync(homeMcpPath)) {
+    const homeMcpPath = path9.join(homedir9(), ".mcp.json");
+    if (fs9.existsSync(homeMcpPath)) {
       try {
-        const config = JSON.parse(fs8.readFileSync(homeMcpPath, "utf8"));
+        const config = JSON.parse(fs9.readFileSync(homeMcpPath, "utf8"));
         const env = config.mcpServers?.contextstream?.env;
         if (env?.CONTEXTSTREAM_API_KEY) apiKey = env.CONTEXTSTREAM_API_KEY;
         if (env?.CONTEXTSTREAM_JWT) jwt = env.CONTEXTSTREAM_JWT;
@@ -4098,17 +4822,17 @@ var session_end_exports = {};
 __export(session_end_exports, {
   runSessionEndHook: () => runSessionEndHook
 });
-import * as fs9 from "node:fs";
-import * as path9 from "node:path";
+import * as fs10 from "node:fs";
+import * as path10 from "node:path";
 import { homedir as homedir10 } from "node:os";
 function loadConfigFromMcpJson5(cwd) {
-  let searchDir = path9.resolve(cwd);
+  let searchDir = path10.resolve(cwd);
   for (let i = 0; i < 5; i++) {
     if (!API_KEY6) {
-      const mcpPath = path9.join(searchDir, ".mcp.json");
-      if (fs9.existsSync(mcpPath)) {
+      const mcpPath = path10.join(searchDir, ".mcp.json");
+      if (fs10.existsSync(mcpPath)) {
         try {
-          const content = fs9.readFileSync(mcpPath, "utf-8");
+          const content = fs10.readFileSync(mcpPath, "utf-8");
           const config = JSON.parse(content);
           const csEnv = config.mcpServers?.contextstream?.env;
           if (csEnv?.CONTEXTSTREAM_API_KEY) {
@@ -4122,10 +4846,10 @@ function loadConfigFromMcpJson5(cwd) {
       }
     }
     if (!WORKSPACE_ID5 || !PROJECT_ID3) {
-      const csConfigPath = path9.join(searchDir, ".contextstream", "config.json");
-      if (fs9.existsSync(csConfigPath)) {
+      const csConfigPath = path10.join(searchDir, ".contextstream", "config.json");
+      if (fs10.existsSync(csConfigPath)) {
         try {
-          const content = fs9.readFileSync(csConfigPath, "utf-8");
+          const content = fs10.readFileSync(csConfigPath, "utf-8");
           const csConfig = JSON.parse(content);
           if (csConfig.workspace_id && !WORKSPACE_ID5) {
             WORKSPACE_ID5 = csConfig.workspace_id;
@@ -4137,15 +4861,15 @@ function loadConfigFromMcpJson5(cwd) {
         }
       }
     }
-    const parentDir = path9.dirname(searchDir);
+    const parentDir = path10.dirname(searchDir);
     if (parentDir === searchDir) break;
     searchDir = parentDir;
   }
   if (!API_KEY6) {
-    const homeMcpPath = path9.join(homedir10(), ".mcp.json");
-    if (fs9.existsSync(homeMcpPath)) {
+    const homeMcpPath = path10.join(homedir10(), ".mcp.json");
+    if (fs10.existsSync(homeMcpPath)) {
       try {
-        const content = fs9.readFileSync(homeMcpPath, "utf-8");
+        const content = fs10.readFileSync(homeMcpPath, "utf-8");
         const config = JSON.parse(content);
         const csEnv = config.mcpServers?.contextstream?.env;
         if (csEnv?.CONTEXTSTREAM_API_KEY) {
@@ -4168,11 +4892,11 @@ function parseTranscriptStats(transcriptPath) {
     messages: [],
     startedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
-  if (!transcriptPath || !fs9.existsSync(transcriptPath)) {
+  if (!transcriptPath || !fs10.existsSync(transcriptPath)) {
     return stats;
   }
   try {
-    const content = fs9.readFileSync(transcriptPath, "utf-8");
+    const content = fs10.readFileSync(transcriptPath, "utf-8");
     const lines = content.split("\n");
     let firstTimestamp = null;
     let lastTimestamp = null;
@@ -4473,8 +5197,8 @@ var post_tool_use_failure_exports = {};
 __export(post_tool_use_failure_exports, {
   runPostToolUseFailureHook: () => runPostToolUseFailureHook
 });
-import * as fs10 from "node:fs";
-import * as path10 from "node:path";
+import * as fs11 from "node:fs";
+import * as path11 from "node:path";
 import { homedir as homedir11 } from "node:os";
 function extractErrorText(input) {
   return typeof input.error === "string" && input.error || typeof input.tool_error === "string" && input.tool_error || typeof input.stderr === "string" && input.stderr || "Tool execution failed";
@@ -4486,13 +5210,13 @@ function failureFingerprint(toolName, errorText) {
 function incrementFailureCounter(fingerprint) {
   let counters = {};
   try {
-    counters = JSON.parse(fs10.readFileSync(FAILURE_COUNTERS_FILE, "utf8"));
+    counters = JSON.parse(fs11.readFileSync(FAILURE_COUNTERS_FILE, "utf8"));
   } catch {
     counters = {};
   }
   counters[fingerprint] = (counters[fingerprint] || 0) + 1;
-  fs10.mkdirSync(path10.dirname(FAILURE_COUNTERS_FILE), { recursive: true });
-  fs10.writeFileSync(FAILURE_COUNTERS_FILE, JSON.stringify(counters, null, 2), "utf8");
+  fs11.mkdirSync(path11.dirname(FAILURE_COUNTERS_FILE), { recursive: true });
+  fs11.writeFileSync(FAILURE_COUNTERS_FILE, JSON.stringify(counters, null, 2), "utf8");
   return counters[fingerprint];
 }
 async function runPostToolUseFailureHook() {
@@ -4545,7 +5269,7 @@ var init_post_tool_use_failure = __esm({
   "src/hooks/post-tool-use-failure.ts"() {
     "use strict";
     init_common();
-    FAILURE_COUNTERS_FILE = path10.join(homedir11(), ".contextstream", "hook-failure-counts.json");
+    FAILURE_COUNTERS_FILE = path11.join(homedir11(), ".contextstream", "hook-failure-counts.json");
     isDirectRun11 = process.argv[1]?.includes("post-tool-use-failure") || process.argv[2] === "post-tool-use-failure";
     if (isDirectRun11) {
       runPostToolUseFailureHook().catch(() => process.exit(0));
@@ -4627,10 +5351,10 @@ var subagent_stop_exports = {};
 __export(subagent_stop_exports, {
   runSubagentStopHook: () => runSubagentStopHook
 });
-import * as fs11 from "node:fs";
+import * as fs12 from "node:fs";
 function parseTranscript2(transcriptPath) {
   try {
-    const content = fs11.readFileSync(transcriptPath, "utf8");
+    const content = fs12.readFileSync(transcriptPath, "utf8");
     const assistantMessages = [];
     let toolCallCount = 0;
     for (const rawLine of content.split("\n")) {
@@ -4692,7 +5416,7 @@ async function runSubagentStopHook() {
   const agentType = typeof input.agent_type === "string" && input.agent_type || typeof input.subagent_type === "string" && input.subagent_type || "unknown";
   const agentId = typeof input.agent_id === "string" && input.agent_id || "unknown";
   const transcriptPath = typeof input.agent_transcript_path === "string" && input.agent_transcript_path || typeof input.transcript_path === "string" && input.transcript_path || "";
-  const transcript = transcriptPath && fs11.existsSync(transcriptPath) ? parseTranscript2(transcriptPath) : { assistantMessages: [], toolCallCount: 0 };
+  const transcript = transcriptPath && fs12.existsSync(transcriptPath) ? parseTranscript2(transcriptPath) : { assistantMessages: [], toolCallCount: 0 };
   const summaryText = transcript.assistantMessages.join("\n\n") || typeof input.summary === "string" && input.summary || "(No assistant output found in subagent transcript.)";
   if (agentType.toLowerCase() === "plan") {
     const suppliedPlanId = typeof input.plan_id === "string" && input.plan_id || typeof input.planId === "string" && input.planId || null;