@ganglion/xacpx 0.24.2-beta.0 → 0.24.3-beta.1

package/dist/adapters/claude-settings-policy.d.ts

@@ -6,7 +6,19 @@ export interface ClaudeExecutionSettings {
     settingsPolicy?: ClaudeSettingsPolicy;
     model?: string;
 }
-interface ResolveClaudeSpawnEnvironmentOptions {
+/**
+ * Mutation provenance for one Claude spawn-env resolution: which keys the
+ * resolver explicitly wrote or removed, independent of whether the value
+ * happens to equal the parent. A same-value intentional write (e.g. an
+ * explicit session model matching an inherited ANTHROPIC_MODEL) must still
+ * ride the Runtime overlay above persisted session env — a pure value diff
+ * cannot recover that intent.
+ */
+export interface ClaudeEnvironmentProvenance {
+    setKeys: Set<string>;
+    clearedKeys: Set<string>;
+}
+export interface ResolveClaudeSpawnEnvironmentOptions {
     baseEnv?: NodeJS.ProcessEnv;
     homeDir?: string;
     platform?: NodeJS.Platform;
@@ -22,6 +34,32 @@ interface ResolveClaudeSpawnEnvironmentOptions {
  * the narrow provider/model fields when a third-party marker is present.
  */
 export declare function resolveClaudeSpawnEnvironment(input: ClaudeExecutionSettings, options?: ResolveClaudeSpawnEnvironmentOptions): NodeJS.ProcessEnv | undefined;
+/**
+ * Resolves the Runtime `agentProcessEnv` overlay in a single pass: the
+ * intentional overlay for acpx, derived with the resolver's own mutation
+ * provenance (not a value diff — a same-value intentional write still rides
+ * above persisted session env). `undefined` when the resolver yields no env.
+ */
+export declare function resolveClaudeAgentProcessEnv(input: ClaudeExecutionSettings, options?: ResolveClaudeSpawnEnvironmentOptions): Record<string, string> | undefined;
+/**
+ * Narrows a fully-resolved Claude spawn env (see
+ * resolveClaudeSpawnEnvironment) to the intentional Runtime overlay for
+ * acpx `agentProcessEnv`. A key crosses the boundary when the resolver
+ * explicitly wrote it (provenance, when provided) or when its value
+ * differs from the base — the inherited parent remainder stays out, so
+ * persisted `sessionOptions.env` keeps its upstream precedence (protected
+ * auth > agentProcessEnv > persisted session env > inherited parent env)
+ * instead of being shadowed by a re-elevated copy of the parent. A
+ * same-value intentional write (e.g. an explicit session model matching
+ * an inherited ANTHROPIC_MODEL) still rides the overlay: without
+ * provenance a pure value diff cannot tell it apart from inheritance.
+ *
+ * `resolved === undefined` (first-party provider-only: nothing intentional)
+ * narrows to `undefined`, as does an empty delta. `baseEnv` must be the
+ * same base the resolver derived from (defaults to process.env, matching
+ * the resolver default).
+ */
+export declare function narrowToAgentProcessEnvOverlay(resolved: NodeJS.ProcessEnv | undefined, baseEnv?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, provenance?: ClaudeEnvironmentProvenance): Record<string, string> | undefined;
 declare function linkClaudeSessionState(sourceConfigDir: string, profileDir: string, platform: NodeJS.Platform): void;
 declare function sanitizeClaudeModelConfig(settings: Record<string, unknown> | undefined): Record<string, unknown>;
 declare function sanitizeClaudeSettings(settings: Record<string, unknown> | undefined, includeModel: boolean): Record<string, unknown>;