Skip to content

📌 feat: Pin an Allowed Schedule Tool to the Definition It First Ran With - #18273

Merged
danny-avila merged 5 commits into
devfrom
danny-avila/consent-definition-pins
Nov 18, 2026
Merged

danny-avila merged 5 commits into
devfrom
danny-avila/consent-definition-pins

Conversation

@danny-avila

@danny-avila danny-avila commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

An owner allows a scheduled chat's MCP tools by name. Since #18260 nothing ties that name to what the tool does: a server can change an allowed tool's description, schema or behaviour hints and the schedule keeps calling it with the owner's credentials while nobody is watching.

This PR ties each allowed tool to its definition. The first authorized use of a tool stores a SHA-256 of its whole live definition on the grant. Every later use compares the live definition with that pin. A tool whose definition differs is refused before tools/call, marked as changed on the grant, and stays refused until the owner confirms again, even if the server restores the old definition.

The consent dialog names the changed tool and leaves it unticked. Ticking it and confirming accepts what the server offers now; the tool is pinned afresh at its next use.

Fourth step of the unattended-authority work, after #18058, #18255 and #18260. Related to #13824 and #16157.

How it works

authorize (activation preflight, invoke, resume)        # packages/api/src/schedules/authorization
  execution.ts   digest = sha256(canonical(live tool definition))
  service.ts     tool marked changed              -> binding_mismatch
                 pin exists, digest differs       -> mark changed, binding_mismatch
                 admission write                  -> also refuses a tool marked or pinned to
                                                     another digest since the grant was read
                 no pin yet                       -> store pin (first writer wins)
                 pin lost to another replica      -> stored pin matches: authorized
                                                     stored pin differs: mark changed, binding_mismatch
// One consent (one server) inside Schedule.mcpConsent. Both fields are optional and additive.
definitions?: { tool: string; digest: string }[]; // written once per tool, never rewritten
changedTools?: string[];                          // refused until the owner confirms again
GET /api/schedules/:id/mcp-consent
  state    'changed' when any allowed tool is marked
  changed  { warehouse: ['run_query'] }            # new field, by server

The two writes are single-document updates fenced on the live grant revision and consent id: $push only when the tool has no pin, $addToSet only when it has one. Neither changes the grant's revision or deadline.

A use reads the grant and is then admitted by a separate write. That write now carries the definitions in use (admitScheduleMCPConsent({ definitions })) and matches only while none of those tools is marked or pinned to a different digest, so a mark or a first pin stored between the read and the admission refuses the use. A use refused this way marks the tool when the stored pin disagrees with what it saw.

Confirming and revoking replace the grant whole, built from an earlier read. Pins and marks are only ever added within a grant revision, so both writes match only while each consent's definitions and changedTools are no longer than they were at that read. A confirmation that loses reports the offer as changed and the dialog reads it again; a revocation reads again and retries.

Confirming again keeps the pins of tools that were not marked, as long as the server binding is the same. A renewal therefore cannot quietly accept a definition that was swapped since the last run. A marked tool the owner allows again loses its pin and is pinned at its next use.

A confirmation is bound to the marks the owner was shown. The offer digest covers the changed tools by server, so a dialog opened before a tool was marked cannot confirm past the mark: the confirm is rejected as stale, the dialog reads the offer again, and the tool appears unticked with its warning. An offer with nothing marked keeps the digest it had before this change. In the dialog, a tick on a marked tool counts only if it was made with that mark in view: a tool marked while the owner is choosing, or marked again under a grant confirmed elsewhere, loses its tick until they tick it again.

When two replicas use a tool for the first time with different definitions, one pin is stored. The replica that lost marks the tool as changed, so the disagreement is refused on every replica and shown to the owner instead of only failing that one call.

definitions and changedTools are bounded by the same per-server tool limit as the allowed tools, in the stored schema and in the pin write.

The pin is checked only where a live catalog is read. Minting a credential for a server is not blocked by one changed tool, and the grant's other tools stay allowed.

The refusal uses the existing binding_mismatch reason (mcp_reauth_required, recovery authorize), the same one a changed server URL or issuer produces. No new failure reason is added.

Type of change

  • Feature

Testing

Tested environments/configuration: WSL2, Node.js 24. Storage tests run against mongodb-memory-server. No external services.

Automated tests:

  • packages/api/src/schedules/authorization/service.spec.ts (definition pins): pin on first use; refusal and changed view on a different digest; still refused after the old definition returns; only the changed tool is refused and minting still works; a renewal keeps unmarked pins and re-pins a marked tool the owner allows again; pins are dropped when the server binding changes; a pin another replica wrote first is accepted only when it matches, and a mismatch marks the tool so the next view reports it as changed; a first use whose pin could not be stored is not authorized; a use whose tool is marked after it read the grant is refused; a first use beaten by another definition is refused and marks the tool without attempting its own pin; a confirmation does not drop a pin or a mark stored while it was being made; a dialog opened before a tool was marked cannot confirm past the mark; an offer with nothing marked keeps its digest.
  • packages/api/src/schedules/authorization/execution.spec.ts: the real execution path pins the live definition; key order is not a change; a new description, input schema or annotation is; the other agent's use of the same tool is refused too.
  • packages/api/src/mcp/__tests__/MCPManager.test.ts: a changed definition is refused at the manager boundary without reaching tools/call.
  • packages/data-schemas/src/methods/scheduleConsent.spec.ts (definition pins): first pin wins, including among six concurrent writers; the mark needs an existing pin and does not rewrite it; nothing is written to a revoked or replaced grant; a malformed pin is rejected before the write; admission passes only while the tool in use is unmarked and pinned to the same digest; a confirmation built from a grant that has since gained a pin or a mark is refused; a revocation keeps a pin stored between its read and its write; revision and deadline are untouched; only classic update operators are used.
  • packages/data-provider/src/types/scheduleConsent.spec.ts: a stored grant parses with or without pins, and a pin holds nothing but a tool name and a digest.
  • client/src/components/SidePanel/Schedules/__tests__/Consent.spec.tsx: a changed tool starts unticked with its note as the checkbox description, and is sent once ticked; a tool marked while the owner is choosing is unticked until they tick it again; so is a tool the owner accepted that is marked again under a later grant; the changed tools are named when there is nothing to confirm.

Each new check was broken in turn (across service, storage, execution and the dialog) and a test confirmed to fail.

npx tsc --noEmit is clean in packages/api, packages/data-schemas, packages/data-provider and client.

Screenshots / recordings

The real Consent component under the app's stylesheet in Chromium, fed fixed consent data in place of the API. "Before" is the component and strings from #18260 with the same grant. The Cancel button shows its key because the capture does not initialise the shared package's i18n; the app does.

Before (#18260) After, light After, dark
before after, light after, dark

When the owner cannot confirm (no offer), the changed tools are listed:

after, nothing to confirm

Risk / compatibility

Trust on first use. The consent offer does not connect to the server, so the definition that gets pinned is the one seen at the first authorized use, not one the owner read. The dialog still shows tool names only. The pin protects against a change after that point.

A changed tool stops a schedule until the owner acts. That is the intent, but a server that legitimately edits a description will also trigger it. The refusal reports mcp_reauth_required, like any other binding change.

A tool the owner removes from the grant loses its pin. Allowing it again later pins it afresh at its next use.

Existing grants have no pins and are pinned at their next use. No migration.

Mixed versions: the stored grant gains two optional fields, and the stored schema is strict. A replica without this change reads a grant that has pins as incompatible and refuses its runs, which fails closed. Upgrade every replica before schedules with consent run, as #16681 already requires.

Schedule consent is off by default (interface.schedules.mcpConsent.enabled).

@danny-avila

Copy link
Copy Markdown
Collaborator Author

@codex review 5c1a461

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-18T14:43:38.349402Z 912414f Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5c1a461562

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +172 to +174
const definitions = prior.definitions.filter(
(pin) => allowed.has(pin.tool) && !prior.changedTools?.includes(pin.tool),
);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Invalidate outstanding offers when a tool is marked changed

If the owner opens the consent dialog before a run detects a changed definition, submitting that old dialog silently authorizes the changed tool. Pin/changed-tool writes leave the enrollment revision unchanged, and the offer digest covers only identity, schedule configuration and targets, so confirm() accepts the stale offer. This filter then removes the newly flagged tool's pin even though the owner never saw its warning or explicitly rechecked it; its next invocation pins and executes the new definition. Bind confirmation to the changed-tool state the owner actually reviewed and reject stale submissions.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 234f503. The offer digest now covers the changed tools by server (offerDigest in packages/api/src/schedules/authorization/service.ts), in both view and confirm, so a dialog opened before a tool was marked cannot confirm past the mark: the confirm is rejected as stale and the dialog reads the offer again, where the tool is unticked with its warning. An offer with nothing marked keeps the digest it had before.

Evidence: service.spec.ts › definition pins › "does not let a dialog opened before a tool was marked confirm past the mark" and "keeps the digest of an offer in which nothing is marked". Removing changed from the digest makes the first fail.

Same class, in the dialog (ec4ecf8): a tool marked while the owner is choosing now loses its tick until they tick it again (currentChoice in Consent.tsx, test "unticks a tool that is marked as changed while the owner is choosing, until they tick it again").

Comment on lines +477 to +479
unpinned.some(([tool, digest]) => !pinned(latest.consent, tool, digest))
)
return denial('binding_mismatch');

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Persist a change marker after a conflicting first-use race

When two concurrent first uses observe different definitions, the losing pin write rereads the winner's digest and returns binding_mismatch here without calling flagScheduleMCPToolChange. Consequently, the consent view still reports no changed tools and subsequent calls matching the winning definition remain authorized, despite the service having observed conflicting definitions. This bypasses the sticky refusal applied by the earlier mismatch branch. Persist the change marker against the same live consent before returning for a conflicting stored digest.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 234f503. When the pin write loses to another replica, authorize reads the grant again and, for each tool whose stored pin differs from the definition this replica saw, calls flagScheduleMCPToolChange before returning binding_mismatch. The tool is then refused on every replica and the consent view reports it under changed, instead of one call failing silently.

Evidence: service.spec.ts › definition pins › the two-replica race test now asserts the loser marks the tool, the winner's definition is refused afterwards, and view returns the tool in changed. Removing the flag call makes it fail.

Base automatically changed from danny-avila/consent-owner-rules to dev November 18, 2026 13:44
@danny-avila
danny-avila marked this pull request as ready for review November 18, 2026 13:44
The dialog reads the offer again while it is open. A tool marked as changed after the
owner's last tick kept its tick, so confirming would have allowed the new definition
without the warning having been in view when the box was ticked. The edit now records
which tools were marked when it was made, and a tool marked since then is unticked
until the owner ticks it again.
@danny-avila
danny-avila force-pushed the danny-avila/consent-definition-pins branch from 5c1a461 to ec4ecf8 Compare November 18, 2026 13:59
@danny-avila

Copy link
Copy Markdown
Collaborator Author

@codex review ec4ecf8

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ec4ecf80d9

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +362 to +366
...carriedPins(
target,
snapshot.enrollment?.consents.find(
(prior) => prior.resource.serverName === target.resource.serverName,
),

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Preserve pins written concurrently with confirmation

If a tool's first invocation stores its pin after confirm() takes this snapshot but before the confirmation write, carriedPins() uses the unpinned snapshot and the confirmation erases the newly stored pin. confirmScheduleMCPConsent() replaces the entire enrollment and only compares enrollment/config revisions, neither of which the pin write changes. The next invocation can therefore pin and execute a different definition without reporting a change, despite the promise that renewals preserve unmarked pins. Fence confirmation against concurrent pin writes or preserve those pins atomically when replacing the enrollment.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 66e75d6. confirmScheduleMCPConsent takes the grant the new one was built from (basis) and its write matches only while each consent's definitions and changedTools are no longer than they were at that read (untouchedSince in packages/data-schemas/src/methods/scheduleConsent.ts). Both lists only grow within a grant revision, so any pin or mark stored in between fails the write; confirm reports consent_changed and the dialog reads the offer again. The same fence is on the revocation write, which had the same read-then-replace shape and now reads again instead of dropping the pin.

Evidence: scheduleConsent.spec.ts › "refuses a confirmation built from a grant that has since gained a pin or a mark" and "revokes without dropping a pin stored between its read and its write" (real MongoDB via mongodb-memory-server); service.spec.ts › "does not let a confirmation drop a pin or a mark stored while it was being made". Removing the fence from either write, or basis from the service call, fails the matching test.

Comment on lines +458 to +461
for (const [tool, digest] of live) {
if (consent.changedTools?.includes(tool)) return denial('binding_mismatch');
const pin = consent.definitions?.find((entry) => entry.tool === tool);
if (!pin || pin.digest === digest) continue;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Check changed-tool markers at the atomic admission boundary

With concurrent invocations, a request using the pinned definition can read an unmarked consent, then another request can detect a different definition and persist the changed marker before the first request reaches admission. This check still uses the old snapshot, and admitScheduleMCPConsent() checks neither changed markers nor a revision advanced by marker writes. Since an already-pinned tool also skips the subsequent pin-write reread, the first request remains authorized after the sticky refusal was committed. Include the selected tools' changed state in the atomic admission predicate so a marker committed before admission prevents execution.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 66e75d6. admitScheduleMCPConsent now receives the definitions in use and its predicate matches the consent only while none of those tools is in changedTools or pinned to another digest (unchangedDefinitions), in the same write that admits. A use refused there marks the tool when the stored pin disagrees with what it saw, so a first use beaten by a different definition is reported to the owner too.

Evidence: scheduleConsent.spec.ts › "admits a tool only while it is unmarked and pinned to the definition in use"; service.spec.ts › "refuses a use whose tool was marked after it read the grant" and "refuses and marks a first use that another first use beat with a different definition". Removing the predicate, the definitions argument, or the mark each fails a test.

A use read the grant, then was admitted by a write that looked at neither the marks nor
the pins. A mark or a first pin stored in between did not stop it. Admission now carries
the definitions in use and refuses, in the same write, a tool that is marked or pinned to
another digest. A use refused this way marks the tool when the stored pin disagrees with
what it saw.

A confirmation and a revocation replace the grant whole, built from an earlier read. A
pin or mark a run added in between was dropped, so the next use could pin a different
definition unnoticed. Both writes now refuse when either list has grown since the read:
the confirmation reports the offer as changed, and the revocation reads again.
@danny-avila

Copy link
Copy Markdown
Collaborator Author

@codex review 66e75d6

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 66e75d669e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +80 to +84
const seen = edited.changed[serverName] ?? [];
return [
serverName,
(edited[serverName] ?? initial[serverName]).filter((tool) => offered.includes(tool)),
(edited.choice[serverName] ?? initial[serverName]).filter(
(tool) => offered.includes(tool) && (!marked.includes(tool) || seen.includes(tool)),

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Scope remembered changed-tool acknowledgments to the grant revision

If the owner ticks a marked tool, then another tab confirms that tool and a subsequent run marks it changed again, the original dialog retains its tick. edited.changed remembers only tool names, so seen.includes(tool) treats the second change as already acknowledged even though it belongs to a different grant. The consent query periodically refetches, and commit() uses the refreshed revision and offer digest, so submitting this dialog successfully clears the new marker without requiring another explicit tick. Store the grant revision with Edited and discard acknowledgments when that revision changes.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 912414f. The edit now records the grant revision it was made against (Edited.revision in Consent.tsx), and currentChoice counts a tick on a marked tool only when the mark was in view under that same revision. A tool marked again under a grant confirmed elsewhere is unticked, the confirm button is disabled if nothing else is ticked, and the owner has to tick it again with the warning shown.

Evidence: Consent.spec.tsx › "unticks a tool the owner accepted once it is marked again under a later grant". Dropping the revision comparison makes it fail.

The dialog remembered which tools were marked when the owner last ticked a box, by name
only. If the grant was replaced elsewhere and a run marked the same tool again, the old
tick stood and confirming accepted a change the owner had not looked at. The edit now
records the grant revision, and a tool marked under another revision is unticked until
the owner ticks it again.
@danny-avila

Copy link
Copy Markdown
Collaborator Author

@codex review 912414f

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Breezy!

Reviewed commit: 912414fcca

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@danny-avila

Copy link
Copy Markdown
Collaborator Author

/quality risk scopes=api

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Quality report

Gate: open. The selected checks completed. Scores and risk levels are advisory.

Status: completed (success). Actions run, attempt 1.

  • Commit: 912414fcca97f993f4a306469ec7a50f9bf838d1
  • Requested by: @danny-avila
  • Check: risk
  • Scopes: api
  • Static mutants: off (not used by change risk)
  • Change risk: api
  • Mutation testing (experimental, data-schemas only): none

Change risk

Takeaway: 2 changed lines have no test. Highest CRAP among changed functions: authorize at packages/api/src/schedules/authorization/service.ts:403, CRAP 59.6 with 85% coverage.

Workspace Files measured Incomplete Unavailable Changed lines with no test Highest CRAP
api 4 of 4 0 0 2 59.6

Changed lines with no test

packages/api/src/schedules/authorization/service.ts: 2 lines (api)

Line 294

          changed: changedByServer,

Line 305

          changed: changedByServer,

Refactor hints (highest CRAP first)

Function Complexity Coverage CRAP Location
authorize 51 85% 59.6 packages/api/src/schedules/authorization/service.ts:403
view 34 88% 35.8 packages/api/src/schedules/authorization/service.ts:235
authorize 31 87% 33.0 packages/api/src/schedules/authorization/execution.ts:194
confirm 15 83% 16.0 packages/api/src/schedules/authorization/service.ts:325
carriedPins 5 100% 5.0 packages/api/src/schedules/authorization/service.ts:168
pinned 5 100% 5.0 packages/api/src/schedules/authorization/service.ts:456
(anonymous) 2 100% 2.0 packages/api/src/schedules/authorization/service.ts:158
(anonymous) 2 100% 2.0 packages/api/src/schedules/authorization/service.ts:176
offerDigest 2 100% 2.0 packages/api/src/schedules/authorization/service.ts:186
(anonymous) 2 100% 2.0 packages/api/src/schedules/authorization/service.ts:360

17 more functions below the threshold (or cut for size) are in report.md.

CRAP = complexity² × (1 − coverage)³ + complexity

Jobs (1)
Check Result
Change risk (api) success

All data (quality-report artifact) · Run page

The gate opens only when the workflow, source selection, tooling verification, and every report job succeed. A report job fails on a failed test in its workspace's own Jest run, a tool error, a job timeout, or an incomplete mutation report, including a mutation shard that reaches its execution budget. A cancelled workflow keeps the gate closed. Scores are advisory. A change-risk file marked incomplete or unavailable, for example by a failed api/ source-alias suite, does not close the gate.

@danny-avila
danny-avila merged commit 4dbfc04 into dev Nov 18, 2026
70 checks passed
@danny-avila
danny-avila deleted the danny-avila/consent-definition-pins branch November 18, 2026 15:21
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