@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

package/framework/hooks/claude-code/core/enforce-phase-writes.js

@@ -1,22 +1,5 @@
 #!/usr/bin/env node
 
-/**
- * PreToolUse Hook: Enforce Phase-Appropriate File Writes
- *
- * Event: PreToolUse | Matcher: Write|Edit
- *
- * Ensures writes to .morph/features/{feature}/ go to the current phase's subfolder:
- *   proposal → only 0-proposal/
- *   uiux → only 1-design/
- *   plan → only 2-plan/
- *   implement → 3-implement/ + any source code (unrestricted)
- *   review → only 4-review/
- *
- * Files outside .morph/features/ are always allowed.
- *
- * Fail-open: exits 0 on any error.
- */
-
 import { existsSync } from 'fs';
 import { stateExists, getFeaturePhase, isGateApproved } from '../../shared/state-reader.js';
 import {
@@ -26,31 +9,20 @@ import {
   PHASE_DIRS
 } from '../../shared/phase-utils.js';
 
-/**
- * The gate that authorizes writing a phase folder's FIRST artifact. Once that
- * gate is approved, the next phase's canonical file may be created even though
- * the phase only advances (via derivation) once that file exists — this is the
- * fix for the forward-transition chicken-and-egg. proposal-approval unlocks both
- * the optional `1-design/` and `2-plan/` (the uiux fork).
- */
+// Approving this gate lets the next phase's first file be created: the phase only advances once that file exists.
 const PHASE_DIR_ENTRY_GATE = {
-  '1-design': 'proposal',
-  '2-plan': 'proposal',
+  '1-design': 'plan',
   '3-implement': 'plan',
   '4-review': 'plan',
 };
+
+const ALWAYS_WRITABLE_DIR = '2-plan';
 import { blockResult, runStandalone } from '../../shared/hook-response.js';
 import { logHookActivity } from '../../shared/activity-logger.js';
 import { getFilePath, resolveMorphRoot, resolveTargetPath } from '../../shared/payload-utils.js';
 
-/**
- * @param {object} payload - parsed PreToolUse stdin payload
- * @returns {Promise<object|null>} `{decision:'block',reason}` or null (pass).
- *   Never prints, never exits — see runStandalone()/chain.js at the bottom.
- */
 export async function run(payload) {
   try {
-    // Amend mode: bypass phase write enforcement for legitimate corrections
     if (process.env.MORPH_AMEND_PHASE) {
       console.error(`[morph-spec] AMEND MODE: bypassing phase protection for phase '${process.env.MORPH_AMEND_PHASE}'`);
       return null;
@@ -61,15 +33,9 @@ export async function run(payload) {
     const filePath = getFilePath(payload);
     if (!filePath) return null;
 
-    // Only check files inside .morph/features/
     if (!isFeaturePath(filePath)) return null;
 
-    // Resolve the tree that OWNS this file, NOT the tree the session sits in.
-    // A session rooted in the primary repo may legitimately write to a feature
-    // living in a secondary worktree; reading the session's `.morph/` there
-    // reported the ROOT's phase for the WORKTREE's file, and blocked a legal
-    // `2-plan/` write with "not allowed during PROPOSAL phase". `stateExists`
-    // must be asked of that same tree — a worktree carries its own state.
+    // The tree that OWNS the file, not the session's: a root session may write into a worktree's feature.
     const root = resolveMorphRoot(filePath, process.cwd());
     if (!stateExists(root)) return null;
 
@@ -79,37 +45,27 @@ export async function run(payload) {
     const phase = getFeaturePhase(featureName, root);
     if (!phase) return null;
 
-    // During implement phase, all writes are allowed (source code is unrestricted)
-    if (phase === 'implement' || phase === 'sync') return null;
+    if (phase === 'implement') return null;
 
     const targetDir = extractPhaseDir(filePath);
-    if (!targetDir) return null; // File directly in feature root — allow
+    if (!targetDir) return null;
+    if (targetDir === ALWAYS_WRITABLE_DIR) return null;
 
     const allowedDir = PHASE_DIRS[phase];
-    if (!allowedDir) return null; // Unknown phase — allow
+    if (!allowedDir) return null;
 
     if (targetDir !== allowedDir) {
-      // Allow editing already-existing files from previous phases
       const absolutePath = resolveTargetPath(filePath, root);
       if (existsSync(absolutePath)) {
         logHookActivity('enforce-phase-writes', 'PreToolUse', 'ok');
-        return null; // editing existing file — allow
+        return null;
       }
 
-      // Gate-aware forward transition: allow creating the NEXT phase's first
-      // artifact as soon as the gate authorizing that phase is approved. Without
-      // this, the first file of a new phase can never be written (the phase only
-      // advances once that file exists) — the deadlock this hook used to create.
       const entryGate = PHASE_DIR_ENTRY_GATE[targetDir];
       if (entryGate && isGateApproved(featureName, entryGate, root)) {
-        // uiux is OPTIONAL — proposal approval alone is enough to enter
-        // 2-plan/ for a feature that never took the design branch (no
-        // 1-design/ dir), exactly as before this check. But once a feature
-        // HAS opted into uiux (1-design/ exists), that gate is not
-        // decorative: 2-plan/ must wait for it too, or a feature can skip
-        // straight from an approved proposal into planning with its design
-        // gate silently left pending.
-        const tookDesignBranch = targetDir === '2-plan'
+        // uiux is optional, but once 1-design/ exists its gate is not
+        // decorative: implementation waits for it too.
+        const tookDesignBranch = targetDir !== '1-design'
           && existsSync(resolveTargetPath(`.morph/features/${featureName}/1-design`, root));
 
         if (!tookDesignBranch || isGateApproved(featureName, 'uiux', root)) {
@@ -119,18 +75,15 @@ export async function run(payload) {
 
         logHookActivity('enforce-phase-writes', 'PreToolUse', 'blocked');
         return blockResult(
-          `MORPH-SPEC: Writing to '2-plan/' is not allowed yet.\n` +
+          `MORPH-SPEC: Writing to '${targetDir}/' is not allowed yet.\n` +
           `This feature entered the uiux branch (1-design/ exists) and the 'uiux' gate is still pending.\n\n` +
-          `Approve the design gate first, then re-enter plan:\n` +
+          `Approve the design gate first, then move on to implementation:\n` +
           `  morph-spec approve ${featureName} uiux\n` +
           `  morph-spec advance ${featureName}`
         );
       }
 
       const phaseLabel = phase.toUpperCase();
-      // Name the tree the verdict came from whenever it is NOT the session's own.
-      // The phase read is per-tree, so "which .morph/ said proposal?" is the first
-      // question anyone debugging this asks.
       const treeNote = root !== process.cwd().replace(/\\/g, '/')
         ? `\n(phase read from the tree that owns the file: ${root})`
         : '';
@@ -147,7 +100,6 @@ export async function run(payload) {
     logHookActivity('enforce-phase-writes', 'PreToolUse', 'ok');
     return null;
   } catch {
-    // Fail-open
     return null;
   }
 }

package/framework/hooks/claude-code/core/gate-guard.js

@@ -1,31 +1,9 @@
 #!/usr/bin/env node
-/**
- * gate-guard.js — PostToolUse hook (detect-and-warn, never block)
- *
- * Closes the gap from issue #63: the trust-mode contract lived only in skill
- * pseudocode, with nothing verifying the LLM actually honored it. This hook
- * compares the OBSERVED gate action against the decision the skill persisted
- * to state.json (`features[feature].gateDecisions[gate]`) and injects a
- * non-blocking warning when they disagree.
- *
- * It is a guardrail, NOT an orchestrator (per MORPH.md): it never blocks,
- * never writes state, and fails open on any error or missing data.
- *
- * Two mismatch directions:
- *  - LLM PAUSED (AskUserQuestion on a gate) but the persisted decision said
- *    pause:false  → over-pausing under trust:auto. Warn.
- *  - LLM AUTO-APPROVED (gate became approvedBy:"auto") but the persisted
- *    decision said pause:true → skipped a required human pause. Warn.
- *
- * Observability: every time a gate action is actually checked against a
- * persisted gateDecisions entry, one line lands in the activity log
- * (.morph/logs/activity.json) with result 'coherent' or 'divergent' — so a
- * human can confirm the guard verified coherence instead of absolute silence.
- * No persisted decision, non-gate action, or any error → silence.
- */
+// Detect-and-warn, never block: compares the observed gate action with the persisted gateDecisions.
 
 import { loadState, stateExists, getActiveFeature } from '../../shared/state-reader.js';
 import { contextResult, runStandalone } from '../../shared/hook-response.js';
+import { gateFromQuestion } from '../../shared/gate-question.js';
 import { logHookActivity } from '../../shared/activity-logger.js';
 import { resolveMorphRoot, resolveTargetPath } from '../../shared/payload-utils.js';
 import { locateFeatureForQuestion } from '../../shared/feature-locator.js';
@@ -34,17 +12,12 @@ function projectDir() {
   return process.env.CLAUDE_PROJECT_DIR || process.cwd();
 }
 
-/** Feature slug from a `.morph/features/{name}/feature.json` path. */
 function featureFromStatePath(filePath) {
   const fp = String(filePath ?? '').replace(/\\/g, '/');
   return (fp.match(/\.morph\/features\/([^/]+)\/feature\.json$/) ?? [])[1] ?? null;
 }
 
-/**
- * The tree owning an edited gate-state file. `resolveMorphRoot` covers the v5
- * per-feature `feature.json`; the legacy `.morph/state.json` has no feature
- * segment to anchor on, so strip its own suffix instead.
- */
+// The legacy `.morph/state.json` has no feature segment to anchor on, so strip its own suffix.
 function rootOfGateStateFile(filePath, fallback) {
   const abs = resolveTargetPath(filePath, fallback);
   const suffix = '/.morph/state.json';
@@ -52,7 +25,6 @@ function rootOfGateStateFile(filePath, fallback) {
   return resolveMorphRoot(abs, fallback);
 }
 
-/** Every question/header text this AskUserQuestion call surfaced. */
 function askedTexts(input) {
   const texts = [];
   const questions = input.tool_input?.questions;
@@ -68,45 +40,26 @@ function askedTexts(input) {
   return texts;
 }
 
-/** Map a gate question's text to a gate id. Mirrors state-sync.js. */
-function gateFromQuestion(question) {
-  if (typeof question !== 'string') return null;
-  const lower = question.toLowerCase();
-  if (lower.includes('gate 1') || lower.includes('proposta')) return 'proposal';
-  if (lower.includes('gate 2') || lower.includes('plano') || lower.includes('plan')) return 'plan';
-  if (lower.includes('gate 3') || lower.includes('review')) return 'review';
-  return null;
-}
-
 function getDecision(state, feature, gate) {
   const d = state.features?.[feature]?.gateDecisions?.[gate];
   if (!d || typeof d.pause !== 'boolean') return null;
   return d;
 }
 
-/**
- * The LLM just asked a gate question. If the persisted decision said this
- * gate should auto-pass (pause:false), the human was interrupted needlessly.
- */
 function checkAskUserQuestion(input, sessionRoot) {
   for (const text of askedTexts(input)) {
     const gate = gateFromQuestion(text);
     if (!gate) continue;
 
-    // Check the decision of the feature the question NAMES, in its own tree.
-    // Reading the session tree's first in_progress feature made this guard
-    // compare a gate against an unrelated feature's gateDecisions — a warning
-    // about the wrong thing is worse than silence, so an unattributable
-    // question is skipped rather than guessed at (state-sync already tells the
-    // operator when a gate answer could not be attributed).
+    // Only the feature the question NAMES: a warning about the wrong feature is worse than silence.
     const located = locateFeatureForQuestion(text, sessionRoot);
     if (!located) continue;
     const { name: feature, root: cwd } = located;
-    if (!stateExists(cwd)) continue; // fail-open
+    if (!stateExists(cwd)) continue;
 
     const state = loadState(cwd);
     const decision = getDecision(state, feature, gate);
-    if (!decision) continue; // no persisted decision → nothing to verify
+    if (!decision) continue;
     if (decision.pause === false) {
       logHookActivity('gate-guard', 'PostToolUse', 'divergent', cwd);
       return contextResult(
@@ -119,34 +72,24 @@ function checkAskUserQuestion(input, sessionRoot) {
         'PostToolUse'
       );
     }
-    // The decision said pause:true and the LLM did pause — coherent.
     logHookActivity('gate-guard', 'PostToolUse', 'coherent', cwd);
     return null;
   }
   return null;
 }
 
-/** True for edits to .morph/state.json (legacy) or a per-feature feature.json (v5). */
 function isGateStateFile(filePath) {
   const fp = String(filePath ?? '').replace(/\\/g, '/');
   if (fp.endsWith('.morph/state.json')) return true;
   return fp.includes('.morph/features/') && fp.endsWith('/feature.json');
 }
 
-/**
- * The LLM just edited gate state (state.json legacy, or the authoritative
- * feature.json in v5). If a gate flipped to approvedBy:"auto" but the
- * persisted decision said pause:true, a required human pause was skipped.
- */
 function checkStateEdit(input, sessionRoot) {
   const filePath = input.tool_input?.file_path;
   if (!isGateStateFile(filePath)) return null;
 
-  // The edited file names its own tree — and, for the v5 per-feature
-  // feature.json, its own feature. Only the legacy `.morph/state.json` shape
-  // still needs a most-recently-updated fallback within that tree.
   const cwd = rootOfGateStateFile(filePath, sessionRoot);
-  if (!stateExists(cwd)) return null; // fail-open
+  if (!stateExists(cwd)) return null;
   const state = loadState(cwd);
   if (!state) return null;
   const feature = featureFromStatePath(filePath) || getActiveFeature(cwd)?.name;
@@ -154,7 +97,7 @@ function checkStateEdit(input, sessionRoot) {
 
   let checked = false;
   const gates = state.features?.[feature]?.approvalGates ?? {};
-  for (const gate of ['proposal', 'plan', 'review']) {
+  for (const gate of ['plan', 'uiux', 'review']) {
     const g = gates[gate];
     const autoApproved = g?.approved === true && g?.approvedBy === 'auto';
     if (!autoApproved) continue;
@@ -177,22 +120,12 @@ function checkStateEdit(input, sessionRoot) {
   return null;
 }
 
-/**
- * @param {object} payload - parsed PostToolUse stdin payload (Write|Edit|AskUserQuestion)
- * @returns {Promise<object|null>} a hookSpecificOutput warning on a
- *   trust-mode divergence, or null (pass/silent).
- */
 export async function run(payload) {
-  // Starting point only — each branch resolves the tree it actually inspects
-  // (from the edited path, or from the feature the question names).
   const sessionRoot = projectDir();
 
   const input = payload || {};
   const toolName = input.tool_name;
 
-  // Short-circuit before loading state: a Write/Edit only matters if it
-  // touched gate state (state.json legacy, or the v5 per-feature
-  // feature.json). Skip the disk read for unrelated edits.
   if (toolName === 'Edit' || toolName === 'Write') {
     if (!isGateStateFile(input.tool_input?.file_path)) return null;
   } else if (toolName !== 'AskUserQuestion') {
@@ -202,9 +135,7 @@ export async function run(payload) {
   try {
     if (toolName === 'AskUserQuestion') return checkAskUserQuestion(input, sessionRoot);
     return checkStateEdit(input, sessionRoot);
-  } catch {
-    // fail-open
-  }
+  } catch {}
   return null;
 }
 

package/framework/hooks/claude-code/core/graph-refresh-kick.js

@@ -1,20 +1,7 @@
 #!/usr/bin/env node
 
-/**
- * PostToolUse Hook: dispara o refresh do grafo de codebase
- *
- * Event: PostToolUse | Matcher: none (elo da cadeia de todos os tools)
- *
- * Depois de um comando de shell — Bash ou PowerShell, que no Windows é o shell
- * principal do Claude Code — que chama git, gh ou morph-spec, solta o refresh
- * do grafo da RAIZ em background (framework/hooks/shared/graph-refresh.js) e
- * volta na hora. O filtro é largo de propósito: o refresh só roda quando o
- * grafo da raiz está atrás do HEAD, então um `git status` custa um processo
- * que sai sem fazer nada — e um comando que move o HEAD sem ser reconhecido é
- * exatamente como o grafo ficou 85 commits atrás.
- *
- * Silencioso e fail-open: nunca injeta contexto, nunca bloqueia.
- */
+// Wide filter on purpose: the refresh only runs when the root's graph is behind HEAD, and a HEAD-moving command
+// left unrecognized is how the graph falls behind.
 
 import { stateExists } from '../../shared/state-reader.js';
 import { runStandalone } from '../../shared/hook-response.js';
@@ -24,20 +11,12 @@ import { kickGraphRefresh } from '../../shared/graph-refresh.js';
 const SHELL_TOOLS = new Set(['Bash', 'PowerShell']);
 const GIT_TOOL = /(^|[\\/])(git|gh|morph-spec)(\.exe|\.cmd)?$/i;
 
-/**
- * @param {string} command
- * @returns {boolean} o comando chama git, gh ou morph-spec em algum ponto
- */
 export function touchesGit(command) {
   return tokenize(command)
     .flatMap((t) => t.split(/[;&|()]+/))
     .some((t) => GIT_TOOL.test(t));
 }
 
-/**
- * @param {object} payload - PostToolUse stdin payload
- * @returns {Promise<null>}
- */
 export async function run(payload) {
   try {
     if (!SHELL_TOOLS.has(payload?.tool_name)) return null;
@@ -45,7 +24,7 @@ export async function run(payload) {
     const dir = payload?.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd();
     if (!stateExists(dir)) return null;
     kickGraphRefresh(dir);
-  } catch { /* fail-open */ }
+  } catch {}
   return null;
 }
 

package/framework/hooks/claude-code/core/heavy-gate.js

@@ -1,20 +1,7 @@
 #!/usr/bin/env node
-/**
- * heavy-gate.js — PreToolUse hook (Bash matcher), link of the Bash chain before worktree-env-inject.
- *
- * A sub-agent that runs `dotnet build` or `npm test` straight through Bash bypasses the heavy-node
- * semaphore that `morph-spec verify` respects. With `heavy.gateBash: true` this hook takes a slot
- * before such a command runs and `heavy-release` gives it back on Post/PostFailure, matched by
- * `tool_use_id`. It never rewrites the command: a rewrite would be judged against the user's
- * permission rules in its rewritten form, and would auto-approve what the prompt would have asked.
- *
- * A slot taken here has no live process to watch — the hook exits at once — so it lapses by TTL
- * (the call's own timeout plus slack). A call refused by a permission rule or interrupted by the
- * user fires no Post hook and keeps its slot until then.
- *
- * Waits below the platform's 600 s hook timeout, because a timed-out PreToolUse hook lets the call
- * run: the refusal has to come from here. Fail-open otherwise.
- */
+// Never rewrites the command: a rewrite would be judged against the user's permission rules in its rewritten form.
+// The lease has no live pid (the hook exits at once), so it lapses by TTL; a call that fires no Post hook holds it until then.
+// The wait stays under the 600 s hook timeout because a timed-out PreToolUse hook lets the call run.
 
 import { stateExists } from '../../shared/state-reader.js';
 import { blockResult, runStandalone } from '../../shared/hook-response.js';
@@ -22,11 +9,6 @@ import { heavyKind, leaseTtlMs } from '../../shared/heavy-command.js';
 
 const HOOK_BUDGET_SEC = 540;
 
-/**
- * @param {object} payload - parsed PreToolUse stdin payload (Bash matcher)
- * @param {{ env?: object, acquire?: Function }} [deps] - test seams; production passes none
- * @returns {Promise<object|null>} a block result when no slot came free, else null (pass)
- */
 export async function run(payload, deps = {}) {
   try {
     if (payload?.tool_name && payload.tool_name !== 'Bash') return null;

package/framework/hooks/claude-code/core/heavy-release.js

@@ -1,21 +1,10 @@
 #!/usr/bin/env node
-/**
- * heavy-release.js — PostToolUse / PostToolUseFailure link: gives back the slot `heavy-gate` took
- * for this Bash call, matched by `tool_use_id`.
- *
- * Silent and fail-open. A call that fires neither event (refused by a rule, interrupted) leaves its
- * slot to the TTL. Releasing is not deciding, so this link is safe in the async failure binding.
- */
+// A call that fires neither Post event leaves its slot to the TTL. Releasing is not deciding, so this link is safe async.
 
 import { existsSync } from 'node:fs';
 import { stateExists } from '../../shared/state-reader.js';
 import { runStandalone } from '../../shared/hook-response.js';
 
-/**
- * @param {object} payload - PostToolUse or PostToolUseFailure stdin payload
- * @param {{ env?: object }} [deps] - test seam
- * @returns {Promise<null>}
- */
 export async function run(payload, deps = {}) {
   try {
     if (payload?.tool_name !== 'Bash' || !payload.tool_use_id) return null;
@@ -27,7 +16,7 @@ export async function run(payload, deps = {}) {
     if (!existsSync(dir)) return null;
     const { releaseLeaseById } = await import('../../shared/heavy-slots.js');
     releaseLeaseById(dir, payload.tool_use_id);
-  } catch { /* fail-open */ }
+  } catch {}
   return null;
 }
 

package/framework/hooks/claude-code/core/loop-detect.js

@@ -1,19 +1,5 @@
 #!/usr/bin/env node
 
-/**
- * PostToolUse Hook: Loop Detection
- *
- * Event: PostToolUse | Matcher: none (all tools)
- *
- * Detects when an agent is stuck in a repetitive loop by tracking
- * the last 15 actions. If the last 8 actions have <= 2 unique
- * signatures, injects a warning with escape instructions.
- *
- * Cooldown: 5 minutes between warnings to prevent meta-loop.
- *
- * Fail-open: exits 0 on any error.
- */
-
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
 import { join } from 'path';
 import { stateExists } from '../../shared/state-reader.js';
@@ -24,13 +10,8 @@ import { logEvent } from '../../shared/activity-logger.js';
 const MAX_BUFFER = 15;
 const LOOP_WINDOW = 8;
 const MAX_UNIQUE_SIGS = 2;
-const COOLDOWN_MS = 5 * 60 * 1000; // 5 minutes
+const COOLDOWN_MS = 5 * 60 * 1000;
 
-/**
- * @param {object} payload - parsed PostToolUse stdin payload (any tool)
- * @returns {Promise<object|null>} a hookSpecificOutput loop warning, or null
- *   (pass/silent).
- */
 export async function run(payload) {
   try {
     if (!stateExists()) return null;
@@ -43,7 +24,6 @@ export async function run(payload) {
 
     mkdirSync(memoryDir, { recursive: true });
 
-    // Read existing buffer
     let buffer = [];
     try {
       if (existsSync(bufferPath)) {
@@ -54,19 +34,15 @@ export async function run(payload) {
       buffer = [];
     }
 
-    // Append current action
     const sig = getCommandSignature(payload);
     buffer.push({ sig, ts: new Date().toISOString() });
 
-    // Trim to max size (FIFO)
     if (buffer.length > MAX_BUFFER) {
       buffer = buffer.slice(-MAX_BUFFER);
     }
 
-    // Save updated buffer
     writeFileSync(bufferPath, JSON.stringify(buffer), 'utf-8');
 
-    // Check for loop (need at least LOOP_WINDOW actions)
     if (buffer.length < LOOP_WINDOW) return null;
 
     const recent = buffer.slice(-LOOP_WINDOW);
@@ -74,18 +50,14 @@ export async function run(payload) {
 
     if (uniqueSigs.size > MAX_UNIQUE_SIGS) return null;
 
-    // Check cooldown
     try {
       if (existsSync(cooldownPath)) {
         const cooldown = JSON.parse(readFileSync(cooldownPath, 'utf-8'));
         const elapsed = Date.now() - new Date(cooldown.lastDetected).getTime();
         if (elapsed < COOLDOWN_MS) return null;
       }
-    } catch {
-      // Ignore corrupt cooldown — proceed with detection
-    }
+    } catch {}
 
-    // Loop detected — set cooldown and warn
     writeFileSync(cooldownPath, JSON.stringify({ lastDetected: new Date().toISOString() }), 'utf-8');
 
     logEvent('loop_detected', { signatures: uniqueSigs.size }, process.cwd());
@@ -102,7 +74,6 @@ export async function run(payload) {
       'PostToolUse'
     );
   } catch {
-    // Fail-open
     return null;
   }
 }

package/framework/hooks/claude-code/core/pre-bash-denylist.js

@@ -4,13 +4,40 @@ import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { blockResult, runStandalone } from '../../shared/hook-response.js';
 import { stateExists } from '../../shared/state-reader.js';
+import { tokenize } from '../../shared/command-tokens.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
+const SEPARATOR = /^[;&|]+$/;
+const executableName = (token) => token.replace(/\\/g, '/').split('/').pop().toLowerCase().replace(/\.exe$/, '');
+
+const hasFlag = (token, flag) => (flag.startsWith('--') || token.startsWith('--')
+  ? token === flag
+  : /^-[A-Za-z]+$/.test(token) && token.includes(flag.slice(1)));
 
 /**
- * @param {object} payload - parsed PreToolUse stdin payload (Bash matcher)
- * @returns {Promise<object|null>} `{decision:'block',reason}` or null (pass).
+ * A quoted argument is one token, never the executable: mentioning the command in a message is not calling it.
+ * `args` match a whole token; each group in `flags` (case-sensitive, clusters like `-rf` count) must appear in the same command.
  */
+export function matchesExecutableRule(command, rule) {
+  const exe = rule.executable.toLowerCase();
+  const args = new Set(rule.args.map((a) => a.toLowerCase()));
+  const flagGroups = rule.flags || [];
+  const tokens = tokenize(command);
+  for (let i = 0; i < tokens.length; i++) {
+    if (executableName(tokens[i].replace(/^[;&|(]+/, '')) !== exe) continue;
+    const seen = [];
+    let argHit = false;
+    for (let j = i + 1; j < tokens.length && !SEPARATOR.test(tokens[j]); j++) {
+      const raw = tokens[j].replace(/[;&|)]+$/, '');
+      if (args.has(raw.toLowerCase())) argHit = true;
+      seen.push(raw);
+      if (tokens[j] !== raw) break;
+    }
+    if (argHit && flagGroups.every((group) => seen.some((t) => group.some((flag) => hasFlag(t, flag))))) return true;
+  }
+  return false;
+}
+
 export async function run(payload) {
   try {
     if (!stateExists()) return null;
@@ -26,6 +53,13 @@ export async function run(payload) {
       }
     }
 
+    for (const rule of denylist.executableArgs || []) {
+      if (matchesExecutableRule(command, rule)) {
+        const shown = [rule.executable, ...(rule.flags || []).map((group) => group[0]), rule.args[0]].join(' ');
+        return blockResult(`Comando bloqueado pela denylist: \`${shown}\` ${rule.reason}.`);
+      }
+    }
+
     return null;
   } catch {
     return null;