@rosetears/aili-pi 0.1.6 → 0.1.8

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/rose-theme.ts

@@ -0,0 +1,26 @@
+import { existsSync, readFileSync } from "node:fs";
+
+const LEGACY_THEME = "rem-cyberdeck";
+const ROSE_THEME = "rose-cyberdeck";
+
+/** Return non-mutating exact-token guidance for a legacy Pi theme setting. */
+export function legacyRoseThemeGuidance(theme: unknown): string | undefined {
+  if (typeof theme !== "string") return undefined;
+  const parts = theme.split("/");
+  if (!parts.some((part) => part === LEGACY_THEME)) return undefined;
+  const replacement = parts.map((part) => part === LEGACY_THEME ? ROSE_THEME : part).join("/");
+  return `Rose Cyberdeck renamed ${LEGACY_THEME} to ${ROSE_THEME}. Use /settings or edit settings.json: \"theme\": \"${replacement}\".`;
+}
+
+/** Read-only startup compatibility detector; malformed settings are intentionally silent. */
+export function legacyRoseThemeGuidanceFromSettings(path: string): string | undefined {
+  try {
+    if (!existsSync(path)) return undefined;
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+    return parsed !== null && typeof parsed === "object" && "theme" in parsed
+      ? legacyRoseThemeGuidance((parsed as { theme?: unknown }).theme)
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/src/runtime/subagents.ts

@@ -22,6 +22,10 @@ type GenericTool = {
   [key: string]: unknown;
 };
 
+type SubagentCompatibilityPlan =
+  | { kind: "forward"; params: unknown }
+  | { kind: "reject"; requestedBackend: "inline" | "auto"; error: string };
+
 type AgentHeading = {
   label: "Agent" | "Agents";
   summary: string;
@@ -29,6 +33,10 @@ type AgentHeading = {
 
 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);
@@ -88,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.
@@ -113,7 +184,9 @@ export function wrapSubagentTool(tool: GenericTool): GenericTool {
     ...(typeof renderCall === "function"
       ? {
           renderCall(args: unknown, theme: RenderTheme): Component {
-            const upstream = renderCall(args, theme);
+            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();
@@ -128,22 +201,24 @@ export function wrapSubagentTool(tool: GenericTool): GenericTool {
         }
       : {}),
     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, execution,
- * and lifecycle behavior. AILI adds a bounded requested-Agent heading and
- * injects non-removable credential protection while each 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;