Restricted Session Scope for agents¶

This page documents user-managed Restricted Session Scope (RSS) in CoCo CLI and CoCo Desktop. That client experience is in private preview.

Admin-managed RSS (session policies, YAML privilege ceilings, SQL DDL, and predefined scopes) is generally available. For that content, see Restricted Session Scope for agents.

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

If an admin-managed RSS and a user-managed RSS both apply to the same session, Snowflake enforces the intersection. You can’t grant the agent more access than the admin ceiling allows.

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.

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.

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:

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.
• If an admin-managed RSS and a user-managed RSS both apply, Snowflake enforces their intersection. You can’t exceed the admin ceiling from a CoCo client. For admin-managed RSS, see Restricted Session Scope for agents.
• 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.
• In this private preview, user-managed RSS is available in CoCo CLI and in CoCo Desktop 1.21.0 or later.
• Both clients require your account to be enabled for the private preview, plus the Restricted Session Scope experimental setting in the client.

Current limitations¶

• 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 CoCo CLI and CoCo Desktop flows cover the session restrictions you need
2. How difficult it is to configure CoCo guardrails for your requirements
3. Gaps between user-managed RSS in CoCo and admin-managed RSS