From 14ad245177614b84682e918be82ef85b8b299622 Mon Sep 17 00:00:00 2001 From: J Date: Sat, 7 Nov 2026 16:25:58 -0800 Subject: [PATCH 1/2] Answer the directory's review warnings where the code can The plugin directory's check of 0.4.0 listed warnings against the hooks module and the manifest. This addresses the ones the code can: - The four git commands are each written out whole as fixed text in ioOf (run.git takes a GitCommand name), so the directory reads exactly what runs instead of "git" with variable arguments. Same commands as before. - plugin.json drops `types`, which the directory reported as an unrecognized field; the contract sits at the default path that the minimum supported release finds on its own, and strict validation still checks every state key against it. - The plugin README answers the remaining findings in their own terms: the exact git commands, no build, start-up, settings or instructions file written of the mod's own accord, no tool but its own two answered in place of the tool, what the command and session-start hooks do, and that the summary call is the only request the mod makes itself. Version 0.4.1, not released yet. --- CHANGELOG.md | 8 ++++++++ README.md | 2 +- sessionpad/.claude-plugin/plugin.json | 3 +-- sessionpad/README.md | 8 ++++---- sessionpad/hooks/register.ts | 20 +++++++++++++++++++- sessionpad/src/git.ts | 14 +++++++------- sessionpad/src/io.ts | 14 ++++++++++++-- sessionpad/tests/io.test.ts | 23 ++++++++++++++++++----- 8 files changed, 70 insertions(+), 22 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f340df4..aaea7e5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,13 @@ # Changelog +## 0.4.1 (not released yet) + +### Changed + +- The four git commands the mod runs are each written out whole, as fixed text, in the hooks module, so the plugin directory can read exactly what runs. They are the same commands as before. +- `plugin.json` no longer names `types`: the contract is at its default path, `types/index.d.ts`, which Claude Code 2.1.299 and later find without it, and the plugin directory reported the field as unrecognized. +- The plugin README answers the directory's review in its own terms: the exact git commands, that the mod edits no build, start-up, settings or instructions file of its own accord, that no tool but its own two is answered in place of the tool, what its hooks on commands and on `/clear`, `/resume` and `/branch` do, and that the summary call is the only request it makes itself. + ## 0.4.0 (2026-10-29) ### Changed diff --git a/README.md b/README.md index bf06f44..eb64b6a 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ sessionpad is beta software. A later version may change how it stores your notes > > To turn them off, set it back to `off` the same way. Sessions already open in other windows may keep the old setting until they start again. While they are off, each turn's line in the Timeline is its prompt's first line, and the mod makes no model calls at all. -Status: beta. Version 0.4.0, released 2026-10-29, with all four milestones built (notes, timeline, workspace, pruning). +Status: beta. Version 0.4.1, not released yet; 0.4.0 was released 2026-10-29, with all four milestones built (notes, timeline, workspace, pruning). ## What it does diff --git a/sessionpad/.claude-plugin/plugin.json b/sessionpad/.claude-plugin/plugin.json index 994ab19..cd90c5a 100644 --- a/sessionpad/.claude-plugin/plugin.json +++ b/sessionpad/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "sessionpad", "displayName": "Session Pad", - "version": "0.4.0", + "version": "0.4.1", "description": "A notepad for each Claude Code session: a headline and notes, a timeline of every turn, and the session's worktree and disk use, in a pane and above the prompt.", "author": { "name": "j127" @@ -12,7 +12,6 @@ "supportUrl": "https://github.com/j127/sessionpad/issues", "privacyPolicyUrl": "https://github.com/j127/sessionpad/blob/main/PRIVACY.md", "termsOfServiceUrl": "https://github.com/j127/sessionpad/blob/main/LICENSE", - "types": "./types/index.d.ts", "userConfig": { "showBand": { "type": "boolean", diff --git a/sessionpad/README.md b/sessionpad/README.md index 7c8e854..8c90f27 100644 --- a/sessionpad/README.md +++ b/sessionpad/README.md @@ -22,7 +22,7 @@ Session Pad is a Claude Code mod: it runs in Claude Code 2.1.299 or later, in th - **Nothing leaves your machine except through Claude Code's own model requests**, in two cases: when you ask Claude about the pad, its `notes_read` tool hands Claude the headline and the newest notes (up to 50, or 20,000 characters), which then go out as part of your conversation; and summary lines, if you turn them on. The mod makes no network calls of its own. - **Summary lines are off until you turn them on**, with the `summaryModel` setting (see [Settings](#settings)). With them on, after each turn the mod asks Claude Haiku, on your own plan or API key, for a one-line summary. It sends the prompt's first 200 characters, the start of Claude's final answer (1,500 characters at most), the names of the files written (not their paths or contents) and the number of commands run. A call is about 500 tokens in and 20 out, roughly 6 cents per 1,000 turns on Haiku 5.5 at the API prices of October 2026 (ten times that if your Claude Code's `haiku` is Haiku 4.5); the Timeline tab shows the running total. - **What it watches in the session:** it hooks each prompt you send, each turn's start and end, and each Edit, Write, NotebookEdit and Bash call, to write the timeline: the prompt's first 200 characters, the paths of the files written (up to 25 a turn) and how many commands ran. These hooks only observe: they pass every prompt and call on unchanged, and never block one. -- **Programs it runs:** `git`, read-only, in the session's folder, for the branch and the worktrees; `du -sk` from your home folder (the root folder where there is none), in the background, to measure worktree sizes (the `measureDisk` setting turns this off); and `rm`, only on the mod's own timeline files, when old sessions are pruned (where there is no `rm`, as on Windows, those files are emptied instead). +- **Programs it runs:** `git`, read-only, in the session's folder, for the branch and the worktrees, as four fixed commands: `git rev-parse --show-toplevel`, `git symbolic-ref --short -q HEAD`, `git rev-parse --short HEAD` and `git worktree list --porcelain`; `du -sk` from your home folder (the root folder where there is none), in the background, to measure worktree sizes (the `measureDisk` setting turns this off); and `rm`, only on the mod's own timeline files, when old sessions are pruned (where there is no `rm`, as on Windows, those files are emptied instead). - **What it stores, all on your machine:** - in the mod's key-value store, a JSON file under `~/.claude/plugins/store/`: each session's headline and notes; an index of sessions, with each one's working folder, repository root and when it was last seen; each worktree's measured size, keyed by its path; the running total of summary calls; whether the summary offer was answered; and when the last prune ran; - one timeline file a session under `~/.claude/sessionpad/timeline/`, each entry holding when the turn ended and how long it ran, the prompt's first 200 characters, the summary line, up to 25 paths written, the number of commands, the branch, the worktree's path and the turn's token counts; @@ -32,9 +32,9 @@ Session Pad is a Claude Code mod: it runs in Claude Code 2.1.299 or later, in th - **What it deletes:** a session nobody has opened for `retentionDays` (90 by default) loses its pad, its timeline file (and any copy of one put aside as unreadable) and its index row; sizes measured that long ago go too, and so do timeline files that old that no session in the index owns. Exports are never touched. - **Settings it changes:** none. It reads its own settings, and a change you make in `/config` reloads it. -- **The model call** goes through Claude Code's own model access, on the plan or API key the session already uses; the mod never reads a key, token or credential itself. -- **What its hooks change:** nothing that passes through them, with two exceptions that are the mod's own: its hooks on its two tools, `note` and `notes_read`, answer those tools, which is how they work, and its commands answer `/pad`, `/note`, `/headline` and `/pad-export`. -- **Files it writes outside its own folders:** only the `/pad-export` file you name. An export never replaces a file that isn't an earlier export: each one starts with the line ``, and a file without it is left alone. +- **The model call** goes through Claude Code's own model access, on the plan or API key the session already uses; the mod never reads a key, token or credential itself, and asks for none in its settings. The summary call is the only request the mod makes itself, and it sends only what the summary-lines bullet above lists; `notes_read` answers Claude inside your conversation, as the first bullet says. +- **What its hooks change:** nothing that passes through them, with two exceptions that are the mod's own: its hooks on its two tools, `note` and `notes_read`, answer those tools, which is how they work (no other tool is ever answered in place of the tool), and its commands answer `/pad`, `/note`, `/headline` and `/pad-export`. Its hooks on commands pass every other command on untouched, and its hook on the session start that `/clear`, `/resume` and `/branch` report only reloads the pad and passes that event on unchanged. +- **Files it writes outside its own folders:** only the `/pad-export` file you name. It is not meant to edit any build, start-up, settings or instructions file, and writes none of its own accord: inside its folders it writes only its timeline files, and outside them only the export you ask for. An export never replaces a file that isn't an earlier export: each one starts with the line ``, and a file without it is left alone. ## Settings diff --git a/sessionpad/hooks/register.ts b/sessionpad/hooks/register.ts index 13a128e..379c57a 100644 --- a/sessionpad/hooks/register.ts +++ b/sessionpad/hooks/register.ts @@ -245,7 +245,25 @@ export function ioOf($: EngineInterface): Io { configDir: () => $.env.get("CLAUDE_CONFIG_DIR"), }, run: { - git: (args, init) => $.process.run(["git", ...args], init), + // Each git command whole, as fixed text (see GitCommand in ../src/io.ts). + git: (command, init) => { + switch (command) { + case "top-level": + return $.process.run(["git", "rev-parse", "--show-toplevel"], init); + case "branch": + return $.process.run( + ["git", "symbolic-ref", "--short", "-q", "HEAD"], + init + ); + case "short-sha": + return $.process.run(["git", "rev-parse", "--short", "HEAD"], init); + case "worktrees": + return $.process.run( + ["git", "worktree", "list", "--porcelain"], + init + ); + } + }, du: (path, init) => $.process.run(["du", "-sk", "--", path], init), rm: (paths, init) => $.process.run(["rm", "-f", "--", ...paths], init), }, diff --git a/sessionpad/src/git.ts b/sessionpad/src/git.ts index f50372b..bdc26e8 100644 --- a/sessionpad/src/git.ts +++ b/sessionpad/src/git.ts @@ -2,7 +2,7 @@ // $.process.run call in the hooks module). Never // called while drawing: the end of a turn runs it on a timer. -import type { Io } from "./io"; +import type { GitCommand, Io } from "./io"; import type { Worktree } from "../types"; /** The branch and the working tree's top folder; both null outside a repo. */ @@ -11,9 +11,9 @@ export type GitPlace = { branch: string | null; worktree: string | null }; const GIT_TIMEOUT_MS = 5000; /** One git command's trimmed output, or null when it failed or wouldn't start. */ -async function git(io: Io, args: readonly string[]): Promise { +async function git(io: Io, command: GitCommand): Promise { try { - const ran = await io.run.git(args, { + const ran = await io.run.git(command, { timeoutMs: GIT_TIMEOUT_MS, }); const out = ran.stdout.trim(); @@ -28,13 +28,13 @@ async function git(io: Io, args: readonly string[]): Promise { * ` for a detached HEAD, and the working tree's top folder. */ export async function gitPlace(io: Io): Promise { - const worktree = await git(io, ["rev-parse", "--show-toplevel"]); + const worktree = await git(io, "top-level"); if (worktree === null) return { branch: null, worktree: null }; // symbolic-ref names the branch even before its first commit, where // `rev-parse --abbrev-ref HEAD` fails; it fails on a detached HEAD. - const branch = await git(io, ["symbolic-ref", "--short", "-q", "HEAD"]); + const branch = await git(io, "branch"); if (branch !== null) return { branch, worktree }; - const sha = await git(io, ["rev-parse", "--short", "HEAD"]); + const sha = await git(io, "short-sha"); return { branch: sha === null ? "detached HEAD" : `detached at ${sha}`, worktree, @@ -91,7 +91,7 @@ export async function listWorktrees( io: Io, current: GitPlace & { worktree: string } ): Promise { - const listed = await git(io, ["worktree", "list", "--porcelain"]); + const listed = await git(io, "worktrees"); const others = listed === null ? [] diff --git a/sessionpad/src/io.ts b/sessionpad/src/io.ts index 367d61c..760b059 100644 --- a/sessionpad/src/io.ts +++ b/sessionpad/src/io.ts @@ -15,6 +15,16 @@ type RunInit = NonNullable[1]>; type Ran = ReturnType; type LogOptions = NonNullable[1]>; +/** + * The git commands the mod runs, each a whole command written out as fixed + * text in the hooks module, so the plugin directory reads exactly what runs: + * - `top-level`: `git rev-parse --show-toplevel`, the working tree's folder; + * - `branch`: `git symbolic-ref --short -q HEAD`, the branch checked out; + * - `short-sha`: `git rev-parse --short HEAD`, for a detached HEAD; + * - `worktrees`: `git worktree list --porcelain`, the repository's trees. + */ +export type GitCommand = "top-level" | "branch" | "short-sha" | "worktrees"; + export type Io = StateDollar & { store: Pick; clock: Pick; @@ -44,8 +54,8 @@ export type Io = StateDollar & { configDir: () => Promise; }; run: { - /** `git `. */ - git: (args: readonly string[], init: RunInit) => Ran; + /** One of the four read-only git commands, written out in the hooks module. */ + git: (command: GitCommand, init: RunInit) => Ran; /** `du -sk -- `: one tree's size in kibibytes. */ du: (path: string, init: RunInit) => Ran; /** `rm -f -- `: the mod's own timeline files, when pruned. */ diff --git a/sessionpad/tests/io.test.ts b/sessionpad/tests/io.test.ts index f29b5b7..2c1d522 100644 --- a/sessionpad/tests/io.test.ts +++ b/sessionpad/tests/io.test.ts @@ -120,17 +120,30 @@ describe("ioOf's other calls", () => { ]); }); + test("run.git runs each named command, whole", async () => { + const { $, calls } = fakeEngine(() => Promise.resolve({ exitCode: 0 })); + const io = ioOf($); + const init = { timeoutMs: 1 }; + await io.run.git("top-level", init); + await io.run.git("branch", init); + await io.run.git("short-sha", init); + await io.run.git("worktrees", init); + expect(calls).toEqual( + [ + ["git", "rev-parse", "--show-toplevel"], + ["git", "symbolic-ref", "--short", "-q", "HEAD"], + ["git", "rev-parse", "--short", "HEAD"], + ["git", "worktree", "list", "--porcelain"], + ].map((argv) => ({ name: "process.run", args: [argv, init] })) + ); + }); + test("run names its program and keeps the arguments after --", async () => { const { $, calls } = fakeEngine(() => Promise.resolve({ exitCode: 0 })); const io = ioOf($); - await io.run.git(["rev-parse", "HEAD"], { timeoutMs: 1 }); await io.run.du("/repo", { timeoutMs: 2, cwd: "/home" }); await io.run.rm(["/a.json", "-b.json"], { cwd: "/t", timeoutMs: 3 }); expect(calls).toEqual([ - { - name: "process.run", - args: [["git", "rev-parse", "HEAD"], { timeoutMs: 1 }], - }, { name: "process.run", args: [["du", "-sk", "--", "/repo"], { timeoutMs: 2, cwd: "/home" }], From fca1a9f0c74d69441509d09019cc15ee2d1ba7b4 Mon Sep 17 00:00:00 2001 From: J Date: Sat, 7 Nov 2026 16:28:58 -0800 Subject: [PATCH 2/2] Make the README's answers match what the hooks and writes do The review found two of the new README sentences untrue of the code. The session-start hook for /clear, /resume and /branch does more than reload the pad: it carries the pad and the timeline on /clear and /branch, drops unsaved typing in the pane and refreshes the Workspace tab, while still passing the event on unchanged. And inside its folders the mod also writes the exports you ask for and a copy of a timeline it finds unreadable. Both sentences now say so. The git.ts header names the four fixed calls, and the git switch gets a never-typed default, so a command name added without its case fails to type-check. --- sessionpad/README.md | 4 ++-- sessionpad/hooks/register.ts | 8 ++++++++ sessionpad/src/git.ts | 4 ++-- 3 files changed, 12 insertions(+), 4 deletions(-) diff --git a/sessionpad/README.md b/sessionpad/README.md index 8c90f27..0814159 100644 --- a/sessionpad/README.md +++ b/sessionpad/README.md @@ -33,8 +33,8 @@ Session Pad is a Claude Code mod: it runs in Claude Code 2.1.299 or later, in th - **What it deletes:** a session nobody has opened for `retentionDays` (90 by default) loses its pad, its timeline file (and any copy of one put aside as unreadable) and its index row; sizes measured that long ago go too, and so do timeline files that old that no session in the index owns. Exports are never touched. - **Settings it changes:** none. It reads its own settings, and a change you make in `/config` reloads it. - **The model call** goes through Claude Code's own model access, on the plan or API key the session already uses; the mod never reads a key, token or credential itself, and asks for none in its settings. The summary call is the only request the mod makes itself, and it sends only what the summary-lines bullet above lists; `notes_read` answers Claude inside your conversation, as the first bullet says. -- **What its hooks change:** nothing that passes through them, with two exceptions that are the mod's own: its hooks on its two tools, `note` and `notes_read`, answer those tools, which is how they work (no other tool is ever answered in place of the tool), and its commands answer `/pad`, `/note`, `/headline` and `/pad-export`. Its hooks on commands pass every other command on untouched, and its hook on the session start that `/clear`, `/resume` and `/branch` report only reloads the pad and passes that event on unchanged. -- **Files it writes outside its own folders:** only the `/pad-export` file you name. It is not meant to edit any build, start-up, settings or instructions file, and writes none of its own accord: inside its folders it writes only its timeline files, and outside them only the export you ask for. An export never replaces a file that isn't an earlier export: each one starts with the line ``, and a file without it is left alone. +- **What its hooks change:** nothing that passes through them, with two exceptions that are the mod's own: its hooks on its two tools, `note` and `notes_read`, answer those tools, which is how they work (no other tool is ever answered in place of the tool), and its commands answer `/pad`, `/note`, `/headline` and `/pad-export`. Its hooks on commands pass every other command on untouched, and its hook on the session start that `/clear`, `/resume` and `/branch` report passes that event on unchanged: it carries the pad and the timeline to the new session on `/clear` and `/branch`, loads that session's pad, drops any unsaved typing in the pane, and refreshes the Workspace tab. +- **Files it writes outside its own folders:** only the `/pad-export` file you name. It is not meant to edit any build, start-up, settings or instructions file, and writes none of its own accord: inside its folders it writes only its timeline files (and a copy of one it finds unreadable) and the exports you ask for, and outside them only an export to a path you name. An export never replaces a file that isn't an earlier export: each one starts with the line ``, and a file without it is left alone. ## Settings diff --git a/sessionpad/hooks/register.ts b/sessionpad/hooks/register.ts index 379c57a..1e04cbd 100644 --- a/sessionpad/hooks/register.ts +++ b/sessionpad/hooks/register.ts @@ -262,6 +262,14 @@ export function ioOf($: EngineInterface): Io { ["git", "worktree", "list", "--porcelain"], init ); + default: { + // A name added to GitCommand without its case here fails to + // type-check; at run time, it runs nothing. + const unknown: never = command; + return Promise.reject( + new Error(`sessionpad: no git command ${String(unknown)}`) + ); + } } }, du: (path, init) => $.process.run(["du", "-sk", "--", path], init), diff --git a/sessionpad/src/git.ts b/sessionpad/src/git.ts index bdc26e8..f5de26a 100644 --- a/sessionpad/src/git.ts +++ b/sessionpad/src/git.ts @@ -1,5 +1,5 @@ -// Where the session's work lives, read from git through io.run.git (a -// $.process.run call in the hooks module). Never +// Where the session's work lives, read from git through io.run.git (one +// of four fixed $.process.run calls in the hooks module). Never // called while drawing: the end of a turn runs it on a timer. import type { GitCommand, Io } from "./io";