@gajae-code/coding-agent 0.2.3 → 0.2.5

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 ?? "*",
@@ -1732,6 +1735,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		const preferOpenAICodexWebsockets =
 			openaiWebsocketSetting === "on" ? true : openaiWebsocketSetting === "off" ? false : undefined;
 		const serviceTierSetting = settings.get("serviceTier");
+		const retrySettings = settings.getGroup("retry");
 
 		const initialServiceTier = hasServiceTierEntry
 			? existingSession.serviceTier
@@ -1789,6 +1793,9 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			repetitionPenalty: settings.get("repetitionPenalty") >= 0 ? settings.get("repetitionPenalty") : undefined,
 			serviceTier: initialServiceTier,
 			hideThinkingSummary: settings.get("hideThinkingBlock"),
+			maxRetryDelayMs: retrySettings.maxDelayMs,
+			requestMaxRetries: retrySettings.requestMaxRetries,
+			streamMaxRetries: retrySettings.streamMaxRetries,
 			kimiApiFormat: settings.get("providers.kimiApiFormat") ?? "anthropic",
 			preferWebsockets: preferOpenAICodexWebsockets,
 			getToolContext: tc => toolContextStore.getContext(tc),

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/slash-commands/builtin-registry.ts

@@ -216,6 +216,14 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 			runtime.ctx.editor.setText("");
 		},
 	},
+	{
+		name: "theme",
+		description: "Open theme selector",
+		handleTui: (_command, runtime) => {
+			runtime.ctx.showThemeSelector();
+			runtime.ctx.editor.setText("");
+		},
+	},
 	{
 		name: "goal",
 		description: "Toggle goal mode (persistent autonomous objective for this session)",
@@ -923,7 +931,9 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 						runtime.settings,
 						runtime.session,
 					);
-					await runtime.output(payload || "Memory payload is empty.");
+					await runtime.output(
+						payload || "Memory payload is empty; durable memory is unavailable or unconfirmed.",
+					);
 					return commandConsumed();
 				}
 				case "clear":

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);
+}