Claude Code Mod API Session

Mod API: Session

$.session lets a mod read the running session as plain data, compact it, and send messages to other agents or sessions. Its events tell a mod when a session starts, ends, compacts, or gets a message. This hook shows a toast when a session starts:

on('session.start', async ($, e, next) => {
  $.ui.toast('Session started')
  return next(e)
})

In the "Where" column, Run time means in a hook, in a closure that a hook drew, or in a timer callback. It does not mean inside register.

Members of $.session

Mark	Item	What it does	How it works	Where it can be used	Source
✅	$.session.messages	Returns the transcript so far, one SessionMessage per user or assistant message, progress rows, $.ui.log lines and notices are not messages.	Type: five call forms. With no argument it returns the main conversation, with { agentId } an agent's messages, and with { as: "api" } raw API messages. At most 4096 entries.	Run time.	CoreEngineInterface line 2823, Mods Reference
✅	$.session.cwd	Returns the directory the session runs in, absolute.	Type: () => Promise<string>. A timer that outlives its hook reads the session's directory, keep the value read inside the hook if you need the hook's (a subagent's own).	Run time.	CoreEngineInterface line 2830, Mods Reference
✅	$.session.root	Returns the session's project root, absolute: where it started, or where /cd, a host's directory change or a worktree move took it.	Type: () => Promise<string>. A shell cd during the session does not move it, nested instruction files are read only beneath it.	Run time.	CoreEngineInterface line 2838, Mods Reference
✅	$.session.model	Returns the main loop's model, as /model shows it.	Type: () => Promise<string>.	Run time.	CoreEngineInterface line 2842, Mods Reference
✅	$.session.turns	Returns how many prompts the user has sent this session (user turns in the transcript).	Type: () => Promise<number>.	Run time.	CoreEngineInterface line 2847, Mods Reference
✅	$.session.id	Returns the session's id (the transcript file's name).	Type: () => Promise<string>.	Run time.	CoreEngineInterface line 2851, Mods Reference
✅	$.session.repo	Returns the git repository the session runs in, read from the working copy on each call, null when the directory is not inside one.	Type: () => Promise<SessionRepo | null>.	Run time.	CoreEngineInterface line 2859, Mods Reference
✅	$.session.surfaces	Returns every surface the session draws on, each once: terminal under the REPL first, then the remote ones in the order they attached.	Type: () => Promise<readonly RenderSurface[]>. Never rejects. Empty in a plain -p run. Example: (await $.session.surfaces()).some(s => s !== "terminal").	Run time.	CoreEngineInterface line 2871, Mods Reference
✅	$.session.surface	Returns the first of $.session.surfaces(), or null where nothing draws.	Type: () => Promise<RenderSurface | null>. Deprecated: use surfaces(), a session may draw on several surfaces at once.	Run time.	CoreEngineInterface line 2879
✅	$.session.usage	Returns when the session began, and the context window's fill, the rate-limit windows and the cost as the status line has them, itemized.	Type: (args?: SessionUsageArgs) => Promise<SessionUsage>. A plain call costs nothing. breakdown "full" uses the token-count API and "summary" estimates locally.	Run time.	CoreEngineInterface line 2901, Mods Reference
✅	$.session.version	Returns the version of the engine the session runs on, the release it is built from, and when it was built.	Type: () => Promise<SessionVersion>. Returns version, base (absent unless the version is a release), and builtAt. Works in every mode.	Run time.	CoreEngineInterface line 2918, Mods Reference
✅	$.session.compact	Compacts the conversation: the event session.compact with trigger plugin, the same call /compact makes, between turns.	Type: (input?: SessionCompactArgs) => Promise<SessionCompactResult>. Runs the hooks, then core. Resolves { skip } if a hook vetoed it. Rejects while a turn runs.	Between turns (rejects while a turn runs).	CoreEngineInterface line 2930, Mods Reference
✅	$.session.send	Sends a plain-text message to another agent or session: the event session.send, the model's SendMessage tool's own call and delivery.	Type: (input: SessionSendArgs) => Promise<SessionSendResult>. to is a name, an agent id, { sessionId }, or { agentId }. Resolves once queued. Example: await $.session.send({ to: { agentId }, text: "stop" }).	Run time.	CoreEngineInterface line 2944, Mods Reference
✅	$.session.append	Appends a row to a conversation of the session: the event session.append, the engine's own call for every row it keeps.	Type: (args: SessionAppendArgs) => Promise<SessionAppendResult>. Adds a user-role row of text blocks. Resolves { deny: reason } if a plugin above refused it.	Run time.	CoreEngineInterface line 2956, Mods Reference
✅	$.session.authorize	Holds the session's Anthropic credential on the host and answers an opaque handle and its kind, the secret never reaches the plugin.	Type: () => Promise<SessionAuthorization>. The handle works only for a first-party host. Null without a first-party login.	Run time.	CoreEngineInterface line 2968, Mods Reference
✅	$.session.identity	Returns how the session is signed in, to a mod the organization's managed settings install, { deny } to any other. No request is made.	Type: () => Promise<SessionIdentity>. Full account data only where managed forceLoginOrgUUID lists the organization. Otherwise only kind.	Mods that the organization's managed settings install (else { deny }).	CoreEngineInterface line 2980

Engine Events

Mark	Item	What it does	How it works	Where it can be used	Source
✅	session.start	Fires once per process for each loaded plugin, before the first prompt, then once per fresh load of one (never /clear), next(e) is { cwd }.	Input SessionStartInput. Result SessionStartResult. Hook result: { cwd }. The first run is awaited, so a $.tool.register in it is listed by turn one.	Hook via on('session.start', ...). Also callable as $.session.start(...).	EngineEventOf line 4445, Mods Reference
✅	session.receive	Fires when a delivery reaches the session, before it is queued: a relay's event, a peer's message, a Remote Control prompt, room events, { text }.	Input SessionReceiveInput. Result SessionReceiveResult. Hook result: { text } or { consumed }. Return { consumed: reason } to stop the message from reaching the model.	Hook via on('session.receive', ...). Also callable as $.session.receive(...).	EngineEventOf line 4457, Mods Reference
✅	session.append	Fires once per row a conversation of this session keeps (a prompt, a response block, a tool result, a notice), before it is stored.	Input SessionAppendInput. Result SessionAppendResult. Hook result: { message, uuid }. next({ ...e, message }) rewrites content before it is stored.	Hook via on('session.append', ...). Also callable as $.session.append(...).	EngineEventOf line 4469, Mods Reference
✅	session.send	Fires when a plain-text message is about to leave this conversation for another agent or session (the SendMessage tool, or $.session.send).	Input SessionSendInput. Result SessionSendResult. Hook result: { isDelivered }. Rewrite text or to with next. Return { isDelivered: false, reason } to refuse.	Hook via on('session.send', ...). Also callable as $.session.send(...).	EngineEventOf line 4481, Mods Reference
✅	session.compact	Fires when the conversation is about to be compacted (/compact, the threshold, a plugin, or ahead of time), next(e) resolves { messages }.	Input SessionCompactInput. Result SessionCompactResult. Hook result: { messages } or { skip }. { skip: reason } leaves the conversation as it is.	Hook via on('session.compact', ...). Also callable as $.session.compact(...).	EngineEventOf line 4493, Mods Reference
✅	session.attach	Fires when a remote client joins the session's roster of attached surfaces: it said so (ui_attach), or it first asked to draw.	Input SessionAttachInput. Result SessionAttachResult. Hook result: { clientId }. A hook observes a client that joins. $.session.surfaces() reads the roster.	Hook via on('session.attach', ...). Also callable as $.session.attach(...).	EngineEventOf line 4505, Mods Reference
✅	session.detach	Fires when a client leaves the roster: it detached, or the session ended with it attached (e.reason). Observe, next(e) echoes { clientId }.	Input SessionDetachInput. Result SessionDetachResult. Hook result: { clientId }. With reason end it runs inside the short bound of session.end.	Hook via on('session.detach', ...). Also callable as $.session.detach(...).	EngineEventOf line 4513, Mods Reference
✅	session.measure	Fires when the engine measures the session and a unit moved: after each main-thread turn, and when a rate-limit window moves a whole point.	Input SessionMeasureInput. Result SessionMeasureResult. Hook result: { changed }. It pushes the figures of $.session.usage(). Calls arrive one at a time.	Hook via on('session.measure', ...). Also callable as $.session.measure(...).	EngineEventOf line 4525, Mods Reference
✅	session.end	Fires once when the session ends (exit, /clear, resume, logout, signal, a -p run done), after its SessionEnd settings hooks, e.reason says which.	Input SessionEndInput. Result SessionEndResult. Hook result: { sessionId }. The whole chain shares one short time bound that next.budget reads.	Hook via on('session.end', ...). Also callable as $.session.end(...).	EngineEventOf line 4537, Mods Reference

Events Raised by $.session Calls

Mark	Item	What it does	How it works	Where it can be used	Source
✅	session.cwd	The argument of $.session.cwd().	Input: NoArgs. Value: string. A hook above the caller returns next(e), { deny: reason } or { value }.	Hook via on('session.cwd', ...). Raised by the call $.session.cwd(...).	OpEventOf line 7030, Mods Reference
✅	session.root	The argument of $.session.root().	Input: NoArgs. Value: string. A hook above the caller returns next(e), { deny: reason } or { value }.	Hook via on('session.root', ...). Raised by the call $.session.root(...).	OpEventOf line 7034, Mods Reference
✅	session.model	The argument of $.session.model().	Input: NoArgs. Value: string. A hook above the caller returns next(e), { deny: reason } or { value }.	Hook via on('session.model', ...). Raised by the call $.session.model(...).	OpEventOf line 7038, Mods Reference
✅	session.turns	The argument of $.session.turns().	Input: NoArgs. Value: number. A hook above the caller returns next(e), { deny: reason } or { value }.	Hook via on('session.turns', ...). Raised by the call $.session.turns(...).	OpEventOf line 7042, Mods Reference
✅	session.id	The argument of $.session.id().	Input: NoArgs. Value: string. A hook above the caller returns next(e), { deny: reason } or { value }.	Hook via on('session.id', ...). Raised by the call $.session.id(...).	OpEventOf line 7046, Mods Reference
✅	session.messages	The argument of $.session.messages(args): {} for the main conversation, { agentId } for one of its agents, as for the form.	Input: SessionMessagesArgs. Value: SessionMessagesValue. A hook above the caller returns next(e), { deny: reason } or { value }.	Hook via on('session.messages', ...). Raised by the call $.session.messages(...).	OpEventOf line 7051, Mods Reference
✅	session.repo	The argument of $.session.repo().	Input: NoArgs. Value: SessionRepo | null. A hook above the caller returns next(e), { deny: reason } or { value }.	Hook via on('session.repo', ...). Raised by the call $.session.repo(...).	OpEventOf line 7055, Mods Reference
✅	session.surface	The argument of $.session.surface().	Input: NoArgs. Value: RenderSurface | null. A hook above the caller returns next(e), { deny: reason } or { value }. Deprecated: with $.session.surface(), hook session.surfaces.	Hook via on('session.surface', ...). Raised by the call $.session.surface(...).	OpEventOf line 7061
✅	session.surfaces	The argument of $.session.surfaces().	Input: NoArgs. Value: readonly RenderSurface[]. A hook above the caller returns next(e), { deny: reason } or { value }.	Hook via on('session.surfaces', ...). Raised by the call $.session.surfaces(...).	OpEventOf line 7065, Mods Reference
✅	session.authorize	The argument of $.session.authorize().	Input: NoArgs. Value: SessionAuthorization. A hook above the caller returns next(e), { deny: reason } or { value }.	Hook via on('session.authorize', ...). Raised by the call $.session.authorize(...).	OpEventOf line 7069, Mods Reference
✅	session.identity	The argument of $.session.identity().	Input: NoArgs. Value: SessionIdentity. A hook above the caller returns next(e), { deny: reason } or { value }.	Hook via on('session.identity', ...). Raised by the call $.session.identity(...).	OpEventOf line 7073
✅	session.usage	The argument of $.session.usage({ breakdown, columns }).	Input: SessionUsageArgs. Value: SessionUsage. A hook above the caller returns next(e), { deny: reason } or { value }.	Hook via on('session.usage', ...). Raised by the call $.session.usage(...).	OpEventOf line 7077, Mods Reference
✅	session.version	The argument of $.session.version().	Input: NoArgs. Value: SessionVersion. A hook above the caller returns next(e), { deny: reason } or { value }.	Hook via on('session.version', ...). Raised by the call $.session.version(...).	OpEventOf line 7081, Mods Reference

See Also

• Mod API: Session Types
• Claude Code Mod API
• Use the Mods API
• Mods Reference