@nredd/pi-subagents 0.22.0-nredd.7 → 0.22.0-nredd.9

package/src/package-resources.ts

@@ -55,7 +55,8 @@
 
 import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { DefaultPackageManager, getAgentDir, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { DefaultPackageManager, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { normalizeHomePath, resolveAgentDir } from "./home-paths.js";
 
 /** Resource kinds a package may declare. Agents are `.md`, workflows are `.js`. */
 export type PackageResourceKind = "agents" | "workflows";
@@ -103,6 +104,8 @@ export interface PiPackage {
 export type PackageGate = boolean | string[] | undefined;
 
 export interface PackageDiscoveryOptions {
+  /** Home directory for user settings and installed resources, resolved at call time. */
+  homeDir?: string;
   /**
    * Pi's project-trust state for `cwd`, from `ctx.isProjectTrusted()`. When
    * false, `.pi/settings.json` is not read — so a package configured only by an
@@ -376,14 +379,26 @@ interface ConfiguredPackageRow {
  * so a later pi that drops or renames this API contributes no packages instead
  * of failing activation.
  */
-function configuredPackages(cwd: string, projectTrusted: boolean): ConfiguredPackageRow[] {
+function configuredPackages(cwd: string, projectTrusted: boolean, homeDir?: string): ConfiguredPackageRow[] {
   try {
     if (typeof DefaultPackageManager !== "function") return [];
-    const agentDir = getAgentDir();
+    const agentDir = resolveAgentDir(homeDir);
     const settingsManager = SettingsManager.create(cwd, agentDir, { projectTrusted });
     const manager = new DefaultPackageManager({ cwd, agentDir, settingsManager });
     if (typeof manager.listConfiguredPackages !== "function") return [];
-    return manager.listConfiguredPackages();
+    if (homeDir === undefined) return manager.listConfiguredPackages();
+    // Pi's enumerator expands local package sources through its own ambient
+    // home. Reuse its public installed-path resolver with normalized inputs,
+    // preserving the original source for package-gate matching and diagnostics.
+    const rows: ConfiguredPackageRow[] = [];
+    for (const scope of ["user", "project"] as const) {
+      const settings = scope === "user" ? settingsManager.getGlobalSettings() : settingsManager.getProjectSettings();
+      for (const pkg of settings.packages ?? []) {
+        const source = typeof pkg === "string" ? pkg : pkg.source;
+        rows.push({ source, scope, installedPath: manager.getInstalledPath(normalizeHomePath(source, homeDir), scope) });
+      }
+    }
+    return rows;
   } catch {
     return [];
   }
@@ -394,10 +409,10 @@ function configuredPackages(cwd: string, projectTrusted: boolean): ConfiguredPac
  * order (global entries first, then project). Duplicates by root are collapsed —
  * a package listed in both scopes is one package on disk.
  */
-export function listPiPackages(cwd: string, projectTrusted = false): PiPackage[] {
+export function listPiPackages(cwd: string, projectTrusted = false, homeDir?: string): PiPackage[] {
   const seen = new Set<string>();
   const out: PiPackage[] = [];
-  for (const entry of configuredPackages(cwd, projectTrusted)) {
+  for (const entry of configuredPackages(cwd, projectTrusted, homeDir)) {
     const root = entry.installedPath;
     if (!root || seen.has(root)) continue;
     const manifest = readPackageJson(root);
@@ -484,9 +499,9 @@ export function invalidatePackageCache(): void {
   cache.clear();
 }
 
-function scan(cwd: string, projectTrusted: boolean, gate: PackageGate): CacheEntry {
+function scan(cwd: string, projectTrusted: boolean, gate: PackageGate, homeDir?: string): CacheEntry {
   const entry = emptyEntry();
-  for (const pkg of listPiPackages(cwd, projectTrusted)) {
+  for (const pkg of listPiPackages(cwd, projectTrusted, homeDir)) {
     if (!packageAllowed(pkg, gate)) continue;
     // The root is normalized here, not at lookup time: the declared paths below
     // go through `resolve(root, entry)`, so a root that arrived with a trailing
@@ -520,10 +535,10 @@ function cacheEntryFor(cwd: string, kind: PackageResourceKind, opts: PackageDisc
   // `\u0000` written as an escape, not a raw byte: a literal NUL makes this
   // whole file read as binary to grep, ripgrep and git, which silently drops
   // it from search results.
-  const key = `${cwd}\u0000${projectTrusted ? 1 : 0}\u0000${JSON.stringify(gate ?? true)}`;
+  const key = `${cwd}\u0000${opts.homeDir ?? ""}\u0000${resolveAgentDir(opts.homeDir)}\u0000${projectTrusted ? 1 : 0}\u0000${JSON.stringify(gate ?? true)}`;
   let hit = cache.get(key);
   if (!hit) {
-    hit = scan(cwd, projectTrusted, gate);
+    hit = scan(cwd, projectTrusted, gate, opts.homeDir);
     cache.set(key, hit);
   }
   return hit;

package/src/plan-mode-children.ts

@@ -0,0 +1,176 @@
+/**
+ * plan-mode-children.ts -- keeps a child started while the parent plans in Plan
+ * mode (#437), as Claude Code keeps a subagent spawned in plan mode in plan mode.
+ *
+ * pi-plan-mode gates only its own session's tool calls, and a child is a separate
+ * session on a separate event bus. So right before a child runs, the manager asks
+ * the parent's pi-plan-mode, synchronously on the parent's `pi.events`, whether it
+ * is planning; when it is, the answer carries the Plan tool policy, and this
+ * module applies it to every call the child makes. No answer means pi-plan-mode is
+ * not installed, and nothing changes.
+ *
+ * The contract mirrors `packages/plan-mode/src/child-policy.ts`, repeated rather
+ * than imported because either package installs without the other.
+ */
+import type { ToolInfo } from "@earendil-works/pi-coding-agent";
+import type { AgentRecord } from "./types.js";
+
+export const PLAN_MODE_STATE_QUERY = "pi-plan-mode:state-query";
+/** pi-plan-mode asks here whether a compatible gate is installed; answering is the handshake. */
+export const PLAN_MODE_GATE_QUERY = "pi-plan-mode:gate-query";
+const PLAN_MODE_STATE_VERSION = 1;
+
+/** Buses on which pi-plan-mode has shown itself by asking {@link PLAN_MODE_GATE_QUERY}. */
+const planModeSeen = new WeakSet<object>();
+
+/**
+ * Answer pi-plan-mode's gate query, so Plan admits `Agent` and friends, and remember that Plan
+ * mode is installed on this bus: from then on a state query nobody answers fails closed.
+ */
+export function answerPlanGateQueries(events: { on(channel: string, handler: (data: unknown) => void): unknown }): void {
+  events.on(PLAN_MODE_GATE_QUERY, (data) => {
+    planModeSeen.add(events);
+    const reply = (data as { reply?: unknown } | undefined)?.reply;
+    if (typeof reply === "function") reply({ version: PLAN_MODE_STATE_VERSION, gate: "@nredd/pi-subagents" });
+  });
+}
+
+/** Thrown when pi-plan-mode is installed but did not answer whether it is planning. */
+export const PLAN_MODE_SILENT_ERROR =
+  "Plan mode is installed but did not answer whether it is planning, so this subagent was not started. Reload Pi, or update @nredd/pi-plan-mode and @nredd/pi-subagents together.";
+
+/** One tool call inside a child session. */
+interface PlanModeChildToolCall {
+  toolName: string;
+  input: unknown;
+  cwd: string;
+  tool: ToolInfo | undefined;
+}
+
+/** Why Plan mode refuses a child's tool call, or `undefined` when it may run. */
+export type PlanToolPolicy = (call: PlanModeChildToolCall) => string | undefined;
+
+/**
+ * The Plan restriction one child run is under. Mutable on purpose: it is decided
+ * per run (a spawn, then each resume) while the hooks reading it are installed
+ * once, on the child's session.
+ */
+export interface PlanGate {
+  policy?: PlanToolPolicy;
+}
+
+/** Tools a child keeps without asking: safe built-ins only. */
+const FAIL_CLOSED_TOOLS: ReadonlySet<string> = new Set(["read", "grep", "find", "ls"]);
+
+/**
+ * For a planner that says it is active but sent no policy this host understands:
+ * nothing beyond the safe built-ins, so a contract mismatch can never run a child
+ * unrestricted.
+ */
+const failClosedPolicy: PlanToolPolicy = ({ toolName }) =>
+  FAIL_CLOSED_TOOLS.has(toolName)
+    ? undefined
+    : `Plan mode is active and sent no tool policy this subagent understands, so '${toolName}' is blocked.`;
+
+/**
+ * Ask the parent's pi-plan-mode whether a child started now must plan. Returns
+ * the policy to run it under, or `undefined` when nobody is planning. Several
+ * answers (two Plan extensions) combine fail-closed: any active one restricts.
+ * A malformed answer (not version 1 with a boolean `active`) restricts like an unusable one.
+ * When Plan mode is installed but nothing answers, a new child is refused
+ * (`silent: "refuse"`, which throws) and a resumed one runs fail-closed.
+ */
+export function queryPlanPolicy(
+  events: { emit(channel: string, data: unknown): void } | undefined,
+  silent: "refuse" | "restrict" = "refuse",
+): PlanToolPolicy | undefined {
+  // Hosts without an event bus (bare programmatic callers) cannot run pi-plan-mode either.
+  if (!events) return undefined;
+  const policies: PlanToolPolicy[] = [];
+  let answered = false;
+  events.emit(PLAN_MODE_STATE_QUERY, {
+    version: PLAN_MODE_STATE_VERSION,
+    reply: (state: unknown) => {
+      const answer = state as { version?: unknown; active?: unknown; evaluate?: unknown } | undefined;
+      // Only a well-formed answer says whether Plan is on; anything else restricts, never frees.
+      if (answer?.version !== PLAN_MODE_STATE_VERSION || typeof answer.active !== "boolean") {
+        policies.push(failClosedPolicy);
+        return;
+      }
+      answered = true;
+      if (!answer.active) return;
+      policies.push(typeof answer.evaluate === "function" ? (answer.evaluate as PlanToolPolicy) : failClosedPolicy);
+    },
+  });
+  if (!answered && policies.length === 0 && planModeSeen.has(events)) {
+    if (silent === "refuse") throw new Error(PLAN_MODE_SILENT_ERROR);
+    return failClosedPolicy;
+  }
+  if (policies.length === 0) return undefined;
+  return (call) => {
+    for (const policy of policies) {
+      const reason = policy(call);
+      if (reason !== undefined) return reason;
+    }
+    return undefined;
+  };
+}
+
+/**
+ * Whether a Plan policy is active on `events` now, failing closed: an installed Plan mode that
+ * answers badly or not at all counts as planning. For work that would otherwise outlive Plan
+ * unrestricted (a schedule, a quota-parked dispatch, steering an unrestricted child).
+ */
+export function planningNow(events: { emit(channel: string, data: unknown): void } | undefined): boolean {
+  return queryPlanPolicy(events, "restrict") !== undefined;
+}
+
+/**
+ * Whether a steer must be refused: the agent is running or queued under no Plan policy (it started
+ * before Plan) while Plan is active, so the steer would drive it with its full surface. The one
+ * predicate for `steer_subagent` and `subagents:rpc:steer`.
+ */
+export function planSteerBlocked(
+  record: Pick<AgentRecord, "status" | "planGate">,
+  events: { emit(channel: string, data: unknown): void } | undefined,
+): boolean {
+  return (record.status === "running" || record.status === "queued") && !record.planGate?.policy && planningNow(events);
+}
+
+/** Plan's model must not steer a child that runs without Plan's restrictions. */
+export function planSteerRefusal(id: string): string {
+  return (
+    `Cannot steer agent "${id}" while Plan mode is active: it started before Plan and runs without Plan's restrictions, so a steer could make it edit. ` +
+    "Wait for it to finish and steer it then (that resumes it read-only), stop it with stop_subagent, or leave Plan mode (/plan exit) first."
+  );
+}
+
+/** A scheduled agent fires as a fresh spawn, after Plan, with nothing restricting it. */
+export const PLAN_SCHEDULE_REFUSAL =
+  "Cannot schedule an agent while Plan mode is active: it would start later, after Plan, without Plan's restrictions. Start it now, or leave Plan mode first.";
+
+/** A quota-parked dispatch is a scheduled job too. */
+export const PLAN_PARK_REFUSAL =
+  "The agent was not started or parked: Plan mode is active, and a parked agent would start after Plan without Plan's restrictions. Retry after the reset, or leave Plan mode first.";
+
+/**
+ * The refusal for one child tool call, or `undefined`. Tools this extension
+ * injects (nested delegation, whose children inherit the gate; StructuredOutput;
+ * the workflow refusal) are exempt: Plan's policy has no entry for them.
+ */
+export function planGateReason(
+  gate: PlanGate | undefined,
+  call: { toolName: string; input: unknown; cwd: string },
+  tools: () => ToolInfo[],
+  exempt: ReadonlySet<string>,
+): string | undefined {
+  const policy = gate?.policy;
+  if (!policy || exempt.has(call.toolName)) return undefined;
+  return policy({ ...call, tool: tools().find((tool) => tool.name === call.toolName) });
+}
+
+/** Told to a child started while planning, so a refused write is not a surprise. */
+export const PLAN_MODE_CHILD_PROMPT = `<plan_mode>
+Your parent is in Plan mode, so you are too: investigate and report, do not change anything.
+edit and write are blocked, bash runs only reviewed read-only commands, and other tools run only when Plan mode admits them.
+</plan_mode>`;

package/src/process-budget.ts

@@ -247,10 +247,13 @@ function admits(s: BudgetState, depth: number): boolean {
   if (level > top) return false;
   // Leases deeper than `top` cannot exist while it is on; clamp so they still count in the total.
   const atDepth = new Array<number>(top + 1).fill(0);
-  for (const lease of s.active) atDepth[Math.min(top, Math.max(1, lease.depth))]++;
+  for (const lease of s.active) {
+    const index = Math.min(top, Math.max(1, lease.depth));
+    atDepth[index] = atDepth[index]! + 1;
+  }
   let atOrAbove = 0;
   for (let j = 1; j <= top; j++) {
-    atOrAbove += atDepth[j];
+    atOrAbove += atDepth[j]!;
     if (j >= level && atOrAbove >= admissionLimit(policy, j)) return false;
   }
   return true;
@@ -322,7 +325,7 @@ export function pumpBudget(): void {
       for (;;) {
         const i = s.waiters.findIndex(w => admits(s, w.depth) && w.ready());
         if (i === -1) break;
-        const [waiter] = s.waiters.splice(i, 1);
+        const waiter = s.waiters.splice(i, 1)[0]!;
         const lease = newLease(s, waiter.depth);
         try {
           waiter.grant(lease);

package/src/prompts.ts

@@ -2,6 +2,7 @@
  * prompts.ts — System prompt builder for agents.
  */
 
+import { PLAN_MODE_CHILD_PROMPT } from "./plan-mode-children.js";
 import type { AgentConfig, EnvInfo } from "./types.js";
 
 /** Extra sections to inject into the system prompt (memory, skills, etc.). */
@@ -16,6 +17,8 @@ export interface PromptExtras {
    * to stay in the copy.
    */
   worktreeBase?: string;
+  /** Set when the parent was planning at spawn: the child is told it plans too (#437). */
+  planMode?: boolean;
   /**
    * Set only for a workflow's own children, and only when they have no
    * `StructuredOutput` tool to answer through.
@@ -93,6 +96,8 @@ Return only the answer, in exactly the shape the prompt asks for — no preamble
 </workflow_child>`
     : "";
 
+  const planModeBlock = extras?.planMode ? `\n\n${PLAN_MODE_CHILD_PROMPT}` : "";
+
   const nestingBlock = extras?.nestingDisabled
     ? `\n\n<nesting_disabled>
 Nested subagents are disabled for this session, so you have no Agent tool. Do the work yourself, inline.
@@ -137,7 +142,7 @@ You are operating as a sub-agent invoked to handle a specific task.
     // placed verbatim (no wrapper tag) so it forms an identical byte prefix
     // with the parent session, maximising KV cache hits. The <active_agent>
     // tag and env block vary per call and are placed after the cached prefix.
-    return identity + "\n\n" + bridge + "\n\n" + activeAgentTag + envBlock + worktreeBlock + workflowBlock + nestingBlock + customSection + extrasSuffix;
+    return identity + "\n\n" + bridge + "\n\n" + activeAgentTag + envBlock + worktreeBlock + planModeBlock + workflowBlock + nestingBlock + customSection + extrasSuffix;
   }
 
   // "replace" mode — env header + the config's full system prompt
@@ -146,7 +151,7 @@ You have been invoked to handle a specific task autonomously.
 
 ${envBlock}`;
 
-  return activeAgentTag + replaceHeader + worktreeBlock + workflowBlock + nestingBlock + "\n\n" + config.systemPrompt + extrasSuffix;
+  return activeAgentTag + replaceHeader + worktreeBlock + planModeBlock + workflowBlock + nestingBlock + "\n\n" + config.systemPrompt + extrasSuffix;
 }
 
 /** Fallback base prompt when parent system prompt is unavailable in append mode. */

package/src/quota-admission.ts

@@ -4,7 +4,7 @@
  * Quota tracking lives in a separate extension (nredd/pi-subscription-router),
  * reached over `pi.events` with the same envelope as `cross-extension-rpc.ts`:
  * emit `router:rpc:admit` `{ requestId, model }`, reply on
- * `router:rpc:admit:reply:<requestId>` as `{ success, data?: { ok, resolvedModel?, resetAt?, wait? } }` (`resolvedModel` is ignored).
+ * `router:rpc:admit:reply:<requestId>` as `{ success, data?: { ok, resolvedModel?, resetAt?, wait? } }` (`resolvedModel` labels the admitted physical model).
  *
  * Admission fails open. No router installed, a slow router, a malformed reply
  * or a router error all admit the dispatch: quota is advisory here, and the
@@ -13,6 +13,7 @@
 
 import { nanoid } from "nanoid";
 import { type Clock, realClock } from "./clock.js";
+import type { TierAdmission } from "./model-tiers.js";
 
 export const ADMIT_CHANNEL = "router:rpc:admit";
 
@@ -50,34 +51,55 @@ export function modelRef(model: { provider: string; id: string }): string {
 }
 
 /** Resolve to the block when the router refuses `model`, else undefined. */
-export function checkAdmission(
+export async function checkAdmission(
   events: AdmissionEvents,
   model: string,
   timeoutMs = ADMIT_TIMEOUT_MS,
   clock: Clock = realClock,
+  signal?: AbortSignal,
 ): Promise<QuotaBlock | undefined> {
+  return (await admissionOutcome(events, model, timeoutMs, clock, signal)).block;
+}
+
+/** Retain the physical admission label and whether the router supplied a signal. */
+export function admissionOutcome(
+  events: AdmissionEvents,
+  model: string,
+  timeoutMs = ADMIT_TIMEOUT_MS,
+  clock: Clock = realClock,
+  signal?: AbortSignal,
+): Promise<TierAdmission> {
+  if (signal?.aborted) return Promise.reject(new DOMException("Admission cancelled", "AbortError"));
   const requestId = nanoid();
-  return new Promise(resolve => {
-    let done = false;
-    const finish = (block: QuotaBlock | undefined) => {
-      if (done) return;
-      done = true;
+  return new Promise((resolve, reject) => {
+    // Every step is idempotent and a promise settles once, so no `done` latch is needed.
+    const cleanup = () => {
       timer.cancel();
       unsubscribe();
-      resolve(block);
+      signal?.removeEventListener("abort", abort);
+    };
+    const abort = () => {
+      cleanup();
+      reject(new DOMException("Admission cancelled", "AbortError"));
+    };
+    const finish = (outcome: TierAdmission) => {
+      cleanup();
+      resolve(outcome);
     };
     const unsubscribe = events.on(`${ADMIT_CHANNEL}:reply:${requestId}`, raw => {
-      const reply = raw as { success?: unknown; data?: { ok?: unknown; resetAt?: unknown; wait?: unknown } } | undefined;
-      if (reply?.success !== true || reply.data?.ok !== false) return finish(undefined);
+      const reply = raw as { success?: unknown; data?: { ok?: unknown; resolvedModel?: unknown; resetAt?: unknown; wait?: unknown } } | undefined;
+      if (reply?.success !== true || typeof reply.data?.ok !== "boolean") return finish({ quotaSignal: false });
+      if (reply.data.ok) return finish({ quotaSignal: true, resolvedModel: typeof reply.data.resolvedModel === "string" ? reply.data.resolvedModel : undefined });
       const resetAt = reply.data.resetAt;
       const wait = reply.data.wait;
-      finish({
+      finish({ quotaSignal: true, block: {
         model,
         resetAt: typeof resetAt === "number" && Number.isFinite(resetAt) ? resetAt : undefined,
         ...(typeof wait === "boolean" ? { wait } : {}),
-      });
+      } });
     });
-    const timer = clock.setTimeout(() => finish(undefined), timeoutMs);
+    const timer = clock.setTimeout(() => finish({ quotaSignal: false }), timeoutMs);
+    signal?.addEventListener("abort", abort, { once: true });
     events.emit(ADMIT_CHANNEL, { requestId, model });
   });
 }

package/src/resource-loader.ts

@@ -0,0 +1,65 @@
+/** Normalize explicit settings paths before Pi's real package manager resolves them. */
+import { DefaultPackageManager, DefaultResourceLoader, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { normalizeHomePath } from "./home-paths.js";
+
+type ResourceLoaderOptions = ConstructorParameters<typeof DefaultResourceLoader>[0];
+type ResourceSettings = ReturnType<SettingsManager["getGlobalSettings"]>;
+
+const RESOURCE_FIELDS = ["extensions", "skills", "prompts", "themes"] as const;
+
+/** Keep filter modifiers and non-home paths intact; only replace leading home references. */
+function expandSetting(entry: string, homeDir: string, modifiers = true): string {
+  const prefix = modifiers && /^[!+-]/.test(entry) ? entry[0] : "";
+  const path = entry.slice(prefix.length);
+  const trimmed = path.trim();
+  if (trimmed !== "~" && !trimmed.startsWith("~/") && !(process.platform === "win32" && trimmed.startsWith("~\\"))) return entry;
+  return prefix + normalizeHomePath(trimmed, homeDir);
+}
+
+/** Return copies so loading resources never changes persisted settings or their source objects. */
+export function normalizeResourceSettings(settings: ResourceSettings, homeDir: string): ResourceSettings {
+  const normalized = { ...settings };
+  for (const field of RESOURCE_FIELDS) {
+    if (settings[field]) normalized[field] = settings[field].map(entry => expandSetting(entry, homeDir));
+  }
+  if (settings.packages) {
+    normalized.packages = settings.packages.map(pkg => {
+      if (typeof pkg === "string") return expandSetting(pkg, homeDir, false);
+      const copy = { ...pkg, source: expandSetting(pkg.source, homeDir, false) };
+      for (const field of RESOURCE_FIELDS) {
+        if (pkg[field]) copy[field] = pkg[field].map(entry => expandSetting(entry, homeDir));
+      }
+      return copy;
+    });
+  }
+  return normalized;
+}
+
+type PackageManagerOptions = ConstructorParameters<typeof DefaultPackageManager>[0];
+
+/** Wrap settings readers once so Pi receives injected-home resource paths. */
+function normalizeHomeResourceSettings(settingsManager: SettingsManager, homeDir: string): SettingsManager {
+  const globalSettings = settingsManager.getGlobalSettings.bind(settingsManager);
+  const projectSettings = settingsManager.getProjectSettings.bind(settingsManager);
+  // Wrap the public readers, not a cached snapshot: reload and project-trust
+  // decisions continue to be owned by Pi, and every read receives fresh copies.
+  Object.assign(settingsManager, {
+    getGlobalSettings: () => normalizeResourceSettings(globalSettings(), homeDir),
+    getProjectSettings: () => normalizeResourceSettings(projectSettings(), homeDir),
+  });
+  return settingsManager;
+}
+
+/** Build Pi's package manager with injected-home settings normalization. */
+export function createHomePackageManager(options: PackageManagerOptions, homeDir?: string): DefaultPackageManager {
+  if (homeDir === undefined) return new DefaultPackageManager(options);
+  // `homeDir` also redirects Pi's automatic `<home>/.agents/skills` root (nredd/pi#13).
+  return new DefaultPackageManager({ ...options, homeDir, settingsManager: normalizeHomeResourceSettings(options.settingsManager, homeDir) });
+}
+
+/** Use the real loader/manager while preventing ambient-home expansion of explicit settings. */
+export function createHomeResourceLoader(options: ResourceLoaderOptions, homeDir?: string): DefaultResourceLoader {
+  if (homeDir === undefined) return new DefaultResourceLoader(options);
+  const settingsManager = options.settingsManager ?? SettingsManager.create(options.cwd, options.agentDir);
+  return new DefaultResourceLoader({ ...options, homeDir, settingsManager: normalizeHomeResourceSettings(settingsManager, homeDir) });
+}