@highflame/policy 2.0.9 → 2.1.0

package/_schemas/overwatch/schema.cedarschema

@@ -84,8 +84,8 @@ action process_prompt appliesTo {
     user_email: String,             // User identifier
 
     // Workspace
-    cwd: String,                   // Current working directory
-    workspace_root: String,        // Workspace/repository root
+    cwd?: String,                   // Current working directory
+    workspace_root?: String,        // Workspace/repository root
 
     // Threat Detection
     threat_count: Long,             // Total threats detected
@@ -94,24 +94,27 @@ action process_prompt appliesTo {
     yara_threats: Set<String>,      // YARA rule names
     max_threat_severity: Long,      // Numeric severity (0-4)
     contains_secrets: Bool,         // Whether secrets detected
-    prompt_text: String,           // Same as content (legacy)
-    response_content: String,      // Response content (if available)
+    prompt_text?: String,           // Same as content (legacy)
+    response_content?: String,      // Response content (if available)
 
     // Trust/Safety Scores (0-100, from Javelin/Lakera/LlamaGuard classifiers)
-    violence_score: Long,          // Violence content detection score
-    weapons_score: Long,           // Weapons content detection score
-    hate_speech_score: Long,       // Hate speech detection score
-    crime_score: Long,             // Criminal content detection score
-    sexual_score: Long,            // Sexual content detection score
-    profanity_score: Long,         // Profanity detection score
+    // Required: content safety classifiers always run for prompt processing
+    violence_score: Long,           // Violence content detection score
+    weapons_score: Long,            // Weapons content detection score
+    hate_speech_score: Long,        // Hate speech detection score
+    crime_score: Long,              // Criminal content detection score
+    sexual_score: Long,             // Sexual content detection score
+    profanity_score: Long,          // Profanity detection score
 
     // Detector Confidence Scores (0-100, ML classifier confidence)
-    pii_confidence: Long,          // PII detection confidence
-    injection_confidence: Long,    // Prompt injection confidence
-    jailbreak_confidence: Long,    // Jailbreak detection confidence
+    // Required: ML classifiers always run for prompt processing
+    pii_confidence: Long,           // PII detection confidence
+    injection_confidence: Long,     // Prompt injection confidence
+    jailbreak_confidence: Long,     // Jailbreak detection confidence
 
     // Agent Security (0-100)
-    indirect_injection_score: Long, // Indirect prompt injection risk
+    // Required: agent security scanners always run for prompt processing
+    indirect_injection_score: Long,  // Indirect prompt injection risk
   },
 };
 
@@ -127,46 +130,50 @@ action call_tool appliesTo {
     user_email: String,             // User identifier
 
     // Tool & MCP
-    tool_name: String,             // Normalized tool name ("shell", "read_file", etc.)
-    mcp_server: String,            // MCP server name
-    mcp_tool: String,              // MCP tool name
+    tool_name?: String,             // Normalized tool name ("shell", "read_file", etc.)
+    mcp_server?: String,            // MCP server name
+    mcp_tool?: String,              // MCP tool name
 
     // File & Path
-    path: String,                  // File path (if file operation)
+    path?: String,                  // File path (if file operation)
 
     // Workspace
-    cwd: String,
-    workspace_root: String,
-
-    // Threat Detection
-    threat_count: Long,
-    highest_severity: String,
-    threat_categories: Set<String>,
-    yara_threats: Set<String>,
-    max_threat_severity: Long,
-    contains_secrets: Bool,
-    response_content: String,
+    cwd?: String,
+    workspace_root?: String,
+
+    // Threat Detection (optional: scanning may not have run before tool call)
+    threat_count?: Long,
+    highest_severity?: String,
+    threat_categories?: Set<String>,
+    yara_threats?: Set<String>,
+    max_threat_severity?: Long,
+    contains_secrets?: Bool,
+    response_content?: String,
 
     // Trust/Safety Scores (0-100, from Javelin/Lakera/LlamaGuard classifiers)
-    violence_score: Long,          // Violence content detection score
-    weapons_score: Long,           // Weapons content detection score
-    hate_speech_score: Long,       // Hate speech detection score
-    crime_score: Long,             // Criminal content detection score
-    sexual_score: Long,            // Sexual content detection score
-    profanity_score: Long,         // Profanity detection score
+    // Optional: only present when trust/safety classifiers have run
+    violence_score?: Long,          // Violence content detection score
+    weapons_score?: Long,           // Weapons content detection score
+    hate_speech_score?: Long,       // Hate speech detection score
+    crime_score?: Long,             // Criminal content detection score
+    sexual_score?: Long,            // Sexual content detection score
+    profanity_score?: Long,         // Profanity detection score
 
     // Detector Confidence Scores (0-100, ML classifier confidence)
-    pii_confidence: Long,          // PII detection confidence
-    injection_confidence: Long,    // Prompt injection confidence
-    jailbreak_confidence: Long,    // Jailbreak detection confidence
+    // Optional: only present when ML classifiers have run
+    pii_confidence?: Long,          // PII detection confidence
+    injection_confidence?: Long,    // Prompt injection confidence
+    jailbreak_confidence?: Long,    // Jailbreak detection confidence
 
     // Agent Security (0-100)
-    tool_poisoning_score: Long,    // Tool description manipulation risk
-    rug_pull_score: Long,          // Tool behavior mismatch risk
-    indirect_injection_score: Long, // Indirect prompt injection risk
+    // Optional: only present when agent security scanners have run
+    tool_poisoning_score?: Long,    // Tool description manipulation risk
+    rug_pull_score?: Long,          // Tool behavior mismatch risk
+    indirect_injection_score?: Long, // Indirect prompt injection risk
 
     // MCP Trust
-    mcp_server_verified: Bool,     // Whether server is from verified registry
+    // Optional: only present when MCP server verification has run
+    mcp_server_verified?: Bool,     // Whether server is from verified registry
   },
 };
 
@@ -175,23 +182,25 @@ action connect_server appliesTo {
   principal: [User, Agent],
   resource: [Server],
   context: {
-    content: String,
+    content?: String,               // No content to scan when connecting
     source: String,
     event: String,
     user_email: String,
-    mcp_server: String,
-    threat_count: Long,
-    highest_severity: String,
-    threat_categories: Set<String>,
-    max_threat_severity: Long,
+    mcp_server?: String,
+    threat_count?: Long,            // Threat scanning may not run for connections
+    highest_severity?: String,
+    threat_categories?: Set<String>,
+    max_threat_severity?: Long,
 
     // Agent Security (0-100)
-    tool_poisoning_score: Long,    // Tool description manipulation risk
-    rug_pull_score: Long,          // Tool behavior mismatch risk
-    indirect_injection_score: Long, // Indirect prompt injection risk
+    // Optional: only present when agent security scanners have run
+    tool_poisoning_score?: Long,    // Tool description manipulation risk
+    rug_pull_score?: Long,          // Tool behavior mismatch risk
+    indirect_injection_score?: Long, // Indirect prompt injection risk
 
     // MCP Trust
-    mcp_server_verified: Bool,     // Whether server is from verified registry
+    // Optional: only present when MCP server verification has run
+    mcp_server_verified?: Bool,     // Whether server is from verified registry
   },
 };
 
@@ -204,14 +213,14 @@ action read_file appliesTo {
     source: String,
     event: String,
     user_email: String,
-    path: String,
-    cwd: String,
-    workspace_root: String,
-    threat_count: Long,
-    highest_severity: String,
-    threat_categories: Set<String>,
-    max_threat_severity: Long,
-    contains_secrets: Bool,
+    path?: String,
+    cwd?: String,
+    workspace_root?: String,
+    threat_count?: Long,             // Threat scanning may not have run
+    highest_severity?: String,
+    threat_categories?: Set<String>,
+    max_threat_severity?: Long,
+    contains_secrets?: Bool,
   },
 };
 
@@ -224,14 +233,14 @@ action write_file appliesTo {
     source: String,
     event: String,
     user_email: String,
-    path: String,
-    cwd: String,
-    workspace_root: String,
-    threat_count: Long,
-    highest_severity: String,
-    threat_categories: Set<String>,
-    max_threat_severity: Long,
-    contains_secrets: Bool,
+    path?: String,
+    cwd?: String,
+    workspace_root?: String,
+    threat_count?: Long,             // Threat scanning may not have run
+    highest_severity?: String,
+    threat_categories?: Set<String>,
+    max_threat_severity?: Long,
+    contains_secrets?: Bool,
   },
 };
 

package/dist/builder.d.ts

@@ -33,6 +33,7 @@
 import { EntityType, EntityUID } from './entities.gen.js';
 import { ActionType } from './actions.gen.js';
 import { type PolicyAnnotations, type CustomAnnotations, type PolicySeverity } from './annotations.js';
+import type { ServiceContext } from './service-schemas.gen.js';
 /**
  * Policy effect - permit or forbid
  */
@@ -52,16 +53,75 @@ export interface PolicyCondition {
     /** The value to compare against */
     value: string | number | boolean | string[];
 }
+/** context.field <op> value */
+export interface ConditionComparison {
+    kind: 'comparison';
+    field: string;
+    operator: ConditionOperator;
+    value: string | number | boolean | string[];
+}
+/** context.field.contains(value) */
+export interface ConditionContains {
+    kind: 'contains';
+    field: string;
+    value: string | number | boolean;
+}
+/** context.field like "pattern" */
+export interface ConditionLike {
+    kind: 'like';
+    field: string;
+    pattern: string;
+}
+/** context has field (existence check) */
+export interface ConditionHas {
+    kind: 'has';
+    field: string;
+}
+/** N-ary AND (flattened from binary && chains) */
+export interface ConditionAnd {
+    kind: 'and';
+    children: ConditionExpression[];
+}
+/** N-ary OR (flattened from binary || chains) */
+export interface ConditionOr {
+    kind: 'or';
+    children: ConditionExpression[];
+}
+/** Unary NOT */
+export interface ConditionNot {
+    kind: 'not';
+    child: ConditionExpression;
+}
+/** Fallback for expressions that cannot be decomposed */
+export interface ConditionRaw {
+    kind: 'raw';
+    text: string;
+}
+/**
+ * Recursive condition expression tree parsed from Cedar JSON AST.
+ * Used by Studio UI for visual condition block rendering and by
+ * explainDecision() for per-condition evaluation with actual values.
+ */
+export type ConditionExpression = ConditionComparison | ConditionContains | ConditionLike | ConditionHas | ConditionAnd | ConditionOr | ConditionNot | ConditionRaw;
 /**
  * Principal or resource entity constraint.
  * Used to specify type-only constraints (any entity of type) or
  * specific entity constraints (type + id).
+ *
+ * The `operator` field controls Cedar scope syntax:
+ * - `'eq'` (default): `resource == Type::"id"` — exact match
+ * - `'in'`: `resource in Type::"id"` — hierarchy match (descendants)
+ *
+ * Use `'in'` for container resource types (Account, Project, App) to match
+ * all descendant entities. Use `'eq'` for leaf types (Session, Tool).
  */
 export interface PolicyEntity {
     /** Entity type (e.g., "Agent", "Tool", "FilePath", "User") */
     type: string;
     /** Optional specific entity ID. If omitted, matches any entity of this type. */
     id?: string;
+    /** Scope operator: 'eq' for exact match (==), 'in' for hierarchy match (in). Default: 'eq' */
+    operator?: 'eq' | 'in';
 }
 /** Alias for PolicyEntity when used as principal constraint */
 export type PolicyPrincipal = PolicyEntity;
@@ -129,6 +189,8 @@ export interface PolicyRule {
     conditions: PolicyCondition[];
     /** Raw condition string (for advanced/complex conditions) */
     rawCondition?: string;
+    /** Recursive condition expression tree from Cedar JSON AST */
+    conditionExpression?: ConditionExpression;
     /** Whether this rule is active - NOT embedded in Cedar (runtime state) */
     enabled: boolean;
     /** Display/evaluation order - NOT embedded in Cedar (runtime state) */
@@ -163,8 +225,11 @@ export declare class Policy {
     /**
      * Convert to Cedar policy text.
      * Uses proper Cedar @annotation syntax.
+     *
+     * @param optionalFields - Set of context field names that are optional and need `context has` guards.
+     *                         Use `getOptionalFields()` to compute this from service context metadata.
      */
-    toCedar(): string;
+    toCedar(optionalFields?: Set<string>): string;
     /**
      * Get JSON representation for storage
      */
@@ -178,10 +243,35 @@ export declare class Policy {
      */
     getName(): string | undefined;
 }
+/**
+ * Get the set of optional context fields for the given action(s).
+ *
+ * A field is considered optional if it has `required: false` in ANY of the
+ * targeted actions. This is the safe choice because at evaluation time,
+ * the policy could be matched against any of the specified actions.
+ *
+ * @param serviceContext - The service context metadata (from OVERWATCH_CONTEXT, etc.)
+ * @param actions - Single action name or array of action names
+ * @returns Set of field names that are optional and need `context has` guards
+ *
+ * @example
+ * ```typescript
+ * import { OVERWATCH_CONTEXT } from '@highflame/policy/types';
+ *
+ * const optionalFields = getOptionalFields(OVERWATCH_CONTEXT, 'call_tool');
+ * // Set { 'tool_name', 'mcp_server', 'threat_count', ... }
+ *
+ * const cedar = ruleToCedar(rule, optionalFields);
+ * // Conditions on optional fields auto-get `context has` guards
+ * ```
+ */
+export declare function getOptionalFields(serviceContext: ServiceContext, actions: string | string[]): Set<string>;
 /**
  * Convert a PolicyRule to Cedar policy text with proper annotations.
  *
  * @param rule - The PolicyRule to convert
+ * @param optionalFields - Set of context field names that are optional and need `context has` guards.
+ *                         Use `getOptionalFields()` to compute this from service context metadata.
  * @returns Cedar policy text string
  *
  * @example
@@ -197,35 +287,38 @@ export declare class Policy {
  *   order: 0,
  * };
  *
+ * // Without optional fields - no guards injected
  * const cedar = ruleToCedar(rule);
- * // Output:
- * // @id("rule-001")
- * // @name("Block threats")
- * // @severity("high")
- * // forbid (
- * //     principal,
- * //     action == Action::"call_tool",
- * //     resource
- * // )
- * // when { context.threat_count > 0 };
+ *
+ * // With optional fields - auto-injects `context has` guards
+ * import { OVERWATCH_CONTEXT } from '@highflame/policy/types';
+ * const optionalFields = getOptionalFields(OVERWATCH_CONTEXT, 'call_tool');
+ * const cedarWithGuards = ruleToCedar(rule, optionalFields);
+ * // when { context has threat_count && context.threat_count > 0 };
  * ```
  */
-export declare function ruleToCedar(rule: PolicyRule): string;
+export declare function ruleToCedar(rule: PolicyRule, optionalFields?: Set<string>): string;
 /**
  * Convert multiple PolicyRules to Cedar policy text.
  * Only enabled rules are included, sorted by order.
  *
  * @param rules - Array of PolicyRules to convert
  * @param includeDisabled - If true, include disabled rules as comments (default: false)
+ * @param optionalFields - Set of context field names that are optional and need `context has` guards.
+ *                         Use `getOptionalFields()` to compute this from service context metadata.
  * @returns Cedar policy text with all rules separated by blank lines
  *
  * @example
  * ```typescript
  * const rules: PolicyRule[] = [...];
  * const cedarText = rulesToCedar(rules);
+ *
+ * // With optional fields awareness
+ * const optionalFields = getOptionalFields(OVERWATCH_CONTEXT, 'call_tool');
+ * const cedarText = rulesToCedar(rules, false, optionalFields);
  * ```
  */
-export declare function rulesToCedar(rules: PolicyRule[], includeDisabled?: boolean): string;
+export declare function rulesToCedar(rules: PolicyRule[], includeDisabled?: boolean, optionalFields?: Set<string>): string;
 /**
  * Builder for constructing Cedar policies with type safety.
  */

package/dist/builder.js

@@ -133,8 +133,11 @@ export class Policy {
     /**
      * Convert to Cedar policy text.
      * Uses proper Cedar @annotation syntax.
+     *
+     * @param optionalFields - Set of context field names that are optional and need `context has` guards.
+     *                         Use `getOptionalFields()` to compute this from service context metadata.
      */
-    toCedar() {
+    toCedar(optionalFields) {
         const lines = [];
         // Generate proper Cedar annotations
         if (this.data.id || this.data.name) {
@@ -145,7 +148,7 @@ export class Policy {
             lines.push(...generateAnnotationLines(annotations));
         }
         // Generate policy body
-        lines.push(generatePolicyBody(this.data.effect, this.data.principal, this.data.action, this.data.resource, this.data.conditions, this.data.rawCondition));
+        lines.push(generatePolicyBody(this.data.effect, this.data.principal, this.data.action, this.data.resource, this.data.conditions, this.data.rawCondition, optionalFields));
         return lines.join('\n');
     }
     /**
@@ -170,40 +173,99 @@ export class Policy {
 // ============================================================================
 // Cedar Generation Functions
 // ============================================================================
+/**
+ * Get the set of optional context fields for the given action(s).
+ *
+ * A field is considered optional if it has `required: false` in ANY of the
+ * targeted actions. This is the safe choice because at evaluation time,
+ * the policy could be matched against any of the specified actions.
+ *
+ * @param serviceContext - The service context metadata (from OVERWATCH_CONTEXT, etc.)
+ * @param actions - Single action name or array of action names
+ * @returns Set of field names that are optional and need `context has` guards
+ *
+ * @example
+ * ```typescript
+ * import { OVERWATCH_CONTEXT } from '@highflame/policy/types';
+ *
+ * const optionalFields = getOptionalFields(OVERWATCH_CONTEXT, 'call_tool');
+ * // Set { 'tool_name', 'mcp_server', 'threat_count', ... }
+ *
+ * const cedar = ruleToCedar(rule, optionalFields);
+ * // Conditions on optional fields auto-get `context has` guards
+ * ```
+ */
+export function getOptionalFields(serviceContext, actions) {
+    const actionList = Array.isArray(actions) ? actions : [actions];
+    const optionalFields = new Set();
+    for (const actionName of actionList) {
+        const action = serviceContext.actions.find(a => a.name === actionName);
+        if (action) {
+            for (const attr of action.context_attributes) {
+                if (!attr.required) {
+                    optionalFields.add(attr.key);
+                }
+            }
+        }
+    }
+    return optionalFields;
+}
 /**
  * Convert a condition to Cedar syntax.
  * Field names are sanitized to prevent injection attacks.
+ *
+ * When `optionalFields` is provided and the condition's field is in the set,
+ * the output is wrapped with a `context has` guard:
+ *   `context has field && context.field > value`
  */
-function conditionToCedar(condition) {
+function conditionToCedar(condition, optionalFields) {
     const field = sanitizeIdentifier(condition.field, 'field');
     const { operator, value } = condition;
     const valueStr = valueToString(value);
+    let expr;
     switch (operator) {
         case 'eq':
-            return `context.${field} == ${valueStr}`;
+            expr = `context.${field} == ${valueStr}`;
+            break;
         case 'neq':
-            return `context.${field} != ${valueStr}`;
+            expr = `context.${field} != ${valueStr}`;
+            break;
         case 'lt':
-            return `context.${field} < ${valueStr}`;
+            expr = `context.${field} < ${valueStr}`;
+            break;
         case 'lte':
-            return `context.${field} <= ${valueStr}`;
+            expr = `context.${field} <= ${valueStr}`;
+            break;
         case 'gt':
-            return `context.${field} > ${valueStr}`;
+            expr = `context.${field} > ${valueStr}`;
+            break;
         case 'gte':
-            return `context.${field} >= ${valueStr}`;
+            expr = `context.${field} >= ${valueStr}`;
+            break;
         case 'contains':
-            return `context.${field}.contains(${valueStr})`;
+            expr = `context.${field}.contains(${valueStr})`;
+            break;
         case 'in':
             if (Array.isArray(value)) {
                 const items = value.map(v => `"${escapeCedarString(v)}"`).join(', ');
-                return `context.${field} in [${items}]`;
+                expr = `context.${field} in [${items}]`;
+            }
+            else {
+                expr = `context.${field} in ${valueStr}`;
             }
-            return `context.${field} in ${valueStr}`;
+            break;
         case 'like':
-            return `context.${field} like ${valueStr}`;
+            expr = `context.${field} like ${valueStr}`;
+            break;
         default:
-            return `context.${field} == ${valueStr}`;
+            expr = `context.${field} == ${valueStr}`;
+            break;
+    }
+    // Auto-inject `context has` guard for optional fields
+    if (optionalFields?.has(field)) {
+        return `context has ${field} && ${expr}`;
     }
+    return expr;
 }
 /**
  * Convert a value to Cedar string representation.
@@ -225,13 +287,14 @@ function valueToString(value) {
  * Generate the Cedar policy body (permit/forbid statement).
  * All inputs are sanitized/escaped to prevent injection attacks.
  */
-function generatePolicyBody(effect, principal, action, resource, conditions, rawCondition) {
+function generatePolicyBody(effect, principal, action, resource, conditions, rawCondition, optionalFields) {
     let policyLine = `${effect} (`;
     // Principal
     if (principal) {
         const entityType = sanitizeIdentifier(principal.type, 'principal_type');
         if (principal.id) {
-            policyLine += `\n    principal == ${entityType}::"${escapeCedarString(principal.id)}"`;
+            const op = principal.operator === 'in' ? 'in' : '==';
+            policyLine += `\n    principal ${op} ${entityType}::"${escapeCedarString(principal.id)}"`;
         }
         else {
             policyLine += `\n    principal is ${entityType}`;
@@ -264,7 +327,8 @@ function generatePolicyBody(effect, principal, action, resource, conditions, raw
     if (resource) {
         const entityType = sanitizeIdentifier(resource.type, 'resource_type');
         if (resource.id) {
-            policyLine += `,\n    resource == ${entityType}::"${escapeCedarString(resource.id)}"`;
+            const op = resource.operator === 'in' ? 'in' : '==';
+            policyLine += `,\n    resource ${op} ${entityType}::"${escapeCedarString(resource.id)}"`;
         }
         else {
             policyLine += `,\n    resource is ${entityType}`;
@@ -283,7 +347,7 @@ function generatePolicyBody(effect, principal, action, resource, conditions, raw
         }
         else if (conditions.length > 0) {
             // Fallback to structured conditions if rawCondition is rejected
-            const conditionStr = conditions.map(c => conditionToCedar(c)).join(' && ');
+            const conditionStr = conditions.map(c => conditionToCedar(c, optionalFields)).join(' && ');
             policyLine += `\nwhen { ${conditionStr} };`;
         }
         else {
@@ -291,7 +355,7 @@ function generatePolicyBody(effect, principal, action, resource, conditions, raw
         }
     }
     else if (conditions.length > 0) {
-        const conditionStr = conditions.map(c => conditionToCedar(c)).join(' && ');
+        const conditionStr = conditions.map(c => conditionToCedar(c, optionalFields)).join(' && ');
         policyLine += `\nwhen { ${conditionStr} };`;
     }
     else {
@@ -303,6 +367,8 @@ function generatePolicyBody(effect, principal, action, resource, conditions, raw
  * Convert a PolicyRule to Cedar policy text with proper annotations.
  *
  * @param rule - The PolicyRule to convert
+ * @param optionalFields - Set of context field names that are optional and need `context has` guards.
+ *                         Use `getOptionalFields()` to compute this from service context metadata.
  * @returns Cedar policy text string
  *
  * @example
@@ -318,25 +384,22 @@ function generatePolicyBody(effect, principal, action, resource, conditions, raw
  *   order: 0,
  * };
  *
+ * // Without optional fields - no guards injected
  * const cedar = ruleToCedar(rule);
- * // Output:
- * // @id("rule-001")
- * // @name("Block threats")
- * // @severity("high")
- * // forbid (
- * //     principal,
- * //     action == Action::"call_tool",
- * //     resource
- * // )
- * // when { context.threat_count > 0 };
+ *
+ * // With optional fields - auto-injects `context has` guards
+ * import { OVERWATCH_CONTEXT } from '@highflame/policy/types';
+ * const optionalFields = getOptionalFields(OVERWATCH_CONTEXT, 'call_tool');
+ * const cedarWithGuards = ruleToCedar(rule, optionalFields);
+ * // when { context has threat_count && context.threat_count > 0 };
  * ```
  */
-export function ruleToCedar(rule) {
+export function ruleToCedar(rule, optionalFields) {
     const lines = [];
     // Generate Cedar annotations
     lines.push(...generateAnnotationLines(rule.annotations, rule.customAnnotations));
     // Generate policy body
-    lines.push(generatePolicyBody(rule.effect, rule.principal, rule.action, rule.resource, rule.conditions, rule.rawCondition));
+    lines.push(generatePolicyBody(rule.effect, rule.principal, rule.action, rule.resource, rule.conditions, rule.rawCondition, optionalFields));
     return lines.join('\n');
 }
 /**
@@ -345,24 +408,30 @@ export function ruleToCedar(rule) {
  *
  * @param rules - Array of PolicyRules to convert
  * @param includeDisabled - If true, include disabled rules as comments (default: false)
+ * @param optionalFields - Set of context field names that are optional and need `context has` guards.
+ *                         Use `getOptionalFields()` to compute this from service context metadata.
  * @returns Cedar policy text with all rules separated by blank lines
  *
  * @example
  * ```typescript
  * const rules: PolicyRule[] = [...];
  * const cedarText = rulesToCedar(rules);
+ *
+ * // With optional fields awareness
+ * const optionalFields = getOptionalFields(OVERWATCH_CONTEXT, 'call_tool');
+ * const cedarText = rulesToCedar(rules, false, optionalFields);
  * ```
  */
-export function rulesToCedar(rules, includeDisabled = false) {
+export function rulesToCedar(rules, includeDisabled = false, optionalFields) {
     const sortedRules = [...rules].sort((a, b) => a.order - b.order);
     const cedarPolicies = [];
     for (const rule of sortedRules) {
         if (rule.enabled) {
-            cedarPolicies.push(ruleToCedar(rule));
+            cedarPolicies.push(ruleToCedar(rule, optionalFields));
         }
         else if (includeDisabled) {
             // Include disabled rules as comments
-            const cedarLines = ruleToCedar(rule).split('\n');
+            const cedarLines = ruleToCedar(rule, optionalFields).split('\n');
             cedarPolicies.push(cedarLines.map(line => `// [DISABLED] ${line}`).join('\n'));
         }
     }