pi-landstrip 0.17.21 → 0.17.23

package/README.md

@@ -1,5 +1,12 @@
 # pi-landstrip
 
+```
+Subagents  3 active
+├─ ● running  @explore  Design Pi entry parsing
+├─ ● running  @general  Design trigger serialization
+└─ ● running  @general  Design bounded summaries
+```
+
 `pi-landstrip` is a [Pi](https://pi.dev/) extension that provides sandboxed Bash
 execution, OpenCode-compatible primary agents, and sandbox-aware subagents. It
 uses an Anthropic-compatible policy and delegates OS-level enforcement to
@@ -239,6 +246,62 @@ follows, then remove the old fields:
 Do not put these fields in Pi's `settings.json`; `pi-landstrip` does not read
 them there.
 
+## Plugin API
+
+Pi extensions can discover the active Landstrip runtime through the versioned
+API exported by `pi-landstrip/api`:
+
+```ts
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { useLandstrip } from 'pi-landstrip/api';
+
+export default function (pi: ExtensionAPI) {
+  const dispose = useLandstrip(pi, (landstrip) => {
+    const context = landstrip.getContext();
+    // Register Landstrip-aware behavior here.
+  });
+  pi.on('session_shutdown', dispose);
+}
+```
+
+Discovery is callback-based so it works regardless of extension load order.
+Do not wait for discovery from an extension factory: Pi initializes extension
+factories sequentially. The returned function stops future notifications.
+
+The runtime exposes:
+
+- `getContext()` for the host, role, sandbox state, task identity, agent and
+  nesting depth.
+- `createBashTool()` for extensions that need Landstrip execution with their
+  own tool presentation.
+- `prepareProcess()` for single-use process launches under the effective
+  sandbox policy.
+- `registerWorkerExtension()` to load an absolute extension entry in Landstrip
+  subagents. The returned function removes the registration.
+- `on()` for typed `sandbox.changed`, `subagent.start` and `subagent.end`
+  lifecycle events.
+
+Registered worker extensions are trusted code. Landstrip adds their canonical
+directories and dependency roots to worker read access, loads them with Pi's
+`--extension` option, and propagates them to nested tasks.
+
+Workers receive a base64url JSON `LANDSTRIP_CONTEXT` environment variable.
+Extensions can read it without runtime discovery:
+
+```ts
+import { contextFromEnvironment } from 'pi-landstrip/api';
+
+const context = contextFromEnvironment();
+```
+
+This public context is informational and contains no permission rules, policy,
+credentials or proxy secrets. Environment values can be spoofed outside a
+Landstrip worker and must not be treated as authorization.
+
+Generic process preparation fails closed on Windows when sandboxing is disabled.
+Windows cannot reliably reclaim an unsandboxed descendant tree after its leader
+has exited; enabled Landstrip launches use an AppContainer job object instead.
+
 ## Limits
 
 `pi-landstrip` grants at most `maxSubagents` scheduler permits to active

package/api.ts

@@ -0,0 +1,198 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) Jarkko Sakkinen 2026
+
+import type { ChildProcess, SpawnOptions } from 'node:child_process';
+
+import {
+  createBashToolDefinition,
+  type ExtensionAPI,
+  type ExtensionContext,
+} from '@earendil-works/pi-coding-agent';
+
+import type { RpcChildProcess } from './rpc-process.ts';
+
+export const LANDSTRIP_CONTEXT_ENV = 'LANDSTRIP_CONTEXT';
+export const LANDSTRIP_RUNTIME_VERSION = 1;
+
+const RUNTIME_REGISTER_EVENT = 'landstrip:runtime:register:v1';
+const RUNTIME_DISCOVER_EVENT = 'landstrip:runtime:discover:v1';
+
+export type LandstripSandboxState = 'enabled' | 'disabled' | 'unavailable';
+export type LandstripBashTool = ReturnType<typeof createBashToolDefinition>;
+
+export interface LandstripContextV1 {
+  readonly version: 1;
+  readonly host: 'pi';
+  readonly role: 'primary' | 'subagent';
+  readonly sandbox: LandstripSandboxState;
+  readonly cwd: string;
+  readonly sessionId?: string;
+  readonly taskId?: string;
+  readonly parentTaskId?: string;
+  readonly agent?: string;
+  readonly depth: number;
+}
+
+export interface LandstripWorkerExtension {
+  readonly id: string;
+  readonly entry: string;
+}
+
+export interface LandstripProcessOptions {
+  readonly command: string;
+  readonly args: readonly string[];
+  readonly cwd: string;
+  readonly env?: NodeJS.ProcessEnv;
+  readonly ctx: ExtensionContext;
+  readonly readPaths?: readonly string[];
+  readonly writePaths?: readonly string[];
+  readonly signal?: AbortSignal;
+}
+
+export interface LandstripPreparedProcess {
+  readonly command: string;
+  readonly args: readonly string[];
+  readonly cwd: string;
+  readonly env: NodeJS.ProcessEnv;
+  readonly spawn: LandstripSpawn;
+  dispose(): Promise<void>;
+}
+
+export type LandstripSpawn = (
+  command: string,
+  args: readonly string[],
+  options: SpawnOptions,
+) => ChildProcess | RpcChildProcess;
+
+export type LandstripEvent =
+  | { readonly type: 'sandbox.changed'; readonly context: LandstripContextV1 }
+  | { readonly type: 'subagent.start'; readonly context: LandstripContextV1 }
+  | {
+      readonly type: 'subagent.end';
+      readonly context: LandstripContextV1;
+      readonly status: 'completed' | 'cancelled' | 'error';
+    };
+
+export interface PiLandstripRuntimeV1 {
+  readonly version: 1;
+  getContext(ctx?: ExtensionContext): LandstripContextV1;
+  createBashTool(cwd: string, ctx?: ExtensionContext): LandstripBashTool;
+  prepareProcess(options: LandstripProcessOptions): Promise<LandstripPreparedProcess>;
+  registerWorkerExtension(extension: LandstripWorkerExtension): () => void;
+  getWorkerExtensions(): readonly LandstripWorkerExtension[];
+  on<T extends LandstripEvent['type']>(
+    type: T,
+    handler: (event: Extract<LandstripEvent, { type: T }>) => void,
+  ): () => void;
+}
+
+interface RuntimeRegistration {
+  readonly version: 1;
+  readonly runtime: PiLandstripRuntimeV1;
+}
+
+interface RuntimeDiscovery {
+  readonly version: 1;
+  register(runtime: PiLandstripRuntimeV1): void;
+}
+
+interface EventBusLike {
+  emit(channel: string, data: unknown): void;
+  on(channel: string, handler: (data: unknown) => void): () => void;
+}
+
+function eventBus(pi: ExtensionAPI): EventBusLike | undefined {
+  return (pi as ExtensionAPI & { events?: EventBusLike }).events;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isRuntime(value: unknown): value is PiLandstripRuntimeV1 {
+  return (
+    isRecord(value) &&
+    value.version === LANDSTRIP_RUNTIME_VERSION &&
+    typeof value.getContext === 'function' &&
+    typeof value.createBashTool === 'function' &&
+    typeof value.prepareProcess === 'function' &&
+    typeof value.registerWorkerExtension === 'function' &&
+    typeof value.getWorkerExtensions === 'function' &&
+    typeof value.on === 'function'
+  );
+}
+
+export function useLandstrip(
+  pi: ExtensionAPI,
+  callback: (runtime: PiLandstripRuntimeV1) => void,
+): () => void {
+  const events = eventBus(pi);
+  if (!events) return () => undefined;
+
+  let current: PiLandstripRuntimeV1 | undefined;
+  const register = (runtime: PiLandstripRuntimeV1): void => {
+    if (runtime === current) return;
+    current = runtime;
+    callback(runtime);
+  };
+  const unsubscribe = events.on(RUNTIME_REGISTER_EVENT, (value) => {
+    if (!isRecord(value) || value.version !== LANDSTRIP_RUNTIME_VERSION) return;
+    if (isRuntime(value.runtime)) register(value.runtime);
+  });
+  events.emit(RUNTIME_DISCOVER_EVENT, {
+    version: LANDSTRIP_RUNTIME_VERSION,
+    register,
+  } satisfies RuntimeDiscovery);
+  return unsubscribe;
+}
+
+export function publishLandstripRuntime(
+  pi: ExtensionAPI,
+  runtime: PiLandstripRuntimeV1,
+): () => void {
+  const events = eventBus(pi);
+  if (!events) return () => undefined;
+
+  const unsubscribe = events.on(RUNTIME_DISCOVER_EVENT, (value) => {
+    if (!isRecord(value) || value.version !== LANDSTRIP_RUNTIME_VERSION) return;
+    if (typeof value.register === 'function') value.register(runtime);
+  });
+  events.emit(RUNTIME_REGISTER_EVENT, {
+    version: LANDSTRIP_RUNTIME_VERSION,
+    runtime,
+  } satisfies RuntimeRegistration);
+  return unsubscribe;
+}
+
+export function encodeLandstripContext(context: LandstripContextV1): string {
+  return Buffer.from(JSON.stringify(context)).toString('base64url');
+}
+
+export function contextFromEnvironment(
+  env: NodeJS.ProcessEnv = process.env,
+): LandstripContextV1 | undefined {
+  const encoded = env[LANDSTRIP_CONTEXT_ENV];
+  if (!encoded) return undefined;
+
+  try {
+    const value: unknown = JSON.parse(Buffer.from(encoded, 'base64url').toString('utf8'));
+    if (
+      !isRecord(value) ||
+      value.version !== LANDSTRIP_RUNTIME_VERSION ||
+      value.host !== 'pi' ||
+      value.role !== 'subagent' ||
+      !['enabled', 'disabled', 'unavailable'].includes(String(value.sandbox)) ||
+      typeof value.cwd !== 'string' ||
+      !Number.isInteger(value.depth) ||
+      Number(value.depth) < 0 ||
+      ['sessionId', 'taskId', 'parentTaskId', 'agent'].some(
+        (key) => value[key] !== undefined && typeof value[key] !== 'string',
+      )
+    ) {
+      return undefined;
+    }
+    return value as unknown as LandstripContextV1;
+  } catch {
+    return undefined;
+  }
+}

package/index.ts

@@ -53,6 +53,18 @@ import {
   type LandstripNetworkTrap,
   type LandstripTrap,
 } from '@landstrip/landstrip';
+import {
+  type LandstripBashTool,
+  type LandstripContextV1,
+  type LandstripEvent,
+  type LandstripPreparedProcess,
+  type LandstripProcessOptions,
+  type LandstripSandboxState,
+  type LandstripWorkerExtension,
+  LANDSTRIP_RUNTIME_VERSION,
+  type PiLandstripRuntimeV1,
+  publishLandstripRuntime,
+} from './api.ts';
 import type { RpcSpawn } from './rpc-process.ts';
 import {
   type SubagentRuntime,
@@ -766,6 +778,24 @@ function patchProcessGroupKill(child: ChildProcess): void {
   };
 }
 
+async function stopPreparedChild(child: ChildProcess | undefined): Promise<void> {
+  if (!child) return;
+
+  child.kill('SIGKILL');
+  if (child.exitCode !== null || child.signalCode !== null) return;
+
+  await new Promise<void>((resolve) => {
+    let settleTimer: NodeJS.Timeout | undefined;
+    const done = (): void => {
+      if (settleTimer) clearTimeout(settleTimer);
+      child.removeListener('exit', done);
+      resolve();
+    };
+    child.once('exit', done);
+    settleTimer = setTimeout(done, 1_000);
+  });
+}
+
 const permissionPromptQueue = new AsyncQueue();
 
 async function showPermissionPrompt(
@@ -976,8 +1006,6 @@ function pipeSockets(client: Socket, upstream: Socket, initialData?: Buffer): vo
   upstream.pipe(client);
 }
 
-type LandstripBashTool = ReturnType<typeof createBashToolDefinition>;
-
 /** Options for creating a landstrip sandbox integration. */
 export interface LandstripIntegrationOptions {
   /** Register a sandboxed bash tool when the integration is registered. */
@@ -987,35 +1015,36 @@ export interface LandstripIntegrationOptions {
 }
 
 /** Landstrip sandbox integration hooks for Pi. */
-export interface LandstripIntegration {
-  /** Create a bash tool definition that runs commands through landstrip when enabled. */
-  createBashTool(cwd: string, ctx?: ExtensionContext): LandstripBashTool;
+export interface LandstripIntegration extends PiLandstripRuntimeV1 {
   /** Prepare a full Pi RPC process constrained by the effective sandbox policy. */
   prepareRpcWorker(options: LandstripRpcWorkerOptions): Promise<LandstripRpcWorkerLaunch>;
   /** Register the integration's tools, events, flags, and commands with Pi. */
   register(pi: ExtensionAPI, runtime?: SubagentRuntime): void;
+  /** Publish an integration lifecycle event from an embedded runtime. */
+  emit(event: LandstripEvent): void;
 }
 
-export interface LandstripRpcWorkerOptions {
-  readonly command: string;
-  readonly args: readonly string[];
-  readonly cwd: string;
+export interface LandstripRpcWorkerOptions extends LandstripProcessOptions {
   readonly env: NodeJS.ProcessEnv;
-  readonly ctx: ExtensionContext;
   readonly readPaths: readonly string[];
   readonly writePaths: readonly string[];
-  readonly signal?: AbortSignal;
 }
 
-export interface LandstripRpcWorkerLaunch {
-  readonly command: string;
-  readonly args: readonly string[];
-  readonly cwd: string;
-  readonly env: NodeJS.ProcessEnv;
+export interface LandstripRpcWorkerLaunch extends LandstripPreparedProcess {
   readonly spawn: RpcSpawn;
-  dispose(): Promise<void>;
 }
 
+export type {
+  LandstripBashTool,
+  LandstripContextV1,
+  LandstripEvent,
+  LandstripPreparedProcess,
+  LandstripProcessOptions,
+  LandstripSandboxState,
+  LandstripWorkerExtension,
+  PiLandstripRuntimeV1,
+} from './api.ts';
+
 /** Register the landstrip extension with Pi. */
 export default function (pi: ExtensionAPI) {
   const workerConfig = workerConfigFromEnvironment();
@@ -1048,12 +1077,92 @@ export function createLandstripIntegration(
 
   let sandboxEnabled = false;
   let sandboxReady = false;
+  let sandboxState: LandstripSandboxState = 'unavailable';
   let unsandboxedWorkerWarningShown = false;
+  let activeContext: ExtensionContext | undefined;
+  let unpublishRuntime: (() => void) | undefined;
+  const eventHandlers = new Set<(event: LandstripEvent) => void>();
+  const workerExtensions = new Map<string, { entry: string; registrations: number }>();
   const sessionAllowedDomains: string[] = [];
   const sessionAllowedReadPaths: string[] = [];
   const sessionAllowedWritePaths: string[] = [];
   const sessionAllowedTargets: string[] = [];
 
+  function getContext(ctx = activeContext): LandstripContextV1 {
+    return {
+      version: LANDSTRIP_RUNTIME_VERSION,
+      host: 'pi',
+      role: 'primary',
+      sandbox: sandboxState,
+      cwd: ctx?.cwd ?? localCwd,
+      sessionId: ctx?.sessionManager?.getSessionId(),
+      depth: 0,
+    };
+  }
+
+  function emitEvent(event: LandstripEvent): void {
+    for (const handler of eventHandlers) {
+      try {
+        handler(event);
+      } catch (error) {
+        console.error(`pi-landstrip: lifecycle listener failed: ${formatError(error)}`);
+      }
+    }
+  }
+
+  function setSandboxState(state: LandstripSandboxState, ctx: ExtensionContext): void {
+    if (sandboxState === state) return;
+    sandboxState = state;
+    emitEvent({ type: 'sandbox.changed', context: getContext(ctx) });
+  }
+
+  function on<T extends LandstripEvent['type']>(
+    type: T,
+    handler: (event: Extract<LandstripEvent, { type: T }>) => void,
+  ): () => void {
+    const listener = (event: LandstripEvent): void => {
+      if (event.type === type) handler(event as Extract<LandstripEvent, { type: T }>);
+    };
+    eventHandlers.add(listener);
+    return () => eventHandlers.delete(listener);
+  }
+
+  function registerWorkerExtension(extension: LandstripWorkerExtension): () => void {
+    const id = extension.id.trim();
+    if (!id) throw new Error('Worker extension id must not be empty');
+    const requestedEntry = extension.entry.startsWith('file:')
+      ? fileURLToPath(extension.entry)
+      : extension.entry;
+    if (!isAbsolute(requestedEntry)) {
+      throw new Error('Worker extension entry must be an absolute path or file URL');
+    }
+    if (!existsSync(requestedEntry)) {
+      throw new Error(`Worker extension entry does not exist: ${requestedEntry}`);
+    }
+    const entry = realpathSync(requestedEntry);
+
+    const existing = workerExtensions.get(id);
+    if (existing && existing.entry !== entry) {
+      throw new Error(`Worker extension id is already registered with another entry: ${id}`);
+    }
+    if (existing) existing.registrations += 1;
+    else workerExtensions.set(id, { entry, registrations: 1 });
+
+    let disposed = false;
+    return () => {
+      if (disposed) return;
+      disposed = true;
+      const registration = workerExtensions.get(id);
+      if (!registration || registration.entry !== entry) return;
+      registration.registrations -= 1;
+      if (registration.registrations === 0) workerExtensions.delete(id);
+    };
+  }
+
+  function getWorkerExtensions(): readonly LandstripWorkerExtension[] {
+    return [...workerExtensions].map(([id, extension]) => ({ id, entry: extension.entry }));
+  }
+
   function resetSessionAllowances(): void {
     sessionAllowedDomains.length = 0;
     sessionAllowedReadPaths.length = 0;
@@ -1546,8 +1655,12 @@ export function createLandstripIntegration(
     options: LandstripRpcWorkerOptions,
   ): LandstripRpcWorkerLaunch {
     let spawned = false;
+    let disposed = false;
+    let disposePromise: Promise<void> | undefined;
+    let preparedChild: ChildProcess | undefined;
     const spawnWorker: RpcSpawn = (command, args, spawnOptions) => {
-      if (spawned) throw new Error('RPC worker launch can only be spawned once');
+      if (disposed) throw new Error('Prepared process has been disposed');
+      if (spawned) throw new Error('Prepared process can only be spawned once');
       spawned = true;
       const child = spawn(command, [...args], {
         ...spawnOptions,
@@ -1556,6 +1669,7 @@ export function createLandstripIntegration(
         detached: true,
       });
       patchProcessGroupKill(child);
+      preparedChild = child;
       return child as ReturnType<RpcSpawn>;
     };
 
@@ -1565,7 +1679,13 @@ export function createLandstripIntegration(
       cwd: options.cwd,
       env: options.env,
       spawn: spawnWorker,
-      async dispose() {},
+      dispose() {
+        disposePromise ??= (async () => {
+          disposed = true;
+          await stopPreparedChild(preparedChild);
+        })();
+        return disposePromise;
+      },
     };
   }
 
@@ -1630,8 +1750,11 @@ export function createLandstripIntegration(
       workerEnv.no_proxy = '';
     }
     let spawned = false;
+    let disposePromise: Promise<void> | undefined;
+    let preparedChild: ChildProcess | undefined;
     const spawnWorker: RpcSpawn = (_command, _args, spawnOptions) => {
-      if (spawned) throw new Error('RPC worker launch can only be spawned once');
+      if (disposed) throw new Error('Prepared process has been disposed');
+      if (spawned) throw new Error('Prepared process can only be spawned once');
       spawned = true;
       const child = spawn(
         binaryPath(),
@@ -1646,6 +1769,7 @@ export function createLandstripIntegration(
       );
       workerChildEnd.destroy();
       patchProcessGroupKill(child);
+      preparedChild = child;
       return child as ReturnType<RpcSpawn>;
     };
 
@@ -1655,17 +1779,34 @@ export function createLandstripIntegration(
       cwd: options.cwd,
       env: workerEnv,
       spawn: spawnWorker,
-      async dispose() {
-        if (disposed) return;
-        disposed = true;
-        trapSocket.destroy();
-        workerChildEnd.destroy();
-        rmSync(workerPolicy.dir, { recursive: true, force: true });
-        await proxy?.stop();
+      dispose() {
+        disposePromise ??= (async () => {
+          disposed = true;
+          await stopPreparedChild(preparedChild);
+          trapSocket.destroy();
+          workerChildEnd.destroy();
+          rmSync(workerPolicy.dir, { recursive: true, force: true });
+          await proxy?.stop();
+        })();
+        return disposePromise;
       },
     };
   }
 
+  async function prepareProcess(
+    options: LandstripProcessOptions,
+  ): Promise<LandstripPreparedProcess> {
+    if (process.platform === 'win32' && (noSandboxFlag || !loadConfig(options.cwd).enabled)) {
+      throw new Error('Generic process preparation requires sandboxing on Windows');
+    }
+    return prepareRpcWorker({
+      ...options,
+      env: options.env ?? process.env,
+      readPaths: options.readPaths ?? [],
+      writePaths: options.writePaths ?? [],
+    });
+  }
+
   function createLandstripBashOps(
     ctx: ExtensionContext,
     callbacks: LandstripBashCallbacks = {},
@@ -2135,6 +2276,7 @@ export function createLandstripIntegration(
     if (!SUPPORTED_PLATFORMS.has(process.platform)) {
       sandboxEnabled = false;
       sandboxReady = false;
+      setSandboxState('unavailable', ctx);
       warnUnsandboxed(
         ctx,
         `landstrip sandboxing is not supported on ${process.platform}`,
@@ -2146,6 +2288,7 @@ export function createLandstripIntegration(
     if (!landstripAvailable()) {
       sandboxEnabled = false;
       sandboxReady = false;
+      setSandboxState('unavailable', ctx);
       warnUnsandboxed(
         ctx,
         `landstrip was not found. Reinstall with: npm install @landstrip/landstrip`,
@@ -2156,6 +2299,7 @@ export function createLandstripIntegration(
 
     sandboxEnabled = true;
     sandboxReady = true;
+    setSandboxState('enabled', ctx);
     warnIfAllDomainsAllowed(ctx, config);
     enableStatus(ctx, config);
     return true;
@@ -2165,6 +2309,7 @@ export function createLandstripIntegration(
   function disableSandbox(ctx: ExtensionContext): void {
     sandboxEnabled = false;
     sandboxReady = false;
+    setSandboxState('disabled', ctx);
     setTuiStatus(ctx, 'sandbox', undefined);
   }
 
@@ -2219,6 +2364,9 @@ export function createLandstripIntegration(
       default: false,
     });
 
+    unpublishRuntime?.();
+    unpublishRuntime = publishLandstripRuntime(pi, integration);
+
     if (shouldRegisterBashTool) pi.registerTool(createBashTool(localCwd));
 
     pi.on('user_bash', async (_event, ctx) => {
@@ -2228,6 +2376,7 @@ export function createLandstripIntegration(
     });
 
     pi.on('session_start', async (_event, ctx) => {
+      activeContext = ctx;
       resetSessionAllowances();
       const trustContext = ctx as ExtensionContext & { isProjectTrusted?: () => boolean };
       projectConfigTrusted = trustContext.isProjectTrusted?.() ?? false;
@@ -2236,6 +2385,7 @@ export function createLandstripIntegration(
       if (noSandboxFlag) {
         disableSandbox(ctx);
         notify(ctx, 'Sandbox disabled via --no-sandbox', 'warning');
+        if (!unpublishRuntime) unpublishRuntime = publishLandstripRuntime(pi, integration);
         return;
       }
 
@@ -2243,10 +2393,17 @@ export function createLandstripIntegration(
       if (!config.enabled) {
         disableSandbox(ctx);
         notify(ctx, 'Sandbox disabled via config', 'info');
+        if (!unpublishRuntime) unpublishRuntime = publishLandstripRuntime(pi, integration);
         return;
       }
 
       enableSandbox(ctx);
+      if (!unpublishRuntime) unpublishRuntime = publishLandstripRuntime(pi, integration);
+    });
+    pi.on('session_shutdown', () => {
+      activeContext = undefined;
+      unpublishRuntime?.();
+      unpublishRuntime = undefined;
     });
     maybePi.registerCommand?.('sandbox', {
       description: 'Show config and toggle the sandbox',
@@ -2641,5 +2798,17 @@ export function createLandstripIntegration(
     });
   }
 
-  return { createBashTool, prepareRpcWorker, register };
+  const integration: LandstripIntegration = {
+    version: LANDSTRIP_RUNTIME_VERSION,
+    getContext,
+    createBashTool,
+    prepareProcess,
+    prepareRpcWorker,
+    registerWorkerExtension,
+    getWorkerExtensions,
+    on,
+    register,
+    emit: emitEvent,
+  };
+  return integration;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-landstrip",
-  "version": "0.17.21",
+  "version": "0.17.23",
   "description": "Sandbox-aware Pi subagents and interactive command permissions",
   "keywords": [
     "landstrip",
@@ -15,6 +15,7 @@
     "url": "git+https://github.com/landstrip/landstrip.git"
   },
   "files": [
+    "api.ts",
     "agents.ts",
     "box.ts",
     "config.ts",
@@ -27,6 +28,11 @@
     "sandbox.json"
   ],
   "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./api": "./api.ts",
+    "./*": "./*"
+  },
   "scripts": {
     "fmt": "oxfmt *.ts package.json tsconfig.json subagents.json sandbox.json .oxfmtrc.json README.md",
     "lint": "oxlint *.ts",
@@ -40,7 +46,7 @@
   },
   "dependencies": {
     "@earendil-works/pi-tui": "^0.80.6",
-    "@landstrip/landstrip": "^0.17.21",
+    "@landstrip/landstrip": "^0.17.23",
     "minimatch": "^10.2.5"
   },
   "devDependencies": {

package/subagents.ts

@@ -29,6 +29,7 @@ import {
 import { matchesKey, Text, truncateToWidth } from '@earendil-works/pi-tui';
 import { Type } from 'typebox';
 
+import { encodeLandstripContext, type LandstripContextV1, LANDSTRIP_CONTEXT_ENV } from './api.ts';
 import {
   type AgentCatalog,
   type AgentDefinition,
@@ -1296,6 +1297,7 @@ export class SubagentRuntime {
     update: (text: string) => void,
   ): Promise<string> {
     let worker: WorkerHandle | undefined;
+    let started = false;
     try {
       const release = await this.semaphore.acquire(signal);
       this.leases.set(task.id, { release });
@@ -1303,6 +1305,8 @@ export class SubagentRuntime {
       task.startedAt = Date.now();
       task.finishedAt = undefined;
       task.error = undefined;
+      started = true;
+      this.integration.emit?.({ type: 'subagent.start', context: this.taskContext(task, ctx) });
       this.persist(task);
       this.updateTaskWidget(ctx);
       const rules = mergePermissionRules(catalog.permissions, agent.permissions);
@@ -1411,6 +1415,13 @@ export class SubagentRuntime {
       if (task.error === message) throw error;
       throw new Error(task.error);
     } finally {
+      if (started && ['completed', 'cancelled', 'error'].includes(task.state)) {
+        this.integration.emit?.({
+          type: 'subagent.end',
+          context: this.taskContext(task, ctx),
+          status: task.state as 'completed' | 'cancelled' | 'error',
+        });
+      }
       this.running.delete(task.id);
       this.pendingPrompts.delete(task.id);
       await worker?.rpc.stop().catch(() => undefined);
@@ -1456,12 +1467,14 @@ export class SubagentRuntime {
     const tools = taskEnabled
       ? [...new Set([...this.pi.getActiveTools(), 'task'])]
       : this.pi.getActiveTools().filter((tool) => tool !== 'task');
+    const workerExtensions = this.integration.getWorkerExtensions?.() ?? [];
     const args = [
       ...invocation.args,
       '--mode',
       'rpc',
       '--extension',
       join(packageDir, 'index.ts'),
+      ...workerExtensions.flatMap((extension) => ['--extension', extension.entry]),
       ...(task.sessionFile
         ? ['--session', task.sessionFile]
         : task.sessionDir
@@ -1478,6 +1491,7 @@ export class SubagentRuntime {
       tools.join(','),
     ];
     const config: WorkerConfig = { rules, task, taskEnabled, steps: agent.steps };
+    const publicContext = this.taskContext(task, ctx);
     const temp = mkdtempSync(join(tmpdir(), `pi-landstrip-task-${task.id}-`));
     const agentDir = getAgentDir();
     let launch: LandstripRpcWorkerLaunch | undefined;
@@ -1497,6 +1511,7 @@ export class SubagentRuntime {
         env: {
           ...process.env,
           [WORKER_ENV]: Buffer.from(JSON.stringify(config)).toString('base64url'),
+          [LANDSTRIP_CONTEXT_ENV]: encodeLandstripContext(publicContext),
           JITI_FS_CACHE: 'false',
           TMPDIR: temp,
           TMP: temp,
@@ -1514,6 +1529,11 @@ export class SubagentRuntime {
               invocation.command,
               cliRoot,
               extensionRoot,
+              ...workerExtensions.flatMap((extension) => [
+                extension.entry,
+                dirname(extension.entry),
+                dependencyRoot(extension.entry),
+              ]),
               task.sessionDir,
               task.sessionFile,
               temp,
@@ -1562,6 +1582,27 @@ export class SubagentRuntime {
     }
   }
 
+  private taskContext(task: TaskRecord, ctx: ExtensionContext): LandstripContextV1 {
+    const context = this.integration.getContext?.(ctx) ?? {
+      version: 1,
+      host: 'pi',
+      role: 'primary',
+      sandbox: 'unavailable',
+      cwd: ctx.cwd,
+      sessionId: ctx.sessionManager.getSessionId(),
+      depth: 0,
+    };
+    return {
+      ...context,
+      role: 'subagent',
+      sessionId: undefined,
+      taskId: task.id,
+      parentTaskId: task.parentTaskId,
+      agent: task.agent,
+      depth: task.depth,
+    };
+  }
+
   private piInvocation(): { command: string; args: string[] } {
     const argvEntry = process.argv[1];
     if (argvEntry && /(?:^|[/\\])cli\.(?:js|mjs|cjs|ts)$/.test(argvEntry)) {