From 8456435d88f4fb565dccbf01f07350fca6a89aa5 Mon Sep 17 00:00:00 2001 From: Bradley Hilton Date: Mon, 26 Oct 2026 09:19:31 +0100 Subject: [PATCH] feat(hooks): supply ATOMIC_SESSION_ID to shells for work-start binding MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The atomic CLI's session-binding flags on intent update (--session-id, or the ATOMIC_SESSION_ID environment variable) let `atomic intent update --status in_progress` bind the governing intent to the active session turn. Without session context the command stays a status-only update and the intent graph never learns which intent governs the turn's recorded changes. Both plugin entrypoints now supply that context: - v1 `shell.env` reads `input.sessionID` (bash tool events carry it; terminal/pty shells do not, keeping the human status-only path). - v2 `create.before` reads `event.sessionID` when the host provides it. Injection is gated on a new read-only `isStarted` tracker lookup: a failed binding fails the whole update, so only sessions whose session-start hook has fired get the variable — the CLI rejects a declaration for an unknown session. Unstarted and terminal shells keep the previous environment exactly. Tests: v1 started/unstarted/terminal shell cases, v2 started/foreign session cases (20 pass). Integration version 1.1.1 -> 1.2.0 so `atomic agent enable` ships the updated package from storage. --- atomic-integration.toml | 2 +- plugins/atomic-hooks.ts | 30 ++++++++++++++++-- tests/session-isolation.test.ts | 56 +++++++++++++++++++++++++++++++++ 3 files changed, 85 insertions(+), 3 deletions(-) diff --git a/atomic-integration.toml b/atomic-integration.toml index 966274f..0c07485 100644 --- a/atomic-integration.toml +++ b/atomic-integration.toml @@ -1,6 +1,6 @@ schema = 1 agent = "opencode" -version = "1.1.1" +version = "1.2.0" [requires] atomic = ">=0.11.0" diff --git a/plugins/atomic-hooks.ts b/plugins/atomic-hooks.ts index f464645..8ada590 100644 --- a/plugins/atomic-hooks.ts +++ b/plugins/atomic-hooks.ts @@ -185,6 +185,13 @@ const createTracker = (directory, invoke) => { reset(state); sessions.delete(sid); } + // Read-only lookup: never materialize state just to ask. A session the + // plugin has started has a session ledger on disk, which is the CLI's + // precondition for accepting a turn-bound work-start declaration. + function isStarted(sid) { + const state = sessions.get(sid); + return !!(state && state.started); + } return { stateFor, hook, @@ -193,6 +200,7 @@ const createTracker = (directory, invoke) => { beginTurn, stopTurn, endSession, + isStarted, }; }; @@ -325,9 +333,20 @@ export const AtomicHooksPlugin = async ({ directory, $ }) => { state.tools.delete(input.callID); }); }, - "shell.env": async (_input, output) => { + "shell.env": async (input, output) => { output.env.ATOMIC_AGENT = "opencode"; output.env.ATOMIC_AGENT_VERSION = ATOMIC_AGENT_VERSION; + // Supply session context so a work-start declaration + // (`atomic intent update --status in_progress`) binds the intent + // to this turn: the turn's recording then carries the intent UID in + // plan_id, which is how the intent graph attributes the turn's changes. + // Without the variable the CLI stays a status-only update. Only + // sessions this plugin started get it — the CLI rejects a declaration + // for an unknown session, and a failed binding fails the whole update. + // Terminal shells (no sessionID in the event) keep the human path. + const sid = input?.sessionID; + if (typeof sid === "string" && sid && t.isStarted(sid)) + output.env.ATOMIC_SESSION_ID = sid; }, }; }; @@ -365,7 +384,7 @@ const setupV2 = async (ctx, invoke) => { directory, invoke ?? ((json, verb) => spawnHook(directory, json, verb)), ); - const { enqueue, stopTurn } = t; + const { enqueue, stopTurn, isStarted } = t; // The public event stream may not be scoped to this plugin instance's // location, so only track sessions that are known to belong to it. const known = new Set(); @@ -458,6 +477,13 @@ const setupV2 = async (ctx, invoke) => { await ctx.shell.hook("create.before", (event) => { event.env.ATOMIC_AGENT = "opencode"; event.env.ATOMIC_AGENT_VERSION = ATOMIC_AGENT_VERSION; + // Same session-context contract as the v1 `shell.env` hook: a started + // session's shells carry ATOMIC_SESSION_ID so `atomic intent update + // --status in_progress` binds the intent to the active turn instead of + // degrading to a status-only update. + const sid = event?.sessionID; + if (typeof sid === "string" && sid && isStarted(sid)) + event.env.ATOMIC_SESSION_ID = sid; }); } catch (error) { try { diff --git a/tests/session-isolation.test.ts b/tests/session-isolation.test.ts index be38fc6..0b61638 100644 --- a/tests/session-isolation.test.ts +++ b/tests/session-isolation.test.ts @@ -684,4 +684,60 @@ describe("OpenCode v2 plugin", () => { await until(() => f.calls.some((c) => c.verb === "session-end")); await f.cleanup?.(); }); + + test("started sessions expose ATOMIC_SESSION_ID to shells", async () => { + const f = await fixtureV2(); + await f.prompt("bind", "ses_bind"); + const env: any = {}; + f.hooks["shell.create.before"]({ + command: "atomic intent update DEMO::you::1 --status in_progress", + cwd: f.root, + sessionID: "ses_bind", + env, + }); + expect(env.ATOMIC_SESSION_ID).toBe("ses_bind"); + const foreign: any = {}; + f.hooks["shell.create.before"]({ + command: "ls", + cwd: f.root, + sessionID: "ses_elsewhere", + env: foreign, + }); + expect(foreign.ATOMIC_SESSION_ID).toBeUndefined(); + expect(foreign.ATOMIC_AGENT).toBe("opencode"); + await f.cleanup?.(); + }); +}); + +describe("work-start binding context", () => { + test("v1 started sessions expose ATOMIC_SESSION_ID to shells", async () => { + const f = await fixture(); + await f.prompt("bind"); + const env: any = {}; + await f.plugin["shell.env"]( + { cwd: f.root, sessionID: "bind" }, + { env }, + ); + expect(env).toMatchObject({ + ATOMIC_AGENT: "opencode", + ATOMIC_SESSION_ID: "bind", + }); + }); + + test("v1 unstarted sessions and terminal shells get no session id", async () => { + const f = await fixture(); + const unknown: any = {}; + await f.plugin["shell.env"]( + { cwd: f.root, sessionID: "never-started" }, + { env: unknown }, + ); + expect(unknown.ATOMIC_AGENT).toBe("opencode"); + expect(unknown.ATOMIC_SESSION_ID).toBeUndefined(); + const terminal: any = {}; + await f.plugin["shell.env"]({ cwd: f.root }, { env: terminal }); + expect(terminal.ATOMIC_AGENT).toBe("opencode"); + expect(terminal.ATOMIC_SESSION_ID).toBeUndefined(); + // The read-only lookup must not materialize state for an unknown session. + expect(f.calls.filter((c) => c.payload.session_id === "never-started")).toHaveLength(0); + }); });