@gotgenes/pi-permission-system 18.2.0 → 19.0.1

package/src/authority/forwarded-request-server.ts

@@ -0,0 +1,285 @@
+import { join } from "node:path";
+import {
+  type ForwarderContext,
+  getSessionId,
+} from "#src/authority/forwarder-context";
+import type { ConfigReader } from "#src/config-store";
+import { isYoloModeEnabled } from "#src/extension-config";
+import type {
+  PermissionDecisionUi,
+  PermissionPromptDecision,
+  RequestPermissionOptions,
+} from "#src/permission-dialog";
+import {
+  emitUiPromptEvent,
+  type PermissionEventBus,
+} from "#src/permission-events";
+import {
+  type ForwardedPermissionRequest,
+  type ForwardedPermissionResponse,
+  isForwardedPermissionRequestForSession,
+  type PermissionForwardingLocation,
+} from "#src/permission-forwarding";
+import { buildForwardedUiPrompt } from "#src/permission-ui-prompt";
+import type { DebugReviewLogger } from "#src/session-logger";
+
+import {
+  cleanupPermissionForwardingLocationIfEmpty,
+  ensureDirectoryExists,
+  getExistingPermissionForwardingLocation,
+  listRequestFiles,
+  logPermissionForwardingError,
+  logPermissionForwardingWarning,
+  readForwardedPermissionRequest,
+  safeDeleteFile,
+  writeJsonFileAtomic,
+} from "./forwarding-io";
+
+/**
+ * Narrow seam describing what `ForwardingManager` needs from the server: a
+ * single method that drains this session's forwarded-permission inbox.
+ *
+ * Depending on the interface (not the concrete `ForwardedRequestServer`)
+ * keeps the manager's unit tests free of casts — they inject a plain
+ * `{ processInbox: vi.fn() }` mock.
+ */
+export interface InboxProcessor {
+  processInbox(ctx: ForwarderContext): Promise<void>;
+}
+
+/** Constructor config for `ForwardedRequestServer`. */
+export interface ForwardedRequestServerDeps {
+  forwardingDir: string;
+  logger: DebugReviewLogger;
+  /** Event bus used for UI prompt broadcasts. */
+  events?: PermissionEventBus;
+  requestPermissionDecisionFromUi: (
+    ui: PermissionDecisionUi,
+    title: string,
+    message: string,
+    options?: RequestPermissionOptions,
+  ) => Promise<PermissionPromptDecision>;
+  /** Read current config for the retained forwarded-inbox yolo auto-approve check. */
+  config: ConfigReader;
+}
+
+// ── Module-private helpers ────────────────────────────────────────────────
+
+function formatForwardedPermissionPrompt(
+  request: ForwardedPermissionRequest,
+): string {
+  const agentName = request.requesterAgentName || "unknown";
+  const sessionId = request.requesterSessionId || "unknown";
+  return [
+    `Subagent '${agentName}' requested permission.`,
+    `Session ID: ${sessionId}`,
+    "",
+    request.message,
+  ].join("\n");
+}
+
+// ── ForwardedRequestServer ────────────────────────────────────────────────
+
+/**
+ * Owner of the serving-down role of the forwarded-permission behavior:
+ * draining this session's forwarded-permission inbox and answering each
+ * request (auto-approve under yolo, or prompt via the injected UI).
+ */
+export class ForwardedRequestServer implements InboxProcessor {
+  private readonly forwardingDir: string;
+  private readonly events: PermissionEventBus | undefined;
+  private readonly logger: DebugReviewLogger;
+  private readonly requestPermissionDecisionFromUi: (
+    ui: PermissionDecisionUi,
+    title: string,
+    message: string,
+    options?: RequestPermissionOptions,
+  ) => Promise<PermissionPromptDecision>;
+  private readonly config: ConfigReader;
+
+  constructor(deps: ForwardedRequestServerDeps) {
+    this.forwardingDir = deps.forwardingDir;
+    this.events = deps.events;
+    this.logger = deps.logger;
+    this.requestPermissionDecisionFromUi = deps.requestPermissionDecisionFromUi;
+    this.config = deps.config;
+  }
+
+  /** Drain and respond to this session's forwarded-permission inbox. */
+  async processInbox(ctx: ForwarderContext): Promise<void> {
+    if (!ctx.hasUI) {
+      return;
+    }
+
+    const currentSessionId = getSessionId(ctx);
+    const location = getExistingPermissionForwardingLocation(
+      this.forwardingDir,
+      currentSessionId,
+    );
+    if (!location) {
+      return;
+    }
+
+    const requestFiles = listRequestFiles(this.logger, location.requestsDir);
+    if (requestFiles.length === 0) {
+      return;
+    }
+
+    // Defensively recreate responses/ before writing any response — a
+    // concurrent cleanup pass may have removed it between the requestsDir
+    // existence check above and the write inside processSingleForwardedRequest
+    // (the ENOENT write loop reported in issue #398).
+    if (
+      !ensureDirectoryExists(
+        this.logger,
+        location.responsesDir,
+        "permission forwarding responses",
+      )
+    ) {
+      return;
+    }
+
+    for (const fileName of requestFiles) {
+      const requestPath = join(location.requestsDir, fileName);
+      const request = readForwardedPermissionRequest(this.logger, requestPath);
+      if (!request) {
+        safeDeleteFile(
+          this.logger,
+          requestPath,
+          `${location.label} forwarded permission request`,
+        );
+        continue;
+      }
+
+      await this.processSingleForwardedRequest(
+        ctx,
+        request,
+        location,
+        requestPath,
+        currentSessionId,
+      );
+    }
+
+    cleanupPermissionForwardingLocationIfEmpty(this.logger, location);
+  }
+
+  // ── Private methods ────────────────────────────────────────────────────
+
+  private async processSingleForwardedRequest(
+    ctx: ForwarderContext,
+    request: ForwardedPermissionRequest,
+    location: PermissionForwardingLocation,
+    requestPath: string,
+    currentSessionId: string,
+  ): Promise<void> {
+    if (!isForwardedPermissionRequestForSession(request, currentSessionId)) {
+      logPermissionForwardingWarning(
+        this.logger,
+        `Ignoring forwarded permission request '${request.id}' because it targets session '${request.targetSessionId}' instead of '${currentSessionId}'`,
+      );
+      safeDeleteFile(
+        this.logger,
+        requestPath,
+        `${location.label} forwarded permission request`,
+      );
+      return;
+    }
+
+    const forwardedPermissionLogDetails = {
+      requestId: request.id,
+      source: location.label,
+      requesterAgentName: request.requesterAgentName,
+      requesterSessionId: request.requesterSessionId,
+      targetSessionId: request.targetSessionId,
+      requestPath,
+    };
+
+    let decision: PermissionPromptDecision = {
+      approved: false,
+      state: "denied",
+    };
+    // Last yolo check outside the composed ruleset: dissolves when
+    // processInbox is refactored onto evaluate() + Authorizer selection in
+    // the Phase 9 spine work.
+    if (isYoloModeEnabled(this.config.current())) {
+      this.logger.review(
+        "forwarded_permission.auto_approved",
+        forwardedPermissionLogDetails,
+      );
+      decision = { approved: true, state: "approved" };
+    } else {
+      this.logger.review(
+        "forwarded_permission.prompted",
+        forwardedPermissionLogDetails,
+      );
+      try {
+        const forwardedMessage = formatForwardedPermissionPrompt(request);
+        if (this.events) {
+          emitUiPromptEvent(
+            this.events,
+            buildForwardedUiPrompt({
+              requestId: request.id,
+              message: forwardedMessage,
+              requesterAgentName: request.requesterAgentName || null,
+              requesterSessionId: request.requesterSessionId || null,
+              source: request.source ?? null,
+              surface: request.surface ?? null,
+              value: request.value ?? null,
+            }),
+          );
+        }
+        decision = await this.requestPermissionDecisionFromUi(
+          ctx.ui,
+          "Permission Required (Subagent)",
+          forwardedMessage,
+        );
+      } catch (error) {
+        logPermissionForwardingError(
+          this.logger,
+          "Failed to show forwarded permission confirmation dialog",
+          error,
+        );
+        decision = { approved: false, state: "denied" };
+      }
+    }
+
+    const responsePath = join(location.responsesDir, `${request.id}.json`);
+    this.logger.review(
+      decision.approved
+        ? "forwarded_permission.approved"
+        : "forwarded_permission.denied",
+      {
+        requestId: request.id,
+        source: location.label,
+        requesterAgentName: request.requesterAgentName,
+        requesterSessionId: request.requesterSessionId,
+        targetSessionId: request.targetSessionId,
+        responsePath,
+        resolution: decision.state,
+        denialReason: decision.denialReason ?? null,
+      },
+    );
+    try {
+      writeJsonFileAtomic(this.logger, responsePath, {
+        approved: decision.approved,
+        state: decision.state,
+        denialReason: decision.denialReason,
+        responderSessionId: currentSessionId,
+        respondedAt: Date.now(),
+      } satisfies ForwardedPermissionResponse);
+    } catch (error) {
+      logPermissionForwardingError(
+        this.logger,
+        `Failed to write ${location.label} forwarded permission response '${responsePath}'`,
+        error,
+      );
+      return;
+    }
+
+    safeDeleteFile(
+      this.logger,
+      requestPath,
+      `${location.label} forwarded permission request`,
+    );
+  }
+}

package/src/authority/forwarder-context.ts

@@ -0,0 +1,32 @@
+import type { SessionEntryView } from "#src/active-agent";
+import type { PermissionDecisionUi } from "#src/permission-dialog";
+
+/**
+ * Narrow context the forwarding subsystem reads: the UI gate (`hasUI`), the
+ * dialog UI surface, and the three session-manager readers `getSessionId`
+ * and the `active-agent` helpers use.
+ *
+ * A full `ExtensionContext` satisfies this structurally, so production
+ * callers pass `ctx` unchanged.
+ */
+export interface ForwarderContext {
+  hasUI: boolean;
+  ui: PermissionDecisionUi;
+  sessionManager: {
+    getSessionId(): string;
+    getSessionDir(): string;
+    getEntries(): readonly SessionEntryView[];
+  };
+}
+
+/** Reads the current session id off `ctx`, falling back to `"unknown"`. */
+export function getSessionId(ctx: ForwarderContext): string {
+  try {
+    const sessionId = ctx.sessionManager.getSessionId();
+    if (typeof sessionId === "string" && sessionId.trim()) {
+      return sessionId.trim();
+    }
+  } catch {}
+
+  return "unknown";
+}

package/src/{subagent-context.ts → authority/subagent-context.ts}

@@ -1,7 +1,7 @@
 import { posix as posixPath, win32 as winPath } from "node:path";
 
-import { SUBAGENT_ENV_HINT_KEYS } from "./permission-forwarding";
-import type { SubagentSessionRegistry } from "./subagent-registry";
+import { SUBAGENT_ENV_HINT_KEYS } from "#src/permission-forwarding";
+import type { SubagentSessionRegistry } from "#src/subagent-registry";
 
 /**
  * Narrow context for subagent detection — the only session-manager readers

package/src/authority/subagent-detection.ts

@@ -0,0 +1,65 @@
+import {
+  isRegisteredSubagentChild,
+  isSubagentExecutionContext,
+  type SubagentDetectionContext,
+} from "#src/authority/subagent-context";
+import type { SubagentSessionRegistry } from "#src/subagent-registry";
+
+/**
+ * Narrow seam for the ask-path consumers: "is the current session a subagent?"
+ *
+ * `PromptingGateway`, `ForwardingManager`, and `ApprovalEscalator` depend on
+ * this single-method view so their unit tests inject a one-field fake without
+ * casts. It is the Authorizer-selection predicate the Phase 9 spine consumes.
+ */
+export interface SubagentDetector {
+  isSubagent(ctx: SubagentDetectionContext): boolean;
+}
+
+/**
+ * Narrow seam for the service-publication guard (#302): "is the current
+ * session a registered in-process child?"
+ *
+ * `PermissionServiceLifecycle` depends on this single-method view so a
+ * registered child never publishes over its parent's process-global slot.
+ */
+export interface RegisteredChildDetector {
+  isRegisteredChild(ctx: SubagentDetectionContext): boolean;
+}
+
+/** Composition-root inputs for {@link SubagentDetection}. */
+export interface SubagentDetectionDeps {
+  subagentSessionsDir: string;
+  platform: NodeJS.Platform;
+  registry?: SubagentSessionRegistry;
+}
+
+/**
+ * Single owner of subagent detection.
+ *
+ * Constructed once in the composition root with the detection inputs
+ * (`subagentSessionsDir`, `platform`, `registry`) and shared across every
+ * consumer, replacing the dep triple those consumers previously threaded
+ * individually. Delegates to the pure detection functions in
+ * {@link ./subagent-context}, holding only the deps.
+ */
+export class SubagentDetection
+  implements SubagentDetector, RegisteredChildDetector
+{
+  constructor(private readonly deps: SubagentDetectionDeps) {}
+
+  isSubagent(ctx: SubagentDetectionContext): boolean {
+    return isSubagentExecutionContext(
+      ctx,
+      this.deps.subagentSessionsDir,
+      this.deps.platform,
+      this.deps.registry,
+    );
+  }
+
+  isRegisteredChild(ctx: SubagentDetectionContext): boolean {
+    return this.deps.registry
+      ? isRegisteredSubagentChild(ctx, this.deps.registry)
+      : false;
+  }
+}

package/src/config-loader.ts

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { normalize } from "node:path";
+import type { ZodError } from "zod";
 import {
   getGlobalConfigPath,
   getLegacyExtensionConfigPath,
@@ -7,32 +8,19 @@ import {
   getLegacyProjectPolicyPath,
   getProjectConfigPath,
 } from "./config-paths";
+import {
+  type UnifiedPermissionConfig,
+  unifiedConfigSchema,
+} from "./config-schema";
 import { mergeFlatPermissions } from "./permission-merge";
 import type { FlatPermissionConfig, PatternValue } from "./types";
-import {
-  isDenyWithReason,
-  isPermissionState,
-  normalizeOptionalPositiveInt,
-  normalizeOptionalStringArray,
-  toRecord,
-} from "./value-guards";
+import { isDenyWithReason, isPermissionState } from "./value-guards";
 
-/**
- * Unified config shape combining runtime knobs and flat permission policy.
- * All fields are optional so partial configs (project-only, global-only) work.
- */
-export interface UnifiedPermissionConfig {
-  // Runtime knobs
-  debugLog?: boolean;
-  permissionReviewLog?: boolean;
-  yoloMode?: boolean;
-  toolInputPreviewMaxLength?: number;
-  toolTextSummaryMaxLength?: number;
-  piInfrastructureReadPaths?: string[];
-
-  // Flat permission policy
-  permission?: FlatPermissionConfig;
-}
+// The unified config shape is derived from the zod schema (config-schema.ts,
+// the single source of truth) and re-exported so existing importers keep their
+// import path. All fields are optional so partial configs merge before
+// defaults are applied downstream.
+export type { UnifiedPermissionConfig };
 
 export interface UnifiedConfigLoadResult {
   config: UnifiedPermissionConfig;
@@ -118,20 +106,13 @@ function consumeString(input: string, start: number): ScanSegment {
   return { output, nextIndex: i };
 }
 
-function normalizeOptionalBoolean(value: unknown): boolean | undefined {
-  if (typeof value === "boolean") {
-    return value;
-  }
-  return undefined;
-}
-
 /**
  * Normalize a raw `permission` value from parsed JSON into a FlatPermissionConfig.
  * Accepts PermissionState strings and DenyWithReason objects inside pattern
  * maps. Drops non-object top-level values, invalid PermissionState strings, and
  * invalid action values inside object maps.
  */
-function normalizeFlatPermissionValue(
+export function normalizeFlatPermissionValue(
   value: unknown,
 ): FlatPermissionConfig | undefined {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -172,52 +153,39 @@ function normalizeFlatPermissionValue(
 }
 
 /**
- * Normalize raw parsed JSON into the unified config shape.
+ * Validate raw parsed JSON against the config schema (the single source of
+ * truth in `config-schema.ts`).
+ *
+ * On success the typed config is returned. On failure the whole scope config is
+ * rejected — fail-closed: an empty config contributes no rules, so missing
+ * surfaces fall through to the universal `ask` default rather than `allow` —
+ * and every schema violation is reported as a clear, actionable issue.
  */
-export function normalizeUnifiedConfig(raw: unknown): {
-  config: UnifiedPermissionConfig;
-  issues: string[];
-} {
-  const record = toRecord(raw);
-  const issues: string[] = [];
-  const config: UnifiedPermissionConfig = {};
-
-  // Runtime knobs
-  const debugLog = normalizeOptionalBoolean(record.debugLog);
-  if (debugLog !== undefined) config.debugLog = debugLog;
-
-  const permissionReviewLog = normalizeOptionalBoolean(
-    record.permissionReviewLog,
-  );
-  if (permissionReviewLog !== undefined)
-    config.permissionReviewLog = permissionReviewLog;
-
-  const yoloMode = normalizeOptionalBoolean(record.yoloMode);
-  if (yoloMode !== undefined) config.yoloMode = yoloMode;
-
-  const toolInputPreviewMaxLength = normalizeOptionalPositiveInt(
-    record.toolInputPreviewMaxLength,
-  );
-  if (toolInputPreviewMaxLength !== undefined)
-    config.toolInputPreviewMaxLength = toolInputPreviewMaxLength;
-
-  const toolTextSummaryMaxLength = normalizeOptionalPositiveInt(
-    record.toolTextSummaryMaxLength,
-  );
-  if (toolTextSummaryMaxLength !== undefined)
-    config.toolTextSummaryMaxLength = toolTextSummaryMaxLength;
-
-  const piInfrastructureReadPaths = normalizeOptionalStringArray(
-    record.piInfrastructureReadPaths,
-  );
-  if (piInfrastructureReadPaths !== undefined)
-    config.piInfrastructureReadPaths = piInfrastructureReadPaths;
-
-  // Flat permission policy
-  const permission = normalizeFlatPermissionValue(record.permission);
-  if (permission !== undefined) config.permission = permission;
+export function validateUnifiedConfig(
+  parsed: unknown,
+): UnifiedConfigLoadResult {
+  const result = unifiedConfigSchema.safeParse(parsed);
+  if (result.success) {
+    return { config: result.data, issues: [] };
+  }
+  return { config: {}, issues: formatConfigIssues(result.error) };
+}
 
-  return { config, issues };
+/** Render each schema violation as a clear, path-qualified message. */
+function formatConfigIssues(error: ZodError): string[] {
+  const messages: string[] = [];
+  for (const issue of error.issues) {
+    if (issue.code === "unrecognized_keys") {
+      for (const key of issue.keys) {
+        messages.push(`Unrecognized config key '${key}'.`);
+      }
+      continue;
+    }
+    const location =
+      issue.path.length > 0 ? issue.path.map(String).join(".") : "(root)";
+    messages.push(`Invalid config value at '${location}': ${issue.message}`);
+  }
+  return messages;
 }
 
 /**
@@ -320,7 +288,8 @@ export function loadAndMergeConfigs(
         `Move it to '${newGlobalPath}':\n` +
         `  mv '${legacyGlobalPolicyPath}' '${newGlobalPath}'`,
     );
-    allIssues.push(...legacy.issues);
+    // Legacy files are migrated away; the move-it guidance above is the
+    // actionable signal, so strict-validation issues for them are suppressed.
     merged = mergeUnifiedConfigs(merged, legacy.config);
   }
 
@@ -337,7 +306,7 @@ export function loadAndMergeConfigs(
         `Move runtime settings to '${newGlobalPath}':\n` +
         `  mv '${legacyExtConfigPath}' '${newGlobalPath}'`,
     );
-    allIssues.push(...legacy.issues);
+    // See above: legacy-file validation issues are suppressed.
     merged = mergeUnifiedConfigs(merged, legacy.config);
   }
 
@@ -355,7 +324,7 @@ export function loadAndMergeConfigs(
         `Move it to '${newProjectPath}':\n` +
         `  mv '${legacyProjectPolicyPath}' '${newProjectPath}'`,
     );
-    allIssues.push(...legacy.issues);
+    // See above: legacy-file validation issues are suppressed.
     merged = mergeUnifiedConfigs(merged, legacy.config);
   }
 
@@ -421,7 +390,7 @@ export function loadUnifiedConfig(path: string): UnifiedConfigLoadResult {
   try {
     const raw = readFileSync(path, "utf-8");
     const parsed = JSON.parse(stripJsonComments(raw)) as unknown;
-    return normalizeUnifiedConfig(parsed);
+    return validateUnifiedConfig(parsed);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     return {