ai: apply changes for #932 (1 review thread)

Addresses:
  - #3860320318 at src/databricks/sql/client.py:230

Signed-off-by: peco-engineer-bot[bot] <peco-engineer-bot[bot]@users.noreply.github.com>

Author: peco-engineer-bot[bot]

CONNECTION_PARAMETERS.md

@@ -82,7 +82,7 @@ to change without notice.
 | `credentials_provider`                              | `CredentialsProvider`|   ✅   |   ❌   | `None`                    | Custom external credentials provider. **Rejected on the kernel path** (`NotSupportedError`) — it is an opaque token source, so the kernel cannot own the token lifecycle; use `oauth_client_id` + `oauth_client_secret` for M2M, or the Thrift backend. |
 | `identity_federation_client_id`                     | `str`                |   ✅   |   ✅   | `None`                    | Workload identity / token-federation client id (kernel support added in #910).                                                                                 |
 | `experimental_oauth_persistence`                    | `OAuthPersistence`   |   ✅   |   ❌   | `None`                    | **Thrift-only.** The kernel owns its own token lifecycle and does not accept a persistence store.                                                              |
-| `oauth_token_cache_enabled`                         | `bool \| None`       |   ❌   |   ✅   | `None`                    | **Kernel-only, U2M-only.** Controls whether the kernel persists OAuth U2M refresh tokens to disk (AES-256 encrypted, at `~/.config/databricks-sql-kernel/oauth/`, requires databricks-sql-kernel PR #283). **Disabled by default:** when unset (None) or False, the connector disables on-disk persistence (tokens in-memory only, matching Thrift); True enables the cache. Omitting it does **not** inherit the kernel's enabled-by-default. Distinct from `experimental_oauth_persistence` — this toggles the kernel's built-in encrypted storage, not a pluggable callback.  |
+| `oauth_token_cache_enabled`                         | `bool \| None`       |   ❌   |   ✅   | `None`                    | **Kernel-only, U2M-only.** Controls whether the kernel persists OAuth U2M refresh tokens to disk (AES-256 encrypted, in the OS config dir — `~/Library/Application Support/databricks-sql-kernel/oauth/` on macOS, `~/.config/databricks-sql-kernel/oauth/` on Linux; requires databricks-sql-kernel PR #283). **Disabled by default:** when unset (None) or False, the connector disables on-disk persistence (tokens in-memory only, matching Thrift); True enables the cache. Omitting it does **not** inherit the kernel's enabled-by-default. Distinct from `experimental_oauth_persistence` — this toggles the kernel's built-in encrypted storage, not a pluggable callback.  |
 | `azure_client_id` / `azure_client_secret` / `azure_tenant_id` | `str` | ✅ | ✅ | `None` | Azure service-principal (Entra ID M2M), selected by `auth_type="azure-sp-m2m"`. On the kernel path the connector forwards these to the kernel, which owns Azure resolution (Entra v2.0 token endpoint + the Databricks-resource `.default` scope) (#919). **`azure_tenant_id` is optional on the kernel path too** — like Thrift, the kernel auto-discovers it from the workspace's `/aad/auth` redirect when omitted. |
 | `azure_workspace_resource_id`                       | `str`                |   ✅   |   ✅   | `None`                    | For `azure-sp-m2m`. When set, the SP **management token** (`X-Databricks-Azure-SP-Management-Token`) + `X-Databricks-Azure-Workspace-Resource-Id` header are sent, to authorize an SP that has an Azure RBAC role but is not a workspace member. Omit it for a workspace-member SP (the data token authenticates alone; no management token is fetched). Works on both the kernel and Thrift paths. |
 | `_use_cert_as_auth` (+ `_tls_client_cert_file`)     | `bool`               |   ✅   |   ❌   | `False`                   | Authenticate with a TLS client certificate instead of a token. Thrift-only.                                                                                    |

src/databricks/sql/client.py

@@ -227,7 +227,9 @@ def read(self) -> Optional[OAuthToken]:
                 ```
             :param oauth_token_cache_enabled: `bool | None`, optional (default is None)
                 **Kernel-only, U2M-only.** Controls whether the kernel persists OAuth U2M
-                refresh tokens to disk (AES-256 encrypted, at `~/.config/databricks-sql-kernel/oauth/`).
+                refresh tokens to disk (AES-256 encrypted). The cache lives in the
+                OS config directory: `~/Library/Application Support/databricks-sql-kernel/oauth/`
+                on macOS, `~/.config/databricks-sql-kernel/oauth/` on Linux.
                 When unset (None, the default), the connector treats this as False and
                 forwards `token_cache_enabled=False` to the kernel, so on-disk caching is
                 disabled by default — matching the Thrift posture and avoiding silently

src/databricks/sql/session.py

@@ -187,7 +187,9 @@ def _create_backend(
                     "identity_federation_client_id"
                 ),
                 # OAuth U2M token-cache enable/disable: controls whether the kernel
-                # persists U2M refresh tokens to disk (encrypted, at ~/.config/databricks-sql-kernel/oauth/).
+                # persists U2M refresh tokens to disk (encrypted, in the OS config dir:
+                # ~/Library/Application Support/databricks-sql-kernel/oauth/ on macOS,
+                # ~/.config/databricks-sql-kernel/oauth/ on Linux).
                 # A typed Optional[bool]; on the oauth-u2m branch omitted/None
                 # ⇒ token_cache_enabled=False (disabled, in-memory only) — the
                 # opt-in default that preserves backward compat when token