one-code-extension 0.4.0 → 0.5.0

package/extensions/background/wakeup.ts

@@ -1,80 +1,184 @@
 /**
- * schedule_wakeup helpers (pure) — Claude Code's self-paced /loop timer.
+ * schedule_wakeup (pure): Claude Code's self-paced `/loop` timer, 2.1.282
+ * (findings §21). A wakeup is a one-shot job in the session's CronStore
+ * (source "wakeup"), so cron_list shows it and
+ * one timer fires everything. Its cron names the target minute
+ * (`M H * * *`); the fire itself is the exact target time.
  *
- * A fired wakeup or loop tick is a RE-INVOCATION, not a notification: Claude
- * Code enqueues the scheduled prompt verbatim as the next turn's input, behind
- * a dim "Running scheduled task" line in the TUI (findings §21), so the model
- * reads its own task back exactly as it wrote it. These builders therefore
- * return the prompt as-is; the TUI shows the line (`scheduledTaskComponent`).
+ * `DynamicLoop` is Claude Code's loop core: one pending wakeup (a new one
+ * supersedes the rest), a 7-day age per prompt, `stop` cancelling every
+ * wakeup, and the keepalive: a turn that ran a wakeup and ended without
+ * scheduling the next gets one 1200 s fallback, and a second miss ends the
+ * loop. Texts are Claude Code's with our tool names.
  */
 
+import { type CronStore, RECURRING_MAX_AGE_MS } from "./cron.ts";
+
 export const MIN_DELAY_SECONDS = 60;
 export const MAX_DELAY_SECONDS = 3600;
+/** Claude Code's keepalive fallback delay and budget. */
+export const KEEPALIVE_DELAY_SECONDS = 1200;
+export const KEEPALIVE_BUDGET = 1;
 
 export function clampDelaySeconds(delay: number): number {
 	if (!Number.isFinite(delay)) return MIN_DELAY_SECONDS;
 	return Math.min(MAX_DELAY_SECONDS, Math.max(MIN_DELAY_SECONDS, Math.round(delay)));
 }
 
-export interface WakeupRequest {
-	delaySeconds: number;
-	prompt: string;
-	reason: string;
-	/** Nothing changed this tick (matches CC's /loop noop flag). Recorded for callers; no effect on scheduling. */
-	noop?: boolean;
+/** An env flag as Claude Code reads a boolean: unset is `fallback`, a false-like value is off. */
+export function envFlag(value: string | undefined, fallback: boolean): boolean {
+	if (value === undefined) return fallback;
+	return !["", "0", "false", "no", "off"].includes(value.trim().toLowerCase());
 }
 
-export interface ParsedLoop {
-	/** undefined = dynamic (model self-paces via schedule_wakeup); set = fixed interval. */
-	intervalSeconds?: number;
-	task: string;
+/** Keepalive is on unless `CLAUDE_CODE_LOOP_KEEPALIVE` turns it off. */
+export function keepaliveEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+	return envFlag(env.CLAUDE_CODE_LOOP_KEEPALIVE, true);
 }
 
-/**
- * Parse `/loop` arguments: a leading duration token (`5m`, `30s`, `2h`) selects
- * fixed-interval mode and the rest is the task; no duration selects dynamic
- * (self-paced) mode. `stop` / `status` are handled by the caller, not here.
- */
-export function parseLoopArgs(raw: string): ParsedLoop {
-	const m = raw.trim().match(/^(\d+)\s*(s|m|h)\b\s*([\s\S]*)$/i);
-	if (m) {
-		const n = Number(m[1]);
-		const unit = m[2].toLowerCase();
-		const seconds = unit === "h" ? n * 3600 : unit === "m" ? n * 60 : n;
-		return { intervalSeconds: seconds, task: m[3].trim() };
-	}
-	return { task: raw.trim() };
+export interface WakeupSchedule {
+	scheduledFor: number;
+	clampedDelaySeconds: number;
+	wasClamped: boolean;
 }
 
-/** The turn input a fixed-interval `/loop` tick delivers: the task, verbatim (CC's cron fire). */
-export function buildLoopMessage(task: string): string {
-	return task;
+interface PromptAge {
+	startedAt: number;
+	lastScheduledFor: number;
+	agedOut?: boolean;
 }
 
-/**
- * The opening turn of a dynamic (self-paced) `/loop`: the user's command, so it
- * reads as their instruction — drive schedule_wakeup, pass the task back each
- * time. Unframed: it is the user's `/loop`, not a harness event.
- */
-export function buildDynamicLoopPrompt(task: string): string {
-	return [
-		"Self-paced loop started. Work the task below now. When this iteration is done, call schedule_wakeup to schedule the next one — choose delaySeconds by what you're waiting for, and pass the same task back as `prompt`. End the loop with schedule_wakeup {stop: true} when the task is complete or the user says to stop.",
-		"",
-		task,
-	].join("\n");
+export class DynamicLoop {
+	/** The wakeup prompt whose turn is running, for the keepalive (Claude Code's in-flight tick). */
+	inFlight: string | null = null;
+	private misses = 0;
+	private readonly ages = new Map<string, PromptAge>();
+
+	constructor(
+		private readonly store: CronStore,
+		private readonly maxAgeMs = RECURRING_MAX_AGE_MS,
+	) {}
+
+	/** A pending wakeup exists. */
+	hasPending(): boolean {
+		return this.store.list().some((job) => job.source === "wakeup");
+	}
+
+	/**
+	 * Claude Code's shared scheduling step: null when the loop for this prompt
+	 * is past its maximum age, which ends it.
+	 */
+	schedule(delaySeconds: number, prompt: string, now: number, viaKeepalive = false): WakeupSchedule | null {
+		if (!viaKeepalive) this.misses = 0;
+		this.store.deleteWhere((job) => job.source === "wakeup");
+		const age = this.ages.get(prompt);
+		const stale = age !== undefined && now > age.lastScheduledFor + MAX_DELAY_SECONDS * 1000;
+		const startedAt = age === undefined || stale ? now : age.startedAt;
+		if (this.maxAgeMs > 0 && now - startedAt >= this.maxAgeMs) {
+			if (!age?.agedOut) this.ages.set(prompt, { startedAt, lastScheduledFor: now - (MAX_DELAY_SECONDS - MIN_DELAY_SECONDS) * 1000, agedOut: true });
+			return null;
+		}
+		const clamped = clampDelaySeconds(delaySeconds);
+		const wasClamped = !(delaySeconds >= MIN_DELAY_SECONDS && delaySeconds <= MAX_DELAY_SECONDS);
+		const scheduledFor = now + clamped * 1000;
+		const target = new Date(scheduledFor);
+		this.store.create({ cron: `${target.getMinutes()} ${target.getHours()} * * *`, prompt, recurring: false, source: "wakeup", fireAt: scheduledFor }, now);
+		this.ages.set(prompt, { startedAt, lastScheduledFor: scheduledFor });
+		if (viaKeepalive) this.misses++;
+		return { scheduledFor, clampedDelaySeconds: clamped, wasClamped };
+	}
+
+	/**
+	 * `stop: true`: cancel every pending wakeup; the count is the result's.
+	 * The cancelled prompts and the one in flight forget their age, so a
+	 * restarted loop gets a fresh 7 days (Claude Code's `forgetChainStart`).
+	 */
+	stop(): number {
+		const cancelled = this.store.deleteWhere((job) => job.source === "wakeup");
+		for (const job of cancelled) this.ages.delete(job.prompt);
+		if (this.inFlight !== null) this.ages.delete(this.inFlight);
+		this.inFlight = null;
+		this.misses = 0;
+		return cancelled.length;
+	}
+
+	/**
+	 * A turn ended. When it ran a wakeup and left none pending, re-arm once at
+	 * the keepalive delay; past the budget the loop ends.
+	 */
+	settle(now: number, keepalive = keepaliveEnabled()): "none" | "armed" | "ended" {
+		const prompt = this.inFlight;
+		this.inFlight = null;
+		if (prompt === null || !keepalive || this.hasPending()) return "none";
+		if (this.misses >= KEEPALIVE_BUDGET) return "ended";
+		return this.schedule(KEEPALIVE_DELAY_SECONDS, prompt, now, true) ? "armed" : "ended";
+	}
+
+	clear(): void {
+		this.inFlight = null;
+		this.misses = 0;
+		this.ages.clear();
+	}
 }
 
-/** The turn input a fired wakeup delivers: the scheduled prompt, verbatim (CC re-invokes with it). */
-export function buildWakeupMessage(request: WakeupRequest): string {
-	return request.prompt;
+// ── Model-facing text (Claude Code 2.1.282, our tool names) ────────────────
+
+export function formatScheduled(result: WakeupSchedule, now: number): string {
+	const at = new Date(result.scheduledFor).toTimeString().slice(0, 8);
+	const inSeconds = Math.max(0, Math.round((result.scheduledFor - now) / 1000));
+	const clamped = result.wasClamped ? ` (clamped to ${result.clampedDelaySeconds}s from your requested value)` : "";
+	return `Next wakeup scheduled for ${at} (in ${inSeconds}s)${clamped}. Nothing more to do this turn — the harness re-invokes you when the wakeup fires or a task-notification arrives.`;
 }
 
-export function describeSchedule(request: WakeupRequest): string {
-	const clamped = clampDelaySeconds(request.delaySeconds);
-	const minutes = Math.round((clamped / 60) * 10) / 10;
-	const adjusted =
-		clamped !== request.delaySeconds
-			? ` (adjusted from ${request.delaySeconds}s — the allowed range is ${MIN_DELAY_SECONDS}-${MAX_DELAY_SECONDS}s)`
-			: "";
-	return `Wake-up scheduled in ${clamped}s (~${minutes}min)${adjusted}: ${request.reason}`;
+export const AGED_OUT_RESULT = "Wakeup not scheduled. The loop reached its maximum duration — the loop has ended; do not re-issue.";
+
+export function formatStopped(cancelled: number): string {
+	const monitor = "If you armed a monitor for this loop, task_stop it now; otherwise nothing more to do this turn.";
+	if (cancelled === 0) {
+		return `Loop stopped — any dynamic loop in this session is ended; there was no pending wakeup to cancel. If you are running a fixed-interval /loop (a recurring cron), it is NOT stopped by this call — cancel it with cron_delete. ${monitor}`;
+	}
+	return `Loop stopped — cancelled ${cancelled} pending wakeup(s); no further dynamic-loop wakeups scheduled. ${monitor}`;
 }
+
+export const WAKEUP_ERRORS = {
+	delayAndReason: "`delaySeconds` and `reason` are required when `stop` is not true.",
+	prompt: "`prompt` is required when `stop` is not true.",
+	noop: "`noop` is required when `stop` is not true.",
+} as const;
+
+/**
+ * Claude Code's description for a session whose prompt-cache TTL it cannot
+ * name (its third branch): One Code runs on any provider, so the 1-hour and
+ * 5-minute branches, which assume Anthropic billing, never apply as such.
+ */
+export const SCHEDULE_WAKEUP_DESCRIPTION = `Schedule when to resume work in /loop dynamic mode — the user invoked /loop without an interval, asking you to self-pace iterations of a specific task.
+
+Do NOT schedule a short-interval wakeup to poll for background work you started — when harness-tracked work finishes, you are re-invoked automatically, so polling is wasted. Instead schedule a long fallback (1200s+) so the loop survives if the work hangs or never notifies. The exception is external work the harness cannot track (a CI run, a deploy, a remote queue) — there, pick a delay matched to how fast that state actually changes.
+
+Pass the same /loop prompt back via \`prompt\` each turn so the next firing repeats the task. For an autonomous /loop (no user prompt), pass the literal sentinel \`<<autonomous-loop-dynamic>>\` as \`prompt\` instead — the runtime resolves it back to the autonomous-loop instructions at fire time. (There is a similar \`<<autonomous-loop>>\` sentinel for cron_create-based autonomous loops; do not confuse the two — schedule_wakeup always uses the \`-dynamic\` variant.) To end the loop, call this tool with \`stop: true\` (omit every other field) — the loop ends immediately and no further wakeups fire.
+
+Set \`noop: true\` if nothing changed — you checked and there's nothing to report ("no change", "still waiting", "quiet hold"). Set \`noop: false\` if something happened worth keeping — you edited a file, posted a message, advanced state, or surfaced a finding. Consecutive \`noop: true\` ticks are collapsed in the user's terminal view and tracked as a streak, so long quiet holds stay legible to the user without scrolling. Omit \`noop\` when stopping (\`stop: true\`).
+
+## Picking delaySeconds
+
+The Anthropic prompt cache decides how expensive a wake-up is: waking inside the cache TTL re-reads your conversation context cached (fast, cheap); waking past it re-reads everything uncached. The TTL depends on how the session is billed: Claude subscriber sessions get a 1-hour TTL (dropping to 5 minutes during usage overage), while API-key, Bedrock, and Vertex sessions default to 5 minutes.
+
+In either regime: never schedule extra wakeups just to keep the cache warm — they cost more than the cache miss they avoid. Match the delay to what you're actually waiting for: when actively polling external state the harness can't notify you about (a CI run, a deploy, a remote queue), pick the delay from how fast that state actually changes; for idle ticks with no specific signal to watch, default to **1200s–1800s** (20–30 min) — the user can always interrupt if they need you sooner.
+
+On a 5-minute TTL only, two refinements: under 300s (60s–270s) the cache stays warm, so prefer 270s over 300s when actively polling (300s is the worst-of-both — you pay the miss without amortizing it); and commit to 1200s+ rather than repeated ~300s waits, so one cache miss buys a long wait.
+
+The runtime clamps to [60, 3600], so you don't need to clamp yourself.
+
+## The reason field
+
+One short sentence on what you chose and why. Goes to telemetry and is shown back to the user. "watching CI run" beats "waiting." The user reads this to understand what you're doing without having to predict your cadence in advance — make it specific.
+`;
+
+export const SCHEDULE_WAKEUP_PARAMS = {
+	delaySeconds: "Seconds from now to wake up. Clamped to [60, 3600] by the runtime. Required unless `stop` is true.",
+	reason: "One short sentence explaining the chosen delay. Goes to telemetry and is shown to the user. Be specific. Required unless `stop` is true.",
+	prompt:
+		"The /loop input to fire on wake-up. Pass the same /loop input verbatim each turn so the next firing re-enters the skill and continues the loop. For autonomous /loop (no user prompt), pass the literal sentinel `<<autonomous-loop-dynamic>>` instead (the dynamic-pacing variant, not the cron_create-mode `<<autonomous-loop>>`). Required unless `stop` is true.",
+	stop: "Set to true to end the dynamic loop immediately instead of scheduling another wakeup. When true, all other fields are ignored and no further wakeups fire.",
+	noop: "true = nothing changed (you checked and there is nothing to report). false = something happened worth keeping (edited a file, posted a message, advanced state, surfaced a finding). Consecutive noop:true ticks are collapsed in the user's terminal view and tracked as a streak. Required unless `stop` is true.",
+} as const;

package/extensions/bash/background.ts

@@ -5,7 +5,7 @@
  * A background command spawns detached in its own process group, spools
  * stdout+stderr to memory (tail-capped) and to a log file when one is given,
  * and satisfies the BackgroundTask contract so task_output/task_stop work
- * unchanged. Robustness rules from docs/features/tools/records/background-bash.md: `output()`
+ * unchanged. Robustness rules from working-docs/features/tools/records/background-bash.md: `output()`
  * never returns an empty body for a finished task (an explicitly-marked
  * "(no output)" beats an ambiguous blank a weak model reads as failure), and
  * the completion callback receives exactly what `output()` returns, so the
@@ -13,9 +13,10 @@
  */
 
 import { createWriteStream } from "node:fs";
+import { StringDecoder } from "node:string_decoder";
 import type { BackgroundTask } from "../background/registry.ts";
 import { whenAborted } from "../lib/abort.ts";
-import { detachedSpawnOptions, KILL_GRACE_MS, stopProcessTree, waitForChildExit } from "../lib/process-tree.ts";
+import { detachedSpawnOptions, KILL_GRACE_MS, rememberProcessGroup, stopProcessTree, waitForChildExit } from "../lib/process-tree.ts";
 import { bashSpawnOrThrow, type ShellSpawn, spawnShellCommand } from "../lib/shell-spawn.ts";
 
 export const STORED_OUTPUT_CAP = 200_000;
@@ -35,6 +36,8 @@ export interface BashFinishSummary {
 	timedOut: boolean;
 	/** Exactly what task.output() returns — never empty. */
 	output: string;
+	/** The flushed spool, absent if writing it failed. */
+	logPath?: string;
 }
 
 export interface StartBackgroundBashOptions {
@@ -61,23 +64,33 @@ export function startBackgroundBash(options: StartBackgroundBashOptions): Backgr
 		...detachedSpawnOptions(),
 		stdio: ["ignore", "pipe", "pipe"],
 	});
+	rememberProcessGroup(child);
 
 	let stored = "";
+	let overflowed = false;
+	let spoolFailed = false;
 	let ended = false;
 	let stopRequested = false;
 	let timedOut = false;
 	const log = options.logPath ? createWriteStream(options.logPath, { flags: "a" }) : undefined;
 	log?.on("error", () => {
-		// Spooling to disk is best-effort; the in-memory tail stays authoritative.
+		// Never name a missing or partial file as the full output.
+		spoolFailed = true;
+		task.logPath = undefined;
 	});
 
-	const append = (chunk: Buffer) => {
-		const text = chunk.toString();
-		stored = tailCap(stored + text, STORED_OUTPUT_CAP);
-		log?.write(text);
+	// One streaming decoder per stream: a UTF-8 character split across two
+	// reads must not become two U+FFFD. The log gets the raw bytes.
+	const stdoutText = new StringDecoder("utf8");
+	const stderrText = new StringDecoder("utf8");
+	const appender = (decoder: StringDecoder) => (chunk: Buffer) => {
+		const text = stored + decoder.write(chunk);
+		overflowed ||= text.length > STORED_OUTPUT_CAP;
+		stored = tailCap(text, STORED_OUTPUT_CAP);
+		if (!spoolFailed) log?.write(chunk);
 	};
-	child.stdout?.on("data", append);
-	child.stderr?.on("data", append);
+	child.stdout?.on("data", appender(stdoutText));
+	child.stderr?.on("data", appender(stderrText));
 
 	let finish!: () => void;
 	const finished = new Promise<void>((resolve) => {
@@ -94,7 +107,9 @@ export function startBackgroundBash(options: StartBackgroundBashOptions): Backgr
 		startedAt: Date.now(),
 		logPath: options.logPath,
 		ownUI: true, // rendered live by the subagents panel's shell manager
-		output: () => stored || (task.status === "running" ? "" : EMPTY_OUTPUT_MARKER),
+		output: () => overflowed && !task.logPath
+			? `[The command's spool file could not be written, so only the last ${STORED_OUTPUT_CAP.toLocaleString("en-US")} characters of its output were kept.]\n${stored}`
+			: stored || (task.status === "running" ? "" : EMPTY_OUTPUT_MARKER),
 		stop: () => {
 			stopRequested = true;
 			// SIGTERM the tree, SIGKILL after the grace: a command that traps TERM
@@ -117,18 +132,39 @@ export function startBackgroundBash(options: StartBackgroundBashOptions): Backgr
 		if (ended) return;
 		ended = true;
 		if (timer) clearTimeout(timer);
-		task.status = status;
-		task.finishedAt = Date.now();
+		// An incomplete sequence at the very end decodes as U+FFFD, as it would have.
+		const rest = stdoutText.end() + stderrText.end();
+		if (rest) stored = tailCap(stored + rest, STORED_OUTPUT_CAP);
+		let completed = false;
 		const complete = () => {
+			if (completed) return;
+			completed = true;
+			task.status = status;
+			task.finishedAt = Date.now();
 			finish();
-			options.onFinished(task, { exitCode, signal, stopped: stopRequested, timedOut, output: task.output() });
+			options.onFinished(task, { exitCode, signal, stopped: stopRequested, timedOut, output: task.output(), logPath: task.logPath });
 		};
 		// end() flushes asynchronously; `finished` must not resolve while the
 		// log file is still short of what output() returns, or a reader sent to
-		// logPath by the completion notification can see a truncated file. The
-		// callback also fires if the stream errors, so this cannot hang.
-		if (log) log.end(complete);
-		else complete();
+		// logPath by the completion notification can see a truncated file.
+		// `close` follows a clean end and an error alike; a stuck stream (a
+		// write that never calls back) must not keep the task running, so after
+		// a second it is dropped and the partial file is no longer named.
+		if (log && !log.closed) {
+			const fallback = setTimeout(() => {
+				spoolFailed = true;
+				task.logPath = undefined;
+				log.destroy();
+				complete();
+			}, 1_000);
+			log.once("close", () => {
+				clearTimeout(fallback);
+				complete();
+			});
+			log.end();
+		} else {
+			complete();
+		}
 	};
 
 	// Exit plus a short stdio grace, not `close`: a descendant the stop missed

package/extensions/bash/child.ts

@@ -0,0 +1,7 @@
+/** One Code's bash tool for an in-process child session (lib/child-extensions.ts): the same tool, prints nothing. */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { bashTool } from "./index.ts";
+
+export default function childBashExtension(pi: ExtensionAPI) {
+	bashTool(pi, { announce: false });
+}

package/extensions/bash/description.ts

@@ -0,0 +1,188 @@
+/**
+ * The bash tool's model-facing texts: Claude Code's Bash descriptions (pure).
+ *
+ * Claude Code has three: a short form for its current models, with one extra
+ * bullet ("IMPORTANT: Avoid using this tool to run `cat`…") when auto mode is
+ * off, and a long form for its weakest models that is the same in every mode.
+ * One Code picks the form by tier (lib/tool-variants.ts) and the extra bullet
+ * by the permission mode. Two kinds of change from Claude Code's text: tool
+ * names are One Code's (`read`, `edit`, `write`, `monitor`, `task_create`),
+ * and the working-directory sentence says what this tool does, since each
+ * command starts in the session's working directory and a `cd` does not carry
+ * over (lib/shell-tool.ts), where Claude Code tracks the directory between
+ * calls. The parameter texts are Claude Code's. On the tiny tier, the one
+ * with dedicated grep, find and ls tools (search-tools/tools.ts), the long
+ * form's two shell-`find` bullets give way to a pointer at those tools, as
+ * tiny's system prompt says (system-prompt/tiers/low.ts).
+ */
+
+import type { DescriptionForm } from "../lib/tool-variants.ts";
+
+/** The bullet Claude Code adds to the short form when auto mode is off. */
+export const BASH_AVOID_SHELL_READS_LINE = "- IMPORTANT: Avoid using this tool to run `cat`, `head`, `tail`, `sed`, `awk`, or `echo` commands, unless explicitly instructed or after you have verified that a dedicated tool cannot accomplish your task. Instead, use the appropriate dedicated tool as this will provide a much better experience for the user.\n";
+
+/** The short form outside auto mode. */
+export const BASH_SHORT_DESCRIPTION = `Executes a bash command and returns its output.
+
+- Each call starts in the session's working directory and a \`cd\` does not carry over, so prefer absolute paths — \`cd\` in a compound command can trigger a permission prompt. Shell state (env vars, functions) does not persist.
+- IMPORTANT: Avoid using this tool to run \`cat\`, \`head\`, \`tail\`, \`sed\`, \`awk\`, or \`echo\` commands, unless explicitly instructed or after you have verified that a dedicated tool cannot accomplish your task. Instead, use the appropriate dedicated tool as this will provide a much better experience for the user.
+- Command output is displayed to you, not reliably to the user.
+- \`timeout\` is in milliseconds: default 120000, max 600000 for a foreground command.
+- \`run_in_background\` runs the command detached: it keeps running across turns and re-invokes you when it exits. No \`&\` needed. Foreground \`sleep\` is blocked; use monitor with an until-loop to wait on a condition.
+
+# Git
+- Interactive flags (\`-i\`, e.g. \`git rebase -i\`, \`git add -i\`) are not supported in this environment.
+- Use the \`gh\` CLI for GitHub operations (PRs, issues, API).
+- Commit or push only when the user asks. If on the default branch, branch first.
+- End git commit messages and PR bodies with the attribution lines given in the conversation's system-reminder, when one is present.`;
+
+/** The long form (every permission mode). */
+export const BASH_LONG_DESCRIPTION = `Executes a given bash command and returns its output.
+
+Each command starts in the session's working directory; neither a directory change (\`cd\`) nor shell state (variables, functions) carries over to the next command.
+
+IMPORTANT: Avoid using this tool to run \`cat\`, \`head\`, \`tail\`, \`sed\`, \`awk\`, or \`echo\` commands, unless explicitly instructed or after you have verified that a dedicated tool cannot accomplish your task. Instead, use the appropriate dedicated tool as this will provide a much better experience for the user:
+
+ - Read files: Use read (NOT cat/head/tail)
+ - Edit files: Use edit (NOT sed/awk)
+ - Write files: Use write (NOT echo >/cat <<EOF)
+ - Communication: Output text directly (NOT echo/printf)
+While the bash tool can do similar things, it’s better to use the built-in tools as they provide a better user experience and make it easier to review tool calls and give permission.
+
+# Instructions
+ - If your command will create new directories or files, first use this tool to run \`ls\` to verify the parent directory exists and is the correct location.
+ - Always quote file paths that contain spaces with double quotes in your command (e.g., cd "path with spaces/file.txt")
+ - Try to maintain your current working directory throughout the session by using absolute paths and avoiding usage of \`cd\`. You may use \`cd\` if the User explicitly requests it. In particular, never prepend \`cd <current-directory>\` to a \`git\` command — \`git\` already operates on the current working tree, and the compound triggers a permission prompt.
+ - You may specify an optional timeout in milliseconds (up to 600000ms / 10 minutes for a foreground command). By default, your command will timeout after 120000ms (2 minutes).
+ - You can use the \`run_in_background\` parameter to run the command in the background. Only use this if you don't need the result immediately and are OK being notified when the command completes later. You do not need to check the output right away - you'll be notified when it finishes. You do not need to use '&' at the end of the command when using this parameter.
+ - For git commands:
+  - Prefer to create a new commit rather than amending an existing commit.
+  - Before running destructive operations (e.g., git reset --hard, git push --force, git checkout --), consider whether there is a safer alternative that achieves the same goal. Only use destructive operations when they are truly the best approach.
+  - Never skip hooks (--no-verify) or bypass signing (--no-gpg-sign, -c commit.gpgsign=false) unless the user has explicitly asked for it. If a hook fails, investigate and fix the underlying issue.
+ - Avoid unnecessary \`sleep\` commands:
+  - Do not sleep between commands that can run immediately — just run them.
+  - Use the monitor tool to stream events from a background process (each stdout line is a notification). For one-shot "wait until done," use bash with run_in_background instead.
+  - If your command is long running and you would like to be notified when it finishes — use \`run_in_background\`. No sleep needed.
+  - Do not retry failing commands in a sleep loop — diagnose the root cause.
+  - If waiting for a background task you started with \`run_in_background\`, you will be notified when it completes — do not poll.
+  - Long leading \`sleep\` commands are blocked. To poll until a condition is met, use monitor with an until-loop (e.g. \`until <check>; do sleep 2; done\`) — you get a notification when the loop exits. Do not chain shorter sleeps to work around the block.
+ - When running \`find\`, search from \`.\` (or a specific path), not \`/\` — scanning the full filesystem can exhaust system resources on large trees.
+ - When using \`find -regex\` with alternation, put the longest alternative first. Example: use \`'.*\\.\\(tsx\\|ts\\)'\` not \`'.*\\.\\(ts\\|tsx\\)'\` — the second form silently skips \`.tsx\` files.
+
+
+# Committing changes with git
+
+Only create commits when requested by the user. If unclear, ask first. When the user asks you to create a new git commit, follow these steps carefully:
+
+You can call multiple tools in a single response. When multiple independent pieces of information are requested and all commands are likely to succeed, run multiple tool calls in parallel for optimal performance. The numbered steps below indicate which commands should be batched in parallel.
+
+Git Safety Protocol:
+- NEVER update the git config
+- NEVER run destructive git commands (push --force, reset --hard, checkout ., restore ., clean -f, branch -D) unless the user explicitly requests these actions. Taking unauthorized destructive actions is unhelpful and can result in lost work, so it's best to ONLY run these commands when given direct instructions 
+- NEVER skip hooks (--no-verify, --no-gpg-sign, etc) unless the user explicitly requests it
+- NEVER run force push to main/master, warn the user if they request it
+- CRITICAL: Always create NEW commits rather than amending, unless the user explicitly requests a git amend. When a pre-commit hook fails, the commit did NOT happen — so --amend would modify the PREVIOUS commit, which may result in destroying work or losing previous changes. Instead, after hook failure, fix the issue, re-stage, and create a NEW commit
+- When staging files, prefer adding specific files by name rather than using "git add -A" or "git add .", which can accidentally include sensitive files (.env, credentials) or large binaries
+- NEVER commit changes unless the user explicitly asks you to. It is VERY IMPORTANT to only commit when explicitly asked, otherwise the user will feel that you are being too proactive
+
+1. Run the following bash commands in parallel, each using the bash tool:
+  - Run a git status command to see all untracked files. IMPORTANT: Never use the -uall flag as it can cause memory issues on large repos.
+  - Run a git diff command to see both staged and unstaged changes that will be committed.
+  - Run a git log command to see recent commit messages, so that you can follow this repository's commit message style.
+2. Analyze all staged changes (both previously staged and newly added) and draft a commit message:
+  - Summarize the nature of the changes (eg. new feature, enhancement to an existing feature, bug fix, refactoring, test, docs, etc.). Ensure the message accurately reflects the changes and their purpose (i.e. "add" means a wholly new feature, "update" means an enhancement to an existing feature, "fix" means a bug fix, etc.).
+  - Do not commit files that likely contain secrets (.env, credentials.json, etc). Warn the user if they specifically request to commit those files
+  - Draft a concise (1-2 sentences) commit message that focuses on the "why" rather than the "what"
+  - Ensure it accurately reflects the changes and their purpose
+3. Run the following commands in parallel:
+   - Add relevant untracked files to the staging area.
+   - Create the commit with a message, ending with the attribution lines given in the conversation's system-reminder, when one is present.
+   - Run git status after the commit completes to verify success.
+   Note: git status depends on the commit completing, so run it sequentially after the commit.
+4. If the commit fails due to pre-commit hook: fix the issue and create a NEW commit
+
+Important notes:
+- NEVER run additional commands to read or explore code, besides git bash commands
+- NEVER use the task_create or Agent tools
+- DO NOT push to the remote repository unless the user explicitly asks you to do so
+- IMPORTANT: Never use git commands with the -i flag (like git rebase -i or git add -i) since they require interactive input which is not supported.
+- IMPORTANT: Do not use --no-edit with git rebase commands, as the --no-edit flag is not a valid option for git rebase.
+- If there are no changes to commit (i.e., no untracked files and no modifications), do not create an empty commit
+- In order to ensure good formatting, ALWAYS pass the commit message via a HEREDOC, a la this example:
+<example>
+git commit -m "$(cat <<'EOF'
+   Commit message here.
+   EOF
+   )"
+</example>
+
+# Creating pull requests
+Use the gh command via the bash tool for ALL GitHub-related tasks including working with issues, pull requests, checks, and releases. If given a Github URL use the gh command to get the information needed.
+
+IMPORTANT: When the user asks you to create a pull request, follow these steps carefully:
+
+1. Run the following bash commands in parallel using the bash tool, in order to understand the current state of the branch since it diverged from the main branch:
+   - Run a git status command to see all untracked files (never use -uall flag)
+   - Run a git diff command to see both staged and unstaged changes that will be committed
+   - Check if the current branch tracks a remote branch and is up to date with the remote, so you know if you need to push to the remote
+   - Run a git log command and \`git diff [base-branch]...HEAD\` to understand the full commit history for the current branch (from the time it diverged from the base branch)
+2. Analyze all changes that will be included in the pull request, making sure to look at all relevant commits (NOT just the latest commit, but ALL commits that will be included in the pull request!!!), and draft a pull request title and summary:
+   - Keep the PR title short (under 70 characters)
+   - Use the description/body for details, not the title
+3. Run the following commands in parallel:
+   - Create new branch if needed
+   - Push to remote with -u flag if needed
+   - Create PR using gh pr create with the format below. Use a HEREDOC to pass the body to ensure correct formatting. End the body with the attribution lines given in the conversation's system-reminder, when one is present.
+<example>
+gh pr create --title "the pr title" --body "$(cat <<'EOF'
+## Summary
+<1-3 bullet points>
+
+## Test plan
+[Bulleted markdown checklist of TODOs for testing the pull request...]
+EOF
+)"
+</example>
+
+Important:
+- DO NOT use the task_create or Agent tools
+- Return the PR URL when you're done, so the user can see it
+
+# Other common operations
+- View comments on a Github PR: gh api repos/foo/bar/pulls/123/comments`;
+
+/** The long form's shell-`find` advice, which the tiny tier's search tools replace. */
+const SHELL_FIND_LINES = ` - When running \`find\`, search from \`.\` (or a specific path), not \`/\` — scanning the full filesystem can exhaust system resources on large trees.
+ - When using \`find -regex\` with alternation, put the longest alternative first. Example: use \`'.*\\.\\(tsx\\|ts\\)'\` not \`'.*\\.\\(ts\\|tsx\\)'\` — the second form silently skips \`.tsx\` files.
+`;
+const SEARCH_TOOLS_LINE = ` - Search with the dedicated tools, not this shell: the find tool for files, the grep tool for content, the ls tool to list a directory.
+`;
+
+/** The long form on the tiny tier, whose grep, find and ls tools replace shell searches. */
+export const BASH_LONG_SEARCH_TOOLS_DESCRIPTION = BASH_LONG_DESCRIPTION.replace(SHELL_FIND_LINES, SEARCH_TOOLS_LINE);
+
+/** The description for a form and permission mode; `searchTools` when the session has the dedicated search tools. */
+export function bashDescription(form: DescriptionForm, autoMode: boolean, searchTools = false): string {
+	if (form === "long") return searchTools ? BASH_LONG_SEARCH_TOOLS_DESCRIPTION : BASH_LONG_DESCRIPTION;
+	return autoMode ? BASH_SHORT_DESCRIPTION.replace(BASH_AVOID_SHELL_READS_LINE, "") : BASH_SHORT_DESCRIPTION;
+}
+
+/** Claude Code's parameter descriptions. */
+export const BASH_PARAMS = {
+	command: `The command to execute`,
+	timeout: `Optional timeout in milliseconds (max 600000 for a foreground command)`,
+	description: `Clear, concise description of what this command does in active voice. Never use words like "complex" or "risk" in the description - just describe what it does.
+
+Say what the command does in plain words: do not echo the command's text, its flags, or file paths - the user reads this description, often without seeing the command.
+
+For simple commands (git, npm, standard CLI tools), keep it brief (5-10 words):
+- ls → "List files in current directory"
+- git status → "Show working tree status"
+- npm install → "Install package dependencies"
+
+For commands that are harder to parse at a glance (piped commands, obscure flags, etc.), add enough context to clarify what it does:
+- find . -name "*.tmp" -exec rm {} \\; → "Find and delete all .tmp files recursively"
+- git reset --hard origin/main → "Discard all local changes and match remote main"
+- curl -s url | jq '.data[]' → "Fetch JSON from URL and extract data array elements"`,
+	run_in_background: `Set to true to run this command in the background.`,
+} as const;