Skip to content

fix(context): send a custom agent's prompt once on kas - #31875

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
fix/13305-persona-once
Nov 7, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
fix/13305-persona-once

Conversation

@bolichen97

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: On KAS through kiro-cli 2.33.1 or later, a custom agent's own prompt reaches the model once at session start instead of twice.

A custom agent that sets its own persona (inline, or a file:// naming its own file) runs on KAS with that prompt on its wire definition, and Crew also opens the first turn with the same text as its [AGENT SYSTEM PROMPT] block. The model gets the persona twice.

Why it matters

Every such KAS session carries a second copy of its persona for its whole life before the first compaction: context space and input tokens spent on every turn for nothing.

Not a goal

  • kiro-cli. Proving what kiro-cli loaded needs a record of the spec it was handed at spawn and at set_mode, plus a check that its sandbox can read a file:// target; fix(context): send a custom agent's prompt once on kiro-cli and KAS #17172 carries that design. On kiro-cli the persona still arrives twice.
  • Crew's bundled KAS engine. No capture shows its release applying a custom agent's prompt, so it keeps the block.
  • The turn after a compaction. It re-sends the block on every backend, as today, because nothing shows what a harness keeps through its own compaction.
  • Prompts that differ once resolved: Crew's placeholders ({bot_name}, {{MAX_SUBAGENTS}}) or a remote-workspace session's added notice. They keep the block.

What changed (motivation → approach → change)

A custom agent's persona on KAS now reaches the model once instead of twice: Crew drops its own session-start copy (the [AGENT SYSTEM PROMPT] block) when KAS already holds the identical text. The runtime already recorded the prompt it sent KAS; the prompt builder never checked that record before adding its own copy.

Where Change
context_assembly/turn_message.py at session start, the block is left out when it equals the session's template://<agent>#prompt native document word for word
acp/runtime_session_create.py that document is recorded only when the session's kas_agent_prompt_applied is set
acp/harness/kas.py, acp/session_handle_class.py agent_prompt_applied: true only on a relay kiro-cli at or above KAS_AGENT_PROMPT_MIN_KIRO_CLI; false below it, when the release cannot be read, and on Crew's bundled engine
src/kiro_crew/docs/agent-spec-fields.md, docs/architecture/context-management.md, docs/system-specs/modules/providers.md say when the block is left out

Crew drops its copy only where KAS is known to apply the prompt. A KAS below kiro-cli 2.33.1 throws the prompt away, so there Crew's copy is the only one and it stays; the same goes for an unreadable release and Crew's bundled engine, which nothing has measured. The worst case is a repeat, as on main today, never a missing persona. The same record also feeds a private crewmate's essentials, so on those releases the essentials keep the persona body too.

Backwards compatibility

Compatible: every session whose harness is not known to hold the identical text still gets the block exactly as before.

Reader: src/kiro_crew/context_assembly/member.py:build_v2_essentials -- chat -- the prompt record it compares against is now absent on a KAS not known to apply the prompt, so the essentials keep the persona body there | test_the_prompt_is_recorded_as_held_only_where_kas_applies_it
Reader: src/kiro_crew/context_assembly/turn_message.py:build_message -- chat -- the block is left out only on an exact match with that record | test_the_block_stays_unless_the_harness_holds_its_exact_text

Tests

  • test/test_context_native_prompt_once.py: a KAS session that holds the agent's exact prompt (inline and file://, each with a control showing the prompt resolves) gets no block and no second copy; with nothing recorded, a record for another agent, or a {bot_name} prompt, the block stays; the turn after a compaction still restores it.
  • test/test_kas_mode_binding.py::test_the_prompt_is_recorded_as_held_only_where_kas_applies_it: through a stub KAS process, kiro-cli 2.32.0 and an unreadable release record nothing, 2.33.1 records the prompt.
  • test/test_kas_agent_prompt_floor.py::test_only_a_relay_at_the_floor_is_taken_to_apply_the_prompt: a relay at 2.33.1 is taken to apply the prompt, and a respawn onto Crew's bundled engine clears that.
  • Determinism: 20 runs at -n0 and 10 at -n 4 --dist loadgroup --max-worker-restart=2 with sibling files, and a shuffled order (seed 15747), all green.

Proof: PROVEN test/test_context_native_prompt_once.py::test_a_kas_session_handed_the_prompt_gets_no_second_copy[inline], test/test_context_native_prompt_once.py::test_a_kas_session_handed_the_prompt_gets_no_second_copy[file], test/test_kas_mode_binding.py::TestModeBinding::test_the_prompt_is_recorded_as_held_only_where_kas_applies_it[dropping-release], test/test_kas_mode_binding.py::TestModeBinding::test_the_prompt_is_recorded_as_held_only_where_kas_applies_it[unknown-release] (head 6e5ea64)

Manual verification

Not run against a live KAS. The behaviour this relies on, which KAS releases apply a custom agent's prompt, is the measured floor KAS_AGENT_PROMPT_MIN_KIRO_CLI already on main; the change only reads it.

Screenshots / video

N/A: no user-facing surface changes.

Related Issues

Part of #13305

Builds on #17172 by @ianlenora.

Sibling sweep

Swept: git grep -n "template://" -- src/
Sibling: src/kiro_crew/context_assembly/member.py:776 -- not affected -- it reads the same record, which is now written only where KAS applies the prompt
Sibling: src/kiro_crew/context_assembly/turn.py:90 -- tracked in #13305
Sibling: src/kiro_crew/acp/harness/kiro.py:139 -- tracked in #13305

Pattern harvest

Rule candidate: review-prompt
Pattern: a dedup that withholds the only other copy must key on evidence the other channel applied it, not on a record of what was sent

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.

A KAS session is handed a custom agent's own prompt on its wire
definition, and the runtime records that text in the session's native
documents. The session-start [AGENT SYSTEM PROMPT] block repeated it,
so the persona reached the model twice. The block is now withheld when
it would repeat that recorded text word for word; any other text, and
the turn after a compaction, keep it.

The record is written only where KAS is known to apply the prompt: a
relay kiro-cli at or above the release floor. Crew's bundled engine and
an older or unreadable release record nothing, so the block stays.

Part of #13305
@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 6, 2026 23:16
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 6, 2026
@github-actions

github-actions Bot commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

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

@github-actions

github-actions Bot commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks: the dedup applies only on a relay KAS at the measured KAS_AGENT_PROMPT_MIN_KIRO_CLI floor and only on an exact text match, so a missed match just repeats the persona, as main does today.

Notes

  • The applied/not-applied decision rests on the session handle's flag. This PR keeps the native_context_documents record and the kas_agent_prompt_applied flag separate, so a future writer of template://…#prompt that skips the flag would silently bring the dedup back on old releases. Writing that record in a single place (it is single today) stops this from drifting.

[DESIGN-REVIEWED] 6e5ea64

Description read

[DESCRIPTION-READ] 9d94517a40daf329a82e1b7071cc96ee808bfcec8289c0acd1e6fff77a19d7f0

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

@github-actions

github-actions Bot commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

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

First-Principles-Verdict: PASS

Nothing blocks. The block is dropped only when the text matches word for word, and only on a KAS release that is known to apply the prompt. Every other case falls back to today's duplicate, never to a missing persona.

What this change ships

Inventory (6 items) — 4 justified

Intent: a custom agent's persona should reach the model once per KAS session instead of twice, so tokens stop being wasted. This is a FIX.

  1. At session start, the [AGENT SYSTEM PROMPT] block is left out when KAS (kiro-cli 2.33.1 or later) already holds the identical prompt — justified
  2. The template://<agent>#prompt record is now written only when KAS is known to apply the prompt; an old, unknown or bundled engine gets no record — justified
  3. A private crewmate's essentials keep the persona body on KAS releases that drop the prompt (member.py:776 reads the same record) — rides along (declared)
  4. New agent_prompt_applied on the harness and kas_agent_prompt_applied on the session handle; one consumer, runtime_session_create.py:964. It can't be derived from agent_prompt_notice, which is "" both when the release is unknown and when it is new enough — justified
  5. Three spec and user docs now say when the block is left out — justified
  6. The test bundle setup is extracted into a _bundle helper — rides along

[FIRST-PRINCIPLES-REVIEWED] 6e5ea64

Description read

[DESCRIPTION-READ] b5d4890e7e31138723d99b7c16b059db3ce466b80b0c7cb52892e7302fca80b4

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

@github-actions

github-actions Bot commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 6e5ea64

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

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

@bolichen97
bolichen97 enabled auto-merge (squash) November 6, 2026 23:43
@github-actions

github-actions Bot commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 6e5ea64

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

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

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Approved for the on-call. Review lanes pass on 6e5ea64, no conflict, no open change request.

@KiroCrewCaptain
KiroCrewCaptain merged commit 568b039 into main Nov 7, 2026
96 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the fix/13305-persona-once branch November 7, 2026 00:43
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 7, 2026
buluoray added a commit that referenced this pull request Nov 7, 2026
A KAS session is handed a custom agent's own prompt on its wire
definition, and the runtime records that text in the session's native
documents. The session-start [AGENT SYSTEM PROMPT] block repeated it,
so the persona reached the model twice. The block is now withheld when
it would repeat that recorded text word for word; any other text, and
the turn after a compaction, keep it.

The record is written only where KAS is known to apply the prompt: a
relay kiro-cli at or above the release floor. Crew's bundled engine and
an older or unreadable release record nothing, so the block stays.

Part of #13305

(cherry picked from commit 568b039)

Release backport: docs/architecture/context-management.md conflicted
in one table row; resolved by keeping release's text and adding this
change's clause. Code and tests applied unchanged.

Original author: Bolin Chen (#31875).
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