@zhijiewang/openharness 2.8.0 → 2.10.0

package/dist/harness/plugins.js

@@ -12,10 +12,31 @@
  */
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, relative } from "node:path";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
 const PROJECT_SKILLS_DIR = join(".oh", "skills");
 const GLOBAL_SKILLS_DIR = join(homedir(), ".oh", "skills");
-/** Parse YAML frontmatter from a skill markdown file */
+// Claude Code ecosystem mirror paths (Anthropic convention)
+const CC_PROJECT_SKILLS_DIR = join(".claude", "skills");
+const CC_GLOBAL_SKILLS_DIR = join(homedir(), ".claude", "skills");
+// Bundled skills shipped with the openharness package itself.
+// At runtime this resolves to <package-root>/data/skills/ both in dev (src/) and prod (dist/).
+const BUNDLED_SKILLS_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "data", "skills");
+/** Parse a frontmatter list value. Accepts `[a, b]` (YAML inline) or `a b c` (space-separated, Anthropic spec). */
+function parseListValue(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
+        return trimmed
+            .slice(1, -1)
+            .split(",")
+            .map((t) => t.trim())
+            .filter(Boolean);
+    }
+    // Strip surrounding quotes if present
+    const unquoted = trimmed.replace(/^["']|["']$/g, "");
+    return unquoted.split(/\s+/).filter(Boolean);
+}
+/** Parse YAML frontmatter from a skill markdown file. Accepts both OH camelCase and Anthropic kebab-case. */
 function parseSkillFrontmatter(content) {
     const match = content.match(/^---\n([\s\S]*?)\n---/);
     if (!match)
@@ -28,33 +49,74 @@ function parseSkillFrontmatter(content) {
     const descMatch = frontmatter.match(/^description:\s*(.+)$/m);
     if (descMatch)
         result.description = descMatch[1].trim();
+    // trigger: OH-native field; when-to-use / whenToUse: Anthropic-style hint (also used as trigger fallback)
     const triggerMatch = frontmatter.match(/^trigger:\s*(.+)$/m);
     if (triggerMatch)
         result.trigger = triggerMatch[1].trim();
-    const toolsMatch = frontmatter.match(/^tools:\s*\[(.+)\]$/m);
-    if (toolsMatch)
-        result.tools = toolsMatch[1].split(",").map((t) => t.trim());
-    // Also parse allowedTools (used by built-in skills) and merge with tools
-    const allowedToolsMatch = frontmatter.match(/^allowedTools:\s*\[(.+)\]$/m);
-    if (allowedToolsMatch) {
-        const allowed = allowedToolsMatch[1].split(",").map((t) => t.trim());
-        result.tools = result.tools ? [...new Set([...result.tools, ...allowed])] : allowed;
+    const whenToUseMatch = frontmatter.match(/^(?:when-to-use|whenToUse):\s*(.+)$/m);
+    if (whenToUseMatch)
+        result.whenToUse = whenToUseMatch[1].trim();
+    // tools / allowedTools / allowed-tools — array OR space-separated. Merge all forms found.
+    const toolsCollected = new Set();
+    for (const re of [/^tools:\s*(.+)$/m, /^allowedTools:\s*(.+)$/m, /^allowed-tools:\s*(.+)$/m]) {
+        const m = frontmatter.match(re);
+        if (m)
+            for (const t of parseListValue(m[1]))
+                toolsCollected.add(t);
     }
-    const argsMatch = frontmatter.match(/^args:\s*\[(.+)\]$/m);
+    if (toolsCollected.size > 0)
+        result.tools = [...toolsCollected];
+    // args / argument-hint
+    const argsMatch = frontmatter.match(/^(?:args|argument-hint):\s*(.+)$/m);
     if (argsMatch)
-        result.args = argsMatch[1].split(",").map((a) => a.trim());
+        result.args = parseListValue(argsMatch[1]);
     // invokeModel: false OR disable-model-invocation: true → hidden from system prompt
     if (frontmatter.match(/^invokeModel:\s*false$/m) || frontmatter.match(/^disable-model-invocation:\s*true$/m)) {
         result.invokeModel = false;
     }
+    // license: SPDX identifier (e.g. MIT, Apache-2.0)
+    const licenseMatch = frontmatter.match(/^license:\s*(.+)$/m);
+    if (licenseMatch)
+        result.license = licenseMatch[1].trim().replace(/^["']|["']$/g, "");
+    // paths: glob list — scopes auto-surfacing to matching files
+    const pathsMatch = frontmatter.match(/^paths:\s*(.+)$/m);
+    if (pathsMatch)
+        result.paths = parseListValue(pathsMatch[1]);
+    // context: "default" | "fork" — when "fork", skill runs in a new sub-agent context
+    const contextMatch = frontmatter.match(/^context:\s*(.+)$/m);
+    if (contextMatch) {
+        const v = contextMatch[1].trim().replace(/^["']|["']$/g, "");
+        if (v === "fork" || v === "default")
+            result.context = v;
+    }
+    // agent: sub-agent type name (only meaningful when context: fork)
+    const agentMatch = frontmatter.match(/^agent:\s*(.+)$/m);
+    if (agentMatch)
+        result.agent = agentMatch[1].trim().replace(/^["']|["']$/g, "");
     return result;
 }
-/** Recursively collect all .md files from a directory tree */
+/** Recursively collect skill .md files from a directory tree.
+ * Anthropic / Claude Code convention: a directory containing `SKILL.md` is a single
+ * directory-packaged skill — only the SKILL.md surfaces; sibling .md files are
+ * companion documentation (referenced via Read at runtime). Directories without
+ * SKILL.md fall through to the legacy flat-file behavior (every .md is a skill).
+ */
 function walkMdFiles(dir) {
     if (!existsSync(dir))
         return [];
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    // Directory-packaged skill: only SKILL.md counts; siblings are companions.
+    if (entries.includes("SKILL.md")) {
+        return [join(dir, "SKILL.md")];
+    }
     const results = [];
-    for (const entry of readdirSync(dir)) {
+    for (const entry of entries) {
         const full = join(dir, entry);
         try {
             if (statSync(full).isDirectory()) {
@@ -86,6 +148,11 @@ function loadSkillsFromDir(dir, source) {
                 trigger: meta.trigger,
                 tools: meta.tools,
                 args: meta.args,
+                whenToUse: meta.whenToUse,
+                license: meta.license,
+                paths: meta.paths,
+                context: meta.context,
+                agent: meta.agent,
                 content,
                 filePath,
                 source,
@@ -98,11 +165,17 @@ function loadSkillsFromDir(dir, source) {
     })
         .filter((s) => s !== null);
 }
-/** Discover all available skills from project + global dirs + installed plugins */
+/** Discover all available skills from bundled + project + global dirs + installed plugins */
 export function discoverSkills() {
     const skills = [];
+    // Bundled (shipped with the openharness package)
+    skills.push(...loadSkillsFromDir(BUNDLED_SKILLS_DIR, "bundled"));
+    // OH-native paths
     skills.push(...loadSkillsFromDir(PROJECT_SKILLS_DIR, "project"));
     skills.push(...loadSkillsFromDir(GLOBAL_SKILLS_DIR, "global"));
+    // Claude Code ecosystem mirror paths — same source labels (project/global)
+    skills.push(...loadSkillsFromDir(CC_PROJECT_SKILLS_DIR, "project"));
+    skills.push(...loadSkillsFromDir(CC_GLOBAL_SKILLS_DIR, "global"));
     // Load skills from installed marketplace plugins (namespaced as plugin-name:skill-name)
     try {
         const { getInstalledPlugins } = require("./marketplace.js");
@@ -119,14 +192,22 @@ export function discoverSkills() {
     catch {
         /* marketplace module may not be loaded yet */
     }
-    return skills;
+    // De-duplicate by name+filePath: if same skill appears in multiple paths (e.g. CC mirror), keep first.
+    const seen = new Set();
+    return skills.filter((s) => {
+        const key = `${s.name}::${s.filePath}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
 }
 /** Find a skill by name (case-insensitive) */
 export function findSkill(name) {
     const skills = discoverSkills();
     return skills.find((s) => s.name.toLowerCase() === name.toLowerCase()) ?? null;
 }
-/** Find skills that match a trigger condition */
+/** Find skills that match a trigger condition (substring match against `trigger` field). */
 export function findTriggeredSkills(userMessage) {
     const skills = discoverSkills();
     return skills.filter((s) => {

package/dist/harness/session-db.d.ts

@@ -48,7 +48,14 @@ export declare function sessionToIndexEntry(session: Session): SessionIndexEntry
  * Rebuilds the FTS5 index from session JSON files on disk.
  */
 export declare function rebuildIndex(db: Database.Database, sessionsDir?: string): number;
-/** Get a shared DB connection (opens once, reuses thereafter) */
+/**
+ * Get a shared DB connection (opens once, reuses thereafter).
+ *
+ * Honors the `OH_SESSION_DB_PATH` environment variable for test isolation.
+ * When the env var changes between calls, the old singleton is closed and a
+ * new one is opened at the new path — this lets tests point at a tmp dir
+ * without leaking into the user's real `~/.oh/sessions.db`.
+ */
 export declare function getSessionDb(): Database.Database;
 /** Close the singleton connection (call on process exit) */
 export declare function closeGlobalSessionDb(): void;

package/dist/harness/session-db.js

@@ -145,11 +145,32 @@ export function rebuildIndex(db, sessionsDir) {
 }
 // ── Singleton Connection ──
 let _singletonDb = null;
-/** Get a shared DB connection (opens once, reuses thereafter) */
+let _singletonDbPath = null;
+/**
+ * Get a shared DB connection (opens once, reuses thereafter).
+ *
+ * Honors the `OH_SESSION_DB_PATH` environment variable for test isolation.
+ * When the env var changes between calls, the old singleton is closed and a
+ * new one is opened at the new path — this lets tests point at a tmp dir
+ * without leaking into the user's real `~/.oh/sessions.db`.
+ */
 export function getSessionDb() {
-    if (!_singletonDb) {
-        _singletonDb = openSessionDb();
+    const envPath = process.env.OH_SESSION_DB_PATH;
+    const targetPath = envPath || DEFAULT_DB_PATH;
+    if (_singletonDb && _singletonDbPath === targetPath) {
+        return _singletonDb;
+    }
+    if (_singletonDb) {
+        try {
+            _singletonDb.close();
+        }
+        catch {
+            /* ignore */
+        }
+        _singletonDb = null;
     }
+    _singletonDb = openSessionDb(targetPath);
+    _singletonDbPath = targetPath;
     return _singletonDb;
 }
 /** Close the singleton connection (call on process exit) */

package/dist/harness/skill-registry.d.ts

@@ -1,6 +1,8 @@
 /**
  * Skills Registry — search and install community skills from a remote registry.
  */
+/** SPDX identifiers for licenses we install without explicit user acceptance. */
+export declare const PERMISSIVE_LICENSES: Set<string>;
 export type RegistrySkill = {
     name: string;
     description: string;
@@ -8,6 +10,14 @@ export type RegistrySkill = {
     version: string;
     source: string;
     tags: string[];
+    /** SPDX license identifier (e.g. "MIT"). Required for new entries; absent for legacy. */
+    license?: string;
+    /** Attribution string to preserve when installing (e.g. "© 2025 Jesse Vincent"). */
+    attribution?: string;
+    /** Upstream homepage / repo URL. */
+    upstream?: string;
+    /** When false, skill cannot be installed via this command — only linked to upstream. Used for viral licenses (CC-BY-SA, GPL). */
+    installable?: boolean;
 };
 export type Registry = {
     skills: RegistrySkill[];
@@ -16,6 +26,20 @@ export type Registry = {
 export declare function fetchRegistry(url?: string): Promise<Registry>;
 /** Search registry by query (matches name, description, tags) */
 export declare function searchRegistry(registry: Registry, query: string): RegistrySkill[];
-/** Install a skill from the registry to ~/.oh/skills/ */
-export declare function installSkill(skill: RegistrySkill): Promise<string>;
+/** Result returned by installSkill — either success with path, or refusal with reason. */
+export type InstallResult = {
+    ok: true;
+    filePath: string;
+} | {
+    ok: false;
+    reason: "not-installable" | "license-not-accepted";
+    message: string;
+};
+/** Install a skill from the registry to ~/.oh/skills/.
+ * Refuses non-permissive licenses unless `acceptLicense` matches the entry's license.
+ * Refuses entries with `installable: false` (e.g. viral-license skills that must be installed upstream).
+ */
+export declare function installSkill(skill: RegistrySkill, opts?: {
+    acceptLicense?: string;
+}): Promise<InstallResult>;
 //# sourceMappingURL=skill-registry.d.ts.map

package/dist/harness/skill-registry.js

@@ -6,6 +6,16 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 const DEFAULT_REGISTRY_URL = "https://raw.githubusercontent.com/zhijiewong/openharness/main/data/registry.json";
 const GLOBAL_SKILLS_DIR = join(homedir(), ".oh", "skills");
+/** SPDX identifiers for licenses we install without explicit user acceptance. */
+export const PERMISSIVE_LICENSES = new Set([
+    "MIT",
+    "Apache-2.0",
+    "BSD-2-Clause",
+    "BSD-3-Clause",
+    "ISC",
+    "CC0-1.0",
+    "Unlicense",
+]);
 /** Fetch the registry from remote URL */
 export async function fetchRegistry(url = DEFAULT_REGISTRY_URL) {
     const response = await fetch(url);
@@ -20,16 +30,44 @@ export function searchRegistry(registry, query) {
         s.description.toLowerCase().includes(q) ||
         s.tags.some((t) => t.toLowerCase().includes(q)));
 }
-/** Install a skill from the registry to ~/.oh/skills/ */
-export async function installSkill(skill) {
+/** Install a skill from the registry to ~/.oh/skills/.
+ * Refuses non-permissive licenses unless `acceptLicense` matches the entry's license.
+ * Refuses entries with `installable: false` (e.g. viral-license skills that must be installed upstream).
+ */
+export async function installSkill(skill, opts = {}) {
+    // Gate 1: link-only entries
+    if (skill.installable === false) {
+        const upstream = skill.upstream ? ` Visit ${skill.upstream} to install under its license terms.` : "";
+        return {
+            ok: false,
+            reason: "not-installable",
+            message: `Skill "${skill.name}" is link-only (license: ${skill.license ?? "unknown"}).${upstream}`,
+        };
+    }
+    // Gate 2: license check
+    if (skill.license && !PERMISSIVE_LICENSES.has(skill.license)) {
+        if (opts.acceptLicense !== skill.license) {
+            return {
+                ok: false,
+                reason: "license-not-accepted",
+                message: `Skill "${skill.name}" is licensed under ${skill.license}, which is not in the auto-install allowlist.\n` +
+                    `To install, re-run with --accept-license=${skill.license} to acknowledge its terms.`,
+            };
+        }
+    }
     const response = await fetch(skill.source);
     if (!response.ok)
         throw new Error(`Failed to download skill: ${response.status}`);
-    const content = await response.text();
+    let content = await response.text();
+    // Preserve attribution by prepending an HTML comment if present and not already in the file
+    if (skill.attribution && !content.includes(skill.attribution)) {
+        const header = `<!-- Source: ${skill.upstream ?? skill.source}\n     License: ${skill.license ?? "unknown"}\n     ${skill.attribution} -->\n`;
+        content = header + content;
+    }
     mkdirSync(GLOBAL_SKILLS_DIR, { recursive: true });
     const slug = skill.name.toLowerCase().replace(/[^a-z0-9]+/g, "-");
     const filePath = join(GLOBAL_SKILLS_DIR, `${slug}.md`);
     writeFileSync(filePath, content);
-    return filePath;
+    return { ok: true, filePath };
 }
 //# sourceMappingURL=skill-registry.js.map

package/dist/tools/AgentTool/index.d.ts

@@ -13,8 +13,8 @@ declare const inputSchema: z.ZodObject<{
     prompt: string;
     model?: string | undefined;
     description?: string | undefined;
-    isolated?: boolean | undefined;
     isolation?: "worktree" | undefined;
+    isolated?: boolean | undefined;
     run_in_background?: boolean | undefined;
     subagent_type?: string | undefined;
     allowed_tools?: string[] | undefined;
@@ -22,8 +22,8 @@ declare const inputSchema: z.ZodObject<{
     prompt: string;
     model?: string | undefined;
     description?: string | undefined;
-    isolated?: boolean | undefined;
     isolation?: "worktree" | undefined;
+    isolated?: boolean | undefined;
     run_in_background?: boolean | undefined;
     subagent_type?: string | undefined;
     allowed_tools?: string[] | undefined;

package/dist/tools/DiagnosticsTool/index.d.ts

@@ -6,8 +6,8 @@ declare const inputSchema: z.ZodObject<{
     line: z.ZodOptional<z.ZodNumber>;
     character: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
-    file_path: string;
     action: "diagnostics" | "definition" | "references" | "hover";
+    file_path: string;
     line?: number | undefined;
     character?: number | undefined;
 }, {

package/dist/tools/GrepTool/index.d.ts

@@ -17,30 +17,30 @@ declare const inputSchema: z.ZodObject<{
     "-n": z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     pattern: string;
-    path?: string | undefined;
     type?: string | undefined;
+    "-i"?: boolean | undefined;
+    path?: string | undefined;
+    context?: number | undefined;
     glob?: string | undefined;
     offset?: number | undefined;
-    context?: number | undefined;
     output_mode?: "content" | "files_with_matches" | "count" | undefined;
     head_limit?: number | undefined;
     multiline?: boolean | undefined;
-    "-i"?: boolean | undefined;
     "-A"?: number | undefined;
     "-B"?: number | undefined;
     "-C"?: number | undefined;
     "-n"?: boolean | undefined;
 }, {
     pattern: string;
-    path?: string | undefined;
     type?: string | undefined;
+    "-i"?: boolean | undefined;
+    path?: string | undefined;
+    context?: number | undefined;
     glob?: string | undefined;
     offset?: number | undefined;
-    context?: number | undefined;
     output_mode?: "content" | "files_with_matches" | "count" | undefined;
     head_limit?: number | undefined;
     multiline?: boolean | undefined;
-    "-i"?: boolean | undefined;
     "-A"?: number | undefined;
     "-B"?: number | undefined;
     "-C"?: number | undefined;

package/dist/tools/MemoryTool/index.d.ts

@@ -9,20 +9,20 @@ declare const inputSchema: z.ZodObject<{
     query: z.ZodOptional<z.ZodString>;
     global: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
-    action: "search" | "list" | "save";
+    action: "search" | "save" | "list";
     content?: string | undefined;
     type?: "user" | "convention" | "preference" | "project" | "debugging" | "feedback" | "reference" | undefined;
-    global?: boolean | undefined;
     name?: string | undefined;
     description?: string | undefined;
+    global?: boolean | undefined;
     query?: string | undefined;
 }, {
-    action: "search" | "list" | "save";
+    action: "search" | "save" | "list";
     content?: string | undefined;
     type?: "user" | "convention" | "preference" | "project" | "debugging" | "feedback" | "reference" | undefined;
-    global?: boolean | undefined;
     name?: string | undefined;
     description?: string | undefined;
+    global?: boolean | undefined;
     query?: string | undefined;
 }>;
 export declare const MemoryTool: Tool<typeof inputSchema>;

package/dist/tools/MonitorTool/index.js

@@ -78,7 +78,11 @@ export const MonitorTool = {
                 for (const line of parts)
                     handleLine(line);
             });
-            proc.on("exit", (code) => {
+            // Use "close" rather than "exit": "exit" can fire before stdout data
+            // has been fully drained on fast-exiting commands, causing CI flakiness
+            // where output appears empty. "close" is guaranteed to fire after all
+            // stdio streams have closed.
+            proc.on("close", (code) => {
                 if (!settled) {
                     settled = true;
                     clearTimeout(timer);

package/dist/types/permissions.js

@@ -1,7 +1,7 @@
 /**
  * Permission types — tool permission context and risk-based gating.
  */
-import { analyzeBashCommand } from "../utils/bash-safety.js";
+import { analyzeBashCommand, isReadOnlyBashCommand, splitCommands, stripProcessWrappers, } from "../utils/bash-safety.js";
 /** Tools auto-approved in acceptEdits mode */
 const EDIT_SAFE_TOOLS = new Set([
     "FileRead",
@@ -46,42 +46,94 @@ function matchArgGlob(pattern, value) {
     }
 }
 /** Find the first matching tool permission rule */
-function findToolRule(rules, toolName, toolInput) {
-    if (!rules || rules.length === 0)
-        return undefined;
-    return rules.find((r) => {
-        const { toolName: specToolName, argPattern } = parseToolSpecifier(r.tool);
-        // Check tool name match (with prefix * support)
-        if (!matchToolPattern(specToolName, toolName))
-            return false;
-        // If rule has an inline argument pattern (e.g., "Bash(npm run *)")
-        if (argPattern && toolInput) {
-            const input = toolInput;
-            // For Bash: match against command string
-            if (toolName === "Bash" && typeof input.command === "string") {
-                return matchArgGlob(argPattern, input.command);
+/**
+ * Priority of a rule action for "most restrictive wins" tie-breaking across
+ * subcommand matches: deny > ask > allow. Rules that don't apply return -1.
+ */
+function actionPriority(action) {
+    return action === "deny" ? 2 : action === "ask" ? 1 : 0;
+}
+function matchesSingleRule(r, toolName, toolInput) {
+    const { toolName: specToolName, argPattern } = parseToolSpecifier(r.tool);
+    if (!matchToolPattern(specToolName, toolName))
+        return false;
+    if (argPattern && toolInput) {
+        const input = toolInput;
+        if (toolName === "Bash" && typeof input.command === "string") {
+            return matchArgGlob(argPattern, input.command);
+        }
+        if (["Edit", "Write", "Read"].includes(toolName) && typeof input.file_path === "string") {
+            return matchArgGlob(argPattern, input.file_path);
+        }
+        return false;
+    }
+    if (r.pattern && toolInput && toolName === "Bash") {
+        const command = toolInput?.command;
+        if (typeof command === "string") {
+            try {
+                return new RegExp(r.pattern).test(command);
             }
-            // For file tools: match against file_path
-            if (["Edit", "Write", "Read"].includes(toolName) && typeof input.file_path === "string") {
-                return matchArgGlob(argPattern, input.file_path);
+            catch {
+                return false;
             }
-            return false; // Has pattern but no matching field
         }
-        // Legacy: separate pattern field (regex) for Bash commands
-        if (r.pattern && toolInput && toolName === "Bash") {
-            const command = toolInput?.command;
-            if (typeof command === "string") {
-                try {
-                    return new RegExp(r.pattern).test(command);
-                }
-                catch {
-                    return false;
-                }
+        return false;
+    }
+    return true;
+}
+/**
+ * Match permission rules against a Bash command.
+ *
+ * For compound commands (`cmd1 && cmd2`, `a | b`, `x; y`), evaluate rules
+ * against each sub-command independently with "most restrictive wins"
+ * semantics: any sub-command matching a `deny` rule returns deny; else any
+ * `ask` match returns ask; else any `allow` match returns allow; else no
+ * match. Process wrappers (`timeout 10 cmd`, `nice -n 5 cmd`) are stripped
+ * before matching so the real underlying command is what gets checked.
+ *
+ * Security note: this closes a common class of bypasses like
+ * `git log && rm -rf /` where a naive full-line match would hit the `git log`
+ * allow rule and skip the deny on `rm`.
+ */
+function findBashRule(rules, command) {
+    const subs = splitCommands(command).map(stripProcessWrappers).filter(Boolean);
+    if (subs.length === 0)
+        return undefined;
+    let best;
+    let bestPriority = -1;
+    for (const sub of subs) {
+        const subInput = { command: sub };
+        for (const r of rules) {
+            if (!matchesSingleRule(r, "Bash", subInput))
+                continue;
+            const p = actionPriority(r.action);
+            if (p > bestPriority) {
+                best = r;
+                bestPriority = p;
+                if (p === 2)
+                    return best; // deny short-circuits
             }
-            return false;
         }
-        return true;
-    });
+    }
+    return best;
+}
+function findToolRule(rules, toolName, toolInput) {
+    if (!rules || rules.length === 0)
+        return undefined;
+    // Bash: always route through the compound-aware matcher. For single commands
+    // this just strips wrappers and does a normal rule search; for compound
+    // commands it evaluates each sub-command with most-restrictive-wins.
+    if (toolName === "Bash" && toolInput) {
+        const command = toolInput?.command;
+        if (typeof command === "string") {
+            const compoundMatch = findBashRule(rules, command);
+            if (compoundMatch)
+                return compoundMatch;
+            // Compound matcher returned nothing (single command or no match).
+            // Fall through to the default single-rule find below.
+        }
+    }
+    return rules.find((r) => matchesSingleRule(r, toolName, toolInput));
 }
 /** Cached tool permission rules — set by the REPL at startup */
 let toolPermissionRules;
@@ -103,23 +155,33 @@ export function checkPermission(mode, riskLevel, isReadOnly, toolName, toolInput
     }
     // Bash command safety analysis — detect destructive patterns
     let effectiveRisk = riskLevel;
+    let bashReadOnly = false;
     if (toolName === "Bash" && toolInput) {
         const command = toolInput?.command;
         if (typeof command === "string") {
-            const analysis = analyzeBashCommand(command);
-            if (analysis.level === "dangerous") {
-                effectiveRisk = "high";
+            // Read-only allowlist short-circuit (Claude Code parity). A pure
+            // inspection pipeline like `ls | head` or `git status` should not
+            // prompt the user in any permission mode that gates read-only work.
+            if (isReadOnlyBashCommand(command)) {
+                bashReadOnly = true;
+                effectiveRisk = "low";
             }
-            else if (analysis.level === "moderate" && effectiveRisk !== "high") {
-                effectiveRisk = "medium";
-            }
-            else if (analysis.level === "safe") {
-                effectiveRisk = "medium"; // bash is never fully "low" risk
+            else {
+                const analysis = analyzeBashCommand(command);
+                if (analysis.level === "dangerous") {
+                    effectiveRisk = "high";
+                }
+                else if (analysis.level === "moderate" && effectiveRisk !== "high") {
+                    effectiveRisk = "medium";
+                }
+                else if (analysis.level === "safe") {
+                    effectiveRisk = "medium"; // bash is never fully "low" risk
+                }
             }
         }
     }
-    // Always allow low-risk read-only
-    if (effectiveRisk === "low" && isReadOnly) {
+    // Always allow low-risk read-only (now includes Bash commands matching the allowlist)
+    if (effectiveRisk === "low" && (isReadOnly || bashReadOnly)) {
         return { allowed: true, reason: "auto-approved", riskLevel: effectiveRisk };
     }
     // bypassPermissions — approve everything unconditionally (CI/testing only)