[Matovidlo]

Why

Query Service rules no longer select readers by email: an identity provider can assert any email, so a rule of a new rls-policy / cls-policy (schema 1.2.0, go-monorepo #668, Query Service RFC decision 34) selects by subjects (<idp>|<sub>) or by IdP groups. kbagent authors these policies, so kbagent rls / kbagent cls follow. Linear: AJDA-3680. Stacked on #778; retarget to main once it merges.

What changes

• rls|cls create|update --rules refuse principal / principals with INVALID_ARGUMENT (exit 2) before anything is read or written; the message names subjects and says how to find one. The stored rules of an update that keeps them (for example a --default change on a 1.1.0 policy) are not refused.
• Validation follows the 1.2.0 schema: exactly one of subjects / groups per rule; a subjects entry is <idp>|<sub> (the schema pattern, at most 1024 characters) or *; * is the only entry of its list. subjects against a metastore older than 1.2.0 is refused locally (--dry-run too) with a message that says so; the live schema is the source of truth, kbagent does not guess the version.
• list / detail / --dry-run show subjects: / groups:; a policy stored at 1.0.0 / 1.1.0 still shows its email selector, flagged legacy email selector (not allowed in a new policy).
• rls setup asks for subjects, groups or everyone (never an email).
• Documentation surfaces: kbagent context (AGENT_CONTEXT), CLAUDE.md, docs/cli-manifest.json, commands-reference.md, gotchas.md (a new (since vNEXT) entry), rls-workflow.md, keboola-expert.md, docs/error-codes.md, docs/web-server-endpoints.md. No version bump, no changelog entry.

Assumptions (to confirm)

• An administrator behind a Storage token is keboola|<user id> (RFC decision 34); the id is the member id of kbagent project member-list (needs a Manage token). There is no new command for it: the help and the workflow say it.
• An app user's subject is <idp>|<sub> as apps-proxy sends it and cannot be read off the identity provider, so group rules and ["*"] are the practical selectors until user discovery exists (AJDA-3565).
• Existing 1.1.0 policies with principal(s) keep working in the enforcement; there is no automatic migration (an email cannot be turned into a subject). To change their rules, recreate the policy.
• The e2e test now authors group rules.

Checks

• tests/test_rls_service.py, test_rls_cli.py, test_cls_cli.py, test_cls_service.py, test_server_rls.py, test_server_cls.py, the bindings tests, test_check_command_sync.py and test_skill_frontmatter.py pass (394 passed); ruff check, ruff format --check, check_command_sync, check_version_gates, check_file_size, check_sentinel_guards, check_error_codes pass.
• check_cli_spec.py reports 17 target.project-not-required problems for rls/cls commands: they exist on the feat(CLI-17): add kbagent rls command group + guided setup skill #778 branch already (that rule came with main) and are not touched here.
• Not run: the e2e test (needs a stack); it is meaningful only on a stack whose Metastore has schema 1.2.0 and whose engine and Query Service have go-monorepo fix(serve,ui): keep the UI session alive across server restarts (cache-proof shell + 401 self-heal) #668, so do not release before that is deployed.

---

🤖 Generated with Claude Code

[linear-code]

AJDA-3680

[keboola-pr-reviewer-bot]

Verdict: needs_human (risk 3/5) · profile _default

Needs human: a backward-incompatible change to a published CLI/SDK security-policy contract, gated on a backend deployment that must land first.

Impact flags: possible rollback re-introduction — see Check Run summary.