acstack 0.52.6 → 0.53.1

package/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acstack-cli",
-  "version": "0.52.6",
+  "version": "0.53.1",
   "description": "CLI for the ACStack agentic coding stack",
   "type": "module",
   "license": "MIT",

package/docs/config-reference.md

@@ -305,7 +305,7 @@ Three refusals protect a file neither command can handle.
 
 ## 3. workflow: the switches
 
-*Five booleans sit in the block. Each one changes how much discipline ACStack applies. A sixth key decides how the agent asks you a question.*
+*Six booleans sit in the block. Each one changes how much discipline ACStack applies. A byte count tunes the large-read guard, and one more key decides how the agent asks you a question.*
 
 | Key | Values | Default | What changes |
 | --- | --- | --- | --- |
@@ -314,6 +314,8 @@ Three refusals protect a file neither command can handle.
 | `workflow.tdd.orchestrator_strict` | `true`, `false` | none | deprecated compatibility boolean; no delegation effect, including explicit `true` |
 | `workflow.frontend_verification` | `true`, `false` | `false` | the frontend-verifier runs only when this is `true`, the file configures a `frontend` block, and the change touched frontend files |
 | `workflow.design_review` | `true`, `false` | `false` | a design review runs on a UI change only when this is `true`; it needs the impeccable plugin installed and switched on, which `acstack config check` reports on |
+| `workflow.read_guard` | `true`, `false` | `true` | `false` turns off the large-read guard; section 3.3 describes it |
+| `workflow.read_guard_bytes` | a whole number, 1 or more | `32768` | the smallest file, in bytes, the large-read guard stops |
 
 How a boolean reads:
 
@@ -361,6 +363,26 @@ How a boolean reads:
 - `tool` falls back to inline prose for any round it cannot hold
 - Two things exceed it: a round of more than four questions, and any question with no discrete options
 
+### 3.3. The large-read guard
+
+*The guard stops a main agent's first whole read of a large file once, and points it to a cheaper way to read.*
+
+- The guard runs on Claude Code and Codex as a `PreToolUse` hook (`hooks/read-guard.mjs`), and on pi in the extension's `tool_call` handler
+    - Both share one policy, `hooks/lib/read-guard.mjs`
+- It stops a whole-file read of a file of at least `workflow.read_guard_bytes` bytes
+    - A whole-file read is the read tool with no offset or limit, or a single-file `cat`, `less`, `more`, `nl`, or `bat` with no pipe, redirect, or variable
+    - The block message suggests a ranged read, a search, or a read-only subagent
+- Repeating the same read passes, and so does any later whole read of the same unchanged file
+    - The guard is a nudge, not a security boundary
+    - A ranged read, a pipe, or `head` always passes
+- The guard watches only a main agent, meaning a session the user started
+    - Claude Code and Codex subagents carry `agent_id` in the hook input, so they pass
+    - ac-teams members (`ACSTACK_AGENT_ROLE` set to anything but `main`, or `AC_TEAMS_MEMBER` set) and pi-subagents children (`PI_SUBAGENT_CHILD`) pass
+    - On pi, a session with a `parentSession` header or no session file passes, so the guard skips a forked session too
+    - When the guard cannot tell, it lets the read through
+- Any error inside the guard lets the read through
+- Claude Code and Codex record passed reads in `${TMPDIR:-/tmp}/acstack-read-guard-<uid>/<session_id>.json`, a folder only its owner can open; pi keeps them in memory
+
 ## 4. workflow.maps
 
 *Two keys record where a map's nodes live, and what happens to those nodes at the end.*
@@ -634,6 +656,8 @@ workflow:
   # An absent key reads as false. Section 3 says why.
   frontend_verification: true
   design_review: false
+  read_guard: true
+  read_guard_bytes: 32768
   maps:
     # tracker has no default: the map skill picks and writes it
     persist: false

package/hooks/hooks.json

@@ -54,6 +54,17 @@
         ]
       }
     ],
+    "PreToolUse": [
+      {
+        "matcher": "Read|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/read-guard.mjs\""
+          }
+        ]
+      }
+    ],
     "UserPromptSubmit": [
       {
         "hooks": [

package/hooks/lib/read-guard.mjs

@@ -0,0 +1,190 @@
+// The large-read guard's policy, shared by hooks/read-guard.mjs (Claude Code
+// and Codex) and pi/extension.ts. It knows nothing about any harness: callers
+// say whether the agent is a main agent and pass a retry ledger.
+//
+// A main agent's first whole-file read of a large file is blocked with a
+// redirect message; an identical repeat passes. Every error allows the read,
+// because the guard saves context and must never trap an agent.
+//
+// Design: .acstack/designs/large-read-guard/overview.md
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { createHash } from 'node:crypto';
+
+export const DEFAULT_MIN_BYTES = 32768;
+
+const SHELL_READERS = new Set(['cat', 'less', 'more', 'nl', 'bat']);
+
+/** True when a launcher marked this process as anything but a main agent. */
+export function envSaysNotMain(env = process.env) {
+  const role = env.ACSTACK_AGENT_ROLE;
+  return Boolean(role && role !== 'main') || Boolean(env.AC_TEAMS_MEMBER);
+}
+
+/**
+ * The one settings function: workflow.read_guard and
+ * workflow.read_guard_bytes from the nearest
+ * .acstack/project.yaml above cwd. Hand-rolled like the other hooks' readers,
+ * because no YAML library is guaranteed at hook time.
+ */
+export function readGuardSettings(cwd) {
+  const settings = { enabled: true, minBytes: DEFAULT_MIN_BYTES };
+  const yaml = projectYaml(cwd);
+  if (yaml === undefined) return settings;
+  const stack = [];
+  for (const raw of yaml.split('\n')) {
+    if (!raw.trim() || raw.trimStart().startsWith('#')) continue;
+    const stripped = raw.replace(/^ +/, '');
+    const indent = raw.length - stripped.length;
+    if (stripped.startsWith('- ') || !stripped.includes(':')) continue;
+    const sep = stripped.indexOf(':');
+    const key = stripped.slice(0, sep).trim().replace(/^["']+|["']+$/g, '');
+    const value = stripped.slice(sep + 1).split('#')[0].trim().replace(/^["']+|["']+$/g, '');
+    while (stack.length && stack[stack.length - 1][0] >= indent) stack.pop();
+    const keyPath = [...stack.map(([, k]) => k), key].join('.');
+    if (!value) {
+      stack.push([indent, key]);
+      continue;
+    }
+    if (keyPath === 'workflow.read_guard') settings.enabled = !['false', 'no', 'off'].includes(value.toLowerCase());
+    if (keyPath === 'workflow.read_guard_bytes' && /^\d+$/.test(value)) settings.minBytes = Number(value);
+  }
+  return settings;
+}
+
+function projectYaml(cwd) {
+  let dir = path.resolve(cwd);
+  while (true) {
+    const file = path.join(dir, '.acstack', 'project.yaml');
+    if (fs.existsSync(file)) {
+      try {
+        return fs.readFileSync(file, 'utf8');
+      } catch {
+        return undefined;
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
+
+/**
+ * The file a tool call reads whole, or undefined when the call is not a
+ * whole-file read: a ranged read, a pipe, a script, or anything unrecognised.
+ */
+export function wholeReadTarget(toolName, input, cwd) {
+  if (!input || typeof input !== 'object') return undefined;
+  const name = String(toolName).toLowerCase();
+  if (name === 'read') {
+    if (input.offset != null || input.limit != null) return undefined;
+    const file = input.file_path ?? input.path;
+    return typeof file === 'string' && file ? resolvePath(file, cwd) : undefined;
+  }
+  if (name === 'bash') {
+    const file = shellReadTarget(input.command);
+    return file === undefined ? undefined : resolvePath(file, cwd);
+  }
+  return undefined;
+}
+
+/** The single file of `cat|less|more|nl|bat [-flags] <file>`, nothing more. */
+export function shellReadTarget(command) {
+  if (typeof command !== 'string') return undefined;
+  // Pipes, redirects, chains, substitutions, globs, and variables all pass.
+  if (/[|;&<>`$()*?\n\\]/.test(command)) return undefined;
+  const words = [];
+  for (const match of command.trim().matchAll(/'([^']*)'|"([^"]*)"|(\S+)/g)) {
+    words.push(match[1] ?? match[2] ?? match[3]);
+  }
+  const [reader, ...args] = words;
+  if (!SHELL_READERS.has(reader)) return undefined;
+  const flags = args.filter((arg) => arg.startsWith('-'));
+  const files = args.filter((arg) => !arg.startsWith('-'));
+  // bat -r / --line-range reads a range.
+  if (reader === 'bat' && flags.some((flag) => flag === '-r' || flag.startsWith('--line-range'))) return undefined;
+  return files.length === 1 ? files[0] : undefined;
+}
+
+function resolvePath(file, cwd) {
+  if (file === '~' || file.startsWith('~/')) return path.join(os.homedir(), file.slice(1));
+  return path.resolve(cwd, file);
+}
+
+/**
+ * Decide one tool call. Returns { block: false } or { block: true, message }.
+ * `ledger` has has(key) and add(key); add throws when it cannot record, and
+ * then the read is allowed so a repeat can never be trapped.
+ */
+export function decide({ toolName, toolInput, cwd, main, ledger, settings = readGuardSettings(cwd) }) {
+  try {
+    if (!main || !settings.enabled || !ledger) return { block: false };
+    const file = wholeReadTarget(toolName, toolInput, cwd);
+    if (!file) return { block: false };
+    const stat = fs.statSync(file);
+    if (!stat.isFile() || stat.size < settings.minBytes) return { block: false };
+    const key = `${fs.realpathSync(file)}\0${stat.size}\0${stat.mtimeMs}`;
+    if (ledger.has(key)) return { block: false };
+    ledger.add(key);
+    return { block: true, message: blockMessage(stat.size) };
+  } catch {
+    return { block: false };
+  }
+}
+
+export function blockMessage(bytes) {
+  const kb = Math.round(bytes / 1024);
+  const tokens = Math.round(bytes / 4 / 1000) * 1000;
+  return [
+    `This file is ${kb} KB (about ${tokens.toLocaleString('en-US')} tokens), and reading all of it is usually unnecessary. Instead:`,
+    '',
+    '- Search for what you need, then read only that range',
+    "- Or hand the question to an investigator, as ACStack's Delegate investigation section describes",
+    '',
+    'If you really need the whole file, repeat this exact read and it will go through.',
+  ].join('\n');
+}
+
+/**
+ * A per-session ledger file in a folder only this user can open:
+ * ${TMPDIR:-/tmp}/acstack-read-guard-<uid>/<session_id>.json.
+ * Returns undefined without a session id, so the guard stays off.
+ */
+export function fileLedger(sessionId, tmpdir = os.tmpdir()) {
+  if (typeof sessionId !== 'string' || !sessionId) return undefined;
+  const uid = typeof process.getuid === 'function' ? process.getuid() : undefined;
+  const dir = path.join(tmpdir, `acstack-read-guard-${uid ?? os.userInfo().username}`);
+  const name = /^[A-Za-z0-9._-]{1,128}$/.test(sessionId) && !sessionId.startsWith('.')
+    ? sessionId
+    : createHash('sha256').update(sessionId).digest('hex');
+  const file = path.join(dir, `${name}.json`);
+
+  const ownedDir = () => {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const stat = fs.lstatSync(dir);
+    // Another user's folder could hold planted entries that switch the guard off.
+    if (!stat.isDirectory() || (uid !== undefined && stat.uid !== uid) || (stat.mode & 0o077) !== 0) {
+      throw new Error(`refusing ledger folder ${dir}`);
+    }
+  };
+  const load = () => {
+    ownedDir();
+    try {
+      const keys = JSON.parse(fs.readFileSync(file, 'utf8'));
+      return new Set(Array.isArray(keys) ? keys : []);
+    } catch {
+      return new Set();
+    }
+  };
+  return {
+    has: (key) => load().has(key),
+    add: (key) => {
+      const keys = load().add(key);
+      const tmp = `${file}.${process.pid}.tmp`;
+      fs.writeFileSync(tmp, JSON.stringify([...keys]), { mode: 0o600 });
+      fs.renameSync(tmp, file);
+    },
+  };
+}

package/hooks/read-guard.mjs

@@ -0,0 +1,31 @@
+// PreToolUse hook for Claude Code and Codex: the large-read guard.
+// Reads the hook input on stdin and prints a deny decision, or nothing.
+// Any failure allows the call, so the guard can never trap an agent.
+
+import { readFileSync } from 'node:fs';
+import { decide, envSaysNotMain, fileLedger } from './lib/read-guard.mjs';
+
+try {
+  const input = JSON.parse(readFileSync(0, 'utf8'));
+  // Subagents and in-process teammates carry agent_id in both harnesses.
+  const main = !input.agent_id && !envSaysNotMain();
+  const cwd = input.cwd || process.cwd();
+  const result = decide({
+    toolName: input.tool_name,
+    toolInput: input.tool_input,
+    cwd,
+    main,
+    ledger: main ? fileLedger(input.session_id) : undefined,
+  });
+  if (result.block) {
+    console.log(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: result.message,
+      },
+    }));
+  }
+} catch {
+  // Allow.
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acstack",
-  "version": "0.52.6",
+  "version": "0.53.1",
   "private": false,
   "description": "Agentic coding stack with first-class Claude Code and pi support: skills, orchestrator instructions, and verification agents.",
   "license": "MIT",

package/pi/extension.ts

@@ -17,6 +17,8 @@
  *   session_compact      re-inject .acstack/HANDOFF.md after a compaction, and
  *                        restart the nudge ladder   (hooks/session-start-handoff.sh,
  *                                                    hooks/context-pressure.sh)
+ *   tool_call            block a main agent's first whole read of a large
+ *                        file                       (hooks/read-guard.mjs)
  *
  * It also registers /acstack <skill>, a /acstack:<skill> command per skill,
  * and /acstack-writing-style for the bundled/default/custom style choice.
@@ -33,6 +35,8 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { execFileSync } from "node:child_process";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+// @ts-ignore -- plain ESM shared with hooks/read-guard.mjs, no type declarations
+import { decide, envSaysNotMain } from "../hooks/lib/read-guard.mjs";
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const troubleshoot = path.join(packageRoot, "TROUBLESHOOTING.md");
@@ -777,6 +781,24 @@ export default function acstack(pi: ExtensionAPI): void {
 		}
 	});
 
+	// The large-read guard. Environment markers are read once, at load, which
+	// is when pi-subagents sets them for an in-process child. A session with a
+	// parentSession header (a tintinweb/pi-subagents child, or a user's /fork)
+	// or with no session file is not treated as main: unclear means off.
+	const readGuardOff = delegated || envSaysNotMain();
+	const readLedgers = new Map<string, Set<string>>();
+	pi.on("tool_call", async (event, ctx) => {
+		if (readGuardOff || (event.toolName !== "read" && event.toolName !== "bash")) return;
+		const sessions = ctx.sessionManager;
+		const sessionId = sessions.getSessionId();
+		const main = Boolean(sessionId && sessions.getSessionFile?.() && !sessions.getHeader?.()?.parentSession);
+		if (!main) return;
+		let ledger = readLedgers.get(sessionId);
+		if (!ledger) readLedgers.set(sessionId, (ledger = new Set()));
+		const result = decide({ toolName: event.toolName, toolInput: event.input, cwd: ctx.cwd, main, ledger });
+		if (result.block) return { block: true, reason: result.message };
+	});
+
 	const runSkill = (name: string, args: string, ctx: ExtensionContext): void => {
 		const file = skills.get(name)?.file;
 		const message = file && skillInvocation(name, file, args);