@highflame/policy 2.2.27 → 2.2.28

package/_schemas/agent_ops/context.json

@@ -131,6 +131,74 @@
         "required": false,
         "description": "Organization that published the agent (e.g., 'anthropic', 'internal', 'acme-corp')."
       }
+    ],
+    "flow_label_keys": [
+      {
+        "key": "flow_confidentiality",
+        "type": "string",
+        "required": false,
+        "description": "Confidentiality tier of the data this action carries or targets (ADR 0020): 'public', 'internal', 'confidential', 'restricted', or 'unknown'. Shares the ladder with session_max_sensitivity but is a per-value fact, not a session scalar. 'unknown' MUST NOT be treated as 'public' — guard with has and let policy DENY/STEP_UP/DEFER per flow_resolution_status."
+      },
+      {
+        "key": "flow_integrity",
+        "type": "string",
+        "required": false,
+        "description": "Integrity/influence tier of the data this action carries (ADR 0020): 'trusted', 'untrusted', 'mixed', or 'unknown'. Orthogonal to confidentiality: untrusted content may inform a pure analysis but MUST NOT authorize a side-effecting sink. Least-trusted contributor wins on join."
+      },
+      {
+        "key": "flow_data_types",
+        "type": "array",
+        "required": false,
+        "description": "Sensitive data categories present in the value (ADR 0020), e.g. 'pii', 'secrets', 'source_code', 'financial', 'health'. Union of all contributing inputs. Set<String>."
+      },
+      {
+        "key": "flow_compartments",
+        "type": "array",
+        "required": false,
+        "description": "Compartments the value belongs to (ADR 0020), e.g. 'tenant:acme', 'customer:123', 'project:x'. Union of all contributing inputs — cross-compartment composition is expressible by cardinality. Set<String>."
+      },
+      {
+        "key": "flow_resolution_status",
+        "type": "string",
+        "required": false,
+        "description": "How the flow label was resolved (ADR 0020): 'known', 'inferred', 'unknown', or 'conflicted'. Policy authors choose the posture for 'unknown' per sink (DENY external, STEP_UP, DEFER while a classifier runs, or allow-and-record). Never silently resolves to public."
+      },
+      {
+        "key": "flow_origins",
+        "type": "array",
+        "required": false,
+        "description": "Origin kinds that produced or influenced the value (ADR 0020): 'mcp_tool_result', 'model', 'file', 'database', 'user'. Provenance fact for lineage-aware policy. Set<String>."
+      },
+      {
+        "key": "flow_sink",
+        "type": "string",
+        "required": false,
+        "description": "Logical destination this action releases the value to (ADR 0020), e.g. 'external_model', 'local_model', 'external_mcp', 'trusted_mcp', 'user_secure_output', 'public_network', 'file'. The 'where' half of a flow decision — pair with flow_confidentiality/flow_integrity."
+      },
+      {
+        "key": "flow_sink_is_external",
+        "type": "boolean",
+        "required": false,
+        "description": "Whether the destination is outside the tenant trust boundary (ADR 0020). Lets a single policy express 'confidential data MUST NOT leave to any external sink' without enumerating sink ids."
+      },
+      {
+        "key": "flow_sink_effects",
+        "type": "array",
+        "required": false,
+        "description": "Side effects the destination can exercise (ADR 0020), e.g. 'network.send', 'financial.transfer', 'filesystem.write'. Enables 'untrusted content MUST NOT reach a financial.transfer sink'. Set<String>."
+      },
+      {
+        "key": "principal_clearances",
+        "type": "array",
+        "required": false,
+        "description": "Clearances AuthN/ZeroID mints for the principal (ADR 0020 D8), e.g. 'restricted', 'pii'. Coarse scopes gate the capability; clearances gate which protected data that capability may touch. Set<String>."
+      },
+      {
+        "key": "principal_compartments",
+        "type": "array",
+        "required": false,
+        "description": "Compartments the principal is admitted to (ADR 0020 D8), e.g. 'tenant:acme', 'customer:123'. A flow into a compartment the principal lacks is deniable independent of confidentiality tier. Set<String>."
+      }
     ]
   },
   "actions": [
@@ -676,8 +744,35 @@
           "required": false,
           "description": "Whether the token budget has been exceeded"
         },
+        {
+          "key": "rpm_remaining_pct",
+          "type": "number",
+          "required": false,
+          "description": "Remaining RPM percentage (0-100). Gateway-metered, Shield-decided (ADR 0014).",
+          "range": "0-100"
+        },
+        {
+          "key": "rpm_exceeded",
+          "type": "boolean",
+          "required": false,
+          "description": "Whether the RPM limit has been exceeded"
+        },
+        {
+          "key": "tpm_remaining_pct",
+          "type": "number",
+          "required": false,
+          "description": "Remaining TPM percentage (0-100). Gateway-metered, Shield-decided (ADR 0014).",
+          "range": "0-100"
+        },
+        {
+          "key": "tpm_exceeded",
+          "type": "boolean",
+          "required": false,
+          "description": "Whether the TPM limit has been exceeded"
+        },
         { "$ref": "session_keys" },
-        { "$ref": "agent_identity_keys" }
+        { "$ref": "agent_identity_keys" },
+        { "$ref": "flow_label_keys" }
       ]
     },
     {
@@ -1145,6 +1240,32 @@
           "required": false,
           "description": "Whether the token budget has been exceeded"
         },
+        {
+          "key": "rpm_remaining_pct",
+          "type": "number",
+          "required": false,
+          "description": "Remaining RPM percentage (0-100). Gateway-metered, Shield-decided (ADR 0014).",
+          "range": "0-100"
+        },
+        {
+          "key": "rpm_exceeded",
+          "type": "boolean",
+          "required": false,
+          "description": "Whether the RPM limit has been exceeded"
+        },
+        {
+          "key": "tpm_remaining_pct",
+          "type": "number",
+          "required": false,
+          "description": "Remaining TPM percentage (0-100). Gateway-metered, Shield-decided (ADR 0014).",
+          "range": "0-100"
+        },
+        {
+          "key": "tpm_exceeded",
+          "type": "boolean",
+          "required": false,
+          "description": "Whether the TPM limit has been exceeded"
+        },
         {
           "key": "highest_severity",
           "type": "string",
@@ -1164,7 +1285,8 @@
           "description": "Array of specific threat names detected"
         },
         { "$ref": "session_keys" },
-        { "$ref": "agent_identity_keys" }
+        { "$ref": "agent_identity_keys" },
+        { "$ref": "flow_label_keys" }
       ]
     },
     {
@@ -1322,8 +1444,35 @@
           "required": false,
           "description": "Whether the token budget has been exceeded"
         },
+        {
+          "key": "rpm_remaining_pct",
+          "type": "number",
+          "required": false,
+          "description": "Remaining RPM percentage (0-100). Gateway-metered, Shield-decided (ADR 0014).",
+          "range": "0-100"
+        },
+        {
+          "key": "rpm_exceeded",
+          "type": "boolean",
+          "required": false,
+          "description": "Whether the RPM limit has been exceeded"
+        },
+        {
+          "key": "tpm_remaining_pct",
+          "type": "number",
+          "required": false,
+          "description": "Remaining TPM percentage (0-100). Gateway-metered, Shield-decided (ADR 0014).",
+          "range": "0-100"
+        },
+        {
+          "key": "tpm_exceeded",
+          "type": "boolean",
+          "required": false,
+          "description": "Whether the TPM limit has been exceeded"
+        },
         { "$ref": "session_keys" },
-        { "$ref": "agent_identity_keys" }
+        { "$ref": "agent_identity_keys" },
+        { "$ref": "flow_label_keys" }
       ]
     },
     {
@@ -1494,8 +1643,35 @@
           "required": false,
           "description": "Whether the token budget has been exceeded"
         },
+        {
+          "key": "rpm_remaining_pct",
+          "type": "number",
+          "required": false,
+          "description": "Remaining RPM percentage (0-100). Gateway-metered, Shield-decided (ADR 0014).",
+          "range": "0-100"
+        },
+        {
+          "key": "rpm_exceeded",
+          "type": "boolean",
+          "required": false,
+          "description": "Whether the RPM limit has been exceeded"
+        },
+        {
+          "key": "tpm_remaining_pct",
+          "type": "number",
+          "required": false,
+          "description": "Remaining TPM percentage (0-100). Gateway-metered, Shield-decided (ADR 0014).",
+          "range": "0-100"
+        },
+        {
+          "key": "tpm_exceeded",
+          "type": "boolean",
+          "required": false,
+          "description": "Whether the TPM limit has been exceeded"
+        },
         { "$ref": "session_keys" },
-        { "$ref": "agent_identity_keys" }
+        { "$ref": "agent_identity_keys" },
+        { "$ref": "flow_label_keys" }
       ]
     },
     {
@@ -1668,8 +1844,119 @@
           "required": false,
           "description": "Whether the token budget has been exceeded"
         },
+        {
+          "key": "rpm_remaining_pct",
+          "type": "number",
+          "required": false,
+          "description": "Remaining RPM percentage (0-100). Gateway-metered, Shield-decided (ADR 0014).",
+          "range": "0-100"
+        },
+        {
+          "key": "rpm_exceeded",
+          "type": "boolean",
+          "required": false,
+          "description": "Whether the RPM limit has been exceeded"
+        },
+        {
+          "key": "tpm_remaining_pct",
+          "type": "number",
+          "required": false,
+          "description": "Remaining TPM percentage (0-100). Gateway-metered, Shield-decided (ADR 0014).",
+          "range": "0-100"
+        },
+        {
+          "key": "tpm_exceeded",
+          "type": "boolean",
+          "required": false,
+          "description": "Whether the TPM limit has been exceeded"
+        },
         { "$ref": "session_keys" },
-        { "$ref": "agent_identity_keys" }
+        { "$ref": "agent_identity_keys" },
+        { "$ref": "flow_label_keys" }
+      ]
+    },
+    {
+      "name": "provision_sandbox",
+      "description": "Provision a sandbox for the acting identity (Forge OS-layer envelope). Mandatory authorization gate for sandbox creation (ADR 0019). Every capability attribute is optional and describes the requested envelope; rules MUST guard each with `has` before access (an absent-attribute access errors, silently voiding a forbid — fail-open).",
+      "context_attributes": [
+        {
+          "key": "role",
+          "type": "string",
+          "required": false,
+          "description": "Caller's RBAC role projected from the principal's token"
+        },
+        {
+          "key": "privilege_scope",
+          "type": "array",
+          "required": false,
+          "description": "Privilege-scope strings granted to the caller"
+        },
+        {
+          "key": "identity_type",
+          "type": "string",
+          "required": false,
+          "description": "Principal identity class: 'human', 'agent', 'service', or 'mcp_server'"
+        },
+        {
+          "key": "principal",
+          "type": "string",
+          "required": false,
+          "description": "Stable principal identifier (ZeroID / WIMSE URI or user id)"
+        },
+        {
+          "key": "agent_trust_level",
+          "type": "string",
+          "required": false,
+          "description": "Agent trust tier: 'untrusted' | 'low' | 'verified' | 'trusted'"
+        },
+        {
+          "key": "request_id",
+          "type": "string",
+          "required": true,
+          "description": "Unique identifier for this request"
+        },
+        {
+          "key": "timestamp",
+          "type": "number",
+          "required": true,
+          "description": "Unix timestamp in milliseconds"
+        },
+        {
+          "key": "isolation_tier",
+          "type": "string",
+          "required": true,
+          "description": "Requested OS-isolation tier as the lowercased Forge IsolationTier name (ADR 0016 D1). Ordinal, weakest→strongest: 'none' < 'os' < 'kernel' (gVisor) < 'hardware' (micro-VM + TEE). Templates assert a floor via set membership; Forge owns the ordering."
+        },
+        {
+          "key": "writable_paths",
+          "type": "array",
+          "required": false,
+          "description": "Writable path prefixes the sandbox is requesting, e.g. ['/scratch']"
+        },
+        {
+          "key": "network_egress",
+          "type": "boolean",
+          "required": false,
+          "description": "Whether any outbound network egress is requested"
+        },
+        {
+          "key": "egress_hosts",
+          "type": "array",
+          "required": false,
+          "description": "Host allowlist for egress, e.g. ['pypi.org', 'files.pythonhosted.org']"
+        },
+        {
+          "key": "exec_allowlist",
+          "type": "array",
+          "required": false,
+          "description": "Executables the sandbox may run, e.g. ['python', 'python3']"
+        },
+        {
+          "key": "mechanism_capabilities",
+          "type": "array",
+          "required": false,
+          "description": "Curated mechanism toggles (ADR 0017 D1.3) — authorization facts only, never raw syscalls. Allowed members: 'sys:ptrace', 'sys:bpf', 'sys:raw_socket', 'dev:gpu', 'virt:nested'."
+        }
       ]
     }
   ]

package/_schemas/agent_ops/schema.cedarschema

@@ -95,6 +95,19 @@ namespace AgentOps {
         context: ConnectServerContext
     };
 
+    /// Provision a sandbox for the acting identity (Forge OS-layer envelope).
+    /// The MANDATORY authorization gate for sandbox creation (ADR 0019 D1):
+    /// Forge evaluates this action's AgentOps bundle at create-time; no decision
+    /// means no sandbox. Context carries the requested capability envelope
+    /// (writable paths, egress, exec allowlist, curated mechanism toggles,
+    /// isolation tier). Raw syscalls are NEVER expressed here — the enforcement
+    /// generators own the mechanism→syscall translation (ADR 0017 D1).
+    action "provision_sandbox" appliesTo {
+        principal: [User, Agent],
+        resource: [Agent, Session],
+        context: ProvisionSandboxContext
+    };
+
     // =========================================================================
     // Context Types (Action-Specific)
     // =========================================================================
@@ -233,6 +246,21 @@ namespace AgentOps {
         "session_original_request"?: String,
         "session_max_sensitivity"?: String,
 
+        // Data-Flow Labels — per-value information-flow facts (ADR 0020, optional).
+        // All optional: guard every access with `has` — an absent-attribute read is
+        // a Cedar evaluation error and an errored forbid is silently skipped (fail-open).
+        "flow_confidentiality"?: String,         // "public" | "internal" | "confidential" | "restricted" | "unknown"
+        "flow_integrity"?: String,               // "trusted" | "untrusted" | "mixed" | "unknown"
+        "flow_data_types"?: Set<String>,         // "pii" | "secrets" | "source_code" | "financial" | "health" | ...
+        "flow_compartments"?: Set<String>,       // "tenant:*" | "customer:*" | "project:*"
+        "flow_resolution_status"?: String,       // "known" | "inferred" | "unknown" | "conflicted"
+        "flow_origins"?: Set<String>,            // "mcp_tool_result" | "model" | "file" | "database" | "user"
+        "flow_sink"?: String,                    // "external_model" | "local_model" | "external_mcp" | "trusted_mcp" | "user_secure_output" | "public_network" | "file"
+        "flow_sink_is_external"?: Boolean,
+        "flow_sink_effects"?: Set<String>,       // "network.send" | "financial.transfer" | "filesystem.write" | ...
+        "principal_clearances"?: Set<String>,    // ADR 0020 D8 — clearances AuthN mints for the principal
+        "principal_compartments"?: Set<String>,  // ADR 0020 D8 — compartments the principal is admitted to
+
         // Usage Budget — multi-window token & cost enforcement (optional)
         "budget_remaining_pct"?: Long,
         "budget_exceeded"?: Boolean,
@@ -247,6 +275,12 @@ namespace AgentOps {
         "budget_exceeded_daily"?: Boolean,
         "budget_exceeded_monthly"?: Boolean,
 
+        // Rate Limiting — gateway-metered, Shield-decided (ADR 0014)
+        "rpm_remaining_pct"?: Long,
+        "rpm_exceeded"?: Boolean,
+        "tpm_remaining_pct"?: Long,
+        "tpm_exceeded"?: Boolean,
+
         // Agent Identity — authenticated agent principal metadata (optional)
         "agent_id"?: String,
         "agent_type"?: String,           // "orchestrator" | "autonomous" | "tool_agent" | "human_proxy"
@@ -391,6 +425,21 @@ namespace AgentOps {
         "session_original_request"?: String,
         "session_max_sensitivity"?: String,
 
+        // Data-Flow Labels — per-value information-flow facts (ADR 0020, optional).
+        // All optional: guard every access with `has` — an absent-attribute read is
+        // a Cedar evaluation error and an errored forbid is silently skipped (fail-open).
+        "flow_confidentiality"?: String,         // "public" | "internal" | "confidential" | "restricted" | "unknown"
+        "flow_integrity"?: String,               // "trusted" | "untrusted" | "mixed" | "unknown"
+        "flow_data_types"?: Set<String>,         // "pii" | "secrets" | "source_code" | "financial" | "health" | ...
+        "flow_compartments"?: Set<String>,       // "tenant:*" | "customer:*" | "project:*"
+        "flow_resolution_status"?: String,       // "known" | "inferred" | "unknown" | "conflicted"
+        "flow_origins"?: Set<String>,            // "mcp_tool_result" | "model" | "file" | "database" | "user"
+        "flow_sink"?: String,                    // "external_model" | "local_model" | "external_mcp" | "trusted_mcp" | "user_secure_output" | "public_network" | "file"
+        "flow_sink_is_external"?: Boolean,
+        "flow_sink_effects"?: Set<String>,       // "network.send" | "financial.transfer" | "filesystem.write" | ...
+        "principal_clearances"?: Set<String>,    // ADR 0020 D8 — clearances AuthN mints for the principal
+        "principal_compartments"?: Set<String>,  // ADR 0020 D8 — compartments the principal is admitted to
+
         // Usage Budget (optional)
         "budget_remaining_pct"?: Long,
         "budget_exceeded"?: Boolean,
@@ -405,6 +454,12 @@ namespace AgentOps {
         "budget_exceeded_daily"?: Boolean,
         "budget_exceeded_monthly"?: Boolean,
 
+        // Rate Limiting — gateway-metered, Shield-decided (ADR 0014)
+        "rpm_remaining_pct"?: Long,
+        "rpm_exceeded"?: Boolean,
+        "tpm_remaining_pct"?: Long,
+        "tpm_exceeded"?: Boolean,
+
         // Aggregated threat summary (optional)
         "highest_severity"?: String,
         "threat_count"?: Long,
@@ -477,6 +532,21 @@ namespace AgentOps {
         "session_original_request"?: String,
         "session_max_sensitivity"?: String,
 
+        // Data-Flow Labels — per-value information-flow facts (ADR 0020, optional).
+        // All optional: guard every access with `has` — an absent-attribute read is
+        // a Cedar evaluation error and an errored forbid is silently skipped (fail-open).
+        "flow_confidentiality"?: String,         // "public" | "internal" | "confidential" | "restricted" | "unknown"
+        "flow_integrity"?: String,               // "trusted" | "untrusted" | "mixed" | "unknown"
+        "flow_data_types"?: Set<String>,         // "pii" | "secrets" | "source_code" | "financial" | "health" | ...
+        "flow_compartments"?: Set<String>,       // "tenant:*" | "customer:*" | "project:*"
+        "flow_resolution_status"?: String,       // "known" | "inferred" | "unknown" | "conflicted"
+        "flow_origins"?: Set<String>,            // "mcp_tool_result" | "model" | "file" | "database" | "user"
+        "flow_sink"?: String,                    // "external_model" | "local_model" | "external_mcp" | "trusted_mcp" | "user_secure_output" | "public_network" | "file"
+        "flow_sink_is_external"?: Boolean,
+        "flow_sink_effects"?: Set<String>,       // "network.send" | "financial.transfer" | "filesystem.write" | ...
+        "principal_clearances"?: Set<String>,    // ADR 0020 D8 — clearances AuthN mints for the principal
+        "principal_compartments"?: Set<String>,  // ADR 0020 D8 — compartments the principal is admitted to
+
         // Usage Budget (optional)
         "budget_remaining_pct"?: Long,
         "budget_exceeded"?: Boolean,
@@ -491,6 +561,12 @@ namespace AgentOps {
         "budget_exceeded_daily"?: Boolean,
         "budget_exceeded_monthly"?: Boolean,
 
+        // Rate Limiting — gateway-metered, Shield-decided (ADR 0014)
+        "rpm_remaining_pct"?: Long,
+        "rpm_exceeded"?: Boolean,
+        "tpm_remaining_pct"?: Long,
+        "tpm_exceeded"?: Boolean,
+
         // Agent Identity (optional)
         "agent_id"?: String,
         "agent_type"?: String,
@@ -559,6 +635,21 @@ namespace AgentOps {
         "session_original_request"?: String,
         "session_max_sensitivity"?: String,
 
+        // Data-Flow Labels — per-value information-flow facts (ADR 0020, optional).
+        // All optional: guard every access with `has` — an absent-attribute read is
+        // a Cedar evaluation error and an errored forbid is silently skipped (fail-open).
+        "flow_confidentiality"?: String,         // "public" | "internal" | "confidential" | "restricted" | "unknown"
+        "flow_integrity"?: String,               // "trusted" | "untrusted" | "mixed" | "unknown"
+        "flow_data_types"?: Set<String>,         // "pii" | "secrets" | "source_code" | "financial" | "health" | ...
+        "flow_compartments"?: Set<String>,       // "tenant:*" | "customer:*" | "project:*"
+        "flow_resolution_status"?: String,       // "known" | "inferred" | "unknown" | "conflicted"
+        "flow_origins"?: Set<String>,            // "mcp_tool_result" | "model" | "file" | "database" | "user"
+        "flow_sink"?: String,                    // "external_model" | "local_model" | "external_mcp" | "trusted_mcp" | "user_secure_output" | "public_network" | "file"
+        "flow_sink_is_external"?: Boolean,
+        "flow_sink_effects"?: Set<String>,       // "network.send" | "financial.transfer" | "filesystem.write" | ...
+        "principal_clearances"?: Set<String>,    // ADR 0020 D8 — clearances AuthN mints for the principal
+        "principal_compartments"?: Set<String>,  // ADR 0020 D8 — compartments the principal is admitted to
+
         // Usage Budget (optional)
         "budget_remaining_pct"?: Long,
         "budget_exceeded"?: Boolean,
@@ -573,6 +664,12 @@ namespace AgentOps {
         "budget_exceeded_daily"?: Boolean,
         "budget_exceeded_monthly"?: Boolean,
 
+        // Rate Limiting — gateway-metered, Shield-decided (ADR 0014)
+        "rpm_remaining_pct"?: Long,
+        "rpm_exceeded"?: Boolean,
+        "tpm_remaining_pct"?: Long,
+        "tpm_exceeded"?: Boolean,
+
         // Agent Identity (optional)
         "agent_id"?: String,
         "agent_type"?: String,
@@ -641,6 +738,21 @@ namespace AgentOps {
         "session_original_request"?: String,
         "session_max_sensitivity"?: String,
 
+        // Data-Flow Labels — per-value information-flow facts (ADR 0020, optional).
+        // All optional: guard every access with `has` — an absent-attribute read is
+        // a Cedar evaluation error and an errored forbid is silently skipped (fail-open).
+        "flow_confidentiality"?: String,         // "public" | "internal" | "confidential" | "restricted" | "unknown"
+        "flow_integrity"?: String,               // "trusted" | "untrusted" | "mixed" | "unknown"
+        "flow_data_types"?: Set<String>,         // "pii" | "secrets" | "source_code" | "financial" | "health" | ...
+        "flow_compartments"?: Set<String>,       // "tenant:*" | "customer:*" | "project:*"
+        "flow_resolution_status"?: String,       // "known" | "inferred" | "unknown" | "conflicted"
+        "flow_origins"?: Set<String>,            // "mcp_tool_result" | "model" | "file" | "database" | "user"
+        "flow_sink"?: String,                    // "external_model" | "local_model" | "external_mcp" | "trusted_mcp" | "user_secure_output" | "public_network" | "file"
+        "flow_sink_is_external"?: Boolean,
+        "flow_sink_effects"?: Set<String>,       // "network.send" | "financial.transfer" | "filesystem.write" | ...
+        "principal_clearances"?: Set<String>,    // ADR 0020 D8 — clearances AuthN mints for the principal
+        "principal_compartments"?: Set<String>,  // ADR 0020 D8 — compartments the principal is admitted to
+
         // Usage Budget (optional)
         "budget_remaining_pct"?: Long,
         "budget_exceeded"?: Boolean,
@@ -655,6 +767,12 @@ namespace AgentOps {
         "budget_exceeded_daily"?: Boolean,
         "budget_exceeded_monthly"?: Boolean,
 
+        // Rate Limiting — gateway-metered, Shield-decided (ADR 0014)
+        "rpm_remaining_pct"?: Long,
+        "rpm_exceeded"?: Boolean,
+        "tpm_remaining_pct"?: Long,
+        "tpm_exceeded"?: Boolean,
+
         // Agent Identity (optional)
         "agent_id"?: String,
         "agent_type"?: String,
@@ -663,4 +781,53 @@ namespace AgentOps {
         "agent_publisher"?: String,
 
     };
+
+    /// Context for provision_sandbox action (Forge sandbox-create envelope).
+    ///
+    /// Every capability field below is OPTIONAL and describes the envelope the
+    /// sandbox is being asked to provision with — Forge synthesizes it from the
+    /// create request attenuated by the token's scope ceiling (ADR 0019 D1),
+    /// then asks Cedar whether this identity may provision it. Profile templates
+    /// `permit` provision_sandbox only when the requested envelope stays within
+    /// the profile ceiling, and `forbid` any escalation beyond it.
+    ///
+    /// FAIL-OPEN WARNING (ADR 0019 D3): because these attributes are optional,
+    /// accessing an absent one is a Cedar *evaluation error*, and an errored
+    /// `forbid` is silently skipped — which fails OPEN. Every rule touching a
+    /// field here MUST guard it first with `has` (e.g.
+    /// `context has mechanism_capabilities && context.mechanism_capabilities.contains("sys:ptrace")`).
+    type ProvisionSandboxContext = {
+        // Identity (AARM R6 / CAP-IDN-011) — projected from the principal's token; optional.
+        "role"?: String,
+        "privilege_scope"?: Set<String>,
+        "identity_type"?: String,        // Principal identity class: "human" | "agent" | "service" | "mcp_server"
+        "principal"?: String,            // Stable principal identifier (ZeroID / WIMSE URI or user id)
+        "agent_trust_level"?: String,    // "untrusted" | "low" | "verified" | "trusted"
+
+        // Core metadata (required)
+        "request_id": String,
+        "timestamp": Long,
+
+        // Requested isolation tier (required) — the OS-isolation tier the
+        // sandbox will run at, as the lowercased Forge IsolationTier name (ADR
+        // 0016 D1). Ordinal, weakest→strongest: "none" (trusted-local) < "os"
+        // (bwrap/seatbelt) < "kernel" (gVisor) < "hardware" (micro-VM + TEE).
+        // Templates assert a floor via set membership (e.g. a KERNEL floor =
+        // {"kernel","hardware"}); Forge owns the ordering.
+        "isolation_tier": String,
+
+        // Requested capability envelope (all optional — has-guard mandatory).
+        "writable_paths"?: Set<String>,        // Writable path prefixes, e.g. {"/scratch"}
+        // Master egress switch. Forge MUST set this true whenever ANY egress is
+        // requested (i.e. whenever egress_hosts is non-empty), so a "no network"
+        // profile can gate on this single boolean. egress_hosts then narrows the
+        // host allowlist for profiles that DO permit egress.
+        "network_egress"?: Boolean,
+        "egress_hosts"?: Set<String>,          // Host allowlist for egress, e.g. {"pypi.org"}
+        "exec_allowlist"?: Set<String>,        // Executables the sandbox may run, e.g. {"python", "python3"}
+        // Curated mechanism toggles (ADR 0017 D1.3) — authorization facts only;
+        // NEVER raw syscalls. Allowed members: "sys:ptrace", "sys:bpf",
+        // "sys:raw_socket", "dev:gpu", "virt:nested".
+        "mechanism_capabilities"?: Set<String>,
+    };
 }