javi-forge 1.35.0 → 1.36.0

package/dist/lib/agent-adapter.js

@@ -0,0 +1,88 @@
+/**
+ * Agent adapter registry (agent-agnostic slice 2). One descriptor per host
+ * (`claude`, `codex`) capturing the per-agent facts the SkillGuard installer and
+ * doctor need: config paths, the protected managed set, the project-root source,
+ * the settings-schema validator (SHARED — both hosts use the identical hooks
+ * schema), the managed marker, the deny protocol, and the trust model.
+ *
+ * This descriptor is additive: Codex is routed through it, while Claude keeps its
+ * existing, byte-identical runtime path (the descriptor only DESCRIBES Claude; it
+ * does not change how the Claude command executes). The CLI dispatch decides the
+ * valid `hooks <sub> <agent>` target set through `isAgentId` (backed by the
+ * `AGENT_ADAPTERS` keys) — this registry is the single source of agent truth, and
+ * a new agent added here cannot be silently dropped: the dispatch's command-loader
+ * map is typed `Record<AgentId, …>`, so omitting a loader is a compile error.
+ */
+import path from "node:path";
+import { ASSET_NAME } from "./__fixtures__/claude-hook-ownership.js";
+import { validateSettingsShape } from "./claude-hook-settings.js";
+import { codexConfigPaths, codexTrustGrantCommand, hasCodexTrustEntry, } from "./codex-hook-manager.js";
+const CLAUDE_MANAGED_SET = [
+    ".claude/settings.json",
+    ".claude/settings.local.json",
+    ".claude/CLAUDE.md",
+    "CLAUDE.md",
+    ".javi-forge/ci.yaml",
+    ".claude/hooks/",
+    ".claude/agents/",
+    ".claude/skills/",
+];
+const CODEX_MANAGED_SET = [
+    ".codex/hooks.json",
+    ".claude/settings.json",
+    ".claude/settings.local.json",
+    ".claude/CLAUDE.md",
+    "CLAUDE.md",
+    ".javi-forge/ci.yaml",
+    ".claude/hooks/",
+    ".claude/agents/",
+    ".claude/skills/",
+];
+export const claudeAdapter = {
+    id: "claude",
+    configPaths(projectDir) {
+        return {
+            hooksFile: path.join(projectDir, ".claude", "hooks", ASSET_NAME),
+            settingsFile: path.join(projectDir, ".claude", "settings.json"),
+        };
+    },
+    managedSet: CLAUDE_MANAGED_SET,
+    projectDir: { envVar: "CLAUDE_PROJECT_DIR" },
+    settingsSchema: validateSettingsShape,
+    marker: "// javi-forge-managed: claude-pretooluse v1",
+    emitDeny: "exit2+stderr",
+    trust: null,
+};
+export const codexAdapter = {
+    id: "codex",
+    configPaths(homeDir) {
+        const paths = codexConfigPaths(homeDir);
+        return { hooksFile: paths.hooksFile, settingsFile: paths.configFile };
+    },
+    managedSet: CODEX_MANAGED_SET,
+    projectDir: { envVar: null },
+    settingsSchema: validateSettingsShape,
+    marker: "// javi-forge-managed: codex-pretooluse v1",
+    emitDeny: "exit2+stderr",
+    trust: {
+        detect(configText, hooksFile) {
+            return hasCodexTrustEntry(configText, hooksFile)
+                ? "trusted"
+                : "untrusted";
+        },
+        grantCommand: codexTrustGrantCommand,
+    },
+};
+export const AGENT_ADAPTERS = {
+    claude: claudeAdapter,
+    codex: codexAdapter,
+};
+/**
+ * Whether a raw CLI token names a known agent adapter. Backed by the
+ * `AGENT_ADAPTERS` registry so there is ONE source deciding valid targets: adding
+ * an adapter to the registry automatically widens the accepted CLI set.
+ */
+export function isAgentId(value) {
+    return typeof value === "string" && Object.hasOwn(AGENT_ADAPTERS, value);
+}
+//# sourceMappingURL=agent-adapter.js.map

package/dist/lib/claude-hook-manager.js

@@ -14,7 +14,7 @@ import os from "node:os";
 import path from "node:path";
 import { CLAUDE_HOOK_ASSETS_DIR } from "../constants.js";
 import { ASSET_MANAGED_MARKER, ASSET_NAME, } from "./__fixtures__/claude-hook-ownership.js";
-import { buildManagedContainer, classifySettingsEntry, isPlainObject, LEGACY_FILE_SHA256, MANAGED_ASSET_ARG, MANAGED_MATCHER, MANAGED_STATUS_PREFIX, planForceReplace, planLegacyCohortExcision, planManagedClaudeHookMerge, scanExecutionFlags, } from "./claude-hook-settings.js";
+import { buildManagedContainer, classifySettingsEntry, isPlainObject, LEGACY_FILE_SHA256, MANAGED_AGENT_ARG, MANAGED_ASSET_ARG, MANAGED_MATCHER, MANAGED_STATUS_PREFIX, planForceReplace, planLegacyCohortExcision, planManagedClaudeHookMerge, scanExecutionFlags, } from "./claude-hook-settings.js";
 import { safeReadFile } from "./safe-read.js";
 import { ACL_DETAIL, probeAclCapability, selectSecureFs, } from "./secure-fs-posix.js";
 import { runTransaction, } from "./secure-fs-transaction.js";
@@ -174,8 +174,9 @@ function settingsSignals(value, classification, currentAssetSha) {
     const commandShapeExact = handler.type === "command" &&
         handler.command === "node" &&
         Array.isArray(args) &&
-        args.length === 1 &&
+        args.length === 2 &&
         args[0] === MANAGED_ASSET_ARG &&
+        args[1] === MANAGED_AGENT_ARG &&
         handler.timeout === 30;
     let assetSettingsConsistent = false;
     if (typeof handler.statusMessage === "string" &&

package/dist/lib/claude-hook-settings.d.ts

@@ -8,8 +8,8 @@
  * removal/merge PLANNING only. Identity is always recomputed from observed
  * structure; a marker only claims ownership, it never proves it.
  */
-import { ASSET_SHA_PLACEHOLDER, LEGACY_FILE_SHA256, MANAGED_ASSET_ARG, MANAGED_MATCHER, MANAGED_STATUS_PREFIX } from "./__fixtures__/claude-hook-ownership.js";
-export { ASSET_SHA_PLACEHOLDER, LEGACY_FILE_SHA256, MANAGED_ASSET_ARG, MANAGED_MATCHER, MANAGED_STATUS_PREFIX, };
+import { ASSET_SHA_PLACEHOLDER, LEGACY_FILE_SHA256, MANAGED_AGENT_ARG, MANAGED_ASSET_ARG, MANAGED_MATCHER, MANAGED_STATUS_PREFIX } from "./__fixtures__/claude-hook-ownership.js";
+export { ASSET_SHA_PLACEHOLDER, LEGACY_FILE_SHA256, MANAGED_AGENT_ARG, MANAGED_ASSET_ARG, MANAGED_MATCHER, MANAGED_STATUS_PREFIX, };
 /** The nine independent component states (identical for asset and settings). */
 export type ClaudeHookComponentState = "absent" | "managed-current" | "released-outdated" | "exact-legacy" | "edited-managed" | "foreign" | "symlink" | "non-regular" | "malformed";
 /** A released settings-entry identity: version plus placeholder-normalized hash. */
@@ -149,7 +149,7 @@ export declare function planManagedClaudeHookMerge(parsed: unknown, currentAsset
 export interface ManagedHandler {
     type: "command";
     command: "node";
-    args: [string];
+    args: [string, string];
     timeout: number;
     statusMessage: string;
 }

package/dist/lib/claude-hook-settings.js

@@ -9,8 +9,8 @@
  * structure; a marker only claims ownership, it never proves it.
  */
 import { createHash } from "node:crypto";
-import { ASSET_SHA_PLACEHOLDER, LEGACY_COHORT, LEGACY_FILE_SHA256, MANAGED_ASSET_ARG, MANAGED_MATCHER, MANAGED_STATUS_PREFIX, } from "./__fixtures__/claude-hook-ownership.js";
-export { ASSET_SHA_PLACEHOLDER, LEGACY_FILE_SHA256, MANAGED_ASSET_ARG, MANAGED_MATCHER, MANAGED_STATUS_PREFIX, };
+import { ASSET_SHA_PLACEHOLDER, LEGACY_COHORT, LEGACY_FILE_SHA256, MANAGED_AGENT_ARG, MANAGED_ASSET_ARG, MANAGED_MATCHER, MANAGED_STATUS_PREFIX, } from "./__fixtures__/claude-hook-ownership.js";
+export { ASSET_SHA_PLACEHOLDER, LEGACY_FILE_SHA256, MANAGED_AGENT_ARG, MANAGED_ASSET_ARG, MANAGED_MATCHER, MANAGED_STATUS_PREFIX, };
 // Shape helpers
 export function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -443,7 +443,7 @@ export function buildManagedContainer(currentAssetSha) {
                         {
                             type: "command",
                             command: "node",
-                            args: [MANAGED_ASSET_ARG],
+                            args: [MANAGED_ASSET_ARG, MANAGED_AGENT_ARG],
                             timeout: MANAGED_TIMEOUT,
                             statusMessage: `${MANAGED_STATUS_PREFIX}${currentAssetSha}`,
                         },

package/dist/lib/codex-hook-manager.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Codex PreToolUse ownership manager (agent-agnostic slice 2). Installs the
+ * SAME shipped SkillGuard `.mjs` asset as a Codex `PreToolUse` hook by writing
+ * `~/.codex/hooks.json` + setting `[features] hooks = true` in
+ * `~/.codex/config.toml`, through the identical secure-fs transaction the Claude
+ * installer uses (no weaker path). It NEVER modifies the guard asset, the pure
+ * `evaluate*` engine, or Claude's observable behavior.
+ *
+ * TRUST (highest-risk surface — engram id 15743, codex-cli 0.147.0, verified
+ * live 2026-08-18): codex hooks are stable + default-ON, but each hook needs a
+ * `trusted_hash` recorded in `config.toml` under
+ * `[hooks.state."<abs-hook-path>:pre_tool_use:0:0"]`; an UNTRUSTED hook is
+ * SILENTLY SKIPPED unless `--dangerously-bypass-hook-trust`. There is NO
+ * `codex hooks trust` subcommand (confirmed: `codex --help` has no `hooks`
+ * command). So we DO NOT compute-and-write a trusted_hash we cannot prove
+ * reproducible (a wrong-but-present hash would leave the hook skipped while
+ * making doctor believe it is trusted — the exact fail-open theater this arc
+ * exists to kill). Instead: install writes the files + REPORTS the trust step,
+ * and the doctor DETECTS the missing trust entry and reports `blocked`
+ * (untrusted = NOT running).
+ *
+ * STALE-HASH INVALIDATION: the trust key path is STABLE across upgrades, so a
+ * rewrite of hooks.json (asset/command/timeout change) leaves the recorded
+ * `trusted_hash` stale — Codex silently skips the hook while the header
+ * persists (doctor would wrongly stay `trusted`). So whenever install/repair
+ * REWRITES the managed hooks.json, it REMOVES our `[hooks.state."<hooksFile>:*"]`
+ * table(s) in the same transactional config write (foreign rows untouched),
+ * reverting the doctor to `untrusted → blocked` until the user re-approves. An
+ * idempotent no-op install (unchanged hook content) never touches the table.
+ */
+import { type AssetManifestEntry, type ExecutionReport, type NodeOnPathProbe } from "./claude-hook-manager.js";
+import { type ClaudeHookComponentState } from "./claude-hook-settings.js";
+import { type SpawnFn } from "./secure-fs-posix.js";
+import { type PlatformSecureFs } from "./secure-fs-transaction.js";
+export type { NodeOnPathProbe };
+/** The shipped, in-package guard asset the Codex hook references by ABSOLUTE path. */
+export declare const SHIPPED_CODEX_ASSET: string;
+/** Codex manifest view — only the asset entry is needed for currency. */
+export interface Manifest {
+    asset: AssetManifestEntry;
+}
+export interface CodexConfigPaths {
+    codexDir: string;
+    hooksFile: string;
+    configFile: string;
+}
+/** Resolve `~/.codex/{hooks.json,config.toml}` for a given home directory. */
+export declare function codexConfigPaths(homeDir: string): CodexConfigPaths;
+/** The exact `command` string the managed Codex hook runs (single-string form). */
+export declare function expectedCodexCommand(assetPath: string): string;
+/** The interactive step that establishes hook trust (there is no non-interactive subcommand). */
+export declare function codexTrustGrantCommand(hooksFile: string): string;
+/** Read the `[features] hooks` flag: "true" | "false" | "absent". */
+export declare function parseFeaturesHooks(text: string): "true" | "false" | "absent";
+/**
+ * True when `config.toml` records a trust table for THIS hook path, i.e. a
+ * `[hooks.state."<hooksFile>:pre_tool_use:0:0"]` header. Fail-closed: a trust
+ * entry for a different path does not count.
+ *
+ * NOTE (fail-open the arc kills): presence of the header is NOT proof the hook
+ * is still trusted — Codex records a `trusted_hash` under it, and a hook whose
+ * content was rewritten (e.g. an asset/command/timeout upgrade) has a STALE hash
+ * → Codex silently skips it and re-prompts. We cannot recompute Codex's hash to
+ * compare here, so instead the installer INVALIDATES this table whenever it
+ * rewrites the managed hooks.json (see `removeCodexTrustEntries`), reverting the
+ * doctor to `untrusted → blocked` until the user re-approves in codex.
+ */
+export declare function hasCodexTrustEntry(text: string, hooksFile: string): boolean;
+/**
+ * Remove every `[hooks.state."<hooksFile>:*"]` table (header + body lines) keyed
+ * on OUR managed hooks.json path, preserving all other content — including
+ * FOREIGN `hooks.state` rows for other hooks files. Used to invalidate a now-
+ * stale `trusted_hash` when the managed hooks.json content is rewritten: the
+ * trust-key path is stable across upgrades, so a rewritten hook keeps its old
+ * (now wrong) recorded hash and would be silently skipped by Codex while the
+ * header persisted. Dropping the table forces the doctor back to `untrusted`
+ * until the user re-approves the hook in codex.
+ */
+export declare function removeCodexTrustEntries(text: string, hooksFile: string): string;
+/**
+ * Ensure `[features] hooks = true`, preserving all other content and idempotent
+ * when already true. Only ever INSERTS a line or flips a `hooks = false` inside
+ * `[features]`, so it can never corrupt unrelated TOML.
+ */
+export declare function mergeFeaturesHooksTrue(text: string): string;
+export interface CodexHooksClassification {
+    state: ClaudeHookComponentState;
+    detail?: string;
+}
+/**
+ * Classify `hooks.json`. Reuses `validateSettingsShape` (the SAME settings-schema
+ * validator the Claude classifier uses — the Codex hooks.json schema is
+ * identical) and recognizes our managed handler by its exact command string.
+ *   - malformed        → not a valid hooks container
+ *   - managed-current  → our exact command present
+ *   - released-outdated→ our guard present but at a stale asset path
+ *   - foreign          → other PreToolUse handlers, none of them ours
+ *   - absent           → no PreToolUse handlers at all (installable)
+ */
+export declare function classifyCodexHooksJson(value: unknown, expectedCommand: string): CodexHooksClassification;
+export type CodexTrustState = "trusted" | "untrusted";
+export interface CodexHookDoctorReport {
+    healthy: boolean;
+    hooksJson: {
+        state: ClaudeHookComponentState;
+        detail?: string;
+    };
+    config: {
+        featuresHooks: "true" | "false" | "absent";
+        readable: boolean;
+    };
+    asset: {
+        state: ClaudeHookComponentState;
+        sha256?: string;
+    };
+    node: {
+        available: boolean;
+        version?: string;
+        satisfiesMinimum: boolean;
+    };
+    nodeOnPath: NodeOnPathProbe;
+    execution: ExecutionReport;
+    trust: {
+        state: CodexTrustState;
+        grantCommand: string;
+    };
+    remediation: string[];
+}
+export interface CodexDoctorOptions {
+    manifest?: Manifest;
+    assetPath?: string;
+    nodeVersion?: string;
+    nodeProbe?: () => Promise<NodeOnPathProbe>;
+}
+export declare function doctorCodexPreToolUse(homeDir?: string, options?: CodexDoctorOptions): Promise<CodexHookDoctorReport>;
+export interface CodexHookMutationResult {
+    ok: boolean;
+    changed: string[];
+    backups: string[];
+    report: CodexHookDoctorReport;
+    errors: string[];
+    warnings: string[];
+}
+export interface CodexHookRunDeps {
+    secureFs?: PlatformSecureFs | null;
+    clock?: () => Date;
+    nonce?: () => string;
+    manifest?: Manifest;
+    platform?: NodeJS.Platform;
+    assetPath?: string;
+    nodeProbe?: () => Promise<NodeOnPathProbe>;
+    nodeSpawn?: SpawnFn;
+}
+export declare function _runCodex(homeDir: string, _mode: "install" | "repair", _options: {
+    force?: boolean;
+}, deps: CodexHookRunDeps): Promise<CodexHookMutationResult>;
+export declare function installCodexPreToolUse(homeDir?: string): Promise<CodexHookMutationResult>;
+export declare function repairCodexPreToolUse(homeDir?: string, options?: {
+    force?: boolean;
+}): Promise<CodexHookMutationResult>;
+//# sourceMappingURL=codex-hook-manager.d.ts.map