phewsh 0.15.64 → 0.15.66

package/commands/ambient.js

@@ -27,6 +27,11 @@ const CLAUDE_SETTINGS = path.join(os.homedir(), '.claude', 'settings.json');
 
 const HOOK_START = { type: 'command', command: 'phewsh hook session-start' };
 const HOOK_END = { type: 'command', command: 'phewsh hook session-end' };
+// Opt-in Decision Gate enforcement (separate from ambient context sync). The
+// matcher scopes the hook to the tools the policy actually judges, so it never
+// fires on harmless reads.
+const HOOK_PRETOOL = { type: 'command', command: 'phewsh hook pre-tool' };
+const PRETOOL_MATCHER = 'Write|Edit|MultiEdit|NotebookEdit|Bash';
 
 // ANSI helpers (256-color per cli/lib/ui.js palette rules)
 const b = (s) => `\x1b[1m${s}\x1b[0m`;
@@ -97,6 +102,35 @@ function removeClaudeHooks() {
   return removed;
 }
 
+// ── Decision Gate enforcement (PreToolUse) — opt-in, reversible ──────────────
+function preToolGateApplied() {
+  const s = loadClaudeSettings();
+  return !!s && hasHook(s, 'PreToolUse', HOOK_PRETOOL.command);
+}
+
+function enablePreToolGate() {
+  const settings = loadClaudeSettings() || {};
+  settings.hooks = settings.hooks || {};
+  settings.hooks.PreToolUse = settings.hooks.PreToolUse || [];
+  if (hasHook(settings, 'PreToolUse', HOOK_PRETOOL.command)) return false;
+  settings.hooks.PreToolUse.push({ matcher: PRETOOL_MATCHER, hooks: [HOOK_PRETOOL] });
+  fs.writeFileSync(CLAUDE_SETTINGS, JSON.stringify(settings, null, 2));
+  return true;
+}
+
+function disablePreToolGate() {
+  const settings = loadClaudeSettings();
+  if (!settings?.hooks?.PreToolUse) return false;
+  const before = settings.hooks.PreToolUse.length;
+  settings.hooks.PreToolUse = settings.hooks.PreToolUse
+    .map(e => ({ ...e, hooks: (e.hooks || []).filter(h => h.command !== HOOK_PRETOOL.command) }))
+    .filter(e => e.hooks.length > 0);
+  if ((settings.hooks.PreToolUse || []).length === 0) delete settings.hooks.PreToolUse;
+  const changed = before !== (settings.hooks.PreToolUse?.length ?? 0);
+  if (changed) fs.writeFileSync(CLAUDE_SETTINGS, JSON.stringify(settings, null, 2));
+  return changed;
+}
+
 function showConsentScreen(harnesses) {
   console.log('');
   console.log(`  ${b(cream('PHEWSH ambient'))} ${sage('— continuity without launching phewsh')}`);
@@ -365,3 +399,6 @@ async function main() {
 
 module.exports = main;
 module.exports.ensureAuto = ensureAuto;
+module.exports.enablePreToolGate = enablePreToolGate;
+module.exports.disablePreToolGate = disablePreToolGate;
+module.exports.preToolGateApplied = preToolGateApplied;

package/commands/gate.js

@@ -373,6 +373,7 @@ async function main() {
   if (subcommand === 'update' || subcommand === 'edit') { await update(); return; }
   if (subcommand === 'pause') { pause(); return; }
   if (subcommand === 'resume') { resume(); return; }
+  if (subcommand === 'enforce') { enforce(args[1]); return; }
   if (subcommand === 'reset') {
     let removed = false;
     const project = loadProjectJson();
@@ -391,6 +392,34 @@ async function main() {
   console.log(`\n  Unknown: ${subcommand}. Run \`phewsh gate --help\`.\n`);
 }
 
+// Opt-in deterministic enforcement: register/unregister the Claude Code
+// PreToolUse hook that makes the Decision Gate act BEFORE a tool runs. Reversible,
+// Claude-Code-only for now (it's the one provider with a real veto hook).
+function enforce(action) {
+  let amb;
+  try { amb = require('./ambient'); } catch { console.log('\n  Enforcement unavailable.\n'); return; }
+  const on = (action || 'status').toLowerCase();
+  if (on === 'on' || on === 'enable') {
+    const changed = amb.enablePreToolGate();
+    console.log(changed
+      ? `\n  ${green('●')} Gate enforcement ${green('ON')} — Claude Code asks/denies on protected-path writes and high-blast-radius commands before they run.\n  ${g('Reversible:')} phewsh gate enforce off\n`
+      : `\n  Gate enforcement already on.\n`);
+    return;
+  }
+  if (on === 'off' || on === 'disable') {
+    const changed = amb.disablePreToolGate();
+    console.log(changed ? `\n  Gate enforcement ${yellow('OFF')} — PreToolUse hook removed.\n` : `\n  Gate enforcement was not on.\n`);
+    return;
+  }
+  // status
+  const applied = amb.preToolGateApplied();
+  console.log(`\n  Gate enforcement: ${applied ? green('ON') : g('off')} ${g('(Claude Code PreToolUse)')}`);
+  console.log(`  ${g('Turn on:')} phewsh gate enforce on   ${g('· off:')} phewsh gate enforce off`);
+  console.log(`  ${g('What it does: deny writes to protected paths (.env, keys, .git/…),')}`);
+  console.log(`  ${g('ask before high-blast-radius shell (rm -rf, force-push, sudo…).')}`);
+  console.log(`  ${g('Opt-in, local-only, fail-open. Other tools: advisory only for now.')}\n`);
+}
+
 module.exports = main;
 
 main().catch(err => {

package/commands/hook.js

@@ -163,10 +163,63 @@ function sessionEnd() {
   setTimeout(() => { appendBreadcrumb('session-end'); process.exit(0); }, 1500);
 }
 
+// Load the Decision Gate context (constraints + protected files) for the project
+// being worked in. Best-effort: missing/garbled → empty context (gate allows).
+function loadGateContext(cwd) {
+  try {
+    const pj = JSON.parse(fs.readFileSync(path.join(cwd, '.intent', 'project.json'), 'utf-8'));
+    const dg = pj.decisionGate || {};
+    return {
+      constraints: dg.constraints || {},
+      protectedFiles: dg.protectedFiles || pj.protectedFiles || [],
+    };
+  } catch { return { constraints: {}, protectedFiles: [] }; }
+}
+
+// PreToolUse adapter — the Decision Gate acting BEFORE a tool runs. Reads Claude
+// Code's PreToolUse JSON from stdin, evaluates against the project's constraints
+// + protected files, and emits a permission decision. FAIL-SAFE: any error, no
+// stdin, or no policy hit → exit 0 (allow). A broken gate must never trap you.
+// It logs only a redacted decision line (never the tool payload).
+function preTool() {
+  try {
+    if (process.stdin.isTTY) process.exit(0); // not a real hook invocation
+    const { evaluateAction, auditLine } = require('../lib/gate-policy');
+    let raw = '';
+    try { raw = fs.readFileSync(0, 'utf-8'); } catch { process.exit(0); }
+    let payload = {};
+    try { payload = JSON.parse(raw || '{}'); } catch { process.exit(0); }
+
+    const cwd = payload.cwd || process.cwd();
+    const envelope = {
+      toolName: payload.tool_name || payload.toolName,
+      toolInput: payload.tool_input || payload.toolInput || {},
+      ...loadGateContext(cwd),
+    };
+    let result = { decision: 'allow', reason: '' };
+    try { result = evaluateAction(envelope); } catch { process.exit(0); }
+
+    if (result.decision !== 'allow') {
+      try { appendBreadcrumb('pre-tool', { decision: result.decision, action: auditLine(envelope, result) }); } catch { /* audit is best-effort */ }
+      process.stdout.write(JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          permissionDecision: result.decision, // 'deny' | 'ask'
+          permissionDecisionReason: result.reason,
+        },
+      }));
+    }
+    process.exit(0);
+  } catch {
+    process.exit(0); // fail open, always
+  }
+}
+
 function main() {
   const event = process.argv[3];
   if (event === 'session-start') return sessionStart();
   if (event === 'session-end') return sessionEnd();
+  if (event === 'pre-tool') return preTool();
   // Unknown event: exit silently — hooks must never error the host tool.
   process.exit(0);
 }

package/commands/pack.js

@@ -52,7 +52,7 @@ async function install(name) {
   console.log('');
 
   if (p.kind === 'linked') {
-    console.log(`  ${sage('This is a separate tool — phewsh doesn\'t vendor it. Install it with:')}`);
+    console.log(`  ${sage('This is a separate tool — phewsh doesn\'t vendor it. Start here:')}`);
     console.log(`    ${cream(p.install)}`);
     console.log('');
     return;

package/lib/gate-policy.js

@@ -0,0 +1,117 @@
+'use strict';
+
+// Deterministic pre-action policy — the enforcement core of the Decision Gate.
+//
+// Pure and provider-neutral: given an action envelope it returns a decision.
+// No I/O, no provider coupling — the hook adapter (commands/hook.js pre-tool)
+// feeds it the action and renders the provider-specific response. This is the
+// "deterministic enforcement" layer from cli/docs/pre-action-architecture.md;
+// it does NOT replace the Decision Gate, it is how the gate acts before a tool
+// runs. Decisions: 'allow' | 'ask' (require human) | 'deny' (block).
+//
+// Design rules: fail OPEN (an empty/garbled envelope returns allow — a policy
+// must never trap the user), and never inspect file CONTENTS (we judge the
+// action's target/shape, not your code or secrets).
+
+const path = require('path');
+
+// Tools that write/modify the filesystem — common names across providers.
+const WRITE_TOOLS = new Set([
+  'Write', 'Edit', 'MultiEdit', 'NotebookEdit',
+  'create_file', 'apply_patch', 'str_replace_editor', 'edit_file',
+]);
+
+// Shell/command tools.
+const SHELL_TOOLS = new Set(['Bash', 'shell', 'run_command', 'run_terminal_cmd']);
+
+// Paths an agent should never silently write — credentials, keys, VCS internals.
+const DEFAULT_PROTECTED = [
+  '.env', '.env.*', '*.pem', '*.key', 'id_rsa', 'id_ed25519',
+  '.git/', '.npmrc', '.aws/', '.ssh/', '.phewsh/config.json',
+];
+
+// High-blast-radius shell patterns that warrant a human OK.
+const DESTRUCTIVE = [
+  { re: /\brm\s+-[a-z]*r[a-z]*f|\brm\s+-[a-z]*f[a-z]*r/, label: 'recursive force delete' },
+  { re: /\bgit\s+push\b[^\n]*--force/, label: 'git force-push' },
+  { re: /\bgit\s+reset\s+--hard\b/, label: 'git hard reset' },
+  { re: /\bDROP\s+(TABLE|DATABASE)\b/i, label: 'SQL DROP' },
+  { re: /\bsudo\b/, label: 'sudo' },
+  { re: /\bchmod\s+-R\b/, label: 'recursive chmod' },
+  { re: /\bmkfs\b|\bdd\s+if=/, label: 'disk write' },
+  { re: /\bcurl\b[^\n]*\|\s*(sh|bash)\b|\bwget\b[^\n]*\|\s*(sh|bash)\b/, label: 'pipe-to-shell' },
+];
+
+function globToRegExp(glob) {
+  const esc = glob.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+  return new RegExp('^' + esc + '$');
+}
+
+// Does `target` match any protected entry? Directory entries (trailing '/')
+// match anywhere in the path; file globs match the basename or full path.
+function isProtected(target, protectedList) {
+  if (!target || typeof target !== 'string') return false;
+  const norm = target.replace(/^\.\//, '');
+  const base = path.basename(norm);
+  return protectedList.some(p => {
+    if (p.endsWith('/')) return norm.split('/').includes(p.slice(0, -1)) || norm.startsWith(p);
+    const re = globToRegExp(p);
+    return re.test(base) || re.test(norm);
+  });
+}
+
+function writeTarget(toolInput = {}) {
+  return toolInput.file_path || toolInput.path || toolInput.notebook_path
+    || toolInput.filename || toolInput.target_file || null;
+}
+
+// envelope: { toolName, toolInput, constraints, protectedFiles }
+function evaluateAction(envelope = {}) {
+  try {
+    const { toolName, toolInput = {}, constraints = {}, protectedFiles = [] } = envelope;
+    if (!toolName) return { decision: 'allow', reason: '' };
+    const protectedList = [...DEFAULT_PROTECTED, ...(Array.isArray(protectedFiles) ? protectedFiles : [])];
+
+    // 1. Writes to a protected path → deny (only a deliberate human act should).
+    if (WRITE_TOOLS.has(toolName)) {
+      const target = writeTarget(toolInput);
+      if (isProtected(target, protectedList)) {
+        return { decision: 'deny', reason: `phewsh gate: ${toolName} targets a protected path (${target}). Credentials/keys/VCS internals are off-limits to automated edits.` };
+      }
+    }
+
+    // 2. High-blast-radius shell → ask (require human confirmation).
+    if (SHELL_TOOLS.has(toolName)) {
+      const cmd = String(toolInput.command || toolInput.cmd || '');
+      const hit = DESTRUCTIVE.find(d => d.re.test(cmd));
+      if (hit) {
+        return { decision: 'ask', reason: `phewsh gate: high-blast-radius command (${hit.label}) — confirm before it runs.` };
+      }
+    }
+
+    // 3. Strict autonomy asks before any write. "delegated"/"guided" do not —
+    //    that would turn every edit into ceremony.
+    const autonomy = String(constraints.autonomy || '').toLowerCase();
+    if ((autonomy === 'manual' || autonomy === 'review') && WRITE_TOOLS.has(toolName)) {
+      return { decision: 'ask', reason: `phewsh gate: your autonomy is "${autonomy}" — confirm this ${toolName} before it runs.` };
+    }
+
+    return { decision: 'allow', reason: '' };
+  } catch {
+    return { decision: 'allow', reason: '' }; // fail OPEN: never trap the user
+  }
+}
+
+// A redacted one-line audit record — decision + target shape only, never the
+// tool payload (which may contain code or secrets).
+function auditLine(envelope = {}, result = {}) {
+  const target = WRITE_TOOLS.has(envelope.toolName)
+    ? writeTarget(envelope.toolInput || {})
+    : (SHELL_TOOLS.has(envelope.toolName) ? '<command>' : '');
+  return `${result.decision || 'allow'} ${envelope.toolName || '?'}${target ? ' ' + target : ''}`;
+}
+
+module.exports = {
+  evaluateAction, isProtected, auditLine, writeTarget,
+  WRITE_TOOLS, SHELL_TOOLS, DEFAULT_PROTECTED, DESTRUCTIVE,
+};

package/lib/packs.js

@@ -12,7 +12,7 @@
 //   • vendored — phewsh writes a clearly-marked block into the project's agent
 //     files (e.g. Karpathy's coding guidelines into CLAUDE.md/AGENTS.md).
 //   • linked   — phewsh doesn't vendor it; it points you at the upstream
-//     installer (e.g. GSD is its own tool — we hand you its command).
+//     installer or review page (e.g. GSD is its own tool — we hand you its command).
 
 const fs = require('fs');
 const path = require('path');
@@ -52,6 +52,110 @@ const PACKS = {
     license: 'see the GSD repo',
     install: 'npx @gsd-build/get-shit-done init   # follow the GSD repo for current instructions',
   },
+  'loop-library': {
+    kind: 'linked',
+    title: 'Loop Library',
+    desc: 'Copy-ready agent loops with checks and stopping conditions. Good Work-layer inspiration; phewsh links to it without becoming a scheduler or runner.',
+    source: 'github.com/Forward-Future/loop-library · signals.forwardfuture.ai/loop-library',
+    license: 'MIT',
+    install: 'npx skills add Forward-Future/loop-library --skill loop-library -g   # install through upstream skills tooling',
+  },
+  'matt-skills': {
+    kind: 'linked',
+    title: 'Matt Pocock Skills',
+    desc: 'Engineering-focused skills for debugging, TDD, domain modeling, handoffs, git guardrails, and design reviews.',
+    source: 'github.com/mattpocock/skills',
+    license: 'MIT',
+    install: 'npx skills@latest add mattpocock/skills   # install through upstream skills tooling',
+  },
+  'cybersecurity-skills': {
+    kind: 'linked',
+    title: 'Anthropic Cybersecurity Skills',
+    desc: 'Large cybersecurity skill library mapped to security frameworks. Review scope carefully before using on real targets.',
+    source: 'github.com/mukul975/Anthropic-Cybersecurity-Skills',
+    license: 'Apache-2.0',
+    install: 'review https://github.com/mukul975/Anthropic-Cybersecurity-Skills   # choose upstream install path and scope deliberately',
+  },
+  skillspector: {
+    kind: 'linked',
+    title: 'NVIDIA SkillSpector',
+    desc: 'Security scanner for AI-agent skills. Useful candidate for future Phewsh pack vetting before install or distribution.',
+    source: 'github.com/nvidia/skillspector',
+    license: 'see the SkillSpector repo',
+    install: 'review https://github.com/nvidia/skillspector   # run scanner only after reading upstream docs',
+  },
+  'codebase-memory-mcp': {
+    kind: 'linked',
+    title: 'Codebase Memory MCP',
+    desc: 'Persistent code-intelligence MCP server for repository memory and fast code search. Linked only; configure per harness.',
+    source: 'github.com/DeusData/codebase-memory-mcp',
+    license: 'see the codebase-memory-mcp repo',
+    install: 'review https://github.com/DeusData/codebase-memory-mcp   # install/configure upstream MCP manually',
+  },
+  'unlimited-ocr': {
+    kind: 'linked',
+    title: 'Unlimited OCR',
+    desc: 'Local/GPU OCR model candidate for images and PDFs. Relevant to RecipeFlower-style recipe capture, but heavy and not auto-installed.',
+    source: 'github.com/baidu/Unlimited-OCR',
+    license: 'MIT',
+    install: 'review https://github.com/baidu/Unlimited-OCR   # inspect CUDA/SGLang requirements before installing',
+  },
+  'palmier-pro': {
+    kind: 'linked',
+    title: 'Palmier Pro',
+    desc: 'Open-source macOS video editor with an MCP surface. Useful media-production inspiration; platform-gated and not bundled.',
+    source: 'github.com/palmier-io/palmier-pro',
+    license: 'GPLv3',
+    install: 'review https://github.com/palmier-io/palmier-pro   # macOS/Apple Silicon requirements apply',
+  },
+  openmontage: {
+    kind: 'linked',
+    title: 'OpenMontage',
+    desc: 'Agentic video-production system with pipelines, tools, and skills. Treat as an upstream media lab, not a core Phewsh dependency.',
+    source: 'github.com/calesthio/OpenMontage',
+    license: 'see the OpenMontage repo',
+    install: 'review https://github.com/calesthio/OpenMontage   # install only in a project that needs agentic video production',
+  },
+  hyperframes: {
+    kind: 'linked',
+    title: 'Hyperframes',
+    desc: 'HTML-to-video rendering for agents. Good fit for future product demos, walkthroughs, and generated media packs.',
+    source: 'github.com/heygen-com/hyperframes',
+    license: 'see the Hyperframes repo',
+    install: 'review https://github.com/heygen-com/hyperframes   # inspect current renderer/runtime requirements',
+  },
+  'deer-flow': {
+    kind: 'linked',
+    title: 'DeerFlow',
+    desc: 'Open-source agent harness with sub-agents, memory, sandboxes, and skills. Compare as an executor/harness, not a Phewsh replacement.',
+    source: 'github.com/bytedance/deer-flow',
+    license: 'MIT',
+    install: 'review https://github.com/bytedance/deer-flow   # evaluate as a separate harness before configuring',
+  },
+  'hermes-agent': {
+    kind: 'linked',
+    title: 'Hermes Agent',
+    desc: 'Nous Research agent project. Linked as a possible compatible harness to evaluate before any deeper integration.',
+    source: 'github.com/nousresearch/hermes-agent',
+    license: 'see the Hermes Agent repo',
+    install: 'review https://github.com/nousresearch/hermes-agent   # evaluate upstream capabilities first',
+  },
+  voicebox: {
+    kind: 'linked',
+    title: 'Voicebox',
+    desc: 'Open-source AI voice studio. Candidate for future audio/voice workflows and Keylink-adjacent media experiments.',
+    source: 'github.com/jamiepine/voicebox',
+    license: 'see the Voicebox repo',
+    install: 'review https://github.com/jamiepine/voicebox   # install only for voice workflows that need it',
+  },
+  gstack: {
+    kind: 'linked',
+    title: 'gstack',
+    desc: 'Opinionated Claude Code setup with role/tooling patterns. Useful reference, but Phewsh should preserve its own four-word model.',
+    source: 'github.com/garrytan/gstack',
+    license: 'see the gstack repo',
+    install: 'review https://github.com/garrytan/gstack   # inspect before mixing with existing agent files',
+  },
 };
 
 function markers(name) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phewsh",
-  "version": "0.15.64",
+  "version": "0.15.66",
   "description": "Turn intent into action. Structure your thinking, execute your next step.",
   "bin": {
     "phewsh": "bin/phewsh.js"