@rosetears/aili-pi 0.1.5 → 0.1.7

package/manifests/subagent-provenance.json

@@ -27,11 +27,21 @@
     },
     {
       "name": "@agwab/pi-subagent",
+      "version": "0.4.8",
       "revision": "daa7b83819116a62008ad17aa65fcd50fefbafd0",
       "license": "MIT",
-      "status": "reference-only",
-      "reusedPatterns": [],
-      "reason": "No community source code is copied or depended on in P5; accepted design evidence is retained for the P8 notice/SBOM audit."
+      "status": "dependency",
+      "reusedPatterns": [
+        "generic subagent tool schema and rendering",
+        "headless/tmux/inline backend and lifecycle envelopes",
+        "bounded parallel fan-out, worktree, sandbox, async, interrupt, and reconcile behavior"
+      ],
+      "localAdaptation": [
+        "ordinary omitted/auto runs use headless for the Pi 0.81.1 compatibility window",
+        "explicit incompatible inline requests fail before model startup",
+        "AILI injects the immutable credential guard and a bounded requested-Agent heading"
+      ],
+      "reason": "AILI depends on the exact package and applies a wrapper-only compatibility adaptation; no upstream source is copied."
     }
   ]
 }

package/notices/pi-sakura-cyberdeck-NOTICE.txt

@@ -2,5 +2,6 @@ This package includes a modified copy of pi-zentui by Luka.
 Original project: https://github.com/lmilojevicc/pi-zentui
 License: MIT. Full license text: licenses/pi-zentui-MIT.txt
 
-Modifications include the Sakura Macaron palette, truecolor gradient editor
-chrome, package-specific defaults, and package-specific configuration path.
+Modifications include the Rem shell palette, retained Sakura Matrix/reasoning
+palette, responsive bounded Matrix track selection, package-specific defaults,
+and package-specific configuration path.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rosetears/aili-pi",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "AILI and ROSE distribution for official Pi",
   "type": "module",
   "license": "MIT",
@@ -68,8 +68,10 @@
     "validate:roles": "npm run verify:roles",
     "sync:adapters": "node --experimental-strip-types scripts/apply-adapter-evidence.ts",
     "validate:compatibility": "node --experimental-strip-types scripts/apply-adapter-evidence.ts --verify",
-    "generate:provenance": "node --experimental-strip-types scripts/generate-provenance.ts",
-    "validate:provenance": "node --experimental-strip-types scripts/generate-provenance.ts --verify",
+    "sync:permission-modes": "node --experimental-strip-types scripts/sync-permission-modes.ts",
+    "verify:permission-modes": "node --experimental-strip-types scripts/sync-permission-modes.ts --verify",
+    "generate:provenance": "node --experimental-strip-types scripts/sync-permission-modes.ts --verify && node --experimental-strip-types scripts/generate-provenance.ts",
+    "validate:provenance": "node --experimental-strip-types scripts/sync-permission-modes.ts --verify && node --experimental-strip-types scripts/generate-provenance.ts --verify",
     "validate:capabilities": "node --experimental-strip-types scripts/validate-runtime.ts",
     "validate:release": "node --experimental-strip-types scripts/validate-runtime.ts --release",
     "test:doctor": "vitest run tests/unit/doctor.test.ts",

package/scripts/generate-provenance.ts

@@ -115,7 +115,7 @@ async function generate(): Promise<{ notices: string; sbom: object }> {
     "",
     `The exact ${packages.length}-entry package-lock inventory, versions, integrity values, dependency scope, and declared licenses is recorded in \`manifests/sbom.json\`.`,
     "",
-    "Runtime dependencies are initialized through the single AILI Extension entry; no third-party source tree is copied into this package.",
+    "Runtime dependencies are initialized through the single AILI Extension entry. Package-owned third-party adaptations are copied only where their provenance sourceFiles explicitly name repository paths.",
     "",
   ].join("\n");
   return { notices, sbom };

package/scripts/sync-permission-modes.ts

@@ -0,0 +1,135 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolvePermissionModesPackageRoot } from "../src/runtime/package-resolution.ts";
+
+const ROOT = resolve(import.meta.dirname, "..");
+const SOURCE_ROOT = fileURLToPath(resolvePermissionModesPackageRoot());
+const VERIFY = process.argv.includes("--verify");
+const VERSION = "2.2.0";
+const REVISION = "23d65d10a53b67043cae42322acf9044d6edb196";
+
+const EXPECTED_UPSTREAM_HASHES: Record<string, string> = {
+  "src/index.ts": "fd4462a3b7ba986af734c2e17ba8ea7178df56c933e87ed444ba90ba24c2fd5b",
+  "src/resolve.ts": "13f52a4a9c08d7a55f5f9d03f97302d864768838fb3e9fca2051cb7d94a0ae82",
+  LICENSE: "d87cb99b43f6bf8771e57be83485db11b977b9dfa21b6bd201b8d3d370bdce43",
+};
+
+const ADAPTATION_HEADER = [
+  "/**",
+  " * Generated AILI adaptation of pi-permission-modes@2.2.0.",
+  " * Source revision: 23d65d10a53b67043cae42322acf9044d6edb196.",
+  " * Regenerate with scripts/sync-permission-modes.ts; do not edit manually.",
+  " */",
+  "",
+].join("\n");
+
+const sha256 = (value: string): string => createHash("sha256").update(value).digest("hex");
+
+function replaceExactlyOnce(source: string, before: string, after: string, label: string): string {
+  const first = source.indexOf(before);
+  if (first < 0 || source.indexOf(before, first + before.length) >= 0) {
+    throw new Error(`expected exactly one ${label} in pi-permission-modes@${VERSION}`);
+  }
+  return source.slice(0, first) + after + source.slice(first + before.length);
+}
+
+function adaptIndex(source: string): string {
+  let redirected = 0;
+  const body = source.replace(/from "\.\/([^"]+)";/g, (full, specifier: string) => {
+    if (specifier === "resolve.ts") return full;
+    redirected += 1;
+    return `from "pi-permission-modes/src/${specifier}";`;
+  });
+  if (redirected !== 12) {
+    throw new Error(`expected 12 redirected sibling imports in pi-permission-modes@${VERSION}, found ${redirected}`);
+  }
+  const documented = replaceExactlyOnce(
+    body,
+    "The logic lives in sibling\n * modules:",
+    "The adapted matcher lives locally; unchanged logic stays in pinned dependency\n * modules:",
+    "entry module ownership comment",
+  );
+  return ADAPTATION_HEADER + documented;
+}
+
+function adaptResolve(source: string): string {
+  const withSchemaRedirect = replaceExactlyOnce(
+    source,
+    'from "./schema.ts";',
+    'from "pi-permission-modes/src/schema.ts";',
+    "schema import",
+  );
+  const withDotAll = replaceExactlyOnce(
+    withSchemaRedirect,
+    "return new RegExp(re).test(t);",
+    'return new RegExp(re, "s").test(t);',
+    "glob RegExp compilation",
+  );
+  return ADAPTATION_HEADER + withDotAll;
+}
+
+async function expectedOutputs(): Promise<Record<string, string>> {
+  const packageJsonText = await readFile(resolve(SOURCE_ROOT, "package.json"), "utf8");
+  const packageJson = JSON.parse(packageJsonText) as { name?: string; version?: string; license?: string };
+  if (packageJson.name !== "pi-permission-modes" || packageJson.version !== VERSION || packageJson.license !== "MIT") {
+    throw new Error(`expected pi-permission-modes@${VERSION} MIT baseline`);
+  }
+
+  const upstream = Object.fromEntries(await Promise.all(
+    Object.keys(EXPECTED_UPSTREAM_HASHES).map(async (path) => [path, await readFile(resolve(SOURCE_ROOT, path), "utf8")]),
+  )) as Record<string, string>;
+  for (const [path, expected] of Object.entries(EXPECTED_UPSTREAM_HASHES)) {
+    const actual = sha256(upstream[path]!);
+    if (actual !== expected) throw new Error(`unexpected upstream drift for ${path}: ${actual}`);
+  }
+
+  const index = adaptIndex(upstream["src/index.ts"]!);
+  const matcher = adaptResolve(upstream["src/resolve.ts"]!);
+  const license = upstream.LICENSE!;
+  const adaptedFiles = {
+    "src/vendor/pi-permission-modes/index.ts": index,
+    "src/vendor/pi-permission-modes/resolve.ts": matcher,
+    "licenses/pi-permission-modes-MIT.txt": license,
+  };
+  const lock = {
+    schemaVersion: 1,
+    package: {
+      name: "pi-permission-modes",
+      version: VERSION,
+      revision: REVISION,
+      license: "MIT",
+    },
+    upstreamFiles: Object.entries(EXPECTED_UPSTREAM_HASHES).map(([path, hash]) => ({ path, sha256: hash })),
+    adaptedFiles: Object.entries(adaptedFiles).map(([path, content]) => ({ path, sha256: sha256(content) })),
+    localChanges: [
+      "Package-owned adapted entry redirects all unchanged sibling modules to the exact pi-permission-modes dependency while owning resolve.ts locally.",
+      "matchPattern compiles its anchored glob RegExp with dotAll so * and ? include ECMAScript line terminators.",
+    ],
+    generatedBy: "scripts/sync-permission-modes.ts",
+    verification: ["npm run verify:permission-modes", "tests/unit/permission-patterns.test.ts", "tests/integration/permission-modes.test.ts"],
+  };
+
+  return {
+    ...adaptedFiles,
+    "upstream/pi-permission-modes.lock.json": `${JSON.stringify(lock, null, 2)}\n`,
+  };
+}
+
+async function main(): Promise<void> {
+  const outputs = await expectedOutputs();
+  for (const [path, expected] of Object.entries(outputs)) {
+    const absolute = resolve(ROOT, path);
+    if (VERIFY) {
+      const actual = await readFile(absolute, "utf8").catch(() => "");
+      if (actual !== expected) throw new Error(`permission-mode adaptation drifted: ${path}`);
+    } else {
+      await mkdir(dirname(absolute), { recursive: true });
+      await writeFile(absolute, expected, "utf8");
+    }
+  }
+  console.log(`${VERIFY ? "PASS" : "SYNCED"}: pi-permission-modes@${VERSION} adapted matcher (${Object.keys(outputs).length} artifacts)`);
+}
+
+await main();

package/src/runtime/native-integrations.ts

@@ -3,7 +3,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 type NativeExtension = (pi: ExtensionAPI) => void | Promise<void>;
 
 export const NATIVE_INTEGRATIONS = [
-  "pi-permission-modes@2.2.0",
+  "pi-permission-modes@2.2.0 (AILI multiline-glob adaptation)",
   "pi-quota-status@0.3.0",
   "pi-web-access@0.13.0",
   "pi-cache-optimizer@2.6.18",
@@ -12,7 +12,7 @@ export const NATIVE_INTEGRATIONS = [
 ] as const;
 
 const INTEGRATION_MODULES = [
-  "pi-permission-modes/src/index.ts",
+  "../vendor/pi-permission-modes/index.ts",
   "pi-quota-status",
   "pi-web-access",
   "pi-cache-optimizer/index.ts",
@@ -21,9 +21,9 @@ const INTEGRATION_MODULES = [
 ] as const;
 
 /**
- * Initialise the pinned upstream extensions through AILI's single package entry.
- * They remain upstream-owned implementations; this module adds no substitute
- * command, tool, permission, or provider behavior.
+ * Initialise pinned native integrations through AILI's single package entry.
+ * Permission modes uses the revision-bound adapted entry that changes only
+ * shared multiline glob matching; the remaining integrations stay upstream-owned.
  */
 export async function registerNativeIntegrations(pi: ExtensionAPI): Promise<void> {
   for (const moduleName of INTEGRATION_MODULES) {

package/src/runtime/package-resolution.ts

@@ -0,0 +1,8 @@
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+
+/** Resolve the installed dependency from either a development tree or npm's hoisted scoped-package layout. */
+export function resolvePermissionModesPackageRoot(from: string | URL = import.meta.url): URL {
+  const packageJson = createRequire(from).resolve("pi-permission-modes/package.json");
+  return new URL("./", pathToFileURL(packageJson));
+}

package/src/runtime/registry.ts

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { access, readFile, readdir } from "node:fs/promises";
 import { loadRoleProfiles, validateRoleProfiles } from "./roles.ts";
+import { resolvePermissionModesPackageRoot } from "./package-resolution.ts";
 
 const ROOT = new URL("../../", import.meta.url);
 
@@ -143,30 +144,158 @@ export async function validateLiveVerification(): Promise<string[]> {
   const errors: string[] = [];
   try {
     const evidence = await json<{
-      schemaVersion?: number; platform?: string; piVersion?: string; status?: string;
-      probes?: Array<{ id?: string; status?: string; changedFiles?: number }>;
+      schemaVersion?: number; platform?: string; piVersion?: string; subagentVersion?: string; status?: string;
+      probes?: Array<{
+        id?: string;
+        status?: string;
+        changedFiles?: number | null;
+        backendRequest?: string;
+        resolvedBackend?: string | null;
+      }>;
       implementation?: Record<string, string>;
     }>("manifests/live-verification.json");
-    if (evidence.schemaVersion !== 1 || evidence.platform !== "linux" || evidence.piVersion !== "0.81.1" || evidence.status !== "passed") errors.push("live verification: identity is incomplete or non-pass");
-    const genericProbe = evidence.probes?.find((probe) => probe.id === "generic-agentless-read-package");
-    const credentialProbe = evidence.probes?.find((probe) => probe.id === "generic-credential-guard");
-    if (evidence.probes?.length !== 3 || evidence.probes.some((probe) => probe.status !== "passed") || genericProbe?.changedFiles !== 0 || credentialProbe?.changedFiles !== 0) {
-      errors.push("live verification: required probes are missing, non-pass, or mutated files");
+    if (
+      evidence.schemaVersion !== 2 ||
+      evidence.platform !== "linux" ||
+      evidence.piVersion !== "0.81.1" ||
+      evidence.subagentVersion !== "0.4.8" ||
+      evidence.status !== "passed"
+    ) {
+      errors.push("live verification: compatibility identity is incomplete or non-pass");
     }
+    const fixtureProbe = evidence.probes?.find((probe) => probe.id === "generic-subagent-fixtures");
+    const defaultProbe = evidence.probes?.find((probe) => probe.id === "generic-agentless-default-path");
+    const credentialProbe = evidence.probes?.find((probe) => probe.id === "generic-credential-guard-explicit-headless");
+    if (
+      evidence.probes?.length !== 3 ||
+      fixtureProbe?.status !== "passed" ||
+      defaultProbe?.status !== "passed" ||
+      defaultProbe.backendRequest !== "omitted" ||
+      defaultProbe.resolvedBackend !== "headless" ||
+      defaultProbe.changedFiles !== 0 ||
+      credentialProbe?.status !== "passed" ||
+      credentialProbe.backendRequest !== "explicit-headless" ||
+      credentialProbe.resolvedBackend !== "headless" ||
+      credentialProbe.changedFiles !== 0
+    ) {
+      errors.push("live verification: default-path/headless probes are missing, ambiguous, non-pass, or mutated files");
+    }
+    const requiredImplementation = [
+      "src/runtime/subagents.ts",
+      "tests/unit/subagents.test.ts",
+      "tests/integration/live-subagent.test.ts",
+    ];
     for (const [filePath, expected] of Object.entries(evidence.implementation ?? {})) {
       const content = await readFile(new URL(filePath, ROOT), "utf8");
       const actual = createHash("sha256").update(content).digest("hex");
       if (actual !== expected) errors.push(`live verification: implementation drift ${filePath}`);
     }
-    if (Object.keys(evidence.implementation ?? {}).length !== 3) errors.push("live verification: implementation binding must contain exactly three files");
+    if (JSON.stringify(Object.keys(evidence.implementation ?? {}).sort()) !== JSON.stringify(requiredImplementation.sort())) {
+      errors.push("live verification: implementation binding must contain the exact default-path files");
+    }
   } catch (error) {
     errors.push(`live verification: ${error instanceof Error ? error.message : String(error)}`);
   }
   return errors;
 }
 
-export async function validateProvenance(): Promise<string[]> {
+export async function validatePermissionModeAdaptation(): Promise<string[]> {
   const errors: string[] = [];
+  try {
+    const lock = await json<{
+      schemaVersion?: number;
+      package?: { name?: string; version?: string; revision?: string; license?: string };
+      upstreamFiles?: Array<{ path?: string; sha256?: string }>;
+      adaptedFiles?: Array<{ path?: string; sha256?: string }>;
+      localChanges?: string[];
+      generatedBy?: string;
+      verification?: string[];
+    }>("upstream/pi-permission-modes.lock.json");
+    const expectedLocalChanges = [
+      "Package-owned adapted entry redirects all unchanged sibling modules to the exact pi-permission-modes dependency while owning resolve.ts locally.",
+      "matchPattern compiles its anchored glob RegExp with dotAll so * and ? include ECMAScript line terminators.",
+    ];
+    const expectedVerification = [
+      "npm run verify:permission-modes",
+      "tests/unit/permission-patterns.test.ts",
+      "tests/integration/permission-modes.test.ts",
+    ];
+    if (
+      lock.schemaVersion !== 1 ||
+      lock.package?.name !== "pi-permission-modes" ||
+      lock.package.version !== "2.2.0" ||
+      lock.package.revision !== "23d65d10a53b67043cae42322acf9044d6edb196" ||
+      lock.package.license !== "MIT" ||
+      lock.upstreamFiles?.length !== 3 ||
+      lock.adaptedFiles?.length !== 3 ||
+      JSON.stringify(lock.localChanges) !== JSON.stringify(expectedLocalChanges) ||
+      lock.generatedBy !== "scripts/sync-permission-modes.ts" ||
+      JSON.stringify(lock.verification) !== JSON.stringify(expectedVerification)
+    ) {
+      errors.push("permission adaptation: lock identity or inventory is incomplete");
+      return errors;
+    }
+    const expectedUpstream = {
+      "src/index.ts": "fd4462a3b7ba986af734c2e17ba8ea7178df56c933e87ed444ba90ba24c2fd5b",
+      "src/resolve.ts": "13f52a4a9c08d7a55f5f9d03f97302d864768838fb3e9fca2051cb7d94a0ae82",
+      LICENSE: "d87cb99b43f6bf8771e57be83485db11b977b9dfa21b6bd201b8d3d370bdce43",
+    };
+    const upstreamIdentity = Object.fromEntries((lock.upstreamFiles ?? []).map((record) => [record.path, record.sha256]));
+    if (JSON.stringify(upstreamIdentity) !== JSON.stringify(expectedUpstream)) {
+      errors.push("permission adaptation: upstream baseline hashes do not match the accepted 2.2.0 revision");
+    }
+    const expectedAdapted = {
+      "src/vendor/pi-permission-modes/index.ts": "8bfa0364967a2b76e9900cc72b8f434ea1cfa6520899c7827488220f2e288ee8",
+      "src/vendor/pi-permission-modes/resolve.ts": "f71688f847495da5122724f75c5ebe3b41066b3d3cac74cbe99f66b9906404f6",
+      "licenses/pi-permission-modes-MIT.txt": "d87cb99b43f6bf8771e57be83485db11b977b9dfa21b6bd201b8d3d370bdce43",
+    };
+    const adaptedIdentity = Object.fromEntries((lock.adaptedFiles ?? []).map((record) => [record.path, record.sha256]));
+    if (JSON.stringify(adaptedIdentity) !== JSON.stringify(expectedAdapted)) {
+      errors.push("permission adaptation: adapted hashes or file inventory do not match the accepted generated output");
+    }
+    const permissionPackageRoot = resolvePermissionModesPackageRoot();
+    const installedPackage = JSON.parse(await readFile(new URL("package.json", permissionPackageRoot), "utf8")) as {
+      name?: string;
+      version?: string;
+      license?: string;
+    };
+    if (installedPackage.name !== "pi-permission-modes" || installedPackage.version !== "2.2.0" || installedPackage.license !== "MIT") {
+      errors.push("permission adaptation: resolved dependency identity is not exact pi-permission-modes@2.2.0 MIT");
+    }
+    for (const [kind, records, sourceRoot] of [
+      ["upstream", lock.upstreamFiles, permissionPackageRoot],
+      ["adapted", lock.adaptedFiles, ROOT],
+    ] as const) {
+      for (const record of records ?? []) {
+        const path = record.path ?? "";
+        if (!path || path.startsWith("/") || path.split("/").includes("..") || !/^[0-9a-f]{64}$/.test(record.sha256 ?? "")) {
+          errors.push(`permission adaptation: unsafe or incomplete ${kind} record ${path || "(missing)"}`);
+          continue;
+        }
+        const content = await readFile(new URL(path, sourceRoot), "utf8");
+        const actual = createHash("sha256").update(content).digest("hex");
+        if (actual !== record.sha256) errors.push(`permission adaptation: ${kind} drift ${path}`);
+      }
+    }
+    const [nativeIntegration, adaptedResolve] = await Promise.all([
+      readFile(new URL("src/runtime/native-integrations.ts", ROOT), "utf8"),
+      readFile(new URL("src/vendor/pi-permission-modes/resolve.ts", ROOT), "utf8"),
+    ]);
+    const adaptedEntryCount = nativeIntegration.match(/"\.\.\/vendor\/pi-permission-modes\/index\.ts"/g)?.length ?? 0;
+    if (adaptedEntryCount !== 1 || nativeIntegration.includes('"pi-permission-modes/src/index.ts"')) {
+      errors.push("permission adaptation: native integration is not bound exactly once and exclusively to the adapted entry");
+    }
+    if (!adaptedResolve.includes('return new RegExp(re, "s").test(t);') || adaptedResolve.includes("return new RegExp(re).test(t);")) {
+      errors.push("permission adaptation: line-terminator-safe matcher semantic is missing");
+    }
+  } catch (error) {
+    errors.push(`permission adaptation: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  return errors;
+}
+
+export async function validateProvenance(): Promise<string[]> {
+  const errors: string[] = [...await validatePermissionModeAdaptation()];
   try {
     const provenance = await json<{ schemaVersion: number; sources: Array<{ name: string; revision: string; license: string; status: string; repository: string; sourceFiles: string[]; symbols: string[]; localChanges: string[]; verification: string[] }> }>("manifests/provenance.json");
     const sbom = await json<{ spdxVersion?: string; packages?: Array<{ SPDXID?: string; name?: string; licenseDeclared?: string }> }>("manifests/sbom.json");

package/src/runtime/subagents.ts

@@ -1,5 +1,7 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { fileURLToPath } from "node:url";
+import { stripVTControlCharacters } from "node:util";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Container, type Component, Text } from "@earendil-works/pi-tui";
 import { validateRoleProfiles } from "./roles.js";
 
 const CREDENTIAL_GUARD_EXTENSION = fileURLToPath(new URL("./credential-guard.ts", import.meta.url));
@@ -9,16 +11,80 @@ const CREDENTIAL_GUARD_EXTENSION = fileURLToPath(new URL("./credential-guard.ts"
 const REQUIRED_CHILD_EXTENSIONS = [CREDENTIAL_GUARD_EXTENSION] as const;
 
 type UnknownRecord = Record<string, unknown>;
+type RenderTheme = {
+  fg(style: string, text: string): string;
+  bold(text: string): string;
+};
 type GenericTool = {
   name?: unknown;
   execute?: (...args: unknown[]) => unknown;
+  renderCall?: (args: unknown, theme: RenderTheme) => Component;
   [key: string]: unknown;
 };
 
+type SubagentCompatibilityPlan =
+  | { kind: "forward"; params: unknown }
+  | { kind: "reject"; requestedBackend: "inline" | "auto"; error: string };
+
+type AgentHeading = {
+  label: "Agent" | "Agents";
+  summary: string;
+};
+
+const MAX_AGENT_NAME_LENGTH = 48;
+const MAX_AGENT_SUMMARY_LENGTH = 120;
+const INLINE_COMPATIBILITY_ERROR =
+  "inline backend is incompatible with Pi 0.81.1 and @agwab/pi-subagent 0.4.8; use backend \"headless\"";
+const MIXED_PARALLEL_COMPATIBILITY_ERROR =
+  "auto backend cannot safely combine visible tasks with ordinary non-visible, non-sandboxed tasks on Pi 0.81.1 and @agwab/pi-subagent 0.4.8; split the fan-out or choose one explicit compatible backend";
+
 function isRecord(value: unknown): value is UnknownRecord {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+function truncateDisplayText(value: string, maxLength: number): string {
+  const characters = [...value];
+  return characters.length <= maxLength
+    ? value
+    : `${characters.slice(0, Math.max(0, maxLength - 1)).join("")}…`;
+}
+
+function requestedAgentName(value: unknown): string {
+  if (typeof value !== "string") return "agentless";
+  const normalized = stripVTControlCharacters(value)
+    .replace(/[\r\n\t\f\v]+/g, " ")
+    .replace(/[\u0000-\u001f\u007f-\u009f]/g, "")
+    .replace(/\p{Cf}/gu, "")
+    .replace(/\s+/g, " ")
+    .trim();
+  return normalized
+    ? truncateDisplayText(normalized, MAX_AGENT_NAME_LENGTH)
+    : "agentless";
+}
+
+function requestedAgentHeading(params: unknown): AgentHeading | undefined {
+  if (!isRecord(params)) return undefined;
+  const action = typeof params.action === "string" ? params.action : "run";
+  if (action !== "run") return undefined;
+
+  const tasks = Array.isArray(params.tasks) ? params.tasks : undefined;
+  const isParallel = tasks !== undefined;
+  const names = tasks
+    ? tasks.map((task: unknown) => requestedAgentName(isRecord(task) ? task.agent : undefined))
+    : [requestedAgentName(params.agent)];
+  if (names.length === 0) names.push("agentless");
+
+  const counts = new Map<string, number>();
+  for (const name of names) counts.set(name, (counts.get(name) ?? 0) + 1);
+  const summary = [...counts]
+    .map(([name, count]) => count > 1 ? `${name} ×${count}` : name)
+    .join(", ");
+  return {
+    label: isParallel ? "Agents" : "Agent",
+    summary: truncateDisplayText(summary, MAX_AGENT_SUMMARY_LENGTH),
+  };
+}
+
 function withRequiredExtensions(value: unknown): unknown {
   if (!isRecord(value)) return value;
   if (value.extensions !== undefined && !Array.isArray(value.extensions)) return value;
@@ -30,6 +96,69 @@ function withRequiredExtensions(value: unknown): unknown {
   };
 }
 
+function sandboxRequested(value: unknown): boolean {
+  return value !== undefined && value !== null && value !== false;
+}
+
+function taskSelector(
+  task: UnknownRecord,
+  parent: UnknownRecord,
+): { visible: boolean; sandboxed: boolean; plain: boolean } {
+  const visible = task.visible === undefined ? parent.visible === true : task.visible === true;
+  const sandbox = Object.hasOwn(task, "sandbox") ? task.sandbox : parent.sandbox;
+  const sandboxed = sandboxRequested(sandbox);
+  return { visible, sandboxed, plain: !visible && !sandboxed };
+}
+
+/**
+ * Select a Pi-0.81.1-compatible backend without changing compatible explicit,
+ * visible, sandboxed, or lifecycle requests. Parallel auto calls are evaluated
+ * per task because task-level visible/sandbox values override their parent.
+ */
+export function normalizeSubagentCompatibility(params: unknown): SubagentCompatibilityPlan {
+  if (!isRecord(params) || (params.action !== undefined && params.action !== "run")) {
+    return { kind: "forward", params };
+  }
+
+  if (params.backend === "inline") {
+    return { kind: "reject", requestedBackend: "inline", error: INLINE_COMPATIBILITY_ERROR };
+  }
+  if (params.backend !== undefined && params.backend !== "auto") return { kind: "forward", params };
+
+  if (Array.isArray(params.tasks)) {
+    if (params.tasks.length === 0 || params.tasks.some((task) => !isRecord(task))) {
+      return { kind: "forward", params };
+    }
+    const selectors = params.tasks.map((task) => taskSelector(task as UnknownRecord, params));
+    const hasPlain = selectors.some((selector) => selector.plain);
+    const hasVisible = selectors.some((selector) => selector.visible);
+    if (hasPlain && hasVisible) {
+      return { kind: "reject", requestedBackend: "auto", error: MIXED_PARALLEL_COMPATIBILITY_ERROR };
+    }
+    if (hasPlain) return { kind: "forward", params: { ...params, backend: "headless" } };
+    return { kind: "forward", params };
+  }
+
+  if (params.visible === true || sandboxRequested(params.sandbox)) return { kind: "forward", params };
+  return { kind: "forward", params: { ...params, backend: "headless" } };
+}
+
+function compatibilityFailure(plan: Extract<SubagentCompatibilityPlan, { kind: "reject" }>): UnknownRecord {
+  const payload = {
+    tool: "subagent",
+    ...(plan.requestedBackend === "inline" ? { backend: "inline" } : {}),
+    requestedBackend: plan.requestedBackend,
+    status: "failed",
+    failureKind: "validation",
+    error: plan.error,
+  };
+  return {
+    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+    details: { compatibility: payload },
+    isError: true,
+  };
+}
+
 /**
  * Adds the immutable child credential guard to every run path while preserving
  * the ambient AILI permission-mode extension and all caller options.
@@ -46,27 +175,50 @@ export function protectSubagentParams(params: unknown): unknown {
   };
 }
 
-function wrapGenericTool(tool: GenericTool): GenericTool {
+export function wrapSubagentTool(tool: GenericTool): GenericTool {
   if (tool.name !== "subagent" || typeof tool.execute !== "function") return tool;
   const execute = tool.execute;
+  const renderCall = tool.renderCall;
   return {
     ...tool,
+    ...(typeof renderCall === "function"
+      ? {
+          renderCall(args: unknown, theme: RenderTheme): Component {
+            const plan = normalizeSubagentCompatibility(args);
+            const effectiveArgs = plan.kind === "forward" ? plan.params : args;
+            const upstream = renderCall(effectiveArgs, theme);
+            const heading = requestedAgentHeading(args);
+            if (!heading) return upstream;
+            const container = new Container();
+            container.addChild(new Text(
+              `${theme.fg("muted", `${heading.label}:`)} ${theme.fg("accent", heading.summary)}`,
+              0,
+              0,
+            ));
+            container.addChild(upstream);
+            return container;
+          },
+        }
+      : {}),
     async execute(...args: unknown[]) {
-      // Pi has supported execute(params, ...) and execute(id, params, ...).
-      // Delegate both shapes back to the upstream implementation unchanged
-      // except for mandatory child extensions on `action: run`.
-      const paramsIndex = args.length > 1 && args[1] !== undefined ? 1 : 0;
+      // Current Pi uses execute(id, params, ...); older direct fixtures may call
+      // execute(params). Detect the object position rather than mistaking a
+      // signal/callback for params.
+      const paramsIndex = isRecord(args[0]) || args.length === 1 ? 0 : 1;
+      const plan = normalizeSubagentCompatibility(args[paramsIndex]);
+      if (plan.kind === "reject") return compatibilityFailure(plan);
       const protectedArgs = [...args];
-      protectedArgs[paramsIndex] = protectSubagentParams(protectedArgs[paramsIndex]);
+      protectedArgs[paramsIndex] = protectSubagentParams(plan.params);
       return await execute(...protectedArgs);
     },
   };
 }
 
 /**
- * Registers the upstream `subagent` tool unchanged in name, schema, and
- * lifecycle behavior. AILI injects non-removable credential protection while
- * the child loads the ambient AILI permission-mode extension exactly once.
+ * Registers the upstream `subagent` name, schema, lifecycle, and worker engine.
+ * AILI wraps backend selection for the pinned SDK compatibility window, adds a
+ * bounded requested-Agent heading, and injects non-removable credential
+ * protection while each child loads permission modes exactly once.
  */
 export async function registerSubagent(pi: ExtensionAPI): Promise<void> {
   let genericToolRegistered = false;
@@ -75,7 +227,7 @@ export async function registerSubagent(pi: ExtensionAPI): Promise<void> {
       if (property === "registerTool") {
         return (tool: GenericTool) => {
           if (tool?.name === "subagent") genericToolRegistered = true;
-          return target.registerTool(wrapGenericTool(tool) as never);
+          return target.registerTool(wrapSubagentTool(tool) as never);
         };
       }
       const value = Reflect.get(target, property, receiver);