@agentex/agent 0.0.36 → 0.0.38

package/dist/utils/instructions.d.ts

@@ -14,15 +14,20 @@ export interface InstallInstructionsOptions {
     cwd?: string;
     /**
      * Also write each runtime's native file when it differs from the shared
-     * standard (currently only Gemini's GEMINI.md). Only affects "workspace";
-     * "global" always uses native files. Default: false.
+     * AGENTS.md: Claude's CLAUDE.md (as a one-line `@AGENTS.md` pointer) and
+     * Gemini's GEMINI.md (as a copy). Only affects "workspace"; "global" always
+     * uses native files. Default: false.
+     *
+     * Opt in for Claude Code before 2.1.277, or on Bedrock, Vertex or Foundry,
+     * where Claude doesn't read AGENTS.md on its own.
      */
     includeNativeFiles?: boolean;
     /**
      * Wrap `content` in managed markers and merge into any existing file,
      * replacing only the previously-managed region and preserving everything the
      * user wrote outside it. Default: true. When false, the file is overwritten
-     * with raw `content` (escape hatch for fully-owned files).
+     * with raw `content` (escape hatch for fully-owned files), and an existing
+     * CLAUDE.md is left alone even though it hides AGENTS.md from Claude Code.
      */
     managed?: boolean;
     /** Marker tag, so the comment reads `<!-- <tag>:managed:start -->`. Default: "agentex". */
@@ -33,7 +38,11 @@ export interface InstallInstructionsOptions {
      */
     homeDir?: string;
 }
-export type InstructionStatus = "created" | "updated" | "skipped" | "error";
+/**
+ * "removed": a workspace CLAUDE.md that held nothing but this installer's
+ * managed region, deleted because the opt-in (`includeNativeFiles`) is off.
+ */
+export type InstructionStatus = "created" | "updated" | "skipped" | "removed" | "error";
 export interface InstructionInstallEntry {
     /** The filename written, e.g. "AGENTS.md", "CLAUDE.md", "GEMINI.md". */
     filename: string;
@@ -41,6 +50,8 @@ export interface InstructionInstallEntry {
     targetPath: string;
     /** Which requested runtimes this file serves. */
     runtimes: SkillRuntime[];
+    /** Set when the file is a pointer: its managed region is `@<importsFile>`, not the brief. */
+    importsFile?: string;
     status: InstructionStatus;
     error?: string;
 }
@@ -49,12 +60,15 @@ export interface InstructionInstallResult {
     installed: number;
     updated: number;
     skipped: number;
+    removed: number;
     errors: number;
 }
 export interface InstructionTarget {
     filename: string;
     targetPath: string;
     runtimes: SkillRuntime[];
+    /** Set when the file is a pointer: its managed region is `@<importsFile>`, not the brief. */
+    importsFile?: string;
 }
 export interface RemoveInstructionsOptions {
     runtimes?: SkillRuntime[];
@@ -85,7 +99,8 @@ export interface ManagedBlockOptions {
  * without touching disk.
  *
  * - "workspace": files dedupe by name under {cwd}/ (the default writes
- *   CLAUDE.md + AGENTS.md once each). `includeNativeFiles` adds GEMINI.md.
+ *   AGENTS.md once). `includeNativeFiles` adds CLAUDE.md (a pointer, marked by
+ *   `importsFile`) and GEMINI.md.
  * - "global": one file per runtime in each runtime's home dir. Runtimes without
  *   a file-based global config (Cursor) are omitted.
  */
@@ -99,18 +114,25 @@ export declare function resolveInstructionTargets(options?: {
 /**
  * Install an instruction brief into the right per-runtime files.
  *
- * By default merges `content` into a managed region of `{cwd}/CLAUDE.md` and
- * `{cwd}/AGENTS.md`, preserving any user-authored content outside the markers.
- * Idempotent: a re-install with unchanged content reports every entry as
- * "skipped".
+ * By default merges `content` into a managed region of `{cwd}/AGENTS.md`,
+ * preserving any user-authored content outside the markers. Idempotent: a
+ * re-install with unchanged content reports every entry as "skipped".
+ *
+ * When Claude is among the runtimes, a `{cwd}/CLAUDE.md` already on disk is
+ * reconciled, because it would hide AGENTS.md from Claude Code: one holding
+ * nothing but this installer's managed region is removed, and one the user
+ * wrote gets `@AGENTS.md` in its managed region. With `includeNativeFiles`,
+ * CLAUDE.md is written as that pointer either way. `managed: false` leaves an
+ * existing CLAUDE.md alone.
  *
  * @example
  * ```ts
  * // Workspace (repo-root) install — the common case.
  * await installInstructions(brief, { location: "workspace", cwd: projectDir });
- * // → {cwd}/CLAUDE.md + {cwd}/AGENTS.md
+ * // → {cwd}/AGENTS.md
  *
- * // Also drop Gemini's native GEMINI.md (it doesn't read AGENTS.md by default).
+ * // Also write the native files: CLAUDE.md as an `@AGENTS.md` pointer (for
+ * // Claude Code before 2.1.277, or on Bedrock/Vertex/Foundry) and GEMINI.md.
  * await installInstructions(brief, { location: "workspace", cwd, includeNativeFiles: true });
  *
  * // Global install — per-runtime home files.
@@ -123,7 +145,9 @@ export declare function installInstructions(content: string, options?: InstallIn
  * Remove the managed region installed by {@link installInstructions}, preserving
  * any user-authored content outside the markers. If the file contains nothing
  * but the managed block, it is deleted. User-owned files (no managed region) are
- * left untouched and reported as "skipped".
+ * left untouched and reported as "skipped". Native files (CLAUDE.md, GEMINI.md)
+ * are always checked, whether or not they were installed with
+ * `includeNativeFiles`.
  */
 export declare function removeInstructions(options?: RemoveInstructionsOptions): Promise<InstructionRemoveResult>;
 /**

package/dist/utils/instructions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../../src/utils/instructions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../../src/utils/instructions.ts"],"names":[],"mappings":"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"}

package/dist/utils/instructions.js

@@ -22,12 +22,12 @@ export async function resolveInstructions(filePath) {
     }
 }
 const RUNTIME_INSTRUCTIONS = {
-    claude: { projectFile: "CLAUDE.md", nativeFile: "CLAUDE.md", hasGlobalFile: true },
-    codex: { projectFile: "AGENTS.md", nativeFile: "AGENTS.md", hasGlobalFile: true },
-    opencode: { projectFile: "AGENTS.md", nativeFile: "AGENTS.md", hasGlobalFile: true },
-    gemini: { projectFile: "AGENTS.md", nativeFile: "GEMINI.md", hasGlobalFile: true },
-    cursor: { projectFile: "AGENTS.md", nativeFile: "AGENTS.md", hasGlobalFile: false },
-    pi: { projectFile: "AGENTS.md", nativeFile: "AGENTS.md", hasGlobalFile: true },
+    claude: { projectFile: "AGENTS.md", nativeFile: "CLAUDE.md", nativeFileMode: "pointer", hasGlobalFile: true },
+    codex: { projectFile: "AGENTS.md", nativeFile: "AGENTS.md", nativeFileMode: "copy", hasGlobalFile: true },
+    opencode: { projectFile: "AGENTS.md", nativeFile: "AGENTS.md", nativeFileMode: "copy", hasGlobalFile: true },
+    gemini: { projectFile: "AGENTS.md", nativeFile: "GEMINI.md", nativeFileMode: "copy", hasGlobalFile: true },
+    cursor: { projectFile: "AGENTS.md", nativeFile: "AGENTS.md", nativeFileMode: "copy", hasGlobalFile: false },
+    pi: { projectFile: "AGENTS.md", nativeFile: "AGENTS.md", nativeFileMode: "copy", hasGlobalFile: true },
 };
 const ALL_RUNTIMES = ["claude", "codex", "gemini", "cursor", "opencode", "pi"];
 const DEFAULT_MANAGED_TAG = "agentex";
@@ -39,7 +39,8 @@ const DEFAULT_MANAGED_TAG = "agentex";
  * without touching disk.
  *
  * - "workspace": files dedupe by name under {cwd}/ (the default writes
- *   CLAUDE.md + AGENTS.md once each). `includeNativeFiles` adds GEMINI.md.
+ *   AGENTS.md once). `includeNativeFiles` adds CLAUDE.md (a pointer, marked by
+ *   `importsFile`) and GEMINI.md.
  * - "global": one file per runtime in each runtime's home dir. Runtimes without
  *   a file-based global config (Cursor) are omitted.
  */
@@ -51,23 +52,24 @@ export function resolveInstructionTargets(options) {
         if (!cwd)
             throw new Error("cwd is required when location is 'workspace'");
         const byFile = new Map();
-        const add = (filename, runtime) => {
-            const list = byFile.get(filename) ?? [];
-            list.push(runtime);
-            byFile.set(filename, list);
+        const add = (filename, runtime, importsFile) => {
+            const target = byFile.get(filename) ?? {
+                filename,
+                targetPath: path.join(cwd, filename),
+                runtimes: [],
+                ...(importsFile !== undefined && { importsFile }),
+            };
+            target.runtimes.push(runtime);
+            byFile.set(filename, target);
         };
         for (const runtime of runtimes) {
             const spec = RUNTIME_INSTRUCTIONS[runtime];
             add(spec.projectFile, runtime);
             if (options?.includeNativeFiles && spec.nativeFile !== spec.projectFile) {
-                add(spec.nativeFile, runtime);
+                add(spec.nativeFile, runtime, spec.nativeFileMode === "pointer" ? spec.projectFile : undefined);
             }
         }
-        return [...byFile.entries()].map(([filename, rts]) => ({
-            filename,
-            targetPath: path.join(cwd, filename),
-            runtimes: dedupeRuntimes(rts),
-        }));
+        return [...byFile.values()].map((target) => ({ ...target, runtimes: dedupeRuntimes(target.runtimes) }));
     }
     // global: each runtime reads its own native file in its own home dir.
     const targets = [];
@@ -93,18 +95,25 @@ function dedupeRuntimes(runtimes) {
 /**
  * Install an instruction brief into the right per-runtime files.
  *
- * By default merges `content` into a managed region of `{cwd}/CLAUDE.md` and
- * `{cwd}/AGENTS.md`, preserving any user-authored content outside the markers.
- * Idempotent: a re-install with unchanged content reports every entry as
- * "skipped".
+ * By default merges `content` into a managed region of `{cwd}/AGENTS.md`,
+ * preserving any user-authored content outside the markers. Idempotent: a
+ * re-install with unchanged content reports every entry as "skipped".
+ *
+ * When Claude is among the runtimes, a `{cwd}/CLAUDE.md` already on disk is
+ * reconciled, because it would hide AGENTS.md from Claude Code: one holding
+ * nothing but this installer's managed region is removed, and one the user
+ * wrote gets `@AGENTS.md` in its managed region. With `includeNativeFiles`,
+ * CLAUDE.md is written as that pointer either way. `managed: false` leaves an
+ * existing CLAUDE.md alone.
  *
  * @example
  * ```ts
  * // Workspace (repo-root) install — the common case.
  * await installInstructions(brief, { location: "workspace", cwd: projectDir });
- * // → {cwd}/CLAUDE.md + {cwd}/AGENTS.md
+ * // → {cwd}/AGENTS.md
  *
- * // Also drop Gemini's native GEMINI.md (it doesn't read AGENTS.md by default).
+ * // Also write the native files: CLAUDE.md as an `@AGENTS.md` pointer (for
+ * // Claude Code before 2.1.277, or on Bedrock/Vertex/Foundry) and GEMINI.md.
  * await installInstructions(brief, { location: "workspace", cwd, includeNativeFiles: true });
  *
  * // Global install — per-runtime home files.
@@ -115,36 +124,16 @@ function dedupeRuntimes(runtimes) {
 export async function installInstructions(content, options) {
     const managed = options?.managed ?? true;
     const tag = options?.managedTag ?? DEFAULT_MANAGED_TAG;
-    const targets = resolveInstructionTargets(options);
     const entries = [];
-    for (const target of targets) {
-        try {
-            const existing = await readFileOrNull(target.targetPath);
-            const next = managed
-                ? upsertManagedBlock(existing, content, { tag })
-                : ensureTrailingNewline(content);
-            let status;
-            if (existing === null) {
-                status = "created";
-            }
-            else if (existing === next) {
-                status = "skipped";
-            }
-            else {
-                status = "updated";
-            }
-            if (status !== "skipped") {
-                await fs.mkdir(path.dirname(target.targetPath), { recursive: true });
-                await fs.writeFile(target.targetPath, next, { mode: 0o644 });
-            }
-            entries.push({ ...target, status });
-        }
-        catch (err) {
-            entries.push({
-                ...target,
-                status: "error",
-                error: err instanceof Error ? err.message : String(err),
-            });
+    for (const target of resolveInstructionTargets(options)) {
+        const body = target.importsFile !== undefined ? `@${target.importsFile}` : content;
+        entries.push(await writeTarget(target, body, managed, tag));
+    }
+    if (managed) {
+        for (const target of unrequestedPointerTargets(options)) {
+            const entry = await reconcilePointer(target, tag);
+            if (entry)
+                entries.push(entry);
         }
     }
     return {
@@ -152,14 +141,75 @@ export async function installInstructions(content, options) {
         installed: entries.filter((e) => e.status === "created").length,
         updated: entries.filter((e) => e.status === "updated").length,
         skipped: entries.filter((e) => e.status === "skipped").length,
+        removed: entries.filter((e) => e.status === "removed").length,
         errors: entries.filter((e) => e.status === "error").length,
     };
 }
+async function writeTarget(target, body, managed, tag) {
+    try {
+        const existing = await readFileOrNull(target.targetPath);
+        const next = managed ? upsertManagedBlock(existing, body, { tag }) : ensureTrailingNewline(body);
+        let status;
+        if (existing === null) {
+            status = "created";
+        }
+        else if (existing === next) {
+            status = "skipped";
+        }
+        else {
+            status = "updated";
+        }
+        if (status !== "skipped") {
+            await fs.mkdir(path.dirname(target.targetPath), { recursive: true });
+            await fs.writeFile(target.targetPath, next, { mode: 0o644 });
+        }
+        return { ...target, status };
+    }
+    catch (err) {
+        return { ...target, status: "error", error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * Pointer files (a workspace CLAUDE.md) for the requested runtimes that the
+ * install doesn't write because the opt-in is off, but that still need
+ * reconciling if they exist.
+ */
+function unrequestedPointerTargets(options) {
+    if ((options?.location ?? "workspace") !== "workspace" || options?.includeNativeFiles)
+        return [];
+    return resolveInstructionTargets({ ...options, includeNativeFiles: true }).filter((target) => target.importsFile !== undefined);
+}
+/**
+ * An existing pointer file with the opt-in off: delete it when nothing but our
+ * managed region is in it, otherwise keep the user's content and make sure it
+ * imports the project file. Returns null when there is no file.
+ */
+async function reconcilePointer(target, tag) {
+    try {
+        const existing = await readFileOrNull(target.targetPath);
+        if (existing === null)
+            return null;
+        if (stripManagedBlock(existing, { tag }) === null) {
+            await fs.rm(target.targetPath, { force: true });
+            return { ...target, status: "removed" };
+        }
+        const next = upsertManagedBlock(existing, `@${target.importsFile}`, { tag });
+        if (next === existing)
+            return { ...target, status: "skipped" };
+        await fs.writeFile(target.targetPath, next);
+        return { ...target, status: "updated" };
+    }
+    catch (err) {
+        return { ...target, status: "error", error: err instanceof Error ? err.message : String(err) };
+    }
+}
 /**
  * Remove the managed region installed by {@link installInstructions}, preserving
  * any user-authored content outside the markers. If the file contains nothing
  * but the managed block, it is deleted. User-owned files (no managed region) are
- * left untouched and reported as "skipped".
+ * left untouched and reported as "skipped". Native files (CLAUDE.md, GEMINI.md)
+ * are always checked, whether or not they were installed with
+ * `includeNativeFiles`.
  */
 export async function removeInstructions(options) {
     const tag = options?.managedTag ?? DEFAULT_MANAGED_TAG;
@@ -167,6 +217,7 @@ export async function removeInstructions(options) {
         runtimes: options?.runtimes,
         location: options?.location,
         cwd: options?.cwd,
+        includeNativeFiles: true,
         homeDir: options?.homeDir,
     });
     const entries = [];

package/dist/utils/instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../src/utils/instructions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../src/utils/instructions.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentex/agent",
-  "version": "0.0.36",
+  "version": "0.0.38",
   "description": "Programmatic execution of AI coding agents including Claude Code, Codex, Cursor, and OpenCode",
   "repository": {
     "type": "git",

package/src/index.ts

@@ -172,6 +172,8 @@ export type {
   BackgroundTaskType,
   BackgroundTaskPhase,
   BackgroundTaskStatus,
+  BackgroundTaskReport,
+  TurnTrigger,
   BinaryStatus,
   ProviderModel,
   ListModelsOptions,

package/src/providers/claude/parse.ts

@@ -827,7 +827,7 @@ function normalizedClaudeTaskStatus(
   }
 }
 
-function backgroundTaskEventFromClaude(
+export function backgroundTaskEventFromClaude(
   raw: Record<string, unknown>,
 ): Extract<StreamEvent, { type: "background_task" }> | null {
   if (asString(raw["type"], "") !== "system") return null;
@@ -861,6 +861,28 @@ function backgroundTaskEventFromClaude(
     description: task.description,
     summary: task.summary,
     parentTaskId: null,
+    // Only `task_started` and `task_notification` carry the launching call;
+    // `task_updated` is a bare state patch keyed by task id alone.
+    toolUseId: task.toolUseId,
+    // The delivery, not the state change. Claude emits `task_updated` and
+    // `task_notification` for one completion — same task, same instant,
+    // different records. Only the notification hands back the result, so only
+    // it gets a report, and a host can render exactly one row per completion
+    // without guessing which of two identical-looking events to keep.
+    //
+    // Gated on the task having actually delivered an outcome. Claude emits
+    // notifications for a task that is still running (a mid-flight ping is not
+    // a result), and a `stopped` task was cut short by a host `stopTask` or a
+    // kill — there is nothing to hand back, no resume turn follows it, and
+    // treating it as a delivery left a stale id that mis-attributed the next
+    // self-started turn. `completed` and `failed` both delivered an outcome.
+    report: task.phase === "notification" && terminal && status !== "stopped"
+      ? {
+          summary: task.summary,
+          outputFile: task.outputFile,
+          usage: task.usage,
+        }
+      : null,
     ...baseFieldsFromEvent(raw, null),
   };
 }