@nanhara/hara 0.102.0 → 0.103.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to `@nanhara/hara`.
 > Versioning (pre-1.0, SemVer-style): the **minor** (middle) number bumps for a **new feature**; the
 > **patch** (last) number bumps for **optimizations/fixes of existing features**.
 
+## 0.103.0 — the project-analysis SOP (why hara felt slow on "analyze this repo")
+
+The execution layer could always parallelize reads and fan out read-only sub-agents — but nothing
+TAUGHT the model, so it explored one call per turn. Distilled from codex's prompt discipline and
+Claude Code's Explore-agent pattern:
+
+- **System prompt playbook**: batch independent tool calls in one response (reads execute in
+  parallel); analyzing a project starts with a ONE-batch wide sweep (manifest + README + build/CI
+  config) then narrow grep/glob; more than ~3 searches → fan out `agent` sub-agents, several in one
+  response.
+- **`agent` tool grows WHEN-TO-USE / WHEN-NOT-TO-USE guidance** (CC's heuristic): narrow lookups go
+  to direct tools; open-ended "how does X work across the codebase" goes to sub-agents.
+- **Built-in `explore` persona** — `agent(role:"explore")` works with zero setup: read-only, parallel
+  searches, excerpts not whole files, returns conclusions with path:line refs, never dumps. A
+  user-defined explore role still wins.
+
 ## 0.102.0 — a slow network never feels dead
 
 Jeff + a designer colleague both hit the same thing: press Enter on a slow connection and hara

package/dist/agent/loop.js

@@ -49,7 +49,13 @@ const HARA_SYSTEM = (cwd) => `You are hara, a coding agent running in the user's
 Working directory: ${cwd}
 Be concise and direct. Use the provided tools to read files, edit/write files, and run shell
 commands. Prefer small, verifiable steps; edit existing files with edit_file rather than rewriting
-them whole. For a multi-step task, call \`todo_write\` to plan a short checklist and keep it updated as
+them whole. Batch INDEPENDENT tool calls in a single response — especially reads (read_file / grep /
+glob / ls run in PARALLEL when requested together); one-call-per-turn exploration is the slowest thing
+you can do. When analyzing a project, start wide in ONE batch — manifest (package.json / Cargo.toml /
+pyproject.toml / go.mod), README, build/CI config — then chase only what the task needs with narrow
+grep/glob; don't read whole large files when a targeted search answers the question. For broad,
+open-ended exploration (more than ~3 searches), spawn \`agent\` sub-agents — several in one response for
+independent questions (role "explore") — each returns conclusions, not dumps. For a multi-step task, call \`todo_write\` to plan a short checklist and keep it updated as
 you go (one item in_progress at a time) — skip it for trivial one-step tasks. You have a persistent
 memory: use memory_search before answering about prior decisions,
 conventions, or the user's preferences, and memory_write to proactively save durable facts you learn.

package/dist/index.js

@@ -36,6 +36,7 @@ import { addJob, removeJob, setEnabled, resolveJob, loadJobs, recordRun, logPath
 import { runTick, runJobOnce, selfArgv } from "./cron/runner.js";
 import { installScheduler, uninstallScheduler, isInstalled } from "./cron/install.js";
 import { getTools } from "./tools/registry.js";
+import { EXPLORE_SYSTEM } from "./tools/agent.js";
 import { createAnthropicProvider } from "./providers/anthropic.js";
 import { createOpenAIProvider } from "./providers/openai.js";
 import { qwenDeviceLogin, getValidQwenAuth } from "./providers/qwen-oauth.js";
@@ -765,6 +766,9 @@ async function maybeAutoCompact(provider, history, meta, stats, cfg, notify) {
 async function runSubagent(cfg, baseProvider, cwd, sandbox, projectContext, stats, task, roleId) {
     const roles = loadRoles(cwd);
     const role = roleId ? roles.find((r) => r.id === roleId) : undefined;
+    // Built-in explore persona: `agent(role:"explore")` works with ZERO user setup (a user-defined
+    // explore role still wins — it was found above and carries its own system).
+    const builtinSystem = !role && roleId === "explore" ? EXPLORE_SYSTEM : undefined;
     const __subModel = effectiveRoleModel(role?.model, cfg.model);
     const provider = __subModel ? ((await buildProvider({ ...cfg, model: __subModel })) ?? baseProvider) : baseProvider;
     // A sub-agent runs full-auto + UNCONFIRMED + parallel, so it is ALWAYS read-only — a role may narrow
@@ -780,7 +784,7 @@ async function runSubagent(cfg, baseProvider, cwd, sandbox, projectContext, stat
         projectContext,
         memory: memoryDigest(cwd),
         stats,
-        systemOverride: role?.system,
+        systemOverride: role?.system ?? builtinSystem,
         toolFilter,
         quiet: true,
     });

package/dist/tools/agent.js

@@ -2,11 +2,24 @@
 // turn run in PARALLEL (kind "read" → concurrent), making the footer's ⛁ count real. Sub-agents are
 // read-only by default (safe to parallelize); the actual spawn is provided via ctx.spawn.
 import { registerTool } from "./registry.js";
+/** Built-in persona for `role: "explore"` (no setup needed — index.ts falls back to this when the
+ *  user hasn't defined an explore role). Claude-Code's Explore-agent playbook: read-only, parallel,
+ *  excerpts-not-files, conclusions-not-dumps. */
+export const EXPLORE_SYSTEM = "You are a fast, READ-ONLY codebase explorer. Navigate with grep/glob/ls/read_file and be quick: " +
+    "issue your searches and file reads as MULTIPLE PARALLEL tool calls in one round whenever they are " +
+    "independent — never one-per-turn. Read targeted excerpts, not whole files. You cannot modify anything. " +
+    "Answer with CONCLUSIONS: the finding, the relevant paths with line references, and what they mean for " +
+    "the question — never dump raw file contents. Match your depth to the task: a quick lookup stays quick; " +
+    "an architecture question deserves a thorough sweep across naming conventions and directories.";
 registerTool({
     name: "agent",
-    description: "Delegate an independent sub-task to a fresh sub-agent and get its result. Spawn SEVERAL in one " +
-        "turn to run them in parallel (e.g. analyze/search/review N things at once). Sub-agents are " +
-        "read-only by default; pass a `role` id to use that role's persona + tools. Not for edits.",
+    description: "Delegate an independent sub-task to a fresh READ-ONLY sub-agent and get its conclusions. " +
+        "WHEN TO USE: open-ended exploration ('how does X work across the codebase', 'find everything that touches Y') " +
+        "that would take more than ~3 searches — pass role \"explore\" for a fast search specialist; and spawning " +
+        "SEVERAL agents in ONE response for independent questions (they run in parallel). " +
+        "WHEN NOT TO USE: reading a specific known file (read_file), finding one symbol (grep), or searching " +
+        "within 2-3 known files — direct tools are faster. Never for edits. " +
+        "Pass a `role` id to use that role's persona + tools.",
     input_schema: {
         type: "object",
         properties: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanhara/hara",
-  "version": "0.102.0",
+  "version": "0.103.0",
   "description": "hara — a coding agent CLI that runs like an engineering org.",
   "bin": {
     "hara": "dist/index.js"