@gajae-code/coding-agent 0.7.10 → 0.7.11

package/src/prompts/agents/architect.md

@@ -25,7 +25,7 @@ You may receive a forked parent-conversation snapshot as background. Your read-o
 
 <constraints>
 - Read-only: never write, edit, format, commit, push, or mutate files.
-- Exception: you may use the restricted `bash` tool only for sanctioned GJC workflow CLI persistence (`gjc ralplan --write ...`) and GJC workflow state read/write/contract commands (`gjc state ...`). For `gjc ralplan --write`, pass the verdict markdown inline in `--artifact`, not as a file path. Do not use bash for product-source writes, direct handoffs, state clears, or general shell work.
+- Exception: you may use the restricted `bash` tool only for sanctioned GJC workflow CLI persistence (`gjc ralplan --write ...`) and GJC workflow state read/write/contract commands (`gjc state ...`). For `gjc ralplan --write`, pass the verdict markdown through the `GJC_RALPLAN_ARTIFACT` env override and `--artifact-env GJC_RALPLAN_ARTIFACT`, not as a file path. Do not use bash for product-source writes, direct handoffs, state clears, or general shell work.
 - Never approve code or plans you have not grounded in inspected files.
 - Never give generic advice detached from this codebase.
 - Never approve CRITICAL or HIGH severity issues.
@@ -63,6 +63,9 @@ A narrow compatibility fallback can be acceptable only when it is scoped to a kn
 ## Summary
 2-3 sentences with result and main recommendation.
 
+## Claims
+Evidence-backed claims being reviewed or introduced.
+
 ## Analysis
 Evidence-backed findings.
 
@@ -81,12 +84,12 @@ Prioritized concrete actions.
 ## Code Review Recommendation
 `APPROVE` / `COMMENT` / `REQUEST CHANGES`
 
-## Trade-offs
+## Tradeoffs
 Table or bullets comparing viable options when relevant.
 
-Persist this full review as the durable artifact via the restricted bash CLI, passing the markdown inline (never a file path, never `/tmp`):
+Persist this full review as the durable artifact via the restricted bash CLI, passing the markdown through the `GJC_RALPLAN_ARTIFACT` env override (never a file path, never `/tmp`):
 
-  gjc ralplan --write --stage architect --stage_n <N> --artifact "<full review markdown>" --json
+  gjc ralplan --write --stage architect --stage_n <N> --artifact-env GJC_RALPLAN_ARTIFACT --json
 
 Then return to the caller ONLY the write receipt (`run_id`, `path`, `sha256`, `stage`, `stage_n`) plus the compact verdict (Architectural Status + Code Review Recommendation). Never paste the full review body back into your response — the caller reads the persisted artifact when it needs the full text.
 </output_contract>

package/src/prompts/agents/critic.md

@@ -17,7 +17,7 @@ Review plan clarity, completeness, verification, big-picture fit, referenced fil
 
 <constraints>
 - Read-only: do not write, edit, format, commit, push, or mutate files.
-- Exception: you may use the restricted `bash` tool only for sanctioned GJC workflow CLI persistence (`gjc ralplan --write ...`) and GJC workflow state read/write/contract commands (`gjc state ...`). For `gjc ralplan --write`, pass the evaluation markdown inline in `--artifact`, not as a file path. Do not use bash for product-source writes, direct handoffs, state clears, or general shell work.
+- Exception: you may use the restricted `bash` tool only for sanctioned GJC workflow CLI persistence (`gjc ralplan --write ...`) and GJC workflow state read/write/contract commands (`gjc state ...`). For `gjc ralplan --write`, pass the evaluation markdown through the `GJC_RALPLAN_ARTIFACT` env override and `--artifact-env GJC_RALPLAN_ARTIFACT`, not as a file path. Do not use bash for product-source writes, direct handoffs, state clears, or general shell work.
 - A lone file path is valid input; read and evaluate it.
 - Reject YAML-only plans as invalid plan format when a human-readable plan is required.
 - Do not invent problems; report no issues found when the plan passes.
@@ -42,11 +42,19 @@ Review plan clarity, completeness, verification, big-picture fit, referenced fil
 </success_criteria>
 
 <output_contract>
+## Verdict
 **[OKAY / ITERATE / REJECT]**
 
-**Justification**: concise evidence-backed explanation.
+## Claim Checks
+Concise evidence-backed explanation of verified claims.
 
-**Summary**:
+## Missing Evidence
+Definitely missing or unverified evidence, or `None`.
+
+## Approval Boundary
+What execution may proceed with, and what remains outside approval.
+
+## Summary
 - Clarity
 - Verifiability
 - Completeness
@@ -55,11 +63,12 @@ Review plan clarity, completeness, verification, big-picture fit, referenced fil
 - Alternatives Depth
 - Risk/Verification Rigor
 
-If not OKAY, list concrete required fixes.
+## Required Changes
+If not OKAY, list concrete required fixes; otherwise write `None`.
 
-Persist this full evaluation as the durable artifact via the restricted bash CLI, passing the markdown inline (never a file path, never `/tmp`):
+Persist this full evaluation as the durable artifact via the restricted bash CLI, passing the markdown through the `GJC_RALPLAN_ARTIFACT` env override (never a file path, never `/tmp`):
 
-  gjc ralplan --write --stage critic --stage_n <N> --artifact "<full evaluation markdown>" --json
+  gjc ralplan --write --stage critic --stage_n <N> --artifact-env GJC_RALPLAN_ARTIFACT --json
 
 Then return to the caller ONLY the write receipt (`run_id`, `path`, `sha256`, `stage`, `stage_n`) plus the compact verdict (OKAY / ITERATE / REJECT). Never paste the full evaluation body back into your response — the caller reads the persisted artifact when it needs the full text.
 </output_contract>

package/src/prompts/agents/planner.md

@@ -17,7 +17,7 @@ Leave execution with a right-sized, evidence-grounded plan: scope, steps, accept
 
 <constraints>
 - Read-only: never write, edit, format, commit, push, or mutate files.
-- Exception: you may use the restricted `bash` tool only for sanctioned GJC workflow CLI persistence (`gjc ralplan --write ...`) and GJC workflow state read/write/contract commands (`gjc state ...`). For `gjc ralplan --write`, pass the plan markdown inline in `--artifact`, not as a file path. Do not use bash for product-source writes, direct handoffs, state clears, or general shell work.
+- Exception: you may use the restricted `bash` tool only for sanctioned GJC workflow CLI persistence (`gjc ralplan --write ...`) and GJC workflow state read/write/contract commands (`gjc state ...`). For `gjc ralplan --write`, pass the plan markdown through the `GJC_RALPLAN_ARTIFACT` env override and `--artifact-env GJC_RALPLAN_ARTIFACT`, not as a file path. Do not use bash for product-source writes, direct handoffs, state clears, or general shell work.
 - Persist durable plans only through `gjc ralplan --write`. Never write plan files to `/tmp`, the repository, or any other path, and never rely on a file the caller must read back. The CLI is your only persistence channel.
 - Inspect the repository before asking about code facts.
 - Ask only about priorities, tradeoffs, scope decisions, timelines, or preferences that repository inspection cannot resolve.
@@ -45,16 +45,21 @@ Leave execution with a right-sized, evidence-grounded plan: scope, steps, accept
 <output_contract>
 Build the full plan as a single markdown document containing:
 - Summary
+- Intent Diff
+- Decision Drivers
+- Options
 - In scope / out of scope
 - File-level changes
 - Sequencing and dependencies
 - Acceptance criteria
 - Verification
+- Escalation/Risk Gate
+- Verification Plan
 - Risks and mitigations
 
-Persist that markdown as the durable artifact via the restricted bash CLI, passing the plan inline (never a file path, never `/tmp`):
+Persist that markdown as the durable artifact via the restricted bash CLI, passing the plan through the `GJC_RALPLAN_ARTIFACT` env override (never a file path, never `/tmp`):
 
-  gjc ralplan --write --stage planner --stage_n <N> --artifact "<full plan markdown>" --json
+  gjc ralplan --write --stage planner --stage_n <N> --artifact-env GJC_RALPLAN_ARTIFACT --json
 
 Then return to the caller ONLY the write receipt (`run_id`, `path`, `sha256`, `stage`, `stage_n`) plus a compact plan summary (<=10 lines). Never paste the full plan body back into your response — the caller reads the persisted artifact when it needs the full text.
 </output_contract>

package/src/prompts/tools/bash.md

@@ -33,7 +33,7 @@ This session's bash tool is restricted. It only accepts commands beginning with:
 {{#each restrictedAllowedPrefixes}}
 - `{{this}}`
 {{/each}}
-Use it only for sanctioned GJC workflow CLI persistence or state read/write/contract operations; per-command env overrides and all other shell command shapes are blocked before execution.
+Use it only for sanctioned GJC workflow CLI persistence or state read/write/contract operations; the only per-command env override allowed is `GJC_RALPLAN_ARTIFACT` when paired with `gjc ralplan --write ... --artifact-env GJC_RALPLAN_ARTIFACT`, and all other shell command shapes are blocked before execution.
 {{/when}}
 </restricted-bash-mode>
 {{/if}}

package/src/sdk.ts

@@ -119,6 +119,7 @@ import { AgentOutputManager } from "./task/output-manager";
 import { parseThinkingLevel, resolveThinkingLevelForModel, toReasoningEffort } from "./thinking";
 import { collectDiscoverableTools, type DiscoverableTool } from "./tool-discovery/tool-index";
 import {
+	applyConfiguredSearchTimeout,
 	BashTool,
 	BUILTIN_TOOLS,
 	computeEssentialBuiltinNames,
@@ -140,7 +141,6 @@ import {
 	setPreferredImageProvider,
 	setPreferredSearchProvider,
 	setSearchFallbackProviders,
-	setSearchHardTimeoutMs,
 	type Tool,
 	type ToolSession,
 	WebSearchTool,
@@ -255,7 +255,7 @@ export interface CreateAgentSessionOptions {
 	thinkingLevel?: ThinkingLevel;
 	/** Runtime substitution metadata for the initial model_change session event. */
 	modelSubstitution?: { requestedModel: Model; reason: string };
-	/** Models available for cycling (Ctrl+P in interactive mode) */
+	/** Models available for cycling (Alt+N in interactive mode) */
 	scopedModels?: ScopedModelSelection[];
 
 	/** System prompt blocks. Array replaces default, function receives default blocks and returns final blocks. */
@@ -940,10 +940,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			webSearchFallback.filter(value => typeof value === "string" && isConfigurableSearchProviderId(value)),
 		);
 	}
-	const webSearchTimeout = settings.get("web_search.timeout");
-	if (typeof webSearchTimeout === "number" && Number.isFinite(webSearchTimeout) && webSearchTimeout > 0) {
-		setSearchHardTimeoutMs(webSearchTimeout * 1000);
-	}
+	applyConfiguredSearchTimeout(settings);
 
 	const imageProvider = settings.get("providers.image");
 	if (

package/src/session/agent-session.ts

@@ -353,7 +353,7 @@ export interface AgentSessionConfig {
 	agent: Agent;
 	sessionManager: SessionManager;
 	settings: Settings;
-	/** Models to cycle through with Ctrl+P (from --models flag) */
+	/** Models to cycle through with Alt+N (from --models flag) */
 	scopedModels?: ScopedModelSelection[];
 	/** Initial session thinking selector. */
 	thinkingLevel?: ThinkingLevel;
@@ -901,8 +901,9 @@ function extractPermissionLocations(
  *  `tag` is set only by `enqueueCustomMessageDisplay` (used for skill-prompt
  *  custom messages queued during streaming) and is matched by the custom-role
  *  `message_start` dequeue branch; user-message pushes leave it undefined and
- *  rely on the existing text-equality match. */
-type QueuedDisplayEntry = { text: string; tag?: string };
+ *  rely on the existing text-equality match. `sequence` preserves cross-queue
+ *  insertion order for one-at-a-time dequeue/edit UX. */
+type QueuedDisplayEntry = { text: string; tag?: string; sequence: number };
 
 /** A custom message contributed at the before-agent-start point. */
 export type BeforeAgentStartInternalMessage = Pick<
@@ -956,6 +957,7 @@ export class AgentSession {
 	/** Tracks pending follow-up messages for UI display. Removed when delivered.
 	 *  See `#steeringMessages` for entry shape. */
 	#followUpMessages: QueuedDisplayEntry[] = [];
+	#queuedDisplaySequence = 0;
 	/** Messages queued to be included with the next user prompt as context ("asides"). */
 	#pendingNextTurnMessages: CustomMessage[] = [];
 	#scheduledHiddenNextTurnGeneration: number | undefined = undefined;
@@ -1625,6 +1627,14 @@ export class AgentSession {
 		this.#planCompactAbortPending = false;
 	}
 
+	#createQueuedDisplayEntry(text: string, tag?: string): QueuedDisplayEntry {
+		const entry: QueuedDisplayEntry = { text, sequence: ++this.#queuedDisplaySequence };
+		if (tag !== undefined) {
+			entry.tag = tag;
+		}
+		return entry;
+	}
+
 	/** Register a compact display string for a custom message that the caller is
 	 *  about to dispatch via `promptCustomMessage` / `sendCustomMessage`.
 	 *  Returns a stable tag the caller MUST embed in
@@ -1638,7 +1648,7 @@ export class AgentSession {
 		const tag = `gjc-cmd-${Date.now()}-${++this.#customDisplayTagCounter}`;
 		const displayText = text.trim();
 		if (!displayText) return tag;
-		const entry: QueuedDisplayEntry = { text: displayText, tag };
+		const entry = this.#createQueuedDisplayEntry(displayText, tag);
 		if (mode === "steer") {
 			this.#steeringMessages.push(entry);
 		} else {
@@ -5285,7 +5295,7 @@ export class AgentSession {
 	 */
 	async #queueSteer(text: string, images?: ImageContent[]): Promise<void> {
 		const displayText = text || (images && images.length > 0 ? "[Image]" : "");
-		this.#steeringMessages.push({ text: displayText });
+		this.#steeringMessages.push(this.#createQueuedDisplayEntry(displayText));
 		const content: (TextContent | ImageContent)[] = [{ type: "text", text }];
 		if (images && images.length > 0) {
 			content.push(...images);
@@ -5316,7 +5326,7 @@ export class AgentSession {
 	 */
 	async #queueFollowUp(text: string, images?: ImageContent[]): Promise<void> {
 		const displayText = text || (images && images.length > 0 ? "[Image]" : "");
-		this.#followUpMessages.push({ text: displayText });
+		this.#followUpMessages.push(this.#createQueuedDisplayEntry(displayText));
 		const content: (TextContent | ImageContent)[] = [{ type: "text", text }];
 		if (images && images.length > 0) {
 			content.push(...images);
@@ -5686,24 +5696,27 @@ export class AgentSession {
 	}
 
 	/**
-	 * Pop the last queued message (steering first, then follow-up).
+	 * Pop the newest queued message across steering and follow-up queues.
 	 * Used by dequeue keybinding to restore messages to editor one at a time.
 	 * Returns the popped entry's `.text`; the tag (if any) dies with the
 	 * record — no orphan state can outlive the queue entry.
 	 */
 	popLastQueuedMessage(): string | undefined {
-		// Pop from steering first (LIFO)
-		if (this.#steeringMessages.length > 0) {
+		const steeringEntry = this.#steeringMessages.at(-1);
+		const followUpEntry = this.#followUpMessages.at(-1);
+
+		if (steeringEntry && (!followUpEntry || steeringEntry.sequence > followUpEntry.sequence)) {
 			const entry = this.#steeringMessages.pop();
 			this.agent.popLastSteer();
 			return entry?.text;
 		}
-		// Then from follow-up
-		if (this.#followUpMessages.length > 0) {
+
+		if (followUpEntry) {
 			const entry = this.#followUpMessages.pop();
 			this.agent.popLastFollowUp();
 			return entry?.text;
 		}
+
 		return undefined;
 	}
 
@@ -8932,22 +8945,52 @@ export class AgentSession {
 	setAutoRetryEnabled(enabled: boolean): void {
 		this.settings.set("retry.enabled", enabled);
 	}
+	#isInterruptedRetryTail(message: AgentMessage | undefined): boolean {
+		if (!message) return false;
+		return (
+			message.role === "user" ||
+			message.role === "developer" ||
+			message.role === "toolResult" ||
+			message.role === "fileMention" ||
+			message.role === "custom" ||
+			message.role === "hookMessage"
+		);
+	}
+
+	#isUnresolvedToolUseAssistant(message: AssistantMessage): boolean {
+		return message.stopReason === "toolUse" && message.content.some(content => content.type === "toolCall");
+	}
+
 	/**
-	 * Manually retry the last failed assistant turn.
-	 * Removes the error message from agent state and re-attempts with a fresh retry budget.
-	 * @returns true if retry was initiated, false if no failed turn to retry or agent is busy
+	 * Manually retry the last failed assistant turn, or resume an interrupted tail
+	 * left by a non-graceful process exit after the user/custom/tool-result message
+	 * was persisted but before the agent emitted a terminal assistant response.
+	 * Removes failed/aborted/unresolved tool-use assistant tails before
+	 * re-attempting with a fresh retry budget.
+	 * @returns true if retry/resume was initiated, false if no retryable tail exists or agent is busy
 	 */
 	async retry(): Promise<boolean> {
 		if (this.isStreaming || this.isCompacting || this.isRetrying) return false;
 
 		const messages = this.agent.state.messages;
 		const lastMsg = messages[messages.length - 1];
-		if (lastMsg?.role !== "assistant") return false;
+		if (!lastMsg) return false;
+
+		if (lastMsg.role !== "assistant") {
+			if (!this.#isInterruptedRetryTail(lastMsg)) return false;
+			this.#retryAttempt = 0;
+			this.#scheduleAgentContinue({ delayMs: 1 });
+			return true;
+		}
 
 		const assistantMsg = lastMsg as AssistantMessage;
-		if (assistantMsg.stopReason !== "error" && assistantMsg.stopReason !== "aborted") return false;
+		const shouldDropAssistant =
+			assistantMsg.stopReason === "error" ||
+			assistantMsg.stopReason === "aborted" ||
+			this.#isUnresolvedToolUseAssistant(assistantMsg);
+		if (!shouldDropAssistant) return false;
 
-		// Remove the failed/aborted assistant message (same as auto-retry does before re-attempting)
+		// Remove the failed/aborted/incomplete assistant message before re-attempting.
 		this.agent.replaceMessages(messages.slice(0, -1));
 
 		// Reset retry budget for a fresh attempt

package/src/slash-commands/builtin-registry.ts

@@ -322,7 +322,8 @@ const shutdownHandlerTui = (_command: ParsedSlashCommand, runtime: TuiSlashComma
 const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 	{
 		name: "settings",
-		description: "Open settings menu",
+		priority: 40,
+		description: "Open settings and preferences",
 		handleTui: (_command, runtime) => {
 			runtime.ctx.showSettingsSelector();
 			runtime.ctx.editor.setText("");
@@ -338,7 +339,8 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 	},
 	{
 		name: "goal",
-		description: "Toggle goal mode (persistent autonomous objective for this session)",
+		priority: 84,
+		description: "Plan and track an autonomous goal",
 		subcommands: [
 			{ name: "set", description: "Set or replace the goal", usage: "<objective>" },
 			{ name: "show", description: "Show current goal details" },
@@ -541,7 +543,8 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 	},
 	{
 		name: "export",
-		description: "Export session to HTML file",
+		priority: 50,
+		description: "Export this session to an HTML file",
 		inlineHint: "[path]",
 		allowArgs: true,
 		handle: async (command, runtime) => {
@@ -568,7 +571,8 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 	},
 	{
 		name: "copy",
-		description: "Copy last response as markdown",
+		priority: 55,
+		description: "Copy the last response for review or sharing",
 		// Public `/copy` is strict zero-argument, but `allowArgs` lets the
 		// TUI dispatcher route `/copy <arg>` here so it can be rejected locally
 		// instead of falling through as a model prompt.
@@ -585,7 +589,8 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 	},
 	{
 		name: "dump",
-		description: "Copy session transcript to clipboard",
+		priority: 54,
+		description: "Dump the full transcript for review or sharing",
 		acpDescription: "Return full transcript as plain text",
 		handle: async (_command, runtime) => {
 			const text = runtime.session.formatSessionAsText();
@@ -599,11 +604,12 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 	},
 	{
 		name: "session",
-		description: "Session management commands",
+		priority: 88,
+		description: "Show current session info or delete current session",
 		acpDescription: "Show session information",
 		acpInputHint: "info|delete",
 		subcommands: [
-			{ name: "info", description: "Show session info and stats" },
+			{ name: "info", description: "Show current session id, title, and workspace" },
 			{ name: "delete", description: "Delete current session and return to selector" },
 		],
 		allowArgs: true,
@@ -713,6 +719,15 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 			runtime.ctx.editor.setText("");
 		},
 	},
+	{
+		name: "help",
+		priority: 100,
+		description: "Learn commands and beginner workflows",
+		handleTui: (_command, runtime) => {
+			runtime.ctx.handleHelpCommand();
+			runtime.ctx.editor.setText("");
+		},
+	},
 	{
 		name: "hotkeys",
 		description: "Show all keyboard shortcuts",
@@ -953,6 +968,7 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 	},
 	{
 		name: "new",
+		priority: 96,
 		description: "Start a new session",
 		handleTui: async (_command, runtime) => {
 			runtime.ctx.editor.setText("");
@@ -969,7 +985,8 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 	},
 	{
 		name: "compact",
-		description: "Manually compact the session context",
+		priority: 72,
+		description: "Compact context and continue this session",
 		acpDescription: "Compact the conversation",
 		inlineHint: "[focus instructions]",
 		allowArgs: true,
@@ -1026,7 +1043,8 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 	},
 	{
 		name: "resume",
-		description: "Resume a different session",
+		priority: 92,
+		description: "Resume a previous session",
 		handleTui: (_command, runtime) => {
 			runtime.ctx.showSessionSelector();
 			runtime.ctx.editor.setText("");
@@ -1045,7 +1063,8 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 	},
 	{
 		name: "retry",
-		description: "Retry the last failed agent turn",
+		priority: 70,
+		description: "Retry or continue the last interrupted turn",
 		handleTui: async (_command, runtime) => {
 			const didRetry = await runtime.ctx.session.retry();
 			if (!didRetry) {
@@ -1242,6 +1261,7 @@ export const BUILTIN_SLASH_COMMAND_DEFS: ReadonlyArray<BuiltinSlashCommand> = AC
 		description: command.description,
 		subcommands: command.subcommands,
 		inlineHint: command.inlineHint,
+		priority: command.priority,
 	}),
 );
 

package/src/slash-commands/types.ts

@@ -19,6 +19,8 @@ export interface BuiltinSlashCommand {
 	subcommands?: SubcommandDef[];
 	/** Static inline hint when command takes a simple argument (no subcommands). */
 	inlineHint?: string;
+	/** Higher values sort earlier in TUI slash-command autocomplete. */
+	priority?: number;
 }
 
 /** Parsed slash-command text after stripping the leading "/". */

package/src/tools/bash.ts

@@ -8,7 +8,10 @@ import { AsyncJobManager } from "../async";
 import { type BashResult, executeBash } from "../exec/bash-executor";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { buildGjcRuntimeSessionEnv } from "../gjc-runtime/goal-mode-request";
-import { GJC_RESTRICTED_ROLE_AGENT_BASH_ENV } from "../gjc-runtime/restricted-role-agent-bash";
+import {
+	GJC_RALPLAN_ARTIFACT_ENV,
+	GJC_RESTRICTED_ROLE_AGENT_BASH_ENV,
+} from "../gjc-runtime/restricted-role-agent-bash";
 import { InternalUrlRouter } from "../internal-urls";
 import { truncateToVisualLines } from "../modes/components/visual-truncate";
 import { highlightCode, type Theme } from "../modes/theme/theme";
@@ -530,13 +533,24 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 
 		const rawCommand = input.command;
 		const allowedPrefixes = this.session.bashAllowedPrefixes;
+		const isRestrictedRalplanArtifactEnv =
+			allowedPrefixes &&
+			allowedPrefixes.length > 0 &&
+			this.session.bashRestrictionProfile !== "read-only" &&
+			env &&
+			Object.keys(env).length === 1 &&
+			Object.hasOwn(env, GJC_RALPLAN_ARTIFACT_ENV) &&
+			rawCommand.includes(`--artifact-env ${GJC_RALPLAN_ARTIFACT_ENV}`);
 		if (
 			(this.session.bashRestrictionProfile === "read-only" || (allowedPrefixes && allowedPrefixes.length > 0)) &&
 			env &&
-			Object.keys(env).length > 0
+			Object.keys(env).length > 0 &&
+			!isRestrictedRalplanArtifactEnv
 		) {
 			const mode = this.session.bashRestrictionProfile === "read-only" ? "Read-only" : "Restricted role-agent";
-			throw new ToolError(`${mode} bash does not allow per-command env overrides.`);
+			throw new ToolError(
+				`${mode} bash only allows the ${GJC_RALPLAN_ARTIFACT_ENV} env override for --artifact-env.`,
+			);
 		}
 		if (allowedPrefixes && allowedPrefixes.length > 0) {
 			const commandsToCheck = rawCommand === command ? [command] : [rawCommand, command];
@@ -597,11 +611,13 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 					await Promise.all(
 						Object.entries(env).map(async ([key, value]) => [
 							key,
-							await expandInternalUrls(value, {
-								...internalUrlOptions,
-								ensureLocalParentDirs: true,
-								noEscape: true,
-							}),
+							key === GJC_RALPLAN_ARTIFACT_ENV
+								? value
+								: await expandInternalUrls(value, {
+										...internalUrlOptions,
+										ensureLocalParentDirs: true,
+										noEscape: true,
+									}),
 						]),
 					),
 				)