@tangle-network/agent-interface 0.43.1 → 0.44.0

package/README.md

@@ -48,6 +48,12 @@ The older `checkpoint()` and `fork()` methods remain source-compatible for provi
 All new wire values have exported Zod schemas on the package root.
 Omitting `interactions` and `nativeContinuation`, or leaving the three durable branching flags false, is the compatible declaration for existing providers.
 
+`profile.systemPrompt` declares two independent bits rather than one flag.
+`replace` means the provider deletes the harness's own system prompt and installs `prompt.systemPrompt`; `append` means it keeps that prompt and adds `prompt.appendSystemPrompt` to it.
+A provider that can only append must declare `replace: false` and refuse a profile carrying `systemPrompt`, because quietly appending a requested replacement leaves the instructions the caller asked to delete in force.
+
+
+
 ## Install
 
 ```bash
@@ -77,7 +83,8 @@ const provider: AgentEnvironmentProvider = {
   capabilities: () => ({
     profile: {
       namedProfiles: false,
-      systemPrompt: true,
+      // Most harnesses can only add to their built-in prompt, not delete it.
+      systemPrompt: { replace: false, append: true },
       instructions: true,
       tools: true,
       permissions: true,

package/dist/agent-candidate-execution-plan-schema.d.ts

@@ -96,6 +96,10 @@ export declare const agentCandidateProfilePlanMaterialSchema: z.ZodObject<{
         kind: z.ZodLiteral<"public">;
         value: z.ZodString;
     }, z.core.$strict>>;
+    appendSystemPrompt: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodLiteral<"public">;
+        value: z.ZodString;
+    }, z.core.$strict>>;
     unsupported: z.ZodArray<z.ZodObject<{
         dimension: z.ZodString;
         reason: z.ZodString;
@@ -545,6 +549,10 @@ export declare const agentCandidateProfilePlanEvidenceSchema: z.ZodObject<{
             kind: "public";
             value: string;
         } | undefined;
+        appendSystemPrompt?: {
+            kind: "public";
+            value: string;
+        } | undefined;
     }, unknown, z.core.$ZodTypeInternals<{
         sourceProfileDigest: `sha256:${string}`;
         harness: "claude-code" | "nanoclaw" | "codex" | "opencode" | "kimi-code" | "pi" | "gemini" | "hermes" | "openclaw" | "amp" | "factory-droids" | "forge" | "cursor" | "acp" | "cli-base";
@@ -569,6 +577,10 @@ export declare const agentCandidateProfilePlanEvidenceSchema: z.ZodObject<{
             kind: "public";
             value: string;
         } | undefined;
+        appendSystemPrompt?: {
+            kind: "public";
+            value: string;
+        } | undefined;
     }, unknown>>;
     artifact: z.ZodUnion<readonly [z.ZodObject<{
         locator: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -618,6 +630,10 @@ export declare const agentCandidateProfileActivationSchema: z.ZodObject<{
                 kind: "public";
                 value: string;
             } | undefined;
+            appendSystemPrompt?: {
+                kind: "public";
+                value: string;
+            } | undefined;
         };
         artifact: {
             locator: {
@@ -665,6 +681,10 @@ export declare const agentCandidateProfileActivationSchema: z.ZodObject<{
                 kind: "public";
                 value: string;
             } | undefined;
+            appendSystemPrompt?: {
+                kind: "public";
+                value: string;
+            } | undefined;
         };
         artifact: {
             locator: {

package/dist/agent-candidate-execution-plan-schema.js

@@ -117,6 +117,7 @@ export const agentCandidateProfilePlanMaterialSchema = z
     env: environmentConfigSchema,
     flags: z.array(agentCandidateConfigValueSchema),
     systemPrompt: agentCandidateConfigValueSchema.optional(),
+    appendSystemPrompt: agentCandidateConfigValueSchema.optional(),
     unsupported: z
         .array(z
         .object({

package/dist/agent-candidate-profile-schema.d.ts

@@ -22,6 +22,7 @@ export declare const agentCandidateProfileSchema: z.ZodObject<{
     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
     prompt: z.ZodOptional<z.ZodObject<{
         systemPrompt: z.ZodOptional<z.ZodString>;
+        appendSystemPrompt: z.ZodOptional<z.ZodString>;
         instructions: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
     model: z.ZodOptional<z.ZodObject<{

package/dist/agent-candidate-promotion-schema.d.ts

@@ -13,6 +13,7 @@ export declare const agentCandidateExperimentSchema: z.ZodObject<{
             tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
             prompt: z.ZodOptional<z.ZodObject<{
                 systemPrompt: z.ZodOptional<z.ZodString>;
+                appendSystemPrompt: z.ZodOptional<z.ZodString>;
                 instructions: z.ZodOptional<z.ZodArray<z.ZodString>>;
             }, z.core.$strict>>;
             model: z.ZodOptional<z.ZodObject<{
@@ -840,6 +841,7 @@ export declare const agentCandidateExperimentSchema: z.ZodObject<{
             tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
             prompt: z.ZodOptional<z.ZodObject<{
                 systemPrompt: z.ZodOptional<z.ZodString>;
+                appendSystemPrompt: z.ZodOptional<z.ZodString>;
                 instructions: z.ZodOptional<z.ZodArray<z.ZodString>>;
             }, z.core.$strict>>;
             model: z.ZodOptional<z.ZodObject<{
@@ -2079,6 +2081,10 @@ export declare const candidateExecutionEvidenceSchema: z.ZodObject<{
                         kind: "public";
                         value: string;
                     } | undefined;
+                    appendSystemPrompt?: {
+                        kind: "public";
+                        value: string;
+                    } | undefined;
                 };
                 artifact: {
                     locator: {
@@ -2126,6 +2132,10 @@ export declare const candidateExecutionEvidenceSchema: z.ZodObject<{
                         kind: "public";
                         value: string;
                     } | undefined;
+                    appendSystemPrompt?: {
+                        kind: "public";
+                        value: string;
+                    } | undefined;
                 };
                 artifact: {
                     locator: {
@@ -3571,6 +3581,7 @@ export declare const agentImprovementMeasuredComparisonSchema: z.ZodObject<{
                 tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 prompt: z.ZodOptional<z.ZodObject<{
                     systemPrompt: z.ZodOptional<z.ZodString>;
+                    appendSystemPrompt: z.ZodOptional<z.ZodString>;
                     instructions: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 }, z.core.$strict>>;
                 model: z.ZodOptional<z.ZodObject<{
@@ -4398,6 +4409,7 @@ export declare const agentImprovementMeasuredComparisonSchema: z.ZodObject<{
                 tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 prompt: z.ZodOptional<z.ZodObject<{
                     systemPrompt: z.ZodOptional<z.ZodString>;
+                    appendSystemPrompt: z.ZodOptional<z.ZodString>;
                     instructions: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 }, z.core.$strict>>;
                 model: z.ZodOptional<z.ZodObject<{
@@ -5638,6 +5650,10 @@ export declare const agentImprovementMeasuredComparisonSchema: z.ZodObject<{
                                 kind: "public";
                                 value: string;
                             } | undefined;
+                            appendSystemPrompt?: {
+                                kind: "public";
+                                value: string;
+                            } | undefined;
                         };
                         artifact: {
                             locator: {
@@ -5685,6 +5701,10 @@ export declare const agentImprovementMeasuredComparisonSchema: z.ZodObject<{
                                 kind: "public";
                                 value: string;
                             } | undefined;
+                            appendSystemPrompt?: {
+                                kind: "public";
+                                value: string;
+                            } | undefined;
                         };
                         artifact: {
                             locator: {
@@ -7018,6 +7038,10 @@ export declare const agentImprovementMeasuredComparisonSchema: z.ZodObject<{
                                 kind: "public";
                                 value: string;
                             } | undefined;
+                            appendSystemPrompt?: {
+                                kind: "public";
+                                value: string;
+                            } | undefined;
                         };
                         artifact: {
                             locator: {
@@ -7065,6 +7089,10 @@ export declare const agentImprovementMeasuredComparisonSchema: z.ZodObject<{
                                 kind: "public";
                                 value: string;
                             } | undefined;
+                            appendSystemPrompt?: {
+                                kind: "public";
+                                value: string;
+                            } | undefined;
                         };
                         artifact: {
                             locator: {
@@ -8540,6 +8568,7 @@ export declare const agentImprovementProposalSchema: z.ZodObject<{
                     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     prompt: z.ZodOptional<z.ZodObject<{
                         systemPrompt: z.ZodOptional<z.ZodString>;
+                        appendSystemPrompt: z.ZodOptional<z.ZodString>;
                         instructions: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     }, z.core.$strict>>;
                     model: z.ZodOptional<z.ZodObject<{
@@ -9367,6 +9396,7 @@ export declare const agentImprovementProposalSchema: z.ZodObject<{
                     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     prompt: z.ZodOptional<z.ZodObject<{
                         systemPrompt: z.ZodOptional<z.ZodString>;
+                        appendSystemPrompt: z.ZodOptional<z.ZodString>;
                         instructions: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     }, z.core.$strict>>;
                     model: z.ZodOptional<z.ZodObject<{
@@ -10607,6 +10637,10 @@ export declare const agentImprovementProposalSchema: z.ZodObject<{
                                     kind: "public";
                                     value: string;
                                 } | undefined;
+                                appendSystemPrompt?: {
+                                    kind: "public";
+                                    value: string;
+                                } | undefined;
                             };
                             artifact: {
                                 locator: {
@@ -10654,6 +10688,10 @@ export declare const agentImprovementProposalSchema: z.ZodObject<{
                                     kind: "public";
                                     value: string;
                                 } | undefined;
+                                appendSystemPrompt?: {
+                                    kind: "public";
+                                    value: string;
+                                } | undefined;
                             };
                             artifact: {
                                 locator: {
@@ -11987,6 +12025,10 @@ export declare const agentImprovementProposalSchema: z.ZodObject<{
                                     kind: "public";
                                     value: string;
                                 } | undefined;
+                                appendSystemPrompt?: {
+                                    kind: "public";
+                                    value: string;
+                                } | undefined;
                             };
                             artifact: {
                                 locator: {
@@ -12034,6 +12076,10 @@ export declare const agentImprovementProposalSchema: z.ZodObject<{
                                     kind: "public";
                                     value: string;
                                 } | undefined;
+                                appendSystemPrompt?: {
+                                    kind: "public";
+                                    value: string;
+                                } | undefined;
                             };
                             artifact: {
                                 locator: {

package/dist/agent-candidate-receipt-schema.d.ts

@@ -218,6 +218,10 @@ export declare const agentCandidateMaterializationReceiptSchema: z.ZodObject<{
                     kind: "public";
                     value: string;
                 } | undefined;
+                appendSystemPrompt?: {
+                    kind: "public";
+                    value: string;
+                } | undefined;
             };
             artifact: {
                 locator: {
@@ -265,6 +269,10 @@ export declare const agentCandidateMaterializationReceiptSchema: z.ZodObject<{
                     kind: "public";
                     value: string;
                 } | undefined;
+                appendSystemPrompt?: {
+                    kind: "public";
+                    value: string;
+                } | undefined;
             };
             artifact: {
                 locator: {

package/dist/agent-candidate-schema.d.ts

@@ -17,6 +17,7 @@ export declare const agentCandidateBundleSchema: z.ZodObject<{
         tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
         prompt: z.ZodOptional<z.ZodObject<{
             systemPrompt: z.ZodOptional<z.ZodString>;
+            appendSystemPrompt: z.ZodOptional<z.ZodString>;
             instructions: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strict>>;
         model: z.ZodOptional<z.ZodObject<{

package/dist/agent-candidate.d.ts

@@ -344,8 +344,19 @@ export interface AgentCandidateProfilePlanMaterial {
     }>;
     env: Record<string, AgentCandidateConfigValue>;
     flags: AgentCandidateConfigValue[];
-    /** Exact system-prompt replacement supplied to the harness, when supported. */
+    /**
+     * Exact system-prompt REPLACEMENT supplied to the harness, when supported.
+     * Present only where the harness's own system prompt is deleted in favor of
+     * this text.
+     */
     systemPrompt?: AgentCandidateConfigValue;
+    /**
+     * Exact text ADDED to the harness's own system prompt, which stays intact.
+     * Recorded separately from the replacement so plan identity distinguishes the
+     * two intents; a harness that lowers this into a flag or file still records
+     * it here, because the same bytes in the two fields are two different runs.
+     */
+    appendSystemPrompt?: AgentCandidateConfigValue;
     unsupported: Array<{
         dimension: string;
         reason: string;

package/dist/agent-execution-preparation.d.ts

@@ -164,10 +164,11 @@ export declare const agentExecutionPreparationAxisResultSchema: z.ZodObject<{
         harness: "harness";
         confidential: "confidential";
         extensions: "extensions";
+        systemPrompt: "systemPrompt";
+        appendSystemPrompt: "appendSystemPrompt";
+        instructions: "instructions";
         skills: "skills";
         commands: "commands";
-        instructions: "instructions";
-        systemPrompt: "systemPrompt";
         modelDefault: "modelDefault";
         modelSmall: "modelSmall";
         modelProvider: "modelProvider";
@@ -310,10 +311,11 @@ export declare const agentExecutionPreparationReceiptSchema: z.ZodObject<{
             harness: "harness";
             confidential: "confidential";
             extensions: "extensions";
+            systemPrompt: "systemPrompt";
+            appendSystemPrompt: "appendSystemPrompt";
+            instructions: "instructions";
             skills: "skills";
             commands: "commands";
-            instructions: "instructions";
-            systemPrompt: "systemPrompt";
             modelDefault: "modelDefault";
             modelSmall: "modelSmall";
             modelProvider: "modelProvider";

package/dist/agent-profile-materialization.d.ts

@@ -1,12 +1,15 @@
 import type { AgentProfile } from "./agent-profile.js";
 /**
- * The 29 canonical AgentProfile leaves that can affect one execution.
+ * The 30 canonical AgentProfile leaves that can affect one execution.
  *
  * Compound parents such as `model`, `prompt`, and `resources` are deliberately
  * absent. A producer must report the exact requested leaf instead of claiming
- * a parent while silently dropping one of its children.
+ * a parent while silently dropping one of its children. `systemPrompt` and
+ * `appendSystemPrompt` are separate leaves for the same reason: a backend that
+ * can only add text must report the requested replacement as unsatisfied rather
+ * than acknowledge it.
  */
-export declare const AGENT_PROFILE_MATERIALIZATION_AXES: readonly ["name", "description", "version", "tags", "systemPrompt", "instructions", "modelDefault", "modelSmall", "modelProvider", "modelReasoningEffort", "modelMetadata", "harness", "permissions", "tools", "mcp", "connections", "subagents", "files", "resourceTools", "skills", "resourceAgents", "commands", "resourceInstructions", "resourceFailOnError", "hooks", "modes", "confidential", "metadata", "extensions"];
+export declare const AGENT_PROFILE_MATERIALIZATION_AXES: readonly ["name", "description", "version", "tags", "systemPrompt", "appendSystemPrompt", "instructions", "modelDefault", "modelSmall", "modelProvider", "modelReasoningEffort", "modelMetadata", "harness", "permissions", "tools", "mcp", "connections", "subagents", "files", "resourceTools", "skills", "resourceAgents", "commands", "resourceInstructions", "resourceFailOnError", "hooks", "modes", "confidential", "metadata", "extensions"];
 /** One exact leaf of the public AgentProfile contract. */
 export type AgentProfileMaterializationAxis = (typeof AGENT_PROFILE_MATERIALIZATION_AXES)[number];
 /** Compatibility name used by runtimes that distinguish canonical axes. */

package/dist/agent-profile-materialization.js

@@ -1,9 +1,12 @@
 /**
- * The 29 canonical AgentProfile leaves that can affect one execution.
+ * The 30 canonical AgentProfile leaves that can affect one execution.
  *
  * Compound parents such as `model`, `prompt`, and `resources` are deliberately
  * absent. A producer must report the exact requested leaf instead of claiming
- * a parent while silently dropping one of its children.
+ * a parent while silently dropping one of its children. `systemPrompt` and
+ * `appendSystemPrompt` are separate leaves for the same reason: a backend that
+ * can only add text must report the requested replacement as unsatisfied rather
+ * than acknowledge it.
  */
 export const AGENT_PROFILE_MATERIALIZATION_AXES = [
     "name",
@@ -11,6 +14,7 @@ export const AGENT_PROFILE_MATERIALIZATION_AXES = [
     "version",
     "tags",
     "systemPrompt",
+    "appendSystemPrompt",
     "instructions",
     "modelDefault",
     "modelSmall",
@@ -68,6 +72,11 @@ const AXIS_DESCRIPTORS = [
         rootPath: "/prompt/systemPrompt",
         value: (profile) => profile.prompt?.systemPrompt,
     },
+    {
+        axis: "appendSystemPrompt",
+        rootPath: "/prompt/appendSystemPrompt",
+        value: (profile) => profile.prompt?.appendSystemPrompt,
+    },
     {
         axis: "instructions",
         rootPath: "/prompt/instructions",

package/dist/agent-profile.d.ts

@@ -131,14 +131,58 @@ export interface AgentProfileModelHints {
 }
 /**
  * Prompt shaping for an agent.
+ *
+ * Replacement and addition are two different intents against the same channel
+ * and are never interchangeable. A backend that can only do one of them must
+ * refuse the other rather than substituting it, which is why
+ * {@link AgentProfileCapabilities.systemPrompt} carries a separate bit for each.
+ *
+ * Setting `systemPrompt` and `appendSystemPrompt` together is legal and ordered:
+ * the replacement is installed first and the addition composes on top of it, so
+ * the effective prompt is `systemPrompt` then `appendSystemPrompt`. The pair is
+ * deliberately allowed because {@link mergeAgentProfiles} composes the two
+ * fields independently — refusing it would let two individually valid profiles
+ * merge into an invalid one.
  */
 export interface AgentProfilePrompt {
     /**
-     * Full system prompt replacement, when supported.
+     * REPLACE the harness's own system prompt with this text.
+     *
+     * The harness's built-in prompt is DELETED, not extended: the model stops
+     * receiving the tool descriptions, output conventions, refusal rules, and
+     * workflow scaffolding it was tuned against, so behavior can move far beyond
+     * the words written here. Supply a prompt that stands on its own.
+     *
+     * Honored only where {@link AgentProfileSystemPromptCapability.replace} is
+     * true — a harness that exposes a real replacement control (`pi
+     * --system-prompt <file>` with context files, skills, and prompt templates
+     * off; gemini `.gemini/system.md` with `GEMINI_SYSTEM_MD=1`). A backend that
+     * can only add text must reject this field. Folding it into an addition is a
+     * silent semantic downgrade: the instructions the caller asked to delete stay
+     * in force, and nothing in the result says so.
      */
     systemPrompt?: string;
     /**
-     * Additional instruction lines appended to the active prompt.
+     * ADD this text to the harness's own system prompt, which stays intact.
+     *
+     * The model keeps everything it was tuned against and receives this on top,
+     * in the same privileged position as the system prompt. Maps to claude-code
+     * `--append-system-prompt`, and to a leading `role: "system"` message on
+     * harnesses that take a message list.
+     *
+     * Distinct from {@link AgentProfilePrompt.instructions}, which harnesses
+     * materialize into their lower-privilege project-instruction surface.
+     *
+     * Honored only where {@link AgentProfileSystemPromptCapability.append} is
+     * true.
+     */
+    appendSystemPrompt?: string;
+    /**
+     * Additional instruction lines composed into the agent's project-instruction
+     * surface — the harness's `AGENTS.md` / `CLAUDE.md`-style files or its own
+     * caller-instruction preamble. Lower privilege than
+     * {@link AgentProfilePrompt.appendSystemPrompt} and placed wherever the
+     * harness keeps caller instructions rather than in the system prompt.
      */
     instructions?: string[];
 }
@@ -326,12 +370,36 @@ export interface AgentProfile {
  * Helper for declaring typed profiles in application code.
  */
 export declare function defineAgentProfile<T extends AgentProfile>(profile: T): T;
+/**
+ * What a backend can do to the harness's system prompt.
+ *
+ * Two independent bits, because most harnesses can do exactly one of them. A
+ * single boolean cannot separate "I delete the built-in prompt and install
+ * yours" from "I keep the built-in prompt and add yours to it", so a caller
+ * reading it has no way to tell whether a requested replacement will actually
+ * happen. Neither bit implies the other: declare each from what the backend's
+ * materialization really does, not from whether it accepts the field.
+ */
+export interface AgentProfileSystemPromptCapability {
+    /**
+     * The backend honors {@link AgentProfilePrompt.systemPrompt} by deleting the
+     * harness's own system prompt and installing the caller's. `false` means a
+     * profile carrying `systemPrompt` must be REFUSED — never quietly added to
+     * the built-in prompt instead.
+     */
+    replace: boolean;
+    /**
+     * The backend honors {@link AgentProfilePrompt.appendSystemPrompt} by keeping
+     * the harness's own system prompt and adding the caller's text to it.
+     */
+    append: boolean;
+}
 /**
  * Capabilities describing how a backend interprets AgentProfile.
  */
 export interface AgentProfileCapabilities {
     namedProfiles: boolean;
-    systemPrompt: boolean;
+    systemPrompt: AgentProfileSystemPromptCapability;
     instructions: boolean;
     tools: boolean;
     permissions: boolean;
@@ -374,7 +442,9 @@ export interface AgentProfileValidationResult {
 /**
  * Merge two public AgentProfile values.
  *
- * Overlay fields win on conflicts. Array-like instruction sets are appended.
+ * Overlay fields win on conflicts. Additive fields compose instead: array-like
+ * instruction sets are concatenated, and `prompt.appendSystemPrompt` values are
+ * joined base-first with a blank line between them.
  */
 export declare function mergeAgentProfiles(base: AgentProfile | undefined, overlay: AgentProfile | undefined): AgentProfile | undefined;
 export {};

package/dist/agent-profile.js

@@ -72,6 +72,19 @@ function mergeStringArrays(base, overlay) {
         return undefined;
     return [...(base ?? []), ...(overlay ?? [])];
 }
+/**
+ * Additive prompt text composes instead of overwriting: an overlay that adds
+ * one line must not delete what the base added. `systemPrompt` keeps
+ * overlay-wins semantics because two replacements cannot both apply, while two
+ * additions always can. An explicitly empty addition contributes no separator.
+ */
+function mergeAppendedSystemPrompts(base, overlay) {
+    if (base === undefined || base === "")
+        return overlay ?? base;
+    if (overlay === undefined || overlay === "")
+        return base;
+    return `${base}\n\n${overlay}`;
+}
 function mergeRecord(base, overlay) {
     if (!base && !overlay)
         return undefined;
@@ -88,7 +101,9 @@ function mergeOptionalArrays(base, overlay) {
 /**
  * Merge two public AgentProfile values.
  *
- * Overlay fields win on conflicts. Array-like instruction sets are appended.
+ * Overlay fields win on conflicts. Additive fields compose instead: array-like
+ * instruction sets are concatenated, and `prompt.appendSystemPrompt` values are
+ * joined base-first with a blank line between them.
  */
 export function mergeAgentProfiles(base, overlay) {
     if (!base && !overlay)
@@ -97,6 +112,7 @@ export function mergeAgentProfiles(base, overlay) {
         ? {
             ...(base?.prompt ?? {}),
             ...(overlay?.prompt ?? {}),
+            appendSystemPrompt: mergeAppendedSystemPrompts(base?.prompt?.appendSystemPrompt, overlay?.prompt?.appendSystemPrompt),
             instructions: mergeStringArrays(base?.prompt?.instructions, overlay?.prompt?.instructions),
         }
         : undefined;

package/dist/environment-provider.d.ts

@@ -617,7 +617,10 @@ export interface AgentEnvironmentCapabilities {
 export declare const AgentEnvironmentCapabilitiesSchema: z.ZodObject<{
     profile: z.ZodObject<{
         namedProfiles: z.ZodBoolean;
-        systemPrompt: z.ZodBoolean;
+        systemPrompt: z.ZodObject<{
+            replace: z.ZodBoolean;
+            append: z.ZodBoolean;
+        }, z.core.$strict>;
         instructions: z.ZodBoolean;
         tools: z.ZodBoolean;
         permissions: z.ZodBoolean;

package/dist/environment-provider.js

@@ -7,7 +7,15 @@ import { InteractionCapabilitiesSchema, } from "./interaction.js";
  */
 const AgentProfileCapabilitiesSchema = z.strictObject({
     namedProfiles: z.boolean(),
-    systemPrompt: z.boolean(),
+    /*
+     * Both bits are required with no default: a document that omits either one,
+     * or sends a bare boolean, fails validation instead of being read as
+     * replacement-supported, which for every append-only backend is false.
+     */
+    systemPrompt: z.strictObject({
+        replace: z.boolean(),
+        append: z.boolean(),
+    }),
     instructions: z.boolean(),
     tools: z.boolean(),
     permissions: z.boolean(),

package/dist/harness-capabilities.d.ts

@@ -1,11 +1,12 @@
-import { type ReasoningEffort } from "./agent-profile.js";
+import { type AgentProfileSystemPromptCapability, type ReasoningEffort } from "./agent-profile.js";
 import type { HarnessType } from "./harness.js";
 /**
  * The unified harness capability layer — the single source of truth for:
- *   1. harness ↔ model compatibility (which models a harness can run), and
- *   2. reasoning-effort support (which thinking levels a harness/model expresses).
+ *   1. harness ↔ model compatibility (which models a harness can run),
+ *   2. reasoning-effort support (which thinking levels a harness/model expresses), and
+ *   3. system-prompt intents (whether a harness can replace its own prompt, add to it, or neither).
  *
- * Both are facets of the same question — "what can this (harness, model) pair actually do" — and
+ * All are facets of the same question — "what can this (harness, model) pair actually do" — and
  * apply to BOTH harness-backed systems (vendor-locked CLIs like claude-code/codex/kimi) AND
  * router-backed systems (opencode, cli-base: any model the router serves). Lifted here so the
  * cli-bridge backends, the sandbox UI pickers, and the router all read one truth instead of each
@@ -66,3 +67,31 @@ export declare function harnessHonorsModel(harness: HarnessType): boolean;
 export declare function harnessHonorsEffort(harness: HarnessType): boolean;
 /** Whether the harness honors BOTH chat selectors — i.e. the model and effort pickers are live. */
 export declare function harnessHonorsSelectors(harness: HarnessType): boolean;
+/**
+ * Which system-prompt intents a harness honors THROUGH A WORKSPACE — the value an adapter that
+ * lowers a profile to files, env vars, and CLI flags and then hands the result to a launcher it
+ * does not own should declare as {@link AgentProfileCapabilities.systemPrompt}. That is the shape
+ * of every caller today (the cli-bridge and tangle providers both forward a plan), which is why
+ * this answer depends on the harness alone.
+ *
+ * It is NOT the whole truth for an adapter that starts the harness itself, because one control in
+ * the table above lives outside any workspace: opencode's `agent.<name>.prompt` really does replace
+ * its built-in prompt, but it binds to the single agent whoever starts the server selects. A plan
+ * cannot name that agent, so `opencode` reads `replace: false` here — while an adapter that writes
+ * opencode's server config AND picks the primary agent (`sdk-provider-opencode`) does honor
+ * replacement, and declares `replace: true` for itself. The capability is a property of the
+ * (harness, executor) pair; this function answers it for the plan-forwarding executor.
+ *
+ * Do not widen the table to close that gap: a harness-keyed `true` would promise the intent to
+ * every plan-forwarding caller, and those callers cannot deliver it. An executor that owns a
+ * launcher control states so where it binds it — `materializeProfile`'s `binds` option in
+ * `@tangle-network/agent-profile-materialize`, which turns the plan's refusal into a binding that
+ * executor must then apply.
+ *
+ * Pass `undefined` when the harness is not known at declaration time: the answer is then
+ * `{ replace: false, append: false }`, because an adapter that cannot name its harness cannot
+ * promise either intent, and `false` means "refuse" rather than "silently substitute the other".
+ * An adapter that forwards a profile to some other layer must still declare what that layer's
+ * harness really does — being able to put the field on the wire is not the same as honoring it.
+ */
+export declare function harnessSystemPromptIntents(harness: HarnessType | undefined): AgentProfileSystemPromptCapability;

package/dist/harness-capabilities.js

@@ -1,10 +1,11 @@
 import { REASONING_EFFORTS, } from "./agent-profile.js";
 /**
  * The unified harness capability layer — the single source of truth for:
- *   1. harness ↔ model compatibility (which models a harness can run), and
- *   2. reasoning-effort support (which thinking levels a harness/model expresses).
+ *   1. harness ↔ model compatibility (which models a harness can run),
+ *   2. reasoning-effort support (which thinking levels a harness/model expresses), and
+ *   3. system-prompt intents (whether a harness can replace its own prompt, add to it, or neither).
  *
- * Both are facets of the same question — "what can this (harness, model) pair actually do" — and
+ * All are facets of the same question — "what can this (harness, model) pair actually do" — and
  * apply to BOTH harness-backed systems (vendor-locked CLIs like claude-code/codex/kimi) AND
  * router-backed systems (opencode, cli-base: any model the router serves). Lifted here so the
  * cli-bridge backends, the sandbox UI pickers, and the router all read one truth instead of each
@@ -219,3 +220,72 @@ export function harnessHonorsEffort(harness) {
 export function harnessHonorsSelectors(harness) {
     return harnessHonorsModel(harness) && harnessHonorsEffort(harness);
 }
+// ── System-prompt intents (which prompt channel the harness actually owns) ────
+/**
+ * The system-prompt intents a harness's own controls can execute, measured by reading the request
+ * each installed CLI sends — NOT taken from its help text:
+ *
+ *   - claude-code 2.1.222 and pi 0.83.0 own both. `--system-prompt` drops the built-in prompt from
+ *     the request (27,673 B → the caller's bytes on claude-code, 2,582 B → the caller's on pi);
+ *     `--append-system-prompt` leaves it in place and adds the caller's text after it.
+ *   - codex 0.146.0 owns replacement only: the `model_instructions_file` config key becomes the
+ *     request's entire instructions text. It has no additive control — its AGENTS.md lands in a
+ *     developer/user message, not the system channel.
+ *   - gemini 0.26.0 owns replacement only: `.gemini/system.md` under `GEMINI_SYSTEM_MD=1` replaces
+ *     the base prompt. Its one additive path is GEMINI.md memory, which IS the `instructions`
+ *     surface, so an addition lowered there would be byte-indistinguishable from `instructions`.
+ *   - opencode 1.17.18 owns addition only THROUGH A WORKSPACE: config-declared `instructions[]`
+ *     files compose into the same single `role: "system"` message as its built-in prompt, which
+ *     stays in place. Its replacement control (`agent.<name>.prompt`) binds to one agent chosen at
+ *     launch, which a workspace plan cannot guarantee — but an executor that selects that agent
+ *     can, so `replace: false` here is the plan-forwarding answer, not opencode's ceiling.
+ *
+ * Every other harness owns NEITHER, including the ones whose prompt path is a `role: "system"` chat
+ * message: that message is flattened into the user turn before the CLI sees it, so it is not a
+ * system-prompt channel at all — honoring an intent through it would put the caller's text in
+ * ordinary user content while the harness's own prompt ran unchanged. A harness with no entry
+ * refuses both, so one added later cannot inherit a capability by omission.
+ */
+const harnessSystemPromptControls = {
+    "claude-code": { replace: true, append: true },
+    pi: { replace: true, append: true },
+    codex: { replace: true, append: false },
+    gemini: { replace: true, append: false },
+    opencode: { replace: false, append: true },
+};
+const noSystemPromptControls = {
+    replace: false,
+    append: false,
+};
+/**
+ * Which system-prompt intents a harness honors THROUGH A WORKSPACE — the value an adapter that
+ * lowers a profile to files, env vars, and CLI flags and then hands the result to a launcher it
+ * does not own should declare as {@link AgentProfileCapabilities.systemPrompt}. That is the shape
+ * of every caller today (the cli-bridge and tangle providers both forward a plan), which is why
+ * this answer depends on the harness alone.
+ *
+ * It is NOT the whole truth for an adapter that starts the harness itself, because one control in
+ * the table above lives outside any workspace: opencode's `agent.<name>.prompt` really does replace
+ * its built-in prompt, but it binds to the single agent whoever starts the server selects. A plan
+ * cannot name that agent, so `opencode` reads `replace: false` here — while an adapter that writes
+ * opencode's server config AND picks the primary agent (`sdk-provider-opencode`) does honor
+ * replacement, and declares `replace: true` for itself. The capability is a property of the
+ * (harness, executor) pair; this function answers it for the plan-forwarding executor.
+ *
+ * Do not widen the table to close that gap: a harness-keyed `true` would promise the intent to
+ * every plan-forwarding caller, and those callers cannot deliver it. An executor that owns a
+ * launcher control states so where it binds it — `materializeProfile`'s `binds` option in
+ * `@tangle-network/agent-profile-materialize`, which turns the plan's refusal into a binding that
+ * executor must then apply.
+ *
+ * Pass `undefined` when the harness is not known at declaration time: the answer is then
+ * `{ replace: false, append: false }`, because an adapter that cannot name its harness cannot
+ * promise either intent, and `false` means "refuse" rather than "silently substitute the other".
+ * An adapter that forwards a profile to some other layer must still declare what that layer's
+ * harness really does — being able to put the field on the wire is not the same as honoring it.
+ */
+export function harnessSystemPromptIntents(harness) {
+    if (!harness)
+        return noSystemPromptControls;
+    return harnessSystemPromptControls[harness] ?? noSystemPromptControls;
+}

package/dist/profile-diff.d.ts

@@ -4,6 +4,7 @@ export type AgentProfileDiffAxis = "identity" | (typeof agentProfileDiffProperty
 export type AgentProfileRemoveList = true | readonly string[];
 export interface AgentProfilePromptRemoval {
     systemPrompt?: true;
+    appendSystemPrompt?: true;
     instructions?: AgentProfileRemoveList;
 }
 export interface AgentProfileResourceRemoval {

package/dist/profile-diff.js

@@ -21,6 +21,13 @@ void _agentProfileDiffPropertyAxesAreExhaustive;
 export function defineAgentProfileDiff(diff) {
     return diff;
 }
+const agentProfilePromptDiffPropertyAxes = [
+    "systemPrompt",
+    "appendSystemPrompt",
+    "instructions",
+];
+const _agentProfilePromptDiffPropertyAxesAreExhaustive = true;
+void _agentProfilePromptDiffPropertyAxesAreExhaustive;
 const agentProfileResourceDiffPropertyAxes = [
     "files",
     "tools",
@@ -223,6 +230,8 @@ function applyRemoval(profile, remove) {
         const prompt = { ...next.prompt };
         if (remove.prompt.systemPrompt)
             prompt.systemPrompt = undefined;
+        if (remove.prompt.appendSystemPrompt)
+            prompt.appendSystemPrompt = undefined;
         prompt.instructions = removeValues(prompt.instructions, remove.prompt.instructions);
         next.prompt = Object.values(prompt).some((value) => value !== undefined)
             ? prompt

package/dist/profile-schema.d.ts

@@ -135,8 +135,15 @@ export declare const agentProfileModelHintsSchema: z.ZodObject<{
     }>>;
     metadata: z.ZodOptional<z.ZodType<Record<string, unknown>, unknown, z.core.$ZodTypeInternals<Record<string, unknown>, unknown>>>;
 }, z.core.$strict>;
+/**
+ * Replacement and addition are separate, independently optional fields, and the
+ * pair is admitted on purpose: the effective prompt is `systemPrompt` followed
+ * by `appendSystemPrompt`. No cross-field refinement rejects the combination,
+ * because {@link mergeAgentProfiles} can produce it from two valid profiles.
+ */
 export declare const agentProfilePromptSchema: z.ZodObject<{
     systemPrompt: z.ZodOptional<z.ZodString>;
+    appendSystemPrompt: z.ZodOptional<z.ZodString>;
     instructions: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
 export declare const agentProfilePublicConfigValueSchema: z.ZodObject<{
@@ -244,6 +251,7 @@ export declare const agentProfileConnectionSchema: z.ZodObject<{
 }, z.core.$strict>;
 export declare const agentProfilePromptRemovalSchema: z.ZodObject<{
     systemPrompt: z.ZodOptional<z.ZodLiteral<true>>;
+    appendSystemPrompt: z.ZodOptional<z.ZodLiteral<true>>;
     instructions: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodArray<z.ZodString>]>>;
 }, z.core.$strict>;
 export declare const agentProfileResourceRemovalSchema: z.ZodObject<{
@@ -260,6 +268,7 @@ export declare const agentProfileDiffRemovalSchema: z.ZodObject<{
     tags: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodArray<z.ZodString>]>>;
     prompt: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodObject<{
         systemPrompt: z.ZodOptional<z.ZodLiteral<true>>;
+        appendSystemPrompt: z.ZodOptional<z.ZodLiteral<true>>;
         instructions: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodArray<z.ZodString>]>>;
     }, z.core.$strict>]>>;
     model: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodArray<z.ZodString>]>>;
@@ -296,6 +305,7 @@ export declare const agentProfileSchema: z.ZodObject<{
     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
     prompt: z.ZodOptional<z.ZodObject<{
         systemPrompt: z.ZodOptional<z.ZodString>;
+        appendSystemPrompt: z.ZodOptional<z.ZodString>;
         instructions: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
     model: z.ZodOptional<z.ZodObject<{

package/dist/profile-schema.js

@@ -98,8 +98,15 @@ export const agentProfileModelHintsSchema = z.strictObject({
     reasoningEffort: reasoningEffortSchema.optional(),
     metadata: ownPropertyRecordSchema(z.unknown()).optional(),
 });
+/**
+ * Replacement and addition are separate, independently optional fields, and the
+ * pair is admitted on purpose: the effective prompt is `systemPrompt` followed
+ * by `appendSystemPrompt`. No cross-field refinement rejects the combination,
+ * because {@link mergeAgentProfiles} can produce it from two valid profiles.
+ */
 export const agentProfilePromptSchema = z.strictObject({
     systemPrompt: z.string().optional(),
+    appendSystemPrompt: z.string().optional(),
     instructions: z.array(z.string()).optional(),
 });
 const controlCharacterPattern = /[\u0000-\u001f\u007f]/;
@@ -245,6 +252,7 @@ export const agentProfileConnectionSchema = z.strictObject({
 const removeListSchema = z.union([z.literal(true), z.array(z.string().min(1))]);
 export const agentProfilePromptRemovalSchema = z.strictObject({
     systemPrompt: z.literal(true).optional(),
+    appendSystemPrompt: z.literal(true).optional(),
     instructions: removeListSchema.optional(),
 });
 export const agentProfileResourceRemovalSchema = z.strictObject({
@@ -347,6 +355,17 @@ export const agentProfileDiffSchema = z.strictObject({
 });
 const _agentProfileSchemaMatchesInterface = true;
 void _agentProfileSchemaMatchesInterface;
+// Plain assignability cannot see a missing OPTIONAL field: an object type
+// without `x?` is assignable to one with it, in both directions. Since nearly
+// every profile field is optional, comparing the same shapes with optionality
+// removed is what actually catches a field added to one side only — and a field
+// missing from this strict schema means valid profiles get rejected at runtime.
+// Applied at the top level and again inside the prompt, whose two intents are
+// distinct enough that losing one is a silent semantic change, not a parse error.
+const _agentProfileSchemaFieldsMatchInterface = true;
+void _agentProfileSchemaFieldsMatchInterface;
+const _agentProfilePromptSchemaFieldsMatchInterface = true;
+void _agentProfilePromptSchemaFieldsMatchInterface;
 export const capabilitySchema = z.strictObject({
     id: z.string().min(1),
     definition: agentProfileSchema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-interface",
-  "version": "0.43.1",
+  "version": "0.44.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",