sphica 0.5.0 → 0.5.2

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "sphica",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Records Claude Code and Codex sessions on your machine and keeps past implementation and decisions, with their sources, for your agent to find.",
   "author": {
     "name": "iroha924",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "sphica",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Records Claude Code and Codex sessions on your machine and keeps past implementation and decisions, with their sources, for your agent to find.",
   "author": {
     "name": "iroha924",

package/README.md

@@ -11,17 +11,17 @@ English | [日本語](https://github.com/iroha924/sphica/blob/main/README.ja.md)
 
 **Local memory of past implementation and decisions for Claude Code and Codex.**
 Sphica records your coding sessions, and keeps what was decided, rejected, deferred, and built, each record quoting the words it came from.
-Your agent finds those records when it searches, and sees the relevant ones on its own before it edits a file they apply to.
+Your agent finds those records when it searches, and sees the relevant ones on its own when it reads or edits a file they apply to (in Codex, before a shell command that names the file and before `apply_patch`).
 The database is a single SQLite file on your machine.
 
 ## Features
 
 - **Automatic recording.** Sphica keeps your prompts, the agent's final reply for each turn, and the paths of the files a turn changed (by the edit tools, or seen in `git status` at the turn's end).
 - **Records with their sources.** `/sphica:trace` turns a session into records: decisions with the options rejected and why, constraints, implementations, findings, dead ends, and open questions. Every record quotes the exact words it came from, and a decision counts as adopted only when you said so.
-- **Pull requests too.** `/sphica:harvest <number>` keeps a GitHub pull request (body, comments, reviews, review comments, commits, and the issues it closes) and records what it decided. A reviewer's suggestion stays a proposal unless the owner or a maintainer adopted it; a merge alone adopts nothing.
+- **Pull requests too.** `/sphica:harvest <number>` keeps a GitHub pull request (body, comments, reviews, review comments, commits, and up to five issues the body says it closes) and records what it decided. A reviewer's suggestion stays a proposal unless the owner or a maintainer adopted it; a merge alone adopts nothing.
 - **Evidence found later.** `/sphica:glean` adds evidence and corrections to existing records. It asks you for the source (an issue URL, the file and line, meeting notes) before saving; a claim without one is kept only as unsourced and never used as fact.
-- **Shown when it matters (Claude Code).** At session start, the current work; before an edit, the active decisions anchored to that file; when your prompt names a recorded option or code symbol, that record.
-- **Search in Japanese and English.** Records carry search words in both languages, so a question in one finds a record written in the other.
+- **Shown when it matters.** At session start, the current work; before the agent reads or edits a file, or runs a shell command that names it, the decisions tied to that file; when your prompt names a recorded option or code symbol, that record. Works in both Claude Code and Codex.
+- **Search in Japanese and English.** Records are made with search words in both languages, so a question in either language is more likely to find them.
 - **Reviews check past decisions.** `/sphica:review` runs a reviewer per focus (correctness, security, written conventions, and past decisions by default; redundancy with `full`), and checks the diff against the records it touches.
 
 Records are never rewritten: a correction is a new record that supersedes the old one, and the history stays.
@@ -60,7 +60,7 @@ codex plugin marketplace add iroha924/sphica --ref main
 codex plugin add sphica@sphica
 ```
 
-In Codex, open `/hooks` and mark Sphica's hooks as trusted. Nothing is recorded until you do. If a plugin update changes the hooks, trust them again.
+In Codex, open `/hooks` and mark Sphica's hooks as trusted. Automatic recording does not start until you do. If a plugin update changes the hooks, trust them again.
 
 **3. Set up in your repository**
 
@@ -81,7 +81,7 @@ sphica doctor
 
 ## Quick start
 
-Sphica records sessions only in repositories you register (projects); run `sphica init` in each one.
+Only sessions in repositories you register (projects) go into Sphica's database; run `sphica init` in each one.
 
 Work as usual. At the end of a session with something worth keeping, run `/sphica:trace` (`$sphica:trace` in Codex).
 `/sphica:trace pending` lists earlier sessions not traced yet. To keep what a pull request decided, run `/sphica:harvest 123`.
@@ -99,21 +99,21 @@ Without being asked, Sphica adds a few past records to what the agent sees, each
 
 - At session start: the current work and project-wide constraints.
 - On a prompt that names a recorded code symbol, file path, or option.
-- Before the agent reads or edits a file a decision applies to. A read shows each record once per session.
-- Before a review. When you run your own review command (any name containing `review`, or a name listed in the `SPHICA_REVIEW_COMMANDS`
-  environment variable, comma-separated), it gets the decisions your local change touches. `/sphica:review` checks them itself. Claude Code only.
+- Before the agent reads or edits a file a decision applies to, and before a shell command that names such a file (naming it is not proof the command reads it). A read shows each record once per session.
+- Before a review (Claude Code only). When you run your own review command (any name containing `review`, or a name listed in the `SPHICA_REVIEW_COMMANDS`
+  environment variable, comma-separated), it gets the decisions your local change touches. `/sphica:review` checks them itself.
 
-In Codex the same happens at session start, on a prompt, before an `apply_patch` edit, and before a shell command that names such a file.
-Edits made through shell commands are not covered, and there is no review hook: run `$sphica:review`.
+In Codex the same happens at session start, on a prompt, before an `apply_patch` edit, and before a shell command that names such a file (Codex reads files through shell commands, so this covers reads).
+There is no review hook in Codex: run `$sphica:review`.
 
-The agent searches with Sphica's `search` and opens full records with `read`. `status` tells it how much of the history has been traced, so an empty search is not mistaken for "never decided".
+The agent searches with Sphica's `search` and opens full records with `read`. `status` tells it how much of the history has been traced, so an empty search is less likely to be mistaken for "never decided".
 
 ## What gets recorded and where it goes
 
-- **Where.** The database is `~/.sphica/sphica.db`. Records wait in a local queue, `~/.sphica/spool`, until they are written to it. Each machine has its own database; nothing is shared between machines.
-- **What.** Your prompts, the agent's final reply for each turn, and the paths of changed files. Background-task notifications and messages from other agents are skipped when Sphica recognizes their format. Replies in the middle of a turn, and files created and deleted within one turn, are not seen.
+- **Where.** The database is `~/.sphica/sphica.db`. Captured sessions wait in a local queue, `~/.sphica/spool`, until they are written to it. Each machine has its own database; nothing is shared between machines.
+- **What.** Your prompts, the agent's final reply for each turn, and the paths of changed files. Background-task notifications and messages from other agents are skipped when Sphica recognizes their format. Replies in the middle of a turn are not kept, nor are files created and deleted within one turn without the edit tools.
 - **What was shown.** Each automatic delivery is logged by which records it showed, not their text.
-- **Unregistered repositories.** Sessions in a repository you have not registered stay in the queue and are written after you register it. Held records are dropped after 30 days, and when more than 1,000 are waiting the oldest go first.
+- **Unregistered repositories.** Sessions in a repository you have not registered stay in the queue and are written after you register it. Held sessions are dropped after 30 days, and when more than 1,000 are waiting the oldest go first.
 - **Secrets.** Only secrets with a recognizable shape are masked:
   - keys with known prefixes
   - `KEY=…` and `"password": …` assignments
@@ -123,20 +123,16 @@ The agent searches with Sphica's `search` and opens full records with `read`. `s
 
   **Anything else is stored as typed, so do not paste secrets into a session.**
 - **Network.** Sphica has no account, no hosted service, and no telemetry, and makes no network connections itself. `/sphica:harvest` and `/sphica:glean` run `gh api` with your credentials to read pull requests and issues, and `sphica doctor` runs `npm` and `claude` to check installed versions.
-- **Text written by others.** Pull request and issue text may come from anyone. It is kept as a source and passed to the agent as data, never as instructions, and only the owner's or a maintainer's words can adopt a decision.
+- **Text written by others.** Pull request and issue text may come from anyone. It is kept as a source and passed to the agent as data, never as instructions, and only your words, or those of the repository's owner or a maintainer, can adopt a decision.
 
-## Limits in 0.5.0
+## What Sphica can't do yet
 
-- Structured records exist only for what you traced, harvested, or gleaned. Everything else is searchable only as captured text (`search` with `sources: true`).
-- In Codex, a shell command that names a file gets its decisions even when the command does not read it, and edits made through shell commands get none.
-- In Codex, `$sphica:trace`, `$sphica:harvest`, and `$sphica:glean` write only when Codex tells Sphica which directory the session is in. Codex 0.157.1 does, through an experimental MCP capability; if a later Codex stops, they stop with a message and write nothing.
-- Showing a record does not make the agent follow it. In our evaluation Codex received and found an earlier decision against a request, and still carried out the request as asked.
-- A code location in a record is checked against your working tree when it is read ("located", "moved", "missing"). A located symbol does not prove the decision still holds.
-
-## Upgrading from 0.4
-
-0.5.0 keeps records in a new format. A 0.4 database is refused and left unchanged; its records are not carried over.
-Move `~/.sphica/sphica.db` aside (keep it if you want the old data), then run `sphica init` again in each repository.
+- Only what you traced, harvested, or gleaned becomes a structured record. The rest of a conversation is searchable as captured text (`search` with `sources: true`).
+- For shell commands, Sphica only sees whether a command names a file. It may show decisions for a file the command never reads, and a shell command that edits a file is not treated as an edit (in Codex, a patch passed to `apply_patch` through the shell is treated as an edit).
+- Commands run through Claude Code's PowerShell tool (Windows without Git Bash) do not get decisions yet.
+- In Codex, `$sphica:trace`, `$sphica:harvest`, and `$sphica:glean` can write only when Codex tells Sphica which directory the session is in. Current Codex does. When it does not, they write nothing and tell you why.
+- Showing a record does not make the agent follow it.
+- A code location in a record is checked against your working tree when it is read. Finding the code name (a function name, say) the record points to does not mean the decision still holds.
 
 ## Updating
 
@@ -200,11 +196,11 @@ Everything else runs inside Claude Code and Codex, through the `/sphica:*` comma
 
 Report vulnerabilities privately as described in [SECURITY.md](https://github.com/iroha924/sphica/blob/main/SECURITY.md).
 
-Since 0.37.1, each release is built by GitHub Actions from a tag on the head of a pull request whose CI has passed, and staged on npm.
+Each release is built by GitHub Actions from a tag on the head of a pull request whose CI has passed, and staged on npm.
 The maintainer checks its SHA-512 checksum and provenance, then approves publication with two-factor authentication.
-For these versions, the [npm page](https://www.npmjs.com/package/sphica#provenance) links to the workflow and the commit each one was built from.
+The [npm page](https://www.npmjs.com/package/sphica#provenance) links to the workflow and the commit each release was built from.
 
-Dependabot opens pull requests to update the GitHub Actions used in CI. It does not cover the npm dependencies bundled into the package, because Dependabot cannot read the Bun lockfile format (v2) this repository uses.
+Dependabot opens weekly pull requests to update the GitHub Actions used in CI, and Renovate opens monthly ones for the npm dependencies bundled into the package.
 
 ## Contributing
 

package/dist/capture.js

@@ -3,7 +3,6 @@
 // server/src/capture.ts
 import { spawn } from "node:child_process";
 import fs4 from "node:fs";
-import os3 from "node:os";
 import path5 from "node:path";
 
 // server/node_modules/kysely/dist/util/object-utils.js
@@ -10815,7 +10814,8 @@ import path from "node:path";
 import { constants as C, DatabaseSync } from "node:sqlite";
 var SCHEMA_GENERATION = 2;
 var SCHEMA_REVISION = 1;
-var dbFile = () => process.env.SPHICA_DB || path.join(os.homedir(), ".sphica", "sphica.db");
+var sphicaHome = () => process.env.SPHICA_HOME || path.join(os.homedir(), ".sphica");
+var dbFile = () => process.env.SPHICA_DB || path.join(sphicaHome(), "sphica.db");
 function requireRuntime() {
   const proto = DatabaseSync.prototype;
   if (typeof proto.setAuthorizer !== "function" || typeof proto.enableDefensive !== "function")
@@ -11287,7 +11287,6 @@ var plain2 = (s) => visible(stripVTControlCharacters(s.replace(STRING_SEQUENCE,
 // server/src/project.ts
 import { execFileSync } from "node:child_process";
 import fs2 from "node:fs";
-import os2 from "node:os";
 import path3 from "node:path";
 
 // server/src/anchors.ts
@@ -11296,7 +11295,7 @@ var MAX_BYTES = 2 * 1024 * 1024;
 var leaves = (rel) => rel === ".." || rel.startsWith(`..${path2.sep}`) || path2.isAbsolute(rel);
 
 // server/src/project.ts
-var localFile = () => path3.join(os2.homedir(), ".sphica", "projects.json");
+var localFile = () => path3.join(sphicaHome(), "projects.json");
 var LOCAL_KEY = /^[a-z0-9][a-z0-9._-]*$/;
 function normalizeRemote(url) {
   const raw = String(url ?? "").trim();
@@ -11439,13 +11438,13 @@ function changed(root, before, after) {
 }
 
 // server/src/capture.ts
-var spoolDir = () => path5.join(os3.homedir(), ".sphica", "spool");
-var stateFile = () => path5.join(os3.homedir(), ".sphica", "capture.json");
+var spoolDir = () => path5.join(sphicaHome(), "spool");
+var stateFile = () => path5.join(sphicaHome(), "capture.json");
 var rejectedDir = () => path5.join(spoolDir(), "rejected");
 var unregisteredDir = () => path5.join(spoolDir(), "unregistered");
 var HOLD_DAYS = 30;
 var HOLD_MAX = 1000;
-var baselineDir = () => path5.join(os3.homedir(), ".sphica", "worktree");
+var baselineDir = () => path5.join(sphicaHome(), "worktree");
 function current(raw) {
   const r = raw;
   if (r.v === 2)

package/dist/cli.js

@@ -93,7 +93,6 @@ var require_src = __commonJS(function(exports, module) {
 
 // server/src/cli.ts
 import fs8 from "node:fs";
-import os5 from "node:os";
 import path9 from "node:path";
 
 // server/node_modules/@clack/core/dist/index.mjs
@@ -14181,7 +14180,8 @@ import path2 from "node:path";
 import { constants as C, DatabaseSync } from "node:sqlite";
 var SCHEMA_GENERATION = 2;
 var SCHEMA_REVISION = 1;
-var dbFile = () => process.env.SPHICA_DB || path2.join(os.homedir(), ".sphica", "sphica.db");
+var sphicaHome = () => process.env.SPHICA_HOME || path2.join(os.homedir(), ".sphica");
+var dbFile = () => process.env.SPHICA_DB || path2.join(sphicaHome(), "sphica.db");
 function requireRuntime() {
   const proto = DatabaseSync.prototype;
   if (typeof proto.setAuthorizer !== "function" || typeof proto.enableDefensive !== "function")
@@ -14522,7 +14522,6 @@ var leaves = (rel) => rel === ".." || rel.startsWith(`..${path4.sep}`) || path4.
 // server/src/capture.ts
 import { spawn } from "node:child_process";
 import fs6 from "node:fs";
-import os3 from "node:os";
 import path7 from "node:path";
 
 // server/src/knowledge.ts
@@ -14533,7 +14532,7 @@ import { execFileSync } from "node:child_process";
 import fs4 from "node:fs";
 import os2 from "node:os";
 import path5 from "node:path";
-var localFile = () => path5.join(os2.homedir(), ".sphica", "projects.json");
+var localFile = () => path5.join(sphicaHome(), "projects.json");
 var LOCAL_KEY = /^[a-z0-9][a-z0-9._-]*$/;
 function normalizeRemote(url) {
   const raw = String(url ?? "").trim();
@@ -14726,13 +14725,13 @@ function changed(root, before, after) {
 }
 
 // server/src/capture.ts
-var spoolDir = () => path7.join(os3.homedir(), ".sphica", "spool");
-var stateFile = () => path7.join(os3.homedir(), ".sphica", "capture.json");
+var spoolDir = () => path7.join(sphicaHome(), "spool");
+var stateFile = () => path7.join(sphicaHome(), "capture.json");
 var rejectedDir = () => path7.join(spoolDir(), "rejected");
 var unregisteredDir = () => path7.join(spoolDir(), "unregistered");
 var HOLD_DAYS = 30;
 var HOLD_MAX = 1000;
-var baselineDir = () => path7.join(os3.homedir(), ".sphica", "worktree");
+var baselineDir = () => path7.join(sphicaHome(), "worktree");
 function current(raw) {
   const r2 = raw;
   if (r2.v === 2)
@@ -15252,7 +15251,7 @@ async function withDb(role, fn) {
 // server/src/plugin.ts
 import { execFileSync as execFileSync3 } from "node:child_process";
 import fs7 from "node:fs";
-import os4 from "node:os";
+import os3 from "node:os";
 import path8 from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 var MANIFEST = path8.join(".claude-plugin", "plugin.json");
@@ -15381,7 +15380,7 @@ function observe(cwdRoot) {
   } catch {
     claude = "unknown";
   }
-  let codexHome = process.env.CODEX_HOME ?? path8.join(os4.homedir(), ".codex");
+  let codexHome = process.env.CODEX_HOME ?? path8.join(os3.homedir(), ".codex");
   try {
     codexHome = fs7.realpathSync(codexHome);
   } catch {}
@@ -15460,7 +15459,7 @@ function report(s, now = new Date) {
   const lines = [];
   const issues = [];
   const todo = new Set;
-  const home = os4.homedir();
+  const home = os3.homedir();
   const short = (p) => p.startsWith(`${home}/`) ? `~${p.slice(home.length)}` : p;
   const say2 = (m, label, text) => {
     if (m === "warn" || m === "fail")
@@ -15738,7 +15737,7 @@ async function init(flags) {
   });
 }
 async function uninstall(yes) {
-  const home = path9.join(os5.homedir(), ".sphica");
+  const home = sphicaHome();
   const inHome = (p) => {
     const rel = path9.relative(home, path9.resolve(p));
     return rel === "" || !leaves(rel);
@@ -15748,6 +15747,8 @@ async function uninstall(yes) {
     ...process.env.SPHICA_DB && !inHome(process.env.SPHICA_DB) ? [process.env.SPHICA_DB] : []
   ];
   await boxed("sphica uninstall", async () => {
+    if (process.env.SPHICA_HOME)
+      throw new Error("SPHICA_HOME is set; uninstall deletes only ~/.sphica. Unset SPHICA_HOME and run it again");
     if (!fs8.existsSync(home))
       console.log(indent(`${mark("none")} ${home} does not exist`));
     else {

package/dist/deliver.js

@@ -16,7 +16,7 @@ var __export = (target, all) => {
 
 // server/src/deliver.ts
 import fs6 from "node:fs";
-import os4 from "node:os";
+import os2 from "node:os";
 import path7 from "node:path";
 
 // server/src/anchors.ts
@@ -27,7 +27,6 @@ var leaves = (rel) => rel === ".." || rel.startsWith(`..${path.sep}`) || path.is
 // server/src/capture.ts
 import { spawn } from "node:child_process";
 import fs4 from "node:fs";
-import os3 from "node:os";
 import path5 from "node:path";
 
 // server/node_modules/kysely/dist/util/object-utils.js
@@ -10839,7 +10838,8 @@ import path2 from "node:path";
 import { constants as C, DatabaseSync } from "node:sqlite";
 var SCHEMA_GENERATION = 2;
 var SCHEMA_REVISION = 1;
-var dbFile = () => process.env.SPHICA_DB || path2.join(os.homedir(), ".sphica", "sphica.db");
+var sphicaHome = () => process.env.SPHICA_HOME || path2.join(os.homedir(), ".sphica");
+var dbFile = () => process.env.SPHICA_DB || path2.join(sphicaHome(), "sphica.db");
 function requireRuntime() {
   const proto = DatabaseSync.prototype;
   if (typeof proto.setAuthorizer !== "function" || typeof proto.enableDefensive !== "function")
@@ -11336,9 +11336,8 @@ var inline = (s) => plain2(s).replace(/[\n\t]+/g, " ");
 // server/src/project.ts
 import { execFileSync } from "node:child_process";
 import fs2 from "node:fs";
-import os2 from "node:os";
 import path3 from "node:path";
-var localFile = () => path3.join(os2.homedir(), ".sphica", "projects.json");
+var localFile = () => path3.join(sphicaHome(), "projects.json");
 var LOCAL_KEY = /^[a-z0-9][a-z0-9._-]*$/;
 function normalizeRemote(url) {
   const raw = String(url ?? "").trim();
@@ -11485,13 +11484,13 @@ function changed(root, before, after) {
 }
 
 // server/src/capture.ts
-var spoolDir = () => path5.join(os3.homedir(), ".sphica", "spool");
-var stateFile = () => path5.join(os3.homedir(), ".sphica", "capture.json");
+var spoolDir = () => path5.join(sphicaHome(), "spool");
+var stateFile = () => path5.join(sphicaHome(), "capture.json");
 var rejectedDir = () => path5.join(spoolDir(), "rejected");
 var unregisteredDir = () => path5.join(spoolDir(), "unregistered");
 var HOLD_DAYS = 30;
 var HOLD_MAX = 1000;
-var baselineDir = () => path5.join(os3.homedir(), ".sphica", "worktree");
+var baselineDir = () => path5.join(sphicaHome(), "worktree");
 function current(raw) {
   const r = raw;
   if (r.v === 2)
@@ -31841,12 +31840,12 @@ function toldBefore(session, key) {
 function markOnce(kind, key) {
   const user = (() => {
     try {
-      return os4.userInfo().username;
+      return os2.userInfo().username;
     } catch {
       return String(process.getuid?.() ?? "user");
     }
   })();
-  const dir = path7.join(os4.tmpdir(), `sphica-${sha256(user).toString("hex").slice(0, 12)}`, kind);
+  const dir = path7.join(os2.tmpdir(), `sphica-${sha256(user).toString("hex").slice(0, 12)}`, kind);
   try {
     fs6.mkdirSync(dir, { recursive: true, mode: 448 });
     fs6.writeFileSync(path7.join(dir, sha256(key).toString("hex").slice(0, 24)), "", { flag: "wx" });
@@ -31883,7 +31882,7 @@ async function log(file2, projectId2, host, external2, event, plan, outcome, bra
 async function deliver(input2, host = "claude-code", file2 = dbFile()) {
   const name = input2.hook_event_name;
   const call = reviewCall(input2);
-  const event = call ? "review" : name === "SessionStart" ? "session_start" : name === "UserPromptSubmit" ? "prompt" : name === "PreToolUse" ? input2.tool_name === "Read" || host === "codex" && input2.tool_name === "Bash" && !shellPatch(input2) ? "pre_read" : "pre_edit" : null;
+  const event = call ? "review" : name === "SessionStart" ? "session_start" : name === "UserPromptSubmit" ? "prompt" : name === "PreToolUse" ? input2.tool_name === "Read" || input2.tool_name === "Bash" && !(host === "codex" && shellPatch(input2)) ? "pre_read" : "pre_edit" : null;
   if (!event || !input2.session_id)
     return "";
   if (event === "prompt" && !isOwnerTurn(input2))
@@ -31892,7 +31891,7 @@ async function deliver(input2, host = "claude-code", file2 = dbFile()) {
     return "";
   const ti = input2.tool_input ?? {};
   const patch = host === "codex" && input2.tool_name === "apply_patch" && typeof ti.command === "string" ? ti.command : host === "codex" ? shellPatch(input2) : null;
-  const shell = host === "codex" && input2.tool_name === "Bash" && !patch && typeof ti.command === "string" ? ti.command : null;
+  const shell = input2.tool_name === "Bash" && !patch && typeof ti.command === "string" ? ti.command : null;
   const targets = patch ? patchPaths2(patch) : [ti.file_path, ti.notebook_path].filter((p) => typeof p === "string").slice(0, 1);
   const onPath = event === "pre_edit" || event === "pre_read";
   if (onPath && !shell && (!(event === "pre_read" || patch || EDIT_TOOLS.has(input2.tool_name ?? "")) || !targets.length))

package/dist/mcp-record.js

@@ -45531,7 +45531,8 @@ import path from "node:path";
 import { constants as C, DatabaseSync } from "node:sqlite";
 var SCHEMA_GENERATION = 2;
 var SCHEMA_REVISION = 1;
-var dbFile = () => process.env.SPHICA_DB || path.join(os.homedir(), ".sphica", "sphica.db");
+var sphicaHome = () => process.env.SPHICA_HOME || path.join(os.homedir(), ".sphica");
+var dbFile = () => process.env.SPHICA_DB || path.join(sphicaHome(), "sphica.db");
 function requireRuntime() {
   const proto = DatabaseSync.prototype;
   if (typeof proto.setAuthorizer !== "function" || typeof proto.enableDefensive !== "function")
@@ -45987,7 +45988,6 @@ import crypto2 from "node:crypto";
 // server/src/capture.ts
 import { spawn } from "node:child_process";
 import fs5 from "node:fs";
-import os3 from "node:os";
 import path5 from "node:path";
 
 // server/src/knowledge.ts
@@ -46023,7 +46023,6 @@ var inline = (s) => plain2(s).replace(/[\n\t]+/g, " ");
 // server/src/project.ts
 import { execFileSync } from "node:child_process";
 import fs3 from "node:fs";
-import os2 from "node:os";
 import path3 from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -46062,7 +46061,7 @@ function locate(root, rel, symbol2) {
 }
 
 // server/src/project.ts
-var localFile = () => path3.join(os2.homedir(), ".sphica", "projects.json");
+var localFile = () => path3.join(sphicaHome(), "projects.json");
 var LOCAL_KEY = /^[a-z0-9][a-z0-9._-]*$/;
 function normalizeRemote(url2) {
   const raw = String(url2 ?? "").trim();
@@ -46229,13 +46228,13 @@ function changed(root, before, after) {
 }
 
 // server/src/capture.ts
-var spoolDir = () => path5.join(os3.homedir(), ".sphica", "spool");
-var stateFile = () => path5.join(os3.homedir(), ".sphica", "capture.json");
+var spoolDir = () => path5.join(sphicaHome(), "spool");
+var stateFile = () => path5.join(sphicaHome(), "capture.json");
 var rejectedDir = () => path5.join(spoolDir(), "rejected");
 var unregisteredDir = () => path5.join(spoolDir(), "unregistered");
 var HOLD_DAYS = 30;
 var HOLD_MAX = 1000;
-var baselineDir = () => path5.join(os3.homedir(), ".sphica", "worktree");
+var baselineDir = () => path5.join(sphicaHome(), "worktree");
 function current(raw) {
   const r = raw;
   if (r.v === 2)

package/dist/mcp.js

@@ -45528,7 +45528,8 @@ import path from "node:path";
 import { constants as C, DatabaseSync } from "node:sqlite";
 var SCHEMA_GENERATION = 2;
 var SCHEMA_REVISION = 1;
-var dbFile = () => process.env.SPHICA_DB || path.join(os.homedir(), ".sphica", "sphica.db");
+var sphicaHome = () => process.env.SPHICA_HOME || path.join(os.homedir(), ".sphica");
+var dbFile = () => process.env.SPHICA_DB || path.join(sphicaHome(), "sphica.db");
 function requireRuntime() {
   const proto = DatabaseSync.prototype;
   if (typeof proto.setAuthorizer !== "function" || typeof proto.enableDefensive !== "function")
@@ -45794,7 +45795,6 @@ var HOST_MARKS = new Set([".orphaned_at", ".in_use"]);
 // server/src/project.ts
 import { execFileSync } from "node:child_process";
 import fs4 from "node:fs";
-import os2 from "node:os";
 import path4 from "node:path";
 
 // server/src/anchors.ts
@@ -45844,7 +45844,7 @@ function checkAnchor(root, a) {
 }
 
 // server/src/project.ts
-var localFile = () => path4.join(os2.homedir(), ".sphica", "projects.json");
+var localFile = () => path4.join(sphicaHome(), "projects.json");
 var LOCAL_KEY = /^[a-z0-9][a-z0-9._-]*$/;
 function normalizeRemote(url2) {
   const raw = String(url2 ?? "").trim();

package/hooks/hooks.json

@@ -65,7 +65,7 @@
     ],
     "PreToolUse": [
       {
-        "matcher": "Edit|Write|MultiEdit|NotebookEdit|Read|Skill",
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit|Read|Skill|Bash",
         "hooks": [
           {
             "type": "command",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sphica",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Records Claude Code and Codex sessions on your machine and keeps past implementation and decisions, with their sources, for your agent to find.",
   "license": "MIT",
   "type": "module",