Skip to content

feat(crew-api): let the owner answer tool approvals without a dashboard - #39962

Merged
bolichen97 merged 1 commit into
mainfrom
crew/headless-crew/owner-approvals
Nov 20, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
crew/headless-crew/owner-approvals

Conversation

@buluoray

@buluoray buluoray commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: On a Kiro Crew with no dashboard, the owner of the machine can list the tool approvals that are waiting, read one, and answer it with allow or deny, over the Crew API.

A tool approval is the gateway pausing before a tool call until a person says yes. Today a person answers it on the dashboard: the routes behind the approval card name a request by an id its caller chose, which can repeat, plus the session and the card it was shown on. A gateway that runs without a dashboard has no card, so a turn that asks for an approval waits until it times out.

Why it matters

A Kiro Crew on a server is only useful to an app on that machine if its owner can still say yes or no to a tool call. This is the last approval piece of "a Kiro Crew with no dashboard that an app on the same machine can use".

Not a goal

  • No allow_always. It stays a proposal.
  • No answer from a Shared Crew teammate. Only the host owner lists, reads and answers.
  • No approval routes for apps (/v1/crew/approvals), no embed credential, no events.
  • No conv_ ids, no expires_at, no final field in the 409 body.
  • No approval that survives a gateway restart. The turn that waited is gone.
  • No dashboard page, and no change to who passes any existing gate or to the dashboard's own approval routes.

What changed (motivation → approach → change)

Goal: one id per approval that an owner without a dashboard can list, read and answer, and that never answers a different request.

Approach: the gateway keeps an approval in memory in two places, under a caller-chosen id that repeats: a background request (a cron job's, a subagent's, a task gate) and a chat turn's own tool prompt. Each already has a name that does not repeat: the record's instance, and the mid of the prompt's row. So the new routes give each request one apr_ id the first time they see it, keep it in memory with that name, and answer through the resolvers the dashboard already uses.

The ids live for the life of the gateway process. Every step that reads what is waiting and updates the ids runs on the event loop with no await in it, so two calls cannot interleave. Keeping the ids across a restart is left to a later change.

RFC amendment, proposed. It needs a maintainer to accept it. Merging this PR accepts these changes to rfc-crew-api.md and assets/crew-api/crew-owner.yaml:

  1. Three new Owner operations: GET /v1/crew/owner/approvals, GET /v1/crew/owner/approvals/{approval_id}, POST /v1/crew/owner/approvals/{approval_id}/decision. They are listed under "Routes outside the 59".
  2. The decision takes allow or deny only.
  3. Host owner only: a Shared Crew teammate, an app credential and a loopback internal caller get 403 owner_only.
  4. An apr_ id lives for the life of the gateway process; after a restart it is 404. A record that survives a restart is proposed and not in this amendment.
  5. conversation is the session's key until the conversation operations exist. expires_at and the 409 body's final are left out.
  6. When the turn that waited is cancelled, the approval reads expired with reason timeout, not turn_cancelled; when a Stop rejects a chat turn's own waiting prompt, it reads denied. Only one of the two approval paths records that a turn was cancelled, and reporting turn_cancelled on both needs a change to the shared interaction_coordinator, which a later PR makes.

Change:

  • dashboard/crew_api_approvals.py (new): reads the waiting requests, keeps the apr_ ids in memory, and serves the three handlers.
  • dashboard/routes/crew_api.py: the three routes.
  • shared_crew/decisions.py: resolve_pinned_slot_approval, moved out of resolve_approval_by_id unchanged.
  • test/fixtures/crew_api_owner_openapi.json, the module spec, the feature map, the RFC and crew-owner.yaml.

Behaviour, each with a test:

  • An answer goes to the request the id was given to. When that request ended and another took its caller id, the old id answers 409 and the new request stays open.
  • The first answer wins; a second gets 409. The decision's body is the settled approval, also when the id list is full.
  • deny on a chat prompt refuses that one call and the turn goes on.
  • A security-rule override card takes deny; allow is 403 approval_requires_dashboard.
  • Every answer and every 403 or 409 refusal of the decision route writes one security event row.
  • An MCP elicitation is not listed, and a session with nothing waiting never has its rows read.

dashboard/routes/crew_api.py, rfc-crew-api.md and learn-cron-dashboard.md are also changed by the open #39574. This PR does not depend on it. Whichever merges later rebases.

Size: 1674 added lines: 705 tests, 475 docs and contract, 494 source.

Backwards compatibility

Compatible: three new routes and one new function; no existing route, body or check changes. resolve_approval_by_id calls the moved code with the same arguments.

Removes nothing: the diff adds routes, a module and a function, and deletes no route, record, key or function.

Tests

test/test_crew_api_approvals.py, 49 cases:

  • an app token, another user, no credential, a loopback internal caller and three kinds of teammate get 403 owner_only on all three routes, and nothing is answered;
  • the owner lists a background request and two chat prompts with stable ids, filters by state, session and app, pages with limit and after, reads one, and gets 404 for an unknown id and 400 for a bad query; an elicitation is not listed;
  • allow and deny settle a background request once, write the audit row naming the owner, and a second answer is 409;
  • allow and deny settle a chat prompt, and the same caller id on another session stays open;
  • for both kinds, an id never answers a later request under the same caller id;
  • an ending made elsewhere reads allowed or denied with no decided_by;
  • a new gateway process answers 404 for an id the old one gave, on read and on decide, and gives the requests waiting now new ids;
  • an override card is denied here and allowed only on the dashboard;
  • the override 403 and a 409 each write exactly one denied row naming the owner and the approval; a failed audit write does not change the response;
  • with the id list full, a decision on the oldest pending approval returns the settled approval, and a read queued behind it returns the same;
  • a session with nothing waiting never has its rows read by a list call or a decision;
  • allow_always, an extra field, an empty body and a non-object answer nothing (400); a limit of 5,000 digits is 400, not 500;
  • the id list keeps pending rows and drops the oldest ended ones; a request that already has an id never gets a second.

The checks that decide whether an answer may land, and what proves each one:

Check What it refuses Test
the record's state, in decide_approval an answer to an approval that already ended test_a_record_that_is_not_pending_is_refused_before_the_answer_layer
_answer, background request: record present, same instance, same slot, future present and open a request that is gone, replaced under its caller id, or settled while its record is still there test_the_answer_layer_refuses_a_background_request_that_is_not_the_one_waiting (5 cases)
_answer, chat prompt: slot present, future present and open, same instance the same, for a chat prompt test_the_answer_layer_refuses_a_chat_prompt_that_is_not_the_one_waiting (4 cases)
the result of _answer an answer the layer refused test_an_answer_the_layer_refused_is_409_and_settles_nothing

No check on this path was taken out. The _answer tests call that layer directly, on a record the index has not caught up with, so each check decides alone; over HTTP the record's state would refuse first.

Two cases at once, each for both kinds of request:

  • two answers to one id sent together: one gets 200, the other 409, the request settles once, and a read returns the winner's body (test_two_answers_at_once_settle_the_request_once);
  • an answer that arrives after the turn ended: 409, nothing runs, the approval reads expired (test_an_answer_after_the_turn_ended_runs_nothing).

Each of 29 guards was broken in turn (the host-owner check on each route, every check in the table, the 404, the body and limit checks, the id cap, the filters, one id per request, the audit rows, the override refusal). 28 made a test fail. The one that did not is slot is None in the chat branch of _answer: without it the next term, future is None, refuses the same case, and it stays because the line after reads slot.approval_instance.

Determinism: the file passed 3 runs in a row, single process, after the last test was added. It never sleeps and every wait has a bound. test/test_flake_pattern_ratchet.py passes.

test/test_crew_api_owner.py checks every Owner route against the contract fixture.

The diff-related backend set (260 files) ran on the previous head: 13400 passed, 23 failed, 5 errors. Those 28 node ids, run alone on unmodified main 94b00be731b on the same machine, fail the same way (missing botocore and h2, and tests that start a second pytest). mypy src/kiro_crew/, the CI command, reports 3 errors here, all in src/kiro_crew/wecom/client.py, which this PR does not touch and which CI does not report; this PR's files are clean. The repository's semgrep rules were run on the first revision only, with semgrep 1.183.0 and not the pinned 1.78.0.

Manual verification

See the real-machine run below.

Real-machine verification

Machine: throwaway cloud dev machine, Amazon Linux 2023.7, x86_64, 8 vCPU
Before (main bdc65269728): with the owner's session, `GET /v1/crew/owner/approvals` -> 404 text/plain "404: Not Found" (no such route); `GET /v1/crew/owner/approvals/apr_0...0` -> the same 404; `POST /v1/crew/owner/approvals/apr_0...0/decision` -> the same 404; with no credential, all three -> 401 invalid_token; `GET /api/approvals` -> 200 []
After (first revision 9c9367650da): with no credential, list, read and decide -> 401 invalid_token each; owner lists -> 200, an empty list, has_more false; owner lists state=expired -> 200, empty; owner lists state=open -> 400 invalid_request; owner reads an unknown id -> 404 not_found in the contract error body; owner decides an unknown id -> 404 not_found; owner sends allow_always -> 400 invalid_request; `GET /api/approvals` -> 200 []; listener: 127.0.0.1:5593 only; port closed after the stop
Cleanup: the machine deleted

The run was on the first revision, 9c9367650da. The head has not been run on a real machine. It differs from that revision: the ids are kept in memory and not on disk, the decision route writes audit rows for its refusals, and a list call skips sessions with nothing waiting. The calls above touch none of that, and the in-process tests cover it.

Not verified on a real machine: answering a real pending approval, with allow and with deny. No approval was waiting on that gateway, so the list was empty on both runs. That path and the same-id check are covered by the in-process tests above only.

Related Issues

None. Follows #39564 and #39921.

Checklist

  • A Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...); PR Hygiene does not count commits
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributed under the project's Apache-2.0 license.

@buluoray
buluoray requested review from a team and KiroCrewCaptain as code owners November 20, 2026 12:30
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 20, 2026
@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision cc6644c9933367b340a167592cf9c1cedb89d19f touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of cc6644c9933367b340a167592cf9c1cedb89d19f — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: process-lifetime apr_ ids keyed on the non-repeating instance/mid answer only the request they were issued for, through the dashboard's own resolvers, and resolve_pinned_slot_approval is a pure extraction.

Notes

  • An approval only gets an id when an Owner route polls. A request that is raised and times out between two polls is never listed, so a client that polls rarely misses approvals it never sees. The PR defers events, so polling is the only signal for now; the spec should say this.
  • live_approvals reads the private registries state._pending_approvals, _approval_futures and slot.approval_instance directly. That ties this module to their internals. A small read accessor on DashboardState would keep the owner routes in step if those registries change shape.

[DESIGN-REVIEWED] cc6644c

Description read

[DESCRIPTION-READ] 621829c1a665a99ff6ff9ba6742def7b34aa693564d2b83770c217f359bff19a

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of cc6644c9933367b340a167592cf9c1cedb89d19f — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing blocks. One query filter, client_id, is not in the Goal or the RFC's approvals list. The API also lets the owner list approvals that already ended, which the Goal does not ask for.

Notes

  • Item 9 — rides along: the list route takes client_id ("Only approvals raised in sessions this app owns"). The RFC's own GET /v1/crew/approvals (crew-public.yaml) offers only state and conversation, and the Goal is to "list … read one, and answer it". Subtraction: delete the client_id query parameter from list_approvals, crew-owner.yaml and the fixture. Clears when: the mechanism is removed, or a human amends the Goal.
  • Item 10 — oversized: the Goal is to list the approvals "that are waiting", but the list also serves allowed, denied and expired, and the PR itself says the list "is not an audit trail". Subtraction: limit state to pending, and keep ended records only for as long as the read and 409 paths need them. Clears when: the mechanism is removed, or a human amends the Goal.

What this change ships

Inventory (10 items) — 8 justified

Intent: the owner of a gateway with no dashboard can see the tool approvals that are waiting and answer allow or deny through the Crew API. This is an ADDITION.

  1. The owner lists approvals over /v1/crew/owner/approvals — justified
  2. The owner reads one approval by its apr_ id — justified
  3. The owner answers allow or deny, and the first answer wins — justified
  4. Each request gets an apr_ id held in memory; after a restart an old id is 404 — justified
  5. Allow on a security-rule override card is refused with 403 approval_requires_dashboard — justified
  6. Each answer and each 403 or 409 refusal writes one security log row — justified
  7. resolve_pinned_slot_approval is moved out of resolve_approval_by_id and used by both — justified
  8. Proposed RFC amendment, contract YAML, module spec and feature-map row — justified
  9. client_id list filter — rides along; not in the Goal or the RFC's list
  10. Listing ended states (allowed, denied, expired) — oversized against the Goal's "waiting"

[FIRST-PRINCIPLES-REVIEWED] cc6644c

Description read

[DESCRIPTION-READ] 40697cf7f06b8b1919520b44a072ba7e362aedffe8d1babc34893587c614bc49

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed cc6644c9933367b340a167592cf9c1cedb89d19f — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] cc6644c

Verdict parsed from the review's SHA-scoped output markers for commit cc6644c9933367b340a167592cf9c1cedb89d19f.

False positive or not applicable? A repository writer can comment:
/ai-review override fable cc6644c9933367b340a167592cf9c1cedb89d19f false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of cc6644c9933367b340a167592cf9c1cedb89d19f and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] cc6644c

False positive or not applicable? A repository writer can comment:
/ai-review override gpt cc6644c9933367b340a167592cf9c1cedb89d19f false-positive: <reason, 20 to 500 characters>

@buluoray
buluoray force-pushed the crew/headless-crew/owner-approvals branch from 2da4fa7 to 2ce82d1 Compare November 20, 2026 13:03
@buluoray

buluoray commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor Author
  • Concurrent reads permanently lose approval outcomes (span=893396b0f0e2)

fixed in 2ce82d1: ApprovalIndex.observe keeps every ending it has seen and hands each sync a copy, so the read that writes first records the real outcome.
_records forgets an ending on the event loop only after a sync returned and its record is no longer pending.
Test: test_overlapping_reads_keep_the_watched_ending runs the two reads in the losing order, for allow and deny. It fails on 2da4fa7 (expired) and passes on the fix.
settle still records decided_by when a read wrote the decision route's own ending first; the same test checks it.

@buluoray

buluoray commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor Author
  • Valid retained approvals make every approval route unavailable (span=893396b0f0e2)

fixed in 2ce82d1: ApprovalIndex._save measures the serialized record against _STATE_MAX_BYTES, the limit _load reads with, and drops the oldest ended approvals until it fits. A pending one is never dropped.
When the pending approvals alone do not fit, _save raises before it writes, so the readable file stays and the route answers 503.
Test: test_the_byte_budget_prunes_ended_rows_and_preserves_a_readable_file uses 2,000-character CJK inputs and a small limit. It fails on 2da4fa7 and passes on the fix.

@buluoray

buluoray commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor Author
  • Approval routes are absent from the headless server (span=b827bb5075ef)

Rebutted: not a defect of this change. No Owner route is served by the --slack-only API server, and this PR keeps to that.
Evidence on main 5dfde5a: start_api_server (dashboard/server_runtime/api_entrypoint.py:355-366) registers _register_mcp_routes, three health routes and the deploy routes. register_all is called only at dashboard/server.py:950.
routes/crew_api.py and routes/local_authorization.py are registered only through register_all (routes/init.py:62-63), so the Bot roster, the grant-request routes of #39564 and the routes of #39921 answer 404 there too.
That server authenticates callers with the internal secret, not an owner credential. Serving the Owner tier there is a separate change to its auth, outside this PR's goal.
The three new routes are registered beside the existing Owner routes and are served wherever those are.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 20, 2026
@buluoray
buluoray force-pushed the crew/headless-crew/owner-approvals branch from 2ce82d1 to 09751c2 Compare November 20, 2026 13:31
@buluoray

Copy link
Copy Markdown
Contributor Author
  • Out-of-order reads expire approvals that are still waiting (span=893396b0f0e2)

fixed in 09751c2: each ApprovalIndex has one asyncio.Lock. _records holds it from the live snapshot and observe until the threaded sync has finished, and the decision route holds it across its threaded settle, so the record is written in snapshot order.
A call cancelled while its write runs keeps the lock until the worker ends (_write). The retained-endings dict of the earlier fix is removed; the lock makes it unnecessary.
Test: test_overlapping_reads_keep_the_watched_ending drives two real _records calls with the first write paused: a request that registers in between stays pending. It fails on 2ce82d1.
Test: test_a_dispatched_write_holds_the_snapshot_lock_until_finished covers sync and settle, cancelled and not.

@buluoray

Copy link
Copy Markdown
Contributor Author
  • A stale snapshot gives one request a second apr_ id (span=44927ecbe62b)

fixed in 09751c2: ApprovalIndex.sync adds the target of every record to known, whatever its state, so it gives an id only to a target with no record at all.
The same commit orders every snapshot with its write under one asyncio.Lock per index, so the stale write the finding describes no longer happens either.
Test: test_a_stale_snapshot_never_mints_an_id_for_an_ended_target covers allowed, denied and expired records. It fails on 2ce82d1.

@buluoray
buluoray force-pushed the crew/headless-crew/owner-approvals branch from 09751c2 to 599abc4 Compare November 20, 2026 13:51
@buluoray

Copy link
Copy Markdown
Contributor Author
  • Every approval route call reads every restored session's transcript on the event loop (span=44927ecbe62b)

fixed in 599abc4: live_approvals skips a slot with no approval waiting before anything reads its rows, the guard _sweep_pending_approvals uses.
The same class at the override-card check in decide_approval: it reads the slot's rows only while that request's future is still waiting.
Test: test_a_slot_with_nothing_waiting_never_has_its_rows_read makes reading such a slot's rows raise, then lists and decides. It fails on 09751c2.

@buluoray
buluoray force-pushed the crew/headless-crew/owner-approvals branch from 599abc4 to 019d69a Compare November 20, 2026 14:22
@buluoray

Copy link
Copy Markdown
Contributor Author
  • Refusing an allow on a security-rule override card writes no audit event (span=44927ecbe62b)

fixed in 019d69a: the decision route writes one SEL row for every permission decision it makes after the owner gate: crew_api.approvals.decide, outcome denied, the code in error, for the 403 approval_requires_dashboard and the 409 approval_already_resolved; outcome allowed or denied for an answer.
The row is written off the event loop, and a failed write does not change the response. A 400 or a 404 writes no row, like the grant-request routes.
Tests: test_an_override_refusal_writes_one_denied_audit_row, test_a_resolved_refusal_writes_one_denied_audit_row, test_a_failed_audit_does_not_change_the_decision_response. Removing the audit of refusals makes them fail.

@buluoray

Copy link
Copy Markdown
Contributor Author

resolution: narrowed -- the on-disk approval record leaves this PR

  • Concurrent pruning returns a pending approval after a successful decision (span=893396b0f0e2)

fixed in 019d69a: the approval ids are kept in memory only, and every index step runs on the event loop with no await in it. The worker thread, both locks and the file are gone from this PR.
After it reads its body, decide_approval checks the record, answers the request and settles the record in one step, so no list or read can run between the answer and the settle.
Test: test_a_full_index_decision_is_settled_before_a_queued_read fills the id list, queues a read behind the answer, and requires the settled body from both.
An apr_ id now lives for the life of the gateway process; after a restart it is 404. The RFC row and the PR description say so, and list a record that survives a restart as proposed, not in this change.

@buluoray
buluoray force-pushed the crew/headless-crew/owner-approvals branch from 019d69a to e3fdd92 Compare November 20, 2026 15:00
@buluoray

Copy link
Copy Markdown
Contributor Author
  • Oversized numeric limits escape validation (span=893396b0f0e2)

fixed in e3fdd92: list_approvals checks the length of limit before it converts it, so a value longer than LIMIT_MAX has digits answers 400 invalid_request, the same answer a non-digit gets.
The other caller-sent values are only compared or looked up, never converted: state, conversation, client_id, after, approval_id.
Test: the bad-query loop in test_the_owner_lists_reads_and_filters_what_is_waiting sends a 5,000-digit limit. It got 500 on 019d69a.
The same push states, in the PR description under Tests, each check on the answer path and the test that proves it. No check on that path was taken out; _answer now has direct tests, and two answers at once and an answer after the turn ended are tested for both kinds of request.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention labels Nov 20, 2026
@KiroCrewCaptain

KiroCrewCaptain commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: the decider thinks the change is probably fine but estimates a 15% chance that this change introduces a defect, above the 12% limit for approving on its own.

Adds three host-owner-only Crew API routes to list, read and answer tool approvals using in-memory apr_ ids. Access goes through owner_route and then is_host_owner_dashboard_request, the same gate as the grant-request routes. The background-request answer path repeats the dashboard's own slot/instance/open-future check; the chat-prompt path pins the exact future through resolve_on_slot, which also refuses allow on an override card. resolve_pinned_slot_approval is a faithful move and resolve_approval_by_id calls it with the same arguments. Reading what is waiting, recording endings and updating ids run in one step with no await. Pruning removes only ended records. Tests are broad and CI is green. No blocking issues found.

Tier: 2, held for a person: design-doc-gate: D.

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit cc6644c993 · 1721 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision labels Nov 20, 2026
@buluoray
buluoray force-pushed the crew/headless-crew/owner-approvals branch from e3fdd92 to 0fc8e50 Compare November 20, 2026 19:41
@buluoray
buluoray force-pushed the crew/headless-crew/owner-approvals branch from 0fc8e50 to cc6644c Compare November 20, 2026 20:24
@buluoray

Copy link
Copy Markdown
Contributor Author

class: a live registry is read by a caller id before the record is proven to be the request still waiting

  • Reject terminal approvals before inspecting a reused request id (span=893396b0f0e2)

fixed in cc6644c: decide_approval checks the record's state first. A record that is not pending answers 409 approval_already_resolved, and neither the override-card check nor _answer runs for it.
The class has four sites in this PR, and a search of the whole diff found no fifth. (1) The override-card check in decide_approval: closed by this change. (2) _answer, background branch: it compares the live record's instance and slot and requires an open future. (3) _answer, chat branch: it compares slot.approval_instance and requires an open future. (4) ApprovalIndex.sync: it matches by a target that includes the instance. resolve_pinned_slot_approval takes the future its caller chose and settles only while the slot still holds that future.
Tests: test_an_ended_id_is_409_when_an_override_card_took_its_caller_id ends a chat prompt, lets an override card take its caller id, and requires 409 with the later request still open. test_a_record_that_is_not_pending_is_refused_before_the_answer_layer runs both kinds of request with allow and deny, and requires that neither the card check nor _answer is called. Both fail on 0fc8e50 with 403 approval_requires_dashboard.
Retrospective, run read-only before this repair: span 893396b0f0e2 was answered in 4 earlier rounds and span 44927ecbe62b in 3. Every mechanism in the diff was ruled keep; nothing was removed or split out. Rounds 0, 1 and 3 of 893396b0f0e2 shared one cause, an await between reading the live registries and writing the index, which 019d69a removed. Round 4 and this one are separate defects in the same file.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 20, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

This PR adds a new way to answer tool approvals. The host owner can allow or deny a waiting tool call over the Crew API, with no dashboard. It also amends the accepted Crew API RFC: ids are held in memory only, a cancelled turn reads timeout and not turn_cancelled, and a new operation replaces the planned /api/approvals wrapper. This automated review does not approve a design that adds a path through the tool approval gate. The decision stays with the maintainers and the security reviewers. A maintainer will post the decision here.

Review result on head cc6644c: no blocking findings, and PR Readiness is green. The review read the whole diff and followed every answer path. It ran test/test_crew_api_approvals.py: 53 passed, both serially and with 4 workers. It also broke 8 guards in the new module, one at a time, to see which tests catch each one. Done well: an answer lands only on the request its apr_ id was given to (the record's instance, or the row's mid plus the pinned future). It goes through the dashboard's own resolvers. The tests cover two answers at once and a reused caller id, for both kinds of request.

For the security review:

  • All three routes pass owner_route and then is_host_owner_dashboard_request. An app token, a Shared Crew teammate and a loopback internal-secret caller each get 403 owner_only, and tests cover each one.
  • A security-rule override card refuses allow with 403 and accepts deny. Every answer, and every 403 or 409 refusal on the decision route, writes one security event row.
  • Please confirm that code inside the agent's sandbox can read no credential that passes the host-owner check. Otherwise a turn could answer its own approval.
  • The PR head was not run on a real machine. Answering a real pending approval, with allow and with deny, was never checked on one. The PR body says so.

Optional:

  • dashboard/crew_api_approvals.py:156: no test covers the string branch of _ending. Changing it to result is True keeps all 69 tests green, yet then a chat prompt approved on the dashboard (settled with "approved") would read denied. Settling a chat prompt with "approved" in the "ending made elsewhere" test would cover it.
  • The client_id list filter and response field go past the Goal and the RFC's approval list contract. Remove them, or name the caller that needs them.
  • crew-owner.yaml still marks the /api/approvals wrapper routes "required by owner clients", with an allow_always mapping. The RFC's "Owner answer paths" row is also unchanged. One line in the amendment saying the apr_ operations replace that plan would leave only one answer path in the contract.

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Maintainer decision on head cc6644c993 (Bolin, via Bolin Review bot): approved. The host owner may answer tool approvals over the Crew API.

On the security question above (can code in the agent's sandbox read a credential that passes the host-owner check): the three new routes go through owner_route → require_owner_dashboard_request and then is_host_owner_dashboard_request, the same gate as the dashboard's own approval routes, and they answer through the same resolvers. So a sandboxed turn that could get past this gate could already answer its own approval through the dashboard routes today; these routes add no new reach for that case. Keeping the owner's credential out of the sandbox stays the boundary, as it is now.

Before the next release, please run one real pending approval through POST /v1/crew/owner/approvals/{id}/decision on a real machine (allow and deny) and note the result on the PR, since this head was not run on one.

AI-assisted, sent by Bolin Review bot

@bolichen97
bolichen97 merged commit 4158830 into main Nov 20, 2026
101 checks passed
@bolichen97
bolichen97 deleted the crew/headless-crew/owner-approvals branch November 20, 2026 22:34
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 20, 2026
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.

3 participants