@gajae-code/coding-agent 0.4.3 → 0.4.4

package/src/modes/components/hook-selector.ts

@@ -4,6 +4,7 @@
  */
 import {
 	Container,
+	Editor,
 	Markdown,
 	matchesKey,
 	padding,
@@ -16,8 +17,13 @@ import {
 	visibleWidth,
 	wrapTextWithAnsi,
 } from "@gajae-code/tui";
-import { getMarkdownTheme, theme } from "../../modes/theme/theme";
-import { matchesAppExternalEditor, matchesSelectCancel } from "../../modes/utils/keybinding-matchers";
+import { getEditorTheme, getMarkdownTheme, theme } from "../../modes/theme/theme";
+import {
+	matchesAppExternalEditor,
+	matchesAppInterrupt,
+	matchesSelectCancel,
+} from "../../modes/utils/keybinding-matchers";
+import { getEditorCommand, openInEditor } from "../../utils/external-editor";
 import { CountdownTimer } from "./countdown-timer";
 import { DynamicBorder } from "./dynamic-border";
 
@@ -56,6 +62,17 @@ export interface HookSelectorOptions {
 	 */
 	wrapFocused?: boolean;
 	scrollTitleRows?: number;
+	/**
+	 * Inline free-text entry for the option with this label (e.g. the ask
+	 * tool's "Other (type your own)"). Selecting it keeps the title and option
+	 * list on screen and opens a prompt-style editor below the list instead of
+	 * replacing the whole selector. Enter submits via `onSubmit`; Escape
+	 * returns to option selection.
+	 */
+	customInput?: {
+		optionLabel: string;
+		onSubmit: (text: string) => void;
+	};
 }
 
 class OutlinedList extends Container {
@@ -297,6 +314,12 @@ export class HookSelectorComponent extends Container {
 	#wrapFocused: boolean;
 	#outline: boolean;
 	#scrollTitleRows: number | undefined;
+	#customInput: { optionLabel: string; onSubmit: (text: string) => void } | undefined;
+	#inputArea: Container;
+	#inlineEditor: Editor | undefined;
+	#helpTextComponent: Text;
+	#baseHelpText: string;
+	#tui: TUI | undefined;
 	constructor(
 		title: string,
 		options: string[],
@@ -317,6 +340,8 @@ export class HookSelectorComponent extends Container {
 		this.#onExternalEditorCallback = opts?.onExternalEditor;
 		this.#wrapFocused = opts?.wrapFocused === true;
 		this.#outline = opts?.outline === true;
+		this.#customInput = opts?.customInput;
+		this.#tui = opts?.tui;
 
 		this.addChild(new DynamicBorder());
 		this.addChild(new Spacer(1));
@@ -364,9 +389,12 @@ export class HookSelectorComponent extends Container {
 			this.#listContainer = new Container();
 			this.addChild(this.#listContainer);
 		}
+		this.#inputArea = new Container();
+		this.addChild(this.#inputArea);
 		this.addChild(new Spacer(1));
-		const controlsHint = opts?.helpText ?? "up/down navigate  enter select  esc cancel";
-		this.addChild(new Text(theme.fg("dim", controlsHint), 1, 0));
+		this.#baseHelpText = opts?.helpText ?? "up/down navigate  enter select  esc cancel";
+		this.#helpTextComponent = new Text(theme.fg("dim", this.#baseHelpText), 1, 0);
+		this.addChild(this.#helpTextComponent);
 		this.addChild(new Spacer(1));
 		this.addChild(new DynamicBorder());
 
@@ -432,6 +460,10 @@ export class HookSelectorComponent extends Container {
 			this.#scrollableTitle?.scrollBy(this.#scrollTitleRows);
 			return;
 		}
+		if (this.#inlineEditor) {
+			this.#handleInputModeKey(keyData, this.#inlineEditor);
+			return;
+		}
 		if (matchesKey(keyData, "up") || keyData === "k") {
 			this.#selectedIndex = Math.max(0, this.#selectedIndex - 1);
 			this.#updateList();
@@ -440,7 +472,12 @@ export class HookSelectorComponent extends Container {
 			this.#updateList();
 		} else if (matchesKey(keyData, "enter") || matchesKey(keyData, "return") || keyData === "\n") {
 			const selected = this.#options[this.#selectedIndex];
-			if (selected) this.#onSelectCallback(selected);
+			if (!selected) return;
+			if (this.#customInput && selected === this.#customInput.optionLabel) {
+				this.#enterInputMode();
+				return;
+			}
+			this.#onSelectCallback(selected);
 		} else if (matchesKey(keyData, "left")) {
 			this.#onLeftCallback?.();
 		} else if (matchesKey(keyData, "right")) {
@@ -452,6 +489,73 @@ export class HookSelectorComponent extends Container {
 		}
 	}
 
+	/** Keys while the inline custom-input editor is open below the option list. */
+	#handleInputModeKey(keyData: string, editor: Editor): void {
+		// Escape backs out to option selection instead of cancelling the dialog,
+		// so a stray Esc never throws away the question context.
+		if (matchesKey(keyData, "escape") || matchesAppInterrupt(keyData)) {
+			this.#exitInputMode();
+			return;
+		}
+		if (matchesAppExternalEditor(keyData)) {
+			void this.#openExternalEditor(editor);
+			return;
+		}
+		if (matchesKey(keyData, "enter") || matchesKey(keyData, "return")) {
+			this.#customInput?.onSubmit(editor.getText());
+			return;
+		}
+		editor.handleInput(keyData);
+	}
+
+	#enterInputMode(): void {
+		if (this.#inlineEditor) return;
+		// Stop the auto-select countdown for good: the user is actively typing,
+		// matching the old behavior where the separate editor had no timeout.
+		if (this.#countdown) {
+			this.#countdown.dispose();
+			this.#countdown = undefined;
+			this.#titleComponent.setText(this.#baseTitle);
+		}
+		const editor = new Editor(getEditorTheme());
+		editor.setBorderVisible(false);
+		editor.setPromptGutter("> ");
+		editor.disableSubmit = true;
+		this.#inlineEditor = editor;
+		this.#inputArea.addChild(new Spacer(1));
+		this.#inputArea.addChild(editor);
+		const scrollHint = this.#scrollTitleRows === undefined ? "" : "  wheel/PgUp/PgDn scroll question";
+		this.#helpTextComponent.setText(
+			theme.fg("dim", `enter submit  esc back to options  ctrl+g external editor${scrollHint}`),
+		);
+		this.invalidate();
+	}
+
+	#exitInputMode(): void {
+		if (!this.#inlineEditor) return;
+		this.#inlineEditor = undefined;
+		this.#inputArea.clear();
+		this.#helpTextComponent.setText(theme.fg("dim", this.#baseHelpText));
+		this.invalidate();
+	}
+
+	async #openExternalEditor(editor: Editor): Promise<void> {
+		const editorCmd = getEditorCommand();
+		if (!editorCmd || !this.#tui) return;
+
+		const currentText = editor.getExpandedText();
+		try {
+			this.#tui.stop();
+			const result = await openInEditor(editorCmd, currentText);
+			if (result !== null) {
+				editor.setText(result);
+			}
+		} finally {
+			this.#tui.start();
+			this.#tui.requestRender(true);
+		}
+	}
+
 	dispose(): void {
 		this.#countdown?.dispose();
 	}

package/src/modes/controllers/extension-ui-controller.ts

@@ -29,6 +29,7 @@ const HOOK_SELECTOR_MOUSE_REPORTING_ENABLE = "\x1b[?1006h\x1b[?1000h";
 const HOOK_SELECTOR_MOUSE_REPORTING_DISABLE = "\x1b[?1000l\x1b[?1006l";
 const HOOK_SELECTOR_CHROME_ROWS = 7;
 const HOOK_SELECTOR_OUTLINE_ROWS = 2;
+const HOOK_SELECTOR_INLINE_INPUT_ROWS = 2;
 
 export class ExtensionUiController {
 	#extensionTerminalInputUnsubscribers = new Set<() => void>();
@@ -601,8 +602,11 @@ export class ExtensionUiController {
 		const maxVisible =
 			requestedTitleRows === undefined ? baseMaxVisible : Math.min(15, Math.max(3, scrollOptionRows + 1));
 		const listChromeRows = dialogOptions?.outline === true ? HOOK_SELECTOR_OUTLINE_ROWS : 0;
+		// Reserve rows for the inline custom-input editor so opening it doesn't
+		// push the scrollable title past the viewport into terminal scrollback.
+		const inlineInputRows = dialogOptions?.customInput ? HOOK_SELECTOR_INLINE_INPUT_ROWS : 0;
 		const availableTitleRows =
-			this.ctx.ui.terminal.rows - scrollOptionRows - listChromeRows - HOOK_SELECTOR_CHROME_ROWS;
+			this.ctx.ui.terminal.rows - scrollOptionRows - listChromeRows - inlineInputRows - HOOK_SELECTOR_CHROME_ROWS;
 		const scrollTitleRows =
 			requestedTitleRows === undefined ? undefined : Math.max(1, Math.min(requestedTitleRows, availableTitleRows));
 		if (scrollTitleRows !== undefined) {
@@ -645,6 +649,17 @@ export class ExtensionUiController {
 				wrapFocused: dialogOptions?.wrapFocused,
 				scrollTitleRows,
 				maxVisible,
+				customInput: dialogOptions?.customInput
+					? {
+							optionLabel: dialogOptions.customInput.optionLabel,
+							onSubmit: text => {
+								const optionLabel = dialogOptions.customInput?.optionLabel;
+								this.hideHookSelector();
+								dialogOptions.customInput?.onSubmit(text);
+								finish(optionLabel);
+							},
+						}
+					: undefined,
 			},
 		);
 		this.ctx.editorContainer.clear();

package/src/prompts/agents/architect.md

@@ -83,4 +83,10 @@ Prioritized concrete actions.
 
 ## Trade-offs
 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`):
+
+  gjc ralplan --write --stage architect --stage_n <N> --artifact "<full review markdown>" --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

@@ -56,4 +56,10 @@ Review plan clarity, completeness, verification, big-picture fit, referenced fil
 - Risk/Verification Rigor
 
 If not OKAY, list concrete required fixes.
+
+Persist this full evaluation as the durable artifact via the restricted bash CLI, passing the markdown inline (never a file path, never `/tmp`):
+
+  gjc ralplan --write --stage critic --stage_n <N> --artifact "<full evaluation markdown>" --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

@@ -18,6 +18,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.
+- 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.
 - Right-size the step count to the task; do not default to a fixed number of steps.
@@ -42,7 +43,7 @@ Leave execution with a right-sized, evidence-grounded plan: scope, steps, accept
 </success_criteria>
 
 <output_contract>
-Return:
+Build the full plan as a single markdown document containing:
 - Summary
 - In scope / out of scope
 - File-level changes
@@ -50,4 +51,10 @@ Return:
 - Acceptance criteria
 - Verification
 - 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`):
+
+  gjc ralplan --write --stage planner --stage_n <N> --artifact "<full plan markdown>" --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/session/agent-session.ts

@@ -180,6 +180,7 @@ import type { HookCommandContext } from "../extensibility/hooks/types";
 import type { Skill, SkillWarning } from "../extensibility/skills";
 import { expandSlashCommand, type FileSlashCommand } from "../extensibility/slash-commands";
 import { buildGjcRuntimeSessionEnv, consumePendingGoalModeRequest } from "../gjc-runtime/goal-mode-request";
+import { persistCoordinatorRuntimeStateFromEvent } from "../gjc-runtime/session-state-sidecar";
 import { writeArtifact } from "../gjc-runtime/state-writer";
 import { requestGjcWorkerIntegrationAttempt } from "../gjc-runtime/team-runtime";
 import { GoalRuntime } from "../goals/runtime";
@@ -1626,6 +1627,11 @@ export class AgentSession {
 	}
 
 	async #emitSessionEvent(event: AgentSessionEvent): Promise<void> {
+		await persistCoordinatorRuntimeStateFromEvent(event, {
+			sessionId: this.sessionId,
+			cwd: this.sessionManager.getCwd(),
+			sessionFile: this.sessionManager.getSessionFile(),
+		});
 		if (event.type === "message_update") {
 			this.#emit(event);
 			void this.#queueExtensionEvent(event);

package/src/setup/hermes/templates/operator-instructions.v1.md

@@ -0,0 +1,29 @@
+# GJC Hermes operator instructions v{{TEMPLATE_VERSION}}
+
+Server key: {{SERVER_KEY}}
+
+These instructions teach a Hermes-style coordinator how to operate GJC through the `{{TOOL_PREFIX}}_*` MCP tools. They are setup guidance, not a GJC workflow skill.
+
+## Core loop
+
+1. Use `{{TOOL_PREFIX}}_list_sessions` to find an existing session, or `{{TOOL_PREFIX}}_start_session` when a new session is required and mutation is enabled.
+2. Send exactly one bounded task prompt with `{{TOOL_PREFIX}}_send_prompt`.
+3. Store the returned `turn_id`.
+4. Poll `{{TOOL_PREFIX}}_read_turn` or `{{TOOL_PREFIX}}_await_turn` for that `turn_id` until the turn is terminal.
+5. If GJC asks a structured question, use `{{TOOL_PREFIX}}_list_questions` and answer with `{{TOOL_PREFIX}}_submit_question_answer`.
+6. Use `{{TOOL_PREFIX}}_report_status` for coordinator-visible status and final reports.
+7. Use `{{TOOL_PREFIX}}_read_tail` only as advisory debug output when structured turn state is insufficient.
+
+Do not report completion to the user until the GJC turn is terminal. Do not infer completion from terminal scrollback alone.
+
+## Model and provider policy
+
+The Hermes bridge does not choose a model/provider. When no session command is configured, GJC uses its normal local model/provider resolution. If the operator config supplies `GJC_COORDINATOR_MCP_SESSION_COMMAND`, preserve it as explicit user intent.
+
+Provider-specific commands are examples only, never product defaults.
+
+## Safety
+
+- Mutating tools require bridge startup mutation classes and per-call consent.
+- Allowed roots restrict workdir and artifact paths.
+- Artifact reads are bounded and should be treated as evidence, not unlimited filesystem access.