Skip to content

fix(subagent): split run_turn.py under the line cap and fix its prompt-hook test - #25950

Merged
buluoray merged 1 commit into
mainfrom
fix/run-turn-line-cap
Oct 30, 2026
Merged

buluoray merged 1 commit into
mainfrom
fix/run-turn-line-cap

Conversation

@buluoray

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Turn main's lint and test jobs green again by bringing src/kiro_crew/subagent_manager/run_turn.py back under the 2,000-line cap and fixing the sub-agent prompt-hook test that the Stop-hook change broke.

Two changes merged on 2026-10-29 left main red:

Why it matters

Every PR that touches run_turn.py fails the line-cap gate, and every PR whose run includes the sub-agent tests sees one inherited red test. Contributors cannot tell their own failures from main's.

Not a goal

  • No change to what a sub-agent run does: the moved code keeps its own statements, order and comments.
  • No split of the stream loop or its nested closures (_stream_with_transient_retry, _fire_stop_hooks, _persist_usage_row). Those close over the turn's locals and stay in _run_inner_impl.
  • No change to the RunEventCoordinator member set or the facade surface.

What changed (motivation → approach → change)

Commit 1, test(subagent): count only prompt hooks in the first-prompt watchdog test:
the test helper _run_child calls its on_fire callback only for AgentSpawn and UserPromptSubmit (a module constant _PROMPT_EVENTS), the two events fired before the prompt. The assertion is unchanged: during each of the two prompt-hook fires the run reads as running its hooks, is not first-prompt silent, and is not a stalled start. With the flag that marks hooks as running removed from production code, the test still fails.

Commit 2, refactor(subagent): split run_turn.py under the line cap:
_run_inner_impl is one long function. The parts before the prompt that close over none of its locals and hand back a value moved, as whole blocks, into a new sibling module src/kiro_crew/subagent_manager/turn_session.py:

  • resolve_parent_policy: the approval policy the child's tool calls inherit, with its audited fallbacks.
  • acquire_session: the shared-runtime arm and the dedicated-process arm, returning (client, is_new, resumed, is_cc, use_session_sharing).
  • capture_cleanup_identity: the cleanup identity captured right after acquisition.
  • prepare_child_context: the child's memory store, crew activity and folder steering; returns the project.
  • persist_spawn_records: model provenance, the identity sidecar, subagent_spawn, the PID record and the session record, in the same order.
  • fire_prompt_hooks: the AgentSpawn/UserPromptSubmit firing with its running flag and clock bookkeeping.

_run_inner_impl runs on kiro_crew.subagent's globals (bind_component_globals), and tests patch names there (sel, time, _redact, the session re-projection helpers). The moved functions read those names through _facade(), a call-time sys.modules["kiro_crew.subagent"] lookup (the pattern src/kiro_crew/snapshot_components.py uses), so every existing patch still reaches them. _run_inner_impl imports the module locally, as it already does for prompt_hooks.

The module is named turn_session.py, not run_*: test/test_run_bindings.py requires every run_*.py sibling to be an owner that RunEventCoordinator binds members from, and these are plain functions. The lines that structural tests read in run_turn.py stay there: publish_execution, extra_kwargs["shared_scratch"], the on_tool_call gate consult, the MCP notice seam, the one usage-row persist, and the permission ladder's settle and bail calls.

run_turn.py goes from 2,030 to 1,598 lines; turn_session.py is 561. The run_turn.py docstring's manager-field list now names only the fields it still reads, and turn_session.py lists its own. docs/system-specs/modules/subagent.md (Session Lifecycle) and docs/system-specs/modules/acp-client.md (the congestion rule) name the new file.

Backwards compatibility

Compatible: the moved code runs the same statements in the same order and reads the same patched names through the facade, and the import path kiro_crew.subagent_manager.run_turn and RunEventCoordinator._run_inner_impl are unchanged.

Removes nothing: no function, key, record or caller-visible name is removed; code moved from one private module to a new private sibling.

Tests

  • test/test_subagent_prompt_hooks.py: the watchdog test and the cancelled-hook test now drive on_fire only for the two prompt-hook events; 7 passed.
  • Mutation check: deleting info._prompt_hooks_running = True from turn_session.fire_prompt_hooks makes test_hook_time_is_not_charged_to_the_first_prompt_watchdog fail (1 failed); restored afterwards.
  • TMPDIR=/tmp python -m pytest -n auto --dist loadgroup over test/test_subagent_*.py plus test_run_bindings.py, test_eval_subagent_deny_notice.py, test_execution_context.py, test_hooks.py, test_turn_duration_recorded.py, test_app_spawn_capability.py, test_session_start_gate.py, test_identity_topology.py, test_member_essential_context.py, test_facade_mirror_guards.py, test_subagent_parts_composition_contract.py, test_session_sharing.py, test_continuable_followups.py, test_adaptive_startup_memory.py: 3489 passed, 2 skipped, 5 xfailed.

Proof: not provable -- other: the fix is a test-only change plus a behaviour-preserving refactor, so there is no production hunk to revert

Manual verification

N/A — unit coverage sufficient: no runtime behaviour changes, and the gates below were run locally on the touched files.

  • python3 scripts/check_file_line_cap.py: 0 failures, 0 main-drift warnings (main showed the run_turn.py 2,030-line drift warning).
  • python3 scripts/check_black_formatting.py with black 26.10.1: passed. black --target-version py310 --check, isort --check-only and flake8 on the three touched Python files: clean.
  • mypy --platform linux src/kiro_crew/subagent_manager: no issues in 33 source files.
  • Comment-history and brand gates against origin/main: passed.

Related Issues

Follows #25127 and #25122, which together left main over the line cap with one failing test.

Sibling sweep

Swept: grep -rln "hook_store.fire = AsyncMock" test/
Sibling: test/test_subagent_run_loop.py -- not affected -- its fakes return nothing or raise for every event, run no per-fire callback, and the file passes on this head
Sibling: test/test_subagent_stop_hook.py -- not affected -- its fake answers by event name, and the whole file passes on this head

Pattern harvest

Not generalizable: the test's callback assumed it saw only prompt-hook fires, a property of this one helper rather than a repeated shape.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.

@buluoray
buluoray requested review from a team and KiroCrewCaptain as code owners October 29, 2026 20:53
@buluoray
buluoray requested a review from dodgeblaster October 29, 2026 20:53
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 29, 2026
@github-actions

github-actions Bot commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 1397b8a7fb2cd82f3753d5152209316b8788ee3c 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 29, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks: the split moves whole blocks before the prompt with no early returns, and patched names still resolve through the call-time facade.

Notes

  • The title ("fix its prompt-hook test") and "Commit 1" describe a test change that isn't in this diff. The event filter on on_fire is already on main at test/test_subagent_prompt_hooks.py:61. The description claims something the diff doesn't do; reword it so the PR reads as a refactor only.

[DESIGN-REVIEWED] 1397b8a

Description read

[DESCRIPTION-READ] ff01e83a5cbdc3cb402ce88b94df9583eaa7001c98c4154bd8c8d8a04daa3558

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

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

First-Principles-Verdict: PASS

This is a behaviour-preserving split, required by the 2,000-line cap. The only gap: the title and description claim a test fix that is not in this diff.

Notes

  • Item 5 — undeclared: the title says "and fix its prompt-hook test", and the description lists "Commit 1, test(subagent): count only prompt hooks…". The diff does not touch test/. The base already filters on_fire to ("AgentSpawn", "UserPromptSubmit") (test/test_subagent_prompt_hooks.py:61), so that fix landed elsewhere. Subtraction: delete "and fix its prompt-hook test" from the title and the Commit 1 paragraph from ## What changed. The frozen Goal itself stays as it is.

What this change ships

Inventory (5 items) — 4 justified

Intent: get main's line-cap gate green again by splitting run_turn.py, which is over the cap. This is a FIX, made by a refactor.

  1. run_turn.py goes from 2,030 to 1,598 lines. The pre-stream steps move out as whole blocks — justified
  2. New private module turn_session.py, using the existing _facade() call-time lookup pattern from snapshot_components.py:480 — justified
  3. turn_session.py added to NON_EGRESS_REDACTION_MODULES — justified
  4. subagent.md and acp-client.md updated to name the new file — justified
  5. Title and description claim a prompt-hook test fix that the diff does not contain — undeclared mismatch

[FIRST-PRINCIPLES-REVIEWED] 1397b8a

Description read

[DESCRIPTION-READ] 122dafc50720979bdbf4fa09fa3bfa85294b39268debd6541d4bab17d664fa35

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

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 1397b8a

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

@github-actions

github-actions Bot commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 1397b8a

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

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

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 29, 2026
@github-actions

github-actions Bot commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

Sensitive Change Review

Sensitive files changed:

  • src/kiro_crew/security_posture.py

  • @buluoray posted a complete reasoning template for 1397b8a.

@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 29, 2026
@buluoray

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: dddd832
  • What rule changed: none. One entry, subagent_manager/turn_session.py, is added to NON_EGRESS_REDACTION_MODULES in src/kiro_crew/security_posture.py, under the existing reason comment for the internal subagent_manager run partitions.
  • Before -> after (what was allowed/blocked, now): before, the census test failed because the run_turn.py split moved the subagent_spawn frame redaction (_redact(info.task), _redact(info.label), _redact(info.requested_model)) into a module the census did not classify. After, that module is classified the same way as run_turn.py, where the code came from. No redaction call, sink, or posture row changes, and run_turn.py keeps its entry because it still calls _redact.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): the posture panel would count a module as an internal partition when it is really an egress boundary. That cannot happen here: turn_session.py adds no transport or audience. It hands the already-redacted frame to the same facade callback as before.
  • Evidence checked (which sandbox result proves it): test_every_redactor_call_site_is_a_registered_sink_or_allowlisted passes on this head. With the entry reverted it fails with assert not [subagent_manager/turn_session.py], which matches the Static Ratchet Gate failure on aff2247.
  • No regression:
    • Tools still work (which tools/commands were run, result): scripts/check_file_line_cap.py reports 0 failures. black --check and flake8 are clean on the touched files.
    • Backward compatible (old config / old data / old callers still work, how checked): this adds one allowlist entry and changes no data, config, or caller.
    • Existing tests (which suites passed on this head): test_security_posture.py, test_security_posture_facade.py, test_run_bindings.py, test_subagent_prompt_hooks.py, and the run_turn subagent suites (delivery_ttl_anchor, provenance_write, scratch_cwd_project, shared_scratch, skill_trigger_text): 423 passed.
  • How to undo: revert dddd832.

@buluoray
buluoray force-pushed the fix/run-turn-line-cap branch from dddd832 to e845ffd Compare October 29, 2026 21:30
@buluoray

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: e845ffd
  • What rule changed: none. One entry, subagent_manager/turn_session.py, is added to NON_EGRESS_REDACTION_MODULES in src/kiro_crew/security_posture.py, under the existing reason comment for the internal subagent_manager run partitions. This head has the same tree as dddd832. The fix was folded into the split commit to keep the PR at 2 commits for PR Hygiene.
  • Before -> after (what was allowed/blocked, now): before, the census test failed because the run_turn.py split moved the subagent_spawn frame redaction (_redact(info.task), _redact(info.label), _redact(info.requested_model)) into a module the census did not classify. After, that module is classified the same way as run_turn.py, where the code came from. No redaction call, sink, or posture row changes, and run_turn.py keeps its entry because it still calls _redact.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): the posture panel would count a module as an internal partition when it is really an egress boundary. That cannot happen here: turn_session.py adds no transport or audience. It hands the already-redacted frame to the same facade callback as before.
  • Evidence checked (which sandbox result proves it): test_every_redactor_call_site_is_a_registered_sink_or_allowlisted passes on this tree. With the entry reverted it fails with assert not [subagent_manager/turn_session.py], which matches the Static Ratchet Gate failure on aff2247.
  • No regression:
    • Tools still work (which tools/commands were run, result): scripts/check_file_line_cap.py reports 0 failures. black --check and flake8 are clean on the touched files.
    • Backward compatible (old config / old data / old callers still work, how checked): this adds one allowlist entry and changes no data, config, or caller.
    • Existing tests (which suites passed on this head): test_security_posture.py, test_security_posture_facade.py, test_run_bindings.py, test_subagent_prompt_hooks.py, and the run_turn subagent suites (delivery_ttl_anchor, provenance_write, scratch_cwd_project, shared_scratch, skill_trigger_text): 423 passed.
  • How to undo: drop the subagent_manager/turn_session.py line from NON_EGRESS_REDACTION_MODULES.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 29, 2026
@buluoray
buluoray force-pushed the fix/run-turn-line-cap branch from e845ffd to ecc1331 Compare October 29, 2026 22:19
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 29, 2026
@buluoray

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: ecc1331
  • What rule changed: none. One entry, subagent_manager/turn_session.py, is added to NON_EGRESS_REDACTION_MODULES in src/kiro_crew/security_posture.py, under the existing reason comment for the internal subagent_manager run partitions. This head is e845ffd rebased onto main after fix: turn main green after three concurrent merges (#25937) #25947 merged; the duplicate test_subagent_prompt_hooks.py commit was dropped (main already carries that fix). security_posture.py is unchanged from e845ffd.
  • Before -> after (what was allowed/blocked, now): before, the census test failed because the run_turn.py split moved the subagent_spawn frame redaction (_redact(info.task), _redact(info.label), _redact(info.requested_model)) into a module the census did not classify. After, that module is classified the same way as run_turn.py, where the code came from. No redaction call, sink, or posture row changes, and run_turn.py keeps its entry because it still calls _redact.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): the posture panel would count a module as an internal partition when it is really an egress boundary. That cannot happen here: turn_session.py adds no transport or audience. It hands the already-redacted frame to the same facade callback as before.
  • Evidence checked (which sandbox result proves it): test_every_redactor_call_site_is_a_registered_sink_or_allowlisted passes on this tree. With the entry reverted it fails with assert not [subagent_manager/turn_session.py], which matches the Static Ratchet Gate failure on aff2247.
  • No regression:
    • Tools still work (which tools/commands were run, result): scripts/check_file_line_cap.py reports 0 failures. black --check and flake8 are clean on the touched files.
    • Backward compatible (old config / old data / old callers still work, how checked): this adds one allowlist entry and changes no data, config, or caller.
    • Existing tests (which suites passed on this head): test_security_posture.py, test_security_posture_facade.py, test_run_bindings.py, test_subagent_prompt_hooks.py, and the run_turn subagent suites (delivery_ttl_anchor, provenance_write, scratch_cwd_project, shared_scratch, skill_trigger_text): 423 passed.
  • How to undo: drop the subagent_manager/turn_session.py line from NON_EGRESS_REDACTION_MODULES.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 29, 2026
@buluoray
buluoray enabled auto-merge (squash) October 29, 2026 23:41
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 30, 2026
Move the pre-stream steps of _run_inner_impl that close over none of its locals (the inherited approval policy, the session acquisition, the cleanup identity, the child's memory and steering, the spawn records and the prompt hooks) into subagent_manager/turn_session.py. They read the names tests patch on kiro_crew.subagent through a call-time sys.modules lookup, so every patch still reaches them. No behaviour change.
@buluoray
buluoray force-pushed the fix/run-turn-line-cap branch from ecc1331 to 1397b8a Compare October 30, 2026 19:18
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision labels Oct 30, 2026
@buluoray

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 1397b8a
  • What rule changed: none. One entry, subagent_manager/turn_session.py, is added to NON_EGRESS_REDACTION_MODULES in src/kiro_crew/security_posture.py, under the existing reason comment for the internal subagent_manager run partitions. This head is e845ffd rebased onto main after fix: turn main green after three concurrent merges (#25937) #25947 merged; the duplicate test_subagent_prompt_hooks.py commit was dropped (main already carries that fix). security_posture.py is unchanged from e845ffd. This head 1397b8a is ecc1331 rebased onto main, carrying perf(web): reconcile the reconnect sub-agent replay into held cards #23797 and feat(crew): let a mate pin its own agent harness #25485 in run_turn.py with turn_session.py and security_posture.py unchanged, and on it the census test passes, fails with the entry reverted, and the suites that name run_turn or the touched functions ran 5710 passed and 3 failed, the same 3 that fail on main 95f7856.
  • Before -> after (what was allowed/blocked, now): before, the census test failed because the run_turn.py split moved the subagent_spawn frame redaction (_redact(info.task), _redact(info.label), _redact(info.requested_model)) into a module the census did not classify. After, that module is classified the same way as run_turn.py, where the code came from. No redaction call, sink, or posture row changes, and run_turn.py keeps its entry because it still calls _redact.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): the posture panel would count a module as an internal partition when it is really an egress boundary. That cannot happen here: turn_session.py adds no transport or audience. It hands the already-redacted frame to the same facade callback as before.
  • Evidence checked (which sandbox result proves it): test_every_redactor_call_site_is_a_registered_sink_or_allowlisted passes on this tree. With the entry reverted it fails with assert not [subagent_manager/turn_session.py], which matches the Static Ratchet Gate failure on aff2247.
  • No regression:
    • Tools still work (which tools/commands were run, result): scripts/check_file_line_cap.py reports 0 failures. black --check and flake8 are clean on the touched files.
    • Backward compatible (old config / old data / old callers still work, how checked): this adds one allowlist entry and changes no data, config, or caller.
    • Existing tests (which suites passed on this head): test_security_posture.py, test_security_posture_facade.py, test_run_bindings.py, test_subagent_prompt_hooks.py, and the run_turn subagent suites (delivery_ttl_anchor, provenance_write, scratch_cwd_project, shared_scratch, skill_trigger_text): 423 passed.
  • How to undo: drop the subagent_manager/turn_session.py line from NON_EGRESS_REDACTION_MODULES.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed 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
@buluoray
buluoray merged commit 936f80d into main Oct 30, 2026
94 of 95 checks passed
@buluoray
buluoray deleted the fix/run-turn-line-cap branch October 30, 2026 23:08
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 30, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants