@haposoft/cafekit 0.18.1 → 0.18.3

package/src/claude/hooks/agent.cjs

@@ -17,6 +17,7 @@ try {
 
   /** Read <runtime>/runtime.json */
   const { runtimeDirName, runtimeDir, runtimePath } = require('./lib/runtime-dir.cjs');
+  const { projectRoot } = require('./lib/project-root.cjs');
   function readRuntime(cwd) {
     try {
       const p = runtimePath(cwd, 'runtime.json');
@@ -43,20 +44,21 @@ try {
 
   const { normalizeHookPayload } = require('./lib/hook-payload.cjs');
   const payload    = normalizeHookPayload(JSON.parse(stdin));
-  // Use payload.cwd for monorepo support — subagent may run in a different dir
-  const payloadCwd = typeof payload.cwd === 'string' ? payload.cwd.trim() : '';
-  const agentCwd   = payloadCwd || process.env.PROJECT_ROOT || process.cwd();
-  const runtime    = readRuntime(agentCwd);
+  const root = projectRoot(payload);
+  // An npx install always has runtime.json; under the plugin it is optional.
+  // Loaded only under the plugin, so npx installs need no extra hook file.
+  const plugin = process.env.CLAUDE_PLUGIN_ROOT ? require('./lib/plugin-options.cjs') : null;
+  const runtime = readRuntime(root) || (plugin ? {} : null);
   if (runtime === null) process.exit(0);
 
   // Language config from runtime.json
   const thinkLang    = runtime.locale?.thinkingLanguage || '';
-  const respondLang  = runtime.locale?.responseLanguage || '';
+  const respondLang  = runtime.locale?.responseLanguage || (plugin ? plugin.pluginOption('response_language') : '');
   // Default thinking to 'en' when only response language is set
   const effectThink  = thinkLang || (respondLang ? 'en' : '');
 
   // Resolve paths from env (set by session.cjs) or runtime defaults
-  const baseDir    = agentCwd;
+  const baseDir    = root;
   const plansPath  = path.join(baseDir, runtime.paths?.plans || 'plans');
   const docsPath   = path.join(baseDir, runtime.paths?.docs  || 'docs');
   const specsPath  = path.join(baseDir, runtime.paths?.specs || 'specs');
@@ -74,10 +76,12 @@ try {
   }
 
   // Python venv (optional — if <skills>/.venv exists)
-  const venv = resolveVenv(agentCwd);
+  const venv = resolveVenv(root);
 
   lines.push('## Rules');
   lines.push(`- Specs → ${specsPath}/ | Plans → ${plansPath}/ | Docs → ${docsPath}/`);
+  lines.push('- YAGNI · KISS · DRY');
+  lines.push('- Be concise. List unresolved questions at end.');
   if (venv) {
     lines.push(`- Python in ${skillsDir()}/: use \`${venv}\``);
     lines.push('- Never use global pip install');

package/src/claude/hooks/inspect-block.cjs

@@ -15,50 +15,8 @@
 
 try {
   const fs   = require('fs');
-  const path = require('path');
-  const { execSync } = require('child_process');
-
-  // Directories that should never be read (too large / irrelevant to LLM)
-  const BLOCKED_DIRS = [
-    'node_modules', 'dist', 'build', '.next', '.nuxt', '.output',
-    '__pycache__', '.venv', 'venv',
-    'vendor', 'target',
-    '.git', 'coverage', '.nyc_output',
-  ];
-
-  // Glob patterns too broad to be useful
-  const BROAD_GLOB = [/^\*\*\/\*$/, /^\*\*\.\w+$/, /^\*\*\/\*\.\w+$/];
-
-  // Commands that are always allowed (build tools, package managers, venv)
-  const ALLOWED_CMD = /^(npm|pnpm|yarn|bun|npx|pnpx|bunx|tsc|vite|esbuild|webpack|rollup|turbo|nx|jest|vitest|eslint|prettier|go|cargo|make|mvn|gradle|dotnet|docker|kubectl|helm|python3?|pip|uv|deno|bundle|rake|php|composer|ruby|mix)\b/;
-  const VENV_EXEC   = /(^|[\/\\])\.?venv[\/\\](bin|Scripts)[\/\\]/;
-  const VENV_CREATE = /^(python3?|py)\s+.*-m\s+venv\s+|^uv\s+venv(\s|$)/;
-
-  function isAllowedCommand(cmd) {
-    const s = cmd.trim().replace(/^(\w+=\S+\s+)+/, '').replace(/^(sudo|env|time)\s+/, '').trim();
-    return ALLOWED_CMD.test(s) || VENV_EXEC.test(s) || VENV_CREATE.test(s);
-  }
-
-  function isBlockedPath(p) {
-    return p.replace(/\\/g, '/').split('/').some(seg => BLOCKED_DIRS.includes(seg));
-  }
-
-  function isBroadGlob(p) {
-    return BROAD_GLOB.some(r => r.test(p.trim()));
-  }
-
-  function extractPaths(toolName, input) {
-    const out = [];
-    if (!input) return out;
-    if (input.file_path) out.push(input.file_path);
-    if (input.path)      out.push(input.path);
-    if (input.pattern)   out.push(input.pattern);
-    if (typeof input.command === 'string') {
-      const m = input.command.match(/(?:cat|ls|find|head|tail)\s+(\S+)/g);
-      if (m) m.forEach(s => out.push(s.trim().split(/\s+/).pop()));
-    }
-    return out.filter(Boolean);
-  }
+  const { BLOCKED_DIRS, inspectInput } = require('./lib/inspect-paths.cjs');
+  const { projectRoot } = require('./lib/project-root.cjs');
 
   const { runtimeDirName, runtimeDir, runtimePath } = require('./lib/runtime-dir.cjs');
   function readRuntime(cwd) {
@@ -97,37 +55,33 @@ function denyWithReason(reason) {
   const data      = normalizeHookPayload(JSON.parse(stdin));
   const toolName  = data.tool_name  || '';
   const toolInput = data.tool_input || {};
-  const cwd       = data.cwd        || process.cwd();
-  const runtime   = readRuntime(cwd);
-
-  if (runtime.scout?.enabled === false || runtime.inspect?.enabled === false) process.exit(0);
-
-  // Allow all-permitted bash commands immediately
-  if (toolInput.command) {
-    const cmds = toolInput.command.split(/\s*(?:&&|\|\||;)\s*/).filter(Boolean);
-    if (cmds.every(c => isAllowedCommand(c))) process.exit(0);
-  }
-
-  // Broad glob check
-  if (toolInput.pattern && isBroadGlob(toolInput.pattern)) {
+  let cwd         = data.cwd        || process.cwd();
+  try { cwd = fs.realpathSync(cwd); } catch { /* retain the payload cwd when unavailable */ }
+  const root      = projectRoot(data);
+  const runtime   = readRuntime(root);
+
+  // A plugin is trusted once for every repository, so a repository cannot switch it off.
+  const disabled = runtime.scout?.enabled === false || runtime.inspect?.enabled === false;
+  if (disabled && !require('./lib/plugin-options.cjs').isPlugin()) process.exit(0);
+
+  const result = inspectInput(toolName, toolInput, {
+    cwd, projectRoot: root
+  });
+  if (result.broadGlob) {
     denyWithReason(
       `SCOPE LIMIT EXCEEDED: Glob pattern is excessively broad\n` +
-      `Requested Pattern: ${toolInput.pattern}\n\n` +
+      `Requested Pattern: ${result.broadGlob}\n\n` +
       `Please narrow your scope (e.g., src/**/*.ts rather than **/*.ts).`
     );
   }
 
-  // Blocked directory check
-  const paths = extractPaths(toolName, toolInput);
-  for (const p of paths) {
-    if (isBlockedPath(p)) {
-      const blocked = p.replace(/\\/g, '/').split('/').find(s => BLOCKED_DIRS.includes(s));
+  if (result.blockedPath) {
+      const { requested, blocked } = result.blockedPath;
       denyWithReason(
         `SCOPE LIMIT EXCEEDED: Directory "${blocked}/" is explicitly forbidden\n` +
-        `Requested Path: ${p}\n` +
-        `Restricted zones: ${BLOCKED_DIRS.join(', ')}`
+        `Requested Path: ${requested}\n` +
+        `Restricted zones: ${[...BLOCKED_DIRS].join(', ')}`
       );
-    }
   }
 
   process.exit(0);

package/src/claude/hooks/lib/hook-state-dir.cjs

@@ -29,11 +29,29 @@ function isSourceTree(dir) {
   return String(dir || '').includes(SOURCE_MARKER);
 }
 
+/**
+ * State root for hooks running from the Claude Code plugin, or null outside it.
+ * The plugin root is replaced on every update and the project must stay clean,
+ * so plugin state lives in CLAUDE_PLUGIN_DATA, or the OS temp directory when the
+ * host gives no usable data directory.
+ */
+function pluginStateRoot() {
+  if (!process.env.CLAUDE_PLUGIN_ROOT) return null;
+  const data = process.env.CLAUDE_PLUGIN_DATA;
+  if (data && path.isAbsolute(data)) return data;
+  // Per-user name so accounts sharing /tmp do not collide; this is a fallback
+  // only, since the host sets CLAUDE_PLUGIN_DATA for plugin hooks.
+  const uid = typeof process.getuid === 'function' ? process.getuid() : 'user';
+  return path.join(os.tmpdir(), `cafekit-plugin-${uid}`);
+}
+
 /** Absolute directory for hook-generated state; create it before writing. */
 function hookStateDir() {
+  const pluginRoot = pluginStateRoot();
+  if (pluginRoot) return path.join(pluginRoot, '.logs');
   return isSourceTree(HOOKS_DIR)
     ? path.join(os.tmpdir(), 'cafekit-hook-logs', require('./runtime-dir.cjs').runtimeDirName().slice(1))
     : path.join(HOOKS_DIR, '.logs');
 }
 
-module.exports = { hookStateDir, isSourceTree };
+module.exports = { hookStateDir, isSourceTree, pluginStateRoot };

package/src/claude/hooks/lib/inspect-paths.cjs

@@ -0,0 +1,304 @@
+'use strict';
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const BLOCKED_DIRS = new Set([
+  'node_modules', 'dist', 'build', '.next', '.nuxt', '.output',
+  '__pycache__', '.venv', 'venv', 'vendor', 'target',
+  '.git', 'coverage', '.nyc_output'
+]);
+const BROAD_GLOBS = [/^\*\*\/\*$/, /^\*\*\.\w+$/, /^\*\*\/\*\.\w+$/];
+const PATH_KEYS = /^(?:file_?paths?|paths?|search_?paths?|notebook_path|(?:source|target|destination)_?paths?|dirs?|director(?:y|ies)|folders?|cwd|root|locations?|uris?)$/i;
+const WRITE_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit', 'apply_patch']);
+const READERS = new Set(['cat', 'head', 'tail', 'nl', 'less', 'more', 'bat', 'ls', 'tree', 'find', 'rg', 'grep', 'sed', 'awk', 'wc', 'du', 'file', 'stat']);
+const clean = (value) => String(value || '').trim();
+const nameOf = (value) => String(value || '').replace(/\\/g, '/').split('/').pop();
+function real(value) { try { return fs.realpathSync(value); } catch { return value; } }
+function relativeInside(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative) ? relative : null;
+}
+function blockedSegment(value, { cwd, projectRoot }) {
+  let candidate = clean(value).replace(/\\/g, '/');
+  if (candidate === '~' || candidate.startsWith('~/')) candidate = os.homedir() + candidate.slice(1);
+  if (path.isAbsolute(candidate)) {
+    // Prefer project root over a nested session cwd. Compare lexical and canonical
+    // roots so /var and /private/var (or a symlink install) have the same boundary.
+    for (const base of [projectRoot, cwd].filter(base => typeof base === 'string' && base)) {
+      const root = path.resolve(base);
+      const relative = relativeInside(root, candidate) ?? relativeInside(real(root), candidate);
+      if (relative !== null) { candidate = relative; break; }
+    }
+  } else candidate = path.normalize(candidate);
+  return candidate.split('/').find((segment) => BLOCKED_DIRS.has(segment));
+}
+function narrowPath(value, context) {
+  if (context.cwd !== undefined && typeof context.cwd !== 'string') return false;
+  let requested = clean(value).replace(/\\/g, '/');
+  if (!requested) return false;
+  if (requested === '~' || requested.startsWith('~/')) requested = os.homedir() + requested.slice(1);
+  const root = path.resolve(context.projectRoot || context.cwd || process.cwd());
+  const candidate = path.resolve(context.cwd || root, requested);
+  const relative = relativeInside(root, candidate) ?? relativeInside(real(root), candidate);
+  // Both boundaries must hold: a symlink cannot turn an outside read into a
+  // narrow scope, nor point a lexical child at the project root or beyond it.
+  const canonical = relative === null ? candidate : real(path.resolve(real(root), relative));
+  return !!relative && !!relativeInside(real(root), canonical)
+    && !blockedSegment(candidate, context) && !blockedSegment(canonical, context);
+}
+function collectStructured(value, key, toolName, paths, globs) {
+  if (typeof value === 'string') {
+    if (PATH_KEYS.test(key)) paths.push(value);
+    if ((toolName === 'Glob' && key === 'pattern') || /^(?:glob|globs)$/i.test(key)) globs.push(value);
+  } else if (Array.isArray(value)) {
+    for (const child of value) collectStructured(child, key, toolName, paths, globs);
+  } else if (value && typeof value === 'object') {
+    for (const [childKey, child] of Object.entries(value)) collectStructured(child, childKey, toolName, paths, globs);
+  }
+}
+
+// A small shell lexer, not an executor: quoted prose is data, while substitutions
+// contribute their own command groups. Heredoc bodies are data, never commands.
+function commandGroups(command) {
+  function scan(start, closing = '') {
+    const groups = []; let group = []; let token = ''; let quote = ''; let index = start;
+    const heredocs = [];
+    const flush = () => { if (token) group.push(token); token = ''; };
+    const boundary = () => { flush(); if (group.length) groups.push(group); group = []; };
+    for (; index < command.length; index += 1) {
+      const char = command[index];
+      if (!quote && closing && char === closing) { boundary(); return { groups, index }; }
+      if (char === '\\' && quote !== "'") {
+        if (command[index + 1] !== '\n') token += command[index + 1] || '';
+        index += 1; continue;
+      }
+      if (quote === "'") { if (char === "'") quote = ''; else token += char; continue; }
+      if (char === '$' && command[index + 1] === '(') {
+        const sub = scan(index + 2, ')'); groups.push(...sub.groups);
+        token += '__substitution__'; index = sub.index; continue;
+      }
+      if (char === '`') {
+        const sub = scan(index + 1, '`'); groups.push(...sub.groups);
+        token += '__substitution__'; index = sub.index; continue;
+      }
+      if (quote) { if (char === quote) quote = ''; else token += char; continue; }
+      if (char === '"' || char === "'") { quote = char; continue; }
+      if (char === '(') {
+        boundary(); const sub = scan(index + 1, ')');
+        groups.push(...sub.groups); index = sub.index; continue;
+      }
+      if (command.startsWith('<<', index) && !command.startsWith('<<<', index)) {
+        const match = command.slice(index).match(/^<<(-?)[ \t]*((?:'[^']*'|"[^"]*"|\\[^\n]|[^\s;|&<>'"\\])+)/);
+        if (match) {
+          const delimiter = match[2].replace(/'([^']*)'|"([^"]*)"|\\(.)/g, (_, single, double, escaped) => single ?? double ?? escaped);
+          flush(); heredocs.push({ delimiter, tabs: !!match[1] });
+          index += match[0].length - 1; continue;
+        }
+      }
+      if (char === '>' || char === '<') {
+        // Preserve operator identity (quoted > remains ordinary text). A numeric
+        // token touching the operator is its fd, not a positional argument.
+        if (/^\d+$/.test(token)) token = '';
+        flush();
+        const operator = command.slice(index).match(/^(?:>>|>&|>|<)/)[0];
+        group.push({ redirect: operator }); index += operator.length - 1; continue;
+      }
+      if (char === '\n') {
+        boundary();
+        for (const here of heredocs.splice(0)) {
+          while (index < command.length) {
+            const end = command.indexOf('\n', index + 1);
+            const stop = end < 0 ? command.length : end;
+            const line = command.slice(index + 1, stop);
+            index = stop;
+            if ((here.tabs ? line.replace(/^\t+/, '') : line) === here.delimiter) break;
+          }
+        }
+      } else if (';&|'.includes(char)) {
+        boundary();
+        if (command[index + 1] === char) index += 1;
+      } else if (/\s/.test(char)) flush();
+      else token += char;
+    }
+    boundary(); return { groups, index };
+  }
+  return scan(0).groups;
+}
+
+const WRAPPER_OPTIONS = {
+  sudo: ['-u', '-g', '-h', '-p', '-C', '-T', '-R', '-D', '--user', '--group', '--host', '--prompt', '--chdir', '--chroot'],
+  env: ['-u', '--unset', '-C', '--chdir', '-S', '--split-string'],
+  time: ['-f', '--format', '-o', '--output'], command: [], builtin: [],
+  nice: ['-n', '--adjustment'], nohup: [],
+  xargs: ['-I', '-i', '-n', '-L', '-P', '-s', '-d', '-E', '-a', '--replace', '--max-args', '--max-lines', '--max-procs', '--arg-file', '--delimiter', '--eof'],
+  npm: ['-p', '--package', '-c', '--call', '--prefix', '--workspace', '-w'],
+  npx: ['-p', '--package', '-c', '--call', '--cache'],
+  pnpm: ['--dir', '-C', '--filter'], pnpx: ['-p', '--package'],
+  yarn: ['--cwd'], bunx: ['-p', '--package'],
+};
+function unwrap(group, state) {
+  let index = 0;
+  while (index < group.length) {
+    while (/^[A-Za-z_][A-Za-z0-9_]*=/.test(group[index] || '')) index += 1;
+    const name = nameOf(group[index]);
+    if (!Object.hasOwn(WRAPPER_OPTIONS, name)) return group.slice(index);
+    if (name === 'xargs') state.unknownCwd = true;
+    index += 1;
+    // npm/pnpm/yarn only wrap a reader in exec mode; run/build remain opaque.
+    let exec = !['npm', 'pnpm', 'yarn'].includes(name);
+    while (index < group.length) {
+      const token = group[index];
+      const cwdOptions = { env: ['-C', '--chdir'], sudo: ['-D', '--chdir'],
+        npm: ['--prefix'], pnpm: ['-C', '--dir'], yarn: ['--cwd'] };
+      if (cwdOptions[name]?.some(option => String(token).split('=')[0] === option
+        || (option.length === 2 && String(token).startsWith(option)))) state.unknownCwd = true;
+      if (name === 'env' && /^-[^-]*C/.test(token)) state.unknownCwd = true;
+      if (token === 'exec' && !exec) { exec = true; index += 1; continue; }
+      if (token === '--') { index += 1; break; }
+      if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(token)) { index += 1; continue; }
+      const commandOption = name === 'env' ? /^(?:-S|--split-string)(?:=|$)/ : ['npm', 'npx'].includes(name) ? /^(?:-c|--call)(?:=|$)/ : null;
+      if (commandOption?.test(token)) {
+        const equals = token.indexOf('=');
+        return { command: equals < 0 ? group[index + 1] || '' : token.slice(equals + 1),
+          rest: name === 'env' ? group.slice(index + (equals < 0 ? 2 : 1)) : [] };
+      }
+      if (!token.startsWith('-')) break;
+      index += WRAPPER_OPTIONS[name].includes(token) ? 2 : 1;
+    }
+    if (!exec) return [];
+  }
+  return [];
+}
+function positional(tokens, options) {
+  const values = []; let afterDash = false;
+  for (let index = 1; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (!afterDash && token === '--') { afterDash = true; continue; }
+    if (!afterDash && options.has(token)) { index += 1; continue; }
+    if (afterDash || !token.startsWith('-') || token === '-') values.push(token);
+  }
+  return values;
+}
+function knownSearchOptions(tokens, options, name) {
+  const booleans = new Set(['-n', '-i', '-v', '-w', '-x', '-F', '-P', '-l', '-L', '-q', '-s', '-h', '-H', '-o', '-c', '-a', '-u', '-U', '-z',
+    '--line-number', '--ignore-case', '--invert-match', '--word-regexp', '--line-regexp', '--fixed-strings', '--pcre2',
+    '--files-with-matches', '--files-without-match', '--quiet', '--no-messages', '--no-filename', '--with-filename',
+    '--only-matching', '--count', '--text', '--multiline', '--null', '--hidden', '--files', '--stats']);
+  if (name === 'grep') for (const flag of ['-r', '-R', '--recursive', '--dereference-recursive']) booleans.add(flag);
+  if (name === 'rg') for (const flag of ['--json', '-S', '--smart-case', '-N', '--no-heading', '--heading',
+    '--column', '--vimgrep', '--follow', '--no-ignore', '--no-ignore-dot', '--no-ignore-exclude',
+    '--no-ignore-files', '--no-ignore-global', '--no-ignore-parent', '--no-ignore-vcs', '--no-ignore-messages',
+    '--no-ignore-file-case-insensitive', '--count-matches', '-b', '--trim']) booleans.add(flag);
+  for (let index = 1; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token === '--') return true;
+    if (!token.startsWith('-') || token === '-') continue;
+    if (options.has(token)) { index += 1; continue; }
+    if (/^-[ABCmMjdt]\S+/.test(token) && options.has(token.slice(0, 2))) continue;
+    if (token.startsWith('--') && options.has(token.split('=')[0]) && token.includes('=')) continue;
+    if (booleans.has(token)) continue;
+    if (!token.startsWith('--') && [...token.slice(1)].every(flag => booleans.has(`-${flag}`))) continue;
+    return false;
+  }
+  return true;
+}
+function commandPaths(group, globs, scopes, state) {
+  const inputs = []; const args = [];
+  for (let index = 0; index < group.length; index += 1) {
+    const token = group[index];
+    if (token.redirect) {
+      const operand = group[index += 1];
+      if (token.redirect === '<' && typeof operand === 'string') inputs.push(operand);
+    } else args.push(token);
+  }
+  return [...inputs, ...readerPaths(args, globs, scopes, state)];
+}
+function readerPaths(group, globs, scopes, state) {
+  const tokens = unwrap(group, state);
+  if (tokens.command !== undefined) {
+    const groups = commandGroups(tokens.command);
+    if (groups.length) groups[groups.length - 1].push(...tokens.rest);
+    return groups.flatMap((nested) => commandPaths(nested, globs, scopes, state));
+  }
+  const name = nameOf(tokens[0]);
+  if (['cd', 'pushd', 'popd', 'eval', 'source', '.'].includes(name)) state.unknownCwd = true;
+  if (!READERS.has(name)) return []; // Executables and non-reader arguments are never paths.
+  if (name === 'find') {
+    let index = 1;
+    while (['-H', '-L', '-P'].includes(tokens[index]) || /^-O\d+$/.test(tokens[index] || '')) index += 1;
+    if (tokens[index] === '-D') index += 2;
+    if (tokens[index] === '--') index += 1;
+    const roots = [];
+    for (; index < tokens.length && !/^(?:-|!|\(|\))/.test(tokens[index]); index += 1) roots.push(tokens[index]);
+    return roots; // Expressions such as -path ... -prune are not read roots.
+  }
+  if (['rg', 'grep'].includes(name)) {
+    const firstGlob = globs.length;
+    for (let index = 1; index < tokens.length; index += 1) {
+      const token = tokens[index];
+      if (['-g', '--glob', '--iglob'].includes(token)) globs.push(tokens[index + 1] || '');
+      else if (/^--i?glob=/.test(token)) globs.push(token.slice(token.indexOf('=') + 1));
+    }
+    const options = new Set(['-e', '--regexp', '-f', '--file', '-g', '--glob', '--iglob', '-t', '--type', '-T', '--type-not', '--exclude', '--exclude-dir', '--include', '-m', '--max-count', '-A', '-B', '-C', '--after-context', '--before-context', '--context', '--encoding', '--color',
+      '--max-depth', '-d', '-j', '--threads', '-M', '--max-columns', '--sort', '--sortr', '--replace', '--max-filesize', '--pre', '--path-separator', '--dfa-size-limit', '--regex-size-limit', '--directories', '-D', '--devices', '--label']);
+    // rg -r takes replacement text; grep -r is a recursive flag.
+    if (name === 'rg') options.add('-r');
+    const values = positional(tokens, options);
+    const explicit = tokens.some((token) => /^(?:-[ef]|--(?:regexp|file)(?:=|$))/.test(token)) || tokens.includes('--files');
+    const paths = explicit ? values : values.slice(1);
+    scopes.push({ paths: state.unknownCwd || !knownSearchOptions(tokens, options, name) ? [] : paths, globs: globs.slice(firstGlob) });
+    return paths;
+  }
+  if (['sed', 'awk'].includes(name)) {
+    const options = new Set(['-e', '--expression', '-f', '--file', '-F', '-v']);
+    const values = positional(tokens, options);
+    return tokens.some((token) => /^(?:-[ef]|--(?:expression|file)(?:=|$))/.test(token)) ? values : values.slice(1);
+  }
+  // A flag's meaning belongs to its reader: cat -n and wc -c are booleans,
+  // whereas head -n consumes a number. Never swallow the following read path.
+  const options = {
+    head: ['-n', '--lines', '-c', '--bytes'], tail: ['-n', '--lines', '-c', '--bytes', '--pid', '-s', '--sleep-interval'],
+    nl: ['-b', '-d', '-f', '-h', '-i', '-l', '-n', '-s', '-v', '-w'],
+    tree: ['-I', '-P', '-L', '-o', '--filelimit', '--sort'],
+    ls: ['-I', '--ignore', '--hide', '--format', '--sort', '--time', '--block-size', '--quoting-style', '-w', '--width'],
+    du: ['-d', '--max-depth', '--exclude', '-X', '--exclude-from', '-B', '--block-size'],
+    stat: ['-c', '--format', '--printf'], file: ['-m', '--magic-file', '-f', '--files-from', '-F', '--separator'],
+    bat: ['--color', '--style', '--language', '--paging', '--theme', '--line-range', '-r', '--tabs'],
+    less: ['-x', '--tabs', '-j', '-p', '-P', '-z'],
+  };
+  return positional(tokens, new Set(options[name] || []));
+}
+function broadGlobFor(paths, globs, context) {
+  if (paths.length > 0 && paths.every(requested => narrowPath(requested, context))) return undefined;
+  return globs.find(glob => !glob.startsWith('!') && BROAD_GLOBS.some(rule => rule.test(clean(glob))));
+}
+function inspectInput(toolName, toolInput, context = {}) {
+  if (WRITE_TOOLS.has(toolName)) return {};
+  const paths = []; const globs = [];
+  collectStructured(toolInput, '', toolName, paths, globs);
+  let broadGlob = broadGlobFor(paths, globs, context);
+  const scopes = [];
+  const commandContext = { ...context };
+  let unknownCwd = context.cwd !== undefined && typeof context.cwd !== 'string';
+  const overrides = ['cwd', 'workdir'].filter(key => Object.hasOwn(toolInput || {}, key));
+  for (const key of overrides) {
+    if (typeof toolInput[key] !== 'string' || !toolInput[key].trim()) unknownCwd = true;
+    else commandContext.cwd = path.resolve(typeof context.cwd === 'string' ? context.cwd : process.cwd(), toolInput[key]);
+  }
+  if (overrides.length > 1 && toolInput.cwd !== toolInput.workdir) unknownCwd = true;
+  for (const key of ['command', 'cmd']) {
+    if (typeof toolInput?.[key] === 'string') {
+      const state = { unknownCwd };
+      for (const group of commandGroups(toolInput[key])) paths.push(...commandPaths(group, globs, scopes, state));
+    }
+  }
+  const included = globs.filter((glob) => !glob.startsWith('!'));
+  for (const scope of scopes) broadGlob ||= broadGlobFor(scope.paths, scope.globs, commandContext);
+  paths.push(...included);
+  return {
+    broadGlob,
+    blockedPath: paths.map((requested) => ({ requested, blocked: blockedSegment(requested, context) })).find((result) => result.blocked),
+  };
+}
+
+module.exports = { BLOCKED_DIRS, inspectInput };

package/src/claude/hooks/lib/parser.cjs

@@ -80,7 +80,7 @@ function processEntry(entry, toolMap, agentMap, latestTodos, result) {
   for (const block of content) {
     // Handle tool_use blocks
     if (block.type === 'tool_use' && block.id && block.name) {
-      if (block.name === 'Task') {
+      if (block.name === 'Task' || block.name === 'Agent') {
         // Agent spawn
         agentMap.set(block.id, {
           id: block.id,

package/src/claude/hooks/lib/plugin-options.cjs

@@ -0,0 +1,47 @@
+'use strict';
+
+/**
+ * Claude Code plugin options for the hooks.
+ *
+ * The plugin's userConfig values reach hooks as CLAUDE_PLUGIN_OPTION_<KEY> and are
+ * injected into model context verbatim, so each one is reduced to a single short
+ * line: no control, bidi, or zero-width characters or line breaks that could open a
+ * new section or disguise the text, and
+ * at most 64 characters so the core stays inside the host's context budget.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const MAX_OPTION_LENGTH = 64;
+
+/**
+ * True when the hook runs from the Claude Code plugin rather than an npx install.
+ * The variable alone is not enough: an npx hook can inherit it from a parent process,
+ * so this file must really live under that plugin root.
+ */
+function isPlugin() {
+  const declared = process.env.CLAUDE_PLUGIN_ROOT;
+  if (!declared) return false;
+  try {
+    return fs.realpathSync(declared) === fs.realpathSync(path.resolve(__dirname, '..', '..'));
+  } catch {
+    return false;
+  }
+}
+
+/** One short plain line: no control, bidi, or zero-width characters; at most 64 characters. */
+function sanitizeLine(raw) {
+  if (typeof raw !== 'string') return '';
+  return [...raw.replace(/[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u2028-\u202e\u2060-\u2069\ufeff]+/g, ' ').replace(/\s+/g, ' ').trim()]
+    .slice(0, MAX_OPTION_LENGTH)
+    .join('')
+    .trim();
+}
+
+/** Sanitized option value, or '' when unset. `key` is the userConfig key, e.g. `response_language`. */
+function pluginOption(key) {
+  return sanitizeLine(process.env[`CLAUDE_PLUGIN_OPTION_${key.toUpperCase()}`]);
+}
+
+module.exports = { MAX_OPTION_LENGTH, isPlugin, pluginOption, sanitizeLine };