acstack 0.52.5 → 0.52.6

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "acstack",
   "description": "Agentic coding stack where planning grows only as far as needed: a map of decisions, tasks, checks, and handoffs behind a pluggable tracker.",
-  "version": "0.52.5",
+  "version": "0.52.6",
   "author": {
     "name": "ac8318740"
   },

package/cli/package.json

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

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.52.6",
   "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

@@ -80,6 +80,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 +624,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 +654,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 +665,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 +673,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 +701,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 +725,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 +756,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) {