@event4u/agent-config 8.12.0 → 8.13.0

package/src/scripts/_lib/claude_plugin.ts

@@ -27,6 +27,22 @@ export const CLAUDE_PLUGIN_INSTALL_HINT: readonly string[] = [
     `claude plugin install ${CLAUDE_PLUGIN_ID}@${CLAUDE_MARKETPLACE_NAME}`,
 ];
 
+/**
+ * Official OpenAI codex plugin for Claude Code (team mode's Claude-Code
+ * transport). Marketplace name verified against the upstream repo's
+ * `.claude-plugin/marketplace.json` (`name: "openai-codex"`, plugin
+ * `name: "codex"`) at HEAD 2026-07-12.
+ */
+export const CODEX_PLUGIN_ID = 'codex';
+export const CODEX_MARKETPLACE_NAME = 'openai-codex';
+export const CODEX_MARKETPLACE_REPO = 'openai/codex-plugin-cc';
+
+/** The one-time install commands surfaced when the codex plugin is missing. */
+export const CODEX_PLUGIN_INSTALL_HINT: readonly string[] = [
+    `claude plugin marketplace add ${CODEX_MARKETPLACE_REPO}`,
+    `claude plugin install ${CODEX_PLUGIN_ID}@${CODEX_MARKETPLACE_NAME}`,
+];
+
 /** Claude Code config dir — `CLAUDE_CONFIG_DIR` env override, else `~/.claude`. */
 export function claude_config_dir(): string {
     const env = (process.env['CLAUDE_CONFIG_DIR'] ?? '').trim();
@@ -34,11 +50,11 @@ export function claude_config_dir(): string {
 }
 
 /**
- * True when the agent-config plugin is recorded in Claude Code's
+ * True when a plugin with the given id is recorded in Claude Code's
  * `plugins/installed_plugins.json` (any marketplace — matched by the
- * `agent-config@` id prefix). Unreadable / absent file → false.
+ * `<id>@` key prefix). Unreadable / absent file → false. Read-only.
  */
-export function claude_plugin_installed(): boolean {
+function _plugin_id_recorded(plugin_id: string): boolean {
     const p = path.join(claude_config_dir(), 'plugins', 'installed_plugins.json');
     let data: unknown;
     try {
@@ -50,10 +66,29 @@ export function claude_plugin_installed(): boolean {
     const plugins = (data as { plugins?: unknown }).plugins;
     if (plugins === null || plugins === undefined || typeof plugins !== 'object') return false;
     return Object.keys(plugins as Record<string, unknown>).some((k) =>
-        k.startsWith(`${CLAUDE_PLUGIN_ID}@`),
+        k.startsWith(`${plugin_id}@`),
     );
 }
 
+/**
+ * True when the agent-config plugin is recorded in Claude Code's
+ * `plugins/installed_plugins.json` (any marketplace — matched by the
+ * `agent-config@` id prefix). Unreadable / absent file → false.
+ */
+export function claude_plugin_installed(): boolean {
+    return _plugin_id_recorded(CLAUDE_PLUGIN_ID);
+}
+
+/**
+ * True when the official OpenAI codex plugin is recorded in Claude Code's
+ * `plugins/installed_plugins.json` (any marketplace — matched by the
+ * `codex@` id prefix). Unreadable / absent file → false. Read-only:
+ * detection never writes under `~/.claude/`.
+ */
+export function codex_plugin_installed(): boolean {
+    return _plugin_id_recorded(CODEX_PLUGIN_ID);
+}
+
 /**
  * Version recorded in the installed marketplace snapshot's
  * `.claude-plugin/marketplace.json` (`metadata.version` — bumped per

package/src/scripts/ai_team/config.ts

@@ -0,0 +1,162 @@
+/**
+ * ai_team configuration loader — single source of truth for the `/team`
+ * cross-model review family.
+ *
+ * Mirrors the fail-closed validation posture of the council loader
+ * (`src/scripts/ai_council/config.ts`) at a fraction of its surface: the
+ * `ai_team` block has five flat keys and no nested sub-schemas, so this
+ * loader is deliberately lean — defaults, per-key type checks, and hard
+ * unknown-key rejection. Contract: `docs/contracts/ai-team-config.md`.
+ *
+ * Unlike the council (ALWAYS user-global `.ai-council.yml`, ADR-104),
+ * `ai_team` lives in the PROJECT settings cascade (`.agent-settings.yml`
+ * via `load_agent_settings`) — team mode is a per-project posture
+ * (default-off), not a per-developer credential store; the codex CLI
+ * carries the subscription auth itself.
+ *
+ * Validation contract (all enforced at load time, fail-closed):
+ *
+ * 1. `ai_team` absent → defaults (feature off). Non-mapping → error.
+ * 2. Unknown keys under `ai_team` are rejected — a typo must never
+ *    silently disable a gate (`allow_delegate` misspelled = delegation
+ *    stays off AND the load fails loudly).
+ * 3. `enabled`, `allow_delegate`, `suppress_setup_hint` are booleans.
+ * 4. `model` is a non-empty string. `'auto'` = pass no `--model` flag
+ *    (the codex CLI default applies); any other value passes through
+ *    verbatim.
+ * 5. `max_calls_per_day` is a non-negative integer (bools rejected).
+ */
+import { load_agent_settings, type SettingsDict } from '../_lib/agent_settings.js';
+
+/** Raised when the `ai_team` block of `.agent-settings.yml` violates the schema. */
+export class TeamConfigError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'TeamConfigError';
+    }
+}
+
+export interface AiTeamConfig {
+    readonly enabled: boolean;
+    readonly model: string;
+    readonly allow_delegate: boolean;
+    readonly max_calls_per_day: number;
+    readonly suppress_setup_hint: boolean;
+}
+
+/** Shipped defaults — byte-parity with `src/config/agent-settings.template.yml`. */
+export const AI_TEAM_DEFAULTS: AiTeamConfig = Object.freeze({
+    enabled: false,
+    model: 'auto',
+    allow_delegate: false,
+    max_calls_per_day: 50,
+    suppress_setup_hint: false,
+});
+
+/**
+ * Sentinel: `model: 'auto'` means "pass NO --model flag" so the codex
+ * CLI's own default applies (tracks the subscription's strongest model
+ * instead of pinning a stale ID).
+ */
+export const AI_TEAM_MODEL_AUTO = 'auto';
+
+const _KNOWN_KEYS: ReadonlySet<string> = new Set([
+    'enabled',
+    'model',
+    'allow_delegate',
+    'max_calls_per_day',
+    'suppress_setup_hint',
+]);
+
+function _isDict(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function _isBool(value: unknown): value is boolean {
+    return typeof value === 'boolean';
+}
+
+function _requireBool(raw: Record<string, unknown>, key: string, fallback: boolean): boolean {
+    if (!(key in raw)) {
+        return fallback;
+    }
+    const value = raw[key];
+    if (!_isBool(value)) {
+        throw new TeamConfigError(
+            `\`ai_team.${key}\` must be a boolean (got ${JSON.stringify(value)}).`,
+        );
+    }
+    return value;
+}
+
+/**
+ * Validate a raw `ai_team` mapping and return the typed config.
+ *
+ * `raw = null | undefined` (block absent) returns the defaults — the
+ * feature is off, never an error. Every other shape is validated
+ * fail-closed per the module contract above.
+ */
+export function build_ai_team_config(raw: unknown): AiTeamConfig {
+    if (raw === null || raw === undefined) {
+        return AI_TEAM_DEFAULTS;
+    }
+    if (!_isDict(raw)) {
+        throw new TeamConfigError('`ai_team` must be a mapping.');
+    }
+
+    for (const key of Object.keys(raw)) {
+        if (!_KNOWN_KEYS.has(key)) {
+            throw new TeamConfigError(
+                `ai_team.${key}: unknown key; valid: ` +
+                    `[${[..._KNOWN_KEYS].map((k) => `'${k}'`).join(', ')}].`,
+            );
+        }
+    }
+
+    const enabled = _requireBool(raw, 'enabled', AI_TEAM_DEFAULTS.enabled);
+    const allow_delegate = _requireBool(raw, 'allow_delegate', AI_TEAM_DEFAULTS.allow_delegate);
+    const suppress_setup_hint = _requireBool(
+        raw,
+        'suppress_setup_hint',
+        AI_TEAM_DEFAULTS.suppress_setup_hint,
+    );
+
+    let model = AI_TEAM_DEFAULTS.model;
+    if ('model' in raw) {
+        const value = raw['model'];
+        if (typeof value !== 'string' || value.trim() === '') {
+            throw new TeamConfigError(
+                `\`ai_team.model\` must be a non-empty string (got ${JSON.stringify(value)}).`,
+            );
+        }
+        model = value;
+    }
+
+    let max_calls_per_day = AI_TEAM_DEFAULTS.max_calls_per_day;
+    if ('max_calls_per_day' in raw) {
+        const value = raw['max_calls_per_day'];
+        if (_isBool(value) || typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+            throw new TeamConfigError(
+                '`ai_team.max_calls_per_day` must be a non-negative integer ' +
+                    `(got ${JSON.stringify(value)}).`,
+            );
+        }
+        max_calls_per_day = value;
+    }
+
+    return { enabled, model, allow_delegate, max_calls_per_day, suppress_setup_hint };
+}
+
+/**
+ * Load the `ai_team` config from the merged project settings cascade.
+ *
+ * `opts.settings` injects a pre-merged settings dict (test seam — no
+ * filesystem access); otherwise `load_agent_settings` walks the normal
+ * `.agent-settings.yml` cascade from `opts.cwd` (default: process cwd).
+ */
+export function load_ai_team_config(
+    opts: { settings?: SettingsDict | null; cwd?: string | null } = {},
+): AiTeamConfig {
+    const settings = opts.settings ?? load_agent_settings({ cwd: opts.cwd ?? process.cwd() });
+    return build_ai_team_config((settings as Record<string, unknown>)['ai_team']);
+}

package/src/scripts/install.ts

@@ -4453,6 +4453,36 @@ function _read_consumer_auto_switch(project_root: string): string {
     return 'suggest';
 }
 
+/**
+ * Team-mode setup hint (road-to-team-mode Phase 1 Step 2) — a one-line
+ * recommendation printed after a claude-code install/init pointing at the
+ * doctor `team` section. Returns null when suppressed via
+ * `ai_team.suppress_setup_hint: true` in `.agent-settings.yml` (default
+ * false; the `ai_team` block may not exist in the schema yet — read
+ * leniently). Pointer only: never auto-installs, never modifies
+ * `~/.claude/plugins`.
+ */
+function _team_setup_hint_line(project_root: string): string | null {
+    let data: Record<string, unknown>;
+    try {
+        data = load_agent_settings({ project_path: _resolve_settings_read(project_root) });
+    } catch {
+        data = {};
+    }
+    const ai_team = _isPlainObject(data) ? data['ai_team'] : null;
+    const flag = _isPlainObject(ai_team)
+        ? (ai_team as Record<string, unknown>)['suppress_setup_hint']
+        : null;
+    const suppressed =
+        flag === true ||
+        (typeof flag === 'string' && ['true', 'yes', 'on', '1'].includes(flag.trim().toLowerCase()));
+    if (suppressed) return null;
+    return (
+        '  • Claude Code team mode (optional cross-model review via the official ' +
+        'codex plugin): run `agent-config doctor --check team` for setup status.'
+    );
+}
+
 function finalize_claude_model_tiers(project_root: string): number {
     const claude_skills = path.join(project_root, '.claude', 'skills');
     const augment_skills = path.join(project_root, '.augment', 'skills');
@@ -4644,6 +4674,13 @@ function _main_project_install(
             );
             process.stdout.write('\n');
         }
+        if (_is_tool_enabled(tools, 'claude-code')) {
+            const team_hint = _team_setup_hint_line(project_root);
+            if (team_hint !== null) {
+                process.stdout.write(team_hint + '\n');
+                process.stdout.write('\n');
+            }
+        }
     }
 
     _propose_modules_config(project_root, is_first_run);
@@ -4730,6 +4767,8 @@ export {
     // ADR-200 py2ts: re-exported for test_consumer_model_tier.ts twin
     // (Python test imports `install.finalize_claude_model_tiers` directly).
     finalize_claude_model_tiers,
+    // road-to-team-mode Phase 1 Step 2: exported for the wizard-hint tests.
+    _team_setup_hint_line,
     SUPPORTED_PROFILES,
     DEFAULT_PROFILE,
     _VALID_TOOLS,

package/src/server/schemas/settings.ts

@@ -288,6 +288,23 @@ export const settingsSchema = z.object({
             'When the agent considers a parallel `git worktree` for risky / large work. ask (default) = surface a numbered option and wait. on = spawn worktrees autonomously. off = never use worktrees, edit in place.',
         ),
     }),
+    ai_team: z.object({
+        enabled: z.boolean().default(false).describe(
+            'Master switch for the /team cross-model review family (docs/contracts/ai-team-config.md). false (default) = commands are never suggested and every invocation refuses with an enable pointer. true = the family is live; individual gates (allow_delegate) still apply.',
+        ),
+        model: z.string().default('auto').describe(
+            "Model handed to the codex CLI. 'auto' (default) = pass no --model flag so the CLI's own default applies — tracks the subscription's current strongest model instead of pinning a stale ID. Any other value passes through verbatim as `--model <value>`.",
+        ),
+        allow_delegate: z.boolean().default(false).describe(
+            'Second opt-in for the only wrapper that delegates write access (/team:delegate). false (default) = delegate refuses even when ai_team.enabled is true. Both keys must be true before delegation is reachable.',
+        ),
+        max_calls_per_day: z.number().int().min(0).default(50).describe(
+            'Per-day cap on team calls, read against the EXISTING cli_call_budget openai bucket (~/.event4u/agent-config/cli-calls.json, daily UTC reset) — one subscription, one counter, never a parallel count. 0 = block all team calls.',
+        ),
+        suppress_setup_hint: z.boolean().default(false).describe(
+            'Suppress the one-line wizard/init recommendation to set up the codex plugin on Claude-Code hosts. Cosmetic only — never changes behavior.',
+        ),
+    }).default({ enabled: false, model: 'auto', allow_delegate: false, max_calls_per_day: 50, suppress_setup_hint: false }),
     onboarding: z.object({
         onboarded: z.boolean().default(false).describe(
             'Set to true once the developer has completed `agent-config setup`. The onboarding-gate rule blocks the first turn of every chat until this is true. Toggle back to false to re-trigger the wizard.',