fix(agent): communication hygiene — no internal-detail leaks, no step narration#56
Merged
Merged
Conversation
…vices, retries) to users Surfacing HTTP status codes, backend service names, retry counts, or tool-call mechanics to authors is both a UX problem (confusing noise) and a security-hygiene concern (internal infrastructure disclosure). - Add a "Communicating with the user" section to the base system prompt instructing the agent to handle transient failures silently, never narrate retries or tool mechanics, and give only a brief non-technical apology when an operation ultimately fails. - Add a prompt-builder test asserting the guidance is present (anchored on "Never expose internal", "HTTP status codes", "stack traces", and "retry as needed without narrating it"). Co-Authored-By: Claude <[email protected]>
Widens the user-communication guidance: the agent should not narrate its plan
or intermediate progress ("I'll convert this first, then create the page",
"Now I have the content", "Let me try again") — just perform the work and
report the result.
Co-Authored-By: Claude <[email protected]>
mhaack
approved these changes
Jul 1, 2026
Contributor
|
🎉 This PR is included in version 1.24.9 🎉 The release is available on:
Your semantic-release bot 📦🚀 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Hardens how the agent talks to authors. Two related guardrails added to the base
system prompt (
src/prompt-builder.ts, inbuildSystemPrompt, so it applies to everyresponse regardless of skill or agent preset):
(500/503), internal service/backend names, stack traces, raw error objects, retry
counts, or tool-call mechanics. Transient failures are retried silently; an ultimate
failure gets a brief, non-technical apology, never the underlying cause.
("I'll convert this first, then create the page", "Now I have the content", "Let me
try again"); it performs the work and reports the result.
Problem
In a live chat, creating a page from an attached document, the agent exposed internal
detail and narrated its mechanics to the author, e.g.:
Authors should never see
503/service internals (a UX problem and a security-hygieneproblem — don't disclose internal error info), nor a play-by-play of tool steps.
What changed
src/prompt-builder.ts— new "## Communicating with the user" section in the basesystem prompt covering both guardrails above.
test/prompt-builder.test.ts— asserts the guidance is present (no-internal-detailsphrasing + the no-narration phrasing).
Commits:
9a3f788— do not disclose internal error details (status codes, services, retries)80ea711— also stop narrating internal plan/progress stepsTest plan
npm test→ all pass (307).mentioning it; on a multi-tool task it reports the outcome without narrating each step.
Risk
Low. Prompt-only change to user-facing communication; no behavioral/tool changes. Worst
case the model is slightly terser about progress.