@maestrofrontier/frontier 1.4.4 → 1.5.0

package/hooks/maestro-terse-mode.cjs

@@ -1,189 +1,189 @@
-#!/usr/bin/env node
-// Maestro terse-mode hook. One file, two events (dispatch on
-// hook_event_name):
-// - SessionStart: resolve the level (env > config > off), write the
-//   flag file, inject the level-filtered ruleset from
-//   skills/terse/SKILL.md (single source of truth) as
-//   additionalContext.
-// - UserPromptSubmit: track level switches (/maestro:terse, /terse,
-//   natural-language deactivation) in the flag file and emit a
-//   one-line reminder every turn while active -- per-turn
-//   reinforcement defeats style drift after context compression
-//   (same pattern as maestro-gate-reminder).
-//
-// Level resolution: MAESTRO_TERSE_LEVEL env var, then terseLevel in
-// $XDG_CONFIG_HOME/maestro/config.json (~/.config/maestro fallback,
-// %APPDATA%\maestro on Windows), then 'off'. Off by default:
-// installing the plugin must not change anyone's output style.
-//
-// Flag I/O ported from Caveman (MIT): symlink-refusing, O_NOFOLLOW,
-// atomic temp+rename, 0600, 64-byte read cap, level whitelist. A
-// predictable flag path under ~/.claude is a symlink-attack target;
-// never write through one, never inject unvalidated bytes into model
-// context.
-//
-// .cjs so Node treats it as CommonJS regardless of any "type": "module"
-// package.json in a parent directory of the install location.
-
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-
-const LEVELS = ['lite', 'full', 'ultra'];
-const MAX_FLAG_BYTES = 64;
-
-const claudeDir = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
-const flagPath = path.join(claudeDir, '.maestro-terse');
-
-function configDir() {
-  if (process.env.XDG_CONFIG_HOME) return path.join(process.env.XDG_CONFIG_HOME, 'maestro');
-  if (process.platform === 'win32') {
-    return path.join(process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming'), 'maestro');
-  }
-  return path.join(os.homedir(), '.config', 'maestro');
-}
-
-function defaultLevel() {
-  const env = String(process.env.MAESTRO_TERSE_LEVEL || '').toLowerCase();
-  if (env === 'off' || LEVELS.includes(env)) return env;
-  try {
-    const cfg = JSON.parse(fs.readFileSync(path.join(configDir(), 'config.json'), 'utf8'));
-    const v = String(cfg.terseLevel || '').toLowerCase();
-    if (v === 'off' || LEVELS.includes(v)) return v;
-  } catch {}
-  return 'off';
-}
-
-function safeWriteFlag(level) {
-  try {
-    const dir = path.dirname(flagPath);
-    fs.mkdirSync(dir, { recursive: true });
-    try { if (fs.lstatSync(dir).isSymbolicLink()) return; } catch { return; }
-    try {
-      if (fs.lstatSync(flagPath).isSymbolicLink()) return;
-    } catch (e) {
-      if (e.code !== 'ENOENT') return;
-    }
-    const tempPath = path.join(dir, `.maestro-terse.${process.pid}.${Date.now()}`);
-    const O_NOFOLLOW = typeof fs.constants.O_NOFOLLOW === 'number' ? fs.constants.O_NOFOLLOW : 0;
-    const flags = fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | O_NOFOLLOW;
-    let fd;
-    try {
-      if (O_NOFOLLOW === 0) { try { if (fs.lstatSync(tempPath).isSymbolicLink()) return; } catch {} }
-      fd = fs.openSync(tempPath, flags, 0o600);
-      fs.writeSync(fd, String(level));
-      try { fs.fchmodSync(fd, 0o600); } catch {}
-    } finally {
-      if (fd !== undefined) fs.closeSync(fd);
-    }
-    fs.renameSync(tempPath, flagPath);
-  } catch {}
-}
-
-function readFlag() {
-  try {
-    let st;
-    try { st = fs.lstatSync(flagPath); } catch { return null; }
-    if (st.isSymbolicLink() || !st.isFile()) return null;
-    if (st.size > MAX_FLAG_BYTES) return null;
-    const O_NOFOLLOW = typeof fs.constants.O_NOFOLLOW === 'number' ? fs.constants.O_NOFOLLOW : 0;
-    let fd, out;
-    try {
-      if (O_NOFOLLOW === 0) { try { if (fs.lstatSync(flagPath).isSymbolicLink()) return null; } catch {} }
-      fd = fs.openSync(flagPath, fs.constants.O_RDONLY | O_NOFOLLOW);
-      const buf = Buffer.alloc(MAX_FLAG_BYTES);
-      const n = fs.readSync(fd, buf, 0, MAX_FLAG_BYTES, 0);
-      out = buf.slice(0, n).toString('utf8');
-    } finally {
-      if (fd !== undefined) fs.closeSync(fd);
-    }
-    const raw = out.trim().toLowerCase();
-    return LEVELS.includes(raw) ? raw : null;
-  } catch {
-    return null;
-  }
-}
-
-function removeFlag() {
-  try { fs.unlinkSync(flagPath); } catch {}
-}
-
-function sessionStart() {
-  const level = defaultLevel();
-  if (level === 'off' || !LEVELS.includes(level)) { removeFlag(); return; }
-  safeWriteFlag(level);
-
-  let body = '';
-  try {
-    const skill = fs.readFileSync(path.join(__dirname, '..', 'skills', 'terse', 'SKILL.md'), 'utf8');
-    // Strip frontmatter and maintainer HTML comments, then keep only
-    // the active level's intensity row and example lines.
-    body = skill
-      .replace(/^---[\s\S]*?---\s*/, '')
-      .replace(/<!--[\s\S]*?-->\s*/g, '')
-      .split('\n')
-      .filter(line => {
-        const row = line.match(/^\|\s*\*\*(\S+?)\*\*\s*\|/);
-        if (row) return row[1] === level;
-        const ex = line.match(/^- (\S+?):\s/);
-        if (ex) return ex[1] === level;
-        return true;
-      })
-      .join('\n');
-  } catch {
-    body = 'Respond terse. All technical substance stay. Only fluff die.\n' +
-      'Drop articles/filler/pleasantries/hedging. Fragments OK. ' +
-      'Code/commits/PRs: write normal. Off: "stop terse" / "normal mode".';
-  }
-
-  process.stdout.write(JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: 'SessionStart',
-      additionalContext: 'MAESTRO TERSE ACTIVE — level: ' + level + '\n\n' + body
-    }
-  }));
-}
-
-function promptSubmit(data) {
-  const prompt = String(data.prompt || '').trim().toLowerCase();
-
-  if (prompt.startsWith('/maestro:terse') || prompt.startsWith('/terse')) {
-    const arg = (prompt.split(/\s+/)[1] || '').toLowerCase();
-    if (arg === 'off') {
-      removeFlag();
-    } else if (LEVELS.includes(arg)) {
-      safeWriteFlag(arg);
-    } else {
-      // Bare invocation: explicit opt-in. Use the configured default,
-      // or 'full' when the default is off.
-      const d = defaultLevel();
-      safeWriteFlag(LEVELS.includes(d) ? d : 'full');
-    }
-  }
-
-  if (/\b(stop|disable|deactivate|turn off)\b.*\bterse\b/.test(prompt) ||
-      /\bterse\b.*\b(stop|disable|off)\b/.test(prompt) ||
-      /\bnormal mode\b/.test(prompt)) {
-    removeFlag();
-  }
-
-  const active = readFlag();
-  if (active) {
-    process.stdout.write(JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: 'UserPromptSubmit',
-        additionalContext: 'MAESTRO TERSE ACTIVE (' + active + '). ' +
-          'Drop articles/filler/pleasantries/hedging. Fragments OK. ' +
-          'Code/commits/security: write normal.'
-      }
-    }));
-  }
-}
-
-let data = {};
-try { data = JSON.parse(fs.readFileSync(0, 'utf8')); } catch { process.exit(0); }
-
-if (data.hook_event_name === 'SessionStart') sessionStart();
-else if (data.hook_event_name === 'UserPromptSubmit') promptSubmit(data);
-
-process.exit(0);
+#!/usr/bin/env node
+// Maestro terse-mode hook. One file, two events (dispatch on
+// hook_event_name):
+// - SessionStart: resolve the level (env > config > off), write the
+//   flag file, inject the level-filtered ruleset from
+//   skills/terse/SKILL.md (single source of truth) as
+//   additionalContext.
+// - UserPromptSubmit: track level switches (/maestro:terse, /terse,
+//   natural-language deactivation) in the flag file and emit a
+//   one-line reminder every turn while active -- per-turn
+//   reinforcement defeats style drift after context compression
+//   (same pattern as maestro-gate-reminder).
+//
+// Level resolution: MAESTRO_TERSE_LEVEL env var, then terseLevel in
+// $XDG_CONFIG_HOME/maestro/config.json (~/.config/maestro fallback,
+// %APPDATA%\maestro on Windows), then 'off'. Off by default:
+// installing the plugin must not change anyone's output style.
+//
+// Flag I/O ported from Caveman (MIT): symlink-refusing, O_NOFOLLOW,
+// atomic temp+rename, 0600, 64-byte read cap, level whitelist. A
+// predictable flag path under ~/.claude is a symlink-attack target;
+// never write through one, never inject unvalidated bytes into model
+// context.
+//
+// .cjs so Node treats it as CommonJS regardless of any "type": "module"
+// package.json in a parent directory of the install location.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const LEVELS = ['lite', 'full', 'ultra'];
+const MAX_FLAG_BYTES = 64;
+
+const claudeDir = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+const flagPath = path.join(claudeDir, '.maestro-terse');
+
+function configDir() {
+  if (process.env.XDG_CONFIG_HOME) return path.join(process.env.XDG_CONFIG_HOME, 'maestro');
+  if (process.platform === 'win32') {
+    return path.join(process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming'), 'maestro');
+  }
+  return path.join(os.homedir(), '.config', 'maestro');
+}
+
+function defaultLevel() {
+  const env = String(process.env.MAESTRO_TERSE_LEVEL || '').toLowerCase();
+  if (env === 'off' || LEVELS.includes(env)) return env;
+  try {
+    const cfg = JSON.parse(fs.readFileSync(path.join(configDir(), 'config.json'), 'utf8'));
+    const v = String(cfg.terseLevel || '').toLowerCase();
+    if (v === 'off' || LEVELS.includes(v)) return v;
+  } catch {}
+  return 'off';
+}
+
+function safeWriteFlag(level) {
+  try {
+    const dir = path.dirname(flagPath);
+    fs.mkdirSync(dir, { recursive: true });
+    try { if (fs.lstatSync(dir).isSymbolicLink()) return; } catch { return; }
+    try {
+      if (fs.lstatSync(flagPath).isSymbolicLink()) return;
+    } catch (e) {
+      if (e.code !== 'ENOENT') return;
+    }
+    const tempPath = path.join(dir, `.maestro-terse.${process.pid}.${Date.now()}`);
+    const O_NOFOLLOW = typeof fs.constants.O_NOFOLLOW === 'number' ? fs.constants.O_NOFOLLOW : 0;
+    const flags = fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | O_NOFOLLOW;
+    let fd;
+    try {
+      if (O_NOFOLLOW === 0) { try { if (fs.lstatSync(tempPath).isSymbolicLink()) return; } catch {} }
+      fd = fs.openSync(tempPath, flags, 0o600);
+      fs.writeSync(fd, String(level));
+      try { fs.fchmodSync(fd, 0o600); } catch {}
+    } finally {
+      if (fd !== undefined) fs.closeSync(fd);
+    }
+    fs.renameSync(tempPath, flagPath);
+  } catch {}
+}
+
+function readFlag() {
+  try {
+    let st;
+    try { st = fs.lstatSync(flagPath); } catch { return null; }
+    if (st.isSymbolicLink() || !st.isFile()) return null;
+    if (st.size > MAX_FLAG_BYTES) return null;
+    const O_NOFOLLOW = typeof fs.constants.O_NOFOLLOW === 'number' ? fs.constants.O_NOFOLLOW : 0;
+    let fd, out;
+    try {
+      if (O_NOFOLLOW === 0) { try { if (fs.lstatSync(flagPath).isSymbolicLink()) return null; } catch {} }
+      fd = fs.openSync(flagPath, fs.constants.O_RDONLY | O_NOFOLLOW);
+      const buf = Buffer.alloc(MAX_FLAG_BYTES);
+      const n = fs.readSync(fd, buf, 0, MAX_FLAG_BYTES, 0);
+      out = buf.slice(0, n).toString('utf8');
+    } finally {
+      if (fd !== undefined) fs.closeSync(fd);
+    }
+    const raw = out.trim().toLowerCase();
+    return LEVELS.includes(raw) ? raw : null;
+  } catch {
+    return null;
+  }
+}
+
+function removeFlag() {
+  try { fs.unlinkSync(flagPath); } catch {}
+}
+
+function sessionStart() {
+  const level = defaultLevel();
+  if (level === 'off' || !LEVELS.includes(level)) { removeFlag(); return; }
+  safeWriteFlag(level);
+
+  let body = '';
+  try {
+    const skill = fs.readFileSync(path.join(__dirname, '..', 'skills', 'terse', 'SKILL.md'), 'utf8');
+    // Strip frontmatter and maintainer HTML comments, then keep only
+    // the active level's intensity row and example lines.
+    body = skill
+      .replace(/^---[\s\S]*?---\s*/, '')
+      .replace(/<!--[\s\S]*?-->\s*/g, '')
+      .split('\n')
+      .filter(line => {
+        const row = line.match(/^\|\s*\*\*(\S+?)\*\*\s*\|/);
+        if (row) return row[1] === level;
+        const ex = line.match(/^- (\S+?):\s/);
+        if (ex) return ex[1] === level;
+        return true;
+      })
+      .join('\n');
+  } catch {
+    body = 'Respond terse. All technical substance stay. Only fluff die.\n' +
+      'Drop articles/filler/pleasantries/hedging. Fragments OK. ' +
+      'Code/commits/PRs: write normal. Off: "stop terse" / "normal mode".';
+  }
+
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'SessionStart',
+      additionalContext: 'MAESTRO TERSE ACTIVE — level: ' + level + '\n\n' + body
+    }
+  }));
+}
+
+function promptSubmit(data) {
+  const prompt = String(data.prompt || '').trim().toLowerCase();
+
+  if (prompt.startsWith('/maestro:terse') || prompt.startsWith('/terse')) {
+    const arg = (prompt.split(/\s+/)[1] || '').toLowerCase();
+    if (arg === 'off') {
+      removeFlag();
+    } else if (LEVELS.includes(arg)) {
+      safeWriteFlag(arg);
+    } else {
+      // Bare invocation: explicit opt-in. Use the configured default,
+      // or 'full' when the default is off.
+      const d = defaultLevel();
+      safeWriteFlag(LEVELS.includes(d) ? d : 'full');
+    }
+  }
+
+  if (/\b(stop|disable|deactivate|turn off)\b.*\bterse\b/.test(prompt) ||
+      /\bterse\b.*\b(stop|disable|off)\b/.test(prompt) ||
+      /\bnormal mode\b/.test(prompt)) {
+    removeFlag();
+  }
+
+  const active = readFlag();
+  if (active) {
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'UserPromptSubmit',
+        additionalContext: 'MAESTRO TERSE ACTIVE (' + active + '). ' +
+          'Drop articles/filler/pleasantries/hedging. Fragments OK. ' +
+          'Code/commits/security: write normal.'
+      }
+    }));
+  }
+}
+
+let data = {};
+try { data = JSON.parse(fs.readFileSync(0, 'utf8')); } catch { process.exit(0); }
+
+if (data.hook_event_name === 'SessionStart') sessionStart();
+else if (data.hook_event_name === 'UserPromptSubmit') promptSubmit(data);
+
+process.exit(0);

package/hooks/maestro-toolbudget-advisory.cjs

@@ -1,127 +1,127 @@
-#!/usr/bin/env node
-// Maestro PostToolUse tool-call budget advisory (Fable T1). Log-only,
-// zero prompt tokens, never blocks.
-//
-// Fable scales tool calls to task complexity (1 for single facts; 3-5
-// medium; 5-10 deep research). Maestro caps subagent tool budgets (S9)
-// but nothing watches the ORCHESTRATOR's own pre-edit exploration. This
-// hook measures how many exploration (non-edit) tool calls happened this
-// turn before the FIRST file edit; if that exceeds a budget it appends
-// one advisory row to a local log. It is a behavioural lever, evidence-
-// gated: log-only first, so a preregistered OFF/ON fixture can show the
-// signal separates before anyone promotes it to an enforcing warning.
-//
-// Design choices:
-// - Fires on PostToolUse for edit tools; evaluates once per turn at the
-//   first-edit boundary (a per-turn marker file makes it idempotent).
-// - "Turn" = everything since the last genuine user prompt, located from
-//   the transcript with the same heuristic as maestro-phase-scope.
-// - ZERO prompt tokens: never writes stdout / additionalContext, so it
-//   adds nothing to context. It only appends a counts-only JSON row.
-// - NEVER blocks: PostToolUse cannot block and this emits no decision.
-// - Privacy: records counts + project folder basename only -- no
-//   prompts, no file contents, no paths. No network, ever.
-//
-// Env:
-// - MAESTRO_TOOLBUDGET=0           disable entirely (default: active, log-only)
-// - MAESTRO_TOOLBUDGET_THRESHOLD   exploration-call budget (default 20)
-// - MAESTRO_TOOLBUDGET_LOG         override log path (default ~/.claude/maestro-toolbudget.jsonl)
-// - MAESTRO_TOOLBUDGET_MARKERDIR   override per-turn marker dir (default OS tmp)
-//
-// Promotion path (NOT shipped, pending fixture evidence): a `warn` mode
-// that emits additionalContext at the first edit. Kept out until the log
-// shows the budget separates real over-exploration from normal work.
-//
-// Payload fields verified against code.claude.com/docs/en/hooks
-// (PostToolUse input: session_id, transcript_path, cwd, tool_name,
-// tool_input; PostToolUse output cannot block), 2026-06-16.
-//
-// .cjs so Node treats it as CommonJS regardless of any "type": "module"
-// package.json in a parent directory of the install location.
-
-'use strict';
-
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const crypto = require('crypto');
-
-if (process.env.MAESTRO_TOOLBUDGET === '0') process.exit(0);
-
-const EDIT_TOOLS = new Set(['Edit', 'Write', 'NotebookEdit', 'MultiEdit']);
-
-let data = {};
-try { data = JSON.parse(fs.readFileSync(0, 'utf8')); } catch { process.exit(0); }
-
-// Only the first edit of a turn matters; ignore every non-edit tool.
-if (!EDIT_TOOLS.has(data.tool_name)) process.exit(0);
-
-// Counting exploration before the first edit needs the transcript.
-if (!data.transcript_path || !fs.existsSync(data.transcript_path)) process.exit(0);
-
-let lines = [];
-try {
-  const buf = fs.readFileSync(data.transcript_path, 'utf8');
-  lines = (buf.length > 4000000 ? buf.slice(-4000000) : buf).split(/\r?\n/);
-} catch { process.exit(0); }
-
-const parsed = lines.map(l => { try { return JSON.parse(l); } catch { return null; } });
-
-// Locate the last genuine user prompt (typed text, not a tool_result
-// carrier); everything after it is the current turn.
-let turnStart = 0;
-for (let i = 0; i < parsed.length; i++) {
-  const e = parsed[i];
-  if (!e || e.type !== 'user' || e.isMeta || !e.message) continue;
-  const c = e.message.content;
-  const genuine = typeof c === 'string'
-    ? true
-    : Array.isArray(c) && c.some(x => x && x.type === 'text') && !c.some(x => x && x.type === 'tool_result');
-  if (genuine) turnStart = i;
-}
-
-// Evaluate at most once per turn, at the first-edit boundary.
-const markerDir = process.env.MAESTRO_TOOLBUDGET_MARKERDIR || os.tmpdir();
-const turnKey = crypto.createHash('sha1')
-  .update(String(data.session_id || '') + ':' + turnStart + ':' + (lines[turnStart] || ''))
-  .digest('hex').slice(0, 16);
-const marker = path.join(markerDir, 'maestro-toolbudget-' + turnKey);
-if (fs.existsSync(marker)) process.exit(0);
-try { fs.mkdirSync(markerDir, { recursive: true }); fs.writeFileSync(marker, '1'); } catch {}
-
-// Count exploration (non-edit) tool calls that ran before the first edit
-// this turn. priorEdit stops the count at the first edit, whether or not
-// the triggering edit is already in the transcript.
-let explore = 0;
-let priorEdit = false;
-for (let i = turnStart; i < parsed.length; i++) {
-  const e = parsed[i];
-  if (!e || e.type !== 'assistant' || !e.message || !Array.isArray(e.message.content)) continue;
-  for (const item of e.message.content) {
-    if (!item || item.type !== 'tool_use') continue;
-    if (EDIT_TOOLS.has(item.name)) { priorEdit = true; break; }
-    explore++;
-  }
-  if (priorEdit) break;
-}
-
-const threshold = parseInt(process.env.MAESTRO_TOOLBUDGET_THRESHOLD, 10) || 20;
-if (explore > threshold) {
-  const row = {
-    ts: new Date().toISOString(),
-    session_id: data.session_id || null,
-    kind: 'toolbudget-advisory',
-    explore_calls: explore,
-    threshold,
-    first_edit_tool: data.tool_name,
-    project: data.cwd ? path.basename(data.cwd) : null
-  };
-  const logPath = process.env.MAESTRO_TOOLBUDGET_LOG
-    || path.join(os.homedir(), '.claude', 'maestro-toolbudget.jsonl');
-  try {
-    fs.mkdirSync(path.dirname(logPath), { recursive: true });
-    fs.appendFileSync(logPath, JSON.stringify(row) + '\n');
-  } catch { /* advisory is best-effort; never disrupt the session */ }
-}
-
-process.exit(0);
+#!/usr/bin/env node
+// Maestro PostToolUse tool-call budget advisory (Fable T1). Log-only,
+// zero prompt tokens, never blocks.
+//
+// Fable scales tool calls to task complexity (1 for single facts; 3-5
+// medium; 5-10 deep research). Maestro caps subagent tool budgets (S9)
+// but nothing watches the ORCHESTRATOR's own pre-edit exploration. This
+// hook measures how many exploration (non-edit) tool calls happened this
+// turn before the FIRST file edit; if that exceeds a budget it appends
+// one advisory row to a local log. It is a behavioural lever, evidence-
+// gated: log-only first, so a preregistered OFF/ON fixture can show the
+// signal separates before anyone promotes it to an enforcing warning.
+//
+// Design choices:
+// - Fires on PostToolUse for edit tools; evaluates once per turn at the
+//   first-edit boundary (a per-turn marker file makes it idempotent).
+// - "Turn" = everything since the last genuine user prompt, located from
+//   the transcript with the same heuristic as maestro-phase-scope.
+// - ZERO prompt tokens: never writes stdout / additionalContext, so it
+//   adds nothing to context. It only appends a counts-only JSON row.
+// - NEVER blocks: PostToolUse cannot block and this emits no decision.
+// - Privacy: records counts + project folder basename only -- no
+//   prompts, no file contents, no paths. No network, ever.
+//
+// Env:
+// - MAESTRO_TOOLBUDGET=0           disable entirely (default: active, log-only)
+// - MAESTRO_TOOLBUDGET_THRESHOLD   exploration-call budget (default 20)
+// - MAESTRO_TOOLBUDGET_LOG         override log path (default ~/.claude/maestro-toolbudget.jsonl)
+// - MAESTRO_TOOLBUDGET_MARKERDIR   override per-turn marker dir (default OS tmp)
+//
+// Promotion path (NOT shipped, pending fixture evidence): a `warn` mode
+// that emits additionalContext at the first edit. Kept out until the log
+// shows the budget separates real over-exploration from normal work.
+//
+// Payload fields verified against code.claude.com/docs/en/hooks
+// (PostToolUse input: session_id, transcript_path, cwd, tool_name,
+// tool_input; PostToolUse output cannot block), 2026-06-16.
+//
+// .cjs so Node treats it as CommonJS regardless of any "type": "module"
+// package.json in a parent directory of the install location.
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+
+if (process.env.MAESTRO_TOOLBUDGET === '0') process.exit(0);
+
+const EDIT_TOOLS = new Set(['Edit', 'Write', 'NotebookEdit', 'MultiEdit']);
+
+let data = {};
+try { data = JSON.parse(fs.readFileSync(0, 'utf8')); } catch { process.exit(0); }
+
+// Only the first edit of a turn matters; ignore every non-edit tool.
+if (!EDIT_TOOLS.has(data.tool_name)) process.exit(0);
+
+// Counting exploration before the first edit needs the transcript.
+if (!data.transcript_path || !fs.existsSync(data.transcript_path)) process.exit(0);
+
+let lines = [];
+try {
+  const buf = fs.readFileSync(data.transcript_path, 'utf8');
+  lines = (buf.length > 4000000 ? buf.slice(-4000000) : buf).split(/\r?\n/);
+} catch { process.exit(0); }
+
+const parsed = lines.map(l => { try { return JSON.parse(l); } catch { return null; } });
+
+// Locate the last genuine user prompt (typed text, not a tool_result
+// carrier); everything after it is the current turn.
+let turnStart = 0;
+for (let i = 0; i < parsed.length; i++) {
+  const e = parsed[i];
+  if (!e || e.type !== 'user' || e.isMeta || !e.message) continue;
+  const c = e.message.content;
+  const genuine = typeof c === 'string'
+    ? true
+    : Array.isArray(c) && c.some(x => x && x.type === 'text') && !c.some(x => x && x.type === 'tool_result');
+  if (genuine) turnStart = i;
+}
+
+// Evaluate at most once per turn, at the first-edit boundary.
+const markerDir = process.env.MAESTRO_TOOLBUDGET_MARKERDIR || os.tmpdir();
+const turnKey = crypto.createHash('sha1')
+  .update(String(data.session_id || '') + ':' + turnStart + ':' + (lines[turnStart] || ''))
+  .digest('hex').slice(0, 16);
+const marker = path.join(markerDir, 'maestro-toolbudget-' + turnKey);
+if (fs.existsSync(marker)) process.exit(0);
+try { fs.mkdirSync(markerDir, { recursive: true }); fs.writeFileSync(marker, '1'); } catch {}
+
+// Count exploration (non-edit) tool calls that ran before the first edit
+// this turn. priorEdit stops the count at the first edit, whether or not
+// the triggering edit is already in the transcript.
+let explore = 0;
+let priorEdit = false;
+for (let i = turnStart; i < parsed.length; i++) {
+  const e = parsed[i];
+  if (!e || e.type !== 'assistant' || !e.message || !Array.isArray(e.message.content)) continue;
+  for (const item of e.message.content) {
+    if (!item || item.type !== 'tool_use') continue;
+    if (EDIT_TOOLS.has(item.name)) { priorEdit = true; break; }
+    explore++;
+  }
+  if (priorEdit) break;
+}
+
+const threshold = parseInt(process.env.MAESTRO_TOOLBUDGET_THRESHOLD, 10) || 20;
+if (explore > threshold) {
+  const row = {
+    ts: new Date().toISOString(),
+    session_id: data.session_id || null,
+    kind: 'toolbudget-advisory',
+    explore_calls: explore,
+    threshold,
+    first_edit_tool: data.tool_name,
+    project: data.cwd ? path.basename(data.cwd) : null
+  };
+  const logPath = process.env.MAESTRO_TOOLBUDGET_LOG
+    || path.join(os.homedir(), '.claude', 'maestro-toolbudget.jsonl');
+  try {
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    fs.appendFileSync(logPath, JSON.stringify(row) + '\n');
+  } catch { /* advisory is best-effort; never disrupt the session */ }
+}
+
+process.exit(0);