@xzzpig/pi-subagents 0.11.0 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -16,6 +16,7 @@ import { normalizeWorktreeBaseRef } from "../shared/worktree.ts";
16
16
  import { intersectThinkingCeilings, parseThinkingLevel, type ThinkingLevel } from "../../shared/thinking-ceiling.ts";
17
17
  import { assertWorkflowGraphHostSteps } from "../shared/host-step-status.ts";
18
18
  import { validateSandboxProfileName } from "../../shared/sandbox-profile.ts";
19
+ import { validatePermissionProfileName } from "../../shared/permission-profile.ts";
19
20
 
20
21
  export interface AsyncResumeParams {
21
22
  id?: string;
@@ -57,6 +58,7 @@ export type AsyncResumeTarget = {
57
58
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
58
59
  launchContractDigest?: string;
59
60
  sandbox?: string;
61
+ permissionProfile?: string;
60
62
  runner?: NonNullable<AsyncStatus["steps"]>[number]["runner"];
61
63
  externalJob?: NonNullable<AsyncStatus["steps"]>[number]["externalJob"];
62
64
  };
@@ -76,8 +78,9 @@ interface AsyncResultFile {
76
78
  thinking?: string;
77
79
  launchContractDigest?: string;
78
80
  sandbox?: string;
81
+ permissionProfile?: string;
79
82
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
80
- results?: Array<{ agent?: string; sessionName?: string; success?: boolean; sessionFile?: string; intercomTarget?: string; model?: string; thinking?: string; launchContractDigest?: string; sandbox?: string; capabilityCeiling?: ResolvedSubagentCapabilityCeiling }>;
83
+ results?: Array<{ agent?: string; sessionName?: string; success?: boolean; sessionFile?: string; intercomTarget?: string; model?: string; thinking?: string; launchContractDigest?: string; sandbox?: string; permissionProfile?: string; capabilityCeiling?: ResolvedSubagentCapabilityCeiling }>;
81
84
  }
82
85
 
83
86
  export interface AsyncRunLocation {
@@ -122,10 +125,13 @@ function validateResultFile(value: unknown, resultPath: string): AsyncResultFile
122
125
  const sandbox = child.sandbox === undefined
123
126
  ? undefined
124
127
  : validateSandboxProfileName(child.sandbox, `async result file '${resultPath}' results[${index}].sandbox`);
128
+ const permissionProfile = child.permissionProfile === undefined
129
+ ? undefined
130
+ : validatePermissionProfileName(child.permissionProfile, `async result file '${resultPath}' results[${index}].permissionProfile`);
125
131
  const capabilityCeiling = child.capabilityCeiling === undefined ? undefined : parseSubagentCapabilityCeiling(child.capabilityCeiling, `async result file '${resultPath}' results[${index}].capabilityCeiling`);
126
132
  const success = child.success;
127
133
  if (success !== undefined && typeof success !== "boolean") throw new Error(`Invalid async result file '${resultPath}': results[${index}].success must be a boolean.`);
128
- return { agent, sessionName, sessionFile, intercomTarget, model, thinking, launchContractDigest, ...(sandbox ? { sandbox } : {}), ...(capabilityCeiling ? { capabilityCeiling } : {}), ...(typeof success === "boolean" ? { success } : {}) };
134
+ return { agent, sessionName, sessionFile, intercomTarget, model, thinking, launchContractDigest, ...(sandbox ? { sandbox } : {}), ...(permissionProfile ? { permissionProfile } : {}), ...(capabilityCeiling ? { capabilityCeiling } : {}), ...(typeof success === "boolean" ? { success } : {}) };
129
135
  });
130
136
  }
131
137
  const success = data.success;
@@ -143,6 +149,7 @@ function validateResultFile(value: unknown, resultPath: string): AsyncResultFile
143
149
  thinking: validateOptionalString(data, "thinking", resultPath),
144
150
  launchContractDigest: validateOptionalString(data, "launchContractDigest", resultPath),
145
151
  ...(data.sandbox === undefined ? {} : { sandbox: validateSandboxProfileName(data.sandbox, `async result file '${resultPath}' sandbox`) }),
152
+ ...(data.permissionProfile === undefined ? {} : { permissionProfile: validatePermissionProfileName(data.permissionProfile, `async result file '${resultPath}' permissionProfile`) }),
146
153
  ...(data.capabilityCeiling === undefined ? {} : { capabilityCeiling: parseSubagentCapabilityCeiling(data.capabilityCeiling, `async result file '${resultPath}' capabilityCeiling`) }),
147
154
  ...(typeof success === "boolean" ? { success } : {}),
148
155
  ...(results ? { results } : {}),
@@ -290,6 +297,7 @@ function validateStatusForResume(status: AsyncStatus | null, source: string): vo
290
297
  if (stepRecord.thinkingCeiling !== undefined) stepRecord.thinkingCeiling = parseThinkingLevel(stepRecord.thinkingCeiling, `async status '${source}' steps[${index}].thinkingCeiling`);
291
298
  if (stepRecord.launchContractDigest !== undefined && typeof stepRecord.launchContractDigest !== "string") throw new Error(`Invalid async status '${source}': steps[${index}].launchContractDigest must be a string.`);
292
299
  if (stepRecord.sandbox !== undefined) stepRecord.sandbox = validateSandboxProfileName(stepRecord.sandbox, `async status '${source}' steps[${index}].sandbox`);
300
+ if (stepRecord.permissionProfile !== undefined) stepRecord.permissionProfile = validatePermissionProfileName(stepRecord.permissionProfile, `async status '${source}' steps[${index}].permissionProfile`);
293
301
  if (stepRecord.capabilityCeiling !== undefined) stepRecord.capabilityCeiling = parseSubagentCapabilityCeiling(stepRecord.capabilityCeiling, `async status '${source}' steps[${index}].capabilityCeiling`);
294
302
  });
295
303
  }
@@ -325,7 +333,7 @@ export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): Steer
325
333
  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': expected an object.`);
326
334
  const parsed = value as Record<string, unknown>;
327
335
  const allowedFields = new Set([
328
- "version", "launchContractDigest", "sourceRunId", "agentContract", "agent", "sandbox", "sessionFile", "cwd", "model", "modelProvider", "modelOverrideFromParent", "modelOrigin", "fallbackModels", "thinking", "thinkingCeiling", "tools", "allowNestedSubagents", "extensions",
336
+ "version", "launchContractDigest", "sourceRunId", "agentContract", "agent", "sandbox", "permissionProfile", "sessionFile", "cwd", "model", "modelProvider", "modelOverrideFromParent", "modelOrigin", "fallbackModels", "thinking", "thinkingCeiling", "tools", "allowNestedSubagents", "extensions",
329
337
  "subagentOnlyExtensions", "mcpDirectTools", "excludeTools", "mutationTools", "systemPrompt", "systemPromptMode", "inheritProjectContext", "inheritGlobalContext", "inheritSkills", "skills",
330
338
  "skillPath", "agentFilePath", "completionGuard", "memory", "outputPath", "outputMode", "structuredOutputSchema", "acceptance", "sessionDir", "artifactConfig",
331
339
  "artifactsDir", "maxOutput", "controlConfig", "context", "intercomBridge", "absoluteDeadlineAt", "initialTurnBudget", "initialToolBudget", "maxSubagentDepth", "share", "capabilityCeiling",
@@ -384,6 +392,7 @@ export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): Steer
384
392
  }
385
393
  }
386
394
  if (parsed.sandbox !== undefined) parsed.sandbox = validateSandboxProfileName(parsed.sandbox, `async recovery descriptor '${descriptorPath}' sandbox`);
395
+ if (parsed.permissionProfile !== undefined) parsed.permissionProfile = validatePermissionProfileName(parsed.permissionProfile, `async recovery descriptor '${descriptorPath}' permissionProfile`);
387
396
  if (parsed.completionGuard !== undefined && typeof parsed.completionGuard !== "boolean") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': completionGuard must be a boolean.`);
388
397
  if (parsed.structuredOutputSchema !== undefined && (!parsed.structuredOutputSchema || typeof parsed.structuredOutputSchema !== "object" || Array.isArray(parsed.structuredOutputSchema))) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': structuredOutputSchema must be an object.`);
389
398
  if (parsed.memory !== undefined) {
@@ -517,6 +526,7 @@ export function resolveAsyncResumeTarget(params: AsyncResumeParams, deps: AsyncR
517
526
  model: selectedStep.model,
518
527
  thinking: selectedStep.thinking,
519
528
  sandbox: selectedStep.sandbox ?? result?.results?.[requestedIndex]?.sandbox ?? result?.sandbox ?? recoveryDescriptor?.sandbox,
529
+ permissionProfile: selectedStep.permissionProfile ?? result?.results?.[requestedIndex]?.permissionProfile ?? result?.permissionProfile ?? recoveryDescriptor?.permissionProfile,
520
530
  launchContractDigest: selectedStep.launchContractDigest ?? result?.results?.[requestedIndex]?.launchContractDigest ?? result?.launchContractDigest ?? recoveryDescriptor?.launchContractDigest,
521
531
  ...(selectedStep.runner ? { runner: selectedStep.runner } : {}),
522
532
  ...(selectedStep.externalJob ? { externalJob: selectedStep.externalJob } : {}),
@@ -550,6 +560,7 @@ export function resolveAsyncResumeTarget(params: AsyncResumeParams, deps: AsyncR
550
560
  model: selected.step.model,
551
561
  thinking: selected.step.thinking,
552
562
  sandbox: selected.step.sandbox ?? result?.results?.[selected.index]?.sandbox ?? result?.sandbox ?? recoveryDescriptor?.sandbox,
563
+ permissionProfile: selected.step.permissionProfile ?? result?.results?.[selected.index]?.permissionProfile ?? result?.permissionProfile ?? recoveryDescriptor?.permissionProfile,
553
564
  launchContractDigest: selected.step.launchContractDigest ?? result?.results?.[selected.index]?.launchContractDigest ?? result?.launchContractDigest ?? recoveryDescriptor?.launchContractDigest,
554
565
  ...(selected.step.runner ? { runner: selected.step.runner } : {}),
555
566
  ...(selected.step.externalJob ? { externalJob: selected.step.externalJob } : {}),
@@ -598,6 +609,7 @@ export function resolveAsyncResumeTarget(params: AsyncResumeParams, deps: AsyncR
598
609
  ...(stepModel ? { model: stepModel } : {}),
599
610
  ...(stepThinking ? { thinking: stepThinking } : {}),
600
611
  sandbox: statusSteps[index]?.sandbox ?? resultSteps[index]?.sandbox ?? result?.sandbox ?? recoveryDescriptor?.sandbox,
612
+ permissionProfile: statusSteps[index]?.permissionProfile ?? resultSteps[index]?.permissionProfile ?? result?.permissionProfile ?? recoveryDescriptor?.permissionProfile,
601
613
  launchContractDigest: statusSteps[index]?.launchContractDigest ?? resultSteps[index]?.launchContractDigest ?? result?.launchContractDigest ?? recoveryDescriptor?.launchContractDigest,
602
614
  ...(statusSteps[index]?.runner ? { runner: statusSteps[index]!.runner } : {}),
603
615
  ...(statusSteps[index]?.externalJob ? { externalJob: statusSteps[index]!.externalJob } : {}),
@@ -623,6 +635,7 @@ export function applySteeringRecoveryAgentConfig(agentConfig: AgentConfig, descr
623
635
  mcpDirectTools: descriptor.mcpDirectTools ? [...descriptor.mcpDirectTools] : undefined,
624
636
  mutationTools: descriptor.mutationTools ? [...descriptor.mutationTools] : undefined,
625
637
  sandbox: descriptor.sandbox ?? agentConfig.sandbox,
638
+ permissionProfile: descriptor.permissionProfile ?? agentConfig.permissionProfile,
626
639
  systemPrompt: descriptor.systemPrompt ?? agentConfig.systemPrompt,
627
640
  systemPromptMode: descriptor.systemPromptMode,
628
641
  inheritProjectContext: descriptor.inheritProjectContext,
@@ -26,6 +26,7 @@ import { workflowGraphStageNodes } from "../shared/workflow-graph.ts";
26
26
  import { formatTimeoutRecoveryLines, projectTimeoutRecovery } from "../shared/mutation-evidence.ts";
27
27
  import { formatWorkflowChecklistText, projectWorkflowChecklist } from "../../workflows/workflow-checklist.ts";
28
28
  import { validateSandboxProfileName } from "../../shared/sandbox-profile.ts";
29
+ import { validatePermissionProfileName } from "../../shared/permission-profile.ts";
29
30
 
30
31
  interface AsyncRunStepSummary {
31
32
  index: number;
@@ -67,6 +68,7 @@ interface AsyncRunStepSummary {
67
68
  contextLimit?: number;
68
69
  thinking?: string;
69
70
  sandbox?: string;
71
+ permissionProfile?: string;
70
72
  attemptedModels?: string[];
71
73
  sessionFile?: string;
72
74
  transcriptPath?: string;
@@ -109,6 +111,7 @@ export interface AsyncRunSummary {
109
111
  mode: SubagentRunMode;
110
112
  context?: ContextSummary;
111
113
  sandbox?: string;
114
+ permissionProfile?: string;
112
115
  cwd?: string;
113
116
  sessionRoot?: string;
114
117
  startedAt: number;
@@ -214,6 +217,14 @@ function sandboxProfileValue(value: unknown): string | undefined {
214
217
  }
215
218
  }
216
219
 
220
+ function permissionProfileValue(value: unknown): string | undefined {
221
+ try {
222
+ return validatePermissionProfileName(value);
223
+ } catch {
224
+ return undefined;
225
+ }
226
+ }
227
+
217
228
  function isNotFoundError(error: unknown): boolean {
218
229
  return typeof error === "object"
219
230
  && error !== null
@@ -339,6 +350,7 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
339
350
  const stepLastActivityAt = step.lastActivityAt;
340
351
  const timeoutRecovery = projectTimeoutRecovery(step.timeoutRecovery);
341
352
  const sandbox = sandboxProfileValue(step.sandbox);
353
+ const permissionProfile = permissionProfileValue(step.permissionProfile);
342
354
  return {
343
355
  index,
344
356
  childId: asyncStatusChildIdentity(step, index),
@@ -378,6 +390,7 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
378
390
  ...(step.contextLimit !== undefined ? { contextLimit: step.contextLimit } : {}),
379
391
  ...(step.thinking ? { thinking: step.thinking } : {}),
380
392
  ...(sandbox ? { sandbox } : {}),
393
+ ...(permissionProfile ? { permissionProfile } : {}),
381
394
  ...(step.thinkingCeiling ? { thinkingCeiling: step.thinkingCeiling } : {}),
382
395
  ...(step.attemptedModels ? { attemptedModels: step.attemptedModels } : {}),
383
396
  ...(step.sessionFile ? { sessionFile: step.sessionFile } : {}),
@@ -409,6 +422,7 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
409
422
  });
410
423
  attachRootChildrenToSteps(status.runId || path.basename(asyncDir), summarizedSteps, nestedChildren);
411
424
  const sandbox = sandboxProfileValue(status.sandbox);
425
+ const permissionProfile = permissionProfileValue(status.permissionProfile);
412
426
  return {
413
427
  id: status.runId || path.basename(asyncDir),
414
428
  asyncDir,
@@ -427,6 +441,7 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
427
441
  mode: status.mode,
428
442
  ...(summarizeContextModes(summarizedSteps.map((step) => step.context)) ? { context: summarizeContextModes(summarizedSteps.map((step) => step.context)) } : {}),
429
443
  ...(sandbox ? { sandbox } : {}),
444
+ ...(permissionProfile ? { permissionProfile } : {}),
430
445
  cwd: status.cwd,
431
446
  ...(status.sessionRoot ? { sessionRoot: status.sessionRoot } : {}),
432
447
  startedAt: status.startedAt,
@@ -130,8 +130,9 @@ import { normalizeExtensionBindings } from "../shared/extension-bindings.ts";
130
130
  import { appendRunnerStepsToStatus, consumeChainAppendRequests, countPendingChainAppendRequests, statusStepDescription } from "./chain-append.ts";
131
131
  import { asyncStatusChildIdentity } from "../shared/child-identity.ts";
132
132
  import { validateSandboxProfileName } from "../../shared/sandbox-profile.ts";
133
+ import { validatePermissionProfileName } from "../../shared/permission-profile.ts";
133
134
  import { initialToolBudgetState, toolBudgetState } from "../shared/tool-budget.ts";
134
- import { effectiveToolTimeoutMs, formatToolTimeoutMessage, toolTimeoutCallKey } from "../shared/tool-timeout.ts";
135
+ import { toolTimeoutCallKey } from "../shared/tool-timeout.ts";
135
136
  import { usageBudgetExceededMessage, usageBudgetState } from "../shared/usage-budget.ts";
136
137
  import { formatParallelHandoffError, formatParallelHandoffReference, parallelHandoffPath, writeParallelHandoffGroup, writePendingParallelHandoff } from "../shared/parallel-handoff.ts";
137
138
  import { resolveWatchdogConfig } from "../../watchdog/settings.ts";
@@ -224,6 +225,7 @@ interface StepResult {
224
225
  sessionName?: string;
225
226
  context?: "fresh" | "fork";
226
227
  sandbox?: string;
228
+ permissionProfile?: string;
227
229
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
228
230
  capabilityAudit?: import("../shared/capability-ceiling.ts").SubagentCapabilityAudit;
229
231
  launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
@@ -284,6 +286,16 @@ function commonSandboxProfile(steps: readonly RunnerStatusStep[]): string | unde
284
286
  }
285
287
  }
286
288
 
289
+ function commonPermissionProfile(steps: readonly RunnerStatusStep[]): string | undefined {
290
+ const profile = steps[0]?.permissionProfile;
291
+ if (!profile || !steps.every((step) => step.permissionProfile === profile)) return undefined;
292
+ try {
293
+ return validatePermissionProfileName(profile);
294
+ } catch {
295
+ return undefined;
296
+ }
297
+ }
298
+
287
299
  function persistStepArtifacts(input: {
288
300
  artifactPaths: ArtifactPaths;
289
301
  artifactConfig?: Partial<ArtifactConfig>;
@@ -796,6 +808,7 @@ async function runSingleStepInner(
796
808
  inheritedCapabilityCeiling: ctx.inheritedChildRuntime?.capabilityCeiling,
797
809
  permissionRules: step.permissionRules,
798
810
  sandbox: step.sandbox,
811
+ permissionProfile: step.permissionProfile,
799
812
  }));
800
813
  const contractTools = resolvedTaskToolPlan.explicitToolAllowlist ? resolvedTaskToolPlan.effectiveToolAllowlist : undefined;
801
814
  const contractError = validateImplementationToolContract({
@@ -1109,6 +1122,7 @@ async function runSingleStepInner(
1109
1122
  projectTrusted: step.projectTrusted,
1110
1123
  trustedProjectCwd: step.trustedProjectCwd,
1111
1124
  sandbox: step.sandbox,
1125
+ permissionProfile: step.permissionProfile,
1112
1126
  permissionAuditPath: step.permissionRules && ctx.artifactsDir
1113
1127
  ? path.join(ctx.artifactsDir, "permission-audit", `${ctx.id}-${ctx.flatIndex}.jsonl`)
1114
1128
  : undefined,
@@ -1148,6 +1162,7 @@ async function runSingleStepInner(
1148
1162
  inheritedCapabilityCeiling: ctx.inheritedChildRuntime?.capabilityCeiling,
1149
1163
  permissionRules: step.permissionRules,
1150
1164
  sandbox: step.sandbox,
1165
+ permissionProfile: step.permissionProfile,
1151
1166
  }));
1152
1167
  launchResolvedExtensions = projectLaunchResolvedChildExtensions(toolPlan);
1153
1168
  actualLaunchContractDigest = launchBindingDigest(omitUndefinedProperties({
@@ -1164,6 +1179,7 @@ async function runSingleStepInner(
1164
1179
  inheritGlobalContext: step.inheritGlobalContext,
1165
1180
  inheritSkills: step.inheritSkills,
1166
1181
  sandbox: step.sandbox,
1182
+ permissionProfile: step.permissionProfile,
1167
1183
  skills: step.skills,
1168
1184
  tools: toolPlan.effectiveToolAllowlist,
1169
1185
  ...(toolPlan.excludeTools.length > 0 ? { excludeTools: toolPlan.excludeTools } : {}),
@@ -1535,6 +1551,7 @@ async function runSingleStepInner(
1535
1551
  ...(childSessionName ? { sessionName: childSessionName } : {}),
1536
1552
  context: step.context,
1537
1553
  ...(step.sandbox ? { sandbox: step.sandbox } : {}),
1554
+ ...(step.permissionProfile ? { permissionProfile: step.permissionProfile } : {}),
1538
1555
  ...(step.agentContract ? { agentContract: step.agentContract } : {}),
1539
1556
  launchContractDigest: actualLaunchContractDigest,
1540
1557
  output: outputForSummary,
@@ -2016,6 +2033,7 @@ async function runSubagent(
2016
2033
  }
2017
2034
  }
2018
2035
  const initialSandbox = commonSandboxProfile(initialStatusSteps);
2036
+ const initialPermissionProfile = commonPermissionProfile(initialStatusSteps);
2019
2037
  const initialAgentLabel = initialStatusSteps.length === 1
2020
2038
  ? initialStatusSteps[0]!.agent
2021
2039
  : (config.resultMode ?? (flatSteps.length > 1 ? "chain" : "single")) === "parallel"
@@ -2052,6 +2070,7 @@ async function runSubagent(
2052
2070
  parallelGroups,
2053
2071
  workflowGraph: config.workflowGraph,
2054
2072
  ...(initialSandbox ? { sandbox: initialSandbox } : {}),
2073
+ ...(initialPermissionProfile ? { permissionProfile: initialPermissionProfile } : {}),
2055
2074
  ...(config.launchContractDigest ? { launchContractDigest: config.launchContractDigest } : {}),
2056
2075
  ...(config.launchResolvedExtensions ? { launchResolvedExtensions: config.launchResolvedExtensions } : {}),
2057
2076
  ...(config.capabilityCeiling ? { capabilityCeiling: config.capabilityCeiling } : {}),
@@ -389,6 +389,7 @@ async function runSingleAttempt(
389
389
  : undefined;
390
390
  const permissionRules = resolvePermissionRules(options.permissions, agent.permissions);
391
391
  const sandbox = options.sandbox ?? agent.sandbox;
392
+ const permissionProfile = options.permissionProfile ?? agent.permissionProfile;
392
393
  const permissionAuditPath = permissionRules && options.artifactsDir
393
394
  ? path.join(options.artifactsDir, "permission-audit", `${options.runId}-${options.index ?? 0}.jsonl`)
394
395
  : undefined;
@@ -428,6 +429,7 @@ async function runSingleAttempt(
428
429
  permissionRules,
429
430
  permissionAuditPath,
430
431
  sandbox,
432
+ permissionProfile,
431
433
  projectTrusted: options.projectTrusted,
432
434
  trustedProjectCwd: options.trustedProjectCwd,
433
435
  childWatchdog,
@@ -492,6 +494,7 @@ async function runSingleAttempt(
492
494
  inheritGlobalContext: agent.inheritGlobalContext,
493
495
  inheritSkills: agent.inheritSkills,
494
496
  sandbox,
497
+ permissionProfile,
495
498
  skills: shared.resolvedSkillNames ?? [],
496
499
  tools: toolPlan.effectiveToolAllowlist,
497
500
  ...(toolPlan.excludeTools.length > 0 ? { excludeTools: toolPlan.excludeTools } : {}),
@@ -509,6 +512,7 @@ async function runSingleAttempt(
509
512
  ...(childSessionName ? { sessionName: childSessionName } : {}),
510
513
  ...(options.agentContract ? { agentContract: options.agentContract } : {}),
511
514
  ...(sandbox ? { sandbox } : {}),
515
+ ...(permissionProfile ? { permissionProfile } : {}),
512
516
  launchContractDigest,
513
517
  launchResolvedExtensions,
514
518
  exitCode: 0,
@@ -544,6 +544,16 @@ function sandboxProfileTrustError(agent: AgentConfig, ctx: ExtensionContext, chi
544
544
  return `Agent '${agent.name}' selects sandbox profile '${agent.sandbox}' from project scope, but child cwd '${path.resolve(childCwd)}' does not match the trusted project cwd '${trustedCwd}'. Launch from the trusted project cwd and retry.`;
545
545
  }
546
546
 
547
+ function permissionProfileTrustError(agent: AgentConfig, ctx: ExtensionContext, childCwd: string): string | undefined {
548
+ if (!agent.permissionProfile || (agent.source !== "project" && agent.override?.scope !== "project")) return undefined;
549
+ const trustedCwd = trustedProjectCwd(ctx);
550
+ if (trustedCwd && trustedCwd === path.resolve(childCwd)) return undefined;
551
+ if (!trustedCwd) {
552
+ return `Agent '${agent.name}' selects permission profile '${agent.permissionProfile}' from project scope, but the project is not trusted. Trust the project and retry.`;
553
+ }
554
+ return `Agent '${agent.name}' selects permission profile '${agent.permissionProfile}' from project scope, but child cwd '${path.resolve(childCwd)}' does not match the trusted project cwd '${trustedCwd}'. Launch from the trusted project cwd and retry.`;
555
+ }
556
+
547
557
  function removeForegroundControlIfIdle(state: SubagentState, runId: string): boolean {
548
558
  const control = state.foregroundControls.get(runId);
549
559
  if (control && (!foregroundSchedulingSettled(control) || (control.activeChildren?.size ?? 0) > 0)) return false;
@@ -792,6 +802,7 @@ function rememberForegroundRun(state: SubagentState, input: { runId: string; mod
792
802
  ...(result.acceptance ? { acceptance: result.acceptance } : {}),
793
803
  ...(Object.keys(resumeContract).length ? { resumeContract } : {}),
794
804
  ...(result.sandbox ? { sandbox: result.sandbox } : {}),
805
+ ...(result.permissionProfile ? { permissionProfile: result.permissionProfile } : {}),
795
806
  ...(result.launchContractDigest ? { launchContractDigest: result.launchContractDigest } : {}),
796
807
  ...(input.extensionBindings ? { extensionBindings: input.extensionBindings } : {}),
797
808
  ...(result.launchResolvedExtensions ? { launchResolvedExtensions: result.launchResolvedExtensions } : {}),
@@ -874,6 +885,7 @@ function updateRememberedForegroundChild(state: SubagentState, input: { runId: s
874
885
  ...(input.result.detachedReason ? { detachedReason: input.result.detachedReason } : {}),
875
886
  ...(input.result.acceptance ? { acceptance: input.result.acceptance } : {}),
876
887
  ...(input.result.sandbox ? { sandbox: input.result.sandbox } : {}),
888
+ ...(input.result.permissionProfile ? { permissionProfile: input.result.permissionProfile } : {}),
877
889
  ...(input.result.launchContractDigest ? { launchContractDigest: input.result.launchContractDigest } : {}),
878
890
  ...(input.result.launchResolvedExtensions ? { launchResolvedExtensions: input.result.launchResolvedExtensions } : {}),
879
891
  ...(input.result.runtimeAcknowledgedExtensions ? { runtimeAcknowledgedExtensions: input.result.runtimeAcknowledgedExtensions } : {}),
@@ -913,7 +925,7 @@ function updateRememberedForegroundChild(state: SubagentState, input: { runId: s
913
925
  });
914
926
  }
915
927
 
916
- function resolveForegroundResumeTarget(params: SubagentParamsLike, state: SubagentState, options: { exactOnly?: boolean } = {}): { runId: string; mode: SubagentRunMode; state: "complete"; agent: string; index: number; cwd: string; sessionFile: string; model?: string; thinking?: string; sandbox?: string; launchContractDigest?: string; resumeContract?: ForegroundResumeChild["resumeContract"]; extensionBindings?: ExtensionBindings; capabilityCeiling?: ResolvedSubagentCapabilityCeiling } | undefined {
928
+ function resolveForegroundResumeTarget(params: SubagentParamsLike, state: SubagentState, options: { exactOnly?: boolean } = {}): { runId: string; mode: SubagentRunMode; state: "complete"; agent: string; index: number; cwd: string; sessionFile: string; model?: string; thinking?: string; sandbox?: string; permissionProfile?: string; launchContractDigest?: string; resumeContract?: ForegroundResumeChild["resumeContract"]; extensionBindings?: ExtensionBindings; capabilityCeiling?: ResolvedSubagentCapabilityCeiling } | undefined {
917
929
  const requested = (params.id ?? params.runId)?.trim();
918
930
  if (!requested || !state.foregroundRuns?.size || !state.currentSessionId) return undefined;
919
931
  const direct = state.foregroundRuns.get(requested);
@@ -944,6 +956,7 @@ function resolveForegroundResumeTarget(params: SubagentParamsLike, state: Subage
944
956
  ...(child.model ? { model: child.model } : {}),
945
957
  ...(child.thinking ? { thinking: child.thinking } : {}),
946
958
  ...(child.sandbox ? { sandbox: child.sandbox } : {}),
959
+ ...(child.permissionProfile ? { permissionProfile: child.permissionProfile } : {}),
947
960
  ...(child.launchContractDigest ? { launchContractDigest: child.launchContractDigest } : {}),
948
961
  ...(child.resumeContract ? { resumeContract: child.resumeContract } : {}),
949
962
  ...(child.extensionBindings ? { extensionBindings: normalizeExtensionBindings(child.extensionBindings)!.value } : {}),
@@ -965,6 +978,7 @@ type NestedResumeSourceTarget = {
965
978
  model?: string;
966
979
  thinking?: AgentConfig["thinking"];
967
980
  sandbox?: string;
981
+ permissionProfile?: string;
968
982
  launchContractDigest?: string;
969
983
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
970
984
  recoveryDescriptor?: SteeringRecoveryDescriptor;
@@ -3269,6 +3283,12 @@ async function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): Pro
3269
3283
  if (sandboxTrustError) {
3270
3284
  return { content: [{ type: "text", text: sandboxTrustError }], isError: true, details: { mode: "single" as const, results: [] } };
3271
3285
  }
3286
+ const permissionProfileTrustErrorForAgent = params.worktree === true
3287
+ ? permissionProfileTrustError(a, ctx, path.join(effectiveCwd, ".pi-subagents-worktree"))
3288
+ : permissionProfileTrustError(a, ctx, effectiveCwd);
3289
+ if (permissionProfileTrustErrorForAgent) {
3290
+ return { content: [{ type: "text", text: permissionProfileTrustErrorForAgent }], isError: true, details: { mode: "single" as const, results: [] } };
3291
+ }
3272
3292
  const rawOutput = params.output !== undefined ? params.output : a.output;
3273
3293
  const effectiveOutput = normalizeSingleOutputOverride(rawOutput, a.output);
3274
3294
  const effectiveOutputMode = params.outputMode ?? a.outputMode ?? "inline";
@@ -3782,6 +3802,11 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
3782
3802
  if (worktreeSetup) cleanupWorktrees(worktreeSetup);
3783
3803
  return { content: [{ type: "text", text: sandboxTrustError }], isError: true, details: { mode: "single", results: [] } };
3784
3804
  }
3805
+ const permissionProfileTrustErrorForLaunch = permissionProfileTrustError(agentConfig, ctx, singleCwd);
3806
+ if (permissionProfileTrustErrorForLaunch) {
3807
+ if (worktreeSetup) cleanupWorktrees(worktreeSetup);
3808
+ return { content: [{ type: "text", text: permissionProfileTrustErrorForLaunch }], isError: true, details: { mode: "single", results: [] } };
3809
+ }
3785
3810
 
3786
3811
  const authoredTask = task;
3787
3812
  if (shouldForkAgent(contextPolicy, params.agent!)) {
@@ -18,6 +18,7 @@ import {
18
18
  type RunFanoutBudgetDescriptor,
19
19
  } from "../../shared/types.ts";
20
20
  import { SUBAGENT_SANDBOX_PROFILE_ENV, SUBAGENT_SANDBOX_PROJECT_TRUST_ENV } from "../../shared/sandbox-profile.ts";
21
+ import { SUBAGENT_PERMISSION_PROFILE_ENV, SUBAGENT_PERMISSION_PROFILE_PINNED_ENV } from "../../shared/permission-profile.ts";
21
22
  import type { NestedPathEntry } from "./nested-path.ts";
22
23
  import type { McpRuntimeSnapshotHost } from "./mcp-direct-tool-allowlist.ts";
23
24
  import type { PermissionRules } from "./permissions.ts";
@@ -120,6 +121,8 @@ export interface BuildInProcessChildLaunchInput {
120
121
  runtimeSnapshotHost?: McpRuntimeSnapshotHost;
121
122
  /** A validated global pi-sandbox profile selected by the agent definition. */
122
123
  sandbox?: string;
124
+ /** A validated global pi-permission-system profile selected by the agent definition. */
125
+ permissionProfile?: string;
123
126
  /** Parent-authoritative trust state for profile-aware project config merging. */
124
127
  projectTrusted?: boolean;
125
128
  /** Exact trusted parent cwd; profile project config applies only when the child cwd matches it. */
@@ -211,6 +214,7 @@ export function buildInProcessChildLaunch(input: BuildInProcessChildLaunchInput)
211
214
  permissionRules: input.permissionRules,
212
215
  runtimeSnapshotHost: input.runtimeSnapshotHost,
213
216
  sandbox: input.sandbox,
217
+ permissionProfile: input.permissionProfile,
214
218
  });
215
219
 
216
220
  // A selected profile is validated by resolvePiLaunchToolPlan; the child
@@ -235,6 +239,37 @@ export function buildInProcessChildLaunch(input: BuildInProcessChildLaunchInput)
235
239
  : undefined;
236
240
  if (sandboxAckPath) fs.mkdirSync(path.dirname(sandboxAckPath), { recursive: true, mode: 0o700 });
237
241
 
242
+ // A selected permission profile travels as a bare validated name (the rules
243
+ // live in the child's global pi-permission-system config). The key is
244
+ // transient like the sandbox keys: restored on the host once the child
245
+ // session exists.
246
+ const permissionProfileEnv: Record<string, string | undefined> | undefined =
247
+ input.permissionProfile !== undefined
248
+ ? { [SUBAGENT_PERMISSION_PROFILE_ENV]: input.permissionProfile }
249
+ : undefined;
250
+ const childEnv: Record<string, string | undefined> | undefined =
251
+ sandboxEnv !== undefined || permissionProfileEnv !== undefined
252
+ ? { ...(sandboxEnv ?? {}), ...(permissionProfileEnv ?? {}) }
253
+ : undefined;
254
+ // The profile key is pinned for every launch, `undefined` included: a child
255
+ // that declares no profile must not inherit the host session's role
256
+ // selection, and one that declares a profile must not be overridden by it
257
+ // (the launcher env wins inside pi-permission-system). It is kept out of
258
+ // `childEnv` so a plain in-process child does not also start receiving the
259
+ // binding and MCP values that only a runner-hosted child used to get.
260
+ const profilePin: Record<string, string | undefined> = {
261
+ [SUBAGENT_PERMISSION_PROFILE_ENV]: input.permissionProfile,
262
+ // Present for every child launch: it is what tells pi-permission-system
263
+ // this selection is authoritative for the child (see the constant).
264
+ [SUBAGENT_PERMISSION_PROFILE_PINNED_ENV]: "1",
265
+ };
266
+ const transientProcessEnv = [
267
+ ...new Set([
268
+ ...(childEnv ? Object.keys(childEnv) : []),
269
+ ...Object.keys(profilePin),
270
+ ]),
271
+ ];
272
+
238
273
  const inherited = input.inherited;
239
274
  const fanout = toolPlan.fanoutAuthorized;
240
275
  const inheritedRoute = inherited?.nestedRoute;
@@ -337,8 +372,10 @@ export function buildInProcessChildLaunch(input: BuildInProcessChildLaunchInput)
337
372
  extensionPaths,
338
373
  ambientExtensions,
339
374
  hooks: createChildHooks(config),
340
- ...(input.host === "runner" || sandboxEnv ? { processEnv: childProcessEnv(input, toolPlan, sandboxEnv) } : {}),
341
- ...(sandboxEnv ? { transientProcessEnv: Object.keys(sandboxEnv) } : {}),
375
+ ...(input.host === "runner" || childEnv
376
+ ? { processEnv: { ...childProcessEnv(input, toolPlan, childEnv), ...profilePin } }
377
+ : { processEnv: profilePin }),
378
+ transientProcessEnv,
342
379
  runtime: config,
343
380
  noSkills: !input.inheritSkills,
344
381
  noContextFiles: !input.inheritProjectContext,
@@ -21,6 +21,7 @@ import {
21
21
  import { THINKING_LEVELS } from "../../shared/model-info.ts";
22
22
  import { getAgentDir } from "../../shared/utils.ts";
23
23
  import { validateSandboxProfileName } from "../../shared/sandbox-profile.ts";
24
+ import { validatePermissionProfileName } from "../../shared/permission-profile.ts";
24
25
  import type { PermissionRules } from "./permissions.ts";
25
26
  import {
26
27
  capabilityCeilingAgentRestrictionSources,
@@ -158,6 +159,8 @@ export interface ResolvePiLaunchToolPlanInput {
158
159
  runtimeSnapshotHost?: McpRuntimeSnapshotHost;
159
160
  /** A validated global pi-sandbox profile selected by the agent definition. */
160
161
  sandbox?: string;
162
+ /** A validated global pi-permission-system profile selected by the agent definition. */
163
+ permissionProfile?: string;
161
164
  }
162
165
 
163
166
  export interface PiLaunchToolPlan {
@@ -482,6 +485,24 @@ export function resolvePiLaunchToolPlan(
482
485
  if (sandboxProfile && capabilityCeiling?.denyExtensions) {
483
486
  throw new Error(`Sandbox profile '${sandboxProfile}' requires the pi-sandbox child extension, but this launch denies child extensions.`);
484
487
  }
488
+ const permissionProfile = input.permissionProfile === undefined
489
+ ? undefined
490
+ : validatePermissionProfileName(input.permissionProfile, "permission profile");
491
+ if (permissionProfile && capabilityCeiling?.denyExtensions) {
492
+ throw new Error(`Permission profile '${permissionProfile}' requires the pi-permission-system child extension, but this launch denies child extensions.`);
493
+ }
494
+ // A permission-profile-only agent has no native `permissionRules` yet still
495
+ // needs the permission system in the child to resolve the profile: without
496
+ // it the selection would silently degrade to no policy at all. Resolve the
497
+ // extension eagerly for this path and fail the launch when the package is
498
+ // missing (the rules-only path keeps its soft resolution as before).
499
+ const permSystemExtForProfile = permissionProfile !== undefined && permSystemExt === undefined
500
+ ? resolvePermissionSystemExtension()
501
+ : undefined;
502
+ if (permissionProfile !== undefined && permSystemExt === undefined && permSystemExtForProfile === undefined) {
503
+ throw new Error(`Permission profile '${permissionProfile}' cannot be enabled: pi-permission-system is not installed; cannot launch a child with a permission profile.`);
504
+ }
505
+ const effectivePermSystemExt = permSystemExt ?? permSystemExtForProfile;
485
506
  let sandboxExtension: string | undefined;
486
507
  if (sandboxProfile) {
487
508
  try {
@@ -497,7 +518,7 @@ export function resolvePiLaunchToolPlan(
497
518
  PROMPT_RUNTIME_EXTENSION_PATH,
498
519
  ...fastModeExtensions,
499
520
  ...(fanoutAuthorized ? [FANOUT_CHILD_EXTENSION_PATH] : []),
500
- ...(permSystemExt ? [permSystemExt] : []),
521
+ ...(effectivePermSystemExt ? [effectivePermSystemExt] : []),
501
522
  ...(sandboxExtension ? [sandboxExtension, SANDBOX_PROFILE_GUARD_EXTENSION_PATH] : []),
502
523
  ];
503
524
  const disableAmbientExtensions =
@@ -1,3 +1,9 @@
1
+ import { SUBAGENT_PERMISSION_PROFILE_ENV, SUBAGENT_PERMISSION_PROFILE_PINNED_ENV } from "../../shared/permission-profile.ts";
2
+ import {
3
+ SUBAGENT_SANDBOX_PROFILE_ENV,
4
+ SUBAGENT_SANDBOX_PROJECT_TRUST_ENV,
5
+ } from "../../shared/sandbox-profile.ts";
6
+
1
7
  export const PI_SUBAGENT_EXTENSION_BINDINGS_ENV = "PI_SUBAGENT_EXTENSION_BINDINGS";
2
8
  export const MAX_EXTENSION_BINDING_NAMESPACES = 16;
3
9
  export const MAX_EXTENSION_BINDINGS_BYTES = 16 * 1024;
@@ -76,3 +82,22 @@ export function omitExtensionBindingsEnv(env: NodeJS.ProcessEnv): NodeJS.Process
76
82
  const { [PI_SUBAGENT_EXTENSION_BINDINGS_ENV]: _extensionBindings, ...sanitized } = env;
77
83
  return sanitized;
78
84
  }
85
+
86
+ /**
87
+ * Drop launcher-owned profile selections from an inherited environment.
88
+ *
89
+ * A runner process must not carry the host session's role selection into the
90
+ * children it launches: each child's own selection is pinned by the child
91
+ * launch, so anything inherited here would silently apply to every step that
92
+ * does not declare one.
93
+ */
94
+ export function omitInheritedProfileEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
95
+ const {
96
+ [SUBAGENT_PERMISSION_PROFILE_ENV]: _permissionProfile,
97
+ [SUBAGENT_PERMISSION_PROFILE_PINNED_ENV]: _permissionProfilePinned,
98
+ [SUBAGENT_SANDBOX_PROFILE_ENV]: _sandboxProfile,
99
+ [SUBAGENT_SANDBOX_PROJECT_TRUST_ENV]: _sandboxTrust,
100
+ ...sanitized
101
+ } = env;
102
+ return sanitized;
103
+ }
@@ -21,6 +21,7 @@ import { writeAtomicJson } from "../../shared/atomic-json.ts";
21
21
  import { sanitizeProcessTerminal } from "../background/process-terminal.ts";
22
22
  import { THINKING_LEVELS } from "../../shared/model-info.ts";
23
23
  import { validateSandboxProfileName } from "../../shared/sandbox-profile.ts";
24
+ import { validatePermissionProfileName } from "../../shared/permission-profile.ts";
24
25
 
25
26
  export const NESTED_EVENTS_DIR = path.join(TEMP_ROOT_DIR, "nested-subagent-events");
26
27
  const ROUTE_FILE = "route.json";
@@ -310,6 +311,14 @@ function sandboxProfileValue(value: unknown): string | undefined {
310
311
  }
311
312
  }
312
313
 
314
+ function permissionProfileValue(value: unknown): string | undefined {
315
+ try {
316
+ return validatePermissionProfileName(value);
317
+ } catch {
318
+ return undefined;
319
+ }
320
+ }
321
+
313
322
  function sanitizeStep(input: unknown, depth: number): NestedStepSummary | undefined {
314
323
  if (!input || typeof input !== "object") return undefined;
315
324
  const raw = input as Record<string, unknown>;
@@ -321,6 +330,7 @@ function sanitizeStep(input: unknown, depth: number): NestedStepSummary | undefi
321
330
  const model = stringValue(raw.model);
322
331
  const thinking = THINKING_LEVELS.find((level) => level === raw.thinking);
323
332
  const sandbox = sandboxProfileValue(raw.sandbox);
333
+ const permissionProfile = permissionProfileValue(raw.permissionProfile);
324
334
  return {
325
335
  agent,
326
336
  status,
@@ -328,6 +338,7 @@ function sanitizeStep(input: unknown, depth: number): NestedStepSummary | undefi
328
338
  ...(thinking ? { thinking } : {}),
329
339
  ...(stringValue(raw.sessionName, 256) ? { sessionName: stringValue(raw.sessionName, 256) } : {}),
330
340
  ...(sandbox ? { sandbox } : {}),
341
+ ...(permissionProfile ? { permissionProfile } : {}),
331
342
  ...(stringValue(raw.sessionFile, 2048) ? { sessionFile: stringValue(raw.sessionFile, 2048) } : {}),
332
343
  ...(raw.activityState === "active_long_running" || raw.activityState === "needs_attention" ? { activityState: raw.activityState } : {}),
333
344
  ...(clampNumber(raw.lastActivityAt) !== undefined ? { lastActivityAt: clampNumber(raw.lastActivityAt) } : {}),
@@ -361,6 +372,7 @@ export function sanitizeSummary(input: unknown, depth = 0): NestedRunSummary | u
361
372
  const totalTokens = sanitizeTokenUsage(raw.totalTokens);
362
373
  const totalCost = sanitizeCost(raw.totalCost);
363
374
  const sandbox = sandboxProfileValue(raw.sandbox);
375
+ const permissionProfile = permissionProfileValue(raw.permissionProfile);
364
376
  return {
365
377
  id: raw.id,
366
378
  parentRunId: raw.parentRunId,
@@ -385,6 +397,7 @@ export function sanitizeSummary(input: unknown, depth = 0): NestedRunSummary | u
385
397
  ...(raw.mode === "single" || raw.mode === "parallel" || raw.mode === "chain" ? { mode: raw.mode } : {}),
386
398
  ...(stringValue(raw.agent, 128) ? { agent: stringValue(raw.agent, 128) } : {}),
387
399
  ...(sandbox ? { sandbox } : {}),
400
+ ...(permissionProfile ? { permissionProfile } : {}),
388
401
  ...(Array.isArray(raw.agents) ? { agents: raw.agents.map((agent) => stringValue(agent, 128)).filter((agent): agent is string => Boolean(agent)).slice(0, MAX_STEPS) } : {}),
389
402
 
390
403
  ...(clampNumber(raw.currentStep) !== undefined ? { currentStep: clampNumber(raw.currentStep) } : {}),
@@ -54,6 +54,7 @@ export interface RunnerSubagentStep {
54
54
  mutationTools?: string[];
55
55
  completionGuard?: boolean;
56
56
  sandbox?: string;
57
+ permissionProfile?: string;
57
58
  systemPrompt?: string | null;
58
59
  systemPromptMode?: "append" | "replace";
59
60
  inheritProjectContext: boolean;
@@ -72,6 +72,7 @@ export function projectAgentDefinition(agent: AgentConfig): Record<string, unkno
72
72
  completionGuard: agent.completionGuard,
73
73
  toolBudget: agent.toolBudget,
74
74
  sandbox: agent.sandbox,
75
+ permissionProfile: agent.permissionProfile,
75
76
  memory: agent.memory,
76
77
  };
77
78
  }
@@ -102,6 +103,7 @@ export interface LaunchBindingInput {
102
103
  outputPath?: string;
103
104
  outputMode?: string;
104
105
  sandbox?: string;
106
+ permissionProfile?: string;
105
107
  structuredOutputSchema?: unknown;
106
108
  extensionBindings?: ExtensionBindings;
107
109
  }
@@ -131,6 +133,7 @@ export function projectLaunchBinding(input: LaunchBindingInput): Record<string,
131
133
  outputPath: input.outputPath,
132
134
  outputMode: input.outputMode,
133
135
  sandbox: input.sandbox,
136
+ permissionProfile: input.permissionProfile,
134
137
  structuredOutputSchema: input.structuredOutputSchema,
135
138
  extensionBindings: input.extensionBindings,
136
139
  };