@highflame/policy 2.2.41 → 2.2.42

package/dist/service-schemas.gen.js

@@ -1025,7 +1025,7 @@ entity FilePath in [Project];
 // ACTIONS
 // =============================================================================
 
-// Call an MCP tool
+// Call an MCP tool (tools/call). Enumeration is the \`list\` action.
 // Threat focus: command injection, tool poisoning, rug pull, secrets, PII
 action call_tool appliesTo {
   principal: [User, MCP_Client],
@@ -1225,6 +1225,108 @@ action connect_server appliesTo {
   },
 };
 
+// Enumerate a server's tools, prompts, or resources
+// (tools/list, prompts/list, resources/list)
+//
+// Threat focus: tool poisoning and rug pull in the DESCRIPTIONS returned by
+// enumeration — the text a host feeds the model when it assembles the
+// session's tool schema, and the vector a rug-pull exploits between scans.
+//
+// Distinct from the actions it enumerates, and deliberately NOT default-locked
+// (highflame-shield#515 / INV-AUTHZ-003). Listing is host plumbing: the model
+// never decides to enumerate, the host does it to build the session. Folding
+// it into call_tool / process_prompt / read_file made enumeration inherit
+// their lock, and because a list names no tool, no conditioned grant
+// (\`context has tool_name && ...\`) can ever match it — so an agent holding a
+// correct grant for every tool it uses was still denied the enumeration step,
+// and without tools/list it cannot call anything at all. The only grant that
+// could match was an unconditioned one, which would have lifted the lock for
+// every call as well. There is no way to express "may list, may not call"
+// while a list and a call are the same action. See highflame-firehog#589.
+//
+// Authorization over WHAT may be enumerated is expressed through the list
+// CONTENTS (the grant-derived list filter), not by denying the request.
+action list appliesTo {
+  principal: [User, MCP_Client],
+  resource: [Server],
+  context: {
+    // Identity (AARM R6 / CAP-IDN-011) — projected from the principal's token; optional.
+    role?: String,
+    privilege_scope?: Set<String>,
+
+    // --- Content ---
+    // The enumerated item's description. Optional: a tool may declare none,
+    // and a policy must still evaluate when it does not.
+    content?: String,
+    mcp_server?: String,
+
+    // --- Enumerated item identity ---
+    // The list is scanned one item at a time, so the item being evaluated
+    // rides here while the resource stays the server being enumerated.
+    tool_name?: String,
+    tool_risk_score?: Long,
+    tool_category?: String,           // "safe", "sensitive", "dangerous"
+    tool_is_sensitive?: Bool,
+    tool_is_builtin?: Bool,
+    tool_operation_classes?: Set<String>,
+
+    // --- Threat Detection ---
+    threat_count?: Long,
+    highest_severity?: String,
+    threat_categories?: Set<String>,
+    detected_threats?: Set<String>,
+    max_threat_severity?: Long,
+
+    // --- Agent Security (0-100) — the reason this action scans at all ---
+    tool_poisoning_score?: Long,      // Hidden instructions in a tool description
+    tool_poisoning_detected?: Bool,
+    rug_pull_score?: Long,            // Description drift after trust establishment
+    rug_pull_detected?: Bool,
+    indirect_injection_score?: Long,
+
+    // --- ML Detector Confidence Scores (0-100) ---
+    injection_score?: Long,
+    jailbreak_score?: Long,
+
+    // --- Secrets ---
+    secrets_detected?: Bool,
+    secret_types?: Set<String>,
+    secret_count?: Long,
+
+    // --- PII Detection ---
+    pii_detected?: Bool,
+    pii_types?: Set<String>,
+    pii_count?: Long,
+    pii_score?: Long,
+
+    // --- MCP Trust & Config Risk ---
+    mcp_server_verified?: Bool,
+    mcp_config_risk?: Bool,
+    mcp_risk_score?: Long,
+
+    // --- Session-Aware Threat Aggregation ---
+    session_threat_turns?: Long,
+    session_cumulative_risk_score?: Long,
+    session_injection_detected?: Bool,
+    session_command_injection?: Bool,
+    session_pii_detected?: Bool,
+    session_pii_types?: Set<String>,
+    session_secrets_detected?: Bool,
+    session_secret_types?: Set<String>,
+    session_max_injection_score?: Long,
+    session_max_jailbreak_score?: Long,
+    session_max_command_injection_score?: Long,
+    session_max_pii_score?: Long,
+    session_max_secret_score?: Long,
+
+    // Rate Limiting — gateway-metered, Shield-decided (ADR 0014)
+    rpm_remaining_pct?: Long,
+    rpm_exceeded?: Bool,
+    tpm_remaining_pct?: Long,
+    tpm_exceeded?: Bool,
+  },
+};
+
 // Shared content-inspection context.
 //
 // Prompts and responses are inspected by the same detector pipeline and so
@@ -1312,7 +1414,8 @@ type ContentInspectionContext = {
     tpm_exceeded?: Bool,
 };
 
-// Process a prompt (MCP prompts/get or LLM chat completions)
+// Process a prompt (MCP prompts/get or LLM chat completions).
+// Enumeration (prompts/list) is the \`list\` action.
 // Threat focus: injection, jailbreak, secrets, PII, content safety
 action process_prompt appliesTo {
   principal: [User, MCP_Client],
@@ -1335,7 +1438,8 @@ action process_response appliesTo {
   context: ContentInspectionContext,
 };
 
-// Read an MCP resource (resources/read, resources/list)
+// Read an MCP resource (resources/read). Enumeration (resources/list)
+// is the \`list\` action.
 // Threat focus: secrets exposure, PII exposure, sensitive paths
 action read_file appliesTo {
   principal: [User, MCP_Client],
@@ -2327,6 +2431,24 @@ action process_prompt appliesTo {
     // --- Legacy ---
     prompt_text?: String,             // Same as content (backward compatibility)
     response_content?: String,        // Response content (if available)
+    // --- Session Token Budget --- (OWASP LLM10; CAP-ENF-009, cerberus#147)
+    // Fed by the cumulative session total the Overwatch daemon reports on the
+    // prompt and before-tool events.
+    //
+    // BOTH are optional, so BOTH need a \`has\` guard — a bare
+    // \`context.budget_remaining_pct < 10\` fails cedar validation with
+    // "unable to guarantee safety of access to optional attribute".
+    // Write: \`context has budget_remaining_pct && context.budget_remaining_pct < 10\`.
+    //
+    // The guard is a validation requirement, NOT a safety property. Whenever a
+    // session loads, budget_checker emits both keys — including
+    // budget_exceeded: false and budget_remaining_pct: 100 when no budget rule
+    // is configured for the scope. So a grant conditioned on
+    // \`!context.budget_exceeded\` fires on unbudgeted sessions, and a low
+    // percentage is evidence of spend only when a budget rule exists. Absence
+    // means the detector did not run at all (no session).
+    budget_remaining_pct?: Long,      // Remaining session token budget (0-100)
+    budget_exceeded?: Bool,           // Session token budget exceeded
   },
 };
 
@@ -2446,6 +2568,24 @@ action call_tool appliesTo {
 
     // --- Legacy ---
     response_content?: String,
+    // --- Session Token Budget --- (OWASP LLM10; CAP-ENF-009, cerberus#147)
+    // Fed by the cumulative session total the Overwatch daemon reports on the
+    // prompt and before-tool events.
+    //
+    // BOTH are optional, so BOTH need a \`has\` guard — a bare
+    // \`context.budget_remaining_pct < 10\` fails cedar validation with
+    // "unable to guarantee safety of access to optional attribute".
+    // Write: \`context has budget_remaining_pct && context.budget_remaining_pct < 10\`.
+    //
+    // The guard is a validation requirement, NOT a safety property. Whenever a
+    // session loads, budget_checker emits both keys — including
+    // budget_exceeded: false and budget_remaining_pct: 100 when no budget rule
+    // is configured for the scope. So a grant conditioned on
+    // \`!context.budget_exceeded\` fires on unbudgeted sessions, and a low
+    // percentage is evidence of spend only when a budget rule exists. Absence
+    // means the detector did not run at all (no session).
+    budget_remaining_pct?: Long,      // Remaining session token budget (0-100)
+    budget_exceeded?: Bool,           // Session token budget exceeded
   },
 };
 
@@ -2568,6 +2708,24 @@ action connect_server appliesTo {
     session_max_pii_score?: Long,
     session_max_secret_score?: Long,
     session_cumulative_risk_score?: Long,
+    // --- Session Token Budget --- (OWASP LLM10; CAP-ENF-009, cerberus#147)
+    // Fed by the cumulative session total the Overwatch daemon reports on the
+    // prompt and before-tool events.
+    //
+    // BOTH are optional, so BOTH need a \`has\` guard — a bare
+    // \`context.budget_remaining_pct < 10\` fails cedar validation with
+    // "unable to guarantee safety of access to optional attribute".
+    // Write: \`context has budget_remaining_pct && context.budget_remaining_pct < 10\`.
+    //
+    // The guard is a validation requirement, NOT a safety property. Whenever a
+    // session loads, budget_checker emits both keys — including
+    // budget_exceeded: false and budget_remaining_pct: 100 when no budget rule
+    // is configured for the scope. So a grant conditioned on
+    // \`!context.budget_exceeded\` fires on unbudgeted sessions, and a low
+    // percentage is evidence of spend only when a budget rule exists. Absence
+    // means the detector did not run at all (no session).
+    budget_remaining_pct?: Long,      // Remaining session token budget (0-100)
+    budget_exceeded?: Bool,           // Session token budget exceeded
   },
 };
 
@@ -2622,6 +2780,24 @@ action read_file appliesTo {
 
     // --- Agent Security ---
     indirect_injection_score?: Long,  // Indirect injection via file content
+    // --- Session Token Budget --- (OWASP LLM10; CAP-ENF-009, cerberus#147)
+    // Fed by the cumulative session total the Overwatch daemon reports on the
+    // prompt and before-tool events.
+    //
+    // BOTH are optional, so BOTH need a \`has\` guard — a bare
+    // \`context.budget_remaining_pct < 10\` fails cedar validation with
+    // "unable to guarantee safety of access to optional attribute".
+    // Write: \`context has budget_remaining_pct && context.budget_remaining_pct < 10\`.
+    //
+    // The guard is a validation requirement, NOT a safety property. Whenever a
+    // session loads, budget_checker emits both keys — including
+    // budget_exceeded: false and budget_remaining_pct: 100 when no budget rule
+    // is configured for the scope. So a grant conditioned on
+    // \`!context.budget_exceeded\` fires on unbudgeted sessions, and a low
+    // percentage is evidence of spend only when a budget rule exists. Absence
+    // means the detector did not run at all (no session).
+    budget_remaining_pct?: Long,      // Remaining session token budget (0-100)
+    budget_exceeded?: Bool,           // Session token budget exceeded
   },
 };
 
@@ -2676,6 +2852,24 @@ action write_file appliesTo {
 
     // --- Agent Security ---
     indirect_injection_score?: Long,  // Indirect injection via file content
+    // --- Session Token Budget --- (OWASP LLM10; CAP-ENF-009, cerberus#147)
+    // Fed by the cumulative session total the Overwatch daemon reports on the
+    // prompt and before-tool events.
+    //
+    // BOTH are optional, so BOTH need a \`has\` guard — a bare
+    // \`context.budget_remaining_pct < 10\` fails cedar validation with
+    // "unable to guarantee safety of access to optional attribute".
+    // Write: \`context has budget_remaining_pct && context.budget_remaining_pct < 10\`.
+    //
+    // The guard is a validation requirement, NOT a safety property. Whenever a
+    // session loads, budget_checker emits both keys — including
+    // budget_exceeded: false and budget_remaining_pct: 100 when no budget rule
+    // is configured for the scope. So a grant conditioned on
+    // \`!context.budget_exceeded\` fires on unbudgeted sessions, and a low
+    // percentage is evidence of spend only when a budget rule exists. Absence
+    // means the detector did not run at all (no session).
+    budget_remaining_pct?: Long,      // Remaining session token budget (0-100)
+    budget_exceeded?: Bool,           // Session token budget exceeded
   },
 };
 
@@ -4035,6 +4229,61 @@ export const AI_GATEWAY_CONTEXT = {
                 { "key": "package_check_status", "type": "string", "required": false, "description": "Set to \'degraded\' when the osv.dev lookup failed (fail-open)" }
             ]
         },
+        {
+            "name": "list",
+            "description": "Enumerate a server\'s tools, prompts, or resources — threat focus: tool poisoning and rug pull in the returned descriptions",
+            "context_attributes": [
+                { "key": "role", "type": "string", "required": false, "description": "Caller\'s RBAC role projected from the principal\'s token (AARM R6 / CAP-IDN-011)." },
+                { "key": "privilege_scope", "type": "array", "required": false, "description": "Privilege-scope strings granted to the caller, projected from the token (AARM R6 / CAP-IDN-011)." },
+                { "key": "content", "type": "string", "required": false, "description": "The enumerated item\'s description — the text scanned for poisoning. Absent when the item declares none." },
+                { "key": "mcp_server", "type": "string", "required": false, "description": "MCP server being enumerated" },
+                { "key": "tool_name", "type": "string", "required": false, "description": "Name of the enumerated item being evaluated" },
+                { "key": "tool_risk_score", "type": "number", "required": false, "description": "Tool risk score" },
+                { "key": "tool_category", "type": "string", "required": false, "description": "\"safe\", \"sensitive\", \"dangerous\"" },
+                { "key": "tool_is_sensitive", "type": "boolean", "required": false, "description": "Tool is sensitive" },
+                { "key": "tool_is_builtin", "type": "boolean", "required": false, "description": "Tool is builtin" },
+                { "key": "tool_operation_classes", "type": "array", "required": false, "description": "Tool operation classes" },
+                { "key": "threat_count", "type": "number", "required": false, "description": "Total threats detected" },
+                { "key": "highest_severity", "type": "string", "required": false, "description": "Highest threat severity" },
+                { "key": "threat_categories", "type": "array", "required": false, "description": "Threat category names" },
+                { "key": "detected_threats", "type": "array", "required": false, "description": "Detection rule names that matched" },
+                { "key": "max_threat_severity", "type": "number", "required": false, "description": "Numeric severity (0=none, 4=critical)" },
+                { "key": "tool_poisoning_score", "type": "number", "required": false, "description": "Hidden instructions in a tool description" },
+                { "key": "tool_poisoning_detected", "type": "boolean", "required": false, "description": "Hidden instructions found in the description" },
+                { "key": "rug_pull_score", "type": "number", "required": false, "description": "Description drift after trust establishment" },
+                { "key": "rug_pull_detected", "type": "boolean", "required": false, "description": "Description drifted after trust was established" },
+                { "key": "indirect_injection_score", "type": "number", "required": false, "description": "Indirect injection score" },
+                { "key": "injection_score", "type": "number", "required": false, "description": "Prompt injection classifier confidence (0-100)" },
+                { "key": "jailbreak_score", "type": "number", "required": false, "description": "Jailbreak classifier confidence (0-100)" },
+                { "key": "secrets_detected", "type": "boolean", "required": false, "description": "Whether secrets were detected in the description" },
+                { "key": "secret_types", "type": "array", "required": false, "description": "Secret types detected" },
+                { "key": "secret_count", "type": "number", "required": false, "description": "Number of secrets detected" },
+                { "key": "pii_detected", "type": "boolean", "required": false, "description": "Whether PII was detected" },
+                { "key": "pii_types", "type": "array", "required": false, "description": "PII types detected" },
+                { "key": "pii_count", "type": "number", "required": false, "description": "Number of PII entities" },
+                { "key": "pii_score", "type": "number", "required": false, "description": "PII confidence (0-100)" },
+                { "key": "mcp_server_verified", "type": "boolean", "required": false, "description": "Whether the server is from a verified registry" },
+                { "key": "mcp_config_risk", "type": "boolean", "required": false, "description": "Server config flagged risky" },
+                { "key": "mcp_risk_score", "type": "number", "required": false, "description": "Server risk score (0-100)" },
+                { "key": "session_threat_turns", "type": "number", "required": false, "description": "Session-aggregated threat turns across prior turns" },
+                { "key": "session_cumulative_risk_score", "type": "number", "required": false, "description": "Session-aggregated cumulative risk score across prior turns" },
+                { "key": "session_injection_detected", "type": "boolean", "required": false, "description": "Session-aggregated injection detected across prior turns" },
+                { "key": "session_command_injection", "type": "boolean", "required": false, "description": "Session-aggregated command injection across prior turns" },
+                { "key": "session_pii_detected", "type": "boolean", "required": false, "description": "Session-aggregated pii detected across prior turns" },
+                { "key": "session_pii_types", "type": "array", "required": false, "description": "Session-aggregated pii types across prior turns" },
+                { "key": "session_secrets_detected", "type": "boolean", "required": false, "description": "Session-aggregated secrets detected across prior turns" },
+                { "key": "session_secret_types", "type": "array", "required": false, "description": "Session-aggregated secret types across prior turns" },
+                { "key": "session_max_injection_score", "type": "number", "required": false, "description": "Session-aggregated max injection score across prior turns" },
+                { "key": "session_max_jailbreak_score", "type": "number", "required": false, "description": "Session-aggregated max jailbreak score across prior turns" },
+                { "key": "session_max_command_injection_score", "type": "number", "required": false, "description": "Session-aggregated max command injection score across prior turns" },
+                { "key": "session_max_pii_score", "type": "number", "required": false, "description": "Session-aggregated max pii score across prior turns" },
+                { "key": "session_max_secret_score", "type": "number", "required": false, "description": "Session-aggregated max secret score across prior turns" },
+                { "key": "rpm_remaining_pct", "type": "number", "required": false, "description": "Requests-per-minute headroom remaining" },
+                { "key": "rpm_exceeded", "type": "boolean", "required": false, "description": "RPM limit exceeded" },
+                { "key": "tpm_remaining_pct", "type": "number", "required": false, "description": "Tokens-per-minute headroom remaining" },
+                { "key": "tpm_exceeded", "type": "boolean", "required": false, "description": "TPM limit exceeded" }
+            ]
+        },
         {
             "name": "process_prompt",
             "description": "Process a prompt (MCP or LLM chat completion) — threat focus: injection, jailbreak, secrets, PII, content safety",
@@ -4774,7 +5023,9 @@ export const OVERWATCH_CONTEXT = {
                 { "key": "session_max_command_injection_score", "type": "number", "required": false, "description": "Highest command injection score seen in any turn of the session (0-100)" },
                 { "key": "session_max_pii_score", "type": "number", "required": false, "description": "Highest PII risk score seen in any turn of the session (0-100)" },
                 { "key": "session_max_secret_score", "type": "number", "required": false, "description": "Highest secret detection score seen in any turn of the session (0-100)" },
-                { "key": "session_cumulative_risk_score", "type": "number", "required": false, "description": "Sum of per-turn risk scores across the session. Catches death-by-a-thousand-cuts where no single turn is high but cumulative risk is significant" }
+                { "key": "session_cumulative_risk_score", "type": "number", "required": false, "description": "Sum of per-turn risk scores across the session. Catches death-by-a-thousand-cuts where no single turn is high but cumulative risk is significant" },
+                { "key": "budget_remaining_pct", "type": "number", "required": false, "description": "Remaining session token budget as a percentage (0-100). Optional, so a policy must guard it: `context has budget_remaining_pct && context.budget_remaining_pct < 10` — a bare comparison fails Cedar validation. Runtime default-fills it to 100 whenever the detector runs, so a high value is not evidence that a budget rule exists." },
+                { "key": "budget_exceeded", "type": "boolean", "required": false, "description": "Whether the session token budget has been exceeded. Optional, so a policy must guard it with `context has budget_exceeded`. The guard is a validation requirement, not a fail-closed property: the detector emits false whenever a session loads, including when no budget rule is configured, so a grant conditioned on `!context.budget_exceeded` will fire on unbudgeted sessions." }
             ]
         },
         {
@@ -4864,7 +5115,9 @@ export const OVERWATCH_CONTEXT = {
                 { "key": "session_max_command_injection_score", "type": "number", "required": false, "description": "Highest command injection score seen in any turn of the session (0-100)" },
                 { "key": "session_max_pii_score", "type": "number", "required": false, "description": "Highest PII risk score seen in any turn of the session (0-100)" },
                 { "key": "session_max_secret_score", "type": "number", "required": false, "description": "Highest secret detection score seen in any turn of the session (0-100)" },
-                { "key": "session_cumulative_risk_score", "type": "number", "required": false, "description": "Sum of per-turn risk scores across the session. Catches death-by-a-thousand-cuts where no single turn is high but cumulative risk is significant" }
+                { "key": "session_cumulative_risk_score", "type": "number", "required": false, "description": "Sum of per-turn risk scores across the session. Catches death-by-a-thousand-cuts where no single turn is high but cumulative risk is significant" },
+                { "key": "budget_remaining_pct", "type": "number", "required": false, "description": "Remaining session token budget as a percentage (0-100). Optional, so a policy must guard it: `context has budget_remaining_pct && context.budget_remaining_pct < 10` — a bare comparison fails Cedar validation. Runtime default-fills it to 100 whenever the detector runs, so a high value is not evidence that a budget rule exists." },
+                { "key": "budget_exceeded", "type": "boolean", "required": false, "description": "Whether the session token budget has been exceeded. Optional, so a policy must guard it with `context has budget_exceeded`. The guard is a validation requirement, not a fail-closed property: the detector emits false whenever a session loads, including when no budget rule is configured, so a grant conditioned on `!context.budget_exceeded` will fire on unbudgeted sessions." }
             ]
         },
         {
@@ -4945,7 +5198,9 @@ export const OVERWATCH_CONTEXT = {
                 { "key": "session_max_command_injection_score", "type": "number", "required": false, "description": "Highest command injection score seen in any turn of the session (0-100)" },
                 { "key": "session_max_pii_score", "type": "number", "required": false, "description": "Highest PII risk score seen in any turn of the session (0-100)" },
                 { "key": "session_max_secret_score", "type": "number", "required": false, "description": "Highest secret detection score seen in any turn of the session (0-100)" },
-                { "key": "session_cumulative_risk_score", "type": "number", "required": false, "description": "Sum of per-turn risk scores across the session. Catches death-by-a-thousand-cuts where no single turn is high but cumulative risk is significant" }
+                { "key": "session_cumulative_risk_score", "type": "number", "required": false, "description": "Sum of per-turn risk scores across the session. Catches death-by-a-thousand-cuts where no single turn is high but cumulative risk is significant" },
+                { "key": "budget_remaining_pct", "type": "number", "required": false, "description": "Remaining session token budget as a percentage (0-100). Optional, so a policy must guard it: `context has budget_remaining_pct && context.budget_remaining_pct < 10` — a bare comparison fails Cedar validation. Runtime default-fills it to 100 whenever the detector runs, so a high value is not evidence that a budget rule exists." },
+                { "key": "budget_exceeded", "type": "boolean", "required": false, "description": "Whether the session token budget has been exceeded. Optional, so a policy must guard it with `context has budget_exceeded`. The guard is a validation requirement, not a fail-closed property: the detector emits false whenever a session loads, including when no budget rule is configured, so a grant conditioned on `!context.budget_exceeded` will fire on unbudgeted sessions." }
             ]
         },
         {
@@ -4984,7 +5239,9 @@ export const OVERWATCH_CONTEXT = {
                 { "key": "session_max_command_injection_score", "type": "number", "required": false, "description": "Highest command injection score seen in any turn of the session (0-100)" },
                 { "key": "session_max_pii_score", "type": "number", "required": false, "description": "Highest PII risk score seen in any turn of the session (0-100)" },
                 { "key": "session_max_secret_score", "type": "number", "required": false, "description": "Highest secret detection score seen in any turn of the session (0-100)" },
-                { "key": "session_cumulative_risk_score", "type": "number", "required": false, "description": "Sum of per-turn risk scores across the session. Catches death-by-a-thousand-cuts where no single turn is high but cumulative risk is significant" }
+                { "key": "session_cumulative_risk_score", "type": "number", "required": false, "description": "Sum of per-turn risk scores across the session. Catches death-by-a-thousand-cuts where no single turn is high but cumulative risk is significant" },
+                { "key": "budget_remaining_pct", "type": "number", "required": false, "description": "Remaining session token budget as a percentage (0-100). Optional, so a policy must guard it: `context has budget_remaining_pct && context.budget_remaining_pct < 10` — a bare comparison fails Cedar validation. Runtime default-fills it to 100 whenever the detector runs, so a high value is not evidence that a budget rule exists." },
+                { "key": "budget_exceeded", "type": "boolean", "required": false, "description": "Whether the session token budget has been exceeded. Optional, so a policy must guard it with `context has budget_exceeded`. The guard is a validation requirement, not a fail-closed property: the detector emits false whenever a session loads, including when no budget rule is configured, so a grant conditioned on `!context.budget_exceeded` will fire on unbudgeted sessions." }
             ]
         },
         {
@@ -5024,7 +5281,9 @@ export const OVERWATCH_CONTEXT = {
                 { "key": "session_max_command_injection_score", "type": "number", "required": false, "description": "Highest command injection score seen in any turn of the session (0-100)" },
                 { "key": "session_max_pii_score", "type": "number", "required": false, "description": "Highest PII risk score seen in any turn of the session (0-100)" },
                 { "key": "session_max_secret_score", "type": "number", "required": false, "description": "Highest secret detection score seen in any turn of the session (0-100)" },
-                { "key": "session_cumulative_risk_score", "type": "number", "required": false, "description": "Sum of per-turn risk scores across the session. Catches death-by-a-thousand-cuts where no single turn is high but cumulative risk is significant" }
+                { "key": "session_cumulative_risk_score", "type": "number", "required": false, "description": "Sum of per-turn risk scores across the session. Catches death-by-a-thousand-cuts where no single turn is high but cumulative risk is significant" },
+                { "key": "budget_remaining_pct", "type": "number", "required": false, "description": "Remaining session token budget as a percentage (0-100). Optional, so a policy must guard it: `context has budget_remaining_pct && context.budget_remaining_pct < 10` — a bare comparison fails Cedar validation. Runtime default-fills it to 100 whenever the detector runs, so a high value is not evidence that a budget rule exists." },
+                { "key": "budget_exceeded", "type": "boolean", "required": false, "description": "Whether the session token budget has been exceeded. Optional, so a policy must guard it with `context has budget_exceeded`. The guard is a validation requirement, not a fail-closed property: the detector emits false whenever a session loads, including when no budget rule is configured, so a grant conditioned on `!context.budget_exceeded` will fire on unbudgeted sessions." }
             ]
         }
     ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@highflame/policy",
-  "version": "2.2.41",
+  "version": "2.2.42",
   "engines": {
     "node": ">=18"
   },