Skip to content

docs(rfc): a code channel's Stop also stops its helper agents - #35935

Merged
bolichen97 merged 1 commit into
mainfrom
docs/rfc-code-channel-stop-helpers
Nov 12, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
docs/rfc-code-channel-stop-helpers

Conversation

@kyleseaman

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Record the decision that Stop in a Slack code channel stops the channel's own session and its helper agents, before any code for it is written.

Today Stop in a code channel (Slack's Stop button or !stop) stops only the channel's own session. If that session is idle while its helper agents are running, !stop answers "Nothing running.", Slack's Stop button says nothing, and every helper agent keeps going: _stop_bound in slack/code_channels/routing.py looks up only the channel's bound slot (verified on main 6ded84fc02).

Why it matters

Stop is the person's brake. A Stop that leaves agents editing code is wrong, and the person has no way to see from the channel that they kept going.

The owner left this call to the Slack Code team lead, who decided it. On #22001 the First Principles lane blocked every head because the restart-resume RFC text arrived in the same diff as its code, so the owner had to re-post an override on each push. This time the decision lands first, as a docs-only change the owner approves and merges, and the code pull request then has a recorded decision on main behind it.

Not a goal

What changed (motivation → approach → change)

The decision is recorded in docs/request-for-change/rfc-slack-code-channels.md, which main already carries as in-progress. A new "Stop" item in §3 (code channels) says:

  • What it stops: the channel's session's running turn, every running helper agent the gateway's own records tie to that session (the code-channel store records each one when the session starts it), and the sub-agents those turns started. Nothing an agent wrote is undone.
  • Who may press it: unchanged. Only Kiro Crew's owner, in a channel whose origin conversation still admits the bot, from an admitted workspace.
  • What the channel says: how many it stopped, and that nothing starts again until someone sends a message there.
  • What happens next: nothing starts again on its own. The channel's session starts no turn by itself (patrol or timer wake, a helper agent's report, a scheduled job) until a person sends it a message. A stopped helper agent stays stopped until a person or the channel's session, working on a person's message, starts it again. Whose message it is comes from the gateway's own record, never from the text. Restart resume does not resume a turn a Stop ended, including one still ending when the gateway restarted.

The document's status line gets a dated amendment line saying who decided and that nothing is built yet. The front matter's last-audited, audited-at and implementation-prs are brought up to date (#21425, #21410 and #22001 are merged). The index row in docs/request-for-change/README.md records the amendment.

Backwards compatibility

Compatible: documentation only; no code, config or behaviour changes.

Removes nothing: the change only adds text and corrects the RFC's audit fields; no section, decision or reader goes away.

Tests

Proof: not provable -- docs or config only

Docs lint and the prepush gate pass on this head.

Manual verification

N/A — documentation only. Every statement about today's behaviour was checked in the code on main 6ded84fc02.

Related Issues

None. This records a decision; the code pull request follows after #21993.

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

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license.

Records the decision before the code: Stop in a code channel stops the channel's own session and every helper agent the gateway's records tie to it, says how many it stopped, keeps a stopped helper stopped, and restart resume never resumes a turn a Stop ended. Docs only; the code follows after #21993.
@kyleseaman
kyleseaman requested review from a team and KiroCrewCaptain as code owners November 12, 2026 17:20
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 12, 2026
@github-actions

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ⏭️ skipped

Revision 9c8272457019c9de17e2066cf88adc1ceb52840b ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Does not block merge.

@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

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

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Docs-only decision record; no design-level concerns.

Notes

  • "No scheduled job" until a person sends a message also holds cron jobs aimed at the channel's session. The code PR should define how the channel shows that a job was held, so a skipped cron doesn't look like a silent failure.

[DESIGN-REVIEWED] 9c82724

Description read

[DESCRIPTION-READ] 74560b10f074f7852663a288e70dfbcff0af14e2a826dff1bca9dc6330e45e4f

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 9c82724

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

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

@github-actions

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 9c82724

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

@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: Approve

Why: the decider estimates a 7% chance that this change introduces a defect, within the 12% limit for approving on its own, and every check passes.

Docs-only RFC amendment that records the decision that Stop in a Slack code channel also stops the channel's helper agents and their sub-agents, and that nothing restarts until a person sends a message. The claims about today's behaviour check out in the code: _stop_bound only checks the bound slot and posts "Nothing running." when idle (routing.py:1837-1864), the native Stop passes say_idle=False (routing.py:1942), and the store records helper agents at birth (store.py:708 record_worker). The trust boundary is unchanged (owner-only Stop; release only on a gateway-recorded person's message), and the lifecycle after a Stop, including restart resume, is covered. Status stays in-progress, with no code or behaviour change. Design Review passed; UX and First Principles skipped it as docs-only, and the Opus, GPT and Security Scope review lanes were still pending.

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 9c82724570 · 47 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@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 12, 2026

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

Approving, docs only. I read the RFC hunks and the index row.

Design brief

  • What it decides. Stop (!stop or Slack's Stop) in a code channel stops the channel's own turn, every helper agent the gateway's own code-channel store ties to that session, and their sub-agents. Afterwards nothing restarts on its own (no patrol, timer, report wake or scheduled job) until a person sends a message, and whose message it is comes from the gateway's record, not the text.
  • Pros. Stop becomes a real brake. Today an idle channel session answers "Nothing running." while its helpers keep editing code. Who may press Stop is unchanged (owner only, admitted conversation and workspace), so it adds no security strictness.
  • Cons. A person who wanted only the channel's own turn stopped now stops the helpers too. A per-helper Stop is left to #22928's Workers tab, which covers that.
  • Long-term debt. Low. It builds on the store the code channels already keep. The code follows in its own PR after #21993.

The front-matter refresh (audited-at: 6ded84fc02, implementation-prs: [21425, 21410, 22001]) matches what has shipped.

Direction signed by maintainer (bolichen97).

@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

This RFC changes what the shipped code-channel Stop does (it would also stop the helper agents), so a maintainer needs to accept it before it can merge. A maintainer will post the decision here.

Review result: no blocking findings on this head. This is a docs-only change to two files under docs/request-for-change/. The review checked each claim about today's behaviour against main:

  • _stop_bound looks up only the bound slot.
  • An idle !stop posts "Nothing running.", while the native Stop passes say_idle=False and stays silent.
  • Stop is owner-only.
  • record_worker records each helper agent when it is created.

The updated implementation-prs (#21425, #21410, #22001) are all on main. One thing done well: the decision is recorded before its code. The release rule also reads who sent a message from the gateway's own record, never from message text, so an agent cannot release itself.

Optional:

  • The Stop scope names only the code-channel store. Restart resume treats both the store records and the crew-log tree as the session's workers. Matching the "Whose work" set used for resume would mean Stop reaches everything resume could continue.
  • For code channels, the amendment overrides the general Stop rule for sub-agents (session.md, and the soft-stop note in docs(stop): record how each Stop treats the parent's sub-agents #26036). One clause saying this is a deliberate exception would leave the code PR a single rule to implement.
  • The "nothing starts again until a person writes" rule, including held scheduled jobs, is a second decision. The README row and the dated status line do not mention it. Naming it there, and saying how the channel will show a held job, would give the code PR a starting point.

@bolichen97
bolichen97 merged commit b3bf88b into main Nov 12, 2026
96 of 98 checks passed
@bolichen97
bolichen97 deleted the docs/rfc-code-channel-stop-helpers branch November 12, 2026 22:09
kyleseaman pushed a commit that referenced this pull request Nov 17, 2026
Slack's Stop and !stop in a code channel now stop the channel's own running
turn, the running turn of every helper agent the code-channel store ties to
that session, and the sub-agents those turns started, and say how many they
stopped, naming each stopped helper the work board shows. Nothing is held
afterwards: a queued wake or a patrol can start a stopped helper again until
the follow-up hold change lands. Implements the brake of RFC #35935.
kyleseaman pushed a commit that referenced this pull request Nov 17, 2026
Slack's Stop and !stop in a code channel now stop the channel's own running
turn, the running turn of every helper agent the code-channel store ties to
that session, and the sub-agents those turns started, and say how many they
stopped, naming each stopped helper the work board shows. Nothing is held
afterwards: a queued wake or a patrol can start a stopped helper again until
the follow-up hold change lands. Implements the brake of RFC #35935.
kyleseaman pushed a commit that referenced this pull request Nov 17, 2026
Slack's Stop and !stop in a code channel now stop the channel's own running
turn, the running turn of every helper agent the code-channel store ties to
that session, and the sub-agents those turns started, and say how many they
stopped, naming each stopped helper the work board shows. Nothing is held
afterwards: a queued wake or a patrol can start a stopped helper again until
the follow-up hold change lands. Implements the brake of RFC #35935.
kyleseaman added a commit that referenced this pull request Nov 17, 2026
Slack's Stop and !stop in a code channel now stop the channel's own running
turn, the running turn of every helper agent the code-channel store ties to
that session, and the sub-agents those turns started, and say how many they
stopped, naming each stopped helper the work board shows. Nothing is held
afterwards: a queued wake or a patrol can start a stopped helper again until
the follow-up hold change lands. Implements the brake of RFC #35935.

Co-authored-by: Kyle Seaman <kseam@dev-dsk-kseam-1b-55230d27.us-east-1.amazon.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

readiness: passed Eligible automated validation passed for the current revision

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants