Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

6.6 KB
Raw Blame
// ─── Host pid and the parent conversation ────────────────────────────────────
//
// Two facts a session or team record carries so an observer outside this
// process — the magus `claudish` plugin monitor — can tell which Claude Code
// window started a run:
//
//   * `hostPid`: the Claude Code process that launched this MCP server. A
//     structural fact, read once at startup from the process tree we were given
//     (our parent, or our launcher's parent). Never searched for.
//   * `parentClaudeSessionId`: the Claude Code CONVERSATION live in that window
//     when the tool call ran. Read once per call from the host's session record
//     `<configDir>/sessions/<hostPid>.json`, which Claude Code rewrites on every
//     session switch (`/clear`, `/resume`). Only when no record can be read does
//     it fall back to `CLAUDE_CODE_SESSION_ID`, the id the server was started
//     with, which goes stale on the first `/clear`.
//
// Why not prove it from the transcript: Claude Code (measured on 2.1.290)
// appends the call's `tool_use` record only AFTER the MCP tool call returns, so
// no search made while the tool runs can find the call it is attributing.
//
// Accepted race: a `/clear` typed in the very moment a call runs may attribute
// that run to the new conversation. It is always a conversation of the same
// window — the record is keyed by this server's own host pid.

import { readFile } from "node:fs/promises";
import { join } from "node:path";

import { userHomeFrom } from "./home-dir.js";

/** What a Claude Code session id may look like. Also the path-safety gate. */
export const CLAUDE_ID_RE = /^[A-Za-z0-9_-]{8,128}$/;

// ─── hostPid ─────────────────────────────────────────────────────────────────

export interface HostPids {
  /** The Claude Code process that launched this MCP server. */
  hostPid: number;
  /**
   * The npm `node` launcher (`bin/claudish.cjs`) between Claude Code and this
   * process, when there is one. Present exactly when `hostPid` came from the
   * launcher branch, so every record says which branch produced it.
   */
  launcherPid?: number;
}

function positiveInt(value: string | undefined): number | undefined {
  if (value === undefined || !/^[1-9][0-9]*$/.test(value)) return undefined;
  const n = Number(value);
  return Number.isSafeInteger(n) ? n : undefined;
}

/**
 * The host pid, from the environment and our own parent pid. Pure.
 *
 * - npm / bun global install: Claude Code → `node` launcher → `bun` (us). The
 *   launcher sets `CLAUDISH_LAUNCHER_PID` (itself) and `CLAUDISH_LAUNCHER_PPID`
 *   (its parent). When `CLAUDISH_LAUNCHER_PID` is OUR parent, the host is the
 *   launcher's parent.
 * - compiled binary, or `bun src/index.ts`: our parent is the host.
 *
 * The pair check makes a leaked pair inert: a nested claudish that inherits an
 * outer launcher's variables sees `CLAUDISH_LAUNCHER_PID` ≠ its own parent and
 * ignores them. No `ps`, no walk.
 */
export function hostPidFrom(env: Record<string, string | undefined>, ppid: number): HostPids {
  const launcherPpid = positiveInt(env.CLAUDISH_LAUNCHER_PPID);
  if (
    env.CLAUDISH_LAUNCHER_PID === String(ppid) &&
    launcherPpid !== undefined &&
    launcherPpid !== ppid
  ) {
    return { hostPid: launcherPpid, launcherPid: ppid };
  }
  return { hostPid: ppid };
}

// ─── parentClaudeSessionId ───────────────────────────────────────────────────

/**
 * The conversation id this server was started with, when it is usable at all.
 *
 * `CLAUDE_CODE_SESSION_ID` when it is well formed and `CLAUDE_CODE_CHILD_SESSION`
 * is empty. Claude Code sets the latter for Bash-tool children and monitors and
 * strips it from the stdio MCP servers it launches, so its presence means this
 * server was not started by Claude Code directly. The fallback only: it is
 * current until the first `/clear` and stale after it.
 */
export function parentSessionIdFrom(env: Record<string, string | undefined>): string | undefined {
  const id = env.CLAUDE_CODE_SESSION_ID;
  if (id === undefined || !CLAUDE_ID_RE.test(id)) return undefined;
  if (env.CLAUDE_CODE_CHILD_SESSION) return undefined;
  return id;
}

/**
 * `CLAUDE_CONFIG_DIR`, else `<home>/.claude`, with `<home>` resolved by the
 * same `$HOME`-first rule as the sessions directory (home-dir.ts): Claude Code
 * follows `$HOME`, and Bun's `os.homedir()` does not.
 */
export function claudeConfigDir(env: Record<string, string | undefined>): string {
  const fromEnv = env.CLAUDE_CONFIG_DIR;
  return fromEnv && fromEnv.length > 0 ? fromEnv : join(userHomeFrom(env), ".claude");
}

/** The host's live session record, as far as claudish trusts it. */
export interface HostSessionRecord {
  sessionId: string;
}

/**
 * `<configDir>/sessions/<hostPid>.json`, the record Claude Code writes at
 * startup and rewrites on every session switch, so its `sessionId` is the
 * window's live conversation (`/clear` moves it to the new id, `/resume` back).
 * Used only when it parses, its `pid === hostPid`, and its `sessionId` is well
 * formed; anything else is `undefined`. Never throws.
 */
export async function readHostSessionRecord(opts: {
  configDir: string;
  hostPid: number;
}): Promise<HostSessionRecord | undefined> {
  try {
    const raw = await readFile(join(opts.configDir, "sessions", `${opts.hostPid}.json`), "utf-8");
    const parsed: unknown = JSON.parse(raw);
    if (!parsed || typeof parsed !== "object") return undefined;
    const rec = parsed as { pid?: unknown; sessionId?: unknown };
    if (rec.pid !== opts.hostPid) return undefined;
    if (typeof rec.sessionId !== "string" || !CLAUDE_ID_RE.test(rec.sessionId)) return undefined;
    return { sessionId: rec.sessionId };
  } catch {
    return undefined;
  }
}

/**
 * The `parentClaudeSessionId` for one `create_session` or `team(mode:"run")`
 * call, read once at call time: the host session record's `sessionId`, else
 * the environment's id, else `undefined` (the field is then omitted). One file
 * read, no search, no wait. Never throws.
 */
export async function parentSessionForCall(opts: {
  hostPid: number;
  env?: Record<string, string | undefined>;
}): Promise<string | undefined> {
  const env = opts.env ?? process.env;
  const record = await readHostSessionRecord({
    configDir: claudeConfigDir(env),
    hostPid: opts.hostPid,
  });
  return record?.sessionId ?? parentSessionIdFrom(env);
}