feat(agent-core): align model-facing prompts with actual tool behavior

[RealKai42]

What

A prompt-text-only accuracy pass over every model-visible prompt surface in agent-core: system.md, tool .md descriptions, zod .describe() strings, subagent profile role prompts (plan/coder/explore/agent.yaml), init.md, and injected reminder strings. 23 files, 57 insertions / 33 deletions — no behavior or schema changes.

Every hunk was cross-checked against the implementation it describes; the ripgrep-related claims were additionally verified empirically with the exact argument order the tools use.

Why

Tool descriptions had drifted from the code in places, and several enforced behaviors were never disclosed to the model — both classes make the model confidently wrong (e.g. concluding code does not exist because a natural Grep glob silently matches nothing, or promising exact cron delivery times the scheduler cannot honor).

Changes by theme

Fix descriptions that contradict the code

• Grep glob matches each file's full absolute path, so src/**/*.ts silently returns nothing — documented the working forms (*.ts, **/src/**/*.ts, or scope with path); verified empirically (0 vs 338 vs 571 matches)
• Glob path accepts relative paths; Glob results are files-only (.md + routing text in read.md)
• FetchURL: the default provider labels every service fetch extracted, so the description no longer promises a content-type-to-mode mapping; the result note states which mode you got
• cron: "30 14 28 2 *" repeats yearly unless recurring: false (the describe previously said "once"); removed a bench-only env knob from cron-list.md
• skill args: expansion also covers $1/$ARGUMENTS, and with no placeholders the string is appended as a trailing ARGUMENTS: line — the old text made models withhold args from skills with no declared parameters
• goal reminder no longer cites a "developer messages" channel that does not exist in the protocol
• system.md: .git/** returns nothing (VCS metadata is always pruned) — the old text claimed it "traverses in full"

Disclose enforced-but-silent behavior

• cron fires deliver only while the session is idle (mirrors the scheduler contract), and no-fire-within-5-years expressions are rejected at create time
• VCS directories are always excluded from Glob/Grep even with include_ignored=true
• sensitive-file guard exemptions: .env.example/.env.sample/.env.template and public SSH keys (id_rsa.pub etc.) read normally — prevents over-refusal on a common legitimate task
• large images may be downsampled while the <system> block reports original dimensions (grounds the relative-coordinates rule)
• subagent final messages under the length floor are sent back for expansion; background-disabled Agent calls are rejected before launch
• /init prompt now discloses the ~32 KB AGENTS.md performance-warning budget and steers toward information-dense output

Resolve cross-surface contradictions

• AskUserQuestion background describe and its result envelope no longer teach polling with TaskOutput (the tool body and every other background surface forbid it)
• AgentSwarm subagent_type documents that resumed subagents keep their original type, so combining it with resume_agent_ids is allowed — the opposite of the Agent tool's hard rejection, which burned models into avoiding valid calls
• bash.md scopes &&-chaining to genuinely dependent commands and steers independent read-only commands to parallel calls; example no longer models the cd-chaining the same file advises against
• the shared system.md no longer names tools that read-only subagent profiles lack (Write/Bash imperative, TodoList, date-via-Bash)

Add missing guidance

• root agent: a denied/rejected call means the user declined that action — adjust, don't retry unchanged or route around (extends the coaching subagents already receive from the runtime)
• plan subagent is told it is read-only (it previously inherited "you MUST make changes with tools" with no counterweight); coder subagent is told its final message is the entire handoff and what it must contain; explore subagent is told WebSearch/FetchURL are in scope
• gh CLI routing for GitHub-hosted work (hedged on availability); FetchURL login-wall note (no credentials are carried to the target site)
• a dual-use content-safety boundary keyed on authorization context; scope discipline (no drive-by refactors), surrounding-idiom matching, dependency-verification norms; file:line citation convention; sparse progress notes on long multi-phase tasks

Validation

• Full agent-core suite: 3402 passed / 0 failed (4 expected-fail, 1 todo)
• tsc --noEmit clean; repo lint 0 errors
• Test-pin audit: every edited sentence was grepped against packages/agent-core/test for pinned phrases before changing; pinned strings (e.g. agent.test.ts background-disabled opener, fetch-url.test.ts extracted/verbatim, read.test.ts sensitive regexes) are preserved

[changeset-bot]

🦋 Changeset detected

Latest commit: c476b17

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@moonshot-ai/agent-core	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

pnpm dlx https://pkg.pr.new/@moonshot-ai/kimi-code@c476b17

npx https://pkg.pr.new/@moonshot-ai/kimi-code@c476b17

commit: c476b17

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c3e5bd4b62

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Let agents fetch completed background answers

When the session has background persistence (normal CLI agents have BackgroundTaskPersistence), a background question's output is persisted to output.log; the automatic completion notification built by BackgroundManager.buildBackgroundTaskNotificationContext then contains an <output-file> pointer rather than the answer text. With this next_step, the model is told TaskOutput is only for missed notifications, so after a normal completion notification it can continue without ever reading the user's answer. Please allow TaskOutput or the returned output file after completion, while still discouraging polling before the user responds.

Useful? React with 👍 / 👎.