Skip to content

feat: add background_run to wake a chat when a command ends - #26455

Open
Yangxinyee wants to merge 1 commit into
mainfrom
feat/background-run
Open

Yangxinyee wants to merge 1 commit into
mainfrom
feat/background-run

Conversation

@Yangxinyee

@Yangxinyee Yangxinyee commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: An agent runs background_run(command), ends its turn, and the chat is woken with the exit code and output tail. The wake survives a gateway restart (an update or a crash restarts it), because the waits this replaces are the long ones: CI, builds and training runs that outlast a restart. The command itself survives whenever the gateway's exit does not take it along: it runs in its own session, so a gateway process that crashes or is stopped leaves it running, and on Linux a service whose spawn gets its own systemd scope (cgroup v2 delegation) keeps it across a service restart. On Linux without delegation the service manager stops it with the service, and it is reported interrupted. Under launchd on macOS this is not verified (see Manual verification).

An agent that has to wait on CI, a build, a test suite or a model training run has three options today, and none of them lets it start the work, end its turn, and be woken when the work finishes:

  • wait holds the turn open for at most 1800 s, and then the agent checks for itself.
  • monitor_start runs a full LLM turn on every interval.
  • monitor_watch is limited to PR review readiness, one per session.

So agents fall back to blind sleep N plus polling, which is the behavior #12681 reports.

Why it matters

Blind sleeps are wrong in both directions: too short and the agent reads a half-finished run, too long and it idles after CI is already green. They also cannot tell a failure from a job that is still queued, and to the user they look like a hang. For multi-hour work such as training, the only existing option spends an LLM turn per interval. A primitive where the harness waits and the model does not makes waiting free, and the agent resumes the moment the outcome is known.

Not a goal

  • Only dashboard chats are supported: Slack/Discord-only sessions and sub-agent sessions are refused with 409, because completion injection is dashboard-slot based. Incognito and Temporary chats are refused with 409 background_run_private_chat: their run is never saved, while the command's record and log would be on disk. The check reads the chat's live memory mode before any run is registered, since a registration at the run cap evicts the oldest finished run.
  • Closing a chat does not stop its commands. They follow the workflow-run rule, so the result lands in the workflow-<id> fallback slot.
  • Waking on output regex matches (success/failure patterns) and an inline running-tasks chip (Give custom agents native visible async spawning with agent pinning #12876) are left for follow-ups.
  • Windows is refused, because the wrapper needs a POSIX shell.

What changed (motivation → approach → change)

An agent can now hand a shell command to the gateway with background_run, end its turn, and be woken in the same chat with the exit status and the last lines of output. The harness does the waiting, as in Claude Code's background tasks: the agent writes the condition as a command (gh pr checks <n> --watch --fail-fast, until grep -qE 'done|Error' train.log; do sleep 30; done).

Approach. The command is a host run on the workflow substrate (WorkflowService.begin_host_run, the API TaskRunner already uses), not a new registry. It reuses run ids, durable status, workflow_status / workflow_cancel, the Runs view, the finished-workflow card and the chat's own queue drain, so it adds one tool and no polling driver. The design and the alternatives set aside are in the comments on #12681.

Part Where What it does
Tool src/kiro_crew/mcp_cron.py, src/kiro_crew/mcp_cron_tool_list.py, src/kiro_crew/validation_parts/cron_schemas.py, src/kiro_crew/constants.py, src/kiro_crew/data/mcp_tool_titles.json background_run(command, cwd?, timeout_secs?, label?) on kirocrew-cron, so kiro-cli asks before it runs, as for execute_bash and cron_add
Route and gate src/kiro_crew/dashboard/handlers/workflows.py, src/kiro_crew/dashboard/server_runtime/mcp_routes.py, src/kiro_crew/agent_sdk/agent_specs.py POST /api/workflows/background: dashboard chats only; refused (background_run_shell_restricted) for an agent whose shell is restricted in any way or whose spec cannot be read; otherwise the same shell gate as the agent's own execute_bash; Shared Crew admission
Runner src/kiro_crew/background_commands.py Spawns in the sandbox in its own session, supervises deadline and output cap, re-adopts a live command after a restart, reports exactly one outcome
Wake src/kiro_crew/dashboard/workflow_inject.py, src/kiro_crew/dashboard/server_runtime/workflow_startup.py, src/kiro_crew/dashboard/chat_turn/queue_drain.py, src/kiro_crew/dashboard/chat_turn/steer_queue.py, src/kiro_crew/dashboard/chat_utils.py, src/kiro_crew/dashboard/chat_utils_injected_rows.py, src/kiro_crew/dashboard/chat_runner.py, src/kiro_crew/dashboard/state_parts/dashboard_state.py Posts the card, queues a gateway wake behind the person's own sends, and settles only once the wake ran
Run store src/kiro_crew/workflows/registry.py, src/kiro_crew/workflows/service.py RunHandle.delivery_pending keeps an undelivered run from eviction; fail / cancel_host_run take an optional result
Sealed records src/kiro_crew/sandbox_leaves.py, src/kiro_crew/sandbox_precreate.py, src/kiro_crew/sandbox.py, src/kiro_crew/sandbox_tiers.py, src/kiro_crew/security/paths_lists.py, src/kiro_crew/security_posture_sinks_delivery.py The background data-home leaf is read-only to every sandboxed process; a cwd under a masked or sealed path is refused (path_within_tier_mask)
Containment src/kiro_crew/shared_crew/containment.py is_principal_slice, so a stop kills a command's whole systemd scope only inside this instance's slices
Grants and docs src/kiro_crew/agent_parts/spec_grants.py, src/kiro_crew/agent_materialization/worker_agent.py, src/kiro_crew/docs/agent-spec-fields.md, docs/system-specs/modules/workflows.md, docs/architecture/mcp.md A worker never inherits an auto-approve for background_run (_WORKER_EXCLUDED_GRANTS); the spec gains a "Background commands" section

What holds, in one line each (the full mechanism list is docs/system-specs/modules/workflows.md § Background commands):

  • The wake survives a restart. A record settles only after the runner reports the wake consumed and the card and wake row are saved; until then the run is held from eviction and the next boot delivers it again (at least once).
  • The command survives the gateway's exit where the OS lets it. Its output goes to a log through head -c, never a pipe, and a watchdog in the wrapper keeps the deadline with no gateway watching.
  • Nothing in a sandbox can aim the gateway. Records are sealed, keep no session key, and pin the process start identity and boot id, so a recycled or forged pid is never signalled.
  • The command gets no more than the chat's shell would. Only an agent with an unrestricted shell can start one (any permissions shell deny or ask, deniedCommands, denyByDefault, a tool list without the shell, or a PreToolUse hook that can match it refuses background_run on every harness); then the same gate, the same sandbox tier (never below standard), the calling harness's credential mask, and a cwd that is never inside a mask or seal.
  • Retained copies are redacted. The command echo and the output tail drop credential shapes before they are stored or shown.
  • One outcome per command: exited, timed_out, output_limit, stopped or interrupted.

Backwards compatibility

Compatible. Every signature change adds an optional keyword with the old behavior as its default (result=None on fail and cancel_host_run), and RunHandle.delivery_pending defaults to False and is absent from records that never set it, so eviction of every existing run is unchanged. The tool, the route and the data-home directory are new, and nothing main accepts is rejected or renamed.

Two take-aways, both on surfaces this PR adds; git grep origin/main finds no other reader of <data home>/background and no other caller of the new spawn:

Reader: src/kiro_crew/background_commands.py:BackgroundCommandService._spawn -- chat -- the extra_hidden_dirs mask is the calling chat's own harness mask (empty for kiro), so a command sees no more than that chat's shell; test_the_command_runs_under_its_chats_harness_credential_mask
Reader: src/kiro_crew/background_commands.py:_wrapper -- chat -- the wrapper's record handshake reads background/, which the enforced masks leave readable and the sealed leaf keeps read-only; test_an_enforced_harness_mask_hides_the_secrets_but_not_the_command_records

Tests

test/test_background_commands.py (spawn, settle, stop, re-adoption) and test/test_background_run_chat.py (the card, the wake, the MCP tool and the route), 88 tests, split to stay under the 2,000-line file cap. The sandbox chokepoint is replaced by an identity wrapper (through _floor_monkeypatch, D11) so the tests pin the lifecycle rather than the host's sandbox backend; the processes are real /bin/sh process groups. No test waits on a fixed sleep or asserts a wall-clock bound: they wait on a marker file or the supervisor's own poll count, set exit-status mtimes and inject the service clock, and the regex-linearity check runs in a child under a lost-run bound.

  • Exit handling: exit 0 finishes the run with the tail and delivers it once; a nonzero exit fails the run with its exit code; an exit before the deadline stays an exit when reading its status file crosses the deadline.
  • Stopping: the timeout kills the whole process group (grandchild included) and the reported tail still ends with the command's last line; workflow_cancel stops the command and cancels the run; output past the cap stops the command; a fast exit past the cap fails the run and the log is cut to the cap; a cancel during settlement still settles the run; the watchdog stops a command no gateway watches; a command that ended unwatched past its deadline is a timeout; a re-adopted command past its deadline is stopped at once; only a scope in this instance's slice is ever killed; settling kills everything left in the command's scope; without cgroup.kill, the scope unit is stopped.
  • Caps: a chat cannot exceed its running cap.
  • Delivery: the real drain writes the wake as an inject row the gateway is credited for, never the person's row; a wake is acknowledged only once the runner reports it consumed, not while queued or once its row is written, and an end-of-turn report only once its turn has ended; a wake that never runs is given up after its wait with the card delivered and the wake left queued; a wake a signed-out CLI refused is queued again and acknowledged after sign-in; a wake its user removed or Stopped is not queued again; an unsaved or declined wake is not acknowledged.
  • Restart: shutdown leaves the command running and the next boot re-adopts it (the run reads running right after reconcile, then settles with the real exit code); a command that finished during the restart settles from its exit status; a command lost without an exit status is reported interrupted and delivered; a result the run store did not save is reported again after a restart; a command whose run cannot be saved is never started; an Incognito or Temporary chat never starts one; reconciling before admission keeps a restored command's run from eviction; a supervised command, a re-adopted one included, is in the sweeps' protected set until it settles; a live command with no run to report to is stopped on boot.
  • Platform and bounds: Windows (no POSIX shell) refuses; a host whose sandbox would drop the mask refuses before any run exists; timeouts are defaulted and bounded.
  • Completion message: it keeps the chat card's header, checked against the same regex the frontend uses, even with backticks in the name, and carries the outcome, tail and log path; a checkpoint error is still shown beside a command result.
  • Tool: it posts the verified chat's session key and tells the agent to end its turn; it refuses without a command or a verified identity; no shipped allowedTools entry (whole-server, glob or per-tool, in the built default or any packaged agent spec) covers it.
  • Route: the real HookManager refuses rm -rf / and a --data-binary @ exfiltration and passes pytest -q; an agent whose shell is restricted in any way (19 shapes, on the KAS, kiro-cli, claude and codex backends), whose spec cannot be read, or that cannot be named is refused with background_run_shell_restricted before anything starts, and the bundled default agent is admitted on every backend; cwd defaults to the project and refuses non-directories, and a cwd inside a tier or harness mask is refused before any run; non-internal callers get 403; the success path starts the command for the caller's own chat with the harness read from that chat's live session (else the configured one through the crewmate pin crewmate_backend_pin, whose unstartable pin is refused with 409); a denied command gets 403 and a session with no chat gets 409, and neither starts anything.
  • Hardening: a job an inner shell left in the group is stopped before settling (on Linux, where the spawn token is readable), and a leaderless group whose members lack that token is never signalled; a backgrounded job keeps the run open until it ends; a command without a readable identity is stopped and dropped, while one that exits before its identity is read still settles; the command cannot write its own exit status; a watched command settles from its real exit, not the status file; a killed wrapper never settles from a forged status; the status reader takes the last whole line; inline secrets are redacted from the retained command, and no retained copy carries them; the sandbox follows the operator's tier but never goes below the shell's, and the command is spawned at the resolved tier; the command runs under its chat's harness credential mask, and an enforced harness's mask hides .local_secret but leaves background/ readable for the wrapper's handshake; the record keeps no session key, and re-adoption restores the owner; an outcome published but never delivered (the gateway stopped, or the chat refused every attempt) is delivered on the next boot with the same card, and an acknowledged one is not delivered again; a refused delivery is asked again in the same gateway and given up only past retention; a run whose outcome is undelivered is never evicted (the hold is saved with it) and is evictable once delivered; a held run no record will deliver is released on boot; an outcome whose run is gone is not marked delivered; a command outcome counts as delivered only once its wake has run and is saved (not while it only sits queued behind a busy turn), an idle chat holding an unrun wake after a restart has that entry run, neither the card nor the wake is posted twice, and a wake its user removed is not queued again; a boot-time delivery waits for the open tabs but not forever; the tail never carries a private key's body, whether the line cut or the read window drops its header; the log stays bounded while no gateway watches; a group whose leader nobody watched is never signalled; a record from another boot is never alive; a job left by a command that ended unwatched is not signalled; a start cancelled during the spawn leaves no run; one record that fails to re-adopt does not stop the rest; records that cannot be listed keep admission closed; the working directory is pinned and re-checked by descriptor; concurrent starts cannot pass one cap check together; the record keeps no cleanup path and pins its files by identity; a replaced or symlinked log is never read; settling prunes settled folders past retention; command output containing fences cannot close the completion message's fence, and a multi-line label cannot forge a card header.
  • Updated pins: test_hooks.py::TestHookGateKwargs (the route splats hook_gate_kwargs), test_security_posture.py (the sink is registered), test_spawn_audit.py (the new spawn site is routed and limited), test_sandbox_governance_mask.py (background is sealed in every mode and edit-refused by the file gate), test_json_object_body_guard.py (the route's body cap is registered), test_sandbox_protected_name_holds.py (the background root leaf is three more leaf-only names per tier, recorded with its reason like the other data-home root leaves), test_dashboard_server_composition_contract.py (the MCP route table gains the background route, re-measured on current main (301 rows; lazy imports 90), the lazy-import table gains the in-function imports, and the workflow-service hooks test stubs the background service and checks the command wake prompt (with its run id) through the service's deliver), and test_transcript_derivation_seam.py (the delivery's yes/no transcript read is named as plumbing), test_slot_running_readers.py (the queued-wake wait and its dispatch read the reservation, like the parked-queue drain), and data/mcp_tool_titles.json (background_run gets its display title). test_sandbox_refactor_facade.py lists the two new sandbox_tiers names (_tier_mask_dirs, path_within_tier_mask), which the sandbox facade forwards and its TYPE_CHECKING block names. test_security_gate_liveness.py raises the package budget by the one background write-protect line, with its reason.

Locally, on 8e85d1cb04 (rebased onto current main): the 450 test files matching background, workflow, mcp_cron, cron_folder, queue, drain, auth_req, sandbox, security_gate, slot_running, transcript_deriv, composition, injected, containment, facade and the pin tests: 18,017 passed. The 2 failures were facade-boundary gates the rebase tripped (test_mcp_cron_facade.py, test_chat_runner_composition_contract.py); they are fixed, and the 1,396 runner, facade and PR tests pass on a rerun, as do the pin tests after the latest rebase. Each new delivery test fails with its fix reverted. Also passing: mypy --platform linux src/kiro_crew, flake8, isort, black on the touched files, the line cap, sync-io, subprocess-encoding, comment-history, harness parity and docs lint.

One host note, not caused by this diff:

  • This host's agent shell refuses /bin/ps, so process_start_time reads None there; the local run read the start identity through get_process_start_id with a test-only plugin. CI runs the real ps.

I did not run the full run_scoped_tests.py --surface backend set locally (2,134 targets); CI runs it.

Manual verification

  • Earlier round: ran BackgroundCommandService against the real sandbox path (sandbox-exec, macOS, isolated KIROCREW_HOME): echo hello; exit 0 → finished 0, exit 5 → failed 5, gh --version → finished 0 (gh works at the standard tier). With the sealed folder, a command writing another run's exit_status or planting a file in background/ gets Operation not permitted, while its own exit status and output are still recorded correctly. With the watchdog (timeout 1s, margin 0, gateway stopped), the whole group was gone about 6s later and the status read timeout.

  • Ran test/test_background_commands.py with the wrapper pointed at /bin/dash as well as /bin/sh, several times each under -n 6: all pass. The earlier Linux-only failures came from dash rejecting a two-digit fd in >&12.

  • Not verified:

    • the full dashboard loop on a live gateway (kiro-cli permission prompt → approval → spawn → completion card → auto-turn);
    • a command surviving a real systemd --user service restart on Linux;
    • a command surviving a launchd restart or a desktop-app quit on macOS.
    • the harness credential mask and the head-drain fix through the real sandbox-exec/namespace backend: this host's own shell runs inside a sandbox, so sandbox-exec cannot nest (sandbox_apply: Operation not permitted); both are covered by unit tests and the wrapper probe above.

    The restart logic is covered by the unit tests above, but not against real service managers.

Related Issues

Closes #12681.

Supersedes #13180: the same change, moved from a fork branch to this repository so Sensitive Change Review can be cleared. Its review history stays on #13180.

Refs #12693: a running command keeps has_pending_work_for true, which gives a completion contract a deterministic "work in flight" signal. Refs #12876: command runs appear in the Runs view; the inline task chip is not in this PR.

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

N/A — the CLA text is still a template placeholder. I agree to license this contribution under the repository's license (Apache-2.0).

@github-actions

github-actions Bot commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor

Sensitive Change Review

Sensitive files changed:

  • src/kiro_crew/sandbox.py

  • src/kiro_crew/sandbox_leaves.py

  • src/kiro_crew/sandbox_precreate.py

  • src/kiro_crew/sandbox_tiers.py

  • src/kiro_crew/security/paths_lists.py

  • src/kiro_crew/security_posture_sinks_delivery.py

  • @Yangxinyee comment (35 comments checked, none complete): does not name the current head 6c2bedb; post it again for this head

How to clear this check:

  1. The PR author posts the template below as a PR comment, with
    every field filled (N/A needs a reason). Keep the
    Head commit line: it must name the current head SHA.
  2. The check turns green within a minute, with no push.
  3. A new push resets this check: post it again for the new head.

Only the author's comment counts this way. A reviewer can instead
paste the filled template into an "Approve" review on this head.
Merging still needs a reviewer's approval.

## Sensitive change review
- Head commit: 6c2bedb67fd1b76618cacc5f056e944044a54154
- What rule changed:
- Before -> after (what was allowed/blocked, now):
- Worst case if wrong (breaks commands / leaks secret / locks user out):
- Evidence checked (which sandbox result proves it):
- No regression:
  - Tools still work (which tools/commands were run, result):
  - Backward compatible (old config / old data / old callers still work, how checked):
  - Existing tests (which suites passed on this head):
- How to undo:

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 30, 2026
@Yangxinyee

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: acc7d33
  • What rule changed: adds one crew-home leaf, background (the gateway's background command records, exit statuses and logs). It is READONLY in every sandbox mode and precreated (sandbox_leaves, sandbox_precreate), and write-protected for the file tools (paths_lists._WRITE_PROTECTED_HOME_PATHS). It also registers one new redaction sink (security_posture_sinks_delivery) and adds sandbox_tiers.path_within_tier_mask, which shares the tier-mask resolver _tier_mask_dirs with carveout_shadowed_by_foreign_mask (that resolution moved there unchanged; sandbox.py only forwards the two names).
  • Before -> after (what was allowed/blocked, now): before, an agent could write <data home>/background/; now it can read it, but neither a sandboxed shell nor a file tool can write it. No deny tier, pattern or existing path disposition changed.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): if the seal failed, an agent could forge a record and aim the gateway's kill at another process, though every signal re-checks the recorded process start identity first. If it is too tight, background_run cannot write its records and is refused; no other tool is affected.
  • Evidence checked (which sandbox result proves it): unit tests test_sandbox_governance_mask.py (the leaf is sealed in every mode and edit-refused by the file gate), test_sandbox_protected_name_holds.py and the background command tests. An earlier round ran BackgroundCommandService through the real sandbox-exec on macOS (a command writing another run's record was refused), and the namespace-sandbox CI lane passed on earlier heads. The real sandbox was not re-run for this head: this host's shell already runs inside a sandbox, so sandbox-exec cannot nest.
  • No regression:
    • Tools still work (which tools/commands were run, result): Security Scope Review classified its candidates on macOS, Ubuntu and Windows with 0 newly refused; reading the leaf's logs (tail, cat, grep, ls) stays allowed.
    • Backward compatible (old config / old data / old callers still work, how checked): a new leaf only; no existing path, config key or caller changed, and an existing install just gains an empty precreated directory.
    • Existing tests (which suites passed on this head): locally on this head, 3,678 tests across the sandbox, security-gate, pin, background, workflow and inject files, plus full flake8 and mypy --platform linux; the backend CI lanes run on this PR.
  • How to undo: revert this commit, or remove the background entries from sandbox_leaves.py, sandbox_precreate.py and security/paths_lists.py.

@github-actions

github-actions Bot commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 6c2bedb67fd1b76618cacc5f056e944044a54154 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 Oct 30, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks. The tool reuses the workflow host-run substrate instead of adding a new registry, and none of the take-aways I checked has a reader that breaks outside the patch.

Notes

  • Rewrite of saved grants can't be undone by a revert. On rebuild, @kirocrew-cron, @* and @kirocrew-* in a user's saved allowedTools are replaced with a per-verb snapshot ("narrowed to the server's other verbs"). Reverting the code won't restore what the user wrote, and cron verbs added later will prompt instead of being auto-approved. It fails toward prompting, so it's safe, but ## Backwards compatibility should say it. That section was cut off at 8000 bytes, so I couldn't check whether it does.
  • Placing the tool on kirocrew-cron forces the grant rewrite. Because background_run, which can run any shell command, lives on a server people grant whole, the never-auto-approve narrowing now runs through every allowedTools writer. A separate server would leave existing @kirocrew-cron grants as written and confine the narrowing to wildcard grants. Weigh that before more verbs that run commands land on this server.
  • Wake delivery is at least once. The rule is "the next boot delivers it again (at least once)", so a crash after the wake runs but before the card is saved re-wakes the chat with the same result. The wake text should let the agent recognise a duplicate run id.

[DESIGN-REVIEWED] 6c2bedb

Description read

[DESCRIPTION-READ] 99080cd920f39f4712ed327fc016a69ca12d0759255c6529d82ab73af8582ef3

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 30, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — 🔴 BLOCK

Premise-level review of 6c2bedb67fd1b76618cacc5f056e944044a54154 — 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: BLOCK

Retained output and the wake prompt are redacted by chaining two redaction passes by hand. kiro_crew.security.redact already does this job, and its owner tells callers not to chain the passes.

What this change ships

Inventory (10 items) — 9 justified

Intent: an agent hands a long command to the gateway, ends its turn, and its chat is woken with the outcome, even across a restart. ADDITION.

  1. New background_run tool on kirocrew-cron, asks before running — justified
  2. New POST /api/workflows/background route with shell-gate and Shared Crew admission — justified
  3. The chat is woken with a card and a queued wake row when the command exits — justified
  4. A pending wake is delivered again after a gateway restart (delivery_pending) — justified
  5. Background commands show as command host runs in the Runs view and in workflow_status/workflow_cancel — justified
  6. New sealed background data-home leaf; a cwd under a mask or seal is refused — justified
  7. Refused for private chats, non-dashboard chats, Windows and restricted shells — justified
  8. Workers never inherit an auto-approve for background_run — justified
  9. is_principal_slice limits a scope kill to this instance's slices — justified
  10. Command echo, output tail and wake prompt are redacted — duplicate of security/text_redaction.py:62

Blockers

Second spelling of security.redact — duplicate of src/kiro_crew/security/text_redaction.py:62
Trigger: the pattern ^\+.*redact_exfiltration_urls\( matches 3 added sites, each followed by redact_credentials: background_commands.py:289 (_redact) and the name and status lines in workflow_startup.py's _deliver_command_outcome. The owner's docstring says "neither order of two sequential passes is right. Call this instead of hand-sequencing them."
Outcome: the chained passes miss overlapping spans that pass_compose.compose catches, and there are now two redaction spellings to keep in step.
Subtraction: delete _redact and the four hand-chained lines, and call kiro_crew.security.redact.
Clears when: no added line calls redact_exfiltration_urls followed by redact_credentials; all three sites go through security.redact.

[FIRST-PRINCIPLES-REVIEWED] 6c2bedb

Description read

[DESCRIPTION-READ] fa6a5c6c76f6ac49230e3d0bf980463ca9b3cdfd8f45550b5b7a87f7af2d396a

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 30, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 6c2bedb

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

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

@github-actions

github-actions Bot commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — 🔴 changes requested (blocking)

GPT 6.1 found at least one blocking issue that must be resolved before merging 6c2bedb67fd1b76618cacc5f056e944044a54154. 1 of 1 blocking finding(s) are security-class and were withheld from adjudication, so the blocking verdict stands.

This comment is updated in place on each push.

BLOCKING -- src/kiro_crew/dashboard/handlers/workflows.py:1029 -- Background commands bypass prefixed operator deny patterns

"execute_bash",
Trigger: With auto_deny_tools=["Running: rm *"], an unrestricted dashboard agent calls background_run("rm build.log"); the route reaches _background_command_denial, which judges execute_bash and the bare command, neither matching the configured pattern.
Outcome: The command deletes the project file despite the deny that rejects the ordinary Running: rm build.log shell call; the sandbox permits this project-file write.
Anchor: residual/security
Fix: Judge Running: <command> as the display title while retaining execute_bash as the tool identity, preserving both title-based and tool-name denials.
Sites: src/kiro_crew/hook_runtime/gate_tiers.py:_tier_deny_rules also misses user-added deny regexes and companion-overlay globs anchored to Running: through this same call.

[BLOCK-MERGE] 6c2bedb
[GPT-REVIEWED] 6c2bedb

Adjudication (Opus 5.5) — is blocking on each finding proportionate?

The adjudicable block is empty. For the one fenced finding, F1, my ruling is UPHOLD-FENCED. That ruling cannot unblock anything, and F1 keeps blocking the merge.

F1: I checked the bypass against the code and it holds:

  • What the gate sees: _background_command_denial (src/kiro_crew/dashboard/handlers/workflows.py:1029) sends the gate only the tool name execute_bash and the bare command. No Running: <command> title is passed. Yet the same file builds exactly that title for the hook matcher at workflows.py:953.
  • Why the pattern misses: _tier_deny_rules (src/kiro_crew/hook_runtime/gate_tiers.py:806) checks the operator's auto_deny_tools globs against each deny target with plain fnmatch. That is the glob tier described at src/kiro_crew/security/deny_gate.py:659. A pattern like Running: rm * matches none of execute_bash, rm build.log or the title-derived targets.
  • The failure condition is common: an operator writes a prefixed deny pattern, the title shape kiro-cli gives every shell call. Nothing about it is extreme or contradictory, so there is no basis for a FLAG.

[ADJUDICATION] 6c2bedb total=0 uphold=0 downgrade=0
[GPT-ADJUDICATED] 6c2bedb

[ADJUDICATION-FENCED] 6c2bedb fenced=1 flagged=0
UPHOLD-FENCED F1 src/kiro_crew/dashboard/handlers/workflows.py:1029 -- The gate call passes only execute_bash and the bare command, never the Running: <command> title, so an operator's ordinary prefixed auto_deny_tools glob (fnmatch at gate_tiers.py:806) never matches and the operator's own deny is silently bypassed.
[GPT-ADJUDICATED-FENCED] 6c2bedb

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

@github-actions

github-actions Bot commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor

Security Scope Review -- ✅ PASS

Which legitimate operations does a1fe31b08fb9c3d9321269fb4420f01fc5979381 newly refuse? Updated in place on each push. A script-confirmed regression blocks; the model proposes candidates and never decides a refusal.

Verdict basis: adjudicated, zero confirmed regressions.

Security scope review -- adjudicated candidates

  • macos-latest (platform posix): 13 classified, 0 newly refused, 13 still allowed.
  • ubuntu-latest (platform posix): 13 classified, 0 newly refused, 13 still allowed.
  • windows-latest (platform windows): 5 classified, 0 newly refused, 5 still allowed.

No candidate flipped from allowed to refused.

Scope-Verdict: PASS

Reason: The diff doesn't touch any of the three shell deny tiers. It only makes three places stricter: the auto-approval predicate (may_skip_gate / narrowed_grant), the file-tool write-protected path list, and the sandbox read-only leaf lists. None of those can be measured by classifying a shell command line, so they are named under UNADJUDICATED below. There is one narrowing I can argue but not confirm: a call path that asks may_skip_gate_now("@kirocrew-cron") directly, without going through narrowed_grant, now prompts for every cron verb, not only background_run.

TIGHTENING: auto-approval predicate, plus the write-protected and read-only path lists -- the threat is a prompt-injected agent auto-approving background_run (unprompted arbitrary command execution), or forging the pid/exit record the gateway acts on: + if reaches_never_auto_approved(ref): / + return False in platform/governance.py may_skip_gate, with +NEVER_AUTO_APPROVED: tuple[str, ...] = ("@kirocrew-cron/background_run",), and + "background", # gateway-owned command records: a forged one would aim its kill in security/paths_lists.py _WRITE_PROTECTED_HOME_PATHS.

ADJUDICATED: 18 candidates, 0 confirmed newly-refused

PLATFORM COVERAGE: I wrote posix rows for:

  • reads of the new background/ leaf under both crew-home prefixes (~/.kiro/crew and ~/.kirocrew), because the write-protected list expands to both;
  • the long commands an agent would hand to background_run, which the same on_tool_call shell gate judges as execute_bash;
  • a kill of the agent's own process, next to the gateway's new pid signalling;
  • kirocrew doctor;
  • a systemd slice status read.

I wrote windows rows for:

  • the same log read in PowerShell ($env:USERPROFILE, \ separators) and in cmd (%USERPROFILE%);
  • .venv\Scripts\python.exe, npm.cmd and kirocrew.exe.

The diff assumes POSIX in one place: background_run spawns /bin/sh -c and refuses on Windows with background_run_unsupported. That is a new feature that is unavailable there, not an operation Windows loses. No other assumed spelling was left without a candidate.

UNADJUDICATED:

  • The may_skip_gate predicate. It now refuses any ref that entry_reaches @kirocrew-cron/background_run, which includes @kirocrew-cron, @kirocrew-cron/*, *, case-folded server spellings, the bare verb, and non-@ verb globs such as *_run.
    • Call paths: auto_approve._ceiling_split, kas_agents._ceiling_permitted, kas_auto_approve.narrow_skill_view and governance._past_never_auto_approved narrow such a grant to the server's other verbs.
    • kas_agents.to_client_custom_agent → merge_user_permissions(..., ceiling_permits=may_skip_gate_now) passes the predicate without narrowing. An authored permissions allow for @kirocrew-cron there would be withheld whole.
    • Inputs I would have submitted:
      • @kirocrew-cron in allowedTools, expecting cron_list, cron_pause, cron_resume, cron_trigger and cron_remove to keep auto-approving;
      • an authored KAS permissions allow on @kirocrew-cron, expecting the same;
      • a non-cron MCP grant whose verb glob happens to match background_run, such as @other/*_run. My reading is that this does not reach the ref, because the @ pattern only matches @other/...; a bare *_run would.
    • narrowed_grant also fails closed when managed_tool_names_for_policy("kirocrew-cron") returns None. In that case the whole-server grant goes and nothing replaces it, so every cron verb prompts.
  • _WRITE_PROTECTED_HOME_PATHS and the sandbox lists. _WRITE_PROTECTED_HOME_PATHS now includes .kiro/crew/background and .kirocrew/background. The sandbox _CREW_READONLY_LEAVES, the precreate list and the no-follow list now include background.
    • Call path: file-edit tool → hooks.on_tool_call → is_sensitive_write_path; the sandbox wrap mounts the leaf read-only.
    • Input I would have submitted: a file-tool write under ~/.kiro/crew/background/.... I found no existing writer of that leaf in the base tree, so nothing is lost today.
  • New refusals on the new /api/workflows/background route. These are _shell_restriction_refusal, the cwd check (is_sensitive_write_path or path_within_tier_mask → background_run_cwd_invalid), the private-chat check and the sandbox-backend check. They gate a capability that didn't exist before, so no previously allowed operation is lost.

[SCOPE-REVIEWED] a1fe31b

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running labels Oct 30, 2026
@Yangxinyee

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 115df84
  • What rule changed: adds one crew-home leaf, background (the gateway's background command records, exit statuses and logs). It is READONLY in every sandbox mode and precreated (sandbox_leaves, sandbox_precreate), and write-protected for the file tools (paths_lists._WRITE_PROTECTED_HOME_PATHS). It also registers one new redaction sink (security_posture_sinks_delivery) and adds sandbox_tiers.path_within_tier_mask, which shares the tier-mask resolver _tier_mask_dirs with carveout_shadowed_by_foreign_mask (that resolution moved there unchanged; sandbox.py only forwards the two names).
  • Before -> after (what was allowed/blocked, now): before, an agent could write <data home>/background/; now it can read it, but neither a sandboxed shell nor a file tool can write it. No deny tier, pattern or existing path disposition changed.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): if the seal failed, an agent could forge a record and aim the gateway's kill at another process, though every signal re-checks the recorded process start identity first. If it is too tight, background_run cannot write its records and is refused; no other tool is affected.
  • Evidence checked (which sandbox result proves it): unit tests test_sandbox_governance_mask.py (the leaf is sealed in every mode and edit-refused by the file gate), test_sandbox_protected_name_holds.py and the background command tests. An earlier round ran BackgroundCommandService through the real sandbox-exec on macOS (a command writing another run's record was refused), and the namespace-sandbox CI lane passed on earlier heads. The real sandbox was not re-run for this head: this host's shell already runs inside a sandbox, so sandbox-exec cannot nest.
  • No regression:
    • Tools still work (which tools/commands were run, result): Security Scope Review classified its candidates on macOS, Ubuntu and Windows with 0 newly refused; reading the leaf's logs (tail, cat, grep, ls) stays allowed.
    • Backward compatible (old config / old data / old callers still work, how checked): a new leaf only; no existing path, config key or caller changed, and an existing install just gains an empty precreated directory.
    • Existing tests (which suites passed on this head): locally on this head, 3,678 tests across the sandbox, security-gate, pin, background, workflow and inject files (the security line budget raised by this PR's one line and re-run), plus full flake8 and mypy --platform linux; the backend CI lanes run on this PR.
  • How to undo: revert this commit, or remove the background entries from sandbox_leaves.py, sandbox_precreate.py and security/paths_lists.py.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Oct 30, 2026
@Yangxinyee

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 21d0fad
  • What rule changed: adds one crew-home leaf, background (the gateway's background command records, exit statuses and logs). It is READONLY in every sandbox mode and precreated (sandbox_leaves, sandbox_precreate), and write-protected for the file tools (paths_lists._WRITE_PROTECTED_HOME_PATHS). It also registers one new redaction sink (security_posture_sinks_delivery) and adds sandbox_tiers.path_within_tier_mask, which shares the tier-mask resolver _tier_mask_dirs with carveout_shadowed_by_foreign_mask (that resolution moved there unchanged; sandbox.py only forwards the two names).
  • Before -> after (what was allowed/blocked, now): before, an agent could write <data home>/background/; now it can read it, but neither a sandboxed shell nor a file tool can write it. No deny tier, pattern or existing path disposition changed.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): if the seal failed, an agent could forge a record and aim the gateway's kill at another process, though every signal re-checks the recorded process start identity first. If it is too tight, background_run cannot write its records and is refused; no other tool is affected.
  • Evidence checked (which sandbox result proves it): unit tests test_sandbox_governance_mask.py (the leaf is sealed in every mode and edit-refused by the file gate), test_sandbox_protected_name_holds.py and the background command tests. An earlier round ran BackgroundCommandService through the real sandbox-exec on macOS (a command writing another run's record was refused), and the namespace-sandbox CI lane passed on earlier heads. The real sandbox was not re-run for this head: this host's shell already runs inside a sandbox, so sandbox-exec cannot nest.
  • No regression:
    • Tools still work (which tools/commands were run, result): Security Scope Review classified its candidates on macOS, Ubuntu and Windows with 0 newly refused on earlier heads of this change, whose sandbox and path edits are unchanged here; reading the leaf's logs (tail, cat, grep, ls) stays allowed.
    • Backward compatible (old config / old data / old callers still work, how checked): a new leaf only; no existing path, config key or caller changed, and an existing install just gains an empty precreated directory.
    • Existing tests (which suites passed on this head): locally on this head, the 6,440 related tests (sandbox, security-gate, pin, kind and drain, background, workflow and inject files) pass, with one shell-gate test example moved off the curl upload rule main deleted in fix(security): delete the curl-upload deny rule #26469; full flake8 and mypy --platform linux are clean. The backend CI lanes run on this PR.
  • How to undo: revert this commit, or remove the background entries from sandbox_leaves.py, sandbox_precreate.py and security/paths_lists.py.

@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 31, 2026
@Yangxinyee

Copy link
Copy Markdown
Contributor Author

Round on 21d0fad06b, rebased onto current main.

  • GPT 6.1 (the wake drained as the person's own message): fixed. The wake is now queued with a new system-injection kind, BACKGROUND_COMMAND_KIND. The drain writes it as an inject row stamped injectKind: automation_notice, so the crewmate chat and the Sessions page hide it (the completion card is what the person reads). The crew log credits its turn to gateway, and it never merges with the person's messages. The delivery's acknowledgement now looks for that row. New test: test_the_real_drain_writes_the_wake_as_the_gateways_inject_row runs the real drain, and fails with ['user'] == ['inject'] when the kind is not classified.
  • test_crewmate_harness on both shard-6 lanes: fixed. _chat_backend now passes crew_backend=crewmate_backend_pin(...) like every other select_provider_backend caller. A crewmate pinned to a harness this gateway cannot start is refused with 409 background_run_unsupported.
  • Design (an unbounded delivery wait): bounded at 24 h (_WAKE_WAIT_SECS). Past that, the card alone is the delivery and the run's slot and cap entry are freed; a wake still queued stays queued. New test: test_a_wake_that_never_runs_is_given_up_after_its_wait_with_the_card_delivered.
  • Rebase: main deleted the curl upload deny rule (fix(security): delete the curl-upload deny rule #26469), so the route's shell-gate test now uses a --data-binary @ exfiltration, which the gate still refuses. Pins re-measured: lazy imports 122, MCP table unchanged, and main's security budget fits.
  • Local checks: full flake8, mypy --platform linux, isort, the line cap, comment-history, sync-io, harness parity and docs lint are clean. 6,440 related tests pass.

The Sensitive change review template is re-posted for this head and the check is green.

@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 31, 2026
@Yangxinyee

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 820a0a9
  • What rule changed: adds one crew-home leaf, background (the gateway's background command records, exit statuses and logs). It is READONLY in every sandbox mode and precreated (sandbox_leaves, sandbox_precreate), and write-protected for the file tools (paths_lists._WRITE_PROTECTED_HOME_PATHS). It also registers one new redaction sink (security_posture_sinks_delivery) and adds sandbox_tiers.path_within_tier_mask, which shares the tier-mask resolver _tier_mask_dirs with carveout_shadowed_by_foreign_mask (that resolution moved there unchanged; sandbox.py only forwards the two names). background_run is refused (403 background_run_shell_restricted) for any agent whose shell is restricted in any way or whose spec cannot be read (agent_sdk.agent_specs.spec_shell_restriction), and its spawn strips the gateway's Python interpreter variables (strip_python_env=True), as the agent's own shell does.
  • Before -> after (what was allowed/blocked, now): before, an agent could write <data home>/background/; now it can read it, but neither a sandboxed shell nor a file tool can write it. An agent with a restricted shell is refused background_run before anything is registered. No deny tier, pattern or existing path disposition changed. This head is a conflict rebase only. The patch matches the previously reviewed head f00084e668 except for pinned counts and two doc rows: lazy imports 145, MCP routes 341, _PACKAGE_LINE_BUDGET 35,037; this PR's clauses are kept on main's current feature-map Workflows row and toolsSettings row. Main's newer toolsSettings handling (denyByDefault, deniedCommands, write allowedPaths) only changes how a shell call is gated; background_run still refuses any agent with a restricted shell, so its behaviour is unchanged.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): if the seal failed, an agent could forge a record and aim the gateway's kill at another process, though every signal re-checks the recorded process start identity first. If the seal or the restriction check is too tight, background_run is refused and the agent keeps its own shell tool; no other tool is affected.
  • Evidence checked (which sandbox result proves it): unit tests test_sandbox_governance_mask.py (the leaf is sealed in every mode and edit-refused by the file gate), test_sandbox_protected_name_holds.py, the background command tests (including test_the_gateways_python_variables_never_reach_the_command, which runs the real env scrub) and test_background_run_chat.py (every restriction shape on kas, kiro-cli, claude and codex, every spec candidate, the bundled default admitted). On f00084e668, which carries the same patch, every review lane and every backend test lane passed, including the namespace sandbox lane. An earlier round ran BackgroundCommandService through the real sandbox-exec on macOS (a command writing another run's record was refused). The real sandbox was not re-run for this head: this host's shell already runs inside a sandbox, so sandbox-exec cannot nest.
  • No regression:
    • Tools still work (which tools/commands were run, result): Security Scope Review classified its candidates on macOS, Ubuntu and Windows with 0 newly refused on earlier heads of this change, whose sandbox and path edits are unchanged here; reading the leaf's logs (tail, cat, grep, ls) stays allowed.
    • Backward compatible (old config / old data / old callers still work, how checked): a new leaf only; no existing path, config key or caller changed, and an existing install just gains an empty precreated directory.
    • Existing tests (which suites passed on this head): locally, the re-measured pinned-count tests, both facade contract tests, the flake-pattern ratchet, the feature-map check, test_background_run_chat.py and test_held_note_turn_starts.py (2,606 passed on this base, with the suites for the chat queue, MCP routes, dashboard state, workflow inject and security-posture sinks modules main also changed). On the preceding rebase, 9,859 related tests passed: the sandbox, KAS allowedCommands, agent-spec, worker-agent, chat-queue and every suite naming these modules. The pre-push gate ran 20 checks with 0 failed, and flake8, isort, black and mypy on every changed module were clean. 43 tests in test_background_commands.py cannot run on this host because its sandbox blocks ps, so a spawn's process identity cannot be read; CI runs them.
  • How to undo: revert this commit, or remove the background entries from sandbox_leaves.py, sandbox_precreate.py and security/paths_lists.py.

@Yangxinyee

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/architecture/mcp.md, docs/feature-map/README.md, docs/system-specs/common/injected-messages.md, docs/system-specs/modules/security.md, src/kiro_crew/dashboard/chat_runner.py, src/kiro_crew/dashboard/chat_turn/queue_drain.py, src/kiro_crew/dashboard/server_runtime/mcp_routes.py, src/kiro_crew/dashboard/state_parts/dashboard_state.py, src/kiro_crew/data/mcp_tool_titles.json, src/kiro_crew/security_posture_sinks_delivery.py, test/test_dashboard_server_composition_contract_reach.py and test/test_json_object_body_guard.py since this head went green (0f1dd2b -> 7f11b5c); CI re-running.

Against dcdf84b2c5, only the MCP route-table pin changed. Main independently reached 340 rows, so this PR's count is now 341, re-measured with the digest. Every review lane passed on dcdf84b2c5. Its only test reds were two ledger flakes this PR does not touch, both recorded: #32526 (macOS BSD sha256sum) and #32634 (Windows crew-log flush).

@Yangxinyee

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 6542262
  • What rule changed: adds one crew-home leaf, background (the gateway's background command records, exit statuses and logs). It is READONLY in every sandbox mode and precreated (sandbox_leaves, sandbox_precreate), and write-protected for the file tools (paths_lists._WRITE_PROTECTED_HOME_PATHS). It also registers one new redaction sink (security_posture_sinks_delivery) and adds sandbox_tiers.path_within_tier_mask, which shares the tier-mask resolver _tier_mask_dirs with carveout_shadowed_by_foreign_mask (that resolution moved there unchanged; sandbox.py only forwards the two names). background_run is refused (403 background_run_shell_restricted) for any agent whose shell is restricted in any way or whose spec cannot be read (agent_sdk.agent_specs.spec_shell_restriction), and its spawn strips the gateway's Python interpreter variables (strip_python_env=True), as the agent's own shell does.
  • Before -> after (what was allowed/blocked, now): before, an agent could write <data home>/background/; now it can read it, but neither a sandboxed shell nor a file tool can write it. An agent with a restricted shell is refused background_run before anything is registered. No deny tier, pattern or existing path disposition changed. This head is a conflict rebase only. The patch matches the previously reviewed head f00084e668 except for pinned counts, two doc rows and import or constant lists main also extended (main's WORKFLOW_FOLLOWUP_KIND and _OP_DEFINITION_UPDATE_PREVIEW are kept beside this PR's BACKGROUND_COMMAND_KIND and _OP_BACKGROUND_RUN): lazy imports 155, MCP routes 350, _PACKAGE_LINE_BUDGET 35,147, protected names main + 3 per tier (330, 337, 338); this PR's clauses are kept on main's current feature-map Workflows row and toolsSettings row. Main's newer toolsSettings handling (denyByDefault, deniedCommands, write allowedPaths) only changes how a shell call is gated; background_run still refuses any agent with a restricted shell, so its behaviour is unchanged.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): if the seal failed, an agent could forge a record and aim the gateway's kill at another process, though every signal re-checks the recorded process start identity first. If the seal or the restriction check is too tight, background_run is refused and the agent keeps its own shell tool; no other tool is affected.
  • Evidence checked (which sandbox result proves it): unit tests test_sandbox_governance_mask.py (the leaf is sealed in every mode and edit-refused by the file gate), test_sandbox_protected_name_holds.py, the background command tests (including test_the_gateways_python_variables_never_reach_the_command, which runs the real env scrub) and test_background_run_chat.py (every restriction shape on kas, kiro-cli, claude and codex, every spec candidate, the bundled default admitted). On f00084e668, which carries the same patch, every review lane and every backend test lane passed, including the namespace sandbox lane. An earlier round ran BackgroundCommandService through the real sandbox-exec on macOS (a command writing another run's record was refused). The real sandbox was not re-run for this head: this host's shell already runs inside a sandbox, so sandbox-exec cannot nest.
  • No regression:
    • Tools still work (which tools/commands were run, result): Security Scope Review classified its candidates on macOS, Ubuntu and Windows with 0 newly refused on earlier heads of this change, whose sandbox and path edits are unchanged here; reading the leaf's logs (tail, cat, grep, ls) stays allowed.
    • Backward compatible (old config / old data / old callers still work, how checked): a new leaf only; no existing path, config key or caller changed, and an existing install just gains an empty precreated directory.
    • Existing tests (which suites passed on this head): locally, the re-measured pinned-count tests, both facade contract tests, the flake-pattern ratchet, the feature-map check, test_background_run_chat.py and test_held_note_turn_starts.py (3,938 passed on this base across the pin, contract, sandbox, chat queue, MCP route, workflow and background suites, plus 392 after the last rebase; 3 test_sandbox_protected_name_holds.py counts read one higher on this macOS host, as they do on a clean main here, while main's CI passes them). On the preceding rebase, 9,859 related tests passed: the sandbox, KAS allowedCommands, agent-spec, worker-agent, chat-queue and every suite naming these modules. The pre-push gate ran 20 checks with 0 failed, and flake8, isort, black and mypy on every changed module were clean. 43 tests in test_background_commands.py cannot run on this host because its sandbox blocks ps, so a spawn's process identity cannot be read; CI runs them.
  • How to undo: revert this commit, or remove the background entries from sandbox_leaves.py, sandbox_precreate.py and security/paths_lists.py.

@Yangxinyee

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/architecture/mcp.md, docs/feature-map/README.md, docs/system-specs/common/injected-messages.md, docs/system-specs/modules/security.md, docs/system-specs/modules/workflows.md, src/kiro_crew/agent_materialization/worker_agent.py, src/kiro_crew/agent_parts/spec_grants.py, src/kiro_crew/agent_sdk/agent_specs.py, src/kiro_crew/constants.py, src/kiro_crew/dashboard/chat_runner.py, src/kiro_crew/dashboard/chat_turn/queue_drain.py, src/kiro_crew/dashboard/chat_turn/steer_queue.py, src/kiro_crew/dashboard/chat_utils.py, src/kiro_crew/dashboard/chat_utils_injected_rows.py, src/kiro_crew/dashboard/handlers/workflows.py, src/kiro_crew/dashboard/server_runtime/mcp_routes.py, src/kiro_crew/dashboard/server_runtime/workflow_startup.py, src/kiro_crew/dashboard/state_parts/dashboard_state.py, src/kiro_crew/data/mcp_tool_titles.json, src/kiro_crew/docs/agent-spec-fields.md, src/kiro_crew/sandbox.py, src/kiro_crew/sandbox_leaves.py, src/kiro_crew/sandbox_precreate.py, src/kiro_crew/sandbox_tiers.py, src/kiro_crew/security/paths_lists.py, src/kiro_crew/security_posture_sinks_delivery.py, src/kiro_crew/workflows/registry.py, src/kiro_crew/workflows/service.py and 11 test files (the pinned-count, composition-contract, sandbox and worker-agent tests) since this head went green (7f11b5c -> 01fcf6d); CI re-running.

Against 820a0a9153, the changes are confined to the merge:

  • Main's WORKFLOW_FOLLOWUP_KIND and is_workflow_followup sit beside this PR's BACKGROUND_COMMAND_KIND in chat_utils_injected_rows.py and chat_turn/queue_drain.py.
  • Main's _OP_DEFINITION_UPDATE_PREVIEW sits beside _OP_BACKGROUND_RUN in handlers/workflows.py.
  • The pins were re-measured: lazy imports 155 (main 146 + 9), MCP routes 350 (main 349 + 1), _PACKAGE_LINE_BUDGET 35,147 (main + 1), and protected names main + 3 per tier (330, 337, 338).

The AI review lanes on 820a0a9153 failed before reviewing, on the GitHub installation API rate limit at 02:01Z on 11-08, so they produced no findings. Its only test red was ledger flake #32526.

@Yangxinyee

Copy link
Copy Markdown
Contributor Author
  • span=5cbfeb9a8013 an exhausted delivery kept its chat's slot until a restart, and every boot charged it again

fixed in 8a43437: _forget_delivery (the delivery task's done callback) now pops _delivery_owners, so a delivery frees its chat's slot however it ends: acknowledged, refused on every attempt, release not saved, settle write failed, or cancelled. The record stays unsettled and the run held from eviction, so the next boot still re-delivers it, charged only while that boot's delivery is in flight; retention bounds a chat that keeps refusing.
Tests: test_a_delivery_refused_on_every_attempt_frees_its_slot_and_is_made_again_on_boot, test_a_boot_redelivery_refused_again_frees_its_slot and test_a_delivery_whose_release_was_not_saved_still_frees_its_slot each fail with the fix reverted; the spec in workflows.md now says the slot is held only while a delivery is in flight.

resolution: narrowed -- an undelivered outcome holds its chat's slot only while a delivery task is in flight; the record stays unsettled so the next boot still re-delivers
mechanism: an undelivered outcome is charged against the caps only while its delivery task is alive
self-added: no

@Yangxinyee

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 8a43437
  • What rule changed: adds one crew-home leaf, background (the gateway's background command records, exit statuses and logs). It is READONLY in every sandbox mode and precreated (sandbox_leaves, sandbox_precreate), and write-protected for the file tools (paths_lists._WRITE_PROTECTED_HOME_PATHS). It also registers one new redaction sink (security_posture_sinks_delivery) and adds sandbox_tiers.path_within_tier_mask, which shares the tier-mask resolver _tier_mask_dirs with carveout_shadowed_by_foreign_mask (that resolution moved there unchanged; sandbox.py only forwards the two names). background_run is refused (403 background_run_shell_restricted) for any agent whose shell is restricted in any way or whose spec cannot be read (agent_sdk.agent_specs.spec_shell_restriction), and its spawn strips the gateway's Python interpreter variables (strip_python_env=True), as the agent's own shell does.
  • Before -> after (what was allowed/blocked, now): before, an agent could write <data home>/background/; now it can read it, but neither a sandboxed shell nor a file tool can write it. An agent with a restricted shell is refused background_run before anything is registered. No deny tier, pattern or existing path disposition changed. This head answers the Opus 5.5 finding on 654226250f (span 5cbfeb9a8013): a background command's admission slot is now held only while its outcome's delivery task is alive, so a chat that refuses every delivery no longer keeps the slot until a restart. The record stays unsettled and the run held from eviction, so the next boot still re-delivers. No sandbox, path or deny rule changed in this round; the rebase onto main 894c5ae281 re-measured _PACKAGE_LINE_BUDGET to 35,161 (main + 1).
  • Worst case if wrong (breaks commands / leaks secret / locks user out): if the seal failed, an agent could forge a record and aim the gateway's kill at another process, though every signal re-checks the recorded process start identity first. If the seal or the restriction check is too tight, background_run is refused and the agent keeps its own shell tool; no other tool is affected.
  • Evidence checked (which sandbox result proves it): unit tests test_sandbox_governance_mask.py (the leaf is sealed in every mode and edit-refused by the file gate), test_sandbox_protected_name_holds.py, the background command tests (including test_the_gateways_python_variables_never_reach_the_command, which runs the real env scrub) and test_background_run_chat.py (every restriction shape on kas, kiro-cli, claude and codex, every spec candidate, the bundled default admitted). On f00084e668, which carries the same patch, every review lane and every backend test lane passed, including the namespace sandbox lane. An earlier round ran BackgroundCommandService through the real sandbox-exec on macOS (a command writing another run's record was refused). The real sandbox was not re-run for this head: this host's shell already runs inside a sandbox, so sandbox-exec cannot nest.
  • No regression:
    • Tools still work (which tools/commands were run, result): Security Scope Review classified its candidates on macOS, Ubuntu and Windows with 0 newly refused on earlier heads of this change, whose sandbox and path edits are unchanged here; reading the leaf's logs (tail, cat, grep, ls) stays allowed.
    • Backward compatible (old config / old data / old callers still work, how checked): a new leaf only; no existing path, config key or caller changed, and an existing install just gains an empty precreated directory.
    • Existing tests (which suites passed on this head): locally, the three new regression tests in test_background_commands.py (each fails with the fix reverted) and test_background_run_chat.py (144 passed), the pinned-count tests, both facade contract tests, the flake-pattern ratchet and the feature-map check (323 passed across those suites on this base; 504 on the previous base), and the pre-push gate (20 checks, 0 failed); flake8, isort, black and mypy on every changed module were clean. 3 test_sandbox_protected_name_holds.py counts read one higher on this macOS host, as they do on a clean main here, while main's CI passes them. 42 to 43 tests in test_background_commands.py cannot run on this host because its sandbox blocks ps; CI runs them.
  • How to undo: revert this commit, or remove the background entries from sandbox_leaves.py, sandbox_precreate.py and security/paths_lists.py.

@Yangxinyee

Copy link
Copy Markdown
Contributor Author
  • span=3dc38755f6bd a Bot's worker session was judged by the shared worker base spec, not its merged spec

fixed in ed295f8: spec_shell_restriction (agent_sdk/agent_specs.py) now refuses agent kirocrew-mate-worker by name before reading any spec, so a Bot's worker session gets 403 background_run_shell_restricted and nothing is registered or started. Its session runs mate_worker.worker_session_spec (the base plus the Bot's own file), which no by-name read sees, so the narrow answer is to refuse that session rather than judge a second spec.
Test: test_a_bots_worker_session_gets_no_background_command (kas, kiro, claude, codex) returns 200 with the fix reverted and 403 with it. Swept: the Bot's own chat runs the stock conductor spec; conductors, sub-agents and task runners either have no per-session merge or are not chat slots.

resolution: narrowed -- background_run is refused in a Bot's worker session, whose effective spec is merged per session, instead of judging that merged spec
mechanism: background_run refuses the Bot worker agent by name before any spec read
self-added: no

@Yangxinyee

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: ed295f8
  • What rule changed: adds one crew-home leaf, background (the gateway's background command records, exit statuses and logs). It is READONLY in every sandbox mode and precreated (sandbox_leaves, sandbox_precreate), and write-protected for the file tools (paths_lists._WRITE_PROTECTED_HOME_PATHS). It also registers one new redaction sink (security_posture_sinks_delivery) and adds sandbox_tiers.path_within_tier_mask, which shares the tier-mask resolver _tier_mask_dirs with carveout_shadowed_by_foreign_mask (that resolution moved there unchanged; sandbox.py only forwards the two names). background_run is refused (403 background_run_shell_restricted) for any agent whose shell is restricted in any way or whose spec cannot be read (agent_sdk.agent_specs.spec_shell_restriction), and its spawn strips the gateway's Python interpreter variables (strip_python_env=True), as the agent's own shell does.
  • Before -> after (what was allowed/blocked, now): before, an agent could write <data home>/background/; now it can read it, but neither a sandboxed shell nor a file tool can write it. An agent with a restricted shell is refused background_run before anything is registered. No deny tier, pattern or existing path disposition changed. This head answers the Opus 5.5 finding on 8a43437303 (span 3dc38755f6bd): background_run is now refused, 403 background_run_shell_restricted, in a Bot's worker session (agent kirocrew-mate-worker) before any spec is read, because that session runs a per-session merged spec (the worker base plus the Bot's own file) the restriction check does not read. The previous round's change stays: an outcome's delivery holds its chat's admission slot only while it is in flight. No sandbox, path or deny rule changed in this round; the rebase onto main 7d498a8647 was clean.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): if the seal failed, an agent could forge a record and aim the gateway's kill at another process, though every signal re-checks the recorded process start identity first. If the seal or the restriction check is too tight, background_run is refused and the agent keeps its own shell tool; no other tool is affected.
  • Evidence checked (which sandbox result proves it): unit tests test_sandbox_governance_mask.py (the leaf is sealed in every mode and edit-refused by the file gate), test_sandbox_protected_name_holds.py, the background command tests (including test_the_gateways_python_variables_never_reach_the_command, which runs the real env scrub) and test_background_run_chat.py (every restriction shape on kas, kiro-cli, claude and codex, every spec candidate, the bundled default admitted). On f00084e668, which carries the same patch, every review lane and every backend test lane passed, including the namespace sandbox lane. An earlier round ran BackgroundCommandService through the real sandbox-exec on macOS (a command writing another run's record was refused). The real sandbox was not re-run for this head: this host's shell already runs inside a sandbox, so sandbox-exec cannot nest.
  • No regression:
    • Tools still work (which tools/commands were run, result): Security Scope Review classified its candidates on macOS, Ubuntu and Windows with 0 newly refused on earlier heads of this change, whose sandbox and path edits are unchanged here; reading the leaf's logs (tail, cat, grep, ls) stays allowed.
    • Backward compatible (old config / old data / old callers still work, how checked): a new leaf only; no existing path, config key or caller changed, and an existing install just gains an empty precreated directory.
    • Existing tests (which suites passed on this head): locally, test_a_bots_worker_session_gets_no_background_command on kas, kiro, claude and codex (200 with the fix reverted, 403 with it), test_background_run_chat.py, the chat-queue suites main also changed, both facade contract tests, the composition contracts and the feature-map check (669 passed on this base, 1,707 on the previous one, 653 when the fix was made), and the pre-push gate (20 checks, 0 failed); flake8, isort, black and mypy on every changed module were clean. On the previous head 8a43437303 every CI test shard passed, Linux, macOS and Windows. 3 test_sandbox_protected_name_holds.py counts read one higher on this macOS host, as they do on a clean main here, while main's CI passes them. About 42 tests in test_background_commands.py cannot run on this host because its sandbox blocks ps; CI runs them.
  • How to undo: revert this commit, or remove the background entries from sandbox_leaves.py, sandbox_precreate.py and security/paths_lists.py.

@Yangxinyee

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 3fdbffd
  • What rule changed: adds one crew-home leaf, background (the gateway's background command records, exit statuses and logs). It is READONLY in every sandbox mode and precreated (sandbox_leaves, sandbox_precreate), and write-protected for the file tools (paths_lists._WRITE_PROTECTED_HOME_PATHS). It also registers one new redaction sink (security_posture_sinks_delivery) and adds sandbox_tiers.path_within_tier_mask, which shares the tier-mask resolver _tier_mask_dirs with carveout_shadowed_by_foreign_mask (that resolution moved there unchanged; sandbox.py only forwards the two names). background_run is refused (403 background_run_shell_restricted) for any agent whose shell is restricted in any way or whose spec cannot be read (agent_sdk.agent_specs.spec_shell_restriction), and its spawn strips the gateway's Python interpreter variables (strip_python_env=True), as the agent's own shell does.
  • Before -> after (what was allowed/blocked, now): before, an agent could write <data home>/background/; now it can read it, but neither a sandboxed shell nor a file tool can write it. An agent with a restricted shell is refused background_run before anything is registered. No deny tier, pattern or existing path disposition changed. This head is a conflict rebase only: the patch matches ed295f8200, which every review lane passed (Opus 5.5, GPT 6.1, Design, First Principles, UX, Sensitive Change, Security Scope). Only one agent-spec-fields.md sentence was re-applied on main's new text. background_run stays refused in a Bot's worker session (agent kirocrew-mate-worker), and an outcome's delivery holds its chat's admission slot only while it is in flight. No sandbox, path or deny rule changed.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): if the seal failed, an agent could forge a record and aim the gateway's kill at another process, though every signal re-checks the recorded process start identity first. If the seal or the restriction check is too tight, background_run is refused and the agent keeps its own shell tool; no other tool is affected.
  • Evidence checked (which sandbox result proves it): unit tests test_sandbox_governance_mask.py (the leaf is sealed in every mode and edit-refused by the file gate), test_sandbox_protected_name_holds.py, the background command tests (including test_the_gateways_python_variables_never_reach_the_command, which runs the real env scrub) and test_background_run_chat.py (every restriction shape on kas, kiro-cli, claude and codex, every spec candidate, the bundled default admitted). On f00084e668, which carries the same patch, every review lane and every backend test lane passed, including the namespace sandbox lane. An earlier round ran BackgroundCommandService through the real sandbox-exec on macOS (a command writing another run's record was refused). The real sandbox was not re-run for this head: this host's shell already runs inside a sandbox, so sandbox-exec cannot nest.
  • No regression:
    • Tools still work (which tools/commands were run, result): Security Scope Review classified its candidates on macOS, Ubuntu and Windows with 0 newly refused on earlier heads of this change, whose sandbox and path edits are unchanged here; reading the leaf's logs (tail, cat, grep, ls) stays allowed.
    • Backward compatible (old config / old data / old callers still work, how checked): a new leaf only; no existing path, config key or caller changed, and an existing install just gains an empty precreated directory.
    • Existing tests (which suites passed on this head): locally, test_background_run_chat.py (including test_a_bots_worker_session_gets_no_background_command on kas, kiro, claude and codex), the chat-queue suites main also changed, both facade contract tests, the composition contracts and the line budget (492 passed on this base, 405 on the previous rebase), and the pre-push gate (20 checks, 0 failed). On ed295f8200 the CI test shards passed except a crew-log timeline test this PR does not touch (test_taskq_timeline.py, intermittent: it passed on 8a43437303), which the Coverage Gate follows. About 42 tests in test_background_commands.py cannot run on this host because its sandbox blocks ps; CI runs them.
  • How to undo: revert this commit, or remove the background entries from sandbox_leaves.py, sandbox_precreate.py and security/paths_lists.py.

@Yangxinyee

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 8e822be
  • What rule changed: adds one crew-home leaf, background (the gateway's background command records, exit statuses and logs). It is READONLY in every sandbox mode and precreated (sandbox_leaves, sandbox_precreate), and write-protected for the file tools (paths_lists._WRITE_PROTECTED_HOME_PATHS). It also registers one new redaction sink (security_posture_sinks_delivery) and adds sandbox_tiers.path_within_tier_mask, which shares the tier-mask resolver _tier_mask_dirs with carveout_shadowed_by_foreign_mask (that resolution moved there unchanged; sandbox.py only forwards the two names). background_run is refused (403 background_run_shell_restricted) for any agent whose shell is restricted in any way or whose spec cannot be read (agent_sdk.agent_specs.spec_shell_restriction), and its spawn strips the gateway's Python interpreter variables (strip_python_env=True), as the agent's own shell does.
  • Before -> after (what was allowed/blocked, now): before, an agent could write <data home>/background/; now it can read it, but neither a sandboxed shell nor a file tool can write it. An agent with a restricted shell is refused background_run before anything is registered. No deny tier, pattern or existing path disposition changed. This head changes only a test helper: _settled in test_background_commands.py now waits for the delivery task's done callback, which frees the chat's slot, before it returns. On Python 3.12 gather on an ended task returns without yielding, so the helper could return first and test_a_cancel_during_settlement_still_settles_the_run read running_for == 1 intermittently in CI's new-test stability lane. A new test, test_settling_waits_for_an_ended_delivery_to_free_its_slot, reproduces that order without a process. Product code is unchanged from ed295f8200, which every review lane passed. No sandbox, path or deny rule changed.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): if the seal failed, an agent could forge a record and aim the gateway's kill at another process, though every signal re-checks the recorded process start identity first. If the seal or the restriction check is too tight, background_run is refused and the agent keeps its own shell tool; no other tool is affected.
  • Evidence checked (which sandbox result proves it): unit tests test_sandbox_governance_mask.py (the leaf is sealed in every mode and edit-refused by the file gate), test_sandbox_protected_name_holds.py, the background command tests (including test_the_gateways_python_variables_never_reach_the_command, which runs the real env scrub) and test_background_run_chat.py (every restriction shape on kas, kiro-cli, claude and codex, every spec candidate, the bundled default admitted). On f00084e668, which carries the same patch, every review lane and every backend test lane passed, including the namespace sandbox lane. An earlier round ran BackgroundCommandService through the real sandbox-exec on macOS (a command writing another run's record was refused). The real sandbox was not re-run for this head: this host's shell already runs inside a sandbox, so sandbox-exec cannot nest.
  • No regression:
    • Tools still work (which tools/commands were run, result): Security Scope Review classified its candidates on macOS, Ubuntu and Windows with 0 newly refused on earlier heads of this change, whose sandbox and path edits are unchanged here; reading the leaf's logs (tail, cat, grep, ls) stays allowed.
    • Backward compatible (old config / old data / old callers still work, how checked): a new leaf only; no existing path, config key or caller changed, and an existing install just gains an empty precreated directory.
    • Existing tests (which suites passed on this head): locally, the new helper test (fails with the helper change reverted) and the three slot-release regression tests, test_background_run_chat.py, test_agent_refactor_contracts.py and test_worker_agent.py (main changed the former), the composition contracts and the line budget (469 passed), the flake-pattern ratchet, and the pre-push gate (20 checks, 0 failed); flake8, isort, black and mypy were clean. On 3fdbffd917 the other CI reds were the installation rate limit (GPT 6.1's withheld verdict reported no findings) and two intermittent tests this PR does not touch: test_taskq_timeline.py (passes locally) and test_transcript_binding_join_sites.py, a timeout tracked in Flaky: test_every_history_key_change_joins_the_alias_group times out on Linux #34284. About 42 tests in test_background_commands.py cannot run on this host because its sandbox blocks ps; CI runs them.
  • How to undo: revert this commit, or remove the background entries from sandbox_leaves.py, sandbox_precreate.py and security/paths_lists.py.

@Zedmor

Zedmor commented Nov 10, 2026

Copy link
Copy Markdown
Contributor

Code change approver recommendation: A person should decide

Automated, not a person, and not a review: a maintainer still decides.

decider-v3c@217fe607 · p_defect 0.2 · router R0 (approves only when p_defect <= 0.12, on changes of at most 400 changed lines) · head 8e822bec3a · 6481 changed lines

Why: the decider approves but is not confident enough to auto-approve (p_defect 0.2 > 0.12).

Adds background_run: a gateway-owned shell command on the workflow host-run substrate that wakes the chat with its outcome and survives a restart. I checked the key boundaries and found no blocking defects. The tool sits on kirocrew-cron, which no shipped allowedTools auto-approves, so kiro-cli asks first. The route refuses non-internal callers, private chats and agents with any shell restriction or PreToolUse hook, then runs the same HookManager gate as execute_bash. The sandbox never drops below standard, and the working directory is pinned and refused if it sits inside a mask or seal; the new background folder is sealed read-only. Host runs register with completion_injection=False, so the generic completion hook never double-posts. delivery_pending is written only when set, and every path releases it, so eviction of existing runs is unchanged. Reconcile runs before admission and retries with admission closed, and shutdown leaves commands running for the next boot to re-adopt. The new kind drains as a gateway inject row. Tests are extensive and deterministic. The remaining risks are unverified behaviour under real systemd and launchd restarts, and CI jobs still pending.

If this recommendation is wrong, reply here; the replies are how the approver is evaluated.

@Yangxinyee

Copy link
Copy Markdown
Contributor Author
  • span=02c55bd49e46 a grant covering background_run (a whole-server @kirocrew-cron, a wildcard) auto-approved it, so its approval never reached a human

fixed in 46fc84c: @kirocrew-cron/background_run is now never auto-approved, for any agent, on any route, as execute_bash is not (NEVER_AUTO_APPROVED, reaches_never_auto_approved and narrowed_grant in agent_sdk/drivers/acp.py, matched with the existing mcp_refs.entry_reaches). _may_auto_approve refuses any ref that reaches it. _ceiling_split (used by _apply_allowed_tools_ceiling, final_ceiling_pass and _filter_auto_approve) replaces a covering grant with the cron server's other verbs, read from its declaration (managed_tool_names_for_policy), so those keep their auto-approve. If that declaration is unreadable, the covering grant is dropped and per-verb grants beside it stand. Doctor mints the narrowed form. On KAS, _ceiling_permitted narrows an on-disk spec that predates the fix, and an authored permissions allow that could cover background_run is not relayed (_never_covering_background_run); a deny still travels.
Tests: test_background_run_never_auto_approved.py (31 tests, 29 fail with the fix reverted) covers the ceiling, the build, the rebuild's final pass, the conductor filter, the fail-closed fallback, the audit, the derived KAS block, the projection of a spec on disk, authored KAS permissions and doctor. The doctor and worker pins now assert the narrowed form. Spec: workflows.md (Background commands) and the allowedTools row in agent-spec-fields.md.

resolution: narrowed -- background_run is never auto-approved by any grant, on every writer and the KAS projection; a covering grant is narrowed to the cron server's other declared verbs
mechanism: a shared never-auto-approve list consulted by the auto-approve predicate, the list split every writer uses, doctor, and the KAS projection
self-added: no

@Yangxinyee

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 46fc84c
  • What rule changed: adds one crew-home leaf, background (the gateway's background command records, exit statuses and logs). It is READONLY in every sandbox mode and precreated (sandbox_leaves, sandbox_precreate), and write-protected for the file tools (paths_lists._WRITE_PROTECTED_HOME_PATHS). It also registers one new redaction sink (security_posture_sinks_delivery) and adds sandbox_tiers.path_within_tier_mask, which shares the tier-mask resolver _tier_mask_dirs with carveout_shadowed_by_foreign_mask (that resolution moved there unchanged; sandbox.py only forwards the two names). background_run is refused (403 background_run_shell_restricted) for any agent whose shell is restricted in any way or whose spec cannot be read (agent_sdk.agent_specs.spec_shell_restriction), and its spawn strips the gateway's Python interpreter variables (strip_python_env=True), as the agent's own shell does. New in this head: @kirocrew-cron/background_run is never auto-approved, for any agent, on any route, as execute_bash is not (agent_sdk.drivers.acp.NEVER_AUTO_APPROVED). Every allowedTools writer (_may_auto_approve and _ceiling_split in auto_approve.py), doctor, the KAS projection (_ceiling_permitted) and authored KAS permissions withhold it, and a grant covering it (@kirocrew-cron, @kirocrew-cron/*, *) is narrowed to the cron server's other declared verbs.
  • Before -> after (what was allowed/blocked, now): before, an agent could write <data home>/background/; now it can read it, but neither a sandboxed shell nor a file tool can write it. An agent with a restricted shell is refused background_run before anything is registered. Before this head, a whole-server @kirocrew-cron grant (which kirocrew doctor mints on an ungoverned host) auto-approved background_run, so a command could start with no prompt. Now every background_run call prompts, and the other cron verbs keep the auto-approve they had. An allowedTools list that is only * now auto-approves just the cron server's other verbs: kiro-cli cannot express "every tool but one", so the narrowing errs toward a prompt. No deny tier, pattern or existing path disposition changed.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): if the seal failed, an agent could forge a record and aim the gateway's kill at another process, though every signal re-checks the recorded process start identity first. If the seal or the restriction check is too tight, background_run is refused and the agent keeps its own shell tool. If the narrowing is too wide, a cron verb that was auto-approved prompts instead; if the cron declaration cannot be read, the covering grant is dropped (fail closed) and per-verb grants beside it stand. No tool loses access; at worst it asks.
  • Evidence checked (which sandbox result proves it): unit tests test_sandbox_governance_mask.py (the leaf is sealed in every mode and edit-refused by the file gate), test_sandbox_protected_name_holds.py, the background command tests (including test_the_gateways_python_variables_never_reach_the_command, which runs the real env scrub) and test_background_run_chat.py (every restriction shape on kas, kiro-cli, claude and codex, every spec candidate, the bundled default admitted). New: test_background_run_never_auto_approved.py, 31 tests, 29 of which fail with the fix reverted. It covers every covering spelling through the ceiling, build_agent_config, the rebuild's final pass and the conductor filter, the fail-closed fallback, the audit record, the derived KAS block on disk, the projection of a spec on disk that predates the fix, authored KAS allows (a deny still travels) and doctor's mint (idempotent). An earlier round ran BackgroundCommandService through the real sandbox-exec on macOS (a command writing another run's record was refused). The real sandbox was not re-run for this head: this host's shell already runs inside a sandbox, so sandbox-exec cannot nest.
  • No regression:
    • Tools still work (which tools/commands were run, result): the other @kirocrew-cron verbs stay auto-approved after narrowing (asserted per covering spelling); Security Scope Review classified its candidates on macOS, Ubuntu and Windows with 0 newly refused on earlier heads of this change, whose sandbox and path edits are unchanged here; reading the leaf's logs (tail, cat, grep, ls) stays allowed.
    • Backward compatible (old config / old data / old callers still work, how checked): a spec on disk carrying @kirocrew-cron whole is narrowed on the next build and on every KAS projection, without doctor removing a user decision; the doctor and worker pins (test_cli_mcp_doctor.py, test_worker_agent.py) now assert the narrowed form. A new leaf only otherwise; an existing install just gains an empty precreated directory.
    • Existing tests (which suites passed on this head): locally, every test file that names _apply_allowed_tools_ceiling, _may_auto_approve, _ceiling_permitted, derived_agent_permissions or allowedTools (180 files), the composition contracts, the hooks contract, the facade guards, the agent-sdk boundary and the line budget, and the pre-push gate (20 checks, 0 failed); flake8, isort, black and mypy were clean on the changed files. Failures that are this host's own and that this change does not touch: the KAS engine-install tests (test_kas_bundle*, test_kas_route; they fail the same way with the fix reverted, because the sandbox cannot install the engine), test_cli_stt_memory_doctor.py (the host's kiro-cli sandbox setting), one test_pptx_maker_provision.py case (a Homebrew pdftoppm earlier on PATH), and the protected-name count, which reads one higher on macOS than in CI. About 42 tests in test_background_commands.py cannot run on this host because its sandbox blocks ps; CI runs them.
  • How to undo: revert this commit, or remove the background entries from sandbox_leaves.py, sandbox_precreate.py and security/paths_lists.py, and empty NEVER_AUTO_APPROVED.

@KiroCrewCaptain

KiroCrewCaptain commented Nov 11, 2026 •

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: Request changes

Why: the decider found 1 problem and estimates an 82% chance that this change introduces a defect, at or above the 80% level where it asks for changes.

The background_run feature is carefully built, but the rule that it must never be auto-approved shrinks a \"*\" allowedTools grant to only the kirocrew-cron verbs and saves that to disk on spec rebuild. Existing agents lose auto-approval for every builtin and every other MCP server, which is a regression from main and contradicts the PR's backwards-compatibility claim.

Problems found:

  • An agent spec with allowedTools: ["*"] (documented as 'every tool') is rewritten to only the other kirocrew-cron verbs, and the rewrite is saved to disk on rebuild. On main may_skip_gate("*") kept the grant on an ungoverned host, so every builtin and other-MCP-server auto-approval is lost and ca (src/kiro_crew/agent_sdk/drivers/acp.py, high)

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

@Yangxinyee

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 0601ec4
  • What rule changed: adds one crew-home leaf, background (the gateway's background command records, exit statuses and logs). It is READONLY in every sandbox mode and precreated (sandbox_leaves, sandbox_precreate), and write-protected for the file tools (paths_lists._WRITE_PROTECTED_HOME_PATHS). It also registers one new redaction sink (security_posture_sinks_delivery) and adds sandbox_tiers.path_within_tier_mask, which shares the tier-mask resolver _tier_mask_dirs with carveout_shadowed_by_foreign_mask (that resolution moved there unchanged; sandbox.py only forwards the two names). background_run is refused (403 background_run_shell_restricted) for any agent whose shell is restricted in any way or whose spec cannot be read (agent_sdk.agent_specs.spec_shell_restriction), and its spawn strips the gateway's Python interpreter variables (strip_python_env=True), as the agent's own shell does. Since 46fc84c211: @kirocrew-cron/background_run is never auto-approved, for any agent, on any route, as execute_bash is not (agent_sdk.drivers.acp.NEVER_AUTO_APPROVED). Every allowedTools writer (_may_auto_approve and _ceiling_split in auto_approve.py), doctor, the KAS projection (_ceiling_permitted) and authored KAS permissions withhold it, and a grant covering it (@kirocrew-cron, @kirocrew-cron/*, *) is narrowed to the cron server's other declared verbs.
  • Before -> after (what was allowed/blocked, now): this head is 46fc84c211 rebased onto main for a conflict (main's new agent-spec-fields.md hooks sentence kept beside ours; the MCP route-table pin re-measured at main's 348 + 1), plus one test update: test_mate_migration_real_kirocrew.py::test_an_upgraded_kirocrew_still_moves now asserts that an older install's whole-server @kirocrew-cron grant comes back narrowed (CI's backend shards found it on 46fc84c211; it passed vacuously in a linked worktree, whose rewrite of an existing agent home is declined, so the test now lifts that guard). No product code changed since 46fc84c211. before, an agent could write <data home>/background/; now it can read it, but neither a sandboxed shell nor a file tool can write it. An agent with a restricted shell is refused background_run before anything is registered. Before this head, a whole-server @kirocrew-cron grant (which kirocrew doctor mints on an ungoverned host) auto-approved background_run, so a command could start with no prompt. Now every background_run call prompts, and the other cron verbs keep the auto-approve they had. An allowedTools list that is only * now auto-approves just the cron server's other verbs: kiro-cli cannot express "every tool but one", so the narrowing errs toward a prompt. No deny tier, pattern or existing path disposition changed.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): if the seal failed, an agent could forge a record and aim the gateway's kill at another process, though every signal re-checks the recorded process start identity first. If the seal or the restriction check is too tight, background_run is refused and the agent keeps its own shell tool. If the narrowing is too wide, a cron verb that was auto-approved prompts instead; if the cron declaration cannot be read, the covering grant is dropped (fail closed) and per-verb grants beside it stand. No tool loses access; at worst it asks.
  • Evidence checked (which sandbox result proves it): unit tests test_sandbox_governance_mask.py (the leaf is sealed in every mode and edit-refused by the file gate), test_sandbox_protected_name_holds.py, the background command tests (including test_the_gateways_python_variables_never_reach_the_command, which runs the real env scrub) and test_background_run_chat.py (every restriction shape on kas, kiro-cli, claude and codex, every spec candidate, the bundled default admitted). New: test_background_run_never_auto_approved.py, 31 tests, 29 of which fail with the fix reverted. It covers every covering spelling through the ceiling, build_agent_config, the rebuild's final pass and the conductor filter, the fail-closed fallback, the audit record, the derived KAS block on disk, the projection of a spec on disk that predates the fix, authored KAS allows (a deny still travels) and doctor's mint (idempotent). An earlier round ran BackgroundCommandService through the real sandbox-exec on macOS (a command writing another run's record was refused). The real sandbox was not re-run for this head: this host's shell already runs inside a sandbox, so sandbox-exec cannot nest.
  • No regression:
    • Tools still work (which tools/commands were run, result): the other @kirocrew-cron verbs stay auto-approved after narrowing (asserted per covering spelling); Security Scope Review's adjudication on 46fc84c211 classified 16 candidates on macOS and Ubuntu and 3 on Windows with 0 newly refused, and earlier heads matched; reading the leaf's logs (tail, cat, grep, ls) stays allowed.
    • Backward compatible (old config / old data / old callers still work, how checked): a spec on disk carrying @kirocrew-cron whole is narrowed on the next build and on every KAS projection, without doctor removing a user decision; the doctor and worker pins (test_cli_mcp_doctor.py, test_worker_agent.py) now assert the narrowed form. A new leaf only otherwise; an existing install just gains an empty precreated directory.
    • Existing tests (which suites passed on this head): on 46fc84c211, every Linux and Windows backend shard passed except the one migration test this head updates; locally on this head, the pin tests, the composition contracts, the new and updated tests (605 run; only the known macOS protected-name count differs) and the pre-push gate (20 checks, 0 failed). On 46fc84c211, locally, every test file that names _apply_allowed_tools_ceiling, _may_auto_approve, _ceiling_permitted, derived_agent_permissions or allowedTools (180 files), the composition contracts, the hooks contract, the facade guards, the agent-sdk boundary and the line budget, and the pre-push gate (20 checks, 0 failed); flake8, isort, black and mypy were clean on the changed files. Failures that are this host's own and that this change does not touch: the KAS engine-install tests (test_kas_bundle*, test_kas_route; they fail the same way with the fix reverted, because the sandbox cannot install the engine), test_cli_stt_memory_doctor.py (the host's kiro-cli sandbox setting), one test_pptx_maker_provision.py case (a Homebrew pdftoppm earlier on PATH), and the protected-name count, which reads one higher on macOS than in CI. About 42 tests in test_background_commands.py cannot run on this host because its sandbox blocks ps; CI runs them.
  • How to undo: revert this commit, or remove the background entries from sandbox_leaves.py, sandbox_precreate.py and security/paths_lists.py, and empty NEVER_AUTO_APPROVED.

@Yangxinyee

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: b833dd9
  • What rule changed: adds one crew-home leaf, background (the gateway's background command records, exit statuses and logs). It is READONLY in every sandbox mode and precreated (sandbox_leaves, sandbox_precreate), and write-protected for the file tools (paths_lists._WRITE_PROTECTED_HOME_PATHS). It also registers one new redaction sink (security_posture_sinks_delivery) and adds sandbox_tiers.path_within_tier_mask, which shares the tier-mask resolver _tier_mask_dirs with carveout_shadowed_by_foreign_mask (that resolution moved there unchanged; sandbox.py only forwards the two names). background_run is refused (403 background_run_shell_restricted) for any agent whose shell is restricted in any way or whose spec cannot be read (agent_sdk.agent_specs.spec_shell_restriction), and its spawn strips the gateway's Python interpreter variables (strip_python_env=True), as the agent's own shell does. Since 46fc84c211: @kirocrew-cron/background_run is never auto-approved, for any agent, on any route, as execute_bash is not (agent_sdk.drivers.acp.NEVER_AUTO_APPROVED). Every allowedTools writer (_may_auto_approve and _ceiling_split in auto_approve.py), doctor, the KAS projection (_ceiling_permitted) and authored KAS permissions withhold it, and a grant covering it (@kirocrew-cron, @kirocrew-cron/*, *) is narrowed to the cron server's other declared verbs.
  • Before -> after (what was allowed/blocked, now): this head is 0601ec417f rebased onto main for a conflict in agent-spec-fields.md (main's fix(kas): mount process control wherever a spec names execute_bash #34877 KAS process-control sentence kept beside ours), plus one test update: test_background_run_chat.py reads the KAS shell id as the first entry of KAS_TOOL_IDS_BY_KIRO_TOOL["execute_bash"], since fix(kas): mount process control wherever a spec names execute_bash #34877 added the deny-only process-control ids after it. No product code changed since 46fc84c211; kas_agents.py merged cleanly with fix(kas): mount process control wherever a spec names execute_bash #34877. before, an agent could write <data home>/background/; now it can read it, but neither a sandboxed shell nor a file tool can write it. An agent with a restricted shell is refused background_run before anything is registered. Before this head, a whole-server @kirocrew-cron grant (which kirocrew doctor mints on an ungoverned host) auto-approved background_run, so a command could start with no prompt. Now every background_run call prompts, and the other cron verbs keep the auto-approve they had. An allowedTools list that is only * now auto-approves just the cron server's other verbs: kiro-cli cannot express "every tool but one", so the narrowing errs toward a prompt. No deny tier, pattern or existing path disposition changed.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): if the seal failed, an agent could forge a record and aim the gateway's kill at another process, though every signal re-checks the recorded process start identity first. If the seal or the restriction check is too tight, background_run is refused and the agent keeps its own shell tool. If the narrowing is too wide, a cron verb that was auto-approved prompts instead; if the cron declaration cannot be read, the covering grant is dropped (fail closed) and per-verb grants beside it stand. No tool loses access; at worst it asks.
  • Evidence checked (which sandbox result proves it): unit tests test_sandbox_governance_mask.py (the leaf is sealed in every mode and edit-refused by the file gate), test_sandbox_protected_name_holds.py, the background command tests (including test_the_gateways_python_variables_never_reach_the_command, which runs the real env scrub) and test_background_run_chat.py (every restriction shape on kas, kiro-cli, claude and codex, every spec candidate, the bundled default admitted). New: test_background_run_never_auto_approved.py, 31 tests, 29 of which fail with the fix reverted. It covers every covering spelling through the ceiling, build_agent_config, the rebuild's final pass and the conductor filter, the fail-closed fallback, the audit record, the derived KAS block on disk, the projection of a spec on disk that predates the fix, authored KAS allows (a deny still travels) and doctor's mint (idempotent). An earlier round ran BackgroundCommandService through the real sandbox-exec on macOS (a command writing another run's record was refused). The real sandbox was not re-run for this head: this host's shell already runs inside a sandbox, so sandbox-exec cannot nest.
  • No regression:
    • Tools still work (which tools/commands were run, result): the other @kirocrew-cron verbs stay auto-approved after narrowing (asserted per covering spelling); Security Scope Review's adjudication on 46fc84c211 classified 16 candidates on macOS and Ubuntu and 3 on Windows with 0 newly refused, and earlier heads matched; reading the leaf's logs (tail, cat, grep, ls) stays allowed.
    • Backward compatible (old config / old data / old callers still work, how checked): a spec on disk carrying @kirocrew-cron whole is narrowed on the next build and on every KAS projection, without doctor removing a user decision; the doctor and worker pins (test_cli_mcp_doctor.py, test_worker_agent.py) now assert the narrowed form. A new leaf only otherwise; an existing install just gains an empty precreated directory.
    • Existing tests (which suites passed on this head): on 0601ec417f (the same product code), every backend shard on Linux, Windows and macOS passed; locally on this head, the KAS agent, permission and auto-approve suites, test_tool_names.py, test_background_run_chat.py, the new and updated tests, the composition contracts, the line budget and the pre-push gate (20 checks, 0 failed). On 46fc84c211, locally, every test file that names _apply_allowed_tools_ceiling, _may_auto_approve, _ceiling_permitted, derived_agent_permissions or allowedTools (180 files), the composition contracts, the hooks contract, the facade guards, the agent-sdk boundary and the line budget, and the pre-push gate (20 checks, 0 failed); flake8, isort, black and mypy were clean on the changed files. Failures that are this host's own and that this change does not touch: the KAS engine-install tests (test_kas_bundle*, test_kas_route; they fail the same way with the fix reverted, because the sandbox cannot install the engine), test_cli_stt_memory_doctor.py (the host's kiro-cli sandbox setting), one test_pptx_maker_provision.py case (a Homebrew pdftoppm earlier on PATH), and the protected-name count, which reads one higher on macOS than in CI. About 42 tests in test_background_commands.py cannot run on this host because its sandbox blocks ps; CI runs them.
  • How to undo: revert this commit, or remove the background entries from sandbox_leaves.py, sandbox_precreate.py and security/paths_lists.py, and empty NEVER_AUTO_APPROVED.

@Yangxinyee

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: a11e28a
  • What rule changed: adds one crew-home leaf, background (the gateway's background command records, exit statuses and logs). It is READONLY in every sandbox mode and precreated (sandbox_leaves, sandbox_precreate), and write-protected for the file tools (paths_lists._WRITE_PROTECTED_HOME_PATHS). It also registers one new redaction sink (security_posture_sinks_delivery) and adds sandbox_tiers.path_within_tier_mask, which shares the tier-mask resolver _tier_mask_dirs with carveout_shadowed_by_foreign_mask (that resolution moved there unchanged; sandbox.py only forwards the two names). background_run is refused (403 background_run_shell_restricted) for any agent whose shell is restricted in any way or whose spec cannot be read (agent_sdk.agent_specs.spec_shell_restriction), and its spawn strips the gateway's Python interpreter variables (strip_python_env=True), as the agent's own shell does. Since 46fc84c211: @kirocrew-cron/background_run is never auto-approved, for any agent, on any route, as execute_bash is not (agent_sdk.drivers.acp.NEVER_AUTO_APPROVED). Every allowedTools writer (_may_auto_approve and _ceiling_split in auto_approve.py), doctor, the KAS projection (_ceiling_permitted) and authored KAS permissions withhold it, and a grant covering it (@kirocrew-cron, @kirocrew-cron/*, *) is narrowed to the cron server's other declared verbs.
  • Before -> after (what was allowed/blocked, now): this head is b833dd9664 rebased onto main for a conflict in the package line budget: main's fix(security): point the self-protection-kill refusal span at the matched target #22646 raised it to 35,311 and this change's background leaf adds one, so the pin is 35,312 with both comments kept. No product code changed since 46fc84c211; main's chat-queue edits (queue_drain.py, chat_utils_injected_rows.py, chat_runner.py) merged cleanly beside ours. before, an agent could write <data home>/background/; now it can read it, but neither a sandboxed shell nor a file tool can write it. An agent with a restricted shell is refused background_run before anything is registered. Before this head, a whole-server @kirocrew-cron grant (which kirocrew doctor mints on an ungoverned host) auto-approved background_run, so a command could start with no prompt. Now every background_run call prompts, and the other cron verbs keep the auto-approve they had. An allowedTools list that is only * now auto-approves just the cron server's other verbs: kiro-cli cannot express "every tool but one", so the narrowing errs toward a prompt. No deny tier, pattern or existing path disposition changed.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): if the seal failed, an agent could forge a record and aim the gateway's kill at another process, though every signal re-checks the recorded process start identity first. If the seal or the restriction check is too tight, background_run is refused and the agent keeps its own shell tool. If the narrowing is too wide, a cron verb that was auto-approved prompts instead; if the cron declaration cannot be read, the covering grant is dropped (fail closed) and per-verb grants beside it stand. No tool loses access; at worst it asks.
  • Evidence checked (which sandbox result proves it): unit tests test_sandbox_governance_mask.py (the leaf is sealed in every mode and edit-refused by the file gate), test_sandbox_protected_name_holds.py, the background command tests (including test_the_gateways_python_variables_never_reach_the_command, which runs the real env scrub) and test_background_run_chat.py (every restriction shape on kas, kiro-cli, claude and codex, every spec candidate, the bundled default admitted). New: test_background_run_never_auto_approved.py, 31 tests, 29 of which fail with the fix reverted. It covers every covering spelling through the ceiling, build_agent_config, the rebuild's final pass and the conductor filter, the fail-closed fallback, the audit record, the derived KAS block on disk, the projection of a spec on disk that predates the fix, authored KAS allows (a deny still travels) and doctor's mint (idempotent). An earlier round ran BackgroundCommandService through the real sandbox-exec on macOS (a command writing another run's record was refused). The real sandbox was not re-run for this head: this host's shell already runs inside a sandbox, so sandbox-exec cannot nest.
  • No regression:
    • Tools still work (which tools/commands were run, result): the other @kirocrew-cron verbs stay auto-approved after narrowing (asserted per covering spelling); Security Scope Review's adjudication on 46fc84c211 classified 16 candidates on macOS and Ubuntu and 3 on Windows with 0 newly refused, and earlier heads matched; reading the leaf's logs (tail, cat, grep, ls) stays allowed.
    • Backward compatible (old config / old data / old callers still work, how checked): a spec on disk carrying @kirocrew-cron whole is narrowed on the next build and on every KAS projection, without doctor removing a user decision; the doctor and worker pins (test_cli_mcp_doctor.py, test_worker_agent.py) now assert the narrowed form. A new leaf only otherwise; an existing install just gains an empty precreated directory.
    • Existing tests (which suites passed on this head): on 0601ec417f (the same product code), every backend shard on Linux, Windows and macOS passed, and on b833dd9664 every AI review lane and Security Scope Review passed; locally on this head, test_background_run_chat.py, the chat-runner, dashboard, hooks and facade composition contracts and every test naming the chat queue drain or injected rows (1,468 passed), the line budget, the MCP table, the protected-name count (one higher on macOS than in CI, as before), the KAS agent suite and the pre-push gate (20 checks, 0 failed). On 46fc84c211, locally, every test file that names _apply_allowed_tools_ceiling, _may_auto_approve, _ceiling_permitted, derived_agent_permissions or allowedTools (180 files), the composition contracts, the hooks contract, the facade guards, the agent-sdk boundary and the line budget, and the pre-push gate (20 checks, 0 failed); flake8, isort, black and mypy were clean on the changed files. Failures that are this host's own and that this change does not touch: the KAS engine-install tests (test_kas_bundle*, test_kas_route; they fail the same way with the fix reverted, because the sandbox cannot install the engine), test_cli_stt_memory_doctor.py (the host's kiro-cli sandbox setting), one test_pptx_maker_provision.py case (a Homebrew pdftoppm earlier on PATH), and the protected-name count, which reads one higher on macOS than in CI. About 42 tests in test_background_commands.py cannot run on this host because its sandbox blocks ps; CI runs them.
  • How to undo: revert this commit, or remove the background entries from sandbox_leaves.py, sandbox_precreate.py and security/paths_lists.py, and empty NEVER_AUTO_APPROVED.

@Yangxinyee

Copy link
Copy Markdown
Contributor Author
  • span=dddfa1b5544d the kiro-cli skill view of a non-crew-bound user agent still auto-approved background_run through a covering allowedTools grant or an owner-written autoApprove verb

fixed in 3b55894: the rule moved out of the individual writers into the shared gate-skip predicate. platform.governance.may_skip_gate now refuses, with or without a ceiling, every ref that agent_sdk.mcp_refs.reaches_never_auto_approved matches (the exact ref, @kirocrew-cron, @kirocrew-cron/*, *, a case-folded server, the bare verb). So every route that consults the predicate withholds it whether or not it knows the feature, including grant_in_skill_view, strip_ungoverned_auto_approve (now judged per verb through _past_never_auto_approved), with_default_crew_servers, the app bridges and the MCP agent sync. The kiro-cli skill view also narrows, for every view whether crew-bound or not (kas_auto_approve.narrow_skill_view in prepare_native_skill_projection), so the other cron verbs keep their auto-approve there. Doctor judges a covered server by one of its other verbs, so the predicate's refusal is not read as a ceiling that revokes every cron grant.
Tests: test_background_run_never_auto_approved.py adds the predicate over every covering spelling, the native skill view (covering allowedTools and an owner-written autoApprove: ["background_run"]), the whole-config filter and the gate's grant row; with the product change reverted they fail, 18 there and 5 in test_default_crew_servers.py. Sweep: every may_skip_gate* caller is listed in the sweep file as fixed, covered by a named test, or out of class.

resolution: narrowed -- background_run is refused by the shared gate-skip predicate every grant writer and projection consults, instead of by each writer
mechanism: platform.governance.may_skip_gate refuses refs reaching mcp_refs.NEVER_AUTO_APPROVED; the spec writers, doctor, KAS and the kiro-cli skill view also narrow covering grants
self-added: no

@Yangxinyee

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 3b55894
  • What rule changed: adds one crew-home leaf, background (the gateway's background command records, exit statuses and logs). It is READONLY in every sandbox mode and precreated (sandbox_leaves, sandbox_precreate), and write-protected for the file tools (paths_lists._WRITE_PROTECTED_HOME_PATHS). It also registers one new redaction sink (security_posture_sinks_delivery) and adds sandbox_tiers.path_within_tier_mask, which shares the tier-mask resolver _tier_mask_dirs with carveout_shadowed_by_foreign_mask (that resolution moved there unchanged; sandbox.py only forwards the two names). background_run is refused (403 background_run_shell_restricted) for any agent whose shell is restricted in any way or whose spec cannot be read (agent_sdk.agent_specs.spec_shell_restriction), and its spawn strips the gateway's Python interpreter variables (strip_python_env=True), as the agent's own shell does. Since 46fc84c211: @kirocrew-cron/background_run is never auto-approved, for any agent, on any route, as execute_bash is not (agent_sdk.drivers.acp.NEVER_AUTO_APPROVED). The rule lives in the shared gate-skip predicate, platform.governance.may_skip_gate, which refuses every ref reaching agent_sdk.mcp_refs.NEVER_AUTO_APPROVED with or without a ceiling, so every grant writer and projection that consults it withholds background_run (spec writers, mcpServers[].autoApprove, the kiro-cli skill view, KAS, app bridges, MCP agent sync, the default crew servers). The spec writers (_ceiling_split), doctor, KAS (_ceiling_permitted) and the kiro-cli skill view (narrow_skill_view) also narrow a covering grant (@kirocrew-cron, @kirocrew-cron/*, *) to the cron server's other declared verbs.
  • Before -> after (what was allowed/blocked, now): this head answers Opus's span dddfa1b5544d on a11e28a5fb. On the kiro-cli backend, a non-crew-bound user agent's skill view still auto-approved background_run through a covering allowedTools grant or an owner-written autoApprove verb, because that route consulted only the shared predicate. The predicate now refuses it, and the view narrows. A route that consults only the predicate and does not narrow now drops a covering grant whole (fail closed), so those cron verbs prompt there (test_default_crew_servers.py, the mate worker merge). It is also rebased onto main for a conflict in sandbox.py (main's feat(sandbox): operator read-only paths with write exceptions #28535 read-only layer names kept beside ours). before, an agent could write <data home>/background/; now it can read it, but neither a sandboxed shell nor a file tool can write it. An agent with a restricted shell is refused background_run before anything is registered. Before this head, a whole-server @kirocrew-cron grant (which kirocrew doctor mints on an ungoverned host) auto-approved background_run, so a command could start with no prompt. Now every background_run call prompts, and the other cron verbs keep the auto-approve they had. An allowedTools list that is only * now auto-approves just the cron server's other verbs: kiro-cli cannot express "every tool but one", so the narrowing errs toward a prompt. No deny tier, pattern or existing path disposition changed.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): if the seal failed, an agent could forge a record and aim the gateway's kill at another process, though every signal re-checks the recorded process start identity first. If the seal or the restriction check is too tight, background_run is refused and the agent keeps its own shell tool. If the narrowing is too wide, a cron verb that was auto-approved prompts instead; if the cron declaration cannot be read, the covering grant is dropped (fail closed) and per-verb grants beside it stand. No tool loses access; at worst it asks.
  • Evidence checked (which sandbox result proves it): unit tests test_sandbox_governance_mask.py (the leaf is sealed in every mode and edit-refused by the file gate), test_sandbox_protected_name_holds.py, the background command tests (including test_the_gateways_python_variables_never_reach_the_command, which runs the real env scrub) and test_background_run_chat.py (every restriction shape on kas, kiro-cli, claude and codex, every spec candidate, the bundled default admitted). New: test_background_run_never_auto_approved.py, 31 tests, 29 of which fail with the fix reverted. It covers every covering spelling through the ceiling, build_agent_config, the rebuild's final pass and the conductor filter, the fail-closed fallback, the audit record, the derived KAS block on disk, the projection of a spec on disk that predates the fix, authored KAS allows (a deny still travels) and doctor's mint (idempotent). An earlier round ran BackgroundCommandService through the real sandbox-exec on macOS (a command writing another run's record was refused). The real sandbox was not re-run for this head: this host's shell already runs inside a sandbox, so sandbox-exec cannot nest.
  • No regression:
    • Tools still work (which tools/commands were run, result): the other @kirocrew-cron verbs stay auto-approved after narrowing (asserted per covering spelling); Security Scope Review's adjudication on 46fc84c211 classified 16 candidates on macOS and Ubuntu and 3 on Windows with 0 newly refused, and earlier heads matched; reading the leaf's logs (tail, cat, grep, ls) stays allowed.
    • Backward compatible (old config / old data / old callers still work, how checked): a spec on disk carrying @kirocrew-cron whole is narrowed on the next build and on every KAS projection, without doctor removing a user decision; the doctor and worker pins (test_cli_mcp_doctor.py, test_worker_agent.py) now assert the narrowed form. A new leaf only otherwise; an existing install just gains an empty precreated directory.
    • Existing tests (which suites passed on this head): locally on this head, every test file naming may_skip_gate, grant_in_skill_view, prepare_native_skill_projection, strip_ungoverned_auto_approve, _ceiling_permitted, allowedTools, autoApprove or derived_agent_permissions (249 files, about 12,800 passed), the composition contracts, the agent-sdk boundary, the facade guards, the line budget, the MCP table, the sweep check (2 entries, no findings) and the pre-push gate (20 checks, 0 failed); flake8, isort, black and mypy were clean. Two existing pins now assert the narrowed form (test_mate_worker_kit.py with *, test_mate_worker_disabled_servers.py). Host-only failures that fail the same way with the fix reverted: test_builtin_adoption_gate.py and test_builtin_adoption_mcp.py (one each), test_acp_runtime_failed_start_reap.py (2, the host sandbox), test_cli_stt_memory_doctor.py, one test_pptx_maker_provision.py case, and the protected-name count, which reads one higher on macOS than in CI. About 42 tests in test_background_commands.py cannot run on this host because its sandbox blocks ps; CI runs them.
  • How to undo: revert this commit, or remove the background entries from sandbox_leaves.py, sandbox_precreate.py and security/paths_lists.py, and empty NEVER_AUTO_APPROVED.

@Yangxinyee

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 9c984a5
  • What rule changed: adds one crew-home leaf, background (the gateway's background command records, exit statuses and logs). It is READONLY in every sandbox mode and precreated (sandbox_leaves, sandbox_precreate), and write-protected for the file tools (paths_lists._WRITE_PROTECTED_HOME_PATHS). It also registers one new redaction sink (security_posture_sinks_delivery) and adds sandbox_tiers.path_within_tier_mask, which shares the tier-mask resolver _tier_mask_dirs with carveout_shadowed_by_foreign_mask (that resolution moved there unchanged; sandbox.py only forwards the two names). background_run is refused (403 background_run_shell_restricted) for any agent whose shell is restricted in any way or whose spec cannot be read (agent_sdk.agent_specs.spec_shell_restriction), and its spawn strips the gateway's Python interpreter variables (strip_python_env=True), as the agent's own shell does. Since 46fc84c211: @kirocrew-cron/background_run is never auto-approved, for any agent, on any route, as execute_bash is not (agent_sdk.drivers.acp.NEVER_AUTO_APPROVED). The rule lives in the shared gate-skip predicate, platform.governance.may_skip_gate, which refuses every ref reaching agent_sdk.mcp_refs.NEVER_AUTO_APPROVED with or without a ceiling, so every grant writer and projection that consults it withholds background_run (spec writers, mcpServers[].autoApprove, the kiro-cli skill view, KAS, app bridges, MCP agent sync, the default crew servers). The spec writers (_ceiling_split), doctor, KAS (_ceiling_permitted) and the kiro-cli skill view (narrow_skill_view) also narrow a covering grant (@kirocrew-cron, @kirocrew-cron/*, *) to the cron server's other declared verbs.
  • Before -> after (what was allowed/blocked, now): this head is 3b55894ca6 rebased onto main for a conflict in the package line budget: main's fix: tighten a self-protection check on shell scripts #32885 raised it to 35,373 and this change's background leaf adds one, so the pin is 35,374 with both comments kept. No product code changed since 3b55894ca6, on which every review lane passed (GPT 6.1, Opus 5.5, Design, UX, First Principles, Security Scope Review). That head answered Opus's span dddfa1b5544d: the never-auto-approve rule lives in the shared gate-skip predicate, and the kiro-cli skill view narrows; a route that only consults the predicate drops a covering grant whole (fail closed).
  • Worst case if wrong (breaks commands / leaks secret / locks user out): if the seal failed, an agent could forge a record and aim the gateway's kill at another process, though every signal re-checks the recorded process start identity first. If the seal or the restriction check is too tight, background_run is refused and the agent keeps its own shell tool. If the narrowing is too wide, a cron verb that was auto-approved prompts instead; if the cron declaration cannot be read, the covering grant is dropped (fail closed) and per-verb grants beside it stand. No tool loses access; at worst it asks.
  • Evidence checked (which sandbox result proves it): unit tests test_sandbox_governance_mask.py (the leaf is sealed in every mode and edit-refused by the file gate), test_sandbox_protected_name_holds.py, the background command tests (including test_the_gateways_python_variables_never_reach_the_command, which runs the real env scrub) and test_background_run_chat.py (every restriction shape on kas, kiro-cli, claude and codex, every spec candidate, the bundled default admitted). New: test_background_run_never_auto_approved.py, 31 tests, 29 of which fail with the fix reverted. It covers every covering spelling through the ceiling, build_agent_config, the rebuild's final pass and the conductor filter, the fail-closed fallback, the audit record, the derived KAS block on disk, the projection of a spec on disk that predates the fix, authored KAS allows (a deny still travels) and doctor's mint (idempotent). An earlier round ran BackgroundCommandService through the real sandbox-exec on macOS (a command writing another run's record was refused). The real sandbox was not re-run for this head: this host's shell already runs inside a sandbox, so sandbox-exec cannot nest.
  • No regression:
    • Tools still work (which tools/commands were run, result): the other @kirocrew-cron verbs stay auto-approved after narrowing (asserted per covering spelling); Security Scope Review's adjudication on 46fc84c211 classified 16 candidates on macOS and Ubuntu and 3 on Windows with 0 newly refused, and earlier heads matched; reading the leaf's logs (tail, cat, grep, ls) stays allowed.
    • Backward compatible (old config / old data / old callers still work, how checked): a spec on disk carrying @kirocrew-cron whole is narrowed on the next build and on every KAS projection, without doctor removing a user decision; the doctor and worker pins (test_cli_mcp_doctor.py, test_worker_agent.py) now assert the narrowed form. A new leaf only otherwise; an existing install just gains an empty precreated directory.
    • Existing tests (which suites passed on this head): locally on this head, the composition contracts, the line budget, the MCP table, test_background_run_never_auto_approved.py, test_background_run_chat.py and the pre-push gate (20 checks, 0 failed); on 3b55894ca6 (same product code), locally, every test file naming may_skip_gate, grant_in_skill_view, prepare_native_skill_projection, strip_ungoverned_auto_approve, _ceiling_permitted, allowedTools, autoApprove or derived_agent_permissions (249 files, about 12,800 passed), the composition contracts, the agent-sdk boundary, the facade guards, the line budget, the MCP table, the sweep check (2 entries, no findings) and the pre-push gate (20 checks, 0 failed); flake8, isort, black and mypy were clean. Two existing pins now assert the narrowed form (test_mate_worker_kit.py with *, test_mate_worker_disabled_servers.py). Host-only failures that fail the same way with the fix reverted: test_builtin_adoption_gate.py and test_builtin_adoption_mcp.py (one each), test_acp_runtime_failed_start_reap.py (2, the host sandbox), test_cli_stt_memory_doctor.py, one test_pptx_maker_provision.py case, and the protected-name count, which reads one higher on macOS than in CI. About 42 tests in test_background_commands.py cannot run on this host because its sandbox blocks ps; CI runs them.
  • How to undo: revert this commit, or remove the background entries from sandbox_leaves.py, sandbox_precreate.py and security/paths_lists.py, and empty NEVER_AUTO_APPROVED.

@Yangxinyee

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: a1fe31b
  • What rule changed: adds one crew-home leaf, background (the gateway's background command records, exit statuses and logs). It is READONLY in every sandbox mode and precreated (sandbox_leaves, sandbox_precreate), and write-protected for the file tools (paths_lists._WRITE_PROTECTED_HOME_PATHS). It also registers one new redaction sink (security_posture_sinks_delivery) and adds sandbox_tiers.path_within_tier_mask, which shares the tier-mask resolver _tier_mask_dirs with carveout_shadowed_by_foreign_mask (that resolution moved there unchanged; sandbox.py only forwards the two names). background_run is refused (403 background_run_shell_restricted) for any agent whose shell is restricted in any way or whose spec cannot be read (agent_sdk.agent_specs.spec_shell_restriction), and its spawn strips the gateway's Python interpreter variables (strip_python_env=True), as the agent's own shell does. Since 46fc84c211: @kirocrew-cron/background_run is never auto-approved, for any agent, on any route, as execute_bash is not (agent_sdk.drivers.acp.NEVER_AUTO_APPROVED). The rule lives in the shared gate-skip predicate, platform.governance.may_skip_gate, which refuses every ref reaching agent_sdk.mcp_refs.NEVER_AUTO_APPROVED with or without a ceiling, so every grant writer and projection that consults it withholds background_run (spec writers, mcpServers[].autoApprove, the kiro-cli skill view, KAS, app bridges, MCP agent sync, the default crew servers). The spec writers (_ceiling_split), doctor, KAS (_ceiling_permitted) and the kiro-cli skill view (narrow_skill_view) also narrow a covering grant (@kirocrew-cron, @kirocrew-cron/*, *) to the cron server's other declared verbs.
  • Before -> after (what was allowed/blocked, now): this head is 9c984a5162 rebased onto main for a conflict in agent-spec-fields.md (main's feat: carry a claude crewmate worker's native-tool excludes #34475 excludedTools sentence on a claude Bot worker's native-tool excludes kept beside our allowedTools clause). No product code changed since 3b55894ca6. On 9c984a5162, every review lane passed (GPT 6.1, Opus 5.5, Design, UX, First Principles, Security Scope Review), and so did every Linux, Windows and macOS backend shard but macOS 5, which hit its 40-minute job limit while still running (65%, no failure).
  • Worst case if wrong (breaks commands / leaks secret / locks user out): if the seal failed, an agent could forge a record and aim the gateway's kill at another process, though every signal re-checks the recorded process start identity first. If the seal or the restriction check is too tight, background_run is refused and the agent keeps its own shell tool. If the narrowing is too wide, a cron verb that was auto-approved prompts instead; if the cron declaration cannot be read, the covering grant is dropped (fail closed) and per-verb grants beside it stand. No tool loses access; at worst it asks.
  • Evidence checked (which sandbox result proves it): unit tests test_sandbox_governance_mask.py (the leaf is sealed in every mode and edit-refused by the file gate), test_sandbox_protected_name_holds.py, the background command tests (including test_the_gateways_python_variables_never_reach_the_command, which runs the real env scrub) and test_background_run_chat.py (every restriction shape on kas, kiro-cli, claude and codex, every spec candidate, the bundled default admitted). New: test_background_run_never_auto_approved.py, 31 tests, 29 of which fail with the fix reverted. It covers every covering spelling through the ceiling, build_agent_config, the rebuild's final pass and the conductor filter, the fail-closed fallback, the audit record, the derived KAS block on disk, the projection of a spec on disk that predates the fix, authored KAS allows (a deny still travels) and doctor's mint (idempotent). An earlier round ran BackgroundCommandService through the real sandbox-exec on macOS (a command writing another run's record was refused). The real sandbox was not re-run for this head: this host's shell already runs inside a sandbox, so sandbox-exec cannot nest.
  • No regression:
    • Tools still work (which tools/commands were run, result): the other @kirocrew-cron verbs stay auto-approved after narrowing (asserted per covering spelling); Security Scope Review's adjudication on 46fc84c211 classified 16 candidates on macOS and Ubuntu and 3 on Windows with 0 newly refused, and earlier heads matched; reading the leaf's logs (tail, cat, grep, ls) stays allowed.
    • Backward compatible (old config / old data / old callers still work, how checked): a spec on disk carrying @kirocrew-cron whole is narrowed on the next build and on every KAS projection, without doctor removing a user decision; the doctor and worker pins (test_cli_mcp_doctor.py, test_worker_agent.py) now assert the narrowed form. A new leaf only otherwise; an existing install just gains an empty precreated directory.
    • Existing tests (which suites passed on this head): locally on this head, the composition contracts, the line budget, the MCP table, the never-auto-approve, background_run chat, default crew servers, mate worker, KAS agent, doctor, worker and claude worker tool suites (1,076 passed; only the known macOS protected-name count differs) and the pre-push gate (20 checks, 0 failed); on 3b55894ca6 (same product code), locally, every test file naming may_skip_gate, grant_in_skill_view, prepare_native_skill_projection, strip_ungoverned_auto_approve, _ceiling_permitted, allowedTools, autoApprove or derived_agent_permissions (249 files, about 12,800 passed), the composition contracts, the agent-sdk boundary, the facade guards, the line budget, the MCP table, the sweep check (2 entries, no findings) and the pre-push gate (20 checks, 0 failed); flake8, isort, black and mypy were clean. Two existing pins now assert the narrowed form (test_mate_worker_kit.py with *, test_mate_worker_disabled_servers.py). Host-only failures that fail the same way with the fix reverted: test_builtin_adoption_gate.py and test_builtin_adoption_mcp.py (one each), test_acp_runtime_failed_start_reap.py (2, the host sandbox), test_cli_stt_memory_doctor.py, one test_pptx_maker_provision.py case, and the protected-name count, which reads one higher on macOS than in CI. About 42 tests in test_background_commands.py cannot run on this host because its sandbox blocks ps; CI runs them.
  • How to undo: revert this commit, or remove the background entries from sandbox_leaves.py, sandbox_precreate.py and security/paths_lists.py, and empty NEVER_AUTO_APPROVED.

@iamwhatever

Copy link
Copy Markdown
Contributor

Stale-PR cleanup check: held for a maintainer. The linked issue #12681 carries needs-human, so background_run needs a maintainer decision before this can move. The branch also conflicts with main.

An agent waiting on CI, a build or a training run had only a blind
sleep, an in-turn wait capped at 30 minutes, or a turn-per-interval
loop. background_run starts the command in the gateway at the agent
shell's sandbox tier, lets the turn end, and wakes the chat with the
exit code and output tail through workflow completion injection.

The command is a host run on the workflow substrate (driver
"command"), so workflow_status and workflow_cancel read and stop it.
Output goes to a file and a wrapper records the exit status, so a
gateway restart re-adopts a live command by its pid start identity,
settles one that exited meanwhile, and reports the rest interrupted.

The tool lives on kirocrew-cron, which is granted tool by tool, so
kiro-cli asks before it runs; the gateway then judges the command
with the same shell gate as execute_bash.

Closes #12681

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add an event-driven wait primitive so agents block on completion instead of sleep

4 participants