cyberlegion 1.2.0 → 1.3.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "cyberlegion",
-	"version": "1.2.0",
+	"version": "1.3.0",
 	"description": "Agent session spawning, messaging, and dispatch — the Legion and its Legate.",
 	"author": {
 		"name": "unional"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "cyberlegion",
-	"version": "1.2.0",
+	"version": "1.3.0",
 	"description": "Agent session spawning, messaging, and dispatch — the Legion and its Legate.",
 	"author": {
 		"name": "unional"

package/.plugin/pins.json

@@ -1,3 +1,3 @@
 {
-	"cyberlegion": "1.2.0"
+	"cyberlegion": "1.3.0"
 }

package/bin/cyberlegion

@@ -0,0 +1,5 @@
+#!/bin/sh
+# Claude Code puts a plugin's bin/ on the Bash tool's PATH, where the file name is the command name.
+# This extensionless twin of cyberlegion.mjs makes a bare `cyberlegion` resolve to the CLI this
+# plugin ships, with no global install.
+exec node "$(dirname -- "$0")/cyberlegion.mjs" "$@"

package/dist/cli.mjs

@@ -6292,6 +6292,9 @@ const KILL_LINE = "";
 *   throws without sending. A multi-row draft cannot be typed back exactly: a scrape cannot tell a
 *   wrapped row from a newline, and a newline typed back would submit it.
 *
+* Text `ownText` recognizes is the caller's own, not a draft: it is cleared at once, whatever rows it
+* wraps onto, `send` runs, and nothing is typed back.
+*
 * Text the clear leaves in place was never a draft — an idle placeholder this reader does not know —
 * so `send` runs and nothing is typed back.
 */
@@ -6308,10 +6311,11 @@ async function withDraftGuard(adapter, exec, target, send, options = {}) {
 			return { kind: "unknown" };
 		}
 	};
+	const isOwn = (s) => s.kind === "draft" && options.ownText?.(s.text) === true;
 	let state = read();
 	const start = now();
 	let changedAt = start;
-	while (state.kind === "draft" && now() - changedAt < idleMs) {
+	while (state.kind === "draft" && !isOwn(state) && now() - changedAt < idleMs) {
 		if (now() - start + pollMs > maxWaitMs) throw new Error(`pane ${target.id} holds a draft the user is still editing — gave up after ${maxWaitMs / 1e3}s without typing`);
 		await sleep(pollMs);
 		const next = read();
@@ -6319,12 +6323,13 @@ async function withDraftGuard(adapter, exec, target, send, options = {}) {
 		state = next;
 	}
 	if (state.kind !== "draft") return send();
+	if (isOwn(state)) {
+		await clearLine(adapter, exec, target, sleep);
+		return send();
+	}
 	if (state.rows > 1) throw new Error(`pane ${target.id} holds an idle draft spanning ${state.rows} rows, which cannot be typed back exactly — left it untouched`);
 	const draft = state.text;
-	adapter.sendText(exec, target, END_OF_LINE);
-	await sleep(KEY_SETTLE_MS);
-	adapter.sendText(exec, target, KILL_LINE);
-	await sleep(KEY_SETTLE_MS);
+	await clearLine(adapter, exec, target, sleep);
 	const after = read();
 	if (after.kind === "draft" && after.text === draft) return send();
 	try {
@@ -6334,6 +6339,12 @@ async function withDraftGuard(adapter, exec, target, send, options = {}) {
 		adapter.sendText(exec, target, draft);
 	}
 }
+async function clearLine(adapter, exec, target, sleep) {
+	adapter.sendText(exec, target, END_OF_LINE);
+	await sleep(KEY_SETTLE_MS);
+	adapter.sendText(exec, target, KILL_LINE);
+	await sleep(KEY_SETTLE_MS);
+}
 //#endregion
 //#region src/console/ring.ts
 const DEFAULT_ATTEMPTS = 10;
@@ -6404,6 +6415,28 @@ const DELIVERY_DOORBELL = "You have unread mail — check your inbox.";
 function spawnDoorbell(briefPath) {
 	return `Read your brief at ${briefPath}, then begin work.`;
 }
+const SPAWN_DOORBELL = /^Readyourbriefat.+,thenbeginwork\.$/;
+const RESUME_DOORBELL = /^Yoursessionwasrestartedwithitsconversationresumed—continueyourwork\.Ifyouhavenoearlierconversation,readyourbriefat.+,thenbeginwork\.$/;
+/**
+* Whether `text`, read out of a peer's input box, is a ring cyberlegion typed — the delivery doorbell,
+* a spawn or resume doorbell, or `message`, the one about to be rung — rather than a human's draft. A harness
+* can take a ring and put its text back in the box (cursor-agent with a rejected login). Whitespace is
+* ignored, since the box wraps the text onto rows wherever it likes.
+*/
+function isRingText(text, message) {
+	const squeeze = (s) => s.replace(/\s+/g, "");
+	const box = squeeze(text);
+	if (box === "") return false;
+	return box === squeeze("You have unread mail — check your inbox.") || SPAWN_DOORBELL.test(box) || RESUME_DOORBELL.test(box) || message !== void 0 && box === squeeze(message);
+}
+/**
+* The first-turn instruction for a restarted session that resumed its conversation. The resume can
+* fall back to a fresh session (the harness no longer has the conversation), and the ring cannot tell
+* which one took the turn, so it names the brief for a session that finds no earlier conversation.
+*/
+function resumeDoorbell(briefPath) {
+	return `Your session was restarted with its conversation resumed — continue your work. If you have no earlier conversation, read your brief at ${briefPath}, then begin work.`;
+}
 /**
 * A freshly-launched harness cold-boots slower than an already-running peer, so the spawn first-turn
 * ring gets a wider retry budget than a plain `mail send` doorbell (nudge's own 10 × 400ms): flush the
@@ -6472,7 +6505,8 @@ async function wakeRecipient(store, getAdapter, exec, input, nudgeOpts, guardOpt
 		const target = { id: pane };
 		await withDraftGuard(adapter, exec, target, () => ringTurn(adapter, exec, target, DELIVERY_DOORBELL, nudgeOpts), {
 			...guardOpts,
-			harness
+			harness,
+			ownText: (text) => isRingText(text)
 		});
 		return {
 			rung: true,
@@ -6505,9 +6539,11 @@ async function wakeSpawn(getAdapter, exec, input, nudgeOpts = SPAWN_NUDGE_OPTS,
 	if (input.noWake) return { rung: false };
 	try {
 		const adapter = getAdapter();
-		await withDraftGuard(adapter, exec, input.target, () => ringTurn(adapter, exec, input.target, spawnDoorbell(input.briefPath), nudgeOpts), {
+		const doorbell = (input.resumed ? resumeDoorbell : spawnDoorbell)(input.briefPath);
+		await withDraftGuard(adapter, exec, input.target, () => ringTurn(adapter, exec, input.target, doorbell, nudgeOpts), {
 			...guardOpts,
-			harness: input.harness
+			harness: input.harness,
+			ownText: (text) => isRingText(text)
 		});
 		return {
 			rung: true,
@@ -6836,6 +6872,20 @@ function resetCommandFor(harness) {
 	if (FALSE_FRIEND_HARNESSES.has(harness)) throw new Error(`"${harness}" has no honest fresh-context command — its own "/clear" clears only the terminal screen, not the model context, so unit clear refuses to send a false-friend reset that would leave stale context behind`);
 	throw new Error(`"${harness}" is not in the reset map (${Object.keys(RESET_MAP).join(" | ")}) — unit clear refuses to guess a command`);
 }
+/** The primary checkout of the repository containing `repo`, asked of git from inside it (`git -C`)
+* rather than from the process cwd. */
+function primaryRootOfRepo(exec, repo) {
+	const dir = resolve(repo);
+	try {
+		return resolvePrimaryRoot((cmd, args) => exec(cmd, cmd === "git" ? [
+			"-C",
+			dir,
+			...args
+		] : args));
+	} catch {
+		throw new Error(`--repo ${repo} is not inside a git repository`);
+	}
+}
 /**
 * Launch a new peer session as a genuine sibling unit: create a real git worktree distinct from
 * the primary checkout (refuse the primary checkout), open a session backend (tmux or herdr) with
@@ -6859,9 +6909,9 @@ function spawn(ctx, input) {
 	if (!harness || !(harness in LAUNCH_MAP)) throw new Error(`spawn needs a --harness in the launch map (${Object.keys(LAUNCH_MAP).join(" | ")})`);
 	const brief = resolveBrief(input);
 	if (brief == null) throw new Error("spawn needs a brief — pass --task <text>, --task - (stdin), or --brief-file <path>");
-	if (input.cwd && (input.branch || input.worktreePath)) throw new Error("--cwd cannot combine with the worktree-creating flags --branch/--worktree-path");
+	if (input.cwd && (input.branch || input.worktreePath || input.repo)) throw new Error("--cwd cannot combine with the worktree-creating flags --branch/--worktree-path/--repo");
 	const id = randomId();
-	const primaryRoot = resolvePrimaryRoot(exec);
+	const primaryRoot = input.repo ? primaryRootOfRepo(exec, input.repo) : resolvePrimaryRoot(exec);
 	const launch = input.command ?? LAUNCH_MAP[harness];
 	const launchLine = () => composeLaunchLine(ctx, sessionAdapter.name, id, launch);
 	const from = callerPane(sessionAdapter, normalizedEnv);
@@ -7041,10 +7091,43 @@ function labelFor(at, input, brief, id) {
 * supplied `ctx.self`), the multiplexer env prefix, then the harness launch command. Writes the shim
 * as a side effect, so call it only past every refusal, right before the session opens. Shared by
 * `spawn` and `unit restart` so a restarted unit boots exactly as a spawned one does.
+*
+* `bindSelf` has the new pane run `unit rebind <id>` through the shim before the harness starts, so
+* the session binds itself to the unit even when the caller dies before its own bind write. It needs
+* the shim, so a context with no recorded invocation gets no bind step.
+*/
+function composeLaunchLine(ctx, muxName, id, launch, options = {}) {
+	const shim = ctx.self ? writeSelfShim(paths.dataDir(ctx.store.root, id), ctx.self) : void 0;
+	const bind = shim && options.bindSelf ? `${shellQuote$1(shim)} unit rebind ${shellQuote$1(id)} --space ${shellQuote$1(ctx.store.root)} >/dev/null 2>&1; ` : "";
+	const prefix = `${shim ? shimEnvPrefix(shim) : ""}${muxEnvPrefix(muxName)}`;
+	return `${bind}${prefix}${launch}${options.fallback ? ` || ${prefix}${options.fallback}` : ""}`;
+}
+/**
+* How each harness resumes a conversation by id, appended to the unit's own launch command. Cursor is
+* absent: its hook's id is not confirmed to be the chat id `cursor-agent --resume` takes, so a cursor
+* unit restarts fresh and is rebriefed.
 */
-function composeLaunchLine(ctx, muxName, id, launch) {
-	const shimDir = ctx.self ? writeSelfShim(paths.dataDir(ctx.store.root, id), ctx.self) : void 0;
-	return `${shimDir ? `PATH=${shellQuote$1(shimDir)}:"$PATH" ` : ""}${muxEnvPrefix(muxName)}${launch}`;
+const RESUME_MAP = {
+	claude: (id) => `--resume ${shellQuote$1(id)}`,
+	codex: (id) => `resume ${shellQuote$1(id)}`
+};
+/**
+* The launch that resumes `conversation`, or undefined when this harness has no resume here or the
+* launch is not the harness's own command — a wrapper script may not take the harness's flags.
+*/
+function resumeLaunch(harness, launch, conversation) {
+	const resume = RESUME_MAP[harness];
+	if (!resume || launch.split(/\s+/)[0] !== LAUNCH_MAP[harness]) return void 0;
+	return `${launch} ${resume(conversation)}`;
+}
+/**
+* Put the shim's directory first on PATH, so a brief's bare `cyberlegion` runs it, and name the shim
+* itself in `$CYBERLEGION_CLI`. The plugin's hook runs outside that PATH lookup (and a PATH lookup
+* cannot tell this shim from a stale global install), so it reads the variable instead: set only
+* here, it marks a spawned session and names the CLI that spawned it.
+*/
+function shimEnvPrefix(shim) {
+	return `PATH=${shellQuote$1(dirname(shim))}:"$PATH" CYBERLEGION_CLI=${shellQuote$1(shim)} `;
 }
 /**
 * The env prefix typed ahead of the launch command so the spawned peer inherits the caller's
@@ -7073,7 +7156,7 @@ function selfInvocation() {
 }
 /**
 * Write `<dataDir>/bin/cyberlegion`, a POSIX shim that execs `self` with the caller's arguments,
-* and return its directory. A spawned session gets that directory first on its PATH, so the
+* and return its path. A spawned session gets that directory first on its PATH, so the
 * `cyberlegion` a brief tells it to run is the install that spawned it: nothing is resolved from
 * the registry or the session's own PATH at report time.
 */
@@ -7083,7 +7166,7 @@ function writeSelfShim(dataDir, self) {
 	const shim = join(dir, "cyberlegion");
 	writeFileSync(shim, `#!/bin/sh\nexec ${self.map(shellQuote$1).join(" ")} "$@"\n`);
 	chmodSync(shim, 493);
-	return dir;
+	return shim;
 }
 /** Single-quote `s` for a POSIX shell, so any path survives word splitting and expansion. */
 function shellQuote$1(s) {
@@ -7135,7 +7218,8 @@ async function nudgeUnit(ctx, ref, options = {}) {
 	const adapter = selectSessionAdapter(ctx.env ?? process.env, exec);
 	const result = await withDraftGuard(adapter, exec, target, () => ringTurn(adapter, exec, target, message, options.nudgeOpts), {
 		...options.guardOpts,
-		harness: agent.harness
+		harness: agent.harness,
+		ownText: (text) => isRingText(text, message)
 	});
 	return {
 		agent,
@@ -7174,7 +7258,8 @@ async function clearUnit(ctx, ref, options = {}) {
 	const adapter = selectSessionAdapter(env, exec);
 	await withDraftGuard(adapter, exec, target, async () => adapter.submit(exec, target, command), {
 		...options.guardOpts,
-		harness: agent.harness
+		harness: agent.harness,
+		ownText: (text) => isRingText(text)
 	});
 	return {
 		agent,
@@ -7469,6 +7554,7 @@ function spawnCommandInput(opts, listCursorModels) {
 			branch: opts.branch,
 			worktreePath: opts.worktreePath,
 			cwd: opts.cwd,
+			repo: opts.repo,
 			at: opts.at
 		},
 		noWake: opts.wake === false,
@@ -7860,6 +7946,58 @@ function fail(msg) {
 	process.exit(1);
 }
 //#endregion
+//#region src/permission.ts
+const CLI_RULE = "Bash(cyberlegion *)";
+const COVERING = /^Bash(?:\((?:\*|cyberlegion(?: \*|:\*|\*))\))?$/;
+/** Claude Code's user settings file: `$CLAUDE_CONFIG_DIR/settings.json`, else `~/.claude/settings.json`. */
+function claudeUserSettingsFile(env = process.env) {
+	return join(env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude"), "settings.json");
+}
+function readSettings(file) {
+	if (!existsSync(file)) return {
+		settings: {},
+		allow: []
+	};
+	let settings;
+	try {
+		settings = JSON.parse(readFileSync(file, "utf8"));
+	} catch {
+		throw new Error(`cannot parse Claude Code settings ${file} — fix it by hand, then re-run`);
+	}
+	if (typeof settings !== "object" || settings === null || Array.isArray(settings)) throw new Error(`Claude Code settings ${file} is not a JSON object — fix it by hand, then re-run`);
+	const { permissions } = settings;
+	const allow = permissions?.allow ?? [];
+	if (permissions !== void 0 && (typeof permissions !== "object" || permissions === null) || !Array.isArray(allow)) throw new Error(`Claude Code settings ${file} has a malformed permissions.allow — fix it by hand, then re-run`);
+	return {
+		settings,
+		allow
+	};
+}
+const covers = (allow) => allow.some((rule) => typeof rule === "string" && COVERING.test(rule));
+/** Whether the settings file's allow list already lets `cyberlegion` subcommands run. */
+function permissionRuleState(file) {
+	try {
+		return covers(readSettings(file).allow) ? "present" : "missing";
+	} catch {
+		return "unreadable";
+	}
+}
+/**
+* Add the CLI rule to the settings file's allow list, merged in after every existing entry. A
+* covering rule already there is a no-op; a file that cannot be read as settings is never rewritten.
+*/
+function addPermissionRule(file) {
+	const { settings, allow } = readSettings(file);
+	if (covers(allow)) return "present";
+	settings.permissions = {
+		...settings.permissions ?? {},
+		allow: [...allow, CLI_RULE]
+	};
+	mkdirSync(dirname(file), { recursive: true });
+	writeFileSync(file, `${JSON.stringify(settings, null, 2)}\n`);
+	return "added";
+}
+//#endregion
 //#region src/project.ts
 /**
 * The canonical git common dir for `dir`, or undefined outside a repository. The common dir is the
@@ -8794,8 +8932,11 @@ function stopUnit(ctx, ref) {
 /**
 * Give a unit a fresh runtime and keep the unit: stop a still-running session (the same verified stop
 * as `stopUnit`), open a new session at the unit's cwd with the launch it was spawned with, bind the
-* record to the new pane, and ring it to read its brief — a rebrief, since a new session starts with
-* an empty context. Every refusal runs before anything is torn down.
+* record to the new pane, and ring it. When the record carries the harness's conversation id and the
+* harness can resume by id, the session resumes that conversation and is rung to continue, with the
+* plain launch as a shell fallback should the harness reject the id; otherwise (or with `fresh`) it
+* starts empty and is rung to read its brief — a rebrief. Every refusal runs before anything is torn
+* down.
 *
 * The unit is recorded `stopped` before the open, so a restart interrupted between the two leaves an
 * ordinary stopped unit and a rerun recovers it; nothing needs a separate repair path.
@@ -8817,6 +8958,7 @@ async function restartUnit(ctx, ref, options = {}) {
 	const env = ctx.env ?? process.env;
 	const exec = ctx.exec ?? realExec;
 	const launch = stopped.launch ?? LAUNCH_MAP[harness];
+	const resume = stopped.conversation && !options.fresh ? resumeLaunch(harness, launch, stopped.conversation) : void 0;
 	const at = stopped.worktree ? "workspace" : "tab";
 	let target;
 	let adapter;
@@ -8829,7 +8971,10 @@ async function restartUnit(ctx, ref, options = {}) {
 		}) } : {};
 		target = adapter.open(exec, {
 			cwd: stopped.cwd,
-			launch: composeLaunchLine(ctx, adapter.name, rec.id, launch),
+			launch: resume ? composeLaunchLine(ctx, adapter.name, rec.id, resume, {
+				bindSelf: true,
+				fallback: launch
+			}) : composeLaunchLine(ctx, adapter.name, rec.id, launch, { bindSelf: true }),
 			at,
 			from: callerPane(adapter, normalizeMuxEnv(env)),
 			...label
@@ -8853,13 +8998,15 @@ async function restartUnit(ctx, ref, options = {}) {
 	const wake = await wakeSpawn(() => adapter, exec, {
 		target,
 		briefPath: briefPath ?? "",
-		noWake: options.noWake || !briefPath
+		noWake: options.noWake || !briefPath,
+		resumed: !!resume
 	}, options.nudgeOpts);
 	return {
 		agent: bound,
 		...previousPane ? { previousPane } : {},
 		pane: target.id,
 		launch,
+		resumed: !!resume,
 		rung: wake.rung,
 		...wake.warning ? { warning: wake.warning } : {}
 	};
@@ -8957,6 +9104,29 @@ function showUnit(ctx, ref) {
 		controls: controlsFor(ctx, rec, liveness)
 	};
 }
+/**
+* Record the harness's conversation id on the calling unit, from the JSON its SessionStart hook hands
+* `mail hook` on stdin (`session_id`, which Claude Code and Codex both send). The hook fires on every
+* session start in the pane — a fresh start, a resume, a `/clear` — so the record follows the
+* conversation the pane is in now. Best-effort and silent: an unparseable input, no id, or a caller
+* that is not a unit records nothing and never fails the harness hook.
+*/
+function recordConversation(ctx, hookInput) {
+	let id;
+	try {
+		id = JSON.parse(hookInput)?.session_id;
+	} catch {
+		return;
+	}
+	if (typeof id !== "string" || id === "") return;
+	const meId = resolveSelfId(ctx);
+	const rec = meId ? loadAgent(ctx.store, meId) : void 0;
+	if (!rec || rec.kind === "standing" || rec.kind === "service" || rec.conversation === id) return;
+	saveAgent(ctx.store, {
+		...rec,
+		conversation: id
+	});
+}
 //#endregion
 //#region src/wake/await.ts
 /** Internal poll interval — not user-facing (the round-trip cost of one `mail await` cycle). */
@@ -9249,7 +9419,7 @@ function warnEffortNotApplied(spawnInput) {
 }
 /** The launch options `unit spawn` and `service start` share. */
 function withSpawnOptions(cmd) {
-	return withGlobals(cmd).option("--harness <h>", "claude | cursor | codex (required unless --agent/--agent-file resolves one)").option("--agent <name>", "resolve an agent def (.agents/agents/<name>.md) for harness/model/effort/instructions").option("--agent-file <path>", "read an exact agent def file instead of resolving by name").option("--model <name>", "model for this launch only (flag > agent def > harness default)").option("--effort <level>", "effort for this launch only (flag > agent def > harness default)").option("--task <text>", "brief text, or - for stdin").option("--brief-file <path>", "read the brief from a file").option("--handle <name>", "handle for the new peer").option("--branch <name>", "branch for the new worktree (default cyberlegion/unit-<id>)").option("--worktree-path <path>", "where to check out the new worktree").option("--cwd <path>", "spawn the session in an existing directory; create no worktree (mutually exclusive with --branch/--worktree-path)").addOption(new Option("--at <placement>", "where to open the new session (default: new-worktree → workspace, --cwd → tab)").choices([
+	return withGlobals(cmd).option("--harness <h>", "claude | cursor | codex (required unless --agent/--agent-file resolves one)").option("--agent <name>", "resolve an agent def (.agents/agents/<name>.md) for harness/model/effort/instructions").option("--agent-file <path>", "read an exact agent def file instead of resolving by name").option("--model <name>", "model for this launch only (flag > agent def > harness default)").option("--effort <level>", "effort for this launch only (flag > agent def > harness default)").option("--task <text>", "brief text, or - for stdin").option("--brief-file <path>", "read the brief from a file").option("--handle <name>", "handle for the new peer").option("--branch <name>", "branch for the new worktree (default cyberlegion/unit-<id>)").option("--worktree-path <path>", "where to check out the new worktree").option("-C, --repo <path>", "create the worktree from the git repository containing <path>, not the current directory's").option("--cwd <path>", "spawn the session in an existing directory; create no worktree (mutually exclusive with --branch/--worktree-path/--repo)").addOption(new Option("--at <placement>", "where to open the new session (default: new-worktree → workspace, --cwd → tab)").choices([
 		"pane:right",
 		"pane:down",
 		"tab",
@@ -9349,15 +9519,19 @@ withGlobals(unit.command("stop")).description("end a unit's session and keep the
 	});
 	if (!res.alreadyStopped) nextStep(`cyberlegion unit restart ${res.agent.handle}`);
 });
-withGlobals(unit.command("restart")).description("give a unit a fresh session and keep the unit — stops a running session, relaunches it, and rebriefs it").argument("<ref>", "unit id, handle, or worktree branch/CR ref").option("--no-wake", "do not ring the new session to read its brief (the caller briefs it by mail)").action(async (ref, opts) => {
+withGlobals(unit.command("restart")).description("give a unit a new session and keep the unit — stops a running session, relaunches it resuming the harness's recorded conversation where it can, and otherwise rebriefs it").argument("<ref>", "unit id, handle, or worktree branch/CR ref").option("--no-wake", "do not ring the new session to read its brief (the caller briefs it by mail)").option("--fresh", "start an empty session and rebrief it, even when the unit's conversation could be resumed").action(async (ref, opts) => {
 	const ctx = ctxOf(opts);
 	touch(ctx);
-	const res = await restartUnit(ctx, ref, { noWake: opts.wake === false });
+	const res = await restartUnit(ctx, ref, {
+		noWake: opts.wake === false,
+		fresh: opts.fresh === true
+	});
 	emit(formatOf(opts), {
 		toon: toonObject({
 			restarted: res.agent.id,
 			previous: res.previousPane ?? "-",
 			pane: res.pane,
+			resumed: res.resumed,
 			rung: res.rung
 		}),
 		json: res
@@ -9841,6 +10015,9 @@ withGlobals(mail.command("watch")).description("stream new matching mail as it a
 withGlobals(mail.command("hook")).description("emit the harness hook injection payload (raw JSON on stdout, not TOON)").option("--event <event>", "SessionStart", "SessionStart").action((opts) => {
 	const ctx = ctxOf(opts);
 	touch(ctx);
+	if (!process.stdin.isTTY) try {
+		recordConversation(ctx, readFileSync(0, "utf8"));
+	} catch {}
 	const payload = injectInbox(ctx, opts.event);
 	if (payload) console.log(JSON.stringify(payload));
 });
@@ -9935,30 +10112,33 @@ withGlobals(agent.command("path")).description("print the resolved def file path
 		json: { path: def.path }
 	});
 });
+const ALLOW_CLI_HINT = `cyberlegion init --allow-cli to add ${CLI_RULE} to Claude Code's permissions.allow, so units can mail their results back`;
 const mux = program.command("mux").description("the unit-agnostic pane layer — multiplexer detection and diagnostics");
 withGlobals(mux.command("doctor")).description("probe harness, multiplexer (ancestry-discovered), hub root, and self-id").action((opts) => {
 	const ctx = ctxOf(opts);
 	const harness = detectHarness(void 0, ctx) ?? "unknown";
 	const probe = probeMultiplexer(ctx.exec ?? realExec, normalizeMuxEnv(ctx.env ?? process.env));
 	const selfId = resolveSelfId(ctx) ?? "-";
+	const permissionRule = harness === "claude" ? permissionRuleState(claudeUserSettingsFile(ctx.env ?? process.env)) : "n/a";
+	const report = {
+		harness,
+		mux: probe.mux,
+		pane: probe.pane,
+		via: probe.via,
+		hubRoot: ctx.store.root,
+		selfId
+	};
 	emit(formatOf(opts), {
 		toon: toonObject({
-			harness,
-			mux: probe.mux,
-			pane: probe.pane,
-			via: probe.via,
-			hubRoot: ctx.store.root,
-			selfId
+			...report,
+			permissionRule
 		}),
 		json: {
-			harness,
-			mux: probe.mux,
-			pane: probe.pane,
-			via: probe.via,
-			hubRoot: ctx.store.root,
-			selfId
+			...report,
+			permissionRule
 		}
 	});
+	if (permissionRule === "missing") nextStep(ALLOW_CLI_HINT);
 	if (probe.mux !== "none") nextStep(`export CYBER_MUX=${probe.mux}${probe.pane ? ` CYBER_MUX_PANE=${probe.pane}` : ""} — pin the fast-path, skip ancestry discovery on later calls`);
 });
 withGlobals(mux.command("mode")).description("report the detected session-backend mode").action((opts) => {
@@ -10009,7 +10189,7 @@ withGlobals(program.command("admin").description("hub-state maintenance").comman
 		json: res
 	});
 });
-withGlobals(program.command("init")).description("resolve this session harness, set up the Legion surfacing hook, and advise owner binding").option("--agent <h>", "claude | cursor | codex (else auto-detected)").option("--dir <path>", "project dir to write config into", process.cwd()).option("--pin <version>", "version the npx fallback of the cursor hook fetches (e.g. the bundled plugin version)").action((opts) => {
+withGlobals(program.command("init")).description("resolve this session harness, set up the Legion surfacing hook, and advise owner binding").option("--agent <h>", "claude | cursor | codex (else auto-detected)").option("--dir <path>", "project dir to write config into", process.cwd()).option("--pin <version>", "version the npx fallback of the cursor hook fetches (e.g. the bundled plugin version)").option("--allow-cli", `add ${CLI_RULE} to Claude Code's user permissions.allow (claude only)`).action((opts) => {
 	const ctx = ctxOf(opts);
 	let harness;
 	try {
@@ -10019,6 +10199,16 @@ withGlobals(program.command("init")).description("resolve this session harness,
 	} catch (err) {
 		fail(err instanceof Error ? err.message : String(err));
 	}
+	if (opts.allowCli && harness !== "claude") fail(`--allow-cli applies to claude only, not ${harness}`);
+	let permissionRule;
+	if (harness === "claude") {
+		const settingsFile = claudeUserSettingsFile(ctx.env ?? process.env);
+		try {
+			permissionRule = opts.allowCli ? addPermissionRule(settingsFile) : permissionRuleState(settingsFile);
+		} catch (err) {
+			fail(err instanceof Error ? err.message : String(err));
+		}
+	}
 	let results;
 	try {
 		results = install(harness, opts.dir, opts.pin);
@@ -10039,12 +10229,14 @@ withGlobals(program.command("init")).description("resolve this session harness,
 				key: "file",
 				get: (r) => r.file
 			}
-		], `harness ${harness}, ${results.length} hooks`),
+		], `harness ${harness}, ${results.length} hooks${permissionRule ? `, permission rule ${permissionRule}` : ""}`),
 		json: {
 			harness,
-			hooks: results
+			hooks: results,
+			...permissionRule && { permissionRule }
 		}
 	});
+	if (permissionRule === "missing") nextStep(ALLOW_CLI_HINT);
 	if (!listAgents(ctx.store).some((a) => a.kind === "standing")) {
 		nextStep("cyberlegion unit register --standing --handle <name> to mint the durable owner inbox");
 		nextStep("cyberlegion attach to bind this pane as the owner live presence");

package/dist/index.d.mts

@@ -62,6 +62,10 @@ interface AgentRecord {
    * mux env prefix not) — what `unit restart` relaunches the unit with. Absent on a record that
    * predates it or that `spawn` did not write; restart then falls back to the harness default. */
   launch?: string;
+  /** The harness's own conversation (session) id, as its SessionStart hook last reported it from this
+   * unit's pane (`mail hook`) — what `unit restart` resumes. Absent until the hook has fired, and on a
+   * harness whose hook never runs; restart then rebriefs a fresh session. */
+  conversation?: string;
   spawnedBy?: string;
   /** Absent ⇒ session (backward compat, no migration). 'standing' = a session-independent,
    * prune-exempt owner inbox minted by `unit register --standing`. 'service' = a project service's
@@ -719,6 +723,10 @@ interface SpawnInput {
   /** Spawn into this existing directory instead — creates no worktree. Mutually exclusive with
    * `branch`/`worktreePath` (those create a worktree; this reuses one). */
   cwd?: string;
+  /** Create the worktree from the repository containing this path rather than the caller's cwd —
+   * so a caller spawns for another repository without a `cd` chained in front of the command.
+   * Mutually exclusive with `cwd` (that one creates no worktree to place). */
+  repo?: string;
   /** Placement relative to the caller; defaults to 'tab'. */
   at?: MuxPlacement;
 }

package/dist/index.mjs

@@ -615,6 +615,9 @@ const KILL_LINE = "";
 *   throws without sending. A multi-row draft cannot be typed back exactly: a scrape cannot tell a
 *   wrapped row from a newline, and a newline typed back would submit it.
 *
+* Text `ownText` recognizes is the caller's own, not a draft: it is cleared at once, whatever rows it
+* wraps onto, `send` runs, and nothing is typed back.
+*
 * Text the clear leaves in place was never a draft — an idle placeholder this reader does not know —
 * so `send` runs and nothing is typed back.
 */
@@ -631,10 +634,11 @@ async function withDraftGuard(adapter, exec, target, send, options = {}) {
 			return { kind: "unknown" };
 		}
 	};
+	const isOwn = (s) => s.kind === "draft" && options.ownText?.(s.text) === true;
 	let state = read();
 	const start = now();
 	let changedAt = start;
-	while (state.kind === "draft" && now() - changedAt < idleMs) {
+	while (state.kind === "draft" && !isOwn(state) && now() - changedAt < idleMs) {
 		if (now() - start + pollMs > maxWaitMs) throw new Error(`pane ${target.id} holds a draft the user is still editing — gave up after ${maxWaitMs / 1e3}s without typing`);
 		await sleep(pollMs);
 		const next = read();
@@ -642,12 +646,13 @@ async function withDraftGuard(adapter, exec, target, send, options = {}) {
 		state = next;
 	}
 	if (state.kind !== "draft") return send();
+	if (isOwn(state)) {
+		await clearLine(adapter, exec, target, sleep);
+		return send();
+	}
 	if (state.rows > 1) throw new Error(`pane ${target.id} holds an idle draft spanning ${state.rows} rows, which cannot be typed back exactly — left it untouched`);
 	const draft = state.text;
-	adapter.sendText(exec, target, END_OF_LINE);
-	await sleep(KEY_SETTLE_MS);
-	adapter.sendText(exec, target, KILL_LINE);
-	await sleep(KEY_SETTLE_MS);
+	await clearLine(adapter, exec, target, sleep);
 	const after = read();
 	if (after.kind === "draft" && after.text === draft) return send();
 	try {
@@ -657,6 +662,12 @@ async function withDraftGuard(adapter, exec, target, send, options = {}) {
 		adapter.sendText(exec, target, draft);
 	}
 }
+async function clearLine(adapter, exec, target, sleep) {
+	adapter.sendText(exec, target, END_OF_LINE);
+	await sleep(KEY_SETTLE_MS);
+	adapter.sendText(exec, target, KILL_LINE);
+	await sleep(KEY_SETTLE_MS);
+}
 //#endregion
 //#region src/console/ring.ts
 const DEFAULT_ATTEMPTS = 10;
@@ -710,8 +721,6 @@ async function ringTurn(adapter, exec, target, message, opts = {}) {
 	}
 	throw new Error(`nudge failed: peer at pane ${target.id} never took the turn — input still staged after ${attempts} re-submit attempts`);
 }
-//#endregion
-//#region src/console/doorbell.ts
 /**
 * The first-turn doorbell `unit spawn` delivers to a freshly-opened paned peer — the instruction
 * itself, not a notification that context is already populated. It names the brief's **file path**
@@ -725,6 +734,28 @@ async function ringTurn(adapter, exec, target, message, opts = {}) {
 function spawnDoorbell(briefPath) {
 	return `Read your brief at ${briefPath}, then begin work.`;
 }
+const SPAWN_DOORBELL = /^Readyourbriefat.+,thenbeginwork\.$/;
+const RESUME_DOORBELL = /^Yoursessionwasrestartedwithitsconversationresumed—continueyourwork\.Ifyouhavenoearlierconversation,readyourbriefat.+,thenbeginwork\.$/;
+/**
+* Whether `text`, read out of a peer's input box, is a ring cyberlegion typed — the delivery doorbell,
+* a spawn or resume doorbell, or `message`, the one about to be rung — rather than a human's draft. A harness
+* can take a ring and put its text back in the box (cursor-agent with a rejected login). Whitespace is
+* ignored, since the box wraps the text onto rows wherever it likes.
+*/
+function isRingText(text, message) {
+	const squeeze = (s) => s.replace(/\s+/g, "");
+	const box = squeeze(text);
+	if (box === "") return false;
+	return box === squeeze("You have unread mail — check your inbox.") || SPAWN_DOORBELL.test(box) || RESUME_DOORBELL.test(box) || message !== void 0 && box === squeeze(message);
+}
+/**
+* The first-turn instruction for a restarted session that resumed its conversation. The resume can
+* fall back to a fresh session (the harness no longer has the conversation), and the ring cannot tell
+* which one took the turn, so it names the brief for a session that finds no earlier conversation.
+*/
+function resumeDoorbell(briefPath) {
+	return `Your session was restarted with its conversation resumed — continue your work. If you have no earlier conversation, read your brief at ${briefPath}, then begin work.`;
+}
 /**
 * A freshly-launched harness cold-boots slower than an already-running peer, so the spawn first-turn
 * ring gets a wider retry budget than a plain `mail send` doorbell (nudge's own 10 × 400ms): flush the
@@ -755,9 +786,11 @@ async function wakeSpawn(getAdapter, exec, input, nudgeOpts = SPAWN_NUDGE_OPTS,
 	if (input.noWake) return { rung: false };
 	try {
 		const adapter = getAdapter();
-		await withDraftGuard(adapter, exec, input.target, () => ringTurn(adapter, exec, input.target, spawnDoorbell(input.briefPath), nudgeOpts), {
+		const doorbell = (input.resumed ? resumeDoorbell : spawnDoorbell)(input.briefPath);
+		await withDraftGuard(adapter, exec, input.target, () => ringTurn(adapter, exec, input.target, doorbell, nudgeOpts), {
 			...guardOpts,
-			harness: input.harness
+			harness: input.harness,
+			ownText: (text) => isRingText(text)
 		});
 		return {
 			rung: true,
@@ -1055,6 +1088,20 @@ const LAUNCH_MAP = {
 	cursor: "cursor-agent",
 	codex: "codex"
 };
+/** The primary checkout of the repository containing `repo`, asked of git from inside it (`git -C`)
+* rather than from the process cwd. */
+function primaryRootOfRepo(exec, repo) {
+	const dir = resolve(repo);
+	try {
+		return resolvePrimaryRoot$1((cmd, args) => exec(cmd, cmd === "git" ? [
+			"-C",
+			dir,
+			...args
+		] : args));
+	} catch {
+		throw new Error(`--repo ${repo} is not inside a git repository`);
+	}
+}
 /**
 * Launch a new peer session as a genuine sibling unit: create a real git worktree distinct from
 * the primary checkout (refuse the primary checkout), open a session backend (tmux or herdr) with
@@ -1078,9 +1125,9 @@ function spawn(ctx, input) {
 	if (!harness || !(harness in LAUNCH_MAP)) throw new Error(`spawn needs a --harness in the launch map (${Object.keys(LAUNCH_MAP).join(" | ")})`);
 	const brief = resolveBrief(input);
 	if (brief == null) throw new Error("spawn needs a brief — pass --task <text>, --task - (stdin), or --brief-file <path>");
-	if (input.cwd && (input.branch || input.worktreePath)) throw new Error("--cwd cannot combine with the worktree-creating flags --branch/--worktree-path");
+	if (input.cwd && (input.branch || input.worktreePath || input.repo)) throw new Error("--cwd cannot combine with the worktree-creating flags --branch/--worktree-path/--repo");
 	const id = randomId();
-	const primaryRoot = resolvePrimaryRoot$1(exec);
+	const primaryRoot = input.repo ? primaryRootOfRepo(exec, input.repo) : resolvePrimaryRoot$1(exec);
 	const launch = input.command ?? LAUNCH_MAP[harness];
 	const launchLine = () => composeLaunchLine(ctx, sessionAdapter.name, id, launch);
 	const from = callerPane(sessionAdapter, normalizedEnv);
@@ -1260,10 +1307,25 @@ function labelFor(at, input, brief, id) {
 * supplied `ctx.self`), the multiplexer env prefix, then the harness launch command. Writes the shim
 * as a side effect, so call it only past every refusal, right before the session opens. Shared by
 * `spawn` and `unit restart` so a restarted unit boots exactly as a spawned one does.
+*
+* `bindSelf` has the new pane run `unit rebind <id>` through the shim before the harness starts, so
+* the session binds itself to the unit even when the caller dies before its own bind write. It needs
+* the shim, so a context with no recorded invocation gets no bind step.
+*/
+function composeLaunchLine(ctx, muxName, id, launch, options = {}) {
+	const shim = ctx.self ? writeSelfShim(paths.dataDir(ctx.store.root, id), ctx.self) : void 0;
+	const bind = shim && options.bindSelf ? `${shellQuote$1(shim)} unit rebind ${shellQuote$1(id)} --space ${shellQuote$1(ctx.store.root)} >/dev/null 2>&1; ` : "";
+	const prefix = `${shim ? shimEnvPrefix(shim) : ""}${muxEnvPrefix(muxName)}`;
+	return `${bind}${prefix}${launch}${options.fallback ? ` || ${prefix}${options.fallback}` : ""}`;
+}
+/**
+* Put the shim's directory first on PATH, so a brief's bare `cyberlegion` runs it, and name the shim
+* itself in `$CYBERLEGION_CLI`. The plugin's hook runs outside that PATH lookup (and a PATH lookup
+* cannot tell this shim from a stale global install), so it reads the variable instead: set only
+* here, it marks a spawned session and names the CLI that spawned it.
 */
-function composeLaunchLine(ctx, muxName, id, launch) {
-	const shimDir = ctx.self ? writeSelfShim(paths.dataDir(ctx.store.root, id), ctx.self) : void 0;
-	return `${shimDir ? `PATH=${shellQuote$1(shimDir)}:"$PATH" ` : ""}${muxEnvPrefix(muxName)}${launch}`;
+function shimEnvPrefix(shim) {
+	return `PATH=${shellQuote$1(dirname(shim))}:"$PATH" CYBERLEGION_CLI=${shellQuote$1(shim)} `;
 }
 /**
 * The env prefix typed ahead of the launch command so the spawned peer inherits the caller's
@@ -1279,7 +1341,7 @@ function muxEnvPrefix(muxName) {
 }
 /**
 * Write `<dataDir>/bin/cyberlegion`, a POSIX shim that execs `self` with the caller's arguments,
-* and return its directory. A spawned session gets that directory first on its PATH, so the
+* and return its path. A spawned session gets that directory first on its PATH, so the
 * `cyberlegion` a brief tells it to run is the install that spawned it: nothing is resolved from
 * the registry or the session's own PATH at report time.
 */
@@ -1289,7 +1351,7 @@ function writeSelfShim(dataDir, self) {
 	const shim = join(dir, "cyberlegion");
 	writeFileSync(shim, `#!/bin/sh\nexec ${self.map(shellQuote$1).join(" ")} "$@"\n`);
 	chmodSync(shim, 493);
-	return dir;
+	return shim;
 }
 /** Single-quote `s` for a POSIX shell, so any path survives word splitting and expansion. */
 function shellQuote$1(s) {

package/hooks/hooks.json

@@ -5,7 +5,7 @@
 				"hooks": [
 					{
 						"type": "command",
-						"command": "node \"${CLAUDE_PLUGIN_ROOT}/bin/cyberlegion.mjs\" mail hook --event SessionStart"
+						"command": "if [ -x \"$CYBERLEGION_CLI\" ]; then \"$CYBERLEGION_CLI\" mail hook --event SessionStart; else node \"${CLAUDE_PLUGIN_ROOT}/bin/cyberlegion.mjs\" mail hook --event SessionStart; fi"
 					}
 				]
 			}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cyberlegion",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Harness-agnostic agent session spawning and messaging over the filesystem",
   "keywords": [
     "agent",

package/plugin.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
 	"name": "cyberlegion",
-	"version": "1.2.0",
+	"version": "1.3.0",
 	"description": "Agent session spawning, messaging, and dispatch — the Legion and its Legate.",
 	"author": {
 		"name": "unional"

package/readme.md

@@ -161,6 +161,11 @@ launcher cannot be resolved, a skill names one fallback pinned to the version th
 `npx -y cyberlegion@<version>`. `pnpm version` rewrites those pins and `.plugin/pins.json` at every
 release, and the test suite fails on a stale one.
 
+Claude Code puts the plugin's `bin/` on the Bash tool's PATH, and `bin/cyberlegion` forwards to
+`bin/cyberlegion.mjs`, so a bare `cyberlegion …` runs the shipped CLI in any Claude Code session with
+no global install. claude.ai and Cowork, including plugins distributed through claude.ai organization
+settings, refuse a plugin with a top-level `bin/`, so the plugin does not install there.
+
 ## License
 
 MIT

package/skills/dispatch-governance/SKILL.md

@@ -17,7 +17,7 @@ satisfies verdict schema `V`.
 > **Running the CLI.** Every `node scripts/cyberlegion.mjs …` command below runs the `cyberlegion` CLI
 > this plugin ships. The path is relative to this skill's own directory, not the working directory.
 > If you cannot resolve it, run the published CLI of the version that shipped this skill instead,
-> with the same arguments: `npx -y cyberlegion@1.2.0`.
+> with the same arguments: `npx -y cyberlegion@1.3.0`.
 
 ## 1. Resolve the agent definition
 

package/skills/dispatch-governance/scripts/cyberlegion.mjs

@@ -11,7 +11,7 @@ import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 
-const FALLBACK = 'npx -y cyberlegion@1.2.0'
+const FALLBACK = 'npx -y cyberlegion@1.3.0'
 const bin = new URL('../../../bin/cyberlegion.mjs', import.meta.url)
 
 if (existsSync(fileURLToPath(bin))) {

package/skills/init-cyberlegion/README.md

@@ -2,13 +2,14 @@
 
 The onboarding front door to the Legion — walks a session through getting `cyberlegion` working in
 this repo: probe the environment, register the surfacing hook, and (root session only, only on an
-explicit yes) bind this pane as the durable `legate` owner inbox.
+explicit yes) allow the `cyberlegion` CLI in Claude Code's permissions and bind this pane as the
+durable `legate` owner inbox.
 
 User-facing. Triggers on "set up cyberlegion", "onboard the legion", "register the cyberlegion
 surfacing hook", "make this pane my main legion inbox", "get cyberlegion working in this repo". Wraps
-`cyberlegion mux doctor` / `init` / `unit register --standing` / `attach` — every mechanic is a
+`cyberlegion mux doctor` / `init [--allow-cli]` / `unit register --standing` / `attach` — every mechanic is a
 CLI call, no filesystem or hub state touched directly.
 
 Distinct from `legate` (spawn/mail/dispatch a peer) and `manage-inbox` (read/ack owner mail once
-bound). See `SKILL.md` for the full flow (probe → register hook → detect root vs spawned →
-consent-gated bind).
+bound). See `SKILL.md` for the full flow (probe → consent-gated permission rule + register hook →
+detect root vs spawned → consent-gated bind).

package/skills/init-cyberlegion/SKILL.md

@@ -1,13 +1,14 @@
 ---
 name: init-cyberlegion
-description: "Use this skill to set up or onboard cyberlegion in this session or repo — probe the environment, register the mail-surfacing hook, and (in a root session, on your yes) bind this pane as the durable legate owner inbox. Triggers: 'set up cyberlegion', 'onboard the legion', 'register the cyberlegion surfacing hook', 'make this pane my main legion inbox', 'get cyberlegion working in this repo'. Not for spawning/messaging/dispatching a peer (that is legate), reading or acking owner mail (that is manage-inbox), or unrelated init like a git repo, npm package, or commit discipline."
+description: "Use this skill to set up or onboard cyberlegion in this session or repo — probe the environment, register the mail-surfacing hook, (in a root session, on your yes) allow the cyberlegion CLI in Claude Code's permissions, and bind this pane as the durable legate owner inbox. Triggers: 'set up cyberlegion', 'onboard the legion', 'register the cyberlegion surfacing hook', 'make this pane my main legion inbox', 'get cyberlegion working in this repo'. Not for spawning/messaging/dispatching a peer (that is legate), reading or acking owner mail (that is manage-inbox), or unrelated init like a git repo, npm package, or commit discipline."
 ---
 
 # init-cyberlegion
 
 The onboarding front door to the Legion — a thin, user-invocable wrapper that walks a session through
 getting `cyberlegion` working in this repo: probe the environment, register the surfacing hook, and
-(only in a root session, only on an explicit yes) bind this pane as the durable `legate` owner inbox.
+(only in a root session, only on an explicit yes) allow the `cyberlegion` CLI in Claude Code's
+permissions and bind this pane as the durable `legate` owner inbox.
 It is a **thin wrapper**: every mechanic is a `cyberlegion` CLI call. The skill holds the *conversation
 and the judgment* — is this a root session? should we ask to bind? what does the environment look
 like? — the CLI holds all the *mechanism*.
@@ -37,21 +38,54 @@ node scripts/cyberlegion.mjs mux doctor
 ```
 
 Run this **before** touching the hook or any identity. It reports `harness`, `mux`, `pane`,
-`hubRoot`, and `selfId` — read it to learn the environment (is there a multiplexer? a pane?) and to
-detect root vs spawned (see step 3). Narrate a short, grounded summary of what it found — do not
-invent facts the probe did not report.
+`hubRoot`, `selfId`, and `permissionRule` — read it to learn the environment (is there a
+multiplexer? a pane? does Claude Code allow the CLI?) and to detect root vs spawned (see step 3).
+Narrate a short, grounded summary of what it found, including the permission rule (e.g. "permission
+rule: missing") — do not invent facts the probe did not report.
 
-### 2. Register the surfacing hook
+`permissionRule` is whether Claude Code's user settings carry a `permissions.allow` rule covering
+`cyberlegion`: `present`, `missing`, `unreadable`, or `n/a` (not Claude Code). Without it, Claude
+Code's auto-mode classifier can deny a unit's `cyberlegion mail send` as *External System Writes*,
+so a unit that finished its work cannot report back. Step 2 handles it.
+
+### 2. Register the surfacing hook (and, on a yes, allow the CLI)
 
 ```bash
 node scripts/cyberlegion.mjs init --pin <version>
 ```
 
+**The permission rule — ask first, never silent.** When the probe reported `permissionRule: missing`
+in a **root** session with a broader onboarding intent (see step 3 for how root is derived), ask
+before running `init`, e.g.:
+
+> "Claude Code has no permission rule for `cyberlegion`, so its auto-mode classifier can block a
+> unit's `cyberlegion mail send` and the unit's report never reaches you. Add
+> `Bash(cyberlegion *)` to `permissions.allow` in your Claude Code user settings
+> (`~/.claude/settings.json`)? It is merged into your existing list."
+
+On an explicit yes, add `--allow-cli` to the `init` call — the CLI merges the rule into the existing
+array, never replaces it, and refuses to rewrite a settings file it cannot parse:
+
+```bash
+node scripts/cyberlegion.mjs init --pin <version> --allow-cli
+```
+
+On a decline, run `init` without `--allow-cli` and say the rule stays missing. Never edit the
+settings file by hand. Do not ask, and do not pass `--allow-cli`, when:
+
+- the rule is `present` or `n/a` — nothing to do;
+- the rule is `unreadable` — tell the user the settings file could not be parsed and must be fixed
+  by hand; `--allow-cli` would refuse it;
+- this is a **spawned** unit — it never changes the user's global settings; report the rule as
+  missing in its result so the human can run this skill from a root session;
+- the request is hook-only — report the rule's state and stop (see step 3).
+
 Pass `--pin <version>` with the version resolved above so a project hook's npx fallback fetches the
 shipped version; **omit `--pin`** when the map yielded no version.
 
 Auto-detect is the default — no `--agent` flag. Pass `--agent <name>` **only** when `mux doctor` could
-not auto-detect the harness, or the user named one explicitly (it composes with `--pin`):
+not auto-detect the harness, or the user named one explicitly (it composes with `--pin` and
+`--allow-cli`):
 
 ```bash
 node scripts/cyberlegion.mjs init --pin <version> --agent <name>
@@ -60,7 +94,9 @@ node scripts/cyberlegion.mjs init --pin <version> --agent <name>
 This step is **idempotent**: if the hook is already registered, `init` reports `already present` —
 that is a clean no-op, never a duplicate registration and never an error. On Claude Code and Codex the
 plugin ships the hook itself, so `init` reports `provided by plugin` (or `removed project hook` when it
-cleared one an earlier `init` wrote); both mean the hook is set up.
+cleared one an earlier `init` wrote); both mean the hook is set up. On Claude Code its summary also
+reports `permission rule <state>` — `added` after `--allow-cli`, `present` when a covering rule was
+already there.
 
 ### 3. Detect root vs spawned — derived, never asked
 
@@ -100,10 +136,18 @@ that is expected, not a failure. Still run `unit register --standing --handle le
 **without erroring**. The root session surfaces owner mail via the `!spawnedBy` fallback instead of a
 bound pane.
 
+## Troubleshooting
+
+**A unit's `cyberlegion mail send` was denied by the auto-mode classifier** (*Permission for this
+action was denied by the Claude Code auto mode classifier. Reason: [External System Writes]*) — the
+`Bash(cyberlegion *)` permission rule is missing. Run this skill from a root session and say yes to
+the permission ask, or run `cyberlegion init --allow-cli` there.
+
 ## Boundaries
 
-- Every mechanic here is a `cyberlegion` CLI call — this skill writes no hub state and invents no
-  config format. Its only filesystem read is the plugin's own bundled `${CLAUDE_PLUGIN_ROOT}/.plugin/pins.json`
+- Every mechanic here is a `cyberlegion` CLI call — this skill writes no hub state, invents no
+  config format, and never edits Claude Code's settings by hand (the permission rule goes in only
+  through `init --allow-cli`, only on an explicit yes in a root session). Its only filesystem read is the plugin's own bundled `${CLAUDE_PLUGIN_ROOT}/.plugin/pins.json`
   version map, to resolve the CLI pin.
 - It never mints or binds an owner identity without an explicit user yes.
 - It is distinct from `legate` — sending/spawning/dispatching to a peer is `legate`'s job, not this

package/skills/init-cyberlegion/scripts/cyberlegion.mjs

@@ -11,7 +11,7 @@ import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 
-const FALLBACK = 'npx -y cyberlegion@1.2.0'
+const FALLBACK = 'npx -y cyberlegion@1.3.0'
 const bin = new URL('../../../bin/cyberlegion.mjs', import.meta.url)
 
 if (existsSync(fileURLToPath(bin))) {

package/skills/legate/SKILL.md

@@ -13,7 +13,7 @@ logic, loads no other governance, and writes no state of its own.
 > **Running the CLI.** Every `node scripts/cyberlegion.mjs …` command below runs the `cyberlegion` CLI
 > this plugin ships. The path is relative to this skill's own directory, not the working directory.
 > If you cannot resolve it, run the published CLI of the version that shipped this skill instead,
-> with the same arguments: `npx -y cyberlegion@1.2.0`.
+> with the same arguments: `npx -y cyberlegion@1.3.0`.
 
 ## Doorbell vs mailbox
 

package/skills/legate/scripts/cyberlegion.mjs

@@ -11,7 +11,7 @@ import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 
-const FALLBACK = 'npx -y cyberlegion@1.2.0'
+const FALLBACK = 'npx -y cyberlegion@1.3.0'
 const bin = new URL('../../../bin/cyberlegion.mjs', import.meta.url)
 
 if (existsSync(fileURLToPath(bin))) {

package/skills/manage-inbox/SKILL.md

@@ -13,7 +13,7 @@ the one owner mailbox from wherever they are.
 > **Running the CLI.** Every `node scripts/cyberlegion.mjs …` command below runs the `cyberlegion` CLI
 > this plugin ships. The path is relative to this skill's own directory, not the working directory.
 > If you cannot resolve it, run the published CLI of the version that shipped this skill instead,
-> with the same arguments: `npx -y cyberlegion@1.2.0`.
+> with the same arguments: `npx -y cyberlegion@1.3.0`.
 
 ## Resolve the owner handle
 

package/skills/manage-inbox/scripts/cyberlegion.mjs

@@ -11,7 +11,7 @@ import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 
-const FALLBACK = 'npx -y cyberlegion@1.2.0'
+const FALLBACK = 'npx -y cyberlegion@1.3.0'
 const bin = new URL('../../../bin/cyberlegion.mjs', import.meta.url)
 
 if (existsSync(fileURLToPath(bin))) {

package/skills/relay-governance/SKILL.md

@@ -15,7 +15,7 @@ agent (`headless-legate`, `sdd-automaton`, the cold judges) to know how *it* rep
 > **Running the CLI.** Every `node scripts/cyberlegion.mjs …` command below runs the `cyberlegion` CLI
 > this plugin ships. The path is relative to this skill's own directory, not the working directory.
 > If you cannot resolve it, run the published CLI of the version that shipped this skill instead,
-> with the same arguments: `npx -y cyberlegion@1.2.0`.
+> with the same arguments: `npx -y cyberlegion@1.3.0`.
 
 ## The one probe: who, if anyone, collects my return?
 

package/skills/relay-governance/scripts/cyberlegion.mjs

@@ -11,7 +11,7 @@ import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 
-const FALLBACK = 'npx -y cyberlegion@1.2.0'
+const FALLBACK = 'npx -y cyberlegion@1.3.0'
 const bin = new URL('../../../bin/cyberlegion.mjs', import.meta.url)
 
 if (existsSync(fileURLToPath(bin))) {

package/skills/subagent-backend-governance/SKILL.md

@@ -14,7 +14,7 @@ the unit's **role** — see *Mid-turn messaging is scoped by role*, below.
 > **Running the CLI.** Every `node scripts/cyberlegion.mjs …` command below runs the `cyberlegion` CLI
 > this plugin ships. The path is relative to this skill's own directory, not the working directory.
 > If you cannot resolve it, run the published CLI of the version that shipped this skill instead,
-> with the same arguments: `npx -y cyberlegion@1.2.0`.
+> with the same arguments: `npx -y cyberlegion@1.3.0`.
 
 ## 1. Resolve the agent def
 

package/skills/subagent-backend-governance/scripts/cyberlegion.mjs

@@ -11,7 +11,7 @@ import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 
-const FALLBACK = 'npx -y cyberlegion@1.2.0'
+const FALLBACK = 'npx -y cyberlegion@1.3.0'
 const bin = new URL('../../../bin/cyberlegion.mjs', import.meta.url)
 
 if (existsSync(fileURLToPath(bin))) {