Skip to content

feat!: a command that grants access asks first, and its tool asks for a person - #571

Merged
bim-ba merged 1 commit into
mainfrom
feat/grants-access
Oct 10, 2026
Merged

bim-ba merged 1 commit into
mainfrom
feat/grants-access

Conversation

@bim-ba

@bim-ba bim-ba commented Oct 10, 2026 •

Copy link
Copy Markdown
Owner

A command that grants access now asks before it sends, as a delete does, and its MCP tool is marked so that the client asks a person. Decisions: #556 (1-A, 3: thirteen operations by metadata, 4-A), #495 (15).

The mark

An operation that lets someone at data they could not reach says so beside its effect, in its endpoints.py: Endpoint(..., grants_access=True) or RPC(..., grants_access=True). Nothing else names these operations: there is no list of them in src/.

# Operation
1-2 forms.access.grant, forms.access.update
3-4 wiki.access.create, wiki.access.update
5 tracker.queues.permissions_update
6-7 tracker.entities.permissions_update, permissions_update_direct
8-10 datalens.{workbooks,collections,sharedentries}.access_bindings_update
11 datalens.licensing.licenses_assign
12 datalens.embeds.create, datalens.embeds.update
13 datalens.embeddingsecrets.create

Thirteen operations of the decision, fourteen endpoint functions. Not marked, as decided: forms.surveys.publish, the revokes, and wiki.pages.update with an access policy in its body.

What follows from it

Surface Before After
CLI, a terminal sent at once POST …/pages/7/access — this grants access. Continue?
CLI, no terminal sent at once exit 2: … this grants access. Pass --yes to confirm; there is no terminal to ask on.
CLI, --yes - sent, nothing asked
CLI, --dry-run the plan the plan, nothing asked
MCP tool annotations only also _meta["anthropic/requiresUserInteraction"] = true, and one sentence in its description
MCP, --tool-search every tool behind search_tools / call_tool the marked tools stay listed by their own names with the mark; the search does not offer them; the proxy refuses one: this tool grants access: call it by its own name, so that the client can ask a person
SDK sent sent; a caller who gave the guard a confirm is asked for these too

A delete keeps its own words ("this deletes data"). The three Tracker permission updates ask even when the body only takes rights away: the mark is of the operation, and their help says so.

The key a client reads

_meta["anthropic/requiresUserInteraction"], read from the vendor's page on 2026-10-10 (code.claude.com/docs/en/mcp, "Require approval for a specific tool"; Claude Code v2.1.214 or later):

  • the prompt is shown on every call, also in acceptEdits, auto and bypassPermissions, with no "don't ask again"; allow rules do not skip it;
  • in dontAsk mode the call is denied, and with --permission-prompt-tool an allow becomes a deny. So a headless agent cannot grant access through these fourteen tools; the CLI with --yes is the way, after a person agreed;
  • other clients pass the key by, which is why the description says it in words: "Grants access: a client that honours the mark asks a person on every call."

Under tool search (found in review)

ycli mcp start --tool-search replaces the listing with a search and a proxy that runs what was found. A client reads the mark from a tool's own entry, so behind the proxy nobody was asked: call_tool {"name": "wiki_access_create", …} sent the grant. Now the marked tools are read from their mark and kept in the listing, and the proxy looks at the mark of what it is asked to run. A write that grants nothing still goes through the proxy.

Not changed here, a fact for ARCH-3: the proxy carries no annotations at all, so a delete run through call_tool has no destructiveHint either (measured: tracker_boards_delete through the proxy is sent).

ARCH-3 changes, with its check (flagged)

ARCHITECTURE.md, ARCH-3, gains the rule and its check in this PR.

Check What it holds Seen failing
the contract test, every case a tool carries the mark if and only if an endpoint it sent has grants_access; the sentence is in its description on the same condition the mark taken off wiki_access_create: "the mark is False, the operation True"; the mark put on wiki_access_delete: "the mark is True, the operation False"
test_the_help_of_a_command_says_it_grants_access_where_its_tool_is_marked the help of a command says it exactly where its tool is marked, over every case; fourteen in all -
test_cli_guard.py the prompt and the no-terminal refusal, each with its own words for a grant and for a delete; --yes; --dry-run asks nobody, through the real entry point -
test_mcp_selection.py under tool search the fourteen are listed with the mark, each is refused by the proxy with nothing sent, the search offers none, an unmarked write goes through; none is served with --read-only red before the fix: the listing held 4 tools and the grant was sent
test_guard.py the core asks for a grant and tells the one asked which it is; the reason is no field of the plan -

Why the reason is not a field of the plan: --dry-run prints the plan, and the table formats derive columns from fields.

Breaking change

The fourteen commands ask for confirmation. A script that called one without a terminal now exits 2.

# before
$ ycli wiki access create 7 --role reader --user-uid 9001
# after
$ ycli wiki access create 7 --role reader --user-uid 9001 --yes

SDK signatures and MCP input schemas do not change.

Shared documents and checks touched

ARCHITECTURE.md (ARCH-3), docs/en|ru/how-to/script-the-cli.md, the yandex-360 skill and its rulesync renders, the generated CLI / MCP reference, docs/en|ru/how-to/use-in-ci.md, the help of --yes on every command, tests/contract/ (one helper, confirmed(case), decides --yes in every contract test that runs a command: the four places in test_contract.py and test_output_formats.py).

Verified

On this head, over main 97c329f3 (0.139.0): ruff, ty, lint-imports (6 kept), ast-grep, pydoclint, gitleaks, rulesync and the generated reference without drift; the full suite: 7047 passed, 5 skipped, coverage 100 %.

The live run below is of the first head of this PR; it was not repeated after the review fixes, which change the server under tool search, help texts and docs.

Live (2026-10-10, output kept): the seven scenarios that call a marked command. 5 passed, 4 skipped.

Scenario Marked steps Ran live
forms/form-content access update (open to all), access grant access update ran; access grant skipped: needs GRANTEE
tracker/queue-parts queues permissions-update skipped: needs a second account (GRANTEE)
tracker/entity-parts entities permissions-update, -direct skipped: needs GRANTEE
wiki/page-content access create, access update skipped: needs GRANTEE
datalens/* (three scenarios) bindings, embeds, the key NOT RUN: no Yandex Cloud credentials on this machine

So one of the fourteen ran live here; CI runs the rest where the variables are set. The live runner passes --yes to every step (e2e/runner.py), so the prompt itself and the no-terminal refusal are held by unit tests only, never by a live run.

NOT RUN: the full live run over every service; any check in a real Claude Code session that the key produces the prompt (the vendor's page is the evidence).

🤖 Generated with Claude Code

… a person

An operation that lets someone at data they could not reach says so beside its
effect, `grants_access=True`, in its `endpoints.py`. Fourteen do today: access
to a form and to a Wiki page, permissions of a Tracker queue and of an entity,
access bindings of a DataLens workbook, collection and shared entry, the
assignment of a licence, an embedding and its key (#556). Nothing else names
them: no list of operations exists.

From that one mark:

- the CLI asks before it sends such a request, as before a delete, in words of
  its own ("this grants access"); `--yes` skips the question, and with no
  terminal the command exits 2 and says to pass `--yes`. `--dry-run` asks
  nothing. The help of the command says it.
- the tool carries `_meta["anthropic/requiresUserInteraction"]`, which Claude
  Code answers by asking a person on every call, in every permission mode, and
  by denying the call where nobody can be asked. Its description says so in
  words for clients that do not read the key.
  Under `--tool-search` such a tool stays in the listing by its own name, with
  its mark, and the proxy that runs what the search found refuses it: behind
  the proxy there would be no entry for a client to read the mark from.
- the SDK asks whoever gave it a `confirm`, and nobody otherwise.

The three Tracker permission updates ask even when the body only takes rights
away: the mark is of the operation.

ARCH-3 holds it honest the way it holds effects: the contract test compares the
mark of every tool with what its operation says, both ways, and the help of
every command with the mark of its tool.

BREAKING CHANGE: the fourteen commands that grant access ask for confirmation.
A script that called one without a terminal now exits 2:

    before: ycli wiki access create 7 --role reader --user-uid 9001
    after:  ycli wiki access create 7 --role reader --user-uid 9001 --yes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch was previously deployed

1 inactive deployment
yandex-e2e — 8646ab97 Deployed Oct 10, 2026 by bim-ba via live (all) #710
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant