fix(coding-agent): carry the monitor wait redirect on the bash surface, dedup terminal guidance

The PTY bash description now routes waits on observable state to the
monitor tool (the surface where a model actually types sleep 30; same
cross-tool routing pattern as the grep->rg snippet rule). Monitor
promptGuidelines collapse to the single when-to-use decision rule and
the terminal section keeps mechanics only, so each aspect is stated
once. The stale-wait-idioms gate now loads the bash description and the
bash-timeout prompt as surfaces, asserts the bash->monitor redirect, and
bans tmux teaching outside negative guidance.

Author: code-yeongyu

packages/coding-agent/src/core/extensions/builtin/terminal/changes.md

@@ -3,6 +3,33 @@
 The persistent-terminal tool suite (`bash` swapped to PTY-backed + `bash_output`,
 `kill_bash`, `bash_input`, `bash_resize`). Backed by `@earendil-works/pi-pty`.
 
+## Wait-discipline routing: bash surface redirect + guidance dedup (2026-07-28)
+
+### What changed
+
+- `tools/bash.ts`: the PTY `bash` tool description now carries the wait redirect — waiting on
+  observable state (a build finishing, a server coming up, a log line) is never a sleep/poll
+  loop; subscribe with the `monitor` tool instead. The bash surface is where a model actually
+  types `sleep 30`, and cross-tool routing in the misused tool's description follows the same
+  pattern as the grep→rg snippet rule (`test/bash-prompt-snippet.test.ts`). The upstream core
+  bash (`src/core/tools/bash.ts`) is deliberately untouched: its toolset has no monitor, and
+  guidance must never name a tool the toolset lacks.
+- `tools/monitor.ts`: promptGuidelines collapsed to the single when-to-use decision rule. The
+  command-shaping sentence duplicated the TERMINAL_PROMPT_SECTION bullet near-verbatim; each
+  aspect is now stated once (decision rule → Tool Guidelines; mechanics → terminal section;
+  redirect → bash schema; long-run routing → bash-timeout policy).
+- `prompt.ts`: the monitor bullet dropped its embedded when-to-use sentence (kept as the monitor
+  tool's guideline) and keeps the subscribe framing plus shaping/filtering/rearm mechanics.
+- `test/prompt-surface-stale-wait-idioms.test.ts`: the consistency gate now also loads the PTY
+  bash description and the bash-timeout prompt section as surfaces; new gates assert the bash
+  description routes waits to monitor, and that no agent-facing terminal surface teaches tmux as
+  the backgrounding mechanism (negative guidance like "do NOT use tmux" stays allowed).
+
+### Expected merge conflict zones on next upstream sync
+
+- LOW: `tools/bash.ts` description string, `tools/monitor.ts` promptGuidelines, `prompt.ts`
+  monitor bullet, gate-test surface list (all fork-owned).
+
 ## Monitor flat schema + subscribe-not-poll prompt (2026-07-27)
 
 ### What changed

packages/coding-agent/src/core/extensions/builtin/terminal/prompt.ts

@@ -14,12 +14,11 @@ manual \`&\` backgrounding — use the built-in session tools:
   \`view: "screen"\`. Completion arrives as a notification carrying the exit code and output
   tail — peeking is for steering, never for waiting.
 - \`monitor({ description, command, filter?, timeout_ms?, persistent? })\` subscribes you to a
-  command: its stdout lines arrive as injected events while you keep working. Any wait on
-  observable state (CI checks, builds, log patterns, deploys) is a monitor, never a foreground
-  sleep/poll loop. Shape the command by notifications needed: exit-on-condition for one
-  completion event; emit-per-occurrence (\`tail -f | grep --line-buffered\`, a polling loop
-  inside the command) for a stream. Filter noise at the command source, stop with \`kill_bash\`,
-  and use \`monitor({ action: "rearm", bash_id })\` only after a wake-budget pause.
+  command: its stdout lines arrive as injected events while you keep working. Shape the command
+  by notifications needed: exit-on-condition for one completion event; emit-per-occurrence
+  (\`tail -f | grep --line-buffered\`, a polling loop inside the command) for a stream. Filter
+  noise at the command source, stop with \`kill_bash\`, and use
+  \`monitor({ action: "rearm", bash_id })\` only after a wake-budget pause.
 - \`bash_input({ bash_id, input, keys, submit })\` sends stdin or named keys (e.g.
   \`["ctrl+c"]\`, \`["enter"]\`) to steer a REPL or interrupt a process.
 - \`bash_resize({ bash_id, cols, rows })\` resizes the PTY so full-screen programs reflow.

packages/coding-agent/src/core/extensions/builtin/terminal/tools/bash.ts

@@ -285,7 +285,7 @@ export function createPtyBashTool(ctx: TerminalToolContext) {
 		name: TERMINAL_BASH_TOOL,
 		label: "bash",
 		description:
-			"Execute a shell command in a persistent PTY-backed session. Set run_in_background:true for long-lived or interactive sessions; steer them with bash_input, snapshot with bash_output, tear down with kill_bash. Foreground timeout is a kill deadline in seconds.",
+			"Execute a shell command in a persistent PTY-backed session. Set run_in_background:true for long-lived or interactive sessions; steer them with bash_input, snapshot with bash_output, tear down with kill_bash. To wait on observable state (a build finishing, a server coming up, a log line), never run sleep or poll loops — subscribe with the monitor tool instead. Foreground timeout is a kill deadline in seconds.",
 		promptSnippet: "Run shell commands; run_in_background:true for long-lived/interactive PTY sessions",
 		promptGuidelines: ["Inspect PI_* environment variables for current model and session details."],
 		parameters: ptyBashSchema,

packages/coding-agent/src/core/extensions/builtin/terminal/tools/monitor.ts

@@ -115,7 +115,6 @@ export function createMonitorTool(ctx: TerminalToolContext) {
 		promptSnippet: "Subscribe to a command's stdout lines as injected events instead of polling",
 		promptGuidelines: [
 			"Waiting on observable state (CI checks, builds, log patterns, deploys) means a monitor, never a foreground sleep/poll loop.",
-			"Shape the command by notifications needed: exit-on-condition for one completion event; emit-per-occurrence (`tail -f | grep --line-buffered`, a polling loop inside the command) for a stream. Filter noise at the source.",
 		],
 		parameters: monitorSchema,
 		renderCall: renderMonitorCall,

packages/coding-agent/test/prompt-surface-stale-wait-idioms.test.ts

@@ -2,7 +2,12 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { describe, expect, it } from "vitest";
+import {
+	buildBashTimeoutPrompt,
+	resolveBashTimeoutDefaults,
+} from "../src/core/extensions/builtin/bash-timeout/timeout.ts";
 import { TERMINAL_PROMPT_SECTION } from "../src/core/extensions/builtin/terminal/prompt.ts";
+import { createPtyBashTool } from "../src/core/extensions/builtin/terminal/tools/bash.ts";
 import {
 	BASH_OUTPUT_WAIT_REMOVED_GUIDANCE,
 	createBashOutputTool,
@@ -23,22 +28,42 @@ const CODING_AGENT_ROOT = join(REPO_ROOT, "packages", "coding-agent");
 /** Lines mentioning wait_for are allowed only when they are removal guidance. */
 const GHOST_GUIDANCE_MARKER = /removed|no longer/i;
 
+/** Lines mentioning tmux are allowed only when they steer away from it. */
+const NEGATIVE_GUIDANCE_MARKER = /do not|don't|never/i;
+
 function surfaceLines(name: string, text: string): Array<{ name: string; line: number; text: string }> {
 	return text.split("\n").map((line, index) => ({ name, line: index + 1, text: line }));
 }
 
-function loadSurfaces(): Array<{ name: string; line: number; text: string }> {
-	const stubCtx = {
+function stubTerminalCtx(): TerminalToolContext {
+	return {
 		manager: { get: () => undefined },
 		cwd: process.cwd(),
 		defaultCols: 120,
 		defaultRows: 40,
 		getEnv: () => process.env,
 	} as unknown as TerminalToolContext;
+}
+
+/** The prompt surfaces the model actually sees (system-prompt sections + tool schemas). */
+function agentFacingSurfaces(): Array<{ name: string; line: number; text: string }> {
+	const stubCtx = stubTerminalCtx();
+	return [
+		...surfaceLines("terminal/prompt.ts TERMINAL_PROMPT_SECTION", TERMINAL_PROMPT_SECTION),
+		...surfaceLines("bash-timeout prompt section", buildBashTimeoutPrompt(resolveBashTimeoutDefaults({}))),
+		...surfaceLines("terminal bash tool description", createPtyBashTool(stubCtx).description),
+		...surfaceLines("bash_output tool description", createBashOutputTool(stubCtx).description),
+	];
+}
+
+function loadSurfaces(): Array<{ name: string; line: number; text: string }> {
+	const stubCtx = stubTerminalCtx();
 	const bashOutput = createBashOutputTool(stubCtx);
 
 	return [
 		...surfaceLines("terminal/prompt.ts TERMINAL_PROMPT_SECTION", TERMINAL_PROMPT_SECTION),
+		...surfaceLines("bash-timeout prompt section", buildBashTimeoutPrompt(resolveBashTimeoutDefaults({}))),
+		...surfaceLines("terminal bash tool description", createPtyBashTool(stubCtx).description),
 		...surfaceLines("bash_output tool description", bashOutput.description),
 		...surfaceLines("bash_output promptSnippet", bashOutput.promptSnippet ?? ""),
 		...surfaceLines(
@@ -69,15 +94,23 @@ describe("stale wait-idiom consistency gate", () => {
 		expect(TERMINAL_PROMPT_SECTION).not.toContain("wait_for");
 	});
 
+	it("the bash tool surface routes waits to the monitor tool", () => {
+		const bash = createPtyBashTool(stubTerminalCtx());
+		expect(bash.description).toContain("monitor");
+	});
+
+	it("no agent-facing terminal surface teaches tmux as the backgrounding mechanism", () => {
+		const violations = agentFacingSurfaces().filter(
+			({ text }) => /tmux/i.test(text) && !NEGATIVE_GUIDANCE_MARKER.test(text),
+		);
+		expect(
+			violations.map(({ name, line, text }) => `${name}:${line}: ${text.trim()}`),
+			"tmux taught as a backgrounding/wait mechanism outside negative guidance",
+		).toEqual([]);
+	});
+
 	it("the bash_output tool surface no longer advertises blocking", () => {
-		const stubCtx = {
-			manager: { get: () => undefined },
-			cwd: process.cwd(),
-			defaultCols: 120,
-			defaultRows: 40,
-			getEnv: () => process.env,
-		} as unknown as TerminalToolContext;
-		const bashOutput = createBashOutputTool(stubCtx);
+		const bashOutput = createBashOutputTool(stubTerminalCtx());
 		expect(bashOutput.description.toLowerCase()).not.toContain("block until");
 		expect(bashOutput.description).not.toContain("wait_for");
 		expect(bashOutput.promptSnippet ?? "").not.toContain("wait_for");