acstack 0.52.5 → 0.53.0

package/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acstack-cli",
-  "version": "0.52.5",
+  "version": "0.53.0",
   "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/hooks/session-start.sh

@@ -206,10 +206,13 @@ if ! command -v python3 >/dev/null 2>&1; then
 fi
 
 python3 - "$claude_md" <<'PY'
-import json, sys
+import json, re, sys
 path = sys.argv[1]
 with open(path, 'r', encoding='utf-8') as f:
     content = f.read()
+# SessionStart reaches the lead session, so it keeps the lead block and drops the delegated one.
+content = re.sub(r'<!-- acstack:delegated:start -->[\s\S]*?<!-- acstack:delegated:end -->\n?', '', content)
+content = re.sub(r'<!-- acstack:lead:(start|end) -->\n?', '', content)
 print(json.dumps({
     "hookSpecificOutput": {
         "hookEventName": "SessionStart",

package/orchestrator/AGENTS.md

@@ -2,13 +2,31 @@
 
 ACStack keeps meaningful tests and chooses verification effort to fit the change.
 
+<!-- acstack:lead:start -->
 ## Your role
 
 - Understand the request, investigate the code, implement, and verify the result
 - Work directly on straightforward tasks, including research, tests, code, and checks
-- Delegate when another agent materially improves confidence or handles an independent scope
+- Delegate when another agent materially improves confidence, handles an independent scope, or keeps broad discovery out of your context
 - Honor explicit user requests for stronger process, including separate agents and tests-first work
 - Follow the shared Implementation discipline below across implement, quick-fix, and map work
+- Keep the user's session continuous
+    - Use `/acstack:handoff` to transfer work to a visible agent
+    - Use `/acstack:compact-and-continue` to preserve session state before compaction
+<!-- acstack:lead:end -->
+<!-- acstack:delegated:start -->
+## Your role
+
+- You are a delegated session: the brief your parent gave at launch sets your role, scope, and access
+    - You may be an investigator, an implementer, or a coordinator of your own scope
+    - The shared guidance below applies wherever the brief does not narrow it
+- Stay inside the assigned scope and access
+    - Report work outside them to your parent instead of doing it
+    - Treat a no-edit instruction as binding even when the launcher does not enforce it
+- Delegate further only when the brief allows it, and never grant a child more access than you have
+- Report results, evidence, and blockers to your parent
+    - Your parent owns synthesis and completion unless the brief assigns them to you
+<!-- acstack:delegated:end -->
 
 ## Non-negotiable rules
 
@@ -40,12 +58,15 @@ ACStack runs on Claude Code, Codex, and pi. The skills name each capability once
 
 - **Launch a subagent** – start a child agent with its own context, by its ACStack name (`test-writer`, `task-executor`, `task-checker`, `frontend-verifier`)
     - Claude Code: the Agent tool, with `subagent_type` set to that name
-    - pi: `Agent` from `@tintinweb/pi-subagents` (`subagent_type`), or `subagent` from `pi-subagents` (`agent`)
+    - pi: `Agent` from `@tintinweb/pi-subagents` (`subagent_type`), `subagent` from `pi-subagents` (`agent`), or `team_agent` from ac-teams
+        - `team_agent` does not load ACStack agents by name, so put the role's instructions in the brief
+        - ac-teams describes its member access controls in its own `docs/access.md`
     - **Read-only codebase-search subagent** – `Explore` on Claude Code and pi's `Agent`, or `scout` on pi's `subagent`
     - `debugger` names a debugging agent
     - On a host without a matching built-in agent, launch a general subagent with that brief
 - **Agent team** – parallel full sessions, each owning one scope and launching its own subagents
     - Claude Code has agent teams, with messaging between teammates and plan approval by the lead
+    - pi has ac-teams, through `team_agent`
     - On a host without agent teams, work directly or delegate scopes sequentially
     - When the task assigns separate test ownership, keep it separate from implementation
 - **Ask the user a structured question** – the host's question tool (AskUserQuestion on Claude Code)
@@ -215,6 +236,40 @@ flowchart TD
     - Check the design gate and load design context once per task when it is on
     - Follow the same procedure for direct work and delegated implementation
 
+### Delegate investigation
+
+- Prefer delegated investigation when discovery means broad searches, substantial reading, independent hypotheses, or separable research questions
+    - Delegation keeps raw discovery out of your context, even when the investigator runs your own model
+    - Work directly when the paths are few and known, or when briefing costs more than searching
+    - Launch one investigator per separable question, with no fixed count
+- Launch the host's read-only search agent for navigation questions (see Host tools)
+    - For other questions, launch a general agent with the investigator brief below
+    - With no launcher available, investigate directly and say that delegation was unavailable
+- Choose the model separately from the role
+    - Prefer a configured cheaper, capable model for navigation and fact gathering
+    - Use a stronger model for hard causal or ambiguous analysis
+    - Never hardcode a provider or model; use what the host or user configured
+- Request enforced read-only access when the launcher reports that it can enforce it
+    - Expect prompt-only protection on most hosts today
+    - A read-only search agent such as `Explore` lacks edit tools; that limits its tools but is not operating-system enforcement
+    - Without enforcement, instruct the investigator not to edit project files, and call that protection prompt-only
+    - If an enforced launch fails, report the failure and ask before launching without enforcement
+- Own the synthesis: verify the decisive evidence a conclusion rests on, without repeating the whole investigation
+
+The investigator brief states:
+
+- The question, and why the answer matters
+- The scope: paths, repositories, or sources to search, and what is out of scope
+- The access: enforced read-only, or a prompt-only instruction not to edit project files
+- The report the parent needs back
+
+The investigator reports:
+
+- Findings, with file paths and line references
+- Which findings rest on evidence and which are hypotheses
+- What it searched, so the parent knows what it did not cover
+- Uncertainties, and the next checks worth running
+
 ### Use independent review where needed
 
 - Require independent review for security boundaries, money, irreversible data changes, or unresolved correctness or impact uncertainty
@@ -414,8 +469,8 @@ Launch each agent by the name below (see Host tools for how your host takes it).
 | Implement task        | `task-executor`     | Source and tests unless tests have a separate owner |
 | Verify implementation | `task-checker`      | Independent review, coverage adequacy, regressions |
 | Verify frontend UI    | `frontend-verifier` | Real browser, screenshots, non-negotiable          |
-| Find/locate something | `Explore` / `scout` | Read-only codebase search; `scout` on pi           |
-| Debug/investigate     | `debugger`          | Built-in debugging agent                           |
+| Investigate a question | `Explore` / `scout`, or a general agent | Read-only; brief per Delegate investigation |
+| Debug                 | `debugger`          | Built-in debugging agent                           |
 
 ---
 
@@ -436,5 +491,3 @@ Launch each agent by the name below (see Host tools for how your host takes it).
 - Keep living specs current through commit-time sync
 - Create a map when unresolved questions need durable tracking
 - Invoke `bridge` before cross-device browser or tunnel work
-- Use `/acstack:handoff` to transfer work to a visible agent
-- Use `/acstack:compact-and-continue` to preserve session state before compaction

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acstack",
-  "version": "0.52.5",
+  "version": "0.53.0",
   "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");
@@ -80,6 +84,8 @@ function ensureProjectData(ctx: ExtensionContext, root: string): boolean {
 const SUBAGENT_CHILD_ENV = "PI_SUBAGENT_CHILD";
 /** pi-subagents sets this instead in a child it places in its own herdr pane. */
 const HERDR_BRIDGE_CHILD_ENV = "PI_SUBAGENTS_HERDR_BRIDGE";
+/** ac-teams sets this in every member it launches. */
+const AC_TEAMS_MEMBER_ENV = "AC_TEAMS_MEMBER";
 
 function agentDir(): string {
 	return process.env.PI_CODING_AGENT_DIR || path.join(os.homedir(), ".pi", "agent");
@@ -622,6 +628,18 @@ export function skillsSection(skills: Map<string, SkillInfo>): string | undefine
 	return lines.join("\n");
 }
 
+/**
+ * The orchestrator text for one kind of session. orchestrator/AGENTS.md marks
+ * the lead-only and delegated-only blocks; each session keeps its own block
+ * and drops the other.
+ */
+export function orchestratorFor(text: string, role: "lead" | "delegated"): string {
+	const other = role === "lead" ? "delegated" : "lead";
+	return text
+		.replace(new RegExp(`<!-- acstack:${other}:start -->[\\s\\S]*?<!-- acstack:${other}:end -->\\n?`, "g"), "")
+		.replace(new RegExp(`<!-- acstack:${role}:(start|end) -->\\n?`, "g"), "");
+}
+
 /**
  * The user message for one ACStack skill, in the same shape pi's own
  * /skill:<name> expansion produces. Built from this package's file, so a
@@ -640,9 +658,9 @@ export function skillInvocation(name: string, file: string, args: string): strin
 // --------------------------------------------------------------------------
 
 export default function acstack(pi: ExtensionAPI): void {
-	// A background subagent loads every ambient extension. The orchestrator
-	// prompt and the nudges belong to the lead session, never to a subagent.
-	if (process.env[SUBAGENT_CHILD_ENV] === "1" || process.env[HERDR_BRIDGE_CHILD_ENV] === "1") return;
+	// A delegated session keeps the shared guidance but not the lead's role,
+	// CLI symlinks, launcher warning, context nudges, or handoff reload.
+	const delegated = process.env[SUBAGENT_CHILD_ENV] === "1" || process.env[HERDR_BRIDGE_CHILD_ENV] === "1" || Boolean(process.env[AC_TEAMS_MEMBER_ENV]);
 
 	const orchestratorFile = path.join(packageRoot, "orchestrator", "AGENTS.md");
 	const styleFile = path.join(packageRoot, "output-styles", "ac-writing-style.md");
@@ -651,7 +669,7 @@ export default function acstack(pi: ExtensionAPI): void {
 	let warnedSubagents = false;
 
 	pi.on("session_start", async (event, ctx) => {
-		linkClis(ctx);
+		if (!delegated) linkClis(ctx);
 		const root = projectRoot(ctx.cwd);
 		if (ensureProjectData(ctx, root)) unsafeProjects.delete(root);
 		else {
@@ -659,6 +677,7 @@ export default function acstack(pi: ExtensionAPI): void {
 			return;
 		}
 
+		if (delegated) return;
 		if (!warnedSubagents && !pi.getAllTools().some((tool) => tool.name === "subagent" || tool.name === "Agent" || tool.name === "team_agent")) {
 			warnedSubagents = true;
 			report(
@@ -686,14 +705,19 @@ export default function acstack(pi: ExtensionAPI): void {
 
 		if (isProject(ctx.cwd)) {
 			const orchestrator = readText(orchestratorFile);
-			if (orchestrator) sections["acstack-orchestrator"] = orchestrator;
+			if (orchestrator) sections["acstack-orchestrator"] = orchestratorFor(orchestrator, delegated ? "delegated" : "lead");
 			else report(ctx, `acstack: could not read ${orchestratorFile}`, "warning");
 		}
 
 		const styleCfg = writingStyleSettings();
 		if (styleCfg.mode === "off") return;
 		const resolvedStyleFile = styleCfg.mode === "custom" && styleCfg.path ? expandUserPath(styleCfg.path) : styleFile;
-		const style = readText(resolvedStyleFile);
+		let style = readText(resolvedStyleFile);
+		// A sandboxed delegated session may not see a custom file outside its read roots.
+		if (!style && delegated && resolvedStyleFile !== styleFile) {
+			report(ctx, `acstack: could not read writing style at ${resolvedStyleFile}; using the bundled style`, "warning");
+			style = readText(styleFile);
+		}
 		if (!style) {
 			report(ctx, `acstack: could not read writing style at ${resolvedStyleFile}`, "warning");
 			return;
@@ -705,7 +729,7 @@ export default function acstack(pi: ExtensionAPI): void {
 		return { message: { customType: "acstack-writing-style-reminder", content: reminder, display: false } };
 	});
 
-	pi.on("agent_before_settle", async (event, ctx) => {
+	if (!delegated) pi.on("agent_before_settle", async (event, ctx) => {
 		if (event.outcome !== "completed") return;
 		const usage = ctx.getContextUsage();
 		if (!usage || usage.tokens === null) return;
@@ -736,7 +760,7 @@ export default function acstack(pi: ExtensionAPI): void {
 		};
 	});
 
-	pi.on("session_compact", async (_event, ctx) => {
+	if (!delegated) pi.on("session_compact", async (_event, ctx) => {
 		// The compaction threw the old context away, so the ladder starts over.
 		const key = sessionKey(ctx);
 		if (key) {
@@ -757,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);