@pugi/cli 0.1.0-alpha.3 → 0.1.0-alpha.5

package/dist/core/permission.js

@@ -1,4 +1,57 @@
 import { basename, resolve } from 'node:path';
+import { classifyBash, listDestructivePatterns, } from './bash-classifier.js';
+/**
+ * Map `PermissionAction.kind` to the `HookMatch.permission` taxonomy.
+ * The hook taxonomy uses `mcp`/`subagent` slots that the permission
+ * engine does not currently emit; `workflow` has no hook-side
+ * equivalent so it falls through as undefined (any matching hook with
+ * an explicit `permission` filter will not match).
+ */
+function toHookPermission(kind) {
+    switch (kind) {
+        case 'read':
+        case 'edit':
+        case 'bash':
+        case 'network':
+        case 'mcp':
+            return kind;
+        case 'workflow':
+            return undefined;
+    }
+}
+/**
+ * Fire the `PermissionRequest` hook for the given action and decision.
+ * Caller is the permission engine's user-facing surface — when the
+ * decision is `ask`, hooks can observe (and, with `onFailure: 'block'`,
+ * pre-empt) the prompt. The hook system does NOT replace the prompt —
+ * a `block` hook simply turns the decision into a refusal that the
+ * caller surfaces as a denial.
+ *
+ * Returns true when no blocking hook objected; false when at least one
+ * `onFailure: 'block'` hook returned a non-zero exit. Callers should
+ * treat false as "deny this action".
+ */
+export async function firePermissionRequestHook(action, decision, hooks, sessionId) {
+    hooks.resetBatch();
+    const ctx = {
+        sessionId,
+        event: 'PermissionRequest',
+        tool: action.tool,
+        permission: toHookPermission(action.kind),
+        path: action.kind === 'read' || action.kind === 'edit' ? action.target : undefined,
+        payload: { action, decision },
+    };
+    const matching = hooks.listMatching(ctx);
+    const results = await hooks.fire(ctx);
+    for (let i = 0; i < matching.length; i += 1) {
+        const hook = matching[i];
+        const result = results[i];
+        if (hook && result && hook.onFailure === 'block' && !result.ok) {
+            return false;
+        }
+    }
+    return true;
+}
 const protectedBasenames = new Set([
     '.env',
     '.npmrc',
@@ -9,98 +62,175 @@ const protectedBasenames = new Set([
     'id_ed25519',
 ]);
 const protectedSuffixes = ['.pem', '.key', '.crt', '.p12', '.dump', '.sql'];
-// Hard-deny list for `bash` actions. Substring match against the
-// normalized (trimmed, original-case) command — the model can
-// concatenate arguments any way it wants, but if ANY substring on
-// this list appears the command is refused before /bin/sh sees it.
-//
-// Coverage classes:
-//   - destructive filesystem wipes: rm -rf, dd, mkfs, shred, wipefs
-//   - destructive system ops: chmod 777, chown -R /, setuid bits
-//   - dangerous shell tricks: eval, fork bombs, /dev/sda writes
-//   - git history loss: reset --hard, clean -fdx
-//   - container / infra wipes: docker system prune, k8s delete --all
-//   - destructive SQL: DROP DATABASE / DROP TABLE
-//   - firewall disable: ufw disable, iptables -F
-//   - credential exfil to stdout: cat ~/.ssh/id_rsa, gpg --export
-//
-// Code Reviewer P1 2026-05-23 flagged the previous list as missing
-// dd/mkfs/chmod 777/eval/fork bomb — added below. List intentionally
-// errs toward over-block: a false positive blocks a destructive
-// pattern the human can `pugi bash -- run` manually with confirmation,
-// while a false negative is catastrophic.
-const destructiveBashPatterns = [
-    // Filesystem wipe
-    'rm -rf /',
-    'rm -rf ~',
-    'rm -rf .',
-    'rm -rf *',
-    'rm -rf "/',
-    'rm -rf "~',
-    'dd if=/dev/zero',
-    'dd if=/dev/random',
-    'dd of=/dev/sda',
-    'dd of=/dev/disk',
-    'mkfs',
-    'shred ',
-    'wipefs',
-    '> /dev/sda',
-    '> /dev/disk',
-    // Permission wipe
-    'chmod 777 /',
-    'chmod -R 777 /',
-    'chown -R root /',
-    // Shell tricks
-    ':(){ :|:& };:',
-    'eval "$',
-    "eval '$",
-    // Git history loss
-    'git reset --hard',
-    'git clean -fdx',
-    'git push --force origin main',
-    'git push -f origin main',
-    // Container / infra
-    'docker system prune',
-    'docker rm -f $(docker',
-    'kubectl delete --all',
-    // SQL destructive. Code Reviewer P2 retro 2026-05-23: the
-    // substring match was case-sensitive; lowercase `drop database`
-    // bypassed the gate. We now uppercase-normalise the target
-    // (`hardDenyReason` below) so both upper- and mixed-case SQL
-    // hits the same pattern. Patterns themselves stay uppercase
-    // since they're compared against the uppercased command.
-    'DROP DATABASE',
-    'DROP TABLE',
-    'TRUNCATE TABLE',
-    // Firewall / network
-    'ufw disable',
-    'iptables -F',
-    'iptables --flush',
-    // Credential exfil
-    'cat ~/.ssh/id_rsa',
-    'cat ~/.ssh/id_ed25519',
-    'gpg --export-secret',
-    // SSH config tampering — write paths only. Code Reviewer P2
-    // retro 2026-05-23: a bare `sshd_config` substring also blocked
-    // read-only `cat /etc/sshd_config` / `grep PermitRootLogin
-    // sshd_config`. Scoped to redirections + tee so the model can
-    // still inspect the file but cannot write to it through bash.
-    '> sshd_config',
-    '>> sshd_config',
-    '> /etc/ssh/sshd_config',
-    '>> /etc/ssh/sshd_config',
-    'tee sshd_config',
-    'tee /etc/ssh/sshd_config',
-    'tee -a sshd_config',
-    'tee -a /etc/ssh/sshd_config',
-    // History destruction
-    'history -c',
-    ' >/dev/null 2>&1; rm',
-];
+/**
+ * Hard-deny list. The list of destructive substrings now lives in
+ * `bash-classifier.ts::DESTRUCTIVE_PATTERNS`; this function exposes
+ * it as a list for callers (doctor, debug tooling) that need to
+ * audit the rule set without re-running `classifyBash`.
+ *
+ * Code Reviewer P2 retro 2026-05-23: previously this list was
+ * duplicated here as `destructiveBashPatterns`. Sprint α5.2 moves it
+ * into the classifier so the permission engine and the doctor surface
+ * cannot drift.
+ */
+export function destructiveBashPatternsList() {
+    return listDestructivePatterns();
+}
+/**
+ * Class-aware bash permission decision. The matrix:
+ *
+ *                     | plan | ask | acceptEdits | auto       | dontAsk | bypass
+ *  read               | allow| allow| allow      | allow      | allow   | allow
+ *  build_test         | deny | ask  | ask        | allow      | allow*  | allow
+ *  network            | deny | ask  | ask        | ask        | allow*  | allow
+ *  write_workspace    | deny | ask  | allow      | allow      | allow*  | allow
+ *  write_protected    | deny | ask  | ask        | ask        | deny    | ask
+ *  destructive        | deny | deny | deny       | deny       | deny    | deny**
+ *  unknown            | deny | ask  | ask        | ask        | deny    | ask
+ *
+ *  * dontAsk allows non-destructive classes when no settings rule
+ *    contradicts; the bare-mode policy is encoded in the table below.
+ *  ** destructive can be unlocked ONLY when ALL three hold:
+ *      - mode === 'bypassPermissions'
+ *      - PUGI_DESTRUCTIVE_OVERRIDE === '1'
+ *      - source === 'human'
+ *    The agent loop never sets `source: 'human'`, so even a runaway
+ *    agent in bypass mode cannot trigger a destructive deletion.
+ */
+export function evaluateBashPermission(cmd, mode, ctx) {
+    const classification = classifyBash(cmd, {
+        workspaceRoot: ctx.workspaceRoot,
+        additionalDirectories: ctx.additionalDirectories,
+    });
+    return decisionForClass(classification, mode, ctx);
+}
+function decisionForClass(classification, mode, ctx) {
+    const { class: klass, reason, matched } = classification;
+    const explain = `${reason}${matched ? ` [matched=${matched}]` : ''}`;
+    if (klass === 'destructive') {
+        const overrideOk = mode === 'bypassPermissions' &&
+            ctx.source === 'human' &&
+            process.env.PUGI_DESTRUCTIVE_OVERRIDE === '1';
+        if (overrideOk) {
+            return {
+                decision: 'allow',
+                reason: `${explain}; destructive override engaged (PUGI_DESTRUCTIVE_OVERRIDE=1, human source, bypassPermissions)`,
+                source: 'mode.bypassPermissions.destructive_override',
+            };
+        }
+        return {
+            decision: 'deny',
+            reason: `${explain}; destructive class is always denied`,
+            source: 'classifier.destructive',
+        };
+    }
+    switch (klass) {
+        case 'read':
+            return { decision: 'allow', reason: explain, source: `classifier.${klass}` };
+        case 'build_test':
+            return classAwareVerdict(mode, klass, explain, {
+                plan: 'deny',
+                ask: 'ask',
+                acceptEdits: 'ask',
+                auto: 'allow',
+                dontAsk: 'allow',
+                bypassPermissions: 'allow',
+            });
+        case 'network':
+            return classAwareVerdict(mode, klass, explain, {
+                plan: 'deny',
+                ask: 'ask',
+                acceptEdits: 'ask',
+                auto: 'ask',
+                dontAsk: 'allow',
+                bypassPermissions: 'allow',
+            });
+        case 'write_workspace':
+            return classAwareVerdict(mode, klass, explain, {
+                plan: 'deny',
+                ask: 'ask',
+                acceptEdits: 'allow',
+                auto: 'allow',
+                dontAsk: 'allow',
+                bypassPermissions: 'allow',
+            });
+        case 'write_protected':
+            return classAwareVerdict(mode, klass, explain, {
+                plan: 'deny',
+                ask: 'ask',
+                acceptEdits: 'ask',
+                auto: 'ask',
+                dontAsk: 'deny',
+                bypassPermissions: 'ask',
+            });
+        case 'unknown':
+            return classAwareVerdict(mode, klass, explain, {
+                plan: 'deny',
+                ask: 'ask',
+                acceptEdits: 'ask',
+                auto: 'ask',
+                dontAsk: 'deny',
+                bypassPermissions: 'ask',
+            });
+    }
+}
+function classAwareVerdict(mode, klass, reason, table) {
+    const verdict = table[mode];
+    const source = `classifier.${klass}.${mode}`;
+    switch (verdict) {
+        case 'allow':
+            return { decision: 'allow', reason, source };
+        case 'deny':
+            return { decision: 'deny', reason: `${reason}; ${mode} mode denies ${klass}`, source };
+        case 'ask':
+            return { decision: 'ask', reason, risk: riskForClass(klass) };
+    }
+}
+function riskForClass(klass) {
+    switch (klass) {
+        case 'read':
+            return 'low';
+        case 'build_test':
+        case 'write_workspace':
+            return 'medium';
+        case 'network':
+        case 'write_protected':
+        case 'unknown':
+        case 'destructive':
+            return 'high';
+    }
+}
 export function decidePermission(action, settings, root) {
-    const hardDeny = hardDenyReason(action);
-    if (hardDeny) {
-        return { decision: 'deny', reason: hardDeny, source: 'hard_deny' };
+    if (action.kind === 'bash') {
+        // Legacy callers (file-tools::bashTool, runtime/cli protected-file
+        // probe) still call `decidePermission` for bash. The class-aware
+        // engine is preferred; we route through it here so the hard-deny
+        // gate stays consistent regardless of entry point.
+        //
+        // Source defaults to 'agent' because every code path that calls
+        // `decidePermission({ kind: 'bash' })` today is reached through
+        // the engine loop. Direct human bash invocation goes through the
+        // new `evaluateBashPermission` with `source: 'human'`.
+        const decision = evaluateBashPermission(action.target, settings.permissions.mode, {
+            workspaceRoot: root,
+            additionalDirectories: [],
+            source: 'agent',
+        });
+        if (decision.decision === 'deny' && decision.source === 'classifier.destructive') {
+            // Locked-source identifier for the retro spec — the existing
+            // tests assert `source === 'hard_deny'`. Re-label so the
+            // semantic stays the same: a destructive command was blocked
+            // by the hard-deny gate.
+            return { ...decision, source: 'hard_deny' };
+        }
+        const signature = `${action.kind}:${action.target}`;
+        if (matchesAny(signature, settings.permissions.deny)) {
+            return { decision: 'deny', reason: `Denied by rule: ${signature}`, source: 'settings.deny' };
+        }
+        if (matchesAny(signature, settings.permissions.allow) && decision.decision !== 'deny') {
+            return { decision: 'allow', reason: `Allowed by rule: ${signature}`, source: 'settings.allow' };
+        }
+        return decision;
     }
     const protectedReason = protectedTargetReason(action, root);
     if (protectedReason) {
@@ -134,31 +264,6 @@ export function protectedTargetReason(action, root) {
     }
     return null;
 }
-function hardDenyReason(action) {
-    if (action.kind !== 'bash')
-        return null;
-    const normalized = action.target.trim();
-    // Patterns whose match must be case-insensitive — primarily SQL verbs
-    // that the model can emit as `drop database`, `Drop Database`, etc.
-    // Code Reviewer P2 retro 2026-05-23: substring match was previously
-    // case-sensitive so lowercase SQL silently bypassed the deny list.
-    // We compare an uppercased copy of the command against the uppercase
-    // patterns below; non-SQL patterns stay exact-match against the
-    // original-case target to avoid over-matching benign filenames.
-    const normalizedUpper = normalized.toUpperCase();
-    const caseInsensitivePatterns = new Set([
-        'DROP DATABASE',
-        'DROP TABLE',
-        'TRUNCATE TABLE',
-    ]);
-    const matched = destructiveBashPatterns.find((pattern) => {
-        if (caseInsensitivePatterns.has(pattern)) {
-            return normalizedUpper.includes(pattern);
-        }
-        return normalized.includes(pattern);
-    });
-    return matched ? `Destructive command blocked: ${matched}` : null;
-}
 function decisionForMode(mode, reason, source, risk) {
     switch (mode) {
         case 'plan':

package/dist/core/repl/cap-warning.js

@@ -0,0 +1,91 @@
+/**
+ * Client-side concurrent-subagent cap - Sprint α5.7 (ADR-0056
+ * acceptance #6, Mac safety memo
+ * `feedback_max_3_parallel_agents_mac_safety.md`).
+ *
+ * Mac-safety memo caps interactive concurrency at 3 active subagents
+ * per workstation. The REPL has its own client-side gate that mirrors
+ * the global rule for one workstation worth of dispatches:
+ *
+ *   - active count >= 3 → soft warning (operator may still dispatch).
+ *   - active count >= 5 → hard block unless the operator opted in via
+ *     PUGI_FORCE_PARALLEL=1.
+ *
+ * The gate is pure: callers pass the current active count and we return
+ * a verdict. The REPL session module reads the dispatcher event stream,
+ * tracks active dispatches, and consults this function before
+ * forwarding `/brief` to the controller.
+ *
+ * The hard cap matches the absolute ceiling cited in the Mac memo (3
+ * brand-recommended, 5 ABSOLUTE max with the env-flag escape hatch).
+ * Bumping either threshold is a memo update, not a code-only change.
+ */
+/**
+ * Soft warning threshold. At this many active subagents the REPL
+ * surfaces a non-blocking nudge. The operator can confirm and proceed.
+ */
+export const CAP_WARNING_THRESHOLD = 3;
+/**
+ * Hard block threshold. At this many active subagents the REPL refuses
+ * the new dispatch unless `PUGI_FORCE_PARALLEL=1` is in the environment.
+ */
+export const CAP_HARD_BLOCK_THRESHOLD = 5;
+/**
+ * Env flag operators set to override the hard cap. Documented in
+ * `pugi doctor` output and in the Mac safety memo. Set this to `1`,
+ * `true`, or `yes` to bypass. Anything else (including unset) leaves
+ * the cap enforced.
+ */
+export const FORCE_PARALLEL_ENV_VAR = 'PUGI_FORCE_PARALLEL';
+/**
+ * Compute the cap verdict given the current active subagent count and
+ * the operator's environment.
+ *
+ * The function is pure (no global state, no IO). Callers must pass the
+ * env they want considered - production callers pass process.env, tests
+ * pass a fixture so the gate is deterministic.
+ */
+export function evaluateCap(input) {
+    const active = Math.max(0, Math.floor(input.active));
+    const env = input.env ?? {};
+    const forceParallel = isForceParallelSet(env);
+    if (active >= CAP_HARD_BLOCK_THRESHOLD) {
+        if (forceParallel) {
+            return { kind: 'override', active, envVar: FORCE_PARALLEL_ENV_VAR };
+        }
+        return { kind: 'block', active, envVar: FORCE_PARALLEL_ENV_VAR };
+    }
+    if (active >= CAP_WARNING_THRESHOLD) {
+        return { kind: 'warn', active };
+    }
+    return { kind: 'allow' };
+}
+/**
+ * Render a one-line operator nudge for a non-allow verdict. The REPL
+ * appends this line to the conversation pane on its own row so the
+ * cyan colour token survives Ink's whitespace collapsing.
+ *
+ * Brand voice: power words `on watch`, `workforce`. No em dash, no
+ * emoji. Capacity rather than `agents` to avoid colliding with the
+ * `/agents` command name in the same frame.
+ */
+export function describeVerdict(verdict) {
+    switch (verdict.kind) {
+        case 'allow':
+            return '';
+        case 'warn':
+            return `Capacity nudge: ${verdict.active} agents already on watch - keep an eye on workstation load.`;
+        case 'block':
+            return `Capacity block: ${verdict.active} agents on watch is the absolute ceiling. Set ${verdict.envVar}=1 to override.`;
+        case 'override':
+            return `Capacity cap bypassed (${verdict.envVar}=1) - ${verdict.active} agents already on watch.`;
+    }
+}
+function isForceParallelSet(env) {
+    const raw = env[FORCE_PARALLEL_ENV_VAR];
+    if (typeof raw !== 'string')
+        return false;
+    const normalized = raw.trim().toLowerCase();
+    return normalized === '1' || normalized === 'true' || normalized === 'yes';
+}
+//# sourceMappingURL=cap-warning.js.map