@gajae-code/coding-agent 0.2.4 → 0.2.5

package/src/prompts/tools/cron.md

@@ -0,0 +1,25 @@
+Schedule a prompt to fire on a recurring cron schedule, or one-shot at the next match. Cron tasks let you re-run a prompt automatically on an interval — poll a deployment, babysit a PR, check back on a long-running build, or remind yourself to do something later in the session.
+
+`CronCreate` accepts a standard 5-field cron expression in your local timezone, the prompt to run, and whether the job recurs or fires once. It returns an 8-character job id you can pass to `CronDelete`. Each session can hold up to 50 scheduled tasks. Recurring tasks auto-expire 7 days after creation; one-shot tasks self-delete after firing.
+
+`CronList` enumerates every scheduled task in the session. `CronDelete` cancels a task by id.
+
+## Cron expressions
+
+`CronCreate` accepts 5-field cron: `minute hour day-of-month month day-of-week`. All fields support `*`, single values (`5`), steps (`*/15`), ranges (`1-5`), and comma lists (`1,15,30`). Day-of-week uses `0`/`7` for Sunday through `6` for Saturday. Extended syntax like `L`, `W`, `?`, or month/weekday names is not supported.
+
+| Example       | Meaning                      |
+| :------------ | :--------------------------- |
+| `*/5 * * * *` | Every 5 minutes              |
+| `0 * * * *`   | Every hour on the hour       |
+| `0 9 * * *`   | Every day at 9am local       |
+| `0 9 * * 1-5` | Weekdays at 9am local        |
+
+## Lifecycle
+
+- Tasks fire between turns, never mid-response.
+- All times are interpreted in the local timezone.
+- Recurring tasks fire with up to 30 minutes of deterministic jitter (or up to half their interval for sub-hourly tasks). One-shot tasks scheduled for `:00` or `:30` may fire up to 90 s early. Pick an off-minute if exact timing matters.
+- Closing or replacing the session clears every scheduled task.
+
+Disable the scheduler entirely via `CLAUDE_CODE_DISABLE_CRON=1`.

package/src/prompts/tools/monitor.md

@@ -0,0 +1,30 @@
+Start a background monitor that streams events from a long-running script. Each stdout line is an event — you keep working and notifications arrive in the chat. Events arrive on their own schedule and are not replies from the user, even if one lands while you're waiting for the user to answer a question.
+
+Pick by how many notifications you need:
+- **One** ("tell me when the server is ready / the build finishes") → use `bash` with `async: true`. That returns a single completion notification when the command exits.
+- **Many ongoing events** (logs, polling, file watching) → use `monitor`. The script keeps running and every new line of stdout becomes one event delivered into the conversation between turns.
+
+`monitor` uses the same permission rules as `bash`. To stop a monitor, cancel its background task via `job` with the returned `task_id`, or end the session.
+
+## When to reach for `monitor`
+
+- Tail a log file and flag errors as they appear (`tail -F server.log | grep -i error`).
+- Poll a PR or CI job and report when its status changes.
+- Watch a directory for file changes (`fswatch -r dist/`).
+- Track output from any long-running script you point it at.
+
+## Inputs
+
+- `command` (required): shell command to run as a background monitor. Each stdout line is delivered as a separate task-notification event.
+- `kind` (required): one of `"log"`, `"poll"`, `"watch"`, `"other"`. Describes the monitoring strategy so listings can surface useful categories.
+- `description` (required): short human-readable description of what is being monitored. Appears in task listings.
+- `timeout` (optional): maximum wall-clock seconds the monitor may run before automatic shutdown. Omit for the session lifetime.
+- `persistent` (optional, default `false`): keep the monitor running past the current turn. Persistent monitors survive until session end or until cancelled via `job`.
+
+## Output
+
+Returns `Monitor started · task <task_id>` plus a task entry visible via `job({op:"list"})`. Each stdout line of the monitored command becomes a `<task-notification>` event delivered between turns.
+
+## Cancellation
+
+There is no separate `monitor` kill tool. Cancel a running monitor with `job` using the returned `task_id`. Disposing the session also cancels every monitor the calling agent started.

package/src/runtime-mcp/oauth-flow.ts

@@ -11,6 +11,7 @@ import type { OAuthController, OAuthCredentials } from "@gajae-code/ai/utils/oau
 
 const DEFAULT_PORT = 3000;
 const CALLBACK_PATH = "/callback";
+const CALLBACK_BIND_HOSTNAME = "127.0.0.1";
 
 function isLoopbackHostname(hostname: string): boolean {
 	return hostname === "localhost" || hostname === "127.0.0.1";
@@ -42,7 +43,7 @@ function getUriPort(uri: URL): number {
 
 function validateRedirectConfig(config: MCPOAuthConfig, redirectUri: string | undefined): void {
 	const parsed = parseRedirectUri(redirectUri);
-	if (!parsed || parsed.protocol !== "https:" || !isLoopbackHostname(parsed.hostname)) {
+	if (parsed?.protocol !== "https:" || !isLoopbackHostname(parsed.hostname)) {
 		return;
 	}
 
@@ -63,7 +64,7 @@ function resolveCallbackPort(callbackPort: number | undefined, redirectUri: stri
 	if (callbackPort !== undefined) return callbackPort;
 
 	const parsed = parseRedirectUri(redirectUri);
-	if (!parsed || parsed.protocol !== "http:" || !isLoopbackHostname(parsed.hostname)) {
+	if (parsed?.protocol !== "http:" || !isLoopbackHostname(parsed.hostname)) {
 		return DEFAULT_PORT;
 	}
 
@@ -93,6 +94,7 @@ function resolveCallbackOptions(config: MCPOAuthConfig): OAuthCallbackFlowOption
 		preferredPort: resolveCallbackPort(config.callbackPort, redirectUri),
 		callbackPath: resolveCallbackPath(config.callbackPath, redirectUri),
 		callbackHostname: resolveCallbackHostname(redirectUri),
+		callbackBindHostname: CALLBACK_BIND_HOSTNAME,
 		redirectUri,
 	};
 }

package/src/sdk.ts

@@ -294,6 +294,8 @@ export interface CreateAgentSessionOptions {
 	agentId?: string;
 	/** Display name for the agent in IRC. Default: "main" or "sub". */
 	agentDisplayName?: string;
+	/** Optional restricted bash command prefixes for read-only role agents. */
+	bashAllowedPrefixes?: string[];
 	/** Optional shared agent registry for IRC routing. Default: AgentRegistry.global(). */
 	agentRegistry?: AgentRegistry;
 	/** Parent task ID prefix for nested artifact naming (e.g., "6-Extensions") */
@@ -1166,6 +1168,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				return agent?.state.model ?? model;
 			},
 			getAgentId: () => resolvedAgentId,
+			bashAllowedPrefixes: options.bashAllowedPrefixes,
 			getToolByName: name => session?.getToolByName(name),
 			agentRegistry,
 			getSessionSpawns: () => options.spawns ?? "*",

package/src/session/agent-session.ts

@@ -629,7 +629,11 @@ function createHandoffFileName(date = new Date()): string {
 // ============================================================================
 
 /** Tools that require user permission before execution when an ACP client is connected. */
-const PERMISSION_REQUIRED_TOOLS = new Set(["bash", "edit", "delete", "move"]);
+const PERMISSION_REQUIRED_TOOLS = new Set(["bash", "monitor", "edit", "delete", "move"]);
+
+function isShellExecutionPermissionTool(toolName: string): boolean {
+	return toolName === "bash" || toolName === "monitor";
+}
 
 /** Permission options presented to the client on each gated tool call. */
 const PERMISSION_OPTIONS: ClientBridgePermissionOption[] = [
@@ -694,7 +698,7 @@ function getPermissionIntent(
 	args: unknown,
 ): { toolName: string; title: string; paths?: string[]; cacheKey: string } | undefined {
 	const a = args && typeof args === "object" && !Array.isArray(args) ? (args as Record<string, unknown>) : {};
-	if (toolName === "bash") {
+	if (isShellExecutionPermissionTool(toolName)) {
 		const cmd = getStringProperty(a, "command")?.slice(0, 80);
 		return { toolName, title: cmd || toolName, cacheKey: toolName };
 	}
@@ -1497,7 +1501,13 @@ export class AgentSession {
 	 */
 	#cancelOwnAsyncJobs(): void {
 		if (!this.#agentId) return;
-		AsyncJobManager.instance()?.cancelAll({ ownerId: this.#agentId });
+		const manager = AsyncJobManager.instance();
+		if (!manager) return;
+		// Run owner cleanups first so cron timers (and any other owner-scoped
+		// resource cleanup) cannot register fresh jobs while we tear down the
+		// existing ones. Cleanup callbacks are error-isolated inside the manager.
+		manager.runOwnerCleanups({ ownerId: this.#agentId });
+		manager.cancelAll({ ownerId: this.#agentId });
 	}
 
 	// =========================================================================
@@ -3395,8 +3405,9 @@ export class AgentSession {
 					if (!permissionIntent) {
 						return await target.execute(toolCallId, args as never, signal, onUpdate, ctx);
 					}
+					const isShellExecutionTool = isShellExecutionPermissionTool(target.name);
 					const command =
-						target.name === "bash" && args && typeof args === "object" && !Array.isArray(args)
+						isShellExecutionTool && args && typeof args === "object" && !Array.isArray(args)
 							? getStringProperty(args as Record<string, unknown>, "command")
 							: undefined;
 					const commandContent = command
@@ -3426,7 +3437,7 @@ export class AgentSession {
 								toolCallId,
 								toolName: target.name,
 								title: permissionIntent.title,
-								...(target.name === "bash" ? { kind: "execute" } : {}),
+								...(isShellExecutionTool ? { kind: "execute" } : {}),
 								status: "pending",
 								rawInput: args,
 								...(commandContent ? { content: commandContent } : {}),

package/src/session/streaming-output.ts

@@ -58,6 +58,17 @@ export interface OutputSinkOptions {
 	onChunk?: (chunk: string) => void;
 	/** Minimum ms between onChunk calls. 0 = every chunk (default). */
 	chunkThrottleMs?: number;
+	/**
+	 * Unthrottled per-chunk callback fired *after* sanitization but *before*
+	 * any throttle gating, column capping, or head/tail bookkeeping. Used by
+	 * background-job substrate to record the complete process stream for the
+	 * Monitor tool while keeping `onChunk` cheap for UI/progress.
+	 *
+	 * Receives the sanitized chunk verbatim; never receives the column-capped
+	 * or minimized text. Implementations must be fast and side-effect-free
+	 * relative to the sink (the sink does not catch errors from this callback).
+	 */
+	onRawChunk?: (chunk: string) => void;
 }
 
 export interface TruncationResult {
@@ -672,6 +683,7 @@ export class OutputSink {
 	readonly #spillThreshold: number;
 	readonly #headLimit: number;
 	readonly #onChunk?: (chunk: string) => void;
+	readonly #onRawChunk?: (chunk: string) => void;
 	readonly #chunkThrottleMs: number;
 	readonly #maxColumns: number;
 
@@ -684,6 +696,7 @@ export class OutputSink {
 			maxColumns = 0,
 			onChunk,
 			chunkThrottleMs = 0,
+			onRawChunk,
 		} = options ?? {};
 		this.#artifactPath = artifactPath;
 		this.#artifactId = artifactId;
@@ -691,6 +704,7 @@ export class OutputSink {
 		this.#headLimit = Math.max(0, headBytes);
 		this.#maxColumns = Math.max(0, maxColumns);
 		this.#onChunk = onChunk;
+		this.#onRawChunk = onRawChunk;
 		this.#chunkThrottleMs = chunkThrottleMs;
 	}
 
@@ -701,6 +715,13 @@ export class OutputSink {
 	push(chunk: string): void {
 		chunk = sanitizeWithOptionalSixelPassthrough(chunk, sanitizeText);
 
+		// Unthrottled raw-chunk hook fires before any throttle/cap gating so
+		// downstream consumers (e.g. AsyncJobManager.appendOutput) can record
+		// the complete process stream while UI/progress callbacks remain throttled.
+		if (this.#onRawChunk && chunk.length > 0) {
+			this.#onRawChunk(chunk);
+		}
+
 		// Throttled onChunk: only call the callback when enough time has passed.
 		// Live preview gets the raw (pre-cap) chunk so the TUI never lags behind
 		// what reached the sink — the column cap is for the persisted LLM view.

package/src/skill-state/active-state.ts

@@ -327,11 +327,33 @@ async function readRawActiveStateForHandoff(filePath: string, strict: boolean):
 }
 
 function rawActiveEntries(state: SkillActiveState | null): SkillActiveEntry[] {
-	if (!state || !Array.isArray(state.active_skills)) return [];
+	if (!state) return [];
 	const out: SkillActiveEntry[] = [];
-	for (const candidate of state.active_skills) {
-		const normalized = normalizeEntry(candidate);
-		if (normalized) out.push(normalized);
+	if (Array.isArray(state.active_skills)) {
+		for (const candidate of state.active_skills) {
+			const normalized = normalizeEntry(candidate);
+			if (normalized) out.push(normalized);
+		}
+	}
+	// Legacy top-level fallback: pre-`active_skills` state files persisted a single
+	// active workflow as top-level `{ active: true, skill, phase, … }` with no
+	// `active_skills` array. `normalizeSkillActiveState` still synthesizes that row,
+	// so the raw read used by the HUD, mutation guard, and caller inference must do
+	// the same or it would treat a legacy active workflow as absent.
+	if (out.length === 0 && state.active === true) {
+		const skill = safeString(state.skill).trim();
+		if (skill) {
+			out.push({
+				skill,
+				phase: safeString(state.phase).trim() || undefined,
+				active: true,
+				activated_at: safeString(state.activated_at).trim() || undefined,
+				updated_at: safeString(state.updated_at).trim() || undefined,
+				session_id: safeString(state.session_id).trim() || undefined,
+				thread_id: safeString(state.thread_id).trim() || undefined,
+				turn_id: safeString(state.turn_id).trim() || undefined,
+			});
+		}
 	}
 	return out;
 }
@@ -345,24 +367,139 @@ function filterRootEntriesForSession(entries: SkillActiveEntry[], sessionId?: st
 	});
 }
 
+function entryRecency(entry: SkillActiveEntry): number {
+	const stamp = entry.handoff_at || entry.updated_at || entry.activated_at;
+	const ms = stamp ? Date.parse(stamp) : Number.NaN;
+	// NaN signals "no trustworthy timestamp" so comparisons can refuse to let an
+	// unknown-recency row win a tie; callers must treat NaN explicitly.
+	return ms;
+}
+
+/**
+ * Session ownership rank for a row visible to a `sessionId` read. When a concrete
+ * session is in scope, a row owned by that exact session outranks a session-less
+ * fallback row, which outranks a foreign-session row. Session-less rows are global
+ * fallbacks and must never override a session's own state. With no scope session,
+ * every row ranks equally.
+ */
+function sessionScopeRank(entry: SkillActiveEntry, sessionId?: string): number {
+	const scope = safeString(sessionId).trim();
+	if (!scope) return 0;
+	const entrySession = safeString(entry.session_id).trim();
+	if (entrySession === scope) return 2;
+	if (entrySession.length === 0) return 1;
+	return 0;
+}
+
+/**
+ * Pick the surviving row for a single skill within a session-scoped visible set.
+ * Precedence, highest first:
+ *   1. exact-session ownership over a session-less fallback row,
+ *   2. a strictly-newer valid timestamp,
+ *   3. a valid timestamp over a missing/unparseable one,
+ *   4. active over inactive — so an untrustworthy inactive row can never hide an
+ *      active row — then merge order for a total tie.
+ * A genuine handoff demotion still supersedes a stale active row of the same skill
+ * because, within one session scope, it carries the newest valid timestamp.
+ */
+function moreVisibleEntry(
+	incumbent: SkillActiveEntry,
+	challenger: SkillActiveEntry,
+	sessionId?: string,
+): SkillActiveEntry {
+	const scopeDelta = sessionScopeRank(incumbent, sessionId) - sessionScopeRank(challenger, sessionId);
+	if (scopeDelta !== 0) return scopeDelta > 0 ? incumbent : challenger;
+	const ri = entryRecency(incumbent);
+	const rc = entryRecency(challenger);
+	const vi = Number.isFinite(ri);
+	const vc = Number.isFinite(rc);
+	if (vi && vc && ri !== rc) return ri > rc ? incumbent : challenger;
+	if (vi !== vc) return vi ? incumbent : challenger;
+	const incumbentActive = incumbent.active !== false;
+	const challengerActive = challenger.active !== false;
+	if (incumbentActive !== challengerActive) return incumbentActive ? incumbent : challenger;
+	return incumbent;
+}
+
+/**
+ * Collapse the merged, session-scoped entries down to a single row per skill.
+ * A handed-off skill can leave more than one row visible to a session — e.g. a
+ * row seeded without a session id (rendered globally by
+ * `filterRootEntriesForSession`) plus a later, session-scoped handoff demotion
+ * of the same skill. Without this collapse the HUD renders the same workflow
+ * twice and keeps showing a skill that has already handed control to its
+ * successor. `moreVisibleEntry` picks the winner so a handoff demotion supersedes
+ * an older stale `active:true` row (and is then dropped by the active filter
+ * below) while a session's own active row is never hidden by a session-less or
+ * untrustworthy-timestamp row.
+ */
+function dedupeVisibleBySkill(entries: SkillActiveEntry[], sessionId?: string): SkillActiveEntry[] {
+	const winners = new Map<string, SkillActiveEntry>();
+	for (const entry of entries) {
+		const current = winners.get(entry.skill);
+		winners.set(entry.skill, current ? moreVisibleEntry(current, entry, sessionId) : entry);
+	}
+	return [...winners.values()];
+}
+
+/**
+ * The planning pipeline advances one stage at a time: `deep-interview →
+ * ralplan → ultragoal`. Each stage is activated through its own command path
+ * (`gjc deep-interview`, `gjc ralplan`, `gjc ultragoal`), and those activations
+ * do not demote the previous stage's row — only the explicit `handoff` verb
+ * does. Without this collapse, activating ultragoal while ralplan is still
+ * `active:true` would render both stages and keep showing a workflow that has
+ * already handed control forward. Keep only the most recently updated pipeline
+ * stage so the HUD reflects the single current workflow. `team` is intentionally
+ * excluded — it runs alongside ultragoal — and every non-pipeline skill is left
+ * untouched.
+ *
+ * This is a HUD-display policy only. It is applied by the skill HUD renderer and
+ * deliberately NOT folded into `readVisibleSkillActiveState`, whose callers (the
+ * deep-interview mutation guard and handoff caller inference) must keep seeing
+ * every genuinely-active skill rather than the single most-recent pipeline stage.
+ */
+const PLANNING_PIPELINE_SKILLS = new Set<string>(["deep-interview", "ralplan", "ultragoal"]);
+
+export function collapsePlanningPipeline(entries: readonly SkillActiveEntry[]): SkillActiveEntry[] {
+	const pipeline = entries.filter(entry => PLANNING_PIPELINE_SKILLS.has(entry.skill));
+	if (pipeline.length <= 1) return [...entries];
+	let current = pipeline[0];
+	let currentRecency = entryRecency(current);
+	for (const entry of pipeline) {
+		const recency = entryRecency(entry);
+		// Prefer a strictly-newer valid timestamp; a valid timestamp also beats a
+		// missing/unparseable one. Ties (or all-invalid) keep the first stage
+		// deterministically rather than letting an unknown-recency row win.
+		const better = Number.isFinite(recency) && (!Number.isFinite(currentRecency) || recency > currentRecency);
+		if (better) {
+			current = entry;
+			currentRecency = recency;
+		}
+	}
+	return entries.filter(entry => !PLANNING_PIPELINE_SKILLS.has(entry.skill) || entry === current);
+}
+
 function mergeVisibleEntries(
 	sessionState: SkillActiveState | null,
 	rootState: SkillActiveState | null,
 	sessionId?: string,
 ): SkillActiveEntry[] {
-	const rootEntries = filterRootEntriesForSession(listActiveSkills(rootState), sessionId);
+	// Use the raw (active + inactive) rows so a handoff demotion stays visible
+	// long enough to supersede a stale same-skill row before the active filter.
+	const rootEntries = filterRootEntriesForSession(rawActiveEntries(rootState), sessionId);
 	const merged = new Map(rootEntries.map(entry => [entryKey(entry), entry]));
-	for (const entry of listActiveSkills(sessionState)) {
+	for (const entry of rawActiveEntries(sessionState)) {
 		merged.set(entryKey(entry), entry);
 	}
-	return [...merged.values()];
+	return dedupeVisibleBySkill([...merged.values()], sessionId).filter(entry => entry.active !== false);
 }
 
 export async function readVisibleSkillActiveState(cwd: string, sessionId?: string): Promise<SkillActiveState | null> {
 	const { rootPath, sessionPath } = getSkillActiveStatePaths(cwd, sessionId);
 	const [rootState, sessionState] = await Promise.all([
-		readStateFile(rootPath),
-		sessionPath ? readStateFile(sessionPath) : Promise.resolve(null),
+		readRawActiveStateForHandoff(rootPath, false),
+		sessionPath ? readRawActiveStateForHandoff(sessionPath, false) : Promise.resolve(null),
 	]);
 	const activeSkills = mergeVisibleEntries(sessionState, rootState, sessionId);
 	if (activeSkills.length === 0) return null;
@@ -468,11 +605,25 @@ export async function applyHandoffToActiveState(options: ApplyHandoffOptions): P
 	const { rootPath, sessionPath } = getSkillActiveStatePaths(options.cwd, sessionId);
 	const readState = (filePath: string) => readRawActiveStateForHandoff(filePath, options.strict === true);
 
+	// A skill can hold more than one visible row in this session's scope — e.g.
+	// it was seeded without a session id (rendered globally) and is now handed
+	// off under a concrete session id. Supersede every same-session-scope row of
+	// the caller and callee skills, not just the exact `skill::session_id` key,
+	// so a stale `active:true` row cannot survive the demotion and keep showing
+	// in the HUD. Rows owned by other sessions are left untouched.
+	const handoffSession = safeString(sessionId).trim();
+	const reassignedSkills = new Set([callerEntry.skill, calleeEntry.skill]);
+	const supersedesVisible = (entry: SkillActiveEntry): boolean => {
+		if (!reassignedSkills.has(entry.skill)) return false;
+		const entrySession = safeString(entry.session_id).trim();
+		return entrySession.length === 0 || entrySession === handoffSession;
+	};
 	const applyEntries = (entries: SkillActiveEntry[]): SkillActiveEntry[] => {
 		const callerKey = entryKey(callerEntry);
-		const calleeKey = entryKey(calleeEntry);
-		const priorCaller = entries.find(e => entryKey(e) === callerKey);
-		const kept = entries.filter(e => entryKey(e) !== callerKey && entryKey(e) !== calleeKey);
+		const priorCaller =
+			entries.find(e => entryKey(e) === callerKey) ??
+			entries.find(e => e.skill === callerEntry.skill && supersedesVisible(e) && Boolean(e.handoff_from));
+		const kept = entries.filter(e => !supersedesVisible(e));
 		// Merge prior lineage into the demoted caller so multi-step handoff
 		// chains preserve `handoff_from` from the previous transition while
 		// the new `handoff_to`/`handoff_at` describe this one.

package/src/task/agents.ts

@@ -30,6 +30,7 @@ interface AgentFrontmatter {
 	blocking?: boolean;
 	hide?: boolean;
 	forkContext?: "forbidden" | "allowed";
+	bashAllowedPrefixes?: string[];
 }
 
 interface EmbeddedAgentDef {

package/src/task/executor.ts

@@ -1186,6 +1186,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 					parentTaskPrefix: id,
 					agentId: id,
 					agentDisplayName: agent.name,
+					bashAllowedPrefixes: agent.bashAllowedPrefixes,
 					enableLsp: lspEnabled,
 					skipPythonPreflight,
 					enableMCP,

package/src/task/types.ts

@@ -181,6 +181,7 @@ export interface AgentDefinition {
 	autoloadSkills?: string[];
 	hide?: boolean;
 	forkContext?: ForkContextPolicy;
+	bashAllowedPrefixes?: string[];
 	source: AgentSource;
 	filePath?: string;
 }

package/src/tools/bash-allowed-prefixes.ts

@@ -0,0 +1,169 @@
+export interface BashAllowedPrefixesCheck {
+	allowed: boolean;
+	reason?: string;
+}
+
+const SHELL_CONTROL_CHARS = new Set([";", "|", "&", "<", ">", "(", ")"]);
+const UNSAFE_UNQUOTED_EXPANSION_CHARS = new Set(["$", "*", "?", "[", "]", "{", "}", "~"]);
+const STATE_FLAGS_WITH_VALUES = new Set(["--input", "--mode", "--session-id", "--thread-id", "--turn-id", "--to"]);
+const STATE_ACTIONS = new Set(["read", "write", "clear", "contract", "handoff"]);
+const ALLOWED_STATE_ACTIONS = new Set(["read", "write", "contract"]);
+
+function parseShellWords(command: string): { words: string[]; reason?: string } {
+	const words: string[] = [];
+	let current = "";
+	let quote: "single" | "double" | null = null;
+
+	for (let index = 0; index < command.length; index += 1) {
+		const char = command[index]!;
+		const next = command[index + 1];
+
+		if (quote === "single") {
+			if (char === "'") {
+				quote = null;
+			} else {
+				current += char;
+			}
+			continue;
+		}
+
+		if (quote === "double") {
+			if (char === '"') {
+				quote = null;
+				continue;
+			}
+			if (char === "`" || (char === "$" && next === "(")) {
+				return { words, reason: "command substitution is not allowed in restricted bash commands" };
+			}
+			if (char === "$") {
+				return { words, reason: "shell expansion character '$' is not allowed in restricted bash commands" };
+			}
+			if (char === "\\") {
+				return { words, reason: "backslash escapes are not allowed in restricted bash commands" };
+			}
+			current += char;
+			continue;
+		}
+
+		if (char === "'") {
+			quote = "single";
+			continue;
+		}
+		if (char === '"') {
+			quote = "double";
+			continue;
+		}
+		if (char === "`" || (char === "$" && next === "(")) {
+			return { words, reason: "command substitution is not allowed in restricted bash commands" };
+		}
+		if (char === "\n" || char === "\r") {
+			return { words, reason: "multiple shell commands are not allowed in restricted bash mode" };
+		}
+		if (SHELL_CONTROL_CHARS.has(char)) {
+			return { words, reason: `shell control operator '${char}' is not allowed in restricted bash commands` };
+		}
+		if (UNSAFE_UNQUOTED_EXPANSION_CHARS.has(char)) {
+			return { words, reason: `shell expansion character '${char}' is not allowed in restricted bash commands` };
+		}
+		if (/\s/u.test(char)) {
+			if (current.length > 0) {
+				words.push(current);
+				current = "";
+			}
+			continue;
+		}
+		if (char === "\\") {
+			return { words, reason: "backslash escapes are not allowed in restricted bash commands" };
+		}
+		current += char;
+	}
+
+	if (quote !== null) {
+		return { words, reason: "unterminated quote in restricted bash command" };
+	}
+	if (current.length > 0) words.push(current);
+	return { words };
+}
+
+function prefixWords(prefix: string): string[] {
+	return prefix.trim().split(/\s+/u).filter(Boolean);
+}
+
+function wordsStartWith(words: readonly string[], prefix: readonly string[]): boolean {
+	if (prefix.length === 0 || words.length < prefix.length) return false;
+	return prefix.every((word, index) => words[index] === word);
+}
+
+function parseStateAction(words: readonly string[]): string | undefined {
+	const args = words.slice(2);
+	const positional: string[] = [];
+	let skipNext = false;
+	for (const arg of args) {
+		if (skipNext) {
+			skipNext = false;
+			continue;
+		}
+		if (STATE_FLAGS_WITH_VALUES.has(arg)) {
+			skipNext = true;
+			continue;
+		}
+		if (!arg.startsWith("-")) positional.push(arg);
+	}
+
+	const [first, second, third] = positional;
+	if (!first) return "read";
+	if (STATE_ACTIONS.has(first)) return second ? undefined : first;
+	if (!second) return "read";
+	if (!STATE_ACTIONS.has(second)) return undefined;
+	return third ? undefined : second;
+}
+
+function validateMatchedGjcCommand(words: readonly string[]): BashAllowedPrefixesCheck {
+	if (words[0] !== "gjc") return { allowed: true };
+
+	if (words[1] === "ralplan") {
+		if (!words.includes("--write")) {
+			return { allowed: false, reason: "restricted role-agent bash only allows `gjc ralplan --write ...`" };
+		}
+		return { allowed: true };
+	}
+
+	if (words[1] === "state") {
+		const action = parseStateAction(words);
+		if (!action) {
+			return {
+				allowed: false,
+				reason: "restricted role-agent bash only allows documented `gjc state` action shapes",
+			};
+		}
+		if (!ALLOWED_STATE_ACTIONS.has(action)) {
+			return { allowed: false, reason: `restricted role-agent bash does not allow \`gjc state ${action}\`` };
+		}
+		return { allowed: true };
+	}
+
+	return { allowed: true };
+}
+
+export function checkBashAllowedPrefixes(
+	command: string,
+	allowedPrefixes: readonly string[] | undefined,
+): BashAllowedPrefixesCheck {
+	const normalizedPrefixes = allowedPrefixes?.map(prefix => prefix.trim()).filter(Boolean) ?? [];
+	if (normalizedPrefixes.length === 0) return { allowed: true };
+
+	const parsed = parseShellWords(command.trim());
+	if (parsed.reason) return { allowed: false, reason: parsed.reason };
+	if (parsed.words.length === 0)
+		return { allowed: false, reason: "empty command is not allowed in restricted bash mode" };
+
+	const matched = normalizedPrefixes.some(prefix => wordsStartWith(parsed.words, prefixWords(prefix)));
+	if (!matched) {
+		return {
+			allowed: false,
+			reason: `restricted role-agent bash only allows commands starting with: ${normalizedPrefixes.join(", ")}`,
+		};
+	}
+
+	return validateMatchedGjcCommand(parsed.words);
+}