@hncode/hncode 0.1.11 → 0.3.0

package/README.md

@@ -67,6 +67,7 @@ hncode draws inspiration from several excellent projects:
 
 - **[Kimi Code](https://github.com/MoonshotAI/kimi-code)** - The original cyan-blue TUI coding agent that inspired this project's design and approach
 - **[Claude Code](https://github.com/anthropics/claude-code)** - The conversation flow and tool interaction patterns
+- **[Codex](https://github.com/openai/codex)** - Several behaviours were shaped by reading its open-source implementation: the AGENTS.md loading spec, the rule against spawning subagents unprompted, the plan-tool state machine, the review rubric, and parts of the system prompt
 
 Special thanks to the communities behind these projects for pushing the boundaries of AI-assisted coding.
 

package/README_CN.md

@@ -65,8 +65,10 @@ npx @hncode/hncode
 
 hncode 从以下几个优秀项目中汲取了灵感：
 
+- **[Kimi Code](https://github.com/MoonshotAI/kimi-code)** - 原始的青色蓝调终端界面 AI 编程助手，启发了本项目的设计和理念
 - **[Kimi Code](https://github.com/MoonshotAI/kimi-code)** - 原始的青色蓝调终端界面 AI 编程助手，启发了本项目的设计和理念
 - **[Claude Code](https://github.com/anthropics/claude-code)** - 对话流程和工具交互模式
+- **[Codex](https://github.com/openai/codex)** - 通过阅读其开源实现，本项目确定了几处行为：AGENTS.md 的加载规则、未获明确许可不得开启子代理、计划工具的状态流转约束、代码审查的判定标准，以及系统提示词的部分内容
 
 特别感谢这些项目背后的社区，它们推动了 AI 辅助编程的边界。
 

package/bin/install.js

@@ -74,7 +74,7 @@ try {
     // Windows: Use PowerShell to refresh environment
     const { execSync } = require('child_process');
     try {
-      execSync('Refresh-Environment', { stdio: 'pipe' });
+      execSync('$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User");', { stdio: 'pipe' });
       console.log('✓ Environment refreshed automatically (PowerShell)');
     } catch (e) {
       console.log('ℹ️  To refresh environment in PowerShell:');

package/package.json

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

package/src/agent-task.js

@@ -0,0 +1,178 @@
+// Background task registry — the single place tasks are created, listed, stopped
+// and read. Mirrors kimi-code's task model:
+//
+//   TaskInfo = base fields + a `kind`-discriminated payload
+//     kind 'process'  -> { command, pid, exitCode }        (Bash run_in_background)
+//     kind 'agent'    -> { agentId, subagentType, model, thinkingEffort }  (Agent)
+//     kind 'question' -> { questionCount, toolCallId }     (AskUserQuestion bg)
+//
+// Statuses match kimi exactly so the UI can share one vocabulary:
+//   running | completed | failed | timed_out | killed | lost
+//
+// Bash used to keep its own ad-hoc objects ('done'/'failed', `id`, `start`), which
+// is why the task panel could not show the same fields as kimi's. Everything now
+// goes through `createTask`, so a task always has the same shape no matter which
+// tool spawned it.
+
+export const TERMINAL_STATUSES = new Set(['completed', 'failed', 'timed_out', 'killed', 'lost']);
+
+export function isTerminal(status) {
+  return TERMINAL_STATUSES.has(status);
+}
+
+// `{prefix}-{8 chars}` like kimi's VALID_TASK_ID. Unique even for two tasks
+// created in the same millisecond (a bare Date.now() collided).
+let seq = 0;
+export function newTaskId(prefix = 'task') {
+  seq = (seq + 1) % 1e9;
+  const rand = Math.random().toString(36).slice(2, 10).padEnd(8, '0');
+  const s = String(seq).padStart(4, '0');
+  return `${prefix}-${(Date.now().toString(36) + s).slice(-8)}-${rand}`;
+}
+
+// Decode a task's buffered chunks for display. Buffer chunks (Bash) are UTF-8;
+// string chunks (Agent/AgentSwarm) are already text.
+function decodeTaskOutput(chunks) {
+  const list = chunks || [];
+  if (!list.length) return '';
+  const allStrings = list.every((c) => typeof c === 'string');
+  if (allStrings) return list.join('');
+  try { return Buffer.concat(list.map((c) => (Buffer.isBuffer(c) ? c : Buffer.from(String(c))))).toString('utf8'); }
+  catch { return list.map((c) => String(c)).join(''); }
+}
+
+// The task store lives on the agent ctx (`ctx.tasks`), so every tool and the TUI
+// see the same map.
+function store(ctx) {
+  if (!ctx) return {};
+  if (!ctx.tasks) ctx.tasks = {};
+  return ctx.tasks;
+}
+
+/**
+ * Register a task. `kind` selects the payload group; the returned object is the
+ * live record (mutate `status`/`endedAt`/`stopReason` as it runs).
+ *
+ * options:
+ *   description  short human label
+ *   detached     true when it runs in the background (Ctrl+B or run_in_background)
+ *   timeoutMs    optional cap
+ *   command/pid/exitCode            (kind 'process')
+ *   agentId/subagentType/model/thinkingEffort  (kind 'agent')
+ *   questionCount/toolCallId        (kind 'question')
+ *   output       initial output text
+ */
+export function createTask(ctx, kind, options = {}) {
+  const tasks = store(ctx);
+  const prefix = kind === 'process' ? 'bash' : kind === 'agent' ? 'agent' : 'question';
+  const task = {
+    taskId: newTaskId(prefix),
+    kind,
+    description: String(options.description || ''),
+    status: 'running',
+    detached: options.detached !== false,
+    startedAt: Date.now(),
+    endedAt: null,
+    stopReason: undefined,
+    timeoutMs: options.timeoutMs,
+    // Output is buffered here and exposed through `output` below. Kept as chunks
+    // so the decoder can run lazily (a chatty task costs nothing until read).
+    _chunks: options._chunks || [],
+    _bytes: 0,
+  };
+  if (kind === 'process') {
+    task.command = String(options.command || '');
+    task.pid = options.pid || 0;
+    task.exitCode = null;
+  } else if (kind === 'agent') {
+    task.agentId = options.agentId;
+    task.subagentType = options.subagentType;
+    task.model = options.model;
+    task.thinkingEffort = options.thinkingEffort;
+  } else if (kind === 'question') {
+    task.questionCount = options.questionCount || 0;
+    task.toolCallId = options.toolCallId;
+  }
+  // Every task exposes its buffered output through `output`. The chunks are
+  // stored raw and decoded lazily:
+  //   * a process appends Buffer chunks -> decode as UTF-8
+  //   * an agent/swarm appends strings  -> join
+  // Callers may override this getter when they need a different decoding.
+  Object.defineProperty(task, 'output', {
+    enumerable: true,
+    configurable: true,
+    get() { return decodeTaskOutput(this._chunks); },
+  });
+  tasks[task.taskId] = task;
+  return task;
+}
+
+// Cap retained output per task; a runaway command must not exhaust memory.
+export const MAX_TASK_OUTPUT_BYTES = 2 * 1024 * 1024;
+
+// Append raw bytes/chunks to a task, trimming the oldest past the cap.
+export function appendTaskOutput(task, chunk) {
+  if (!task || chunk == null) return;
+  task._chunks.push(chunk);
+  task._bytes = (task._bytes || 0) + (chunk.length || 0);
+  while (task._bytes > MAX_TASK_OUTPUT_BYTES && task._chunks.length > 1) {
+    task._bytes -= task._chunks[0].length || 0;
+    task._chunks.shift();
+  }
+}
+
+// Settle a task. `status` is one of the kimi statuses; a task that was already
+// stopped keeps 'killed' (mirrors kimi: a deliberate stop must not be relabelled
+// as a failure by the process's non-zero exit).
+export function settleTask(task, status, extra = {}) {
+  if (!task) return;
+  // A task that already reached a TERMINAL state must not be relabelled: a
+  // deliberate stop ('killed') must not turn into 'failed' when the killed
+  // process reports a non-zero exit, and a 'completed' task must not be
+  // downgraded by a late error. Only a still-running task settles.
+  if (isTerminal(task.status)) {
+    if (extra.exitCode !== undefined && task.kind === 'process') task.exitCode = extra.exitCode;
+    return;
+  }
+  task.status = status;
+  task.endedAt = Date.now();
+  if (extra.stopReason !== undefined) task.stopReason = extra.stopReason;
+  if (extra.exitCode !== undefined && task.kind === 'process') task.exitCode = extra.exitCode;
+}
+
+export function listTasks(ctx) {
+  return Object.values(store(ctx));
+}
+
+export function getTask(ctx, id) {
+  return store(ctx)[id] || null;
+}
+
+// Newest-first for display (mirrors kimi's compareTasks: running first, then by
+// most recent activity).
+export function sortedTasks(ctx) {
+  const tasks = listTasks(ctx);
+  return tasks.slice().sort((a, b) => {
+    const at = isTerminal(a.status), bt = isTerminal(b.status);
+    if (at !== bt) return at ? 1 : -1;
+    if (!at) return a.startedAt - b.startedAt;
+    return (b.endedAt || b.startedAt) - (a.endedAt || a.startedAt);
+  });
+}
+
+// Human label for a status, matching kimi's STATUS_LABEL.
+export const STATUS_LABEL = {
+  running: 'running',
+  completed: 'completed',
+  failed: 'failed',
+  timed_out: 'timed out',
+  killed: 'killed',
+  lost: 'lost',
+};
+
+// Colour token for a status (the TUI maps it to a theme colour).
+export function statusColor(status) {
+  if (status === 'running') return 'green';
+  if (status === 'completed') return 'gray';
+  return 'red';
+}

package/src/agent.js

@@ -4,7 +4,9 @@
 
 import { LLM, setToolsList } from './llm.js';
 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';
 
 // ---- completion guard --------------------------------------------------------
 // A turn is only complete when the model ends it with an actual answer. Models
@@ -33,10 +35,40 @@ Tools:
 - If a tool fails, read the error and fix your approach. After 2 failed attempts on the same goal, stop and report the blocker.
 - Independent tool calls may run in parallel; never parallelize dependent ones.
 
+Reasoning:
+- Put ALL of your internal reasoning inside <think>...</think> tags, and always emit BOTH the opening
+  and the closing tag. Do not omit the tags, do not abbreviate them, and do not leave the block unclosed.
+- Everything outside <think>...</think> is what the user reads: keep it to the answer itself — what you
+  did and what you found. Never repeat or summarise your reasoning there.
+- Keep the tags exactly as written: <think> and </think>. Do not emit any other variant.
+Acting:
+- Unless the user is explicitly asking for a plan, asking a question about the code, or brainstorming,
+  assume they want the work DONE. Say less and do more: implement the change rather than describing it.
+- Carry the task through implementation and verification in this turn. Do not stop at analysis, at a
+  partial fix, or at a list of things you would do next.
+- New project, no prior context: be ambitious, use your judgement on structure.
+  Existing codebase: be surgical. Touch only what the task needs — no renames, no reorganising,
+  no drive-by fixes.
+- Read the neighbours before you write: match the naming, error handling and comment density you see.
+- Do not re-read a file after editing it, and do not re-run a search you already have results for.
+  A successful edit tool call already proves it worked.
+
 Scope:
 - Do only what was asked. Do not refactor or "improve" unrelated code.
+- Do not fix unrelated bugs or broken tests — mention them instead; they are not yours to change.
 - If the request is ambiguous, ask one short clarifying question.
 - State any assumption you make.
+- Might be a dirty git worktree. Never revert changes you did not make. Never run a destructive command
+  (git reset --hard, git checkout --) unless the user asked for it. If you notice an unexpected change
+  you did not make, stop and ask.
+
+Verifying:
+- Run the narrowest check that exercises your change first, then widen.
+- In auto/yolo mode, run tests and lint yourself without asking.
+- In ask mode, do not burn the user's time on slow test suites mid-task: say what you would run and
+  let them confirm.
+- Do not add tests to a codebase that has none. Do not add a formatter that the project did not configure.
+- If you could not verify something, say so plainly. Do not imply a test passed when you did not run it.
 
 Finishing:
 - Never stop silently after a tool call; end every turn with a written answer in the user's language.
@@ -56,10 +88,18 @@ export class Agent {
     // Ensure the LLM client knows the bare tool specs (the client wraps them per-protocol).
     // A toolFilter (array of tool names) limits which tools are exposed — used
     // by Plan mode (read-only subset) and Focus mode (minimal subset first).
-    const filtered = Array.isArray(cfg.toolFilter) && cfg.toolFilter.length
+    // `cfg.noDelegation` marks this as a SUBAGENT: delegation tools are removed
+    // even if the filter would have allowed them. The catalog already excludes
+    // them from every profile; this is the hard backstop that also covers the
+    // `null` (= everything) case, so a subagent can never spawn another agent.
+    const filtered = (Array.isArray(cfg.toolFilter) && cfg.toolFilter.length
       ? tools.filter((t) => cfg.toolFilter.includes(t.name))
-      : tools;
+      : tools
+    ).filter((t) => !(cfg.noDelegation && DELEGATION_TOOLS.includes(t.name)));
     setToolsList(filtered);
+    // A block for the direct-call path too: the model can still emit a tool call
+    // for a tool that is not exposed, so refuse it here rather than at execution.
+    this.noDelegation = !!cfg.noDelegation;
     // AbortSignal handed to every tool so a long-running one (Bash) is killed
     // when the user presses Esc / Ctrl-C — otherwise the command keeps running
     // after the turn was interrupted.
@@ -72,6 +112,12 @@ export class Agent {
     this.ctx.onOutput = (chunk) => {
       if (chunk && this._currentToolId) this.onEvent({ type: 'tool_output', id: this._currentToolId, chunk });
     };
+    // `fork` (the Agent tool) snapshots THIS conversation into the subagent. The
+    // tool reads `ctx._parentMessages`, which nothing ever set — so `fork: true`
+    // was accepted and then seeded the subagent with an empty history. Hand the
+    // 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;
     this.llm = new LLM(cfg);
     this.stopRequested = false;
     this.onApproval = onApproval; // async (toolName, args) => boolean
@@ -97,14 +143,15 @@ export class Agent {
   }
 
   async run() {
+    // Plugin lifecycle: `onTurnStart` fires here and `onTurnEnd` in the finally
+    // 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 });
     let text = '';
     let toolCalls = [];
     let emittedEnd = false;
-    // Reasoning text seen in the current step. A turn that ends with reasoning
-    // but no answer is a truncated turn (see the completion guard below).
     let thought = '';
     let nudges = 0;
-    // True when the most recent iteration still had tool calls pending; used to
     // decide whether running out of steps actually left the turn unfinished.
     let hadToolCallsOnFinalStep = false;
 
@@ -225,7 +272,12 @@ export class Agent {
         }
       }
 
+      // Plugin hooks around the model round-trip. `onBeforeRequest` sees the exact
+      // message array being sent (and may mutate it); `onAfterRequest` fires once
+      // the stream has been consumed.
+      await runHooks('onBeforeRequest', this.messages, this.cfg);
       await this.llm.request(this.messages, handle);
+      await runHooks('onAfterRequest', this.messages, this.cfg);
 
       // An abort ends the turn: keep whatever text arrived, then stop.
       if (this.stopRequested) {
@@ -238,11 +290,17 @@ export class Agent {
       const hasText = !!(text && text.trim());
       const hasCalls = toolCalls.length > 0;
       if (hasText || hasCalls) {
-        this.messages.push({
+        const assistantMsg = {
           role: 'assistant',
           content: hasText ? text : null,
           toolCalls: hasCalls ? toolCalls : undefined,
-        });
+        };
+        this.messages.push(assistantMsg);
+        // Plugin hook: one per assistant message committed to the history. Fired
+        // here (the single point where the model's reply lands) rather than at each
+        // of the eleven `messages.push` sites, so a plugin sees a coherent message
+        // instead of the intermediate bookkeeping pushes.
+        await runHooks('onNewMessage', assistantMsg, this.messages);
       }
 
       // ---- if tool calls exist, execute them ----
@@ -308,6 +366,17 @@ export class Agent {
         }
         
         const tool = getTool(tc.name);
+        // A subagent may not delegate. The tool is not exposed to it, but the model
+        // can still emit a call for a tool it was told about earlier, so refuse it
+        // here with an actionable message instead of running a nested agent.
+        if (this.noDelegation && DELEGATION_TOOLS.includes(tc.name)) {
+          result = `You CAN'T use ${tc.name}: subagents cannot delegate. Do the work yourself and report the result to the agent that started you.`;
+          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 (modeName && !this.cfg.toolFilter.includes(tc.name)) {
           result = `You CAN'T use this tool on ${modeName} Mode. Allowed: ${this.cfg.toolFilter.join(', ')}.`;
           this.onEvent({ type: 'tool_use', id: tc.id, name: tc.name, args: tc.args });
@@ -322,6 +391,10 @@ export class Agent {
         } else {
           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
+          // mutable args object, so a plugin can inspect or adjust a call. Errors
+          // are swallowed by runHooks — a broken plugin must not break a turn.
+          await runHooks('onToolExecute', tc.name, tc.args, this.ctx);
           try {
             result = await tool.execute(tc.args, this.ctx);
           } catch (err) {
@@ -329,15 +402,27 @@ export class Agent {
             allOk = false;
           }
           this.ctx.lastResult = result;
+          // Plugin hook: onToolResult fires with the tool's output.
+          await runHooks('onToolResult', tc.name, result, this.ctx);
           // Surface the live TODO list so the TUI can render its panel.
           if (tc.name === 'TodoList') {
             this.onEvent({ type: 'todos', todos: this.ctx.todoState || [] });
           }
         }
         this.messages.push({ role: 'tool', toolCallId: tc.id, content: result });
-        this.onEvent({ type: 'tool_result', id: tc.id, name: tc.name, content: result });
+        // An Edit reports the text it replaced on ctx (both the substring and the
+        // line-range path do). Forward it so the TUI can draw the +/- diff: the
+        // line-range mode has no `old_string` in its args, so without this the
+        // edit rendered with no diff at all. Cleared every time so a later tool
+        // cannot inherit a stale diff.
+        this.onEvent({
+          type: 'tool_result', id: tc.id, name: tc.name, content: result,
+          editDiff: this.ctx.lastEditDiff || null,
+        });
+        this.ctx.lastEditDiff = null;
       }
 
+
       // Did THIS iteration still have tool calls? If the loop runs out of budget
       // right after running them, the turn really is unfinished.
       hadToolCallsOnFinalStep = toolCalls.length > 0;
@@ -360,5 +445,8 @@ export class Agent {
       });
     }
     if (!emittedEnd && this.onEvent) this.onEvent({ type: 'done' });
+    // 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 });
   }
 }

package/src/colors.js

@@ -57,6 +57,13 @@ export const C = {
   reset: '\x1b[0m',
   bold: '\x1b[1m',
   dim: '\x1b[2m',
+  // Italic (SGR 3). Used for the BODY of a reasoning block — the prose reads as
+  // an aside rather than as the answer. Must be closed with SGR 23 (`endItalic`),
+  // NOT with `reset`, because resetting also drops the surrounding dim/gray that
+  // the same row depends on. Terminals without italic fall back to normal text,
+  // so this is a decoration, never load-bearing.
+  italic: '\x1b[3m',
+  endItalic: '\x1b[23m',
   muted: '\x1b[90m',
   teal: TEAL,
   cyan: CYAN,
@@ -74,6 +81,13 @@ export const C = {
   gray: '\x1b[90m',
   white: '\x1b[97m',
   orange: TRUECOLOR ? rgb(255, 140, 0) : '\x1b[38;5;208m',
+  // Cyan pushed slightly toward green — used for the Swarm mode badge so it reads
+  // as its own mode next to Plan (pure cyan) and Focus (blue) while staying in the
+  // theme's blue-green family. 38;5;43 is rgb(0,215,175): red at zero and green
+  // only 40 above blue, i.e. still clearly cyan with a green cast. 38;5;85 was the
+  // 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',
   bgRed: '\x1b[41m',
   bgGreen: '\x1b[42m',
   // Selection highlight (mouse text selection) and the scrollbar gutter.

package/src/config.js

@@ -62,6 +62,124 @@ export function hncodeConfigFile() {
   return process.env.HNCODE_CONFIG || path.join(home, '.hncode', 'config.toml');
 }
 
+// ---- personal preferences (/personal) ----
+// Free-form markdown the user wants applied on EVERY turn ("reply in Chinese",
+// "I use pnpm", "never add a trailing newline", …). Two scopes are merged, the
+// project one LAST so it can refine the global one:
+//   * global  — ~/.hncode/PERSONAL.md      (every workspace)
+//   * project — <workspace>/.hncode/PERSONAL.md  (this workspace only)
+// Both are OPTIONAL; a missing/empty file injects nothing. The files are read
+// fresh on each turn, so an edit through /personal takes effect immediately.
+export function personalPromptFile(scope, workspace) {
+  if (scope === 'global') return path.join(home, '.hncode', 'PERSONAL.md');
+  return path.join(workspace || process.cwd(), '.hncode', 'PERSONAL.md');
+}
+
+// Header placed before the injected preferences, so the model knows where the
+// text came from and how much authority it has.
+export const PERSONAL_PROMPT_HEADER =
+  'USER PERSONAL PREFERENCES (persistent notes from the user; follow them unless\n'
+  + 'the current request says otherwise):';
+
+// Raw file content for one scope (no header) — used by /personal's editor.
+export function readPersonalPromptRaw(scope, workspace) {
+  try { return fs.readFileSync(personalPromptFile(scope, workspace), 'utf8'); } catch { return ''; }
+}
+
+// Save one scope. Empty text REMOVES the file (so nothing is injected).
+export function writePersonalPrompt(scope, workspace, text) {
+  const file = personalPromptFile(scope, workspace);
+  const value = String(text == null ? '' : text);
+  if (!value.trim()) {
+    try { fs.unlinkSync(file); } catch { /* already gone */ }
+    return file;
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, value.replace(/\s+$/, '') + '\n', 'utf8');
+  return file;
+}
+
+export function readPersonalPrompt(workspace) {
+  const parts = [];
+  for (const scope of ['global', 'project']) {
+    try {
+      const t = fs.readFileSync(personalPromptFile(scope, workspace), 'utf8').trim();
+      if (t) parts.push(t);
+    } catch { /* no file for this scope: nothing to inject */ }
+  }
+  if (!parts.length) return '';
+  return PERSONAL_PROMPT_HEADER + '\n' + parts.join('\n\n');
+}
+
+// ---- AGENTS.md --------------------------------------------------------------
+// Project instruction files, mirroring codex's AGENTS.md spec
+// (codex-rs/core/gpt_5_2_prompt.md, "AGENTS.md spec"):
+//   * a file's scope is the whole directory tree rooted where it sits;
+//   * for every file you touch you must obey the AGENTS.md whose scope covers it;
+//   * more-deeply-nested files take precedence on conflict;
+//   * direct system/user instructions outrank all of them.
+// Files are therefore collected from the workspace root DOWN to the working
+// directory and injected outermost-first, so the deepest one is read last and
+// naturally wins — the same precedence, without a merge step.
+//
+// This closes a real gap: /init WRITES an AGENTS.md and the prompt advertises it
+// as "smarter agent context", but nothing ever read it back.
+const AGENTS_MAX_BYTES = 32 * 1024;
+const AGENTS_FILENAMES = ['AGENTS.md', 'agents.md', 'AGENTS.override.md'];
+
+export const AGENTS_PROMPT_HEADER =
+  'PROJECT INSTRUCTIONS (AGENTS.md). The scope of each file is the directory it sits in,\n'
+  + 'so a deeper file is more specific and takes precedence over a shallower one. They apply\n'
+  + 'to every file you touch under that directory. The current request and the user\'s direct\n'
+  + 'instructions still outrank anything here.'
+
+// Every applicable AGENTS.md, outermost first. `dir` keeps the scope visible.
+export function agentsFilesFor(cwd, workspaceRoot) {
+  const start = path.resolve(cwd || process.cwd());
+  const root = path.resolve(workspaceRoot || start);
+  const dirs = [];
+  let dir = start;
+  for (;;) {
+    dirs.push(dir);
+    const parent = path.dirname(dir);
+    // Stop at the filesystem root, or once we have walked past the workspace.
+    if (parent === dir || dir === root) break;
+    dir = parent;
+  }
+  dirs.reverse();                     // outermost first
+  const found = [];
+  for (const d of dirs) {
+    for (const name of AGENTS_FILENAMES) {
+      const p = path.join(d, name);
+      try {
+        if (!fs.statSync(p).isFile()) continue;
+        found.push({ path: p, dir: d });
+        break;                        // one instruction file per directory
+      } catch { /* not present here */ }
+    }
+  }
+  return found;
+}
+
+// The block injected into the system prompt, or '' when the project has none.
+export function readAgentsMd(cwd, workspaceRoot) {
+  const files = agentsFilesFor(cwd, workspaceRoot);
+  if (!files.length) return '';
+  const parts = [];
+  for (const f of files) {
+    try {
+      let text = fs.readFileSync(f.path, 'utf8').trim();
+      if (!text) continue;
+      if (Buffer.byteLength(text, 'utf8') > AGENTS_MAX_BYTES) {
+        text = Buffer.from(text, 'utf8').subarray(0, AGENTS_MAX_BYTES).toString('utf8') + '\n[truncated]';
+      }
+      parts.push(`--- ${f.path} ---\n${text}`);
+    } catch { /* unreadable: skip rather than fail the turn */ }
+  }
+  if (!parts.length) return '';
+  return AGENTS_PROMPT_HEADER + '\n\n' + parts.join('\n\n');
+}
+
 function loadBaseToml() {
   // Only hncode's own config file participates.
   const f = hncodeConfigFile();
@@ -146,9 +264,19 @@ export function resolveConfig() {
       // Backwards-compat: read legacy cool_mode key if calm_mode is not set.
       : (root.calm_mode === true || root.calm_mode === 'true'
          || root.cool_mode === true || root.cool_mode === 'true'),
+    // SUBAGENT MODEL (/swarm-sub-agent): the model each subagent runs on. Empty
+    // (the default) means "follow this session's model", which is what the Agent
+    // and AgentSwarm tools fall back to. Set from config.toml so it persists.
+    subagentModel: process.env.HNCODE_SUBAGENT_MODEL || root.subagent_model || '',
     // Plugin directory (default: ~/.hncode/plugins). Set to "" or "false" to
     // disable plugin loading entirely.
     pluginDir: process.env.HNCODE_PLUGINS || root.plugins_dir || '',
+    // AUTO-UPDATE (/auto-update): when true, hncode checks npm for a newer
+    // version at startup and then every 30 minutes, installing in the background
+    // without interrupting the session.
+    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'),
     raw: root,
   };
 }

package/src/index.js

@@ -3,7 +3,7 @@
 import os from 'node:os';
 import path from 'node:path';
 import fs from 'node:fs';
-import { resolveConfig, effectiveSnapshot, saveConfig, resolveModelArg } from './config.js';
+import { resolveConfig, effectiveSnapshot, saveConfig, resolveModelArg, readPersonalPrompt } from './config.js';
 import * as sess from './session.js';
 import { Agent, SYSTEM_PROMPT } from './agent.js';
 import { llmTools } from './tools/index.js';
@@ -171,7 +171,12 @@ async function runPrompt({ cfg, prompt, format, session, modelArg }) {
   }
   const messages = [];
   if (session && session.messages) for (const m of session.messages.slice(-30)) messages.push(m);
-  messages.push({ role: 'system', content: SYSTEM_PROMPT });
+  // Same layering as the TUI: built-in prompt first, then the user's own
+  // system_prompt override if any, then the /personal notes, then calm mode.
+  let sysText = (cfg.systemPrompt && String(cfg.systemPrompt).trim()) || SYSTEM_PROMPT;
+  const personal = readPersonalPrompt(cfg.workspace);
+  if (personal) sysText += '\n\n' + personal;
+  messages.push({ role: 'system', content: sysText });
   const saved = session || { id: sess.newId(), title: prompt.slice(0, 60), workspace: path.resolve(process.cwd()), model: cfg.model, createdAt: Date.now(), messages: [] };
   const agent = new Agent({
     cfg,

package/src/plugin.js

@@ -143,8 +143,18 @@ export async function loadPlugins(dir) {
         continue;
       }
 
-      const meta = (mod.default && (mod.default.name || mod.default.meta)) || { name: f };
-      const plugin = { id: f, name: meta.name || f, version: meta.version || '0.0.0' };
+      // Metadata comes from the default export. `name` there is a plain STRING
+      // (`export default { name: 'recorder' }`), so reading `meta.name` off it
+      // returned undefined and the plugin showed up as its FILENAME with version
+      // 0.0.0 — /plugins listed every plugin under the wrong name. Accept both
+      // shapes: a string name, or an object carrying { name, version }.
+      const def = (mod && mod.default) || {};
+      const meta = typeof def === 'string' ? { name: def } : def;
+      const plugin = {
+        id: f,
+        name: meta.name || meta.meta?.name || f,
+        version: meta.version || meta.meta?.version || '0.0.0',
+      };
       loadedPlugins.push(plugin);
       installFn(API);
       // eslint-disable-next-line no-console