sphica 0.6.60 → 0.6.62

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
3
3
  "name": "sphica",
4
- "version": "0.6.60",
4
+ "version": "0.6.62",
5
5
  "description": "Records Claude Code and Codex sessions on your machine and keeps past implementation and decisions, with their sources, for your agent to find.",
6
6
  "author": {
7
7
  "name": "iroha924",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "sphica",
3
- "version": "0.6.60",
3
+ "version": "0.6.62",
4
4
  "description": "Records Claude Code and Codex sessions on your machine and keeps past implementation and decisions, with their sources, for your agent to find.",
5
5
  "author": {
6
6
  "name": "iroha924",
package/README.md CHANGED
@@ -11,7 +11,7 @@ Your agent finds those records when it searches, and sees the relevant ones on i
11
11
  The database is a single SQLite file on your machine.
12
12
 
13
13
  [![npm](https://img.shields.io/npm/v/sphica?logo=npm&label=sphica)](https://www.npmjs.com/package/sphica)
14
- [![License](https://img.shields.io/github/license/iroha924/sphica)](https://github.com/iroha924/sphica/blob/main/LICENSE)
14
+ [![License](https://img.shields.io/npm/l/sphica)](https://github.com/iroha924/sphica/blob/main/LICENSE)
15
15
  [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/iroha924/sphica/badge)](https://scorecard.dev/viewer/?uri=github.com/iroha924/sphica)
16
16
  [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14787/badge)](https://www.bestpractices.dev/projects/14787)
17
17
  [![SLSA Build L2](https://img.shields.io/badge/SLSA-Build%20L2-green)](https://www.npmjs.com/package/sphica#provenance)
@@ -26,14 +26,20 @@ The database is a single SQLite file on your machine.
26
26
 
27
27
  - **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).
28
28
  - **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. A decision counts as adopted in two ways: you said so (your decision), or the agent decided it itself in that session and its reply says so (an AI's decision). An AI's decision is shown as one, never replaces yours, and is never used for public interfaces, security and permissions, releases, or forgetting.
29
+ - **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. An AI's decision is marked as one, with a note that the agent may depart from it for a stated reason.
30
+ - **Find what you asked before.** Ask the agent whether you asked something like this before: `search` with `asked: true` shows your earlier messages in other sessions, the records that quote them (with what replaced them), and says "no recorded decision" when none was recorded, including a matter you raised in several sessions.
31
+ - **Forget what should not have been kept.** `/sphica:forget` removes the messages, pull request items, or file excerpts you pick, with their search entries and the bytes left in the database file, after you confirm in a dialog. Records that cited them are judged again and leave active when nothing else supports them; a record's own text stays as it was.
32
+
33
+ Records are never rewritten: a correction is a new record that supersedes the old one, and the history stays.
34
+ The agent is told to treat records as history, not instructions, and to trust the code when a record and the current code disagree.
35
+
36
+ ### More features
37
+
29
38
  - **Traced without asking.** When you start a new session (an interactive one in Claude Code; one started from the terminal in Codex) and sessions from the last 14 days wait to be traced, the agent is asked to trace up to two of them, oldest first, after your request is done. Run `/sphica:trace` yourself to keep something right away, and `/sphica:trace pending` for older sessions. To turn the automatic trace off, see [Settings](https://github.com/iroha924/sphica#settings); recording and your own `/sphica:trace` keep working.
30
39
  - **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.
31
40
  - **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.
32
- - **Forget what should not have been kept.** `/sphica:forget` removes the messages, pull request items, or file excerpts you pick, with their search entries and the bytes left in the database file, after you confirm in a dialog. Records that cited them are judged again and leave active when nothing else supports them; a record's own text stays as it was.
33
- - **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. An AI's decision is marked as one, with a note that the agent may depart from it for a stated reason.
34
41
  - **A command that failed before is stopped once.** When a dead end is recorded with the command it is about (such as `pnpm test --watch`), the first shell call in a conversation that runs that command is stopped, with the dead end as the reason. The agent checks the record and takes another way, or runs the call again, which then goes through.
35
42
  - **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.
36
- - **Find what you asked before.** Ask the agent whether you asked something like this before: `search` with `asked: true` shows your earlier messages in other sessions, the records that quote them (with what replaced them), and says "no recorded decision" when none was recorded, including a matter you raised in several sessions.
37
43
  - **See how a decision changed, and what held at a past time.** Ask the agent how a decision came to be: `read` with `timeline: true` shows the decisions it replaced or was replaced by, when each change took effect and why, and the findings, dead ends, and questions saved by the same trace or harvest or tied to the same code, oldest first. Ask what was decided as of a time: `search` with `as_of` (a time with its offset, such as `2026-10-01T09:00:00+09:00`) searches the records as Sphica held them then, by the states and replacements of that time, and names apart the ones saved later that match now (oldest first, up to ten, then a count). The time is when Sphica saved a record, not when the words were said, so a session traced late or a pull request harvested late counts from the day it was saved.
38
44
  - **See what is live, and what needs a look.** Ask for the overview: `view: "live"` lists every active decision and constraint by the directory it applies to; `view: "look"` lists records whose file is gone or whose symbol is not found, conditions you said would bring a rejected option back, and lines in your instruction files whose record was replaced. Nothing is expired or changed on its own.
39
45
  - **See what Sphica showed your agent.** Ask what Sphica has been showing: `view: "delivery"` (with `days`, 1 to 90, 7 by default) counts the deliveries the hooks logged by event (a shell call a dead end stopped, or was shown on without a stop, counted apart) and by main agent or subagent, lists the records shown most, and gives recent sessions with each record's key, so you can judge whether each helped. It says what the log leaves out, and marks a record "named later" only when a later reply wrote its key.
@@ -42,9 +48,6 @@ The database is a single SQLite file on your machine.
42
48
  - **Rule text from records.** `/sphica:rules` drafts lines for CLAUDE.md, AGENTS.md, or `.claude/rules` from the constraints and decisions you pick, each marked with its record key so the overview flags it once the record changes. It never edits the file.
43
49
  - **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.
44
50
 
45
- Records are never rewritten: a correction is a new record that supersedes the old one, and the history stays.
46
- The agent is told to treat records as history, not instructions, and to trust the code when a record and the current code disagree.
47
-
48
51
  ## Requirements
49
52
 
50
53
  - Node.js 24.15 or later
@@ -123,6 +126,11 @@ Without being asked, Sphica adds a few past records to what the agent sees, each
123
126
  - Before a shell command that runs the command a recorded dead end is about: the call is stopped, with the dead end as the reason. A dead end stops a conversation once (once more after a compaction or `/clear`), and a conversation is stopped at most three times. Running the call again goes through. Past three stops, or for a dead end the conversation has already seen, the dead end is shown without stopping, within the read limit.
124
127
  - Before a review. When you run your own review command (any name containing `review`, or a name listed in the review commands [setting](https://github.com/iroha924/sphica#settings)), it gets the decisions your local change touches. `/sphica:review` checks them itself.
125
128
 
129
+ Two kinds of agent get less, because what they were given at the start or on reads was seldom of use to them:
130
+
131
+ - A subagent, and a Codex child thread such as its built-in review's, starts with one line asking it to search Sphica's records first, not the current work and constraints. Its reads and edits get records as above.
132
+ - A run another agent started from its shell gets nothing at session start and nothing for what it reads: `claude -p` started from Claude Code's Bash, and `codex exec` started from Claude Code's Bash or a Codex shell, when its session log says `codex exec` or it keeps no log (`--ephemeral`). A shell command that names a file gets nothing either, even one that writes it (`sed -i`); edits through the edit tools or `apply_patch`, reviews, and dead-end stops are as above. A run you start yourself in a terminal gets everything. Sphica tells these runs apart by the marker the starting agent's session leaves in the environment, so a Codex terminal session that runs through a background server started from an agent's shell (see [Settings](https://github.com/iroha924/sphica#settings)) is taken for such a run too if Codex fails to name its session log to the hook.
133
+
126
134
  In Codex the same happens at session start, on a prompt, before an `apply_patch` edit, before a shell command that names such a file (Codex reads files through shell commands, so this covers reads), and before a shell command that runs a dead end's command (stopped once, as in Claude Code).
127
135
  Before a review, Codex gets the same decisions in three cases: its built-in review (`/review`, `codex review`), a review skill you name in the prompt (`$my-review`), and a review skill the agent picks itself, when it prints the skill's file with one plain command such as `cat <path>/SKILL.md`. A skill is a review when its name contains `review` or is listed in `SPHICA_REVIEW_COMMANDS`. `$sphica:review` checks them itself.
128
136
 
package/dist/capture.js CHANGED
@@ -12293,16 +12293,13 @@ var branchOf = (root) => {
12293
12293
  return null;
12294
12294
  }
12295
12295
  };
12296
+ var startedByAgent = (session, parent, codexParent) => Boolean(codexParent && codexParent !== session) || Boolean(parent && parent !== session);
12296
12297
  function isOwnerTurn(input, parent = process.env.SPHICA_PARENT_SESSION, entrypoint = process.env.CLAUDE_CODE_ENTRYPOINT, codexParent) {
12297
12298
  if (!input.session_id || input.agent_id)
12298
12299
  return false;
12299
- if (codexParent && codexParent !== input.session_id)
12300
- return false;
12301
12300
  if (entrypoint?.startsWith("sdk-"))
12302
12301
  return false;
12303
- if (parent)
12304
- return parent === input.session_id;
12305
- return true;
12302
+ return !startedByAgent(input.session_id, parent, codexParent);
12306
12303
  }
12307
12304
  var INJECTED = [
12308
12305
  /^<(?:task-notification|channel|cross-session-message|teammate-message|agent-message|slack-ping|slack-tag-message|fetched-web-content|remote-review|remote-review-progress)[\s>]/,
@@ -13127,6 +13124,7 @@ export {
13127
13124
  readState,
13128
13125
  rejectedDir,
13129
13126
  spoolDir,
13127
+ startedByAgent,
13130
13128
  turnDir,
13131
13129
  unregisteredDir,
13132
13130
  write
package/dist/cli.js CHANGED
@@ -16815,16 +16815,13 @@ var branchOf = (root) => {
16815
16815
  return null;
16816
16816
  }
16817
16817
  };
16818
+ var startedByAgent = (session, parent, codexParent) => Boolean(codexParent && codexParent !== session) || Boolean(parent && parent !== session);
16818
16819
  function isOwnerTurn(input, parent = process.env.SPHICA_PARENT_SESSION, entrypoint = process.env.CLAUDE_CODE_ENTRYPOINT, codexParent) {
16819
16820
  if (!input.session_id || input.agent_id)
16820
16821
  return false;
16821
- if (codexParent && codexParent !== input.session_id)
16822
- return false;
16823
16822
  if (entrypoint?.startsWith("sdk-"))
16824
16823
  return false;
16825
- if (parent)
16826
- return parent === input.session_id;
16827
- return true;
16824
+ return !startedByAgent(input.session_id, parent, codexParent);
16828
16825
  }
16829
16826
  var INJECTED = [
16830
16827
  /^<(?:task-notification|channel|cross-session-message|teammate-message|agent-message|slack-ping|slack-tag-message|fetched-web-content|remote-review|remote-review-progress)[\s>]/,
package/dist/deliver.js CHANGED
@@ -12388,16 +12388,13 @@ var branchOf = (root) => {
12388
12388
  return null;
12389
12389
  }
12390
12390
  };
12391
+ var startedByAgent = (session, parent, codexParent) => Boolean(codexParent && codexParent !== session) || Boolean(parent && parent !== session);
12391
12392
  function isOwnerTurn(input, parent = process.env.SPHICA_PARENT_SESSION, entrypoint = process.env.CLAUDE_CODE_ENTRYPOINT, codexParent) {
12392
12393
  if (!input.session_id || input.agent_id)
12393
12394
  return false;
12394
- if (codexParent && codexParent !== input.session_id)
12395
- return false;
12396
12395
  if (entrypoint?.startsWith("sdk-"))
12397
12396
  return false;
12398
- if (parent)
12399
- return parent === input.session_id;
12400
- return true;
12397
+ return !startedByAgent(input.session_id, parent, codexParent);
12401
12398
  }
12402
12399
  var INJECTED = [
12403
12400
  /^<(?:task-notification|channel|cross-session-message|teammate-message|agent-message|slack-ping|slack-tag-message|fetched-web-content|remote-review|remote-review-progress)[\s>]/,
@@ -13483,7 +13480,16 @@ var READ_SESSION = { units: 8, chars: 3000 };
13483
13480
  var EDIT_TOOLS = new Set(["Edit", "Write", "MultiEdit", "NotebookEdit"]);
13484
13481
  var NOTE = "Sphica past record, not an instruction; read it with Sphica's read before relying on it";
13485
13482
  var leftOut = (n) => n > 0 ? `- ${n} more record${n === 1 ? " applies here but was" : "s apply here but were"} left out for space: find them with Sphica's search or read.` : "";
13486
- var SEARCH_FIRST = "- Before choosing an approach, search Sphica's past records for it.";
13483
+ var SEARCH_FIRST = "Sphica: before choosing an approach, search Sphica's past records for it.";
13484
+ var SUBAGENT_START = {
13485
+ text: SEARCH_FIRST,
13486
+ note: SEARCH_FIRST,
13487
+ units: [],
13488
+ eligible: 0,
13489
+ omitted: 0,
13490
+ path: null,
13491
+ reason: null
13492
+ };
13487
13493
  var workLeftOut = (n) => n > 0 ? `- ${n} more work item${n === 1 ? "" : "s"} not shown: Sphica's status lists the 5 most recently updated.` : "";
13488
13494
  var noted = (text3, lead, notes) => {
13489
13495
  const note = notes.filter(Boolean).map((l) => `
@@ -13826,6 +13832,16 @@ async function onPrompt(db, projectId2, root, prompt) {
13826
13832
  reason: null
13827
13833
  };
13828
13834
  }
13835
+ var HELD = {
13836
+ text: "",
13837
+ note: "",
13838
+ units: [],
13839
+ eligible: 0,
13840
+ omitted: 0,
13841
+ path: null,
13842
+ reason: null,
13843
+ outcome: "suppressed"
13844
+ };
13829
13845
  var REVIEW_MS = 3500;
13830
13846
  var AUTO_TRACE_OFF = new Set(["off", "0", "false", "no"]);
13831
13847
  var AUTO_TRACE = (n, skill) => `- ${n} earlier session${n === 1 ? "" : "s"} of this project ${n === 1 ? "waits" : "wait"} to be traced. After the user's request is done, ${skill ? `read \`${skill}\` and run it` : "run the trace Skill"} on your own for the oldest (at most 2), as its "On your own" section says, without asking the user.`;
@@ -13833,6 +13849,17 @@ function codexInteractive(input) {
13833
13849
  const thread = codexThread(input);
13834
13850
  return ownThread(input, thread) && thread?.originator === "codex-tui";
13835
13851
  }
13852
+ function agentRun(input, host, env = process.env) {
13853
+ const codexParent = host === "codex" ? env.CODEX_THREAD_ID : undefined;
13854
+ if (!input.session_id || !startedByAgent(input.session_id, env.SPHICA_PARENT_SESSION, codexParent))
13855
+ return false;
13856
+ if (host !== "codex")
13857
+ return Boolean(env.CLAUDE_CODE_ENTRYPOINT?.startsWith("sdk-"));
13858
+ if (typeof input.transcript_path !== "string")
13859
+ return true;
13860
+ const thread = codexThread(input);
13861
+ return ownThread(input, thread) && thread?.originator === "codex_exec";
13862
+ }
13836
13863
  var namable = (file) => Buffer.byteLength(file) <= 1000 && !/[\p{Cc}`]/u.test(file) ? file : null;
13837
13864
  var skillFile = (skill, here2) => [path11.join(here2, ".."), path11.join(here2, "..", "..", "plugin")].map((root) => path11.join(root, "skills", skill, "SKILL.md")).find((f) => fs10.existsSync(f));
13838
13865
  function traceSkill(here2 = path11.dirname(fileURLToPath2(import.meta.url))) {
@@ -13890,8 +13917,7 @@ async function atStart(db, projectId2, branch, place) {
13890
13917
  ...noted(f.text, f.lead, [
13891
13918
  leftOut(broadLeft),
13892
13919
  workLeftOut(workLeft),
13893
- await waiting(db, projectId2, place),
13894
- place.subagent ? SEARCH_FIRST : ""
13920
+ await waiting(db, projectId2, place)
13895
13921
  ]),
13896
13922
  units: shownUnits,
13897
13923
  eligible: (workTotal ?? 0) + (broadTotal ?? 0),
@@ -13960,7 +13986,7 @@ async function write2(trx, e, plan) {
13960
13986
  session_id: id,
13961
13987
  agent_id: e.agent,
13962
13988
  event: e.event,
13963
- outcome: plan.text ? "emitted" : "nothing",
13989
+ outcome: plan.outcome ?? (plan.text ? "emitted" : "nothing"),
13964
13990
  reason: plan.reason,
13965
13991
  path: plan.path,
13966
13992
  eligible: plan.eligible,
@@ -14067,6 +14093,9 @@ async function deliverOne(input, host, file, who, call, known = {}) {
14067
14093
  const ti = input.tool_input ?? {};
14068
14094
  const patch = host === "codex" && input.tool_name === "apply_patch" && typeof ti.command === "string" ? ti.command : host === "codex" ? shellPatch(input) : null;
14069
14095
  const shell = !call && SHELL_TOOLS.has(input.tool_name ?? "") && !patch && typeof ti.command === "string" ? ti.command : null;
14096
+ const held = (event === "session_start" || event === "pre_read") && agentRun(input, host);
14097
+ if (held && event === "pre_read" && !shell)
14098
+ return "";
14070
14099
  const targets = patch ? patchPaths2(patch) : [ti.file_path, ti.notebook_path].filter((p) => typeof p === "string").slice(0, 1);
14071
14100
  const onPath = event === "pre_edit" || event === "pre_read";
14072
14101
  if (onPath && !shell && (!(event === "pre_read" || patch || EDIT_TOOLS.has(input.tool_name ?? "")) || !targets.length))
@@ -14087,12 +14116,12 @@ async function deliverOne(input, host, file, who, call, known = {}) {
14087
14116
  return "";
14088
14117
  let ran = [];
14089
14118
  if (shell) {
14090
- rels = await namedInCommand(db, pid, place.root, input.cwd ?? place.root, shell);
14119
+ rels = held ? [] : await namedInCommand(db, pid, place.root, input.cwd ?? place.root, shell);
14091
14120
  ran = await commandsRun(db, pid, shell);
14092
14121
  if (!rels.length && !ran.length)
14093
14122
  return "";
14094
14123
  }
14095
- if (event === "session_start" && input.source === "resume") {
14124
+ if (event === "session_start" && input.source === "resume" && !held) {
14096
14125
  const said = await db.selectFrom("delivery").select("id").where("session_id", "=", sessionId(pid, host, input.session_id)).where("agent_id", "is", null).where("event", "=", "session_start").where((eb) => eb.or([eb("reason", "is", null), eb("reason", "!=", "subagent")])).where("outcome", "=", "emitted").executeTakeFirst();
14097
14126
  if (said)
14098
14127
  return "";
@@ -14102,17 +14131,17 @@ async function deliverOne(input, host, file, who, call, known = {}) {
14102
14131
  const asksToTrace = name === "SessionStart" && input.source === "startup" && ![process.env.CLAUDE_PLUGIN_OPTION_AUTO_TRACE, process.env.SPHICA_AUTO_TRACE].some((v) => AUTO_TRACE_OFF.has((v ?? "").trim().toLowerCase()));
14103
14132
  const skill = asksToTrace && host === "codex" && codexInteractive(input) ? traceSkill() : null;
14104
14133
  const newInteractive = asksToTrace && (host === "claude-code" ? process.env.CLAUDE_CODE_ENTRYPOINT === "cli" : skill !== null);
14105
- const make = async () => event === "pre_edit" ? await beforeEdit(reader, pid, rels) : event === "pre_read" ? await beforeRead(reader, pid, rels, sessionId(pid, host, session), who, shell ? "named" : "reading") : event === "prompt" ? await onPrompt(reader, pid, place.root, input.prompt ?? "") : call ? await beforeReview(reader, pid, place.root, call, known.reviewUntil) : {
14134
+ const startReason = name === "SubagentStart" ? "subagent" : input.source && START_SOURCES.has(input.source) ? input.source : null;
14135
+ const make = async () => event === "pre_edit" ? await beforeEdit(reader, pid, rels) : event === "pre_read" ? await beforeRead(reader, pid, rels, sessionId(pid, host, session), who, shell ? "named" : "reading") : event === "prompt" ? await onPrompt(reader, pid, place.root, input.prompt ?? "") : call ? await beforeReview(reader, pid, place.root, call, known.reviewUntil) : held ? { ...HELD, reason: startReason } : name === "SubagentStart" || who !== null ? { ...SUBAGENT_START, reason: startReason } : {
14106
14136
  ...await atStart(reader, pid, branchOf(place.root), {
14107
14137
  file,
14108
14138
  key: place.key,
14109
14139
  host,
14110
- subagent: name === "SubagentStart",
14111
14140
  auto: newInteractive ? session : null,
14112
14141
  ...skill ? { skill } : {},
14113
- owner: name !== "SubagentStart" && isOwnerTurn(input, undefined, undefined, host === "codex" ? process.env.CODEX_THREAD_ID : undefined)
14142
+ owner: isOwnerTurn(input, undefined, undefined, host === "codex" ? process.env.CODEX_THREAD_ID : undefined)
14114
14143
  }),
14115
- reason: name === "SubagentStart" ? "subagent" : input.source && START_SOURCES.has(input.source) ? input.source : null
14144
+ reason: startReason
14116
14145
  };
14117
14146
  const entry = {
14118
14147
  projectId: pid,
@@ -14134,6 +14163,8 @@ async function deliverOne(input, host, file, who, call, known = {}) {
14134
14163
  await log(file, entry, plan).catch(() => {});
14135
14164
  return plan.text;
14136
14165
  } catch (e) {
14166
+ if (held)
14167
+ return "";
14137
14168
  if (e instanceof RevisionMismatch)
14138
14169
  return shell || !markOnce("revision", `${host}\x00${input.session_id}`) ? "" : `Sphica unavailable: ${head(inline(e.message), 400)}`;
14139
14170
  if (event === "prompt" || shell || !onceUnavailable(`${host}\x00${input.session_id}`))
@@ -14169,6 +14200,7 @@ export {
14169
14200
  CONFIRM_GOLD,
14170
14201
  RAN,
14171
14202
  STOP2 as STOP,
14203
+ agentRun,
14172
14204
  codexInteractive,
14173
14205
  deliver,
14174
14206
  deliverableIds,
@@ -47337,16 +47337,13 @@ var branchOf = (root) => {
47337
47337
  return null;
47338
47338
  }
47339
47339
  };
47340
+ var startedByAgent = (session, parent, codexParent) => Boolean(codexParent && codexParent !== session) || Boolean(parent && parent !== session);
47340
47341
  function isOwnerTurn(input2, parent = process.env.SPHICA_PARENT_SESSION, entrypoint = process.env.CLAUDE_CODE_ENTRYPOINT, codexParent) {
47341
47342
  if (!input2.session_id || input2.agent_id)
47342
47343
  return false;
47343
- if (codexParent && codexParent !== input2.session_id)
47344
- return false;
47345
47344
  if (entrypoint?.startsWith("sdk-"))
47346
47345
  return false;
47347
- if (parent)
47348
- return parent === input2.session_id;
47349
- return true;
47346
+ return !startedByAgent(input2.session_id, parent, codexParent);
47350
47347
  }
47351
47348
  var INJECTED = [
47352
47349
  /^<(?:task-notification|channel|cross-session-message|teammate-message|agent-message|slack-ping|slack-tag-message|fetched-web-content|remote-review|remote-review-progress)[\s>]/,
@@ -49173,7 +49170,8 @@ async function checkRecord(db, target, raw, facts = prepareRecord(target.root, r
49173
49170
  "text",
49174
49171
  "external_id",
49175
49172
  "session_id",
49176
- "turn_id"
49173
+ "turn_id",
49174
+ "created_at"
49177
49175
  ]).where("project_id", "=", target.projectId).where("id", "in", [...refs]).execute() : []).map((s) => [s.id, s]));
49178
49176
  for (const r of refs) {
49179
49177
  if (!sources.has(r))
@@ -49418,6 +49416,19 @@ async function checkRecord(db, target, raw, facts = prepareRecord(target.root, r
49418
49416
  problems.push(`${key}: the AI's adoption in s${x.source} left out, so it stays a candidate: ${why}`);
49419
49417
  adoption.splice(adoption.indexOf(x), 1);
49420
49418
  }
49419
+ if (target.origin === "trace") {
49420
+ const newest = (ids) => {
49421
+ let found;
49422
+ for (const s of ids.map((id) => sources.get(id)))
49423
+ if (s?.kind === "session_message" && (!found || s.created_at > found.created_at))
49424
+ found = s;
49425
+ return found;
49426
+ };
49427
+ const adopted = newest(adoption.filter((x) => x.route !== "agent").map((x) => x.source));
49428
+ const proposed = newest(evidence.filter((e) => e.role === "proposes").map((e) => e.source));
49429
+ if (adopted && proposed && proposed.created_at > adopted.created_at)
49430
+ problems.push(`${key}: its adoption (s${adopted.id}) is older than the proposal it cites (s${proposed.id}); if the proposal changed, quote the owner's reply to the final version or leave the adoption out; keep it if the adoption is right`);
49431
+ }
49421
49432
  const grounds = (["decision", "constraint"].includes(u.kind) ? adoption.find((x) => x.route !== "agent") : evidence[0])?.source ?? null;
49422
49433
  const fields = [];
49423
49434
  for (const f of u.fields) {
package/dist/mcp.js CHANGED
@@ -47318,7 +47318,7 @@ var DELIVERY_LIMITS_TEXT = [
47318
47318
  "Counted are the logged delivery rows only: since 0.6.16 a read or edit that showed nothing is not logged (older rows show it as nothing), and a delivery answered while the write lock was busy, or whose log write failed, is not either.",
47319
47319
  "A session's rows are dropped once its last delivery is older than 90 days, so a long period is not a rolling window.",
47320
47320
  "The text delivered then is not kept, only the record ids: a record shown now may have changed since.",
47321
- "Outcomes suppressed and unavailable are not written today, so only emitted and nothing appear.",
47321
+ "suppressed is a session start held back for a run another agent started (claude -p or codex exec from an agent's shell): it shows nothing and keeps no record. The reads such a run held back are not logged. unavailable is not written yet.",
47322
47322
  "Rows without an agent id count as main, as the host reported them, except a subagent start logged without one: subagent, id unknown.",
47323
47323
  "named later: a captured reply of the same session, after the delivery, writes the key whole (questions asked with AskUserQuestion are not counted). An agent may use a record without naming it, naming it does not mean it helped, a reply may be missing, cut, or redacted in capture, and it may come from any agent of the session."
47324
47324
  ];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "sphica",
3
- "version": "0.6.60",
3
+ "version": "0.6.62",
4
4
  "description": "Records Claude Code and Codex sessions on your machine and keeps past implementation and decisions, with their sources, for your agent to find.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -75,7 +75,7 @@ read tools `search` and `read`. Pass the repository root as `cwd` to every tool.
75
75
  | Op | What it does |
76
76
  |---|---|
77
77
  | `add_evidence` | Cites a `source` ref or a committed `file` (path, commit, lines). `role` as in trace. When the owner reports what someone else said, add `reported_speaker`: it stays the owner's report, never that person's statement or an adoption. A file excerpt is stored with keys masked, so quote words around a key, never the key, and cite whole lines around it: a range that cuts through a private key, or leaves a key's name outside, is refused |
78
- | `adopt` | The owner's (or a maintainer's) words that settle a decision or constraint. "Kimura said it was agreed" is not adoption; the owner saying "let's make it final" is |
78
+ | `adopt` | The owner's (or a maintainer's) words that settle a decision or constraint. "Kimura said it was agreed" is not adoption; the owner saying "let's make it final" is. When the proposal changed after a reply (narrowed, widened, or replaced), cite the reply to the final version: a reply to an earlier version does not adopt it |
79
79
  | `anchor` / `replace_anchor` | Adds a code location, or replaces one whose code moved (`from` and `to`, citing the owner's words); the old one is kept as history with those words. A replacement carries no commit, so an implementation whose proof was the replaced anchor goes back to candidate: add an `anchor` op with `commit` in the same batch to keep it active. A `symbol` that is a key or a value Sphica masks is refused: anchor a name, or the path alone. A warning that the path is not in the working tree (with near paths), is a directory, or does not hold the symbol means fix it and check again |
80
80
  | `retire_anchor` | Retires a code location with nothing in its place (`from`, citing the owner's words). Reads and edits are matched by path, so the record stops being shown on that file only once it has no live `applies_to` anchor on the path; retire each one, whatever its symbol. `from` names one live anchor by `path`, and `symbol` or `role` when the path holds more than one; check lists them when it cannot tell. The anchor is kept as history with the owner's words, and read shows it under retired anchors. Retiring an implementation's only code proof puts it back to candidate. In one batch, retirements run first, then replacements, then new anchors |
81
81
  | `replace_aliases` | Replaces the record's search words (`aliases`, up to 12, each 1 to 40 characters) when search needs a word it lacks (the other language, a common term) or an alias is so broad it floods results. Search only, never evidence, so no quote; read prints the current ones, and `[]` clears them |
@@ -57,6 +57,8 @@ and only by saying so: "we rejected yarn", "let's keep SQLite". check refuses th
57
57
  `sphica init` bound. It adopts like the owner's words anywhere, even where their association is CONTRIBUTOR
58
58
  - The merge only shows the code went in. It is evidence for an `implementation` (with the commit message, `role: "implements"`), never adoption
59
59
  - A resolved review thread is not agreement either
60
+ - When the proposal changed after a reply (narrowed, widened, or replaced), quote the owner's or a maintainer's reply to the final version;
61
+ a reply to an earlier version does not adopt it. When no such reply answers the final version, leave the adoption out
60
62
  - `supersedes` and `conflicts` retire or dispute a saved record, so they need the owner's or a maintainer's words among the unit's evidence or adoption.
61
63
  Those words have to be in the source and be the writer's own: a maintainer quoting someone else (a `>` line, a code block, words wholly
62
64
  inside quotation marks or right between two of them) does not count, and neither does a quote that is not there
@@ -48,7 +48,9 @@ Everything goes through Sphica's `record` MCP server (its tools are `trace_pendi
48
48
  `call record_more with cursor: "..."`, the rest of its lines are read with `record_more` and that cursor, until a reply names none
49
49
  (the same goes for `record_save`; nothing is checked or saved again by reading on). Errors refuse the save; fix and check again. Warnings say what will be
50
50
  left out, quarantined, or kept as a candidate, and why. An anchor warning (a path not in the working tree, with near paths; a directory; a
51
- symbol not in the file) means fix the anchor and check again; keep it only when you know it is right
51
+ symbol not in the file) means fix the anchor and check again; keep it only when you know it is right. A warning that the adoption is older
52
+ than the proposal it cites means look at what changed: if the proposal really changed, quote the owner's reply to the final version or leave
53
+ the adoption out; if the later message only explains what was already adopted, cite it as `explains`; if the adoption is right, keep it
52
54
  5. **Save**: `record_save` with the same run and record. A run saves once. A reply that starts with `✗` saved nothing: fix the record,
53
55
  check it, and save with the same run
54
56
  6. **Report** to the owner what was saved, copying save's lines (active, candidate with the reason, quarantined, superseded), all of them:
@@ -112,7 +114,7 @@ The `"..."` stands for the other language's words: in this example, `"データ
112
114
  | `text`, `why`, `scope_note` | In the conversation's language. `text` states the record in one sentence; `why` is the reason given, not one you infer. A dead end's `text` is a lesson another task can use: what fails, under which condition (tool, version, environment), and the cause and the way around it only when the conversation says them. Leave the specifics to the quote, the anchors, and `commands` |
113
115
  | `evidence` | Required. `source` is a ref from context, `quote` is copied **exactly** from that message (a phrase is enough). `role`: `states`, `proposes`, `rejects`, `explains`, `implements`, `decides` (the AI's reply deciding it; see below). When the owner reports what someone else said, add `reported_speaker` |
114
116
  | `options` | Options compared, with `outcome` `chosen` / `rejected` / `deferred` / `proposed` and the `why` given. Evidence is optional per option. A rejected option may add `reconsider_when` (when it would be worth looking at again) with `reconsider_quote` (`source`, `quote`): **only a condition the owner stated, quoting the owner's words**. Never infer one, and never take it from the AI's suggestion or from someone else's words the owner passes on (a `>` line, a code block, or words wholly inside quotation marks refuse the save). A `reconsider_quote` not found in the message refuses the save (unlike other quotes, which quarantine the record) |
115
- | `adoption` | Decisions and constraints only: the words that settle it. The owner's message adopts it as the owner's decision. The AI's own reply adopts it as an AI's decision only under the rules below. The AI proposing something and the owner not objecting is not adoption; leave it out and the record stays a candidate. Words the owner quoted (`>` lines), pasted in a code block, or put wholly inside quotation marks on a line (straight or curly quotes, Japanese corner brackets, backticks) are someone else's and never adopt, and neither do words that stand right between two such marks or apostrophes: quote more of the owner's own words around them. Check reads where the words sit, not what they mean |
117
+ | `adoption` | Decisions and constraints only: the words that settle it. The owner's message adopts it as the owner's decision. The AI's own reply adopts it as an AI's decision only under the rules below. The AI proposing something and the owner not objecting is not adoption; leave it out and the record stays a candidate. For the owner's adoption: when the proposal changed after an owner reply (narrowed, widened, or replaced), quote the owner's reply to the final version; a reply to an earlier version does not adopt it. When no owner reply answers the final version, leave the adoption out. Words the owner quoted (`>` lines), pasted in a code block, or put wholly inside quotation marks on a line (straight or curly quotes, Japanese corner brackets, backticks) are someone else's and never adopt, and neither do words that stand right between two such marks or apostrophes: quote more of the owner's own words around them. Check reads where the words sit, not what they mean |
116
118
  | `anchors` | Only where the record has a code location: `path` relative to the repository root, `symbol` when there is one, `role` `applies_to` (where it applies) or `evidence` (code that shows it was done; add `commit` when known). When an adopted decision or constraint governs how one existing code location behaves (keeping it as it is included), give it `applies_to` there, even if this work did not change it: delivery shows it when that file is read or edited. Confirm the path in the repository; do not infer one from a broad topic, and leave it unanchored when several places are plausible. `no_code_surface` may say why there is none. A `symbol` must be a name in the code, never a key or a value Sphica masks: such a symbol is dropped and the anchor keeps only its path (save reports it) |
117
119
  | `commands` | Dead ends only, up to 5: a command the dead end is about, as typed, cut to the shortest part that still names the failing use (the program and the flag or option, such as `pnpm test --watch`). The first call in a later conversation that runs it, word for word on one line, is stopped once and shown the dead end. Never a bare program name, a command in quotes, two commands joined with `;`, `\|`, or `&`, or one holding a secret |
118
120
  | `aliases` | 8 to 12 short search words in **both Japanese and English** a later reader might type: synonyms, the other language's words, abbreviations. Search only; never evidence. Not broad words that match everything (`code`, `fix`, `update`) |