Restricted Session Scope for agents¶

When an agent acts on behalf of a user, it inherits the user’s full privileges by default. That can include write access to production databases, elevated roles such as ACCOUNTADMIN, or access to data that shouldn’t enter an LLM context. An agent’s work is usually narrower than the user’s full privilege set, so that inheritance can create governance risk without any change to the user’s roles.

A Restricted Session Scope (RSS) is a privilege ceiling that limits what an agent can do on behalf of a user. An RSS doesn’t replace RBAC and can’t grant privileges the user doesn’t already have through their roles.

You can apply an RSS in two ways. Both use the same ceiling model; they differ in who configures the restriction and how it is applied:

Admin-managed RSS is a standing governance control: it applies whenever an agent is active for users covered by the session policy. User-managed RSS lets an individual tighten their own CoCo session, for example to work against production data in read-only mode or to block elevated roles for that session.

If both apply to the same session, Snowflake enforces the intersection of the admin ceiling and the user restriction. A user can’t grant the agent more access than the admin ceiling allows.

AGENT_RESTRICTED_SESSION_SCOPE on a session policy applies only when an agent is active. When no agent is active, that property is ignored. For when SYS_CONTEXT('SNOWFLAKE$CURRENT', 'IS_AGENT_ACTIVATED') returns TRUE, see IS_AGENT_ACTIVATED (SYS_CONTEXT function).

In short:

• RSS is a privilege ceiling for agents. It intersects with RBAC and never grants more privileges than the user’s roles already allow.
• Admins set a standing ceiling with session policies. End users can further restrict their own CoCo sessions.
• When both are present, the effective privilege set is the intersection of both ceilings.

Benefits¶

Restricted Session Scope helps you:

• Set a privilege ceiling for agents without changing user roles (admin-managed).
• Let individual users self-limit a CoCo session when they hold elevated roles or work against production data (user-managed).
• Reduce unintended production writes, privilege escalation through secondary roles, and access to sensitive data from agent workflows.
• Keep full RBAC available when no agent is active in the session, or when no RSS is applied.
• Apply different agent ceilings account-wide or to specific users through session policy attachment.

Access this feature¶

This feature is in private preview and available only to selected accounts. To request access, contact your Snowflake account team.

User-managed RSS also requires a client that supports the preview, and you must turn on the Restricted Session Scope experimental setting in that client:

Admin-managed RSS (session policy)¶

Use this scenario when you want an organization-wide or per-user privilege ceiling for agent sessions. An administrator sets AGENT_RESTRICTED_SESSION_SCOPE on a session policy, then attaches that policy to the account or to users.

To apply an RSS when an agent is active:

1. Set AGENT_RESTRICTED_SESSION_SCOPE on a session policy.
2. Attach the session policy to the account or to a user.

You can specify the scope value in any of these ways:

1. Reference a Snowflake predefined scope (easiest starting point).
2. Create an RSS object and reference it by fully qualified name.
3. Embed the RSS YAML inline in the session policy.

RSS YAML structure¶

An RSS is defined as a YAML document with two top-level sections:

privilege scopes:
  allowed privileges:
    - privileges: [<group_privilege>]
      account: [all]            # or databases: [...] or schemas: [...]
  # Optional: extend a predefined scope, then add more privileges
  # extend: [SNOWFLAKE$DATA_READ]
role scopes:
  blocked roles: [<role>, ...]  # or allowed roles: [...]
  allow role switching: false   # default: true

• Privilege scopes: Categories of operations that are allowed and the containers they apply to (account-wide, specific databases, or specific schemas). Operations that aren’t listed are implicitly denied. In privilege scopes, you can do either of the following:
  • Use a predefined scope (for example, SNOWFLAKE$DATA_READ): a Snowflake-managed, coarse package of allowed operations you can reference by name or extend.
  • Use group privileges (for example, data read, data write, program usage): named categories of Snowflake operations you list explicitly when you need a custom ceiling.
• Role scopes: Roles that can be activated while an agent is active. You can allow specific roles, block specific roles, or disable role switching.

After an RSS is activated for agent activity in a session, it’s immutable for the lifetime of that session. It can’t be changed, unset, or escalated. To apply a different scope, close the session and open a new one.

Create an RSS object and reference it¶

Creating an RSS requires the CREATE RESTRICTED SESSION SCOPE privilege on the parent schema. If you later update the RSS object, policies that reference it pick up the change for new agent activity.

CREATE RESTRICTED SESSION SCOPE mydb.governance.agent_scope AS $$
privilege scopes:
  allowed privileges:
    - privileges: [data read]
      account: [all]
    - privileges: [data write]
      databases: [SANDBOX_DB]
    - privileges: [program usage]
      account: [all]
role scopes:
  blocked roles: [ACCOUNTADMIN, SYSADMIN, SECURITYADMIN]
  allow role switching: false
$$;

CREATE SESSION POLICY mydb.governance.agent_policy
  AGENT_RESTRICTED_SESSION_SCOPE = 'MYDB.GOVERNANCE.AGENT_SCOPE';

Embed the RSS YAML inline¶

Define the scope directly in the session policy without creating a separate object. Useful for simple or one-off configurations.

CREATE SESSION POLICY mydb.governance.agent_policy
  AGENT_RESTRICTED_SESSION_SCOPE = $$
privilege scopes:
  allowed privileges:
    - privileges: [data read]
      account: [all]
$$;

Attach the session policy to the account or a user¶

Account-level (default for users without a user-level override):

ALTER ACCOUNT SET SESSION POLICY mydb.governance.agent_policy;

Per-user (overrides the account-level policy for that user):

ALTER USER <user_name> SET SESSION POLICY mydb.governance.per_user_agent_policy;

When a user-level session policy is present, its AGENT_RESTRICTED_SESSION_SCOPE is used exclusively. The account-level policy isn’t consulted or merged for that user.

Predefined scopes¶

Snowflake provides coarse-grained predefined scopes you can reference directly in a session policy, without creating an RSS object. You can also extend a predefined scope inside a custom RSS YAML definition. CoCo CLI also exposes these predefined scopes when you restrict a session.

SNOWFLAKE$DATA_READ_WITH_AI excludes stored procedures because they may run with owner’s rights and can’t guarantee read-only execution.

CREATE SESSION POLICY mydb.governance.agent_policy
  AGENT_RESTRICTED_SESSION_SCOPE = 'SNOWFLAKE$DATA_READ';

For the YAML that backs each predefined scope, see Appendix: Predefined scope YAML.

Group privileges for custom scopes¶

When you create an RSS object or embed YAML inline, privilege scopes use group privileges: named categories of operations that map to high-level caller privileges. See that topic for detailed descriptions of each category.

Some group privileges can naturally overlap or subsume others. For example, object management subsumes object discovery and compute usage. UPDATE and DELETE require the ability to read existing data and can’t be authorized by data write alone; use data read in conjunction when those operations are needed.

Containers: Privileges can be scoped account-wide (account: [all]), to specific databases (databases: [db1, db2]), or to specific schemas (schemas: [db1.public, db1.private]). Defining access to a schema implicitly grants access to its parent database. Warehouses are implicitly allowed regardless of privilege scope.

Intersection behavior: The effective privileges while an agent is active are the intersection of the user’s RBAC privileges and every active RSS. An RSS never expands what RBAC already allows.

Role scopes:

Admin example scenarios¶

Account-wide read-only for agents¶

Use this as a conservative baseline when agents should read and analyze data but not write, create objects, or modify anything in the account.

CREATE SESSION POLICY mydb.governance.agent_readonly_policy
  AGENT_RESTRICTED_SESSION_SCOPE = 'SNOWFLAKE$DATA_READ';

ALTER ACCOUNT SET SESSION POLICY mydb.governance.agent_readonly_policy;

To also allow AI and agent usage:

CREATE SESSION POLICY mydb.governance.agent_ai_readonly_policy
  AGENT_RESTRICTED_SESSION_SCOPE = 'SNOWFLAKE$DATA_READ_WITH_AI';

ALTER ACCOUNT SET SESSION POLICY mydb.governance.agent_ai_readonly_policy;

Production read-only, write allowed in a sandbox¶

Allow agents to assist with data engineering work while confining writes to designated development or sandbox databases.

CREATE RESTRICTED SESSION SCOPE mydb.governance.prod_readonly_sandbox_write AS $$
privilege scopes:
  allowed privileges:
    - privileges: [data read]
      account: [all]
    - privileges: [data write]
      databases: [AGENT_SANDBOX_DB, DEV_DB]
    - privileges: [program usage]
      account: [all]
$$;

CREATE SESSION POLICY mydb.governance.agent_prod_policy
  AGENT_RESTRICTED_SESSION_SCOPE = 'MYDB.GOVERNANCE.PROD_READONLY_SANDBOX_WRITE';

ALTER ACCOUNT SET SESSION POLICY mydb.governance.agent_prod_policy;

Block privileged roles when an agent is active¶

Prevent elevated roles such as ACCOUNTADMIN, SYSADMIN, or SECURITYADMIN from being activated while an agent is active, even when the user holds those roles.

CREATE RESTRICTED SESSION SCOPE mydb.governance.no_privilege_escalation AS $$
privilege scopes:
  allowed privileges:
    - privileges: [data read]
      account: [all]
    - privileges: [data write]
      databases: [DEV_DB, SANDBOX_DB]
    - privileges: [program usage]
      account: [all]
role scopes:
  blocked roles: [ACCOUNTADMIN, SYSADMIN, SECURITYADMIN, ORGADMIN]
  allow role switching: false
$$;

CREATE SESSION POLICY mydb.governance.no_privesc_policy
  AGENT_RESTRICTED_SESSION_SCOPE = 'MYDB.GOVERNANCE.NO_PRIVILEGE_ESCALATION';

ALTER ACCOUNT SET SESSION POLICY mydb.governance.no_privesc_policy;

Allow data work, block grant and object management¶

Allow read, sandbox write, and program usage, while leaving grant management and object management implicitly denied.

CREATE RESTRICTED SESSION SCOPE mydb.governance.data_operations_only AS $$
privilege scopes:
  allowed privileges:
    - privileges: [data read]
      account: [all]
    - privileges: [data write]
      databases: [SANDBOX_DB, DEV_DB]
    - privileges: [program usage]
      account: [all]
role scopes:
  blocked roles: [ACCOUNTADMIN, SECURITYADMIN]
$$;

CREATE SESSION POLICY mydb.governance.data_ops_policy
  AGENT_RESTRICTED_SESSION_SCOPE = 'MYDB.GOVERNANCE.DATA_OPERATIONS_ONLY';

ALTER ACCOUNT SET SESSION POLICY mydb.governance.data_ops_policy;

Restrict access to approved databases¶

Limit what an agent can reach to databases approved for AI use. Databases that aren’t listed are inaccessible while the agent is active, even if the user’s roles grant SELECT on them.

CREATE RESTRICTED SESSION SCOPE mydb.governance.ai_approved_databases AS $$
privilege scopes:
  allowed privileges:
    - privileges: [data read]
      databases: [ANALYTICS_DB, REPORTING_DB, METRICS_DB]
    - privileges: [data write]
      databases: [AGENT_SANDBOX_DB]
    - privileges: [program usage]
      databases: [ANALYTICS_DB, REPORTING_DB]
$$;

CREATE SESSION POLICY mydb.governance.ai_scope_policy
  AGENT_RESTRICTED_SESSION_SCOPE = 'MYDB.GOVERNANCE.AI_APPROVED_DATABASES';

ALTER ACCOUNT SET SESSION POLICY mydb.governance.ai_scope_policy;

Pair this with masking policies that use SYS_CONTEXT('SNOWFLAKE$CURRENT', 'IS_AGENT_ACTIVATED') on sensitive columns within approved databases. RSS controls which databases and operations the agent can reach; agent-aware masking controls which column values are visible within those databases.

User-managed RSS (CoCo)¶

Use this scenario when you want to restrict what CoCo can do in your session, without waiting for an account-wide session policy. In this private preview, user-managed RSS is available in CoCo CLI and in CoCo Desktop 1.21.0 or later.

User-managed RSS is useful when:

• You hold elevated roles (for example, SYSADMIN or ACCOUNTADMIN) and don’t want the agent to use them while you explore data or write queries.
• You’re working against production data and want read-only agent access for that session.
• Your organization hasn’t deployed admin-managed agent ceilings yet, and you want to self-enforce least privilege today.

User-managed RSS doesn’t replace an admin-managed ceiling. If a session policy also sets AGENT_RESTRICTED_SESSION_SCOPE, Snowflake applies both and enforces their intersection.

Your account must be enabled for the private preview before user-managed RSS works in either client. Turning on the client setting alone isn’t enough.

Enable the preview in CoCo CLI¶

In this private preview, start CoCo CLI with the Restricted Session Scope experimental feature flags:

CORTEX_CODE_EXPERIMENTAL_FEATURES='{"restrictedSessionScope":true,"restrictedSessionScopeChildSessions":true}' cortex

You can also export the variable first, then start CoCo:

export CORTEX_CODE_EXPERIMENTAL_FEATURES='{"restrictedSessionScope":true,"restrictedSessionScopeChildSessions":true}'
cortex

Without these flags, /guardrails and --with-restricted-session-scope aren’t available.

Enable the preview in CoCo Desktop¶

CoCo Desktop 1.21.0 or later supports user-managed RSS behind an experimental setting. To turn it on:

1. Update CoCo Desktop to 1.21.0 or later. See Cortex Code Desktop v1.21.0 release notes.
2. Open App Settings, then search for restricted.
3. Turn on Restricted Session Scope: Enabled.

With this setting on, CoCo runs agent SQL in an isolated Snowflake session for each chat, so agent session state such as roles, temporary tables, and session variables doesn’t mix with the SQL you run yourself. Agent SQL fails when CoCo can’t establish that isolated session. Turning the setting off restores the shared session.

What you can configure¶

In this private preview, CoCo CLI and CoCo Desktop support the following restrictions:

• SQL read-only mode: Apply a predefined scope such as SNOWFLAKE$DATA_READ_WITH_AI so the agent can query data and use AI-related objects, but can’t write, create, or drop objects, or run stored procedures.
• Role allowlist: Limit the session to roles you explicitly allow.
• Role blocklist: Suppress specific roles for the session.

Role allow and block lists apply to roles that are granted directly to you. If a role is available only through nested role inheritance (not a direct grant), listing it by name doesn’t suppress or enable those privileges. Plan allowlists and blocklists around your direct grants.

Restrict the current CoCo CLI session¶

1. Start CoCo CLI with the experimental feature flags described in Enable the preview in CoCo CLI, then run /guardrails.
2. Choose one of the following:
   • Restrict this session: Apply an existing RSS definition, or enable SQL read-only mode with a predefined scope such as SNOWFLAKE$DATA_READ_WITH_AI.
   • Create new restricted session scope: Build a named RSS that allows or blocks roles, and optionally enable SQL read-only mode. CoCo shows a live YAML preview of the definition as you configure it.
3. If you create a new RSS, give it a name (for example, READONLY_PM). CoCo stores the definition in your personal database under USER$<username>.RSS, so you can reuse it later.
4. After you create a named RSS, return to Restrict this session and select that definition to activate it.

You can ask CoCo to guide you through the steps with /guardrails-help. CoCo can’t apply or remove the restriction on your behalf. Applying RSS must be an explicit action in the CoCo harness so the agent can’t lift its own ceiling.

To see the active restriction, use /guardrails status.

Restrict the current CoCo Desktop session¶

After you turn on the experimental setting, restrict the current chat from the composer:

1. Select +, then Restrict this session.
2. Choose one of the following:
   • Read only: Apply a read-only ceiling for this chat without selecting an existing RSS.
   • Restrict by role: Choose how to configure role restrictions:
     • Use existing restriction: Apply a previous allowlist or blocklist saved in USER$<username>.RSS. You can reuse a definition you created in CoCo Desktop, in CoCo CLI, or directly in Snowflake.
     • Create custom restriction: Search for and select roles, then choose Allow or Block for each. CoCo stores the named definition in USER$<username>.RSS so you can reuse it later from Desktop, CLI, or SQL.

CoCo can’t apply or remove the restriction on your behalf. Applying RSS must be an explicit action in the CoCo harness so the agent can’t lift its own ceiling.

Apply RSS when you start CoCo CLI¶

Reuse a named RSS at startup. Keep the experimental feature flags set. For definitions stored in USER$<username>.RSS, you can pass the bare name; CoCo adds the personal-database prefix:

CORTEX_CODE_EXPERIMENTAL_FEATURES='{"restrictedSessionScope":true,"restrictedSessionScopeChildSessions":true}' \
  cortex --with-restricted-session-scope=READONLY_PM

Change or clear a user-managed RSS¶

After an RSS is active in a CoCo session, you can switch to a different RSS through the Restrict this session flow (CLI /guardrails, or + then Restrict this session in Desktop), but you can’t remove the restriction from the current session. To clear the restriction, start a new CoCo session without applying an RSS.

Considerations¶

• An RSS is a ceiling on the user’s existing RBAC privileges. It never grants additional privileges.
• AGENT_RESTRICTED_SESSION_SCOPE on a session policy applies only when an agent is active (SYS_CONTEXT('SNOWFLAKE$CURRENT', 'IS_AGENT_ACTIVATED') returns TRUE). When no agent is active, the property is ignored. For the contexts that set this value, see IS_AGENT_ACTIVATED (SYS_CONTEXT function).
• Session policies are evaluated for each action. If an agent becomes active during a session, Snowflake applies the RSS for actions the agent attempts while IS_AGENT_ACTIVATED is TRUE.
• If a user has a user-level session policy, that policy fully overrides the account-level policy for that user. The two aren’t merged.
• If the session policy doesn’t set AGENT_RESTRICTED_SESSION_SCOPE, no admin-managed agent scope is applied. While an agent is active, the agent has the same data access as when no agent is active under the same policy, unless a user-managed RSS is also active.
• If an admin-managed RSS and a user-managed RSS both apply, Snowflake enforces their intersection. The user can’t exceed the admin ceiling from a CoCo client.
• If an RSS object referenced by fully qualified name is dropped, the session policy keeps the reference, but enforcement is disabled until you update the property or recreate the object. DESCRIBE output for the policy reflects a dropped-object placeholder.
• Once an RSS is active for agent activity in a session, it can’t be escalated. Close the session and open a new one to apply a different scope or to clear a user-managed restriction.
• Role allowlists and blocklists apply to roles granted directly to the user. Nested inheritance alone isn’t enough for a named role to be allowed or blocked.
• RSS and agent-aware masking policies are complementary. RSS controls access scope; masking controls data visibility within that scope.
• For third-party agents, IS_AGENT_ACTIVATED returns TRUE when the connection goes through the Snowflake MCP Server or an OAuth security integration with IS_AGENTIC = TRUE. Agents that connect through REST APIs or SDKs with standard authentication (key pair or personal access token) and neither of those mechanisms currently activate the agent context, unless the session uses a SERVICE_AGENT user.
• In this private preview, user-managed RSS is available in CoCo CLI and in CoCo Desktop 1.21.0 or later. Admin-managed RSS applies to agent-active sessions covered by the session policy, regardless of client.
• Both clients require your account to be enabled for the private preview, plus the Restricted Session Scope experimental setting in the client.

Current limitations¶

• If an agent invokes a job or application that runs in Snowpark Container Services (SPCS), the RSS is dropped for that workload and the agent ceiling no longer applies. Snowflake is actively addressing this gap.
• User-managed RSS is available only in CoCo CLI and CoCo Desktop in this private preview. CoCo in Snowsight isn’t supported yet. Support for that client is in progress.
• CoCo Desktop support requires version 1.21.0 or later. Earlier versions don’t expose the setting.
• In CoCo CLI, user-managed RSS requires the CORTEX_CODE_EXPERIMENTAL_FEATURES flags described in Enable the preview in CoCo CLI.

Provide feedback¶

As a private preview participant, your feedback shapes how this feature develops before general availability. Snowflake is especially interested in feedback on:

1. Whether the admin and CoCo scenarios cover the governance configurations your organization needs
2. Whether the group privileges are the right set, or whether operations are missing
3. Whether the predefined scopes (SNOWFLAKE$DATA_READ, SNOWFLAKE$DATA_READ_WITH_AI, and SNOWFLAKE$DATA_READ_PROGRAM_USAGE) are sufficient starting points
4. How difficult it is to define custom RSS YAML or to configure CoCo guardrails for your requirements

Appendix: Predefined scope YAML¶

The following YAML shows the effective privilege shape of each Snowflake predefined scope. Use these definitions when you need to understand or extend a built-in scope.

SNOWFLAKE$DATA_READ¶

privilege scopes:
  allowed privileges:
    - privileges: [data read]
      account:
        - all

SNOWFLAKE$DATA_READ_PROGRAM_USAGE¶

privilege scopes:
  allowed privileges:
    - privileges: [data read]
      account:
        - all
    - privileges: [program usage]
      account:
        - all

SNOWFLAKE$DATA_READ_WITH_AI¶

privilege scopes:
  allowed privileges:
    - privileges: [data read]
      account:
        - all
    - privileges: [usage]
      object_types: [agent, mcp server, cortex search service]
      account:
        - all
    - privileges: [object discovery]
      account:
        - all