Skip to content

armgit / cogit

Public Imported from GitHub
0

Git for the intent behind agent-written code. Records what your coding agent decided and why, and links every commit to it.

feat(hooks): leave claude -p sessions unrecorded unless recordHeadless is on

Erenb8dcd8f7243c
diff --git a/docs/guide/settings.md b/docs/guide/settings.md
index 7857096..b0be7f4 100644
--- a/docs/guide/settings.md
+++ b/docs/guide/settings.md
@@ -32,6 +32,14 @@ A one-sentence summary under each message title, so a skim reads better. Off kee
When a chat starts, the agent gets a short summary of where the previous session left off and how to read the record. It costs a few tokens; turn it off if your projects are unrelated.
+### Headless sessions
+
+`recordHeadless` · default `false`
+
+**Record sessions that start without a person, such as `claude -p`.**
+
+Some plugins and scripts run `claude -p` in the background, often once per prompt. Off, cogit leaves those sessions out of the map and the inbox. Turn it on if you do real work through `claude -p` or the SDK and want it recorded.
+
### Tried-before notes
`tryBeforeNotes` · default `true`
diff --git a/docs/schema/config.json b/docs/schema/config.json
index ad66b35..fe41ca5 100644
--- a/docs/schema/config.json
+++ b/docs/schema/config.json
@@ -56,6 +56,10 @@
"default": true,
"type": "boolean"
},
+ "recordHeadless": {
+ "default": false,
+ "type": "boolean"
+ },
"serverPort": {
"default": 4747,
"type": "integer",
@@ -134,6 +138,7 @@
"sideEveryTurns",
"messageSummaries",
"startupContext",
+ "recordHeadless",
"serverPort",
"gitPolicy",
"shareConversations",
diff --git a/packages/cli/src/agents/claude/hooks.ts b/packages/cli/src/agents/claude/hooks.ts
index 67f55be..6db32df 100644
--- a/packages/cli/src/agents/claude/hooks.ts
+++ b/packages/cli/src/agents/claude/hooks.ts
@@ -32,6 +32,15 @@ export function parseHookInput(stdin: string): HookInput | undefined {
return parsed.success ? parsed.data : undefined;
}
+/**
+ * Whether the hook runs in a session nobody types into: `claude -p` and the SDKs
+ * mark themselves `sdk-*` in `CLAUDE_CODE_ENTRYPOINT`, which the hooks inherit.
+ * Other plugins start such sessions in the background, one per prompt.
+ */
+export function isHeadless(env: NodeJS.ProcessEnv): boolean {
+ return env.CLAUDE_CODE_ENTRYPOINT?.startsWith("sdk") ?? false;
+}
+
/** A hook answer Claude Code shows the user as a warning line; the agent does not see it. */
export function userNotice(text: string): Record<string, unknown> {
return { systemMessage: text };
diff --git a/packages/cli/src/agents/claude/index.ts b/packages/cli/src/agents/claude/index.ts
index c1b2089..d92e7d8 100644
--- a/packages/cli/src/agents/claude/index.ts
+++ b/packages/cli/src/agents/claude/index.ts
@@ -1,5 +1,5 @@
import { type AgentAdapter, DEFAULT_AGENT } from "../types.js";
-import { additionalContext, parseHookInput, userNotice } from "./hooks.js";
+import { additionalContext, isHeadless, parseHookInput, userNotice } from "./hooks.js";
import {
allowSkill,
CLAUDE_DEFAULT_RETENTION,
@@ -55,6 +55,7 @@ export const claude: AgentAdapter = {
excerpt,
parseHookInput,
+ isHeadless,
additionalContext,
userNotice,
diff --git a/packages/cli/src/agents/types.ts b/packages/cli/src/agents/types.ts
index f323bde..9e0302d 100644
--- a/packages/cli/src/agents/types.ts
+++ b/packages/cli/src/agents/types.ts
@@ -135,6 +135,8 @@ export interface AgentAdapter {
excerpt(text: string, max?: number): string;
/** Parses a hook's stdin; undefined when it is not a payload cogit understands. */
parseHookInput(stdin: string): HookInput | undefined;
+ /** Whether the hook runs in a session started without a person (`claude -p`, an SDK). */
+ isHeadless(env: NodeJS.ProcessEnv): boolean;
/** Hook output that adds context for the agent, in the agent's own protocol. */
additionalContext(event: string, text: string): Record<string, unknown>;
/** A hook answer that shows one line to the user, not to the agent. */
diff --git a/packages/cli/src/hooks/run.ts b/packages/cli/src/hooks/run.ts
index 9448634..86c8b41 100644
--- a/packages/cli/src/hooks/run.ts
+++ b/packages/cli/src/hooks/run.ts
@@ -6,6 +6,7 @@ import { type AgentAdapter, defaultAgent, type HookInput } from "../agents/index
import { Slug } from "../schema/common.js";
import { captureDisabled, projectPaths } from "../store/paths.js";
import { resolveProjectRoot } from "../store/root.js";
+import { loadConfig } from "../store/stores.js";
import { onPreToolUse } from "./pretooluse.js";
import { onPromptSubmit } from "./promptsubmit.js";
import { onSessionEnd } from "./sessionend.js";
@@ -126,6 +127,8 @@ export async function runHook(
await agent
.markLive(input.session_id)
.catch((err: Error) => debug(`cogit mark: ${err.message}`));
+ // A session nobody types into is left alone unless the user asked for it.
+ if (agent.isHeadless(env) && !(await loadConfig(env)).recordHeadless) return undefined;
// In a linked worktree both point at the worktree; the record lives in the main checkout.
const { root } = await resolveProjectRoot(env[agent.projectDirEnv] ?? input.cwd ?? ".");
const initialized = existsSync(projectPaths(root).project);
diff --git a/packages/cli/src/schema/config.ts b/packages/cli/src/schema/config.ts
index 685c81c..ef80f3a 100644
--- a/packages/cli/src/schema/config.ts
+++ b/packages/cli/src/schema/config.ts
@@ -39,6 +39,12 @@ export const Config = z.object({
* how to read the record (`log` / `show`). On by default; costs only tokens.
*/
startupContext: z.boolean().default(true),
+ /**
+ * Whether sessions started without a person (`claude -p`, an SDK) are recorded.
+ * Off by default: other plugins start them in the background, one per prompt,
+ * and they would fill the map and the inbox.
+ */
+ recordHeadless: z.boolean().default(false),
/** Port the local map server binds on `127.0.0.1`. */
serverPort: z.int().min(1).max(65535).default(4747),
/** Default for new projects; `init` asks per repo. Story 9.3: the record travels. */
diff --git a/packages/cli/src/view/model.ts b/packages/cli/src/view/model.ts
index fc46371..bcfcc54 100644
--- a/packages/cli/src/view/model.ts
+++ b/packages/cli/src/view/model.ts
@@ -33,6 +33,7 @@ export const PANEL_EDITABLE_KEYS = [
"recorder",
"messageSummaries",
"startupContext",
+ "recordHeadless",
"tryBeforeNotes",
"language",
"updateEveryTurns",
@@ -387,6 +388,8 @@ export interface PanelSettings {
sideModel: string;
messageSummaries: boolean;
startupContext: boolean;
+ /** Whether `claude -p` and SDK sessions are recorded. */
+ recordHeadless: boolean;
/**
* Whether the agent is told before editing a file about options earlier
* thoughts considered and rejected (Story 10.4).
diff --git a/packages/cli/src/view/panel.ts b/packages/cli/src/view/panel.ts
index b813060..68fc491 100644
--- a/packages/cli/src/view/panel.ts
+++ b/packages/cli/src/view/panel.ts
@@ -67,6 +67,7 @@ export function panelSettings(config: Config): PanelSettings {
sideModel: config.sideModel,
messageSummaries: config.messageSummaries,
startupContext: config.startupContext,
+ recordHeadless: config.recordHeadless,
tryBeforeNotes: config.tryBeforeNotes,
shareConversations: config.shareConversations,
recordCommit: config.recordCommit,
diff --git a/packages/cli/src/view/settings.ts b/packages/cli/src/view/settings.ts
index 2c6788f..856f752 100644
--- a/packages/cli/src/view/settings.ts
+++ b/packages/cli/src/view/settings.ts
@@ -85,6 +85,16 @@ const EDITABLE: FieldSpec[] = [
"are unrelated.",
kind: "boolean",
},
+ {
+ key: "recordHeadless",
+ label: "Headless sessions",
+ help: "Record sessions that start without a person, such as `claude -p`.",
+ details:
+ "Some plugins and scripts run `claude -p` in the background, often once per prompt. " +
+ "Off, cogit leaves those sessions out of the map and the inbox. Turn it on if you do " +
+ "real work through `claude -p` or the SDK and want it recorded.",
+ kind: "boolean",
+ },
{
key: "tryBeforeNotes",
label: "Tried-before notes",
@@ -260,6 +270,7 @@ export const DEFAULT_SETTINGS: PanelSettings = {
sideModel: "haiku",
messageSummaries: false,
startupContext: true,
+ recordHeadless: false,
tryBeforeNotes: true,
shareConversations: false,
recordCommit: "ask",
@@ -278,6 +289,7 @@ export function editableSettings(settings: PanelSettings): PanelEditableSettings
recorder: settings.recorder,
messageSummaries: settings.messageSummaries,
startupContext: settings.startupContext,
+ recordHeadless: settings.recordHeadless,
tryBeforeNotes: settings.tryBeforeNotes,
language: settings.language,
updateEveryTurns: settings.updateEveryTurns,
diff --git a/packages/cli/test/hooks.test.ts b/packages/cli/test/hooks.test.ts
index 2bdcfb5..5acaf30 100644
--- a/packages/cli/test/hooks.test.ts
+++ b/packages/cli/test/hooks.test.ts
@@ -296,6 +296,19 @@ describe("runHook", () => {
expect(await sessionStart("clear")).toBeUndefined();
});
+ it("leaves `claude -p` sessions alone unless recordHeadless is on", async () => {
+ const headless = { ...env, CLAUDE_CODE_ENTRYPOINT: "sdk-cli" };
+ expect(await sessionStart("startup", headless)).toBeUndefined();
+ await initialized(1);
+ expect(await sessionStart("startup", headless)).toBeUndefined();
+ expect(await stop({}, headless)).toBeUndefined();
+ expect(spawned).toEqual([]);
+ await configSet("recordHeadless", "true", fakeIo(env));
+ expect(await sessionStart("startup", headless)).toContain("records this project's lineage");
+ await stop({}, headless);
+ expect(spawned).not.toEqual([]);
+ });
+
it("silences the setup hint per project with hint-off and undoes it with hint-on", async () => {
const off = fakeIo(env);
await configHintOff(root, off);
diff --git a/packages/cli/test/panel.test.ts b/packages/cli/test/panel.test.ts
index f53240a..5f880ba 100644
--- a/packages/cli/test/panel.test.ts
+++ b/packages/cli/test/panel.test.ts
@@ -89,6 +89,7 @@ describe("buildPanel", () => {
sideModel: "haiku",
messageSummaries: false,
startupContext: true,
+ recordHeadless: false,
tryBeforeNotes: true,
shareConversations: false,
recordCommit: "ask",
diff --git a/packages/cli/test/server.test.ts b/packages/cli/test/server.test.ts
index 4e0a41c..b9cccdd 100644
--- a/packages/cli/test/server.test.ts
+++ b/packages/cli/test/server.test.ts
@@ -550,6 +550,7 @@ describe("settings read", () => {
recorder: "mixed",
messageSummaries: false,
startupContext: true,
+ recordHeadless: false,
tryBeforeNotes: true,
language: "auto",
updateEveryTurns: 15,
diff --git a/packages/cli/test/settings.test.ts b/packages/cli/test/settings.test.ts
index 4255cd1..e114e86 100644
--- a/packages/cli/test/settings.test.ts
+++ b/packages/cli/test/settings.test.ts
@@ -23,6 +23,7 @@ describe("settings model", () => {
sideModel: parsed.sideModel,
messageSummaries: parsed.messageSummaries,
startupContext: parsed.startupContext,
+ recordHeadless: parsed.recordHeadless,
tryBeforeNotes: parsed.tryBeforeNotes,
shareConversations: parsed.shareConversations,
recordCommit: parsed.recordCommit,
@@ -67,6 +68,7 @@ describe("settings model", () => {
recorder: "mixed",
messageSummaries: false,
startupContext: true,
+ recordHeadless: false,
tryBeforeNotes: true,
language: "tr",
updateEveryTurns: 8,
diff --git a/packages/template/src/fixture.ts b/packages/template/src/fixture.ts
index 42ea81b..970d3d3 100644
--- a/packages/template/src/fixture.ts
+++ b/packages/template/src/fixture.ts
@@ -60,6 +60,7 @@ export const fixture: LineageViewModel = {
sideModel: "haiku",
messageSummaries: false,
startupContext: true,
+ recordHeadless: false,
tryBeforeNotes: true,
shareConversations: false,
recordCommit: "ask",