claude-yes 1.166.0 → 1.167.0

package/dist/{SUPPORTED_CLIS-Xem8nliL.js → SUPPORTED_CLIS-DFBATC85.js}

@@ -1,8 +1,8 @@
-import { t as CLIS_CONFIG } from "./ts-CXxZiZKE.js";
+import { t as CLIS_CONFIG } from "./ts-s3wYccKf.js";
 
 //#region ts/SUPPORTED_CLIS.ts
 const SUPPORTED_CLIS = Object.keys(CLIS_CONFIG);
 
 //#endregion
 export { SUPPORTED_CLIS as t };
-//# sourceMappingURL=SUPPORTED_CLIS-Xem8nliL.js.map
+//# sourceMappingURL=SUPPORTED_CLIS-DFBATC85.js.map

package/dist/SUPPORTED_CLIS-DLFqRE8W.js

@@ -0,0 +1,8 @@
+import "./ts-s3wYccKf.js";
+import "./logger-CDIsZ-Pp.js";
+import "./versionChecker-BvR6tV3u.js";
+import "./pidStore-BfoBWUjc.js";
+import "./globalPidIndex-DlmmJlO8.js";
+import { t as SUPPORTED_CLIS } from "./SUPPORTED_CLIS-DFBATC85.js";
+
+export { SUPPORTED_CLIS };

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import { t as invokedCliName } from "./invokedCli-uqM2YYA7.js";
 import { n as logger } from "./logger-CDIsZ-Pp.js";
-import { i as versionString, n as displayVersion, r as getInstalledPackage, t as checkAndAutoUpdate } from "./versionChecker-Dv5DhRs3.js";
+import { i as versionString, n as displayVersion, r as getInstalledPackage, t as checkAndAutoUpdate } from "./versionChecker-BvR6tV3u.js";
 import { argv } from "process";
 import { execFileSync, spawn } from "child_process";
 import ms from "ms";
@@ -481,9 +481,9 @@ function buildRustArgs(argv, cliFromScript, supportedClis) {
 	const rawArg = process.argv[2];
 	const managerCommands = !invokedCliName(process.argv);
 	const isHelpFlag = rawArg === "-h" || rawArg === "--help";
-	const { isSubcommand, runSubcommand, cmdHelp } = await import("./subcommands-BnsjTNpy.js");
+	const { isSubcommand, runSubcommand, cmdHelp } = await import("./subcommands-B-WoBVhk.js");
 	if (isHelpFlag && process.argv.length === 3) {
-		cmdHelp(managerCommands);
+		await cmdHelp(managerCommands);
 		process.exit(0);
 	}
 	if (isSubcommand(rawArg, managerCommands)) {
@@ -523,7 +523,7 @@ if (config.useRust) {
 		}
 	}
 	if (rustBinary) {
-		const { SUPPORTED_CLIS } = await import("./SUPPORTED_CLIS-ClQgRKQu.js");
+		const { SUPPORTED_CLIS } = await import("./SUPPORTED_CLIS-DLFqRE8W.js");
 		const rustArgs = buildRustArgs(process.argv, config.cli, SUPPORTED_CLIS);
 		if (config.verbose) {
 			console.log(`[rust] Using binary: ${rustBinary}`);

package/dist/index.js

@@ -1,6 +1,6 @@
-import { a as removeControlCharacters, i as AgentContext, n as agentYes, r as config, t as CLIS_CONFIG } from "./ts-CXxZiZKE.js";
+import { a as removeControlCharacters, i as AgentContext, n as agentYes, r as config, t as CLIS_CONFIG } from "./ts-s3wYccKf.js";
 import "./logger-CDIsZ-Pp.js";
-import "./versionChecker-Dv5DhRs3.js";
+import "./versionChecker-BvR6tV3u.js";
 import "./pidStore-BfoBWUjc.js";
 import "./globalPidIndex-DlmmJlO8.js";
 

package/dist/{schedule-CwAX3y8s.js → schedule-C2RMA3qm.js}

@@ -1,9 +1,9 @@
-import "./ts-CXxZiZKE.js";
+import "./ts-s3wYccKf.js";
 import "./logger-CDIsZ-Pp.js";
-import "./versionChecker-Dv5DhRs3.js";
+import "./versionChecker-BvR6tV3u.js";
 import "./pidStore-BfoBWUjc.js";
 import "./globalPidIndex-DlmmJlO8.js";
-import { t as SUPPORTED_CLIS } from "./SUPPORTED_CLIS-Xem8nliL.js";
+import { t as SUPPORTED_CLIS } from "./SUPPORTED_CLIS-DFBATC85.js";
 import { l as resolveSpawnCwd } from "./workspaceConfig-D3OH7and.js";
 import { createHash } from "node:crypto";
 
@@ -141,4 +141,4 @@ async function cmdSchedule(rest) {
 
 //#endregion
 export { cmdSchedule };
-//# sourceMappingURL=schedule-CwAX3y8s.js.map
+//# sourceMappingURL=schedule-C2RMA3qm.js.map

package/dist/{serve-DeJBMba0.js → serve-mLqsRwfR.js}

@@ -1,16 +1,16 @@
-import "./ts-CXxZiZKE.js";
+import "./ts-s3wYccKf.js";
 import "./logger-CDIsZ-Pp.js";
-import { r as getInstalledPackage } from "./versionChecker-Dv5DhRs3.js";
+import { r as getInstalledPackage } from "./versionChecker-BvR6tV3u.js";
 import "./pidStore-BfoBWUjc.js";
 import { a as updateGlobalPidStatus } from "./globalPidIndex-DlmmJlO8.js";
 import { t as pgidForWrapper } from "./reaper-C-eWAxIj.js";
 import "./configShared-CEyhl0WH.js";
-import { t as SUPPORTED_CLIS } from "./SUPPORTED_CLIS-Xem8nliL.js";
+import { t as SUPPORTED_CLIS } from "./SUPPORTED_CLIS-DFBATC85.js";
 import "./e2e-Bfw7qL9O.js";
 import "./webrtcLink-CBZkZ-LT.js";
 import "./remotes-T6nf0t3K.js";
 import { c as isProvisionAllowed, i as getSpawnHook, l as resolveSpawnCwd, r as getProvisionRoot, s as hasSpawnHook } from "./workspaceConfig-D3OH7and.js";
-import { A as writeToIpc, D as snapshotStatus, S as resolveOne, b as renderRawLog, c as extractNeedsInput, h as listRecords, i as controlCodeFromName, l as extractTaskCounts, o as deriveLiveStatus, v as readNotes, y as readPtysize } from "./subcommands-BY0mIDo9.js";
+import { A as writeToIpc, D as snapshotStatus, S as resolveOne, b as renderRawLog, c as extractNeedsInput, h as listRecords, i as controlCodeFromName, l as extractTaskCounts, o as deriveLiveStatus, v as readNotes, y as readPtysize } from "./subcommands-DWeo7ZLc.js";
 import { r as spawnRejectionReason } from "./spawnGate-B_VDMXYL.js";
 import yargs from "yargs";
 import { mkdir, open, readFile, stat, unlink, writeFile } from "fs/promises";
@@ -1445,4 +1445,4 @@ Options:
 
 //#endregion
 export { cmdServe };
-//# sourceMappingURL=serve-DeJBMba0.js.map
+//# sourceMappingURL=serve-mLqsRwfR.js.map

package/dist/{setup-hWG3ZBG3.js → setup-BtqKZx3q.js}

@@ -32,7 +32,7 @@ async function cmdSetup(rest) {
 	if (!existsSync(abs)) process.stderr.write(`  note: that directory doesn't exist yet — create it, or agents spawned there will fail\n`);
 	if (noShare) return 0;
 	process.stdout.write(`\nsharing this machine to agent-yes.com…\n`);
-	const { cmdServe } = await import("./serve-DeJBMba0.js");
+	const { cmdServe } = await import("./serve-mLqsRwfR.js");
 	return cmdServe([
 		"install",
 		"--share",
@@ -42,4 +42,4 @@ async function cmdSetup(rest) {
 
 //#endregion
 export { cmdSetup };
-//# sourceMappingURL=setup-hWG3ZBG3.js.map
+//# sourceMappingURL=setup-BtqKZx3q.js.map

package/dist/{subcommands-BnsjTNpy.js → subcommands-B-WoBVhk.js}

@@ -4,6 +4,6 @@ import "./configShared-CEyhl0WH.js";
 import "./e2e-Bfw7qL9O.js";
 import "./webrtcLink-CBZkZ-LT.js";
 import "./remotes-T6nf0t3K.js";
-import { A as writeToIpc, C as resolveReadWindow, D as snapshotStatus, E as runSubcommand, O as stopTipForCli, S as resolveOne, T as restartHintLines, _ as menuSelectKeys, a as cursorAbs, b as renderRawLog, c as extractNeedsInput, d as isAgentStuck, f as isExitRequest, g as matchKeyword, h as listRecords, i as controlCodeFromName, k as writeKeysPaced, l as extractTaskCounts, m as isSubcommand, n as READ_PAGE_DEFAULT, o as deriveLiveStatus, p as isPidAlive, r as cmdHelp, s as extractMenu, t as GRACEFUL_EXIT_COMMANDS, u as finalizedLines, v as readNotes, w as resolveResumeArgs, x as renderRawLogLines, y as readPtysize } from "./subcommands-BY0mIDo9.js";
+import { A as writeToIpc, C as resolveReadWindow, D as snapshotStatus, E as runSubcommand, O as stopTipForCli, S as resolveOne, T as restartHintLines, _ as menuSelectKeys, a as cursorAbs, b as renderRawLog, c as extractNeedsInput, d as isAgentStuck, f as isExitRequest, g as matchKeyword, h as listRecords, i as controlCodeFromName, k as writeKeysPaced, l as extractTaskCounts, m as isSubcommand, n as READ_PAGE_DEFAULT, o as deriveLiveStatus, p as isPidAlive, r as cmdHelp, s as extractMenu, t as GRACEFUL_EXIT_COMMANDS, u as finalizedLines, v as readNotes, w as resolveResumeArgs, x as renderRawLogLines, y as readPtysize } from "./subcommands-DWeo7ZLc.js";
 
 export { cmdHelp, isSubcommand, runSubcommand };

package/dist/{subcommands-BY0mIDo9.js → subcommands-DWeo7ZLc.js}

@@ -597,15 +597,15 @@ async function runSubcommand(argv) {
 			case "restart": return await cmdRestart(rest);
 			case "note": return await cmdNote(rest);
 			case "serve": {
-				const { cmdServe } = await import("./serve-DeJBMba0.js");
+				const { cmdServe } = await import("./serve-mLqsRwfR.js");
 				return cmdServe(rest);
 			}
 			case "setup": {
-				const { cmdSetup } = await import("./setup-hWG3ZBG3.js");
+				const { cmdSetup } = await import("./setup-BtqKZx3q.js");
 				return cmdSetup(rest);
 			}
 			case "schedule": {
-				const { cmdSchedule } = await import("./schedule-CwAX3y8s.js");
+				const { cmdSchedule } = await import("./schedule-C2RMA3qm.js");
 				return cmdSchedule(rest);
 			}
 			case "remote": {
@@ -624,9 +624,29 @@ async function runSubcommand(argv) {
 		return 1;
 	}
 }
-function cmdHelp(managerCommands = true) {
+/**
+* The banner shown by `ay help` / `ay -h` when this process is itself running
+* inside an agent (`AGENT_YES_PID` set — see resolveSender). Answers the three
+* things a nested agent actually needs: who am I, who spawned me, and how do I
+* drive sub-agents of my own — so it doesn't have to rediscover the fan-out
+* primitives (spawn / ay ls forest / ay ls --watch) from scratch every session.
+*/
+async function buildAgentContextSection(self) {
+	const hasParentPid = typeof self.parent_pid === "number" && self.parent_pid > 0;
+	const parent = hasParentPid ? (await listRecords(void 0, {
+		all: true,
+		active: false,
+		json: false,
+		latest: false,
+		cwdScope: null
+	})).find((r) => r.wrapper_pid === self.parent_pid) : void 0;
+	return `You are running inside an agent:\n  ${`You are agent pid ${self.pid} (${self.cli}) in ${shortenPath(self.cwd)}.`}\n  ${!hasParentPid ? `Top-level agent — no parent (started from a human shell or scheduler).` : parent ? `Spawned by agent pid ${parent.pid} (${parent.cli}) in ${shortenPath(parent.cwd)}.` : `Nested under a parent (wrapper pid ${self.parent_pid}) whose record isn't in the local registry.`}\n\nAs an agent, you can:\n  Spawn a sub-agent:\n    ay <cli> -- "<prompt>"                                  auto-links as your child\n    ay claude --model sonnet --advisor opus -- "<prompt>"   routine task\n    ay claude --model opus --advisor fable -- "<prompt>"    complex task\n    (pick --model by task complexity so easy tasks don't cost like hard ones;\n     --advisor is a claude-cli flag — only takes effect for claude/cy)\n  List agents (your children nest under your own pid in the tree):\n    ay ls --cwd ${shortenPath(self.cwd)}\n  Watch agent state changes, scoped to your workspace:\n    ay ls --watch --cwd ${shortenPath(self.cwd)}\n    (NDJSON stream of state changes across every matched agent — one watcher\n     for the whole fan-out instead of N \`ay status --watch\`es)\n  Read one sub-agent's output:\n    ay tail -f <pid>                        follow live output (no single command tails\n                                              many agents' content at once yet — loop\n                                              \`ay ls --json\` pids into per-pid \`ay tail\`)\n\n`;
+}
+async function cmdHelp(managerCommands = true) {
 	const setupLine = managerCommands ? `  ay setup                            guided setup: pick a workspace, share to agent-yes.com\n` : ``;
-	process.stdout.write("ay - agent-yes CLI\n\nManagement:\n  ay ls [keyword]                     list running agents\n  ay tail [-f] [-n N] <keyword>       last N lines (96), -f to follow\n  ay read <keyword> [page opts]       paginate: --last/--head N, --range A:B,\n                                        --before-line L [--limit N]\n  ay cat <keyword>                    full log\n  ay head <keyword>                   first N lines\n  ay send <keyword> <msg>             send a message\n  ay key <keyword> <key...>           send raw keystrokes (down/up/enter/esc/…) — drives menus\n  ay select <keyword> <N>             pick option N of a needs_input selection menu\n  ay attach <keyword>                 interactive attach (detach: Ctrl-\\)\n  ay stop <keyword>                   graceful shutdown (/exit for claude/codex)\n  ay exit <keyword> [reason]          graceful shutdown, recording who/why (= 'ay send <kw> exit')\n  ay restart <keyword> [--fresh]      stop (if live) + relaunch resuming the session; --fresh replays the prompt\n  ay status <keyword>                 agent status snapshot\n  ay result <keyword> [--wait]        pull an agent's structured result envelope\n  ay result set '<json>'              (inside an agent) deposit your result envelope\n  ay reap                             kill process groups leaked by dead agents\n\nRemote:\n" + setupLine + "  ay schedule <when> <cli> -- <msg>   run an agent on a schedule (HH:MM or cron)\n  ay serve [--port N]                 start HTTP API server (prints token)\n  ay serve status                     show serve daemon/server status\n  ay remote add <alias> http://<token>@<host>:<port>\n  ay remote ls / rm <alias>           manage saved remotes\n  ay ls   <token>@<host>:<port>       connect inline (no alias needed)\n  ay send <token>@<host>:<port>:<kw> <msg>\n\nRun an agent:\n  ay [claude|codex|gemini|...] [options] -- [prompt]\n  ay claude -- \"fix the bug in auth.ts\"\n  ay claude --help                    full agent-runner options\n\nLabs (examples at https://github.com/snomiao/agent-yes/tree/main/lab):\n  local-role-play/   designer + builder on one machine\n  http-remote/       ay serve remote access demo\n  p2p-pairing/       libp2p P2P  (needs: cargo build --features swarm)\n");
+	const self = process.env.AGENT_YES_PID ? await resolveSender() : null;
+	const agentSection = self ? await buildAgentContextSection(self) : "";
+	process.stdout.write(agentSection + "ay - agent-yes CLI\n\nManagement:\n  ay ls [keyword]                     list running agents\n  ay tail [-f] [-n N] <keyword>       last N lines (96), -f to follow\n  ay read <keyword> [page opts]       paginate: --last/--head N, --range A:B,\n                                        --before-line L [--limit N]\n  ay cat <keyword>                    full log\n  ay head <keyword>                   first N lines\n  ay send <keyword> <msg>             send a message\n  ay key <keyword> <key...>           send raw keystrokes (down/up/enter/esc/…) — drives menus\n  ay select <keyword> <N>             pick option N of a needs_input selection menu\n  ay attach <keyword>                 interactive attach (detach: Ctrl-\\)\n  ay stop <keyword>                   graceful shutdown (/exit for claude/codex)\n  ay exit <keyword> [reason]          graceful shutdown, recording who/why (= 'ay send <kw> exit')\n  ay restart <keyword> [--fresh]      stop (if live) + relaunch resuming the session; --fresh replays the prompt\n  ay status <keyword>                 agent status snapshot\n  ay result <keyword> [--wait]        pull an agent's structured result envelope\n  ay result set '<json>'              (inside an agent) deposit your result envelope\n  ay reap                             kill process groups leaked by dead agents\n\nRemote:\n" + setupLine + "  ay schedule <when> <cli> -- <msg>   run an agent on a schedule (HH:MM or cron)\n  ay serve [--port N]                 start HTTP API server (prints token)\n  ay serve status                     show serve daemon/server status\n  ay remote add <alias> http://<token>@<host>:<port>\n  ay remote ls / rm <alias>           manage saved remotes\n  ay ls   <token>@<host>:<port>       connect inline (no alias needed)\n  ay send <token>@<host>:<port>:<kw> <msg>\n\nRun an agent:\n  ay [claude|codex|gemini|...] [options] -- [prompt]\n  ay claude -- \"fix the bug in auth.ts\"\n  ay claude --help                    full agent-runner options\n\nLabs (examples at https://github.com/snomiao/agent-yes/tree/main/lab):\n  local-role-play/   designer + builder on one machine\n  http-remote/       ay serve remote access demo\n  p2p-pairing/       libp2p P2P  (needs: cargo build --features swarm)\n");
 	return 0;
 }
 function matchKeyword(record, keyword) {
@@ -3005,4 +3025,4 @@ async function cmdResultSet(rest) {
 
 //#endregion
 export { writeToIpc as A, resolveReadWindow as C, snapshotStatus as D, runSubcommand as E, stopTipForCli as O, resolveOne as S, restartHintLines as T, menuSelectKeys as _, cursorAbs as a, renderRawLog as b, extractNeedsInput as c, isAgentStuck as d, isExitRequest as f, matchKeyword as g, listRecords as h, controlCodeFromName as i, writeKeysPaced as k, extractTaskCounts as l, isSubcommand as m, READ_PAGE_DEFAULT as n, deriveLiveStatus as o, isPidAlive as p, cmdHelp as r, extractMenu as s, GRACEFUL_EXIT_COMMANDS as t, finalizedLines as u, readNotes as v, resolveResumeArgs as w, renderRawLogLines as x, readPtysize as y };
-//# sourceMappingURL=subcommands-BY0mIDo9.js.map
+//# sourceMappingURL=subcommands-DWeo7ZLc.js.map

package/dist/{ts-CXxZiZKE.js → ts-s3wYccKf.js}

@@ -1,5 +1,5 @@
 import { n as logger, t as addTransport } from "./logger-CDIsZ-Pp.js";
-import { r as getInstalledPackage } from "./versionChecker-Dv5DhRs3.js";
+import { r as getInstalledPackage } from "./versionChecker-BvR6tV3u.js";
 import { t as agentYesHome } from "./agentYesHome-_eJa3DaX.js";
 import { i as shouldUseLock, r as releaseLock, t as acquireLock } from "./runningLock-V4qvXgAw.js";
 import { t as PidStore } from "./pidStore-BfoBWUjc.js";
@@ -1803,4 +1803,4 @@ function sleep(ms) {
 
 //#endregion
 export { removeControlCharacters as a, AgentContext as i, agentYes as n, config as r, CLIS_CONFIG as t };
-//# sourceMappingURL=ts-CXxZiZKE.js.map
+//# sourceMappingURL=ts-s3wYccKf.js.map

package/dist/{versionChecker-Dv5DhRs3.js → versionChecker-BvR6tV3u.js}

@@ -7,7 +7,7 @@ import { fileURLToPath } from "url";
 
 //#region package.json
 var name = "claude-yes";
-var version = "1.166.0";
+var version = "1.167.0";
 
 //#endregion
 //#region ts/versionChecker.ts
@@ -215,4 +215,4 @@ async function displayVersion() {
 
 //#endregion
 export { versionString as i, displayVersion as n, getInstalledPackage as r, checkAndAutoUpdate as t };
-//# sourceMappingURL=versionChecker-Dv5DhRs3.js.map
+//# sourceMappingURL=versionChecker-BvR6tV3u.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-yes",
-  "version": "1.166.0",
+  "version": "1.167.0",
   "description": "A wrapper tool that automates interactions with various AI CLI tools by automatically handling common prompts and responses.",
   "keywords": [
     "ai",

package/ts/cli.ts

@@ -30,7 +30,7 @@ import { buildRustArgs } from "./buildRustArgs.ts";
   const isHelpFlag = rawArg === "-h" || rawArg === "--help";
   const { isSubcommand, runSubcommand, cmdHelp } = await import("./subcommands.ts");
   if (isHelpFlag && process.argv.length === 3) {
-    cmdHelp(managerCommands);
+    await cmdHelp(managerCommands);
     process.exit(0);
   }
   if (isSubcommand(rawArg, managerCommands)) {

package/ts/subcommands.spec.ts

@@ -113,25 +113,134 @@ describe("subcommands.isSubcommand", () => {
 });
 
 describe("subcommands.cmdHelp", () => {
-  it("hides the manager-only `setup` line for cli-bound aliases", async () => {
+  const capture = async (managerCommands?: boolean) => {
     const { cmdHelp } = await loadModule();
-    const capture = (managerCommands?: boolean) => {
-      let out = "";
-      const spy = vi.spyOn(process.stdout, "write").mockImplementation((s: unknown) => {
-        out += String(s);
-        return true;
-      });
-      try {
-        cmdHelp(managerCommands);
-      } finally {
-        spy.mockRestore();
-      }
-      return out;
-    };
-    expect(capture(true)).toContain("ay setup"); // manager
-    expect(capture()).toContain("ay setup"); // default = manager
-    expect(capture(false)).not.toContain("ay setup"); // cli-bound alias (cy)
-    expect(capture(false)).toContain("ay ls"); // universal commands still shown
+    let out = "";
+    const spy = vi.spyOn(process.stdout, "write").mockImplementation((s: unknown) => {
+      out += String(s);
+      return true;
+    });
+    try {
+      await cmdHelp(managerCommands);
+    } finally {
+      spy.mockRestore();
+    }
+    return out;
+  };
+
+  it("hides the manager-only `setup` line for cli-bound aliases", async () => {
+    expect(await capture(true)).toContain("ay setup"); // manager
+    expect(await capture()).toContain("ay setup"); // default = manager
+    expect(await capture(false)).not.toContain("ay setup"); // cli-bound alias (cy)
+    expect(await capture(false)).toContain("ay ls"); // universal commands still shown
+  });
+
+  it("stays plain for a human shell (no AGENT_YES_PID)", async () => {
+    const out = await capture();
+    expect(out).not.toContain("You are running inside an agent");
+  });
+
+  it("prints self + parent identity and sub-agent guidance when nested in an agent", async () => {
+    const { appendGlobalPid } = await import("./globalPidIndex.ts");
+    const parentWrapperPid = 555001;
+    const selfWrapperPid = 555002;
+    await appendGlobalPid({
+      pid: 900001,
+      cli: "codex",
+      prompt: "orchestrate the migration",
+      cwd: "/work/parent",
+      log_file: null,
+      fifo_file: null,
+      status: "active",
+      exit_code: null,
+      exit_reason: null,
+      started_at: Date.now(),
+      wrapper_pid: parentWrapperPid,
+    });
+    await appendGlobalPid({
+      pid: process.pid,
+      cli: "claude",
+      prompt: "fix the failing test",
+      cwd: "/work/parent/child",
+      log_file: null,
+      fifo_file: null,
+      status: "active",
+      exit_code: null,
+      exit_reason: null,
+      started_at: Date.now(),
+      wrapper_pid: selfWrapperPid,
+      parent_pid: parentWrapperPid,
+    });
+    const saved = process.env.AGENT_YES_PID;
+    process.env.AGENT_YES_PID = String(selfWrapperPid);
+    try {
+      const out = await capture();
+      expect(out).toContain("You are running inside an agent");
+      expect(out).toContain(`You are agent pid ${process.pid} (claude)`);
+      expect(out).toContain(`Spawned by agent pid 900001 (codex)`);
+      expect(out).toContain("Spawn a sub-agent");
+      expect(out).toContain(`ay ls --cwd /work/parent/child`);
+      expect(out).toContain(`ay ls --watch --cwd /work/parent/child`);
+    } finally {
+      if (saved === undefined) delete process.env.AGENT_YES_PID;
+      else process.env.AGENT_YES_PID = saved;
+    }
+  });
+
+  it("reports a nested-but-unresolved parent distinctly from top-level", async () => {
+    const { appendGlobalPid } = await import("./globalPidIndex.ts");
+    const selfWrapperPid = 555004;
+    await appendGlobalPid({
+      pid: process.pid,
+      cli: "claude",
+      prompt: null,
+      cwd: process.cwd(),
+      log_file: null,
+      fifo_file: null,
+      status: "active",
+      exit_code: null,
+      exit_reason: null,
+      started_at: Date.now(),
+      wrapper_pid: selfWrapperPid,
+      parent_pid: 999999999, // no record ever registered for this wrapper pid
+    });
+    const saved = process.env.AGENT_YES_PID;
+    process.env.AGENT_YES_PID = String(selfWrapperPid);
+    try {
+      const out = await capture();
+      expect(out).not.toContain("Top-level agent");
+      expect(out).toContain("Nested under a parent (wrapper pid 999999999)");
+    } finally {
+      if (saved === undefined) delete process.env.AGENT_YES_PID;
+      else process.env.AGENT_YES_PID = saved;
+    }
+  });
+
+  it("reports top-level (no parent) when parent_pid is absent", async () => {
+    const { appendGlobalPid } = await import("./globalPidIndex.ts");
+    const selfWrapperPid = 555003;
+    await appendGlobalPid({
+      pid: process.pid,
+      cli: "claude",
+      prompt: null,
+      cwd: process.cwd(),
+      log_file: null,
+      fifo_file: null,
+      status: "active",
+      exit_code: null,
+      exit_reason: null,
+      started_at: Date.now(),
+      wrapper_pid: selfWrapperPid,
+    });
+    const saved = process.env.AGENT_YES_PID;
+    process.env.AGENT_YES_PID = String(selfWrapperPid);
+    try {
+      const out = await capture();
+      expect(out).toContain("Top-level agent");
+    } finally {
+      if (saved === undefined) delete process.env.AGENT_YES_PID;
+      else process.env.AGENT_YES_PID = saved;
+    }
   });
 });
 

package/ts/subcommands.ts

@@ -387,14 +387,77 @@ export async function runSubcommand(argv: string[]): Promise<number | null> {
 // ay help
 // ---------------------------------------------------------------------------
 
-export function cmdHelp(managerCommands = true): number {
+/**
+ * The banner shown by `ay help` / `ay -h` when this process is itself running
+ * inside an agent (`AGENT_YES_PID` set — see resolveSender). Answers the three
+ * things a nested agent actually needs: who am I, who spawned me, and how do I
+ * drive sub-agents of my own — so it doesn't have to rediscover the fan-out
+ * primitives (spawn / ay ls forest / ay ls --watch) from scratch every session.
+ */
+async function buildAgentContextSection(self: GlobalPidRecord): Promise<string> {
+  const hasParentPid = typeof self.parent_pid === "number" && self.parent_pid > 0;
+  const parent = hasParentPid
+    ? (
+        await listRecords(undefined, {
+          all: true,
+          active: false,
+          json: false,
+          latest: false,
+          cwdScope: null,
+        })
+      ).find((r) => r.wrapper_pid === self.parent_pid)
+    : undefined;
+
+  const whoAmI = `You are agent pid ${self.pid} (${self.cli}) in ${shortenPath(self.cwd)}.`;
+  // Three distinct states: no parent at all (top-level); a parent_pid whose
+  // record we can resolve; or a parent_pid we can't resolve (its record aged
+  // out / lives on a remote) — that last case is still nested, just unknown,
+  // so it must not collapse into the "top-level" line.
+  const parentLine = !hasParentPid
+    ? `Top-level agent — no parent (started from a human shell or scheduler).`
+    : parent
+      ? `Spawned by agent pid ${parent.pid} (${parent.cli}) in ${shortenPath(parent.cwd)}.`
+      : `Nested under a parent (wrapper pid ${self.parent_pid}) whose record isn't in the local registry.`;
+
+  return (
+    `You are running inside an agent:\n` +
+    `  ${whoAmI}\n` +
+    `  ${parentLine}\n` +
+    `\n` +
+    `As an agent, you can:\n` +
+    `  Spawn a sub-agent:\n` +
+    `    ay <cli> -- "<prompt>"                                  auto-links as your child\n` +
+    `    ay claude --model sonnet --advisor opus -- "<prompt>"   routine task\n` +
+    `    ay claude --model opus --advisor fable -- "<prompt>"    complex task\n` +
+    `    (pick --model by task complexity so easy tasks don't cost like hard ones;\n` +
+    `     --advisor is a claude-cli flag — only takes effect for claude/cy)\n` +
+    `  List agents (your children nest under your own pid in the tree):\n` +
+    `    ay ls --cwd ${shortenPath(self.cwd)}\n` +
+    `  Watch agent state changes, scoped to your workspace:\n` +
+    `    ay ls --watch --cwd ${shortenPath(self.cwd)}\n` +
+    `    (NDJSON stream of state changes across every matched agent — one watcher\n` +
+    `     for the whole fan-out instead of N \`ay status --watch\`es)\n` +
+    `  Read one sub-agent's output:\n` +
+    `    ay tail -f <pid>                        follow live output (no single command tails\n` +
+    `                                              many agents' content at once yet — loop\n` +
+    `                                              \`ay ls --json\` pids into per-pid \`ay tail\`)\n` +
+    `\n`
+  );
+}
+
+export async function cmdHelp(managerCommands = true): Promise<number> {
   // `setup` is manager-only — hide it when invoked through a cli-bound alias
   // (cy/claude-yes/…), where `cy setup` runs the agent instead of managing the host.
   const setupLine = managerCommands
     ? `  ay setup                            guided setup: pick a workspace, share to agent-yes.com\n`
     : ``;
+  // Only agents carry AGENT_YES_PID — a human shell never sets it — so this
+  // section is skipped entirely (no async work at all) for interactive use.
+  const self = process.env.AGENT_YES_PID ? await resolveSender() : null;
+  const agentSection = self ? await buildAgentContextSection(self) : "";
   process.stdout.write(
-    `ay - agent-yes CLI\n` +
+    agentSection +
+      `ay - agent-yes CLI\n` +
       `\n` +
       `Management:\n` +
       `  ay ls [keyword]                     list running agents\n` +

package/dist/SUPPORTED_CLIS-ClQgRKQu.js

@@ -1,8 +0,0 @@
-import "./ts-CXxZiZKE.js";
-import "./logger-CDIsZ-Pp.js";
-import "./versionChecker-Dv5DhRs3.js";
-import "./pidStore-BfoBWUjc.js";
-import "./globalPidIndex-DlmmJlO8.js";
-import { t as SUPPORTED_CLIS } from "./SUPPORTED_CLIS-Xem8nliL.js";
-
-export { SUPPORTED_CLIS };