Skip to content

fix(mcp): give each documented clear a spelling that reaches the server - #20144

Merged
chenmingwei23 merged 1 commit into
mainfrom
fix/empty-clear-spellings-20089
Oct 14, 2026
Merged

chenmingwei23 merged 1 commit into
mainfrom
fix/empty-clear-spellings-20089

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Every clear that seven Kiro Crew MCP tools document reaches the server through Kiro CLI, and every call that passes a value behaves as it does on main.

Kiro CLI rebuilds a tool call's arguments and drops every list or object that holds no scalar (measured on 2.31.0). These tools document an empty list or object as the way to clear something, so the clear never arrives:

Tool Documented clear What happens on main
cron_update skip_dates: [] Alone: Error: no fields to update. With another field the update lands and the skip dates stay
cron_secret_request secrets: {} Error: secrets: required; the pending request stays
monitor_update judge: {} Alone: nothing to change. With another field the old criteria stay
propose_change folder.steering steering_dirs: [] Refused: 'steering_dirs' must be a list of at most 300
propose_change template.update fields.allowedTools: [] Alone: refused. With model: the card proposes only the model change
artifact_update tags: [] Alone: Error: nothing to update. With another field the old tags stay
issue_radar_crew_record labels_applied: [] The record keeps the previous labels

Why it matters

An agent asked to clear one of these gets either a refusal it cannot fix by retrying, or a success that silently did not clear: a schedule keeps skipping its dates, a stale secret request waits for approval, a card that should tighten a template's auto-approvals proposes only the other half, and a crew's record claims labels it already removed.

Not a goal

What changed (motivation → approach → change)

Tool Clear that reaches the server Beside a non-empty value
cron_update clear_skip_dates: true refused, nothing written
cron_secret_request withdraw: true with no secrets refused, request kept
propose_change folder.steering params.clear: true refused, no card
propose_change template.update params.clear: ["allowedTools"] (also tools, skills) refused, no card
artifact_update clear_tags: true refused, nothing sent
monitor_update judge: {"wake_when": "", "quiet_when": ""} (already arrives; description only) not applicable
issue_radar_crew_record clear: ["labels_applied"] (already arrives; description only) not applicable

Once the client drops an empty container, the server sees an omitted field, so each clear needs a spelling that holds a scalar: a boolean, or a list with at least one name. Both arrive unchanged on the deferred tool_call path and the direct path.

Each new argument is optional and the empty spelling keeps working beside it. The change-card catalog (change_card_catalog.py) turns clear into the plain empty list (steering_dirs: [], fields.allowedTools: []), so the preview, the apply step, the person's edit and Undo read one shape. artifact_update (mcp_tools/artifacts.py) turns clear_tags into tags: [] before it calls the route. The cron handler (mcp_cron.py) empties the skip dates, or withdraws the request through the same step secrets: {} takes. cron_secret_request takes secrets as required unless withdraw is true (validation.py), and a call with neither gets the same secrets: required refusal. The two change-card refusals a dropped list produces name the clear spelling. The monitor_update and issue_radar_crew_record changes are description text only (mcp_tools/control.py, mcp_tools/apps.py).

Tool descriptions and the owning docs say which spelling to use: the new-tool checklist in docs/architecture/mcp.md, config.md (folder steering), artifacts.md, learn-cron-dashboard.md (secret requests), and the packaged cron-and-scheduling.md, monitor-loops.md and the Issue Radar crew_ledger_spec.md.

Backwards compatibility

Compatible: every new argument was an unknown field, and so refused, on main. A call that passes skip_dates, secrets, tags, steering_dirs, fields or judge with a value is handled exactly as on main, and so is secrets: {} or skip_dates: [] where a client delivers it.

Removes nothing: the advertised required lists only loosen (secrets on cron_secret_request, steering_dirs on folder.steering, fields on template.update); the server still refuses a call that has neither the value nor the new spelling, with the same code.

Tests

Each test drives the tool's own entry (schema validation and handler) into its real backend: the cron store, the AutoNudge store, the change-card and folder routes, the artifact update route and the Issue Radar crew routes. A gateway leg is bridged onto a loopback test server or the registered handler, never a live gateway. Each tool has three kinds of case: the new spelling clears (alone, beside the empty spelling, and beside another field), a call with a value is unchanged, and the new spelling beside a value is refused with nothing written.

  • test_cron_skip_dates.py, test_cron_secret_env.py: clear_skip_dates and withdraw through the cron dispatch, read back from the store; secrets: required with neither; withdraw and secrets: {} give the same answer, and keep the request, for a job the caller cannot reach and on a busy store.
  • test_private_cron_proxy.py: both cron spellings cross the real /api/crons/tools route to the host store.
  • test_monitor_directive_apply.py: {} and blank criteria leave the loop identical (no own criteria, judge state reset, {} after a store reload) from the tool through the directive consumer.
  • test_change_card_clear_spellings.py (new): catalog normalization and refusals for both kinds; the tool through the real card routes, then the owner's Apply through the real folder route, leaves the folder with no steering directories; a template.update card plans {"allowedTools": []} as tighten.
  • test_artifacts_handlers.py: clear_tags from the tool to the real update route and store; the refusal sends no request.
  • test_issue_radar_crew_routes.py: clear: ["labels_applied"] from the record tool through the read and write handlers empties the stored labels; a misspelled name is refused.

Determinism: the 52 new test ids passed 20 times at -n0, 10 times at -n 2 --dist loadgroup --max-worker-restart=2 beside test_change_card_folder_steering.py and test_cron_skip_dates.py, and once in a shuffled order (seed 17231). The worker count is 2 rather than 4 on the host that ran them.

Locally the related set is the 134 test files that reference a changed symbol, at -n 2. The local gate selects about 1,860 backend files because validation.py is imported nearly everywhere, and the full set and the cross-surface set run in CI.

Manual verification

Offline replay of Kiro CLI's own argument rebuild (no model call) on every old and new spelling, through the engine bundles of 2.29.0, 2.29.1, 2.30.0 and 2.31.0: in all four each old spelling arrives with the key missing and each new one arrives unchanged, on both the deferred and the direct path, with identical results across versions.

Kiro Crew does not pin a Kiro CLI version; it runs the installed release. The change does not depend on the drop: a client that delivers [] or {} still clears through the existing spelling.

Screenshots / video

N/A: backend tool arguments and their descriptions; no dashboard surface changes.

Related Issues

Refs #20089

This is the first part of #20089. The dashboard_write object-field item depends on #20068 and follows in a separate pull request, which closes the issue.

Pattern harvest

Rule candidate: review-prompt
Pattern: a tool argument whose only documented clear is an empty list or object, which a client that drops empty containers delivers as an omitted field

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • 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

@chenmingwei23
chenmingwei23 requested review from a team and KiroCrewCaptain as code owners October 14, 2026 05:39
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 14, 2026
@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 1bcd900f0eeaa0ef7a5ec61e041105e4203f0209 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 1bcd900f0eeaa0ef7a5ec61e041105e4203f0209 — 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/CONCERNS are advisory.

First-Principles-Verdict: PASS

Check one thing before merge: no test here reproduces Kiro CLI dropping empty containers. Every new spelling rests on the author's offline replay of versions 2.29.0–2.31.0.

What this change ships

Inventory (10 items) — 10 justified

Intent: let an agent clear a list or object field through Kiro CLI, which drops empty containers. This is a FIX.

  1. cron_update accepts clear_skip_dates: true to remove every skip date — justified
  2. cron_secret_request accepts withdraw: true and no longer requires secrets — justified
  3. propose_change folder.steering accepts clear: true and no longer requires steering_dirs — justified
  4. propose_change template.update accepts clear: [list field] and no longer requires fields — justified
  5. artifact_update accepts clear_tags: true and sends the route tags: [] — justified
  6. Each new flag is refused beside a non-empty value, and nothing is written — justified
  7. Change-card refusals name the clear spelling — justified
  8. monitor_update description recommends blank criteria over {} — justified
  9. issue_radar_crew_record description points to clear: ["labels_applied"] — justified
  10. mcp.md new-tool checklist: a clear never relies on an empty container — justified

[FIRST-PRINCIPLES-REVIEWED] 1bcd900

Description read

[DESCRIPTION-READ] 15f75daec05897f51b7432250064b88da46c85a79de1f5c369848c65d6cfde6d

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 Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 1bcd900f0eeaa0ef7a5ec61e041105e4203f0209 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Nothing to check.

[DESIGN-REVIEWED] 1bcd900

Description read

[DESCRIPTION-READ] 0818592fd22f2d72e8b777b48dd76198f6cb42d12d5de543a501ccb3b71d83a6

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 Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 1bcd900

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 1bcd900f0eeaa0ef7a5ec61e041105e4203f0209: <one-sentence reason>

@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 Oct 14, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/empty-clear-spellings-20089 branch from c5ed358 to e50aedb Compare October 14, 2026 06:53
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 14, 2026
@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 1bcd900

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable 1bcd900f0eeaa0ef7a5ec61e041105e4203f0209: <one-sentence reason>

@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 Oct 14, 2026
Kiro CLI rebuilds a tool call's arguments and drops every list or object
that holds no scalar, so the clears seven tools document as an empty
list or object never reached the server: the call was refused, or it
landed with the clear silently missing.

Each clear gets a spelling that arrives unchanged, and the empty
spelling keeps working beside it:

- cron_update: clear_skip_dates: true empties the skip dates.
- cron_secret_request: withdraw: true withdraws the pending request;
  secrets is required unless withdraw is true.
- propose_change: clear: true for folder.steering and a clear list of
  field names for template.update; the catalog normalizes both to the
  plain empty list, so preview, apply, edit and Undo are unchanged.
- artifact_update: clear_tags: true sends the route tags: [].
- monitor_update and issue_radar_crew_record: descriptions name the
  spellings that already arrive ({"wake_when": "", "quiet_when": ""}
  and clear: ["labels_applied"]).

Every new argument is optional, a call that passes a value is
unchanged, and a new spelling beside a non-empty value is refused. Tool
descriptions and the owning docs change together.

Refs #20089
@chenmingwei23
chenmingwei23 force-pushed the fix/empty-clear-spellings-20089 branch from e50aedb to 1bcd900 Compare October 14, 2026 08:09
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 14, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

rebutted: the check was run before merge. The drop happens inside Kiro CLI's own engine bundle, which the repository's tests do not run, so the evidence is the offline replay in the PR body (Manual verification).
That replay ran the client's own argument rebuild (no model call) from the 2.29.0, 2.29.1, 2.30.0 and 2.31.0 bundles on every old and new spelling, on the deferred and the direct path: each old spelling arrived with its key missing, each new one arrived unchanged, and all four versions agreed.
The change does not rely on the drop: every new spelling holds at least one scalar (a boolean, a field name or a blank string), and a client that delivers [] or {} still clears through the existing spelling.

@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 Oct 14, 2026
@chenmingwei23
chenmingwei23 enabled auto-merge (squash) October 14, 2026 08:44

@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.

Readiness sweep: full diff read, PR Readiness success on this head, no live change requests.

Sensitive change review
Rule touched: cron_secret_request schema (secret-grant requests) and propose_change template.update / folder.steering param validation (template allowedTools = auto-approval list). Before: secrets required; empty {} withdrew the pending request; template.update needed a non-empty fields object. After: secrets optional when withdraw:true (validation.py _validate_cron_secret_request refuses withdraw beside a non-empty map and still returns 'secrets: required' when neither is given); withdraw runs only after _check_cron_job_ownership (mcp_cron.py ~3833) and only empties secret_env_pending, never an approved grant; template.update clear:[tools|allowedTools|skills] normalizes to the empty list and still goes through a change card that the owner must Apply (risk classified 'tighten'). No approval, redaction, deny-list or auth path is loosened. Worst case if wrong: an agent withdraws its own job's pending secret request, or proposes a card that empties a template list — both already possible via the empty spelling. Evidence: read whole diff and head versions of mcp_cron.py and change_card_catalog.py; tests cover foreign/unknown job ids, busy store, refusal-with-nothing-written. Undo: revert the squash commit.

Undo: revert the squash commit.

@chenmingwei23
chenmingwei23 merged commit 7e3b9ab into main Oct 14, 2026
102 checks passed
@chenmingwei23
chenmingwei23 deleted the fix/empty-clear-spellings-20089 branch October 14, 2026 09:27
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 14, 2026
chenmingwei23 added a commit that referenced this pull request Oct 14, 2026
When clear: true is passed to dashboard_write, the panel server now
reads the field's declared type from the dashboard/fields route and
writes the matching empty value: [] for array fields and {} for object
fields. Previously only [] was written, which the gateway refused as
wrong_type for object fields (asks, drafts, steps). Calls that pass a
value are unchanged.

Closes #20089 (part 2; part 1 is #20144)
iamwhatever pushed a commit that referenced this pull request Oct 15, 2026
…20241)

* fix(mcp): let dashboard_write clear an object field with clear: true

When clear: true is passed to dashboard_write, the panel server now
reads the field's declared type from the dashboard/fields route and
writes the matching empty value: [] for array fields and {} for object
fields. Previously only [] was written, which the gateway refused as
wrong_type for object fields (asks, drafts, steps). Calls that pass a
value are unchanged.

Closes #20089 (part 2; part 1 is #20144)

* fix(mcp): fall through to the gateway for scalar and fold-sourced clears

_empty_value_for returns {} for an object field and [] for every other
field, including string, number, boolean and fold-sourced fields,
instead of refusing early. The write route then refuses those with
wrong_type or field_not_agentic and records the refusal in the mistake
book; an early refusal duplicated the gateway's check and bypassed the
book.

A field list that cannot be read also gets [], the value clear: true
wrote before object fields were supported, so emptying an array field
does not depend on the fields route answering. The owning spec now
says the same instead of claiming scalar clears are refused before the
POST.

---------

Co-authored-by: Raymond Chen <chenmingwei23@users.noreply.github.com>
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.

2 participants