Official

codex

Codex agent provider: runs the Codex CLI's app-server for each account.

The app opens the listing; nothing installs until an agent in your Plugins workspace has read the files and you enable the plugin. In a terminal: dvg install divergence/codex@0.2.4

Permissions in 0.2.4

  • Provide agents agents.provideMediumAdds agents to the app.Provide the Codex agent and pass its tool calls to plugin tools
  • Run named programs processMediumStarts the listed programs.Run the Codex CLI, and ask or tell the installer that owns it (npm or Homebrew) about a newer versionPrograms: codexnpmbrew
  • Environment variables envMediumReads the listed environment variables.Find each account's Codex home, and pass extra app-server arguments set in CODEX_ARGSVariables: HOMECODEX_HOMECODEX_ARGS
  • Read files fs.readMediumReads files in the listed places.Notice a conversation started in the Codex app or CLI, so it shows up at once, and read, once, the accounts the previous Codex provider keptPlaces: its own data folder~/.codex/sessions~/.codex/sessions/**~/.codex*/sessions~/.codex*/sessions/**

Files

requests.ts6.7 KB
// What the app-server's requests become (approval cards and questions),
// and the replies Codex expects for the user's answers. Pure functions of
// the request and the answer; the agent keeps the pending requests.
import type { ApprovalOption } from "divergence/protocol";
import type { Notification } from "./wire.ts";
import type { QuestionAnswer, QuestionField, QuestionOption, ToolContent } from "./types.ts";
import * as map from "./map.ts";

/// File changes and ordinary commands share these four base decisions.
export const APPROVAL_OPTIONS: ApprovalOption[] = [
  { id: "accept", name: "Allow once", kind: "allow_once" },
  { id: "acceptForSession", name: "Allow for this session", kind: "allow_always" },
  { id: "decline", name: "Reject", kind: "reject_once" },
  { id: "cancel", name: "Reject and stop", kind: "reject_always" },
];

/// A command approval's headline and the tool call its card shows.
export function commandApproval(p: Notification & { itemId: string }) {
  const command = p.command ?? "";
  const cwd = p.cwd ?? null;
  const network = p.networkApprovalContext;
  const operation = p.kind === "writeStdin" ? "Send input to a terminal" : p.kind === "humanCommand" ? "Approve a command personally" : "Run a command";
  const title = p.reason ?? (network ? `Allow ${network.protocol} access to ${network.host}` : operation);
  const content: ToolContent[] = command ? [{ type: "terminal", command, output: "", ...(cwd ? { cwd } : {}) }] : [];
  if (network) content.push({ type: "text", text: `Network destination: ${network.protocol}://${network.host}` });
  const call = map.toolCall({
    id: p.itemId,
    name: p.kind === "writeStdin" ? "write_stdin" : "shell",
    kind: map.commandToolKind(p.commandActions),
    title: command || operation,
    status: "pending",
    input: { command, cwd, kind: p.kind ?? "command", networkApprovalContext: network ?? null },
    content,
  });
  return { title, call };
}

/// Only amendments supplied by Codex become persistent approval choices.
export function commandDecisions(p: Notification) {
  const human = p.kind === "humanCommand";
  const options = APPROVAL_OPTIONS.filter((option) => !human || option.id !== "acceptForSession");
  const decisions = new Map<string, unknown>(options.map((option) => [option.id, option.id]));
  if (!human && p.proposedExecpolicyAmendment) {
    const id = "acceptWithExecpolicyAmendment";
    options.splice(2, 0, { id, name: `Always allow ${p.proposedExecpolicyAmendment.join(" ")}`, kind: "allow_always" });
    decisions.set(id, { acceptWithExecpolicyAmendment: { execpolicy_amendment: p.proposedExecpolicyAmendment } });
  }
  if (!human) for (const [index, amendment] of (p.proposedNetworkPolicyAmendments ?? []).entries()) {
    const id = `network:${index}`;
    options.push({ id, name: `${amendment.action === "allow" ? "Always allow" : "Always deny"} ${amendment.host}`, kind: amendment.action === "allow" ? "allow_always" : "reject_always" });
    decisions.set(id, { applyNetworkPolicyAmendment: { network_policy_amendment: amendment } });
  }
  return { options, decisions };
}

/// A file change approval's headline and the tool call its card shows,
/// with the diffs the item streamed so far.
export function fileChangeApproval(p: Notification & { itemId: string }, content: ToolContent[]) {
  const title =
    typeof p.reason === "string"
      ? p.reason
      : typeof p.grantRoot === "string"
        ? `Allow writes under ${p.grantRoot}`
        : "Apply file changes";
  return { title, call: map.toolCall({ id: p.itemId, name: "apply_patch", kind: "edit", title, status: "pending", content }) };
}

/// An MCP elicitation's refusal.
export const REFUSE = { action: "cancel", content: null, _meta: null };

/// An MCP tool approval's options: the persistence scopes the request
/// advertises become choices.
export function mcpApprovalOptions(persist: string | string[] | null | undefined) {
  const supports = (scope: string) => (Array.isArray(persist) ? persist.includes(scope) : persist === scope);
  const options: ApprovalOption[] = [{ id: "accept", name: "Allow once", kind: "allow_once" }];
  if (supports("session")) options.push({ id: "acceptForSession", name: "Allow for this session", kind: "allow_always" });
  if (supports("always")) options.push({ id: "acceptAlways", name: "Always allow", kind: "allow_always" });
  options.push({ id: "cancel", name: "Cancel", kind: "reject_always" });
  return options;
}

/// The reply to an MCP tool approval. The scope goes back in the
/// response metadata, never in the form content.
export function mcpApprovalReply(decision: string) {
  if (decision === "accept") return { action: "accept", content: {}, _meta: null };
  if (decision === "acceptForSession") return { action: "accept", content: {}, _meta: { persist: "session" } };
  if (decision === "acceptAlways") return { action: "accept", content: {}, _meta: { persist: "always" } };
  if (decision === "decline") return { action: "decline", content: null, _meta: null };
  return REFUSE;
}

type Questions = NonNullable<Notification["questions"]>;

/// `item/tool/requestUserInput`'s questions as one field each: a select
/// when it carries options, text otherwise.
export function userInputFields(questions: Questions) {
  return questions.map((question) => {
    const header = typeof question?.header === "string" ? question.header : "";
    const text = typeof question?.question === "string" ? question.question : "";
    const options = (Array.isArray(question?.options) ? question.options : []).map((option) => {
      const out: QuestionOption = { value: String(option?.label ?? ""), label: String(option?.label ?? "") };
      if (typeof option?.description === "string" && option.description) out.description = option.description;
      return out;
    });
    const field: QuestionField = {
      id: String(question?.id ?? ""),
      label: header || text,
      kind: options.length ? "select" : "text",
      allowOther: question?.isOther === true,
      required: true,
    };
    if (question.isSecret === true) field.secret = true;
    if (text) field.description = text;
    if (options.length) field.options = options;
    return field;
  });
}

/// The user's answer as Codex expects it: `{ answers: { <questionId>: { answers: [...] } } }`.
export function userInputReply(questions: Questions, answer: QuestionAnswer) {
  const values = answer.values ?? {};
  const answers: Record<string, { answers: string[] }> = {};
  for (const question of questions) {
    const id = String(question?.id ?? "");
    const value = values[id];
    let list: string[] = [];
    if (typeof value === "string") list = [value];
    else if (Array.isArray(value)) list = value.filter((item) => typeof item === "string");
    else if (typeof value === "boolean") list = [String(value)];
    answers[id] = { answers: list };
  }
  return { answers };
}

Versions

VersionPublishedPlugin APISizePermissionsStatus
0.2.5latestNov 21, 2026>=5 <6121.1 KB4 permissionsListed
0.2.4Nov 16, 2026>=5 <6120.2 KB4 permissionsListed
0.2.3Nov 11, 2026>=5 <695.2 KB4 permissionsListed
0.2.2Nov 9, 2026>=5 <688.9 KB4 permissionsListed
0.2.1Oct 27, 2026>=2 <484.1 KB4 permissionsListed

Reviews and comments

0 threads · 0 reviews

No comments yet.