pi-landstrip 0.17.6 → 0.17.7

package/README.md

@@ -1,11 +1,15 @@
 # pi-landstrip
 
-`pi-landstrip` is an extension for [pi](https://pi.dev/) providing a sandbox
-defined with a policy compatible with Anthropic's JSON format. It uses
-[`landstrip`](https://github.com/landstrip/landstrip) to implement the sandbox.
+`pi-landstrip` is an extension for [pi](https://pi.dev/) providing sandbox-aware
+subagents and a sandbox defined with a policy compatible with Anthropic's JSON
+format. It uses [`landstrip`](https://github.com/landstrip/landstrip) to
+implement the sandbox.
 
-`pi-landstrip` has a default policy [sandbox.json](./sandbox.json), and allows
-the define either or both global or project specific policies.
+`pi-landstrip` has a shared sandbox policy [sandbox.json](./sandbox.json) and a
+separate [landstrip.json](./landstrip.json) for primary-agent and subagent
+configuration. Global and trusted project files can override both.
+
+Pi >=0.80.6 <0.81.0 and Node.js >=22.19.0 are required for process-backed subagents.
 
 ## Installing the extension
 
@@ -15,8 +19,8 @@ the define either or both global or project specific policies.
 pi install npm:pi-landstrip
 ```
 
-This installs `pi-landstrip` and its `@landstrip/landstrip` dependency, which
-includes platform-specific native binaries for Linux, macOS, and Windows.
+This installs `pi-landstrip` and its `@landstrip/landstrip` dependency. Native
+binaries are currently published for Linux x64, Windows x64, and macOS x64/arm64.
 
 ### Manual install
 
@@ -37,8 +41,7 @@ On unsupported platforms the extension loads but leaves sandboxing disabled.
 
 ## Disable
 
-Use the `--no-sandbox` flag, or set `enabled` to `false` in the sandbox
-config:
+Use the `--no-sandbox` flag, or set `enabled` to `false` in `sandbox.json`:
 
 ```json
 {
@@ -46,8 +49,14 @@ config:
 }
 ```
 
-Project config overrides global config. The `/sandbox` UI updates the project
-config when present, otherwise the global config.
+When sandboxing is explicitly disabled, subagents still run as separate Pi RPC
+processes, but without the outer Landstrip OS sandbox. The extension warns once
+per session. Agent tool permissions still apply, but they are not an OS isolation
+boundary.
+
+Trusted project config overrides global config. `/landstrip` updates a trusted
+project sandbox file when present, otherwise the global file. Pi versions
+without a project-trust API use only global configuration.
 
 ## Behavior
 
@@ -59,16 +68,184 @@ reject. The dialog shows the exact path or domain being approved.
 Project approvals are written to `.pi/sandbox.json`; global approvals are
 written to `~/.pi/agent/sandbox.json`.
 
-When pi runs a bash command, the extension wraps it in `landstrip`. This
-applies to both the AI `bash` tool calls and manually typed shell-mode commands
-(`!` and `!!`). Network traffic is routed through an allowlist proxy when
-network access is off, and read/write tool access is blocked outside the
-configured filesystem allowlists. The default policy is strict: network access
-is off unless domains are allowed, reads are limited to the project,
-`~/.gitconfig`, and `/dev/null`, and writes are limited to the project and
-`/dev/null`.
+The main agent remains a normal Pi process. Pi performs its usual filesystem
+tool and plugin composition; `pi-landstrip` replaces Bash execution, including
+AI `bash` calls and manually typed shell-mode commands (`!` and `!!`), with a
+Landstrip-wrapped implementation. Network traffic is routed through an
+allowlist proxy when network access is off. Main-agent filesystem tools and
+plugin callbacks remain trusted Pi code and are not confined by Landstrip. The
+default policy for Bash and subagent processes is strict: network access is off
+unless domains are allowed, reads are limited to the project, `~/.gitconfig`,
+and `/dev/null`, and writes are limited to the project and `/dev/null`.
+
+Subagent startup adds read-only bootstrap access to the selected Pi runtime,
+global settings, model/auth configuration, installed plugins, skills, and the
+task's dedicated session directory. These paths are required to construct a
+normal Pi worker and are not persisted into `sandbox.json`. The worker receives
+write access only to its own session and temporary directories.
+
+Use `/landstrip` inside Pi. Its Sandbox tab shows the active policy, its Agents
+tab selects the primary role, and its Settings tab controls sandboxing and the
+maximum number of concurrent subagents.
+
+## Primary agents
+
+The Agents tab provides OpenCode-compatible `build` and `plan` roles by default.
+Build has normal development access; plan asks before shell commands and file
+changes. The selection controls the root system prompt and permissions and is
+restored with the session.
+
+## Subagents
+
+Landstrip provides an OpenCode-compatible `task` tool. Each active task is a
+full `pi --mode rpc` process under one outer Landstrip instance. The sandbox
+covers Pi itself, its plugins and tools, model requests, and every descendant
+process. The root Pi supervises RPC, permissions, nesting, persistence, and
+completion delivery.
+
+The worker uses normal Pi resource discovery and plugin loading from the Pi
+filesystem, plus the pi-landstrip worker extension. Its requested active tool
+names come from the parent, but their implementations are composed normally in
+the worker: plugins can add or replace tools, including replacements such as
+`pi-readseek`. Every task run starts a fresh Pi process and fresh plugin
+instances. Continuing a `task_id` restores its persisted Pi session in a new
+worker process.
+
+The tool accepts the OpenCode task fields:
+
+```json
+{
+  "description": "Review sandbox boundary",
+  "prompt": "Review the sandbox implementation and report concrete issues.",
+  "subagent_type": "review",
+  "task_id": "optional-session-id",
+  "command": "optional-originating-command",
+  "background": false
+}
+```
+
+Foreground tasks return the child result directly. Background tasks return a
+running result while the worker continues, then deliver completion to the
+parent automatically. The process exits when the run settles; its Pi session
+remains on disk and can be continued with `task_id`. While tasks are active, Pi
+shows their parent-child tree automatically above the editor.
+Session switching or shutdown stops live workers. After an unclean restart,
+unfinished work is marked interrupted rather than silently rerun; a completed
+but undelivered background result is delivered when the root session resumes.
+
+OpenCode-style worker permissions are enforced around the worker's composed
+tools: `deny` blocks a call, `ask` suspends that worker and asks in the root UI,
+and `allow` lets the tool run. Other workers may continue while a prompt is
+open. An "Allow for this session" worker-permission decision applies to the
+root session and its descendants. These permissions are separate from the
+outer Landstrip policy and cannot widen it. Sandbox approvals continue to use
+`.pi/sandbox.json` and `~/.pi/agent/sandbox.json`.
+
+Subagents fail closed when sandboxing is expected but unavailable, unsupported,
+or missing. An explicit `--no-sandbox` flag or `enabled: false` configuration is
+treated as an intentional opt-out and uses the warned unsandboxed process path.
+Unsupported Pi versions still fail task startup.
+
+### Platform behavior
+
+- **Linux**: seccomp query traps can grant a blocked filesystem or network
+  operation dynamically, so an approved worker can continue without restart.
+- **macOS**: Seatbelt policy is fixed when the worker starts. Update
+  `sandbox.json`, then restart or continue the task in a fresh worker to apply
+  additional filesystem access. Main-agent Bash can retry a command, but there
+  is no live worker-policy update.
+- **Windows**: AppContainer cannot permit only the loopback proxy port, so
+  domain-proxied worker networking is unavailable and the worker has no network.
+  Setting `network.allowNetwork` to `true` is a degraded mode that permits model
+  access but gives the entire worker unrestricted network access; domain lists
+  are then not a boundary.
+
+### Credentials
+
+Model requests originate inside each worker. Pi's `auth.json` is readable but
+not writable by workers. Inherited credential environment variables also cross
+the sandbox boundary, and plugins loaded in that worker share access to these
+credentials. Landstrip does not provide a credential broker: load only trusted
+plugins and use credentials appropriate for the sandboxed process. An OAuth
+refresh that needs to rewrite `auth.json` must be completed in the root Pi
+first.
+
+## Configuration
+
+Subagent configuration is read from `~/.pi/agent/landstrip.json` and, for
+trusted projects, `.pi/landstrip.json`. Project values override global values;
+both are merged over the packaged [default](./landstrip.json). Sandbox policy
+continues to use `~/.pi/agent/sandbox.json` and `.pi/sandbox.json`. Pi's
+`settings.json` contains only normal Pi settings such as the `pi-landstrip`
+package entry. `landstrip.json` accepts only top-level `maxSubagents` and
+`subagents`; sandbox fields belong only in `sandbox.json`.
+
+```json
+{
+  "maxSubagents": 2,
+  "subagents": {
+    "agent": {
+      "review": {
+        "description": "Review code without modifying it",
+        "mode": "subagent",
+        "prompt": "Review the requested code and report concrete findings.",
+        "permission": {
+          "edit": "deny",
+          "bash": "ask"
+        }
+      }
+    },
+    "permission": {
+      "task": {
+        "*": "deny",
+        "review": "allow"
+      }
+    }
+  }
+}
+```
+
+`maxSubagents` is an integer from 0 through 16 controlling concurrent worker
+processes. Setting it to zero removes the `task` tool while retaining the Agents
+tab and primary roles. There is no separate subagent enable switch. The Settings
+tab in `/landstrip` edits this limit and the persisted sandbox enable checkbox;
+the Sandbox tab only reports effective policy and status.
+
+Agent modes, hidden/disabled agents, prompts, and ordered `allow`/`ask`/`deny`
+permissions apply to primary agents and subagents. Subagent workers also honor
+model selection, supported Pi thinking-level variants, and step limits. Primary
+agent activation currently changes the prompt and permissions only. Later
+matching permission rules win. Put provider-specific values under `options`;
+unknown agent fields are rejected. Agent permissions cannot weaken an enabled
+OS sandbox, grant filesystem access, or grant network access.
+
+## Migrating configuration
+
+There is no compatibility loader for previous subagent configuration sources.
+Legacy keys in `settings.json` produce a migration warning. Move configuration as
+follows, then remove the old fields:
+
+- Move `agent` and `permission` from Pi `settings.json` or OpenCode JSON under
+  `subagents.agent` and `subagents.permission`.
+- Convert legacy `tools` booleans to explicit `permission` rules.
+- Move Markdown agent prompts into each `subagents.agent.<name>.prompt` string.
+- Put the worker limit in top-level `maxSubagents`; zero disables delegation.
+- Use `~/.pi/agent/landstrip.json` for global configuration and
+  `.pi/landstrip.json` for trusted project configuration.
+- Leave sandbox policy in `~/.pi/agent/sandbox.json` and `.pi/sandbox.json`;
+  those files are unchanged.
+
+Do not put `subagents`, `agent`, `permission`, or `maxSubagents` in Pi's
+`settings.json`; Pi-Landstrip does not read them there.
+
+## Limits
 
-Use `/sandbox` inside pi to show the active config and toggle sandboxing.
+Pi-Landstrip runs at most `maxSubagents` worker processes concurrently and
+allows nesting to three levels. A foreground parent hands its scheduler permit to a child
+while waiting, preventing nested-task deadlocks. A worker receives a nested
+`task` tool only when its agent has an explicit `task` permission. Nested tasks
+are separate Pi processes supervised by the root and Landstrip-wrapped unless
+sandboxing is explicitly disabled. Persisted sessions remain resumable by `task_id`.
 
 ## License
 

package/agents.ts

@@ -0,0 +1,258 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) Jarkko Sakkinen 2026
+
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { minimatch } from 'minimatch';
+import { getAgentDir } from '@earendil-works/pi-coding-agent';
+
+import { loadLandstripConfig, type ConfigObject } from './config.ts';
+
+export type PermissionAction = 'allow' | 'ask' | 'deny';
+
+export interface PermissionRule {
+  readonly permission: string;
+  readonly pattern: string;
+  readonly action: PermissionAction;
+}
+
+export type PermissionRules = readonly PermissionRule[];
+
+export interface AgentDefinition {
+  readonly name: string;
+  readonly description?: string;
+  readonly prompt: string;
+  readonly mode: 'primary' | 'subagent' | 'all';
+  readonly model?: string;
+  readonly variant?: string;
+  readonly hidden: boolean;
+  readonly steps?: number;
+  readonly permissions: PermissionRules;
+  readonly providerOptions: Readonly<Record<string, unknown>>;
+}
+
+export interface AgentCatalog {
+  readonly agents: ReadonlyMap<string, AgentDefinition>;
+  readonly permissions: PermissionRules;
+  readonly diagnostics: readonly string[];
+  readonly warnings: readonly string[];
+  readonly maxSubagents: number;
+}
+
+const AGENT_FIELDS = new Set([
+  'name',
+  'description',
+  'prompt',
+  'mode',
+  'model',
+  'variant',
+  'hidden',
+  'disable',
+  'steps',
+  'permission',
+  'temperature',
+  'top_p',
+  'options',
+  'color',
+]);
+
+function isObject(value: unknown): value is ConfigObject {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function normalizeAbsolutePath(value: string): string {
+  return /^(?:[A-Za-z]:[\\/]|\\\\)/.test(value) ? value.replaceAll('\\', '/') : value;
+}
+
+function expandPattern(pattern: string): string {
+  if (pattern === '~' || pattern === '$HOME') return normalizeAbsolutePath(homedir());
+  if (pattern.startsWith('~/')) {
+    return normalizeAbsolutePath(join(homedir(), pattern.slice(2)));
+  }
+  if (pattern.startsWith('$HOME/')) {
+    return normalizeAbsolutePath(join(homedir(), pattern.slice(6)));
+  }
+  return normalizeAbsolutePath(pattern);
+}
+
+function permissionEntries(permission: string, value: unknown): PermissionRule[] {
+  if (value === 'allow' || value === 'ask' || value === 'deny') {
+    return [{ permission, pattern: '*', action: value }];
+  }
+  if (!isObject(value)) {
+    throw new Error(`permission ${permission} must be allow, ask, deny, or a map`);
+  }
+  return Object.entries(value).map(([pattern, action]) => {
+    if (action !== 'allow' && action !== 'ask' && action !== 'deny') {
+      throw new Error(`permission ${permission} pattern ${pattern} has an invalid action`);
+    }
+    return { permission, pattern: expandPattern(pattern), action };
+  });
+}
+
+function normalizePermissions(value: unknown): PermissionRules {
+  if (value === 'allow' || value === 'ask' || value === 'deny') {
+    return [{ permission: '*', pattern: '*', action: value }];
+  }
+  if (value === undefined) return [];
+  if (!isObject(value)) throw new Error('permission must be allow, ask, deny, or a map');
+  return Object.entries(value).flatMap(([permission, rules]) =>
+    permissionEntries(permission, rules),
+  );
+}
+
+function legacyConfigWarnings(piAgentDir: string): string[] {
+  const path = join(piAgentDir, 'settings.json');
+  if (!existsSync(path)) return [];
+  try {
+    const value: unknown = JSON.parse(readFileSync(path, 'utf8'));
+    if (!isObject(value)) return [];
+    const fields = ['agent', 'permission', 'subagents', 'maxSubagents'].filter(
+      (field) => value[field] !== undefined,
+    );
+    if (fields.length === 0) return [];
+    return [
+      `${path}: legacy ${fields.join(', ')} configuration is ignored; move it to landstrip.json`,
+    ];
+  } catch {
+    return [];
+  }
+}
+
+function normalizeAgent(name: string, raw: ConfigObject): AgentDefinition | undefined {
+  for (const field of ['description', 'prompt', 'model', 'variant'] as const) {
+    if (raw[field] !== undefined && typeof raw[field] !== 'string') {
+      throw new Error(`agent ${name} ${field} must be a string`);
+    }
+  }
+  for (const field of ['hidden', 'disable'] as const) {
+    if (raw[field] !== undefined && typeof raw[field] !== 'boolean') {
+      throw new Error(`agent ${name} ${field} must be a boolean`);
+    }
+  }
+  for (const key of Object.keys(raw)) {
+    if (!AGENT_FIELDS.has(key)) throw new Error(`agent ${name} has an unknown field ${key}`);
+  }
+  if (raw.options !== undefined && !isObject(raw.options)) {
+    throw new Error(`agent ${name} options must be an object`);
+  }
+  for (const field of ['temperature', 'top_p'] as const) {
+    if (raw[field] !== undefined && typeof raw[field] !== 'number') {
+      throw new Error(`agent ${name} ${field} must be a number`);
+    }
+  }
+  if (raw.disable === true) return undefined;
+  if (
+    raw.mode !== undefined &&
+    raw.mode !== 'primary' &&
+    raw.mode !== 'subagent' &&
+    raw.mode !== 'all'
+  ) {
+    throw new Error(`agent ${name} has an invalid mode`);
+  }
+  const providerOptions: Record<string, unknown> = isObject(raw.options) ? { ...raw.options } : {};
+  if (typeof raw.temperature === 'number') providerOptions.temperature = raw.temperature;
+  if (typeof raw.top_p === 'number') providerOptions.top_p = raw.top_p;
+  if (raw.steps !== undefined && (!Number.isInteger(raw.steps) || (raw.steps as number) <= 0)) {
+    throw new Error(`agent ${name} steps must be a positive number`);
+  }
+  return {
+    name,
+    description: typeof raw.description === 'string' ? raw.description : undefined,
+    prompt: typeof raw.prompt === 'string' ? raw.prompt : '',
+    mode: raw.mode ?? 'all',
+    model: typeof raw.model === 'string' ? raw.model : undefined,
+    variant: typeof raw.variant === 'string' ? raw.variant : undefined,
+    hidden: raw.hidden === true,
+    steps: typeof raw.steps === 'number' ? raw.steps : undefined,
+    permissions: normalizePermissions(raw.permission),
+    providerOptions,
+  };
+}
+
+export function loadAgentCatalog(
+  cwd: string,
+  piAgentDir = getAgentDir(),
+  includeProject = true,
+): AgentCatalog {
+  const warnings = [
+    ...legacyConfigWarnings(piAgentDir),
+    ...(includeProject ? legacyConfigWarnings(join(cwd, '.pi')) : []),
+  ];
+  const diagnostics: string[] = [];
+  let maxSubagents = 0;
+  let subagents: ConfigObject = {};
+  try {
+    const config = loadLandstripConfig(cwd, includeProject, piAgentDir);
+    maxSubagents = config.maxSubagents;
+    subagents = config.subagents;
+  } catch (error) {
+    diagnostics.push(error instanceof Error ? error.message : String(error));
+  }
+
+  const normalized = new Map<string, AgentDefinition>();
+  if (subagents.agent !== undefined && !isObject(subagents.agent)) {
+    diagnostics.push('subagents.agent must be an object');
+  } else if (isObject(subagents.agent)) {
+    for (const name of Object.keys(subagents.agent).sort()) {
+      const value = subagents.agent[name];
+      if (!isObject(value)) {
+        diagnostics.push(`agent ${name} must be an object`);
+        continue;
+      }
+      try {
+        const agent = normalizeAgent(name, value);
+        if (agent) normalized.set(name, agent);
+      } catch (error) {
+        diagnostics.push(error instanceof Error ? error.message : String(error));
+      }
+    }
+  }
+
+  let permissions: PermissionRules = [];
+  for (const key of Object.keys(subagents)) {
+    if (key !== 'agent' && key !== 'permission') {
+      diagnostics.push(`subagents has an unknown field ${key}`);
+    }
+  }
+  try {
+    permissions = normalizePermissions(subagents.permission);
+  } catch (error) {
+    diagnostics.push(error instanceof Error ? error.message : String(error));
+  }
+  return { agents: normalized, permissions, diagnostics, warnings, maxSubagents };
+}
+
+export function permissionDecision(
+  rules: PermissionRules,
+  permission: string,
+  resource = '*',
+): PermissionAction {
+  let decision: PermissionAction = 'ask';
+  for (const rule of rules) {
+    const matchesPermission =
+      rule.permission === '*' || minimatch(permission, rule.permission, { dot: true });
+    const matchesResource =
+      rule.pattern === '*' ||
+      minimatch(normalizeAbsolutePath(resource), normalizeAbsolutePath(rule.pattern), {
+        dot: true,
+        matchBase: false,
+      });
+    if (matchesPermission && matchesResource) decision = rule.action;
+  }
+  return decision;
+}
+
+export function mergePermissionRules(...values: PermissionRules[]): PermissionRules {
+  return values.flatMap((value) => value);
+}
+
+export function availableSubagents(catalog: AgentCatalog): AgentDefinition[] {
+  return [...catalog.agents.values()].filter((agent) => agent.mode !== 'primary');
+}
+
+export function availablePrimaryAgents(catalog: AgentCatalog): AgentDefinition[] {
+  return [...catalog.agents.values()].filter((agent) => agent.mode !== 'subagent' && !agent.hidden);
+}

package/config.ts

@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) Jarkko Sakkinen 2026
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { getAgentDir, withFileMutationQueue } from '@earendil-works/pi-coding-agent';
+
+export type ConfigObject = Record<string, unknown>;
+
+export const MAX_SUBAGENTS = 16;
+
+export interface LandstripConfigFile {
+  maxSubagents?: number;
+  subagents?: ConfigObject;
+}
+
+export interface LandstripConfig extends LandstripConfigFile {
+  maxSubagents: number;
+  subagents: ConfigObject;
+}
+
+const packageDir = dirname(fileURLToPath(import.meta.url));
+
+function isObject(value: unknown): value is ConfigObject {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function readConfig(path: string): LandstripConfigFile {
+  if (!existsSync(path)) return {};
+  let value: unknown;
+  try {
+    value = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`${path}: ${message}`);
+  }
+  if (!isObject(value)) throw new Error(`${path} must contain a JSON object`);
+  for (const key of Object.keys(value)) {
+    if (key !== 'maxSubagents' && key !== 'subagents') {
+      throw new Error(`${path}: unknown top-level field ${key}`);
+    }
+  }
+  return value;
+}
+
+function mergeValue(base: unknown, override: unknown): unknown {
+  if (override === undefined) return base;
+  if (Array.isArray(override)) return [...override];
+  if (isObject(base) && isObject(override)) {
+    const result: ConfigObject = { ...base };
+    for (const [key, value] of Object.entries(override)) {
+      const merged = mergeValue(result[key], value);
+      delete result[key];
+      result[key] = merged;
+    }
+    return result;
+  }
+  return override;
+}
+
+function getLandstripConfigPaths(
+  cwd: string,
+  agentDir = getAgentDir(),
+): { globalPath: string; projectPath: string } {
+  return {
+    globalPath: join(agentDir, 'landstrip.json'),
+    projectPath: join(cwd, '.pi', 'landstrip.json'),
+  };
+}
+
+export async function setMaxSubagentsConfig(
+  cwd: string,
+  maxSubagents: number,
+  includeProject = true,
+  agentDir = getAgentDir(),
+): Promise<'global' | 'project'> {
+  if (!Number.isInteger(maxSubagents) || maxSubagents < 0 || maxSubagents > MAX_SUBAGENTS) {
+    throw new Error(`maxSubagents must be an integer from 0 to ${MAX_SUBAGENTS}`);
+  }
+  const { globalPath, projectPath } = getLandstripConfigPaths(cwd, agentDir);
+  const target =
+    includeProject && existsSync(projectPath)
+      ? { scope: 'project' as const, path: projectPath }
+      : { scope: 'global' as const, path: globalPath };
+  await withFileMutationQueue(target.path, async () => {
+    const config = readConfig(target.path);
+    config.maxSubagents = maxSubagents;
+    mkdirSync(dirname(target.path), { recursive: true });
+    writeFileSync(target.path, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+  });
+  return target.scope;
+}
+
+export function loadLandstripConfig(
+  cwd: string,
+  includeProject = true,
+  agentDir = getAgentDir(),
+): LandstripConfig {
+  const { globalPath, projectPath } = getLandstripConfigPaths(cwd, agentDir);
+  let config = readConfig(join(packageDir, 'landstrip.json'));
+  config = mergeValue(config, readConfig(globalPath)) as LandstripConfigFile;
+  if (includeProject) {
+    config = mergeValue(config, readConfig(projectPath)) as LandstripConfigFile;
+  }
+  if (
+    !Number.isInteger(config.maxSubagents) ||
+    (config.maxSubagents ?? -1) < 0 ||
+    (config.maxSubagents ?? MAX_SUBAGENTS + 1) > MAX_SUBAGENTS
+  ) {
+    throw new Error(`maxSubagents must be an integer from 0 to ${MAX_SUBAGENTS}`);
+  }
+  if (!isObject(config.subagents)) throw new Error('subagents must be an object');
+  return config as LandstripConfig;
+}