@haposoft/cafekit 0.14.1 → 0.15.0

package/src/claude/skills/specs/rules/tasks-generation.md

@@ -157,7 +157,7 @@ Every task file MUST contain the Risk Assessment table, even if no risks are ide
 
 ### Mandatory Evidence Section
 
-Every new task file MUST include a `## Evidence` section. Existing specs may still use the v0.8 heading `## Task Test Plan & Verification Evidence` or the legacy `## Verification & Evidence` heading; readers and sync tools must support all three.
+Every new task file MUST include a `## Evidence` section (`## Evidence` (legacy heading aliases still parse)).
 
 That section is the task-level test plan and proof checklist. It MUST contain:
 1. **Automated proof** — exact command(s) for typecheck, tests, build, or explicit `N/A`

package/src/claude/skills/specs/templates/task.md

@@ -60,6 +60,8 @@
 This section is both the task-level test plan and the proof checklist. Keep it short, exact, and executable.
 Select the proof by task risk; do not run every test type for every task.
 
+Verification: PENDING
+
 - Logic/data/validator task: include unit tests.
 - Stateful UI/component task: include component or integration tests.
 - Cross-module/API/state flow task: include integration tests.
@@ -94,4 +96,4 @@ Select the proof by task risk; do not run every test type for every task.
 > **Parallel marker**: Append `(P)` to the title if this task can run concurrently with another (usually when serving different requirements).
 > **Test note**: If a test coverage sub-task can be deferred post-MVP, mark it with `- [ ]*`.
 > **Requirement mapping**: Every sub-task MUST end with `_Requirements: X.X_`. No mapping = invalid task file.
-> **Evidence rule**: No `## Evidence` section = invalid task file. Existing specs may use `## Task Test Plan & Verification Evidence` or legacy `## Verification & Evidence`; agents must support all three headings.
+> **Evidence rule**: No `## Evidence` section = invalid task file. Use `## Evidence` (legacy heading aliases still parse).

package/src/claude/skills/sync/SKILL.md

@@ -39,8 +39,8 @@ Scans the `spec.json` against all physical `task-R*.md` files to detect mismatch
 
 1. **Precision Edits:** Never overwrite the entire `spec.json` string blindly. Update only the required keys, while keeping JSON valid.
 2. **Machine + Human Sync:** Every task status update MUST modify both `spec.json.task_registry[...]` and the matching markdown task file header/status section.
-3. **Markdown Integrity:** When marking a task `done`, only then turn `[ ]` into `[x]` inside `## Steps` / `## Implementation Steps` and relevant `Completion Criteria` / `Evidence` checkboxes that have actual proof. `Task Test Plan & Verification Evidence` and legacy `Verification & Evidence` sections are supported.
-4. **Verification Receipt Rule:** `done` is illegal without a human-readable verification receipt already present in `## Evidence`, `## Task Test Plan & Verification Evidence`, or legacy `## Verification & Evidence` (commands executed, artifact/runtime proof, or equivalent concrete evidence). If proof is missing, keep the task `in_progress` or `blocked`.
+3. **Markdown Integrity:** When marking a task `done`, only then turn `[ ]` into `[x]` inside `## Steps` / `## Implementation Steps` and relevant `Completion Criteria` / `Evidence` checkboxes that have actual proof. Use `## Evidence` (legacy heading aliases still parse).
+4. **Verification Receipt Rule:** `done` is illegal without a human-readable verification receipt already present in `## Evidence` (legacy heading aliases still parse) (commands executed, artifact/runtime proof, or equivalent concrete evidence). If proof is missing, keep the task `in_progress` or `blocked`.
 5. **Task Docs Hook:** Every time `hapo:sync` marks a task as `done`, it must flag that a task-level docs checkpoint is now due for that verified task.
 6. **Phase Prompt Rule:** When `hapo:sync` marks the final pending task in the whole feature as `done`, it should automatically prompt the user if they'd like to advance the phase, but only after the docs checkpoint for that last completed task has been considered.
 

package/src/claude/skills/sync/references/sync-protocols.md

@@ -15,7 +15,7 @@ When requested to update a phase or change task configuration, `spec.json` must
     - full relative path like `tasks/task-R0-02-extension-shell.md`
 *   **Status Update:** If a task changes to `blocked`, the matching `task_registry[path].status` must become `"blocked"`, `task_registry[path].blocker` must record the reason, and `spec.json.status` / `spec.json.blocker` must reflect the top-level block if work is globally blocked.
 *   **Timestamp Rule:** Update `task_registry[path].started_at`, `completed_at`, and `last_updated_at` consistently with the new state. Also refresh `spec.json.updated_at`.
-*   **Done-State Rule:** Never set `task_registry[path].status = "done"` unless the matching markdown task file already contains a verification receipt in `## Evidence`, `## Task Test Plan & Verification Evidence`, or legacy `## Verification & Evidence`, or the caller explicitly provides proof that can be written there first.
+*   **Done-State Rule:** Never set `task_registry[path].status = "done"` unless the matching markdown task file already contains a verification receipt in `## Evidence` (legacy heading aliases still parse), or the caller explicitly provides proof that can be written there first.
 *   **Receipt Integrity Rule:** A valid verification receipt must include the exact commands run, their outcomes, and artifact/runtime proof. Receipts containing `PRECHECK_FAIL`, `FAIL`, `UNVERIFIED`, or explicit "placeholder / simplified for MVP / production later" contract deviations are not eligible for `done`.
 *   **Contract Fidelity Rule:** If the task file notes or evidence show that a named framework/auth/runtime choice from the spec was silently replaced, sync MUST refuse `done` until the spec is amended or the implementation is corrected.
 *   **Task Docs Rule:** After a task is moved to `done`, emit a short alert that a task-level docs checkpoint is due for this verified task.
@@ -27,12 +27,12 @@ The structure of `tasks/task.md` relies heavily on exact keyword markers. Follow
 ### A. Completing a Task
 When `/hapo:sync <feature> <task-id> done`:
 1. Find: `**Status:** pending` (or `in_progress` / `blocked`).
-2. Inspect `## Evidence` first. If the task uses `## Task Test Plan & Verification Evidence` or legacy `## Verification & Evidence`, inspect that section instead. If it has no explicit proof lines (commands run, artifact proof, runtime proof, or blockers cleared), STOP and refuse to mark the task done.
+2. Inspect `## Evidence` (legacy heading aliases still parse) first. If it has no explicit proof lines (commands run, artifact proof, runtime proof, or blockers cleared), STOP and refuse to mark the task done.
 3. Refuse completion if the receipt contains any non-passing marker such as `PRECHECK_FAIL`, `FAIL`, `UNVERIFIED`, or an explicit note that the implementation substituted a named contract with a placeholder/custom simplification.
 4. Replace with: `**Status:** done`.
 5. Locate block: `## Steps` or `## Implementation Steps`.
 6. Convert `- [ ]` into `- [x]` strictly within that section.
-7. Update relevant checkboxes in `## Completion Criteria` and `## Evidence` only when the caller provides or the file already contains real proof. For v0.8 or legacy task files, update `## Task Test Plan & Verification Evidence` or `## Verification & Evidence` instead.
+7. Update relevant checkboxes in `## Completion Criteria` and `## Evidence` (legacy heading aliases still parse) only when the caller provides or the file already contains real proof.
 8. Surface a note such as: `Docs checkpoint due: task Rn-mm just completed`.
 
 ### B. Blocking a Task
@@ -59,7 +59,7 @@ When `/hapo:sync audit <feature>` is activated:
    - Missing disk file referenced in registry → remove or flag it
    - Markdown says `done` but registry not done → registry wins only if evidence already exists; otherwise downgrade markdown or flag conflict
    - Registry says `done` but markdown still pending → update markdown only if evidence exists
-   - Either side says `done` but `## Evidence` / `## Task Test Plan & Verification Evidence` / legacy `## Verification & Evidence` has no concrete proof → downgrade to `in_progress` or flag conflict instead of preserving fake completion
+   - Either side says `done` but `## Evidence` (legacy heading aliases still parse) has no concrete proof → downgrade to `in_progress` or flag conflict instead of preserving fake completion
    - Either side says `done` but the receipt contains `PRECHECK_FAIL`, `FAIL`, `UNVERIFIED`, or explicit contract-substitution notes → downgrade to `in_progress` or flag conflict
 5. **Correction Alert:** Output a brief markdown alert detailing mismatches fixed and any unresolved conflicts requiring manual review.
 6. **Task Docs Alert:** If audit reveals tasks newly marked `done`, include whether task-level docs sync appears still due or already accounted for in the current run summary.

package/src/claude/skills/test/SKILL.md

@@ -177,7 +177,7 @@ It merges the JSON data into `.hapo/test-memory.json` per `references/test-memor
 | `hapo:develop` | orchestrates | Spawns hapo:test at Step 4 |
 | `inspector` agent | hapo:test → | Scout test file locations when structure is unfamiliar |
 | `god-developer` agent | hapo:test → | FAIL verdicts route back here for fixing |
-| `test-runner` agent | hapo:test → | Primary executor, spawned via Task tool |
+| `test-runner` agent | hapo:test → | Primary executor, spawned via the `Agent` tool |
 | chrome-devtools scripts | test-runner → | UI verification (navigate, screenshot, console, network, performance, aria-snapshot, inject-auth) |
 
 ## References

package/src/claude/status.cjs

@@ -21,8 +21,10 @@ const { countConfigs } = require('./hooks/lib/counter.cjs');
 const { loadConfig } = require('./hooks/lib/config.cjs');
 const { getGitInfo } = require('./hooks/lib/git.cjs');
 
-// Buffer constant matching /context output (22.5% of 200k)
-const AUTOCOMPACT_BUFFER = 45000;
+// Autocompact reserve as a fraction of the ACTUAL window size from the payload.
+// Derived from /context on a 200k window (45000/200000 = 22.5%); expressed as a
+// ratio so 1M-context models are not treated as if they were 200k.
+const AUTOCOMPACT_BUFFER_RATIO = 0.225;
 
 /**
  * Expand home directory to ~
@@ -411,19 +413,20 @@ async function main() {
       }
     } catch {}
 
-    // Context window - use current_usage fields with AUTOCOMPACT_BUFFER
+    // Context window - use current_usage fields with a proportional reserve
     const usage = data.context_window?.current_usage || {};
     const contextSize = data.context_window?.context_window_size || 0;
     let contextPercent = 0;
     let totalTokens = 0;
 
-    if (contextSize > 0 && contextSize > AUTOCOMPACT_BUFFER) {
+    if (contextSize > 0) {
       totalTokens = (usage.input_tokens ?? 0) +
                     (usage.cache_creation_input_tokens ?? 0) +
                     (usage.cache_read_input_tokens ?? 0);
 
-      // Add buffer to match /context calculation
-      contextPercent = Math.min(100, Math.round(((totalTokens + AUTOCOMPACT_BUFFER) / contextSize) * 100));
+      // Add the reserve to match /context calculation on any window size
+      const buffer = Math.round(contextSize * AUTOCOMPACT_BUFFER_RATIO);
+      contextPercent = Math.min(100, Math.round(((totalTokens + buffer) / contextSize) * 100));
     }
 
     // Write context data to temp file for hooks to read

package/src/codex/AGENTS.md

@@ -0,0 +1,30 @@
+# CafeKit for Codex CLI
+
+## Native runtime mapping
+
+- Repository instructions: `AGENTS.md`.
+- CafeKit skills: `.agents/skills/`; invoke explicitly as `$hapo-<name>` or browse with `/skills`.
+- CafeKit agents: native auto-discovered definitions in `.codex/agents/*.toml`.
+- Runtime support: `.codex/rules/`, `.codex/scripts/`, `.codex/references/`, and `.codex/runtime.json`.
+- Lifecycle enforcement: `.codex/hooks.json`. Project hooks run only after the repository and hook definitions are trusted; review them with `/hooks`.
+- Do not create deprecated custom prompts or assume Claude/OpenCode command wrappers exist.
+
+## Operating contract
+
+- Read `README.md` and relevant project instructions before non-trivial work.
+- Choose the matching CafeKit skill before improvising a workflow.
+- Read `.codex/rules/workflow.md`, `.codex/rules/ai-dev-rules.md`, and
+  `.codex/rules/skill-workflow-routing.md` for non-trivial work. Load the other
+  `.codex/rules/*.md` files when their topic applies.
+- Keep scope surgical; prefer YAGNI, KISS, then DRY.
+- Do not claim completion without fresh build, test, runtime, or artifact evidence.
+- For spec tasks, keep `spec.json`, task status, `Completion Criteria`, and `Evidence` synchronized only after verification.
+- Privacy approvals are one request, one session, one retry. Only the user may submit the exact approval phrase emitted by the privacy hook.
+
+## Runtime caveats
+
+- Codex custom agents use snake_case names.
+- When selecting a CafeKit custom role explicitly, call `spawn_agent` with `agent_type`, a unique snake_case `task_name`, `message`, and `fork_turns: "none"`. A full-history fork cannot change agent type.
+- Use Codex-native subagent delegation and task-state tools; do not rely on Claude-only tool labels.
+- The project `.codex/` layer—agents, config, rules, and hooks—loads only after the repository is trusted. Never edit the user's global trust configuration on their behalf.
+- Hooks are guardrails, not a complete security boundary. Hosted tools and untrusted project hooks may not enter the local hook path.

package/src/codex/agents-gitignore

@@ -0,0 +1,11 @@
+# CafeKit skill-local secrets and generated dependencies
+skills/**/.env
+skills/**/.env.*
+!skills/**/.env.example
+!skills/**/.env.sample
+!skills/**/.env.template
+
+skills/**/.venv/
+skills/**/node_modules/
+skills/**/__pycache__/
+skills/**/*.pyc

package/src/codex/gitignore

@@ -0,0 +1,12 @@
+# CafeKit local Codex runtime
+.env
+.env.*
+!.env.example
+!.env.sample
+!.env.template
+
+hooks/.logs/
+hooks/.privacy/
+session-state/
+.cafekit-update-cache.json
+*.tmp

package/src/codex/hooks/agent.cjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const {
+  getHookContext,
+  logCrash,
+  readPayload,
+  resolveProjectPath
+} = require('./lib/hook-context.cjs');
+
+function resolveVenv(projectRoot) {
+  const base = path.join(projectRoot, '.agents', 'skills', '.venv');
+  return [
+    path.join(base, 'bin', 'python3'),
+    path.join(base, 'Scripts', 'python.exe')
+  ].find((candidate) => fs.existsSync(candidate)) || null;
+}
+
+try {
+  const payload = readPayload();
+  if (!payload) process.exit(0);
+  const { projectRoot, runtime, sessionCwd } = getHookContext(payload);
+  const respondLang = runtime.locale?.responseLanguage || '';
+  const thinkLang = runtime.locale?.thinkingLanguage || (respondLang ? 'en' : '');
+  const plansPath = resolveProjectPath(projectRoot, runtime.paths?.plans, 'plans');
+  const docsPath = resolveProjectPath(projectRoot, runtime.paths?.docs, 'docs');
+  const venv = resolveVenv(projectRoot);
+  const lines = [
+    `## Subagent: ${payload.agent_type || 'unknown'}`,
+    `ID: ${payload.agent_id || 'unknown'} | CWD: ${sessionCwd}`,
+    ''
+  ];
+
+  if ((thinkLang && thinkLang !== respondLang) || respondLang) {
+    lines.push('## Language');
+    if (thinkLang && thinkLang !== respondLang) {
+      lines.push(`- Thinking: Use ${thinkLang} for reasoning.`);
+    }
+    if (respondLang) lines.push(`- Response: Respond in ${respondLang}.`);
+    lines.push('');
+  }
+
+  lines.push(
+    '## Rules',
+    `- Plans → ${plansPath}/ | Docs → ${docsPath}/`,
+    '- YAGNI · KISS · DRY',
+    '- Be concise. List unresolved questions at end.'
+  );
+  if (venv) {
+    lines.push(
+      `- Python in .agents/skills/: use \`${venv}\``,
+      '- Never use global pip install.'
+    );
+  }
+
+  process.stdout.write(`${JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'SubagentStart',
+      additionalContext: lines.join('\n')
+    }
+  })}\n`);
+} catch (error) {
+  logCrash('agent', error);
+}

package/src/codex/hooks/docs-sync.cjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const {
+  getHookContext,
+  logCrash,
+  readPayload,
+  resolveProjectPath
+} = require('./lib/hook-context.cjs');
+
+function latestSourceHash(projectRoot, docsRelative) {
+  try {
+    return execFileSync(
+      'git',
+      ['log', '-1', '--format=%H', '--', '.', `:(exclude)${docsRelative}`],
+      {
+        cwd: projectRoot,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore']
+      }
+    ).trim();
+  } catch {
+    return '';
+  }
+}
+
+try {
+  const payload = readPayload();
+  if (!payload) process.exit(0);
+  const { projectRoot, runtime } = getHookContext(payload);
+  const docsDir = resolveProjectPath(projectRoot, runtime.paths?.docs, 'docs');
+  const docsRelative = path.relative(projectRoot, docsDir).replace(/\\/g, '/');
+  const hasCode = [
+    'src', 'app', 'lib', 'package.json', 'index.js', 'main.py'
+  ].some((candidate) => fs.existsSync(path.join(projectRoot, candidate)));
+  if (!hasCode) process.exit(0);
+
+  const lines = [];
+  if (!fs.existsSync(docsDir)) {
+    lines.push(
+      '### Missing docs/',
+      '> Source exists but the configured docs directory does not.',
+      '> Create baseline architecture and project-overview docs, then record the source Git hash in `docs/.sync_hash`.'
+    );
+  } else {
+    const currentHash = latestSourceHash(projectRoot, docsRelative);
+    const trackingFile = path.join(docsDir, '.sync_hash');
+    const previousHash = fs.existsSync(trackingFile)
+      ? fs.readFileSync(trackingFile, 'utf8').trim()
+      : '';
+    if (currentHash && currentHash !== previousHash) {
+      lines.push(
+        '### Docs sync needed',
+        `> Source changed (\`${currentHash}\`) since last docs sync (\`${previousHash || 'none'}\`).`,
+        '> Review the source changes, update affected docs, then refresh `docs/.sync_hash`.'
+      );
+    }
+  }
+
+  if (lines.length) process.stdout.write(`${lines.join('\n')}\n`);
+} catch (error) {
+  logCrash('docs-sync', error);
+}

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

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+'use strict';
+
+const {
+  getHookContext,
+  logCrash,
+  readPayload
+} = require('./lib/hook-context.cjs');
+const { BLOCKED_DIRS, inspectInput } = require('./lib/inspect-paths.cjs');
+
+function denyPath(requested, blocked) {
+  process.stderr.write(
+    `SCOPE LIMIT EXCEEDED: Directory "${blocked}/" is explicitly forbidden\n`
+    + `Requested Path: ${requested}\n`
+    + `Restricted zones: ${[...BLOCKED_DIRS].join(', ')}\n`
+  );
+  process.exit(2);
+}
+
+try {
+  const payload = readPayload();
+  if (!payload) process.exit(0);
+  const { runtime } = getHookContext(payload);
+  if (runtime.scout?.enabled === false || runtime.inspect?.enabled === false) process.exit(0);
+
+  const result = inspectInput(payload.tool_input || {});
+  if (result.broadGlob) {
+    process.stderr.write(
+      `SCOPE LIMIT EXCEEDED: Glob pattern is excessively broad\n`
+      + `Requested Pattern: ${result.broadGlob}\n`
+      + 'Please narrow the scope (for example, src/**/*.ts).\n'
+    );
+    process.exit(2);
+  }
+  if (result.blockedPath) {
+    denyPath(result.blockedPath.requested, result.blockedPath.blocked);
+  }
+} catch (error) {
+  logCrash('inspect-block', error);
+}

package/src/codex/hooks/lib/hook-context.cjs

@@ -0,0 +1,93 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+// Installed layout: <project>/.codex/hooks/lib/hook-context.cjs
+const PROJECT_ROOT = path.resolve(__dirname, '..', '..', '..');
+
+function readPayload() {
+  const raw = fs.readFileSync(0, 'utf8').trim();
+  return raw ? JSON.parse(raw) : null;
+}
+
+function resolveSessionCwd(payload) {
+  const value = typeof payload?.cwd === 'string' ? payload.cwd.trim() : '';
+  const resolved = value
+    ? path.resolve(process.cwd(), value)
+    : process.cwd();
+  try {
+    return fs.realpathSync(resolved);
+  } catch {
+    return resolved;
+  }
+}
+
+function readRuntime(projectRoot = PROJECT_ROOT) {
+  try {
+    const file = path.join(projectRoot, '.codex', 'runtime.json');
+    return fs.existsSync(file)
+      ? JSON.parse(fs.readFileSync(file, 'utf8'))
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+function getHookContext(payload) {
+  return {
+    projectRoot: PROJECT_ROOT,
+    sessionCwd: resolveSessionCwd(payload),
+    runtime: readRuntime(PROJECT_ROOT)
+  };
+}
+
+function resolveProjectPath(projectRoot, configuredPath, fallback) {
+  const requested = typeof configuredPath === 'string' && configuredPath.trim()
+    ? configuredPath.trim()
+    : fallback;
+  const resolved = path.resolve(projectRoot, requested);
+  const relative = path.relative(projectRoot, resolved);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative))
+    ? resolved
+    : path.resolve(projectRoot, fallback);
+}
+
+function atomicWrite(file, content, mode = 0o600) {
+  const dir = path.dirname(file);
+  fs.mkdirSync(dir, { recursive: true });
+  const suffix = `${process.pid}-${crypto.randomBytes(6).toString('hex')}`;
+  const temp = `${file}.${suffix}.tmp`;
+  fs.writeFileSync(temp, content, { encoding: 'utf8', mode });
+  fs.renameSync(temp, file);
+}
+
+function logCrash(hook, error) {
+  try {
+    const dir = path.join(PROJECT_ROOT, '.codex', 'hooks', '.logs');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.appendFileSync(
+      path.join(dir, 'hook-log.jsonl'),
+      `${JSON.stringify({
+        ts: new Date().toISOString(),
+        hook,
+        status: 'crash',
+        error: String(error?.message || error)
+      })}\n`
+    );
+  } catch {
+    // Hook failures remain fail-open unless the hook explicitly denies.
+  }
+}
+
+module.exports = {
+  PROJECT_ROOT,
+  atomicWrite,
+  getHookContext,
+  logCrash,
+  readPayload,
+  readRuntime,
+  resolveProjectPath,
+  resolveSessionCwd
+};

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

@@ -0,0 +1,199 @@
+'use strict';
+
+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 = new RegExp(
+  '^(?:file_?paths?|paths?|search_?paths?|'
+  + '(?:source|target|destination)_?paths?|dirs?|director(?:y|ies)|'
+  + 'folders?|cwd|root|locations?|uris?)$',
+  'i'
+);
+const GLOB_KEYS = /(?:^|_)(?:glob|globs|pattern|patterns)$/i;
+function clean(value) {
+  return String(value || '').trim().replace(/^['"`]+|['"`,:]+$/g, '');
+}
+function blockedSegment(value) {
+  return clean(value)
+    .replace(/\\/g, '/')
+    .split('/')
+    .find((segment) => BLOCKED_DIRS.has(segment));
+}
+function isBroadGlob(value) {
+  const candidate = clean(value);
+  return BROAD_GLOBS.some((rule) => rule.test(candidate));
+}
+function collectStructured(value, key, paths, globs) {
+  if (typeof value === 'string') {
+    if (PATH_KEYS.test(key)) paths.push(value);
+    if (GLOB_KEYS.test(key)) globs.push(value);
+    return;
+  }
+  if (Array.isArray(value)) {
+    if (PATH_KEYS.test(key)) paths.push(...value.filter((item) => typeof item === 'string'));
+    if (GLOB_KEYS.test(key)) globs.push(...value.filter((item) => typeof item === 'string'));
+    for (const item of value) collectStructured(item, '', paths, globs);
+    return;
+  }
+  if (!value || typeof value !== 'object') return;
+  for (const [childKey, child] of Object.entries(value)) {
+    collectStructured(child, childKey, paths, globs);
+  }
+}
+function shellTokens(command) {
+  const tokens = [];
+  let token = '';
+  let quote = '';
+  for (let index = 0; index < command.length; index += 1) {
+    const char = command[index];
+    if (quote) {
+      if (char === quote) quote = '';
+      else if (char === '\\' && quote === '"' && index + 1 < command.length) {
+        token += command[index += 1];
+      } else token += char;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+    } else if (char === '\n') {
+      if (token) tokens.push(token);
+      token = '';
+      tokens.push('|');
+    } else if (/\s/.test(char)) {
+      if (token) tokens.push(token);
+      token = '';
+    } else if (';&|'.includes(char)) {
+      if (token) tokens.push(token);
+      token = '';
+      const pair = command.slice(index, index + 2);
+      if (pair === '&&' || pair === '||') index += 1;
+      tokens.push('|');
+    } else {
+      token += char;
+    }
+  }
+  if (token) tokens.push(token);
+  return tokens;
+}
+function commandGroups(command) {
+  const groups = [[]];
+  for (const token of shellTokens(command)) {
+    if (token === '|') groups.push([]);
+    else groups[groups.length - 1].push(clean(token));
+  }
+  return groups.filter((group) => group.length);
+}
+
+function positional(tokens, optionsWithValue = new Set()) {
+  const out = [];
+  for (let index = 1; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (optionsWithValue.has(token)) index += 1;
+    else if (!token.startsWith('-') || token === '-') out.push(token);
+  }
+  return out;
+}
+
+function readerOptionPaths(name, tokens) {
+  if (!['rg', 'grep', 'sed'].includes(name)) return [];
+  const paths = [];
+  for (let index = 1; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token === '-f' || token === '--file') {
+      if (tokens[index + 1]) paths.push(tokens[index + 1]);
+      index += 1;
+    } else if (token.startsWith('--file=')) {
+      paths.push(token.slice('--file='.length));
+    }
+  }
+  return paths;
+}
+
+function findRoots(tokens) {
+  const roots = [];
+  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;
+  for (; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token.startsWith('-') || ['!', '(', ')'].includes(token)) break;
+    roots.push(token);
+  }
+  return roots;
+}
+
+function commandPaths(group, globs) {
+  const commandIndex = group.findIndex((token) => (
+    token && !/^[A-Za-z_][A-Za-z0-9_]*=/.test(token)
+  ));
+  if (commandIndex < 0) return [];
+  const tokens = group.slice(commandIndex);
+  while (['sudo', 'env', 'time', 'command'].includes(tokens[0])) tokens.shift();
+  if (!tokens.length) return [];
+  const name = tokens[0].replace(/\\/g, '/').split('/').pop();
+  const optionPaths = readerOptionPaths(name, tokens);
+
+  for (let index = 1; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token === '-g' || token === '--glob' || token === '--iglob') {
+      if (tokens[index + 1]) globs.push(tokens[index + 1]);
+    } else if (/^--(?:i?glob)=/.test(token)) {
+      globs.push(token.slice(token.indexOf('=') + 1));
+    }
+  }
+
+  if (name === 'rg' || name === 'grep') {
+    const values = positional(tokens, new Set([
+      '-e', '--regexp', '-f', '--file', '-g', '--glob', '--iglob',
+      '-t', '--type', '-T', '--type-not'
+    ]));
+    const explicitPattern = tokens.some((token) => token === '-e' || token === '--regexp');
+    const fileMode = tokens.includes('--files');
+    return [...optionPaths, ...(explicitPattern || fileMode ? values : values.slice(1))];
+  }
+  if (name === 'sed') {
+    const values = positional(tokens, new Set(['-e', '--expression', '-f', '--file']));
+    const explicitScript = tokens.some((token) => (
+      ['-e', '--expression', '-f', '--file'].includes(token)
+    ));
+    return [...optionPaths, ...(explicitScript ? values : values.slice(1))];
+  }
+  if (name === 'find') return findRoots(tokens);
+  if (['cat', 'head', 'tail', 'ls', 'wc', 'du', 'tree', 'file', 'stat', 'cd', 'pushd', 'source', '.'].includes(name)) {
+    return positional(tokens, new Set(['-n', '--lines', '-c', '--bytes']));
+  }
+  return tokens.filter((token) => (
+    /^(?:\.{0,2}[\\/]|~[\\/])/.test(token)
+    || (token.includes('/') && blockedSegment(token))
+  ));
+}
+
+function inspectInput(input) {
+  const paths = [];
+  const globs = [];
+  collectStructured(input, '', paths, globs);
+  const command = typeof input?.command === 'string'
+    ? input.command
+    : typeof input?.cmd === 'string' ? input.cmd : '';
+  for (const group of commandGroups(command)) {
+    paths.push(...commandPaths(group, globs));
+  }
+  return {
+    broadGlob: globs.find(isBroadGlob),
+    blockedPath: paths.map((requested) => ({
+      requested,
+      blocked: blockedSegment(requested)
+    })).find((result) => result.blocked)
+  };
+}
+
+module.exports = {
+  BLOCKED_DIRS,
+  inspectInput
+};