@zhihaohong52/sonata 0.4.0

package/hooks/ensure-serve.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+// SessionStart hook: makes sure the sonata router is up when a session is
+// configured (via `sonata route on`) to route through it. The hook and the
+// router are launched by the same install, so it knows the port directly.
+//
+// Unlike `sonata code`, which auto-starts the daemon as part of launching
+// claude, a routed session is just `claude` — nothing of sonata runs to start
+// the router. Without this hook the first thing such a session does is cache
+// the connection error from a router that is not there.
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const port = Number(process.argv[2]);
+const global = process.argv[3] === '--global';
+
+/**
+ * The sonata.toml this session should be routed through, mirroring
+ * `configPath()` in src/config.ts (project config wins outright over the
+ * machine one) — duplicated here in plain JS because this hook runs
+ * standalone, not through the built TypeScript.
+ */
+function expectedConfigPath() {
+  const home = homedir();
+  if (global) {
+    const globalPath = join(home, '.config', 'sonata', 'sonata.toml');
+    return existsSync(globalPath) ? globalPath : null;
+  }
+  const localPath = join(process.cwd(), 'sonata.toml');
+  if (existsSync(localPath)) return localPath;
+  const globalPath = join(home, '.config', 'sonata', 'sonata.toml');
+  return existsSync(globalPath) ? globalPath : null;
+}
+
+if (Number.isInteger(port) && port > 0) {
+  const probeHealth = async (timeoutMs) => {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+      const res = await fetch(`http://localhost:${port}/__sonata_health`, { signal: ctrl.signal });
+      if (!res.ok) return null;
+      const body = await res.json();
+      return body?.sonata === true ? body : null;
+    } catch {
+      return null;
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+
+  const existing = await probeHealth(1000);
+  if (existing) {
+    const expected = expectedConfigPath();
+    // When this session can resolve its own expected config, the existing
+    // router must prove it is the same one — a router that cannot or does
+    // not report its own configPath (an older sonata build, or one whose own
+    // resolution failed) is treated the same as a mismatch, not silently
+    // trusted. When this session cannot resolve ANY config of its own
+    // (`expected === null`), there is nothing to enforce and the existing
+    // router is accepted unchanged.
+    if (expected !== null) {
+      if (typeof existing.configPath !== 'string') {
+        console.error(
+          `sonata: router port ${port} answered but did not report which sonata configuration ` +
+          'it is running (too old, or its own config resolution failed) — refusing to trust it. ' +
+          'Restart it with `sonata restart` once confirmed to be this project\'s own router.',
+        );
+        process.exit(1);
+      }
+      if (existing.configPath !== expected) {
+        console.error(
+          `sonata: router port ${port} is already serving a different sonata configuration ` +
+          `(${existing.configPath}) than this session resolves to (${expected}). Two ` +
+          'projects cannot share one router port — set a different [native.ports].router ' +
+          'in one of the two configs, then restart the router with `sonata restart`.',
+        );
+        process.exit(1);
+      }
+    }
+    process.exit(0);
+  }
+
+  try {
+    // Global routing is one shared router for every project — it has to
+    // resolve the *machine* config, not whichever project's session happens
+    // to trigger this hook first. Starting it from the machine config's own
+    // directory (~/.config/sonata) — not `home` itself — forces that
+    // resolution deterministically even when a stray `~/sonata.toml` (a
+    // known leftover some upgrades still have) exists: configPath()'s first
+    // check is `join(cwd, 'sonata.toml')`, so pointing `cwd` at
+    // `~/.config/sonata` makes that check land exactly on the real machine
+    // config, with the stray file never in the search path at all. A plain
+    // (project-scoped) install keeps inheriting this hook's own cwd.
+    const daemon = spawn('sonata', ['serve', '--daemon'], {
+      detached: true,
+      stdio: 'ignore',
+      ...(global ? { cwd: join(homedir(), '.config', 'sonata') } : {}),
+    });
+    daemon.unref();
+
+    const deadline = Date.now() + 10_000;
+    let started = null;
+    while (Date.now() < deadline) {
+      started = await probeHealth(1000);
+      if (started) break;
+      await new Promise((r) => setTimeout(r, 500));
+    }
+    if (started) {
+      // A concurrent `route on` in another project could have won the race
+      // to bind this same default port with ITS daemon between the probe
+      // above and this wait loop breaking — verify identity again now that
+      // something is confirmed to be listening, the same check the
+      // pre-existing branch above already does.
+      const expected = expectedConfigPath();
+      if (expected !== null) {
+        if (typeof started.configPath !== 'string') {
+          console.error(
+            `sonata: router port ${port} answered but did not report which sonata configuration ` +
+            'it is running (too old, or its own config resolution failed) — refusing to trust it. ' +
+            'Restart it with `sonata restart` once confirmed to be this project\'s own router.',
+          );
+          process.exit(1);
+        }
+        if (started.configPath !== expected) {
+          console.error(
+            `sonata: router port ${port} is already serving a different sonata configuration ` +
+            `(${started.configPath}) than this session resolves to (${expected}). Two ` +
+            'projects cannot share one router port — set a different [native.ports].router ' +
+            'in one of the two configs, then restart the router with `sonata restart`.',
+          );
+          process.exit(1);
+        }
+      }
+    }
+  } catch {
+    // A hook must never break the session it observes.
+  }
+}
+process.exit(0);

package/hooks/hooks.json

@@ -0,0 +1,12 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/capture-mode.mjs\"" }
+        ]
+      }
+    ]
+  }
+}

package/hooks/route-session.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// SessionStart / SessionEnd hook for `sonata route auto`: turns routing on for
+// the life of a session and off again when the last one ends, so a session
+// launches with a clean settings file (keeping Remote Control) and is routed
+// anyway from its first request onward.
+//
+// All of the work is `sonata route session-<phase>` in the CLI, where it is
+// ordinary tested code. This script only finds the session id and stays quiet:
+// a hook that throws is a hook that breaks the session it was meant to serve,
+// so it always exits 0.
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const phase = process.argv[2] === 'end' ? 'end' : 'start';
+const global = process.argv[3] === '--global';
+const cli = join(dirname(dirname(fileURLToPath(import.meta.url))), 'dist', 'cli.js');
+
+/** Claude Code sends the hook a JSON payload on stdin; `session_id` is in it. */
+async function readSessionId() {
+  try {
+    const chunks = [];
+    for await (const chunk of process.stdin) chunks.push(chunk);
+    const doc = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    return typeof doc.session_id === 'string' ? doc.session_id : '';
+  } catch {
+    return '';
+  }
+}
+
+const sessionId = await readSessionId();
+if (sessionId === '') process.exit(0);
+
+await new Promise((resolve) => {
+  try {
+    const args = [cli, 'route', `session-${phase}`, '--id', sessionId];
+    if (global) args.push('--global');
+    const child = spawn(process.execPath, args, {
+      stdio: 'ignore',
+    });
+    child.on('exit', resolve);
+    child.on('error', resolve);
+  } catch {
+    resolve();
+  }
+});
+process.exit(0);

package/hooks/route-subagent.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// SubagentStart / SubagentStop hook for `sonata route auto`.
+//
+// Routing is off at rest, so every session launches from a settings file with
+// no ANTHROPIC_BASE_URL in it and keeps Remote Control. It is turned on only
+// while a foreign-model subagent is actually running, and off again when the
+// last one finishes.
+//
+// This replaced turning routing on for the whole life of a session. Two things
+// were measured to get here: adding the env is picked up by a running session
+// within seconds — which is why a subagent's very first request is already
+// routed — while removing it is only observed eventually, which is why routing
+// must stay on for as long as the subagent runs rather than being cleaned up
+// on a timer.
+//
+// All of the work is `sonata route subagent-<phase>` in the CLI, where it is
+// ordinary tested code. This script only finds the agent id and stays quiet: a
+// hook that throws is a hook that breaks the subagent it was meant to serve,
+// so it always exits 0.
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const phase = process.argv[2] === 'stop' ? 'stop' : 'start';
+const global = process.argv[3] === '--global';
+const cli = join(dirname(dirname(fileURLToPath(import.meta.url))), 'dist', 'cli.js');
+
+/** Claude Code sends the hook a JSON payload on stdin; `agent_id` is in it. */
+async function readAgentId() {
+  try {
+    const chunks = [];
+    for await (const chunk of process.stdin) chunks.push(chunk);
+    const doc = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    return typeof doc.agent_id === 'string' ? doc.agent_id : '';
+  } catch {
+    return '';
+  }
+}
+
+const agentId = await readAgentId();
+if (agentId === '') process.exit(0);
+
+await new Promise((resolve) => {
+  try {
+    const args = [cli, 'route', `subagent-${phase}`, '--id', agentId];
+    if (global) args.push('--global');
+    const child = spawn(process.execPath, args, { stdio: 'ignore' });
+    child.on('exit', resolve);
+    child.on('error', resolve);
+  } catch {
+    resolve();
+  }
+});
+process.exit(0);

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@zhihaohong52/sonata",
+  "version": "0.4.0",
+  "description": "Foreign-model subagents for Claude Code — dispatch cheaper or different models through their own harnesses, as ordinary subagents",
+  "keywords": [
+    "claude-code",
+    "subagent",
+    "opencode",
+    "codex",
+    "tmux",
+    "llm",
+    "ai-agent"
+  ],
+  "homepage": "https://github.com/zhihaohong52/sonata#readme",
+  "bugs": {
+    "url": "https://github.com/zhihaohong52/sonata/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhihaohong52/sonata.git"
+  },
+  "license": "MIT",
+  "author": "James (https://github.com/zhihaohong52)",
+  "type": "module",
+  "bin": {
+    "sonata": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "roles",
+    "hooks",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "dev": "tsx src/cli.ts",
+    "prepublishOnly": "npm run build && npm test",
+    "release": "node scripts/release.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@inkjs/ui": "^2.0.0",
+    "ink": "^7.1.1",
+    "react": "^19.2.8",
+    "smol-toml": "^1.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/react": "^19.2.18",
+    "ink-testing-library": "^4.0.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/roles/code.md

@@ -0,0 +1,13 @@
+You are implementing a change in an existing codebase.
+
+Work directly in the repository you have been started in. Follow the existing
+patterns, naming, and test conventions of the surrounding code rather than
+importing conventions from elsewhere.
+
+Make the smallest change that fully accomplishes the task. Do not refactor
+unrelated code, do not add features that were not requested, and do not leave
+commented-out code behind.
+
+If the repository has tests, run them before you finish and make sure the ones
+related to your change pass. If you cannot make them pass, say so explicitly
+rather than describing the work as complete.

package/roles/explore.md

@@ -0,0 +1,9 @@
+You are exploring a codebase you have never seen. Do not modify any files.
+
+Locate where things live and answer questions about the code. Report what you
+actually find, and say plainly when you could not find something rather than
+guessing.
+
+Report concrete paths with `file.ts:123` line references so the reader can jump
+straight to the code. If a search turns up nothing, say so directly instead of
+inventing a location.

package/roles/plan.md

@@ -0,0 +1,10 @@
+You are producing an implementation plan, not performing it. Do not modify any
+file.
+
+Name the exact files to create or modify, and state the order of work and what
+to verify at each step. Flag anything ambiguous in the request rather than
+silently choosing one interpretation.
+
+Keep the plan concrete and minimal. If the request leaves a decision open, call
+it out and say what options exist, but do not expand the scope beyond what was
+asked.

package/roles/review.md

@@ -0,0 +1,11 @@
+You are reviewing code you did not write. Do not modify any files.
+
+Report only defects you can point at concretely: a file, a line, and what goes
+wrong. For each one, give the specific input or state that triggers it and the
+resulting incorrect behaviour.
+
+Rank findings by severity, most severe first. Correctness bugs outrank style.
+
+Do not pad the review. If you find nothing serious, say so plainly. A short
+review naming two real bugs is more useful than a long one listing twenty
+preferences.

package/skills/loop/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: sonata-loop
+description: Use when building a feature end-to-end with sonata tier agents — plans the work, routes each task to a difficulty tier, gates every change behind review, and escalates tiers on repeated failure.
+---
+
+# Loop engineering with sonata tier agents
+
+Run feature development as a loop over sonata's tier agents. You (the
+orchestrating session) judge difficulty and drive the loop; the agents do the
+work on foreign models. All of them require a routed session (`sonata route
+auto`) — if a tier agent errors with "all native routes … failed", fall back
+to `sonata dispatch --tier <role>-<tier> --task-file <path>` in Bash (or pass
+the task text directly as the trailing argument).
+
+## Difficulty heuristic
+
+- **simple** — mechanical, well-specified, contained: single-file changes,
+  bulk edits, scaffolding, test-writing against a clear spec.
+- **complex** — cross-cutting, ambiguous, design-sensitive, or needs
+  sustained reasoning: multi-file refactors, API design, debugging unknowns.
+- When unsure, use `-complex`.
+
+## The loop
+
+1. **Plan.** Dispatch `plan-complex` with the feature description. Ask it for
+   a numbered task list with per-task difficulty guesses.
+2. **Route.** For each task, judge difficulty yourself (the plan's guess is
+   advice, not binding) and dispatch `code-simple` or `code-complex` with a
+   self-contained task description — name the files to touch and the files to
+   leave alone; never say "see the plan".
+3. **Gate.** After each task, dispatch `review-simple` on the diff. Findings →
+   dispatch a fix at the same tier, then re-review.
+   - **Escalation rule:** a task that fails review twice at `simple` re-runs at
+     `complex` from scratch.
+   - **Loop bound:** at most 3 fix iterations per task; then stop and surface
+     the findings to the user.
+4. **Final gate.** When every task passed, dispatch `review-complex` over the
+   whole change. Findings loop back through step 3.
+
+## When not to loop
+
+A single contained change does not need the loop — dispatch one `code-*`
+agent directly, review it yourself or with one `review-simple` pass, done.