pi-t3-bridge 0.8.0 → 0.8.2

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Change log
 
+## 0.8.2, 6 November 2026
+
+Version 0.8.2 closes a hole in the child sandbox. A delegated child whose brief missed a section or a header field ran with no sandbox and no limits, because the bridge treated it as the user's own session. Such a child could rewrite the parent's git hooks. Now every tool in that child is blocked, and the block lists what the brief is missing, so the parent can resend a complete one. A top-level session is never blocked, even when its first message starts with `# Task:`.
+
+## 0.8.1, 6 November 2026
+
+Version 0.8.1 lets a delegated child run `pnpm install` and `git commit` in a pnpm and lefthook repo, under `bwrap` on Linux and `sandbox-exec` on macOS. Each child gets its own `XDG_RUNTIME_DIR` in the temp folder, where pnpm 12 takes its store lock. The sandbox can now write to the store that `pnpm store path` names for the workdir, and the child uses that store, so it shares the parent's store and does not build a second one in the workdir.
+
+Children now skip install scripts, so a root `prepare` such as `lefthook install` no longer fails on the read-only git hooks. With this setting npm also skips the pre and post scripts of `npm run`, while pnpm still runs them. A brief that needs a postinstall step, such as `next typegen`, should name the build or typecheck that runs it.
+
 ## 0.8.0, 5 November 2026
 
 Version 0.8.0 removes the pi-amplike adapter (`amplike.ts`). The package no longer loads pi-amplike or changes its `/mode`, `/btw`, `/handoff`, and `subagent` for T3. Use T3's own `/btw`, `/side`, model picker, and `delegate_task` instead. If you set `{"source":"npm:pi-amplike","extensions":[]}` for the adapter, remove that entry from `~/.pi/agent/settings.json`.

package/README.md

@@ -29,6 +29,8 @@ You need the following programs:
 
 A delegated child runs its shell commands in a sandbox, which is `sandbox-exec` on macOS and `bwrap` (bubblewrap) on Linux and WSL2. On Linux you need the `bubblewrap` package and unprivileged user namespaces. The Ubuntu `bubblewrap` package ships an AppArmor profile that lets `bwrap` run (checked on 26.04). If AppArmor still blocks `bwrap`, run `sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0`.
 
+Inside the sandbox a child can write only to its workdir, its git directory, the tool caches, the pnpm store, and the system temp folder. The git hooks and git config stay read-only, because the parent runs them later outside the sandbox. Each child gets its own `XDG_RUNTIME_DIR` in the temp folder, where pnpm takes its store lock. The child also gets `pnpm_config_store_dir` set to the store that `pnpm store path` names for the workdir outside the sandbox, so it shares the parent's store. Under `bwrap`, pnpm copies packages from the store, because Linux refuses hardlinks across the sandbox's mounts. Children skip install scripts (`npm_config_ignore_scripts` and `pnpm_config_ignore_scripts` are `true`), so a root `prepare` such as `lefthook install` does not run. With this setting npm also skips the pre and post scripts of `npm run` and `npm test`, while pnpm still runs them. Steps that only a postinstall runs must run through the build or typecheck the brief names.
+
 Native Windows and WSL1 have no sandbox. Where no sandbox can run, the bridge blocks a child's shell commands, unless you set `childSandbox` to `"off"` in the settings file.
 
 ## Install
@@ -228,7 +230,7 @@ To choose your own models, run the `setup-pstack` skill, which writes a model sh
 
 ### Limits for delegated children
 
-When the first message of a session is a complete pstack brief, the extension treats the session as a delegated child and holds it to the limits in the brief. The child can't lift the limits through anything it writes.
+When the first message of a session is a complete pstack brief, the extension treats the session as a delegated child and holds it to the limits in the brief. The child can't lift the limits through anything it writes. A T3-delegated child whose brief has a `# Task:` heading but misses a section or a header field gets every tool blocked, with a list of what is missing, so it never runs without the sandbox.
 
 ```mermaid
 sequenceDiagram

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-t3-bridge",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Pi extension adapter for t3-pstack inside T3 Code.",
   "keywords": [
     "pi-extension",

package/pstack/skills/poteto-mode/brief.md

@@ -60,7 +60,8 @@ ISSUES or BLOCKED: one line each with file:line and the command that shows it
 
 The child's own pstack extension reads this brief from its first message and enforces it, whatever the model does:
 
-- Every shell command runs in a macOS sandbox that can write only to the workdir, its git directory, the tool caches and the system temp folder.
+- Every shell command runs in a sandbox (`sandbox-exec` on macOS, `bwrap` on Linux) that can write only to the workdir, its git directory, the tool caches, the pnpm store and the system temp folder. Git hooks and git config stay read-only.
+- Install scripts are skipped, so `pnpm install` or `npm install` runs no `prepare` or `postinstall`. Don't ask for `prepare` to pass. If a postinstall generates something, such as `next typegen`, name the build or typecheck that runs it in the acceptance command. npm also skips `pre` and `post` scripts of `npm run` and `npm test`, so name those too, as in `npm run prebuild && npm test`.
 - `write` and `edit` only touch the listed files and `.scratch/`.
 - Shell timeouts stop at the time limit. After it, or past the disk limit, every tool is refused and the child can only report.
 - When the child ends its turn, the extension reruns the acceptance command, `git status` and `du`, and appends a "Checked by t3-pstack" block with the real exit codes and STATUS. It also writes a ledger line to `~/.local/state/t3-pstack/ledger.jsonl`.

package/src/pstack/brief.ts

@@ -253,10 +253,9 @@ const dispatchable = (brief: Brief): boolean =>
   brief.diskMb !== undefined &&
   SECTIONS.every((section) => brief.sections.has(section));
 
-// The brief that started this session, when it is a delegated child.
-export const sessionBrief = (
+const firstMessage = (
   ctx: ExtensionContext
-): { readonly brief: Brief; readonly startedAt: number } | undefined => {
+): { readonly at: number; readonly text: string } | undefined => {
   const first = ctx.sessionManager
     .getBranch()
     .find((entry) => entry.type === "message" && entry.message.role === "user");
@@ -267,13 +266,38 @@ export const sessionBrief = (
 
   const { content } = first.message;
 
-  const text = isString(content)
-    ? content
-    : content.map((part) => (part.type === "text" ? part.text : "")).join("\n");
+  return {
+    at: Date.parse(first.timestamp),
+    text: isString(content)
+      ? content
+      : content
+          .map((part) => (part.type === "text" ? part.text : ""))
+          .join("\n"),
+  };
+};
 
-  const brief = parseBrief(text);
+// The brief that started this session, when it is a delegated child.
+export const sessionBrief = (
+  ctx: ExtensionContext
+): { readonly brief: Brief; readonly startedAt: number } | undefined => {
+  const first = firstMessage(ctx);
+  const brief = first === undefined ? undefined : parseBrief(first.text);
+
+  return first === undefined || brief === undefined || !dispatchable(brief)
+    ? undefined
+    : { brief, startedAt: first.at };
+};
+
+// What is wrong with a brief that has a `# Task:` heading but is not complete
+// enough to hold a child to. Undefined when there is no such brief.
+export const incompleteBrief = (
+  ctx: ExtensionContext,
+  rules: BriefRules
+): string[] | undefined => {
+  const first = firstMessage(ctx);
+  const brief = first === undefined ? undefined : parseBrief(first.text);
 
-  return brief === undefined || !dispatchable(brief)
+  return first === undefined || brief === undefined || dispatchable(brief)
     ? undefined
-    : { brief, startedAt: Date.parse(first.timestamp) };
+    : briefProblems(first.text, rules);
 };

package/src/pstack/child.ts

@@ -22,9 +22,9 @@ import {
 
 import { bashTimeoutSeconds } from "../bridge/bash-timeout.ts";
 import { appendLedger } from "../bridge/state.ts";
-import { ownThreadId } from "../bridge/thread.ts";
-import { sessionBrief } from "./brief.ts";
-import type { Brief } from "./brief.ts";
+import { isDelegatedChild, ownThreadId } from "../bridge/thread.ts";
+import { incompleteBrief, sessionBrief } from "./brief.ts";
+import type { Brief, BriefRules } from "./brief.ts";
 import { policyPath } from "./resources.ts";
 import {
   chooseSandbox,
@@ -122,10 +122,22 @@ const isExecFailure = compile(
   )
 ).check;
 
+const isLimits = compile(obj({ files: num(), minutes: num() })).check;
+
 const isPolicy = compile(
   obj(
     {
-      briefs: opt(obj({ redBeforeGreen: opt(arr(str())) }, { open: true })),
+      briefs: opt(
+        obj(
+          {
+            noWrites: opt(arr(str())),
+            redBeforeGreen: opt(arr(str())),
+            sizes: opt(obj({}, { open: true })),
+          },
+          { open: true }
+        )
+      ),
+      jobs: opt(obj({}, { open: true })),
     },
     { open: true }
   )
@@ -139,10 +151,27 @@ const isPathInput = compile(obj({ path: str() }, { open: true })).check;
 
 const isNumber = compile(num()).check;
 
-const readRedBeforeGreen = (): readonly string[] => {
+const readPolicy = () => {
   const policy: unknown = JSON.parse(readFileSync(policyPath(), "utf-8"));
 
-  return isPolicy(policy) ? (policy.briefs?.redBeforeGreen ?? []) : [];
+  return isPolicy(policy) ? policy : {};
+};
+
+const readRedBeforeGreen = (): readonly string[] =>
+  readPolicy().briefs?.redBeforeGreen ?? [];
+
+const readBriefRules = (): BriefRules => {
+  const { briefs, jobs } = readPolicy();
+
+  return {
+    jobs: Object.keys(jobs ?? {}),
+    noWrites: briefs?.noWrites ?? [],
+    sizes: Object.fromEntries(
+      Object.entries(briefs?.sizes ?? {}).flatMap(([size, limits]) =>
+        isLimits(limits) ? [[size, limits] as const] : []
+      )
+    ),
+  };
 };
 
 const changedFiles = async (cwd: string): Promise<string[]> => {
@@ -227,6 +256,7 @@ interface ChildState {
   diskCheck: Promise<void>;
   diskOver: boolean;
   diskQueued: boolean;
+  delegated: boolean | undefined;
   gitDir: string | undefined;
   greenAtStart: boolean;
   ready: boolean;
@@ -237,6 +267,7 @@ export const registerChild = (pi: ExtensionAPI): void => {
   const state: ChildState = {
     baselineKb: undefined,
     before: undefined,
+    delegated: undefined,
     diskCheck: Promise.resolve(),
     diskOver: false,
     diskQueued: false,
@@ -297,7 +328,7 @@ export const registerChild = (pi: ExtensionAPI): void => {
       state.gitDir = undefined;
     }
 
-    state.sandbox = await chooseSandbox(state.gitDir);
+    state.sandbox = await chooseSandbox(ctx.cwd, state.gitDir);
 
     state.baselineKb = await duKb(ctx.cwd);
 
@@ -331,7 +362,22 @@ export const registerChild = (pi: ExtensionAPI): void => {
     const started = sessionBrief(ctx);
 
     if (started === undefined) {
-      return;
+      // A delegated child whose brief is incomplete would otherwise run with
+      // no sandbox and no limits, as if it were the user's own session.
+      const problems = incompleteBrief(ctx, readBriefRules());
+
+      if (problems === undefined) {
+        return;
+      }
+
+      state.delegated ??= await isDelegatedChild();
+
+      return state.delegated
+        ? {
+            block: true,
+            reason: `This delegated task's brief is incomplete, so it can't run in the sandbox and every tool is blocked. Use no more tools. Report STATUS: BLOCKED (incomplete brief) with these problems, so the parent can resend a complete brief:\n- ${problems.join("\n- ")}`,
+          }
+        : undefined;
     }
 
     const { brief, startedAt } = started;

package/src/pstack/sandbox.ts

@@ -1,5 +1,5 @@
 import { execFile } from "node:child_process";
-import { existsSync, mkdirSync, realpathSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, realpathSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
@@ -34,10 +34,17 @@ const isProbeFailure = compile(
   )
 ).check;
 
+// Settled once per child: its own XDG_RUNTIME_DIR, and the pnpm store it
+// shares with the parent.
+interface ChildEnv {
+  readonly pnpmStore: string | undefined;
+  readonly runtimeDir: string;
+}
+
 export type Sandbox =
-  | { kind: "bubblewrap"; bwrap: string }
-  | { kind: "off" }
-  | { kind: "sandbox-exec" }
+  | { kind: "bubblewrap"; bwrap: string; env: ChildEnv }
+  | { kind: "off"; env: ChildEnv }
+  | { kind: "sandbox-exec"; env: ChildEnv }
   | { kind: "unavailable"; reason: string };
 
 const quote = (text: string): string => `'${text.replaceAll("'", `'\\''`)}'`;
@@ -50,8 +57,30 @@ export const real = (target: string): string => {
   }
 };
 
-// Tool caches and installs stay writable, so uv, npm and mise work.
-const cacheRoots = (): string[] => {
+// The store pnpm picks for this workdir outside the sandbox, from project and
+// user config alike. Undefined when pnpm isn't installed. A store at or above
+// home would open all of home, so it stays unbound.
+const pnpmStore = async (workdir: string): Promise<string | undefined> => {
+  try {
+    const { stdout } = await run("pnpm", ["store", "path"], {
+      cwd: workdir,
+      timeout: PROBE_TIMEOUT_MS,
+    });
+
+    const store = path.dirname(stdout.trim());
+    const fromHome = path.relative(store, homedir());
+
+    return path.isAbsolute(store) && fromHome.startsWith("..")
+      ? store
+      : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+// Tool caches, installs and the pnpm store stay writable, so uv, npm, pnpm
+// and mise work.
+const cacheRoots = (store: string | undefined): string[] => {
   const home = homedir();
 
   return [
@@ -59,14 +88,19 @@ const cacheRoots = (): string[] => {
     path.join(home, ".npm"),
     path.join(home, ".local", "share", "uv"),
     path.join(home, ".local", "share", "mise"),
+    ...(store === undefined ? [] : [store]),
   ];
 };
 
-const writableRoots = (workdir: string, gitDir: string | undefined) =>
+const writableRoots = (
+  workdir: string,
+  gitDir: string | undefined,
+  store: string | undefined
+) =>
   [
     workdir,
     gitDir,
-    ...cacheRoots(),
+    ...cacheRoots(store),
     path.join(homedir(), "Library", "Caches"),
     "/private/var/folders",
     tmpdir(),
@@ -114,7 +148,8 @@ const bwrapArgs = (
   bwrap: string,
   command: string,
   workdir: string,
-  gitDir: string | undefined
+  gitDir: string | undefined,
+  store: string | undefined
 ): string[] => [
   bwrap,
   "--ro-bind",
@@ -125,7 +160,7 @@ const bwrapArgs = (
   "/dev",
   "--proc",
   "/proc",
-  ...existing(writableRoots(workdir, gitDir)).flatMap((root) =>
+  ...existing(writableRoots(workdir, gitDir, store)).flatMap((root) =>
     root === "/dev" ? [] : ["--bind", root, root]
   ),
   ...existing(
@@ -158,10 +193,18 @@ const probeBwrap = async (bwrap: string): Promise<string | undefined> => {
 
 // A missing root can't be bound, and a missing hooks directory could be
 // created by the child, so both are made on the host first. They are empty
-// directories, so git and the tools see no change.
-const prepareBinds = (gitDir: string | undefined): void => {
-  for (const root of cacheRoots()) {
-    mkdirSync(root, { recursive: true });
+// directories, so git and the tools see no change. A root the user can't
+// create stays unbound.
+const prepareBinds = (
+  gitDir: string | undefined,
+  store: string | undefined
+): void => {
+  for (const root of cacheRoots(store)) {
+    try {
+      mkdirSync(root, { recursive: true });
+    } catch {
+      continue;
+    }
   }
 
   if (gitDir !== undefined) {
@@ -169,17 +212,23 @@ const prepareBinds = (gitDir: string | undefined): void => {
   }
 };
 
+const childEnv = async (workdir: string): Promise<ChildEnv> => ({
+  pnpmStore: await pnpmStore(workdir),
+  runtimeDir: mkdtempSync(path.join(tmpdir(), "pi-t3-child-")),
+});
+
 // Run once per child, before its first command. "childSandbox": "off" in the
 // config wins on every platform.
 export const chooseSandbox = async (
+  workdir: string,
   gitDir: string | undefined
 ): Promise<Sandbox> => {
   if (readConfig().childSandbox === "off") {
-    return { kind: "off" };
+    return { env: await childEnv(workdir), kind: "off" };
   }
 
   if (process.platform === "darwin" && existsSync(SANDBOX)) {
-    return { kind: "sandbox-exec" };
+    return { env: await childEnv(workdir), kind: "sandbox-exec" };
   }
 
   if (process.platform !== "linux") {
@@ -204,11 +253,24 @@ export const chooseSandbox = async (
     return { kind: "unavailable", reason: problem };
   }
 
-  prepareBinds(gitDir);
+  const env = await childEnv(workdir);
 
-  return { bwrap, kind: "bubblewrap" };
+  prepareBinds(gitDir, env.pnpmStore);
+
+  return { bwrap, env, kind: "bubblewrap" };
 };
 
+// pnpm 12 takes its store lock in $XDG_RUNTIME_DIR, which the sandbox keeps
+// read-only, so each child gets its own. Each bwrap bind is its own mount, and
+// Linux refuses a hardlink between mounts, so pnpm would build a second store
+// in the workdir. Naming the store keeps the one pnpm picked for the parent,
+// and pnpm copies from it. Install scripts stay off, so a `prepare` such as `lefthook install`
+// doesn't fail on the read-only hooks. npm and yarn read npm_config_*, pnpm 11
+// and later read pnpm_config_*. npm also skips pre and post scripts of
+// `npm run` then.
+const exportEnv = (env: ChildEnv, command: string): string =>
+  `export XDG_RUNTIME_DIR=${quote(env.runtimeDir)}${env.pnpmStore === undefined ? "" : ` pnpm_config_store_dir=${quote(env.pnpmStore)}`} npm_config_ignore_scripts=true pnpm_config_ignore_scripts=true; ${command}`;
+
 // Undefined when no sandbox runs: the caller must not run the command.
 export const wrap = (
   sandbox: Sandbox | undefined,
@@ -218,17 +280,29 @@ export const wrap = (
 ): string | undefined => {
   switch (sandbox?.kind) {
     case "sandbox-exec": {
-      return `${SANDBOX} -p ${quote(sandboxProfile(writableRoots(workdir, gitDir), gitDenies(gitDir)))} /bin/bash -c ${quote(command)}`;
+      return exportEnv(
+        sandbox.env,
+        `${SANDBOX} -p ${quote(sandboxProfile(writableRoots(workdir, gitDir, sandbox.env.pnpmStore), gitDenies(gitDir)))} /bin/bash -c ${quote(command)}`
+      );
     }
 
     case "bubblewrap": {
-      return bwrapArgs(sandbox.bwrap, command, workdir, gitDir)
-        .map(quote)
-        .join(" ");
+      return exportEnv(
+        sandbox.env,
+        bwrapArgs(
+          sandbox.bwrap,
+          command,
+          workdir,
+          gitDir,
+          sandbox.env.pnpmStore
+        )
+          .map(quote)
+          .join(" ")
+      );
     }
 
     case "off": {
-      return command;
+      return exportEnv(sandbox.env, command);
     }
 
     default: {