@hncode/hncode 0.3.2 → 0.3.3

package/README.md

@@ -13,10 +13,53 @@ A cyan-blue terminal user interface (TUI) coding agent inspired by [Kimi Code](h
 - **Cyan-blue TUI**: Raw terminal renderer for perfect Windows Terminal compatibility
 - **Dual Protocol Support**: Works with both OpenAI-compatible APIs and Anthropic
 - **Smart Context Management**: Auto-compaction at 85% usage, AI-summarized history retention
+- **Prompt Caching**: Explicit cache breakpoints for the stable prefix (`/cache`)
 - **MCP-style Toolbelt**: Read, Write, Edit, Bash, Glob, Grep, TodoList, WebSearch, etc.
+- **MCP Client**: Connect real Model Context Protocol servers (stdio + HTTP) and use their tools
+- **Skills**: Package reusable prompts as Markdown (`/import-skill`, `/skill:<name>` with tab-completion)
+- **Shell Hooks**: Run your own commands at lifecycle events (`PreToolUse`, `PostToolUse`, …)
+- **Git Workflow**: `/git`, `/commit`, `/branch`, `/worktree`, `/pr` plus a `Git` tool for the agent
+- **Plan Review**: Review what a plan will touch, edit it, then approve before any file changes
 - **Plugin System**: Extend with custom tools, commands, and hooks
 - **Session Persistence**: Resume conversations across sessions
 - **Permission Modes**: Ask, YOLO, or Auto modes for different workflows
+- **Shell Passthrough**: type `!` on an empty prompt to switch the composer into shell mode — no model round-trip
+- **CI / Scripting**: Headless `-p` with `json` / `stream-json` output and outcome-based exit codes
+- **Remote Control**: `--control` exposes a local socket to prompt/status/interrupt a running session
+
+### CI usage
+
+```bash
+# One prompt, machine-readable result, exit code reflects the outcome.
+hncode -p "fix the failing tests" --output-format json
+# -> {"type":"result","ok":true,"reply":"…","toolCalls":["Bash"],"files":["src/a.js"],…}
+
+# Exit codes: 0 ok · 1 failure · 2 config · 3 no answer · 4 interrupted
+hncode -p "run the linter and fix everything" --output-format stream-json | jq -c 'select(.type=="result")'
+```
+
+### Shell passthrough
+
+Type `!` on an **empty** prompt to switch the composer into shell mode — the `!`
+becomes the prompt symbol and the line runs directly, with no model involved:
+
+```
+! git add -A && git push
+! npm test
+```
+
+The `!` is a mode marker, not part of what you type, so it appears exactly once.
+Press `Esc` or `Backspace` on an empty line to leave the mode. Output appears in
+the transcript as a `↳` receipt.
+
+### Remote control
+
+```bash
+hncode --control                       # in one terminal (TUI)
+hncode control status                  # in another
+hncode control prompt "run the tests"  # queue a prompt on the running session
+hncode control interrupt
+```
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hncode/hncode",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "hncode — A cyan-blue TUI AI coding agent with zero runtime dependencies.",
   "type": "module",
   "main": "src/index.js",

package/src/agent.js

@@ -7,6 +7,22 @@ import { tools, getTool, llmTools } from './tools/index.js';
 import { DELEGATION_TOOLS } from './subagent-types.js';
 import { estimateMessagesTokens } from './term.js';
 import { runHooks } from './plugin.js';
+import { loadHooks, runShellHooks } from './hooks.js';
+
+// A short, stable key for the prompt cache, derived from the conversation's
+// first user message. Stability is the whole point: the same conversation must
+// produce the same key on every turn, so a cheap deterministic hash beats a
+// random id. (Different conversations may collide — that is harmless, it only
+// means the provider's routing key is shared.)
+function hashKey(s) {
+  let h = 0x811c9dc5;
+  const str = String(s || '');
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    h = (h * 0x01000193) >>> 0;
+  }
+  return h.toString(36) + '-' + str.length.toString(36);
+}
 
 // ---- completion guard --------------------------------------------------------
 // A turn is only complete when the model ends it with an actual answer. Models
@@ -118,9 +134,28 @@ export class Agent {
     // tool a live getter over this agent's own messages instead of a copy, so the
     // snapshot is taken at spawn time and reflects everything up to that point.
     this.ctx._parentMessages = this.messages;
+    // Prompt-cache key: identify the SESSION, not the request, so the cached
+    // prefix is reused across turns instead of thrashing. The caller may pass one
+    // (the TUI knows the session id); otherwise derive a stable value from the
+    // first user message so repeated runs of the same conversation still share a
+    // prefix. A subagent inherits the parent's key (same conversation family).
+    if (cfg.sessionId == null) {
+      const firstUser = (Array.isArray(messages) ? messages : []).find((m) => m.role === 'user' && typeof m.content === 'string');
+      cfg = { ...cfg, sessionId: firstUser ? hashKey(firstUser.content) : 'default' };
+      this.cfg = cfg;
+    }
     this.llm = new LLM(cfg);
     this.stopRequested = false;
     this.onApproval = onApproval; // async (toolName, args) => boolean
+    // Shell hooks (Claude Code-style): user-configured commands run at lifecycle
+    // events. ALWAYS stored as a `{ hooks: {Event: [...]} }` config, which is the
+    // shape runShellHooks() reads. A caller may inject one (tests / the TUI,
+    // which reloads per turn); otherwise it is read from disk for this workspace.
+    this.hookConfig = cfg.hookConfig
+      ? (cfg.hookConfig.hooks ? cfg.hookConfig : { hooks: cfg.hookConfig })
+      : { hooks: loadHooks(cfg.workspace).hooks };
+    // The turn's user prompt, for the UserPromptSubmit hook. Set by run().
+    this._turnPrompt = '';
     // Messages the user types while the agent is streaming. They are injected
     // as user messages right AFTER the current round of tool calls, so the
     // model sees "tool callback / user steer" together on the next request —
@@ -147,6 +182,19 @@ export class Agent {
     // block at the end of this method. Both are awaited and both swallow plugin
     // errors (see runHooks), so a broken plugin cannot abort a turn.
     await runHooks('onTurnStart', { messages: this.messages });
+    // SHELL HOOK: SessionStart fires once per agent run (the first turn of a
+    // session). A hook failure never blocks — it is a convenience signal.
+    await runShellHooks(this.hookConfig, 'SessionStart', { messages: this.messages }, this.cfg.workspace);
+    // SHELL HOOK: UserPromptSubmit fires with the latest user message. It cannot
+    // block (Claude Code's can add context; blocking the user's own prompt is a
+    // worse failure than a missing hook), so the result is only logged.
+    {
+      const lastUser = [...this.messages].reverse().find((m) => m.role === 'user' && typeof m.content === 'string');
+      if (lastUser) {
+        this._turnPrompt = lastUser.content;
+        await runShellHooks(this.hookConfig, 'UserPromptSubmit', { prompt: lastUser.content }, this.cfg.workspace);
+      }
+    }
     let text = '';
     let toolCalls = [];
     let emittedEnd = false;
@@ -232,6 +280,10 @@ export class Agent {
       let usedNow = estimateMessagesTokens(this.messages, this.cfg);
       if (maxCtx > 0 && usedNow >= maxCtx * 0.85) {
         const before = usedNow;
+        // SHELL HOOK: PreCompact — a chance to back up the transcript before the
+        // older half is summarized away. Never blocks (the trim must go ahead).
+        await runShellHooks(this.hookConfig, 'PreCompact',
+          { tokens: usedNow, messages: this.messages }, this.cfg.workspace);
         const keepN = Math.max(1, Math.ceil(this.messages.length * 0.2));
         const keep = this.messages.slice(-keepN);
         const dropped = this.messages.slice(0, this.messages.length - keepN);
@@ -389,6 +441,21 @@ export class Agent {
           result = `Error: unknown tool "${tc.name}".`;
           allOk = false;
         } else {
+          // SHELL HOOK: PreToolUse. A non-zero exit blocks the tool, and its
+          // message goes back to the model in place of the tool result — that is
+          // the whole point of a pre-hook (e.g. refuse a write that fails a lint
+          // gate). Checked BEFORE approving/executing so a blocked call never
+          // touches the filesystem.
+          const pre = await runShellHooks(this.hookConfig, 'PreToolUse',
+            { toolName: tc.name, toolArgs: tc.args }, this.ctx.cwd || this.cfg.workspace);
+          if (pre.blocked) {
+            result = `Blocked by a PreToolUse hook: ${pre.reason}`;
+            this.onEvent({ type: 'tool_use', id: tc.id, name: tc.name, args: tc.args });
+            this.messages.push({ role: 'tool', toolCallId: tc.id, content: result });
+            this.onEvent({ type: 'tool_result', id: tc.id, name: tc.name, content: result });
+            allOk = false;
+            continue;
+          }
           if (this.onToolStart) this.onToolStart(tc.name, tc.args);
           this.onEvent({ type: 'tool_use', id: tc.id, name: tc.name, args: tc.args });
           // Plugin hook: onToolExecute fires BEFORE the tool runs and receives the
@@ -404,6 +471,10 @@ export class Agent {
           this.ctx.lastResult = result;
           // Plugin hook: onToolResult fires with the tool's output.
           await runHooks('onToolResult', tc.name, result, this.ctx);
+          // SHELL HOOK: PostToolUse. Never blocks (the tool already ran); a
+          // failure is logged. This is where "format after every edit" lives.
+          await runShellHooks(this.hookConfig, 'PostToolUse',
+            { toolName: tc.name, toolArgs: tc.args, toolResult: result }, this.ctx.cwd || this.cfg.workspace);
           // Surface the live TODO list so the TUI can render its panel.
           if (tc.name === 'TodoList') {
             this.onEvent({ type: 'todos', todos: this.ctx.todoState || [] });
@@ -453,5 +524,9 @@ export class Agent {
     // Plugin lifecycle: the turn is over (normally, interrupted, or out of steps).
     // In a finally-equivalent position — every exit path above reaches here.
     await runHooks('onTurnEnd', { messages: this.messages, stopped: this.stopRequested });
+    // SHELL HOOK: Stop fires when the turn ends, whether it finished or was
+    // interrupted. Never blocks.
+    await runShellHooks(this.hookConfig, 'Stop',
+      { messages: this.messages, stopped: this.stopRequested, prompt: this._turnPrompt }, this.cfg.workspace);
   }
 }

package/src/cache.js

@@ -0,0 +1,130 @@
+// Prompt caching — explicit cache breakpoints for long, stable prefixes.
+//
+// Why this is worth doing: an agent resends the whole conversation every turn,
+// and the prefix (system prompt + tool definitions + early messages) is
+// byte-identical across turns. Providers that support prompt caching bill those
+// tokens at a fraction of the input price and skip the prefill compute. Without
+// explicit breakpoints only the providers that cache automatically benefit.
+//
+// Protocol differences:
+//   * anthropic — explicit: mark up to N breakpoints with
+//     `cache_control: { type: "ephemeral" }`. Anthropic caches everything UP TO
+//     and INCLUDING a marked block, so the LAST breakpoint should sit at the end
+//     of the stable prefix. The minimum cacheable prefix is model-dependent
+//     (~1024 tokens); marking a shorter prefix is a no-op, not an error.
+//   * openai — automatic for prompts over ~1024 tokens on supporting models. A
+//     stable `prompt_cache_key` improves routing; keys must not vary per request.
+//   * everything else — no-op. Unknown providers are left untouched: sending an
+//     unsupported `cache_control` field can 400 some gateways.
+//
+// The cache is only useful when the prefix is STABLE, so the helpers here take
+// care to mark the same positions every turn for the same conversation.
+
+import { estimateTokens } from './term.js';
+
+// Anthropic allows at most 4 cache breakpoints per request.
+export const MAX_BREAKPOINTS = 4;
+// Below this, a breakpoint is pointless: most providers will not cache a prefix
+// this short, and the marker is wasted budget.
+export const MIN_CACHEABLE_TOKENS = 1024;
+
+export function supportsCaching(protocol) {
+  return protocol === 'anthropic' || protocol === 'openai';
+}
+
+// Index (into `messages`) of the last message that belongs to the STABLE prefix.
+//
+// The prefix is only cacheable while it cannot change between turns. The system
+// prompt and tool list are fixed for a session; the conversation then grows by
+// APPENDING. So the prefix is "everything except the recent tail", and the tail
+// must be excluded because it is what changes next turn.
+//
+// We keep the last `keepTail` messages out of the cached region: a tool result
+// appended this turn is not part of the stable prefix next turn until it is
+// itself superseded. Returns -1 when there is nothing worth marking.
+export function stablePrefixEnd(messages, keepTail = 2) {
+  const n = Array.isArray(messages) ? messages.length : 0;
+  if (n === 0) return -1;
+  // Never mark the very last message: it is the newest content and is the most
+  // likely to be replaced/regenerated.
+  const end = Math.min(n - 1, n - 1 - Math.max(1, keepTail));
+  return end >= 0 ? end : -1;
+}
+
+// Attach Anthropic `cache_control` breakpoints to a request body IN PLACE-safe
+// fashion (returns a new body). Breakpoints are placed:
+//   1. on the LAST tool definition (caches the whole tool block),
+//   2. on the system prompt (caches tools + system together),
+//   3. on the last message of the stable prefix (caches the conversation head).
+// Marking the tail first and working backwards keeps the total <= MAX_BREAKPOINTS.
+export function withAnthropicCache(body, opts = {}) {
+  if (!body || typeof body !== 'object') return body;
+  const minTokens = opts.minTokens || MIN_CACHEABLE_TOKENS;
+  const out = { ...body };
+  const marker = { type: 'ephemeral' };
+
+  // Tools: marking the last one caches the entire tools array.
+  if (Array.isArray(out.tools) && out.tools.length) {
+    const tools = out.tools.slice();
+    tools[tools.length - 1] = { ...tools[tools.length - 1], cache_control: marker };
+    out.tools = tools;
+  }
+
+  // System: a plain string must become a text block to carry cache_control.
+  if (typeof out.system === 'string' && out.system.trim()) {
+    out.system = [{ type: 'text', text: out.system, cache_control: marker }];
+  } else if (Array.isArray(out.system) && out.system.length) {
+    const sys = out.system.slice();
+    const last = sys.length - 1;
+    sys[last] = { ...(typeof sys[last] === 'string' ? { type: 'text', text: sys[last] } : sys[last]), cache_control: marker };
+    out.system = sys;
+  }
+
+  // Conversation head: mark the stable prefix's last message.
+  if (Array.isArray(out.messages) && out.messages.length) {
+    const end = stablePrefixEnd(out.messages, opts.keepTail);
+    if (end >= 0 && end < out.messages.length) {
+      // Only worth a breakpoint once the prefix is long enough to cache.
+      const prefixText = out.messages.slice(0, end + 1)
+        .map((m) => (typeof m.content === 'string' ? m.content
+          : Array.isArray(m.content) ? m.content.map((b) => b.text || '').join('') : ''))
+        .join('\n');
+      if (estimateTokens(prefixText) >= minTokens) {
+        const msgs = out.messages.slice();
+        const msg = { ...msgs[end] };
+        if (typeof msg.content === 'string') {
+          msg.content = [{ type: 'text', text: msg.content }];
+        }
+        if (Array.isArray(msg.content) && msg.content.length) {
+          const c = msg.content.slice();
+          const li = c.length - 1;
+          c[li] = { ...c[li], cache_control: marker };
+          msg.content = c;
+        }
+        msgs[end] = msg;
+        out.messages = msgs;
+      }
+    }
+  }
+  return out;
+}
+
+// OpenAI-compatible: most providers cache automatically. A STABLE
+// `prompt_cache_key` helps routing on the providers that accept it, and must not
+// change between turns of the same conversation or the cache thrashes.
+// `seed` should therefore identify the SESSION, not the request.
+export function withOpenAiCache(body, opts = {}) {
+  if (!body || typeof body !== 'object') return body;
+  const key = opts.sessionKey;
+  if (!key) return body;
+  return { ...body, prompt_cache_key: String(key) };
+}
+
+// Apply the right caching strategy for `protocol`. Returns the body unchanged
+// for protocols with no explicit support.
+export function applyPromptCache(protocol, body, opts = {}) {
+  if (!opts.enabled) return body;
+  if (protocol === 'anthropic') return withAnthropicCache(body, opts);
+  if (protocol === 'openai') return withOpenAiCache(body, opts);
+  return body;
+}

package/src/ci.js

@@ -0,0 +1,244 @@
+// CI / scripting integration — turning a headless run into something a pipeline
+// can act on.
+//
+// `hncode -p "…"` already prints the reply. What a CI job additionally needs is:
+//   * a machine-readable final result (did it succeed? what changed?),
+//   * an exit code that reflects the OUTCOME, not just "the process started",
+//   * a stable JSON envelope it can parse without scraping prose.
+//
+// The formats (chosen to match what CI systems and Claude-Code-style tools
+// already understand):
+//   text        — the assistant's reply, as before (default)
+//   json        — ONE object at the end: { ok, reply, toolCalls, files, error }
+//   stream-json — one JSON event per line as the run progresses (existing), now
+//                 terminated by a final `result` event so a reader can stop.
+//
+// Exit codes (see EXIT):
+//   0  the run completed and produced an answer
+//   1  generic failure (LLM error, bad config)
+//   2  configuration problem (no API key)
+//   3  the model stopped without an answer / reported a blocker
+//   4  interrupted
+//
+// Nothing here writes to stdout directly except through the helpers, so the
+// caller stays in control of framing.
+
+import net from 'node:net';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const EXIT = {
+  OK: 0,
+  FAILURE: 1,
+  CONFIG: 2,
+  NO_ANSWER: 3,
+  INTERRUPTED: 4,
+};
+
+export const FORMATS = ['text', 'json', 'stream-json'];
+
+export function isValidFormat(f) {
+  return f == null || FORMATS.includes(f);
+}
+
+// Build the structured result for a finished run.
+//   ok        — completed with a usable answer
+//   reply     — the assistant's final text
+//   toolCalls — names of tools invoked, in order
+//   files     — files the run wrote/edited (from tool ARGS, best-effort)
+//   error     — a fatal error message, when the run failed outright
+//   stopped   — the turn was interrupted
+export function buildResult({ reply, toolCalls, files, error, stopped, durationMs, model, sessionId }) {
+  const hasReply = typeof reply === 'string' && reply.trim().length > 0;
+  const ok = !error && !stopped && hasReply;
+  const result = {
+    ok,
+    reply: reply || '',
+    toolCalls: toolCalls || [],
+    files: files || [],
+    durationMs: durationMs || 0,
+    model: model || '',
+    sessionId: sessionId || '',
+  };
+  if (error) result.error = String(error);
+  if (stopped) result.stopped = true;
+  return result;
+}
+
+// Map a result to a process exit code.
+export function exitCodeFor(result, hadConfigError) {
+  if (hadConfigError) return EXIT.CONFIG;
+  if (!result) return EXIT.FAILURE;
+  if (result.stopped) return EXIT.INTERRUPTED;
+  if (result.error) return EXIT.FAILURE;
+  if (!result.ok) return EXIT.NO_ANSWER;
+  return EXIT.OK;
+}
+
+// The JSON envelope printed at the end in `json` mode. Single line so a shell
+// can capture it with `tail -1` or `jq`.
+export function resultLine(result) {
+  return JSON.stringify({ type: 'result', ...result });
+}
+
+// Collect tool activity from an agent event stream. `onEvent` is called per
+// event; this returns the mutable accumulators the caller reads at the end.
+export function createRunTracker() {
+  return { toolCalls: [], files: [], errors: [], text: '' };
+}
+
+// Files a tool call will write, taken from its arguments. Only the mutating
+// tools are considered: a Read of a file is not "changed by this run".
+const WRITE_TOOLS = new Set(['Write', 'Edit']);
+
+export function trackEvent(tracker, e) {
+  if (!tracker || !e) return tracker;
+  if (e.type === 'data' && e.text) tracker.text += e.text;
+  if (e.type === 'tool_use' && e.name) {
+    tracker.toolCalls.push(e.name);
+    if (WRITE_TOOLS.has(e.name) && e.args && typeof e.args.path === 'string') {
+      if (!tracker.files.includes(e.args.path)) tracker.files.push(e.args.path);
+    }
+  }
+  if (e.type === 'error') tracker.errors.push((e.error && e.error.message) || String(e.error));
+  return tracker;
+}
+
+// The final assistant text for the run. Prefers the LAST assistant message that
+// has text (the handoff), falling back to the streamed aggregate. Mirrors the
+// rule subagents use, so both report the same thing.
+export function finalReply(messages, streamedText) {
+  const msgs = Array.isArray(messages) ? messages : [];
+  for (let i = msgs.length - 1; i >= 0; i--) {
+    const m = msgs[i];
+    if (m && m.role === 'assistant' && typeof m.content === 'string' && m.content.trim()) {
+      return m.content.trim();
+    }
+  }
+  return String(streamedText || '').trim();
+}
+
+// --- remote control ----------------------------------------------------------
+// A running hncode TUI can expose a small control surface (a unix socket /
+// named pipe) so another process can queue a prompt or query status. This is
+// what "remote control" means here: not a network server by default, a local
+// endpoint the user opts into.
+//
+// The protocol is newline-delimited JSON, one request per line, one response
+// per line:  {"op":"prompt","text":"…"}  ->  {"ok":true}
+//            {"op":"status"}             ->  {"ok":true,"busy":false,"session":"…"}
+
+export function defaultControlPath() {
+  if (process.env.HNCODE_CONTROL_SOCKET) return process.env.HNCODE_CONTROL_SOCKET;
+  if (process.platform === 'win32') {
+    // Windows has no unix sockets at a filesystem path: Node exposes named pipes
+    // under \\.\pipe\. Using a normal temp path there fails with EACCES, which is
+    // exactly what happened before this branch existed.
+    return `\\\\.\\pipe\\hncode-control-${process.pid}`;
+  }
+  return path.join(os.homedir(), '.hncode', 'control.sock');
+}
+
+// Start a control server. `handlers` is { prompt(text), status(), interrupt() }.
+// Returns { server, path, close() }. A stale socket file is replaced; a live one
+// makes the call fail so two TUIs cannot fight over it.
+export function startControlServer(handlers, opts = {}) {
+  const sockPath = opts.path || defaultControlPath();
+  const isPipe = process.platform === 'win32' && sockPath.startsWith('\\\\');
+  if (!isPipe) {
+    try { fs.mkdirSync(path.dirname(sockPath), { recursive: true }); } catch { /* exists */ }
+    // Remove a stale socket (a crash leaves one behind). Windows named pipes
+    // disappear with the process and cannot be stat()ed, hence the guard above.
+    try {
+      const st = fs.statSync(sockPath);
+      if (st.isSocket() || st.isFIFO()) fs.unlinkSync(sockPath);
+    } catch { /* nothing to clean */ }
+  }
+
+  const server = net.createServer((conn) => {
+    let buf = '';
+    conn.on('data', (d) => {
+      buf += d.toString('utf8');
+      let i;
+      while ((i = buf.indexOf('\n')) >= 0) {
+        const line = buf.slice(0, i).trim();
+        buf = buf.slice(i + 1);
+        if (!line) continue;
+        handleControlLine(line, handlers).then((res) => {
+          try { conn.write(JSON.stringify(res) + '\n'); } catch { /* peer gone */ }
+        });
+      }
+    });
+    conn.on('error', () => { /* client hung up */ });
+  });
+
+  return new Promise((resolve) => {
+    server.on('error', (e) => resolve({ server: null, path: sockPath, error: e.message, close() {} }));
+    server.listen(sockPath, () => {
+      resolve({
+        server,
+        path: sockPath,
+        error: null,
+        close() {
+          try { server.close(); } catch { /* already closed */ }
+          if (!isPipe) { try { fs.unlinkSync(sockPath); } catch { /* already gone */ } }
+        },
+      });
+    });
+  });
+}
+
+async function handleControlLine(line, handlers) {
+  let req;
+  try { req = JSON.parse(line); } catch { return { ok: false, error: 'invalid JSON' }; }
+  try {
+    if (req.op === 'status') return { ok: true, ...(await handlers.status()) };
+    if (req.op === 'prompt') {
+      if (typeof req.text !== 'string' || !req.text.trim()) return { ok: false, error: 'text required' };
+      await handlers.prompt(req.text);
+      return { ok: true };
+    }
+    if (req.op === 'interrupt') {
+      await handlers.interrupt();
+      return { ok: true };
+    }
+    return { ok: false, error: `unknown op: ${req.op}` };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+}
+
+// Client side: send one request to a running control server. Returns the parsed
+// response or { ok:false, error }. Never throws.
+export async function sendControl(req, opts = {}) {
+  const sockPath = opts.path || defaultControlPath();
+  const timeoutMs = opts.timeoutMs || 10_000;
+  return new Promise((resolve) => {
+    let done = false;
+    let sock = null;
+    const finish = (r) => {
+      if (done) return;
+      done = true;
+      try { if (sock) sock.destroy(); } catch { /* already gone */ }
+      resolve(r);
+    };
+    try { sock = net.connect(sockPath); }
+    catch (e) { resolve({ ok: false, error: e.message }); return; }
+    const timer = setTimeout(() => finish({ ok: false, error: 'timeout' }), timeoutMs);
+    sock.on('connect', () => {
+      try { sock.write(JSON.stringify(req) + '\n'); }
+      catch (e) { clearTimeout(timer); finish({ ok: false, error: e.message }); }
+    });
+    let buf = '';
+    sock.on('data', (d) => {
+      buf += d.toString('utf8');
+      const i = buf.indexOf('\n');
+      if (i >= 0) {
+        clearTimeout(timer);
+        try { finish(JSON.parse(buf.slice(0, i))); } catch { finish({ ok: false, error: 'bad response' }); }
+      }
+    });
+    sock.on('error', (e) => { clearTimeout(timer); finish({ ok: false, error: e.message }); });
+  });
+}

package/src/colors.js

@@ -88,6 +88,16 @@ export const C = {
   // first attempt and read as plain GREEN — its red channel is lifted to 95 and
   // green pins at 255, which is a spring green, not a green-tinted cyan.
   spring: TRUECOLOR ? rgb(0, 215, 175) : '\x1b[38;5;43m',
+  // Git branch in the status line: yellow pulled about half way toward white, so
+  // it stays clearly "yellow" (not cream/ivory) while reading brighter than the
+  // plain 93 yellow on a dark background. rgb(255,219,110) keeps red at max,
+  // green near it, and blue around 43% — that ratio is what keeps the hue
+  // yellow rather than dropping into orange.
+  branch: TRUECOLOR ? rgb(255, 219, 110) : '\x1b[38;5;222m',
+  // Shell-mode (`!`) accent — violet, matching kimi-code's shellMode token so the
+  // bash-mode editor border and the `!` read as "shell", distinct from the cyan
+  // prompt and the yellow git badge. #BD93F9 dark / #7C3AED light.
+  shellMode: TRUECOLOR ? rgb(189, 147, 249) : '\x1b[38;5;141m',
   bgRed: '\x1b[41m',
   bgGreen: '\x1b[42m',
   // Selection highlight (mouse text selection) and the scrollbar gutter.
@@ -168,6 +178,14 @@ export function setTheme(name) {
   if (t.green)  C.green  = rgb(...t.green);
   if (t.yellow) C.yellow = rgb(...t.yellow);
   if (t.orange) C.orange = rgb(...t.orange);
+  // The git branch colour is derived per theme: the pale yellow that reads well
+  // on the dark background is nearly invisible on white, so on a light theme it
+  // is darkened (keeping the same hue) instead of being left as-is.
+  if (t.bg && t.bg[0] > 128) {
+    C.branch = rgb(146, 106, 0);           // dark amber for light backgrounds
+  } else {
+    C.branch = TRUECOLOR ? rgb(255, 219, 110) : '\x1b[38;5;222m';
+  }
 
   return true;
 }

package/src/config.js

@@ -286,6 +286,13 @@ const b = baseUrl.replace(/\/+$/, '');
     autoUpdate: process.env.HNCODE_AUTO_UPDATE
       ? /^(1|true|yes|on)$/i.test(process.env.HNCODE_AUTO_UPDATE)
       : (root.auto_update === true || root.auto_update === 'true'),
+    // PROMPT CACHE (/cache): explicit cache breakpoints for long stable prefixes.
+    // Default ON — it only ever adds provider-recognised markers, and an
+    // unsupported field on a non-caching gateway is filtered out in cache.js.
+    // Set HNCODE_PROMPT_CACHE=0 or `prompt_cache = false` to disable.
+    promptCache: process.env.HNCODE_PROMPT_CACHE
+      ? /^(1|true|yes|on)$/i.test(process.env.HNCODE_PROMPT_CACHE)
+      : (root.prompt_cache === false || root.prompt_cache === 'false' ? false : true),
     raw: root,
   };
 }