@jam-mcp/server 1.3.0 → 1.3.1

package/dist/application/plan-write.js

@@ -1,6 +1,7 @@
 import { JamError } from "../domain/errors.js";
 import { assertExistingIssueOperation, assertFieldsAllowed, assertOperationAllowed, assertWriteScope, PLAN_TTL_MS, resolveTransition, } from "../policy/write-policy.js";
 import { assertAssignable, assertNotAlreadyAssigned, exactMatches, resolveAssignee, } from "../policy/assignee-policy.js";
+import { assertEditable, classifyKind, resolveCustomFieldValue, resolveWritableField, } from "../policy/custom-field-policy.js";
 import { planCreateIssue } from "./plan-create-issue.js";
 /**
  * Work out whether a requested change is currently possible, and describe it.
@@ -31,9 +32,15 @@ export async function planWrite(deps, request) {
     // does not write should get that answer, not a round trip and then that
     // answer.
     const input = validateInput(operation, request.input);
-    const snapshot = await readIssue(deps, issueKey);
+    // Which custom field the whitelist says this is, settled before the read so
+    // the read can fetch its current value in the same request. A selector the
+    // team never opted in costs no Jira call at all.
+    const targetField = operation === "custom-field.update"
+        ? resolveWritableField(deps.config, input.field)
+        : undefined;
+    const snapshot = await readIssue(deps, issueKey, targetField ? [targetField.id] : []);
     const issue = snapshot.issue;
-    const { before, intendedAfter, mutation, transition, baseAssigneeAccountId } = await describe(deps, operation, issueKey, snapshot, input);
+    const { before, intendedAfter, mutation, transition, baseAssigneeAccountId, customFieldRequirements } = await describe(deps, operation, issueKey, snapshot, input, targetField);
     const createdAt = new Date();
     const plan = deps.writePlans.create({
         kind: "existing-issue",
@@ -47,6 +54,7 @@ export async function planWrite(deps, request) {
         expiresAt: new Date(createdAt.getTime() + PLAN_TTL_MS).toISOString(),
         ...(transition ? { transition } : {}),
         ...(baseAssigneeAccountId ? { baseAssigneeAccountId } : {}),
+        ...(customFieldRequirements ? { customFieldRequirements } : {}),
         mutation,
     });
     return {
@@ -63,8 +71,8 @@ export async function planWrite(deps, request) {
         },
     };
 }
-export async function readIssue(deps, issueKey) {
-    const { issue: found, assigneeAccountId } = await deps.jira.getIssue({
+export async function readIssue(deps, issueKey, extraFields = []) {
+    const { issue: found, assigneeAccountId, customFieldValues } = await deps.jira.getIssue({
         key: issueKey,
         // `issuetype` and `description` are here for creation's verification step,
         // which has to confirm the issue Jira made is the one that was asked for.
@@ -81,13 +89,33 @@ export async function readIssue(deps, issueKey) {
             "labels",
             "components",
             "updated",
+            // A custom field is only read when one is being written, and then only
+            // that one - so a custom-field update still costs a single direct GET
+            // rather than a second read for the field it is about to change.
+            ...extraFields.filter((f) => !BASE_WRITE_FIELDS.has(f)),
         ],
     });
     if (!found) {
         throw new JamError("ISSUE_NOT_FOUND", `Jira has no issue ${issueKey}, or it is not visible to this account.`, { issueKey });
     }
-    return { issue: found, ...(assigneeAccountId ? { assigneeAccountId } : {}) };
+    return {
+        issue: found,
+        ...(assigneeAccountId ? { assigneeAccountId } : {}),
+        ...(customFieldValues ? { customFieldValues } : {}),
+    };
 }
+/** Requested on every write-plane read, so an extra field is never a duplicate. */
+const BASE_WRITE_FIELDS = new Set([
+    "summary",
+    "status",
+    "issuetype",
+    "description",
+    "assignee",
+    "priority",
+    "labels",
+    "components",
+    "updated",
+]);
 /**
  * The issue an existing-issue operation names, or a refusal that says why.
  *
@@ -128,6 +156,30 @@ function validateInput(operation, raw) {
             }
             return { status: status.trim() };
         }
+        case "custom-field.update": {
+            // Anything outside this operation's own two keys is refused rather than
+            // ignored. Silently dropping a key an agent supplied is how a caller
+            // ends up with a write that is not the one it described - and the shared
+            // input object means another operation's key is a plausible mistake.
+            const extra = Object.keys(raw).filter((k) => raw[k] !== undefined && k !== "field" && k !== "value");
+            if (extra.length > 0) {
+                throw new JamError("JAM_WRITE_FIELD_NOT_ALLOWED", `custom-field.update takes only \`field\` and \`value\`. Remove: ${extra.join(", ")}.`, { operation, rejected: extra });
+            }
+            const { field, value } = raw;
+            if (typeof field !== "string" || field.trim().length === 0) {
+                throw new JamError("JAM_WRITE_OPERATION_NOT_ALLOWED", "custom-field.update needs non-empty `input.field` - a configured custom field id or name.", { operation });
+            }
+            // The value's family is checked against Jira's schema later; what is
+            // checked here is that it is a shape the contract admits at all. An
+            // object, a boolean or a null never reaches the type policy.
+            const isString = typeof value === "string";
+            const isNumber = typeof value === "number";
+            const isStringArray = Array.isArray(value) && value.every((v) => typeof v === "string");
+            if (!isString && !isNumber && !isStringArray) {
+                throw new JamError("JAM_WRITE_OPERATION_NOT_ALLOWED", "custom-field.update needs `input.value` to be a string, a number, or an array of strings.", { operation, received: Array.isArray(value) ? "array" : typeof value });
+            }
+            return { field: field.trim(), value };
+        }
         case "assignee.update": {
             const assignee = raw.assignee;
             if (typeof assignee !== "string" || assignee.trim().length === 0) {
@@ -137,7 +189,7 @@ function validateInput(operation, raw) {
         }
     }
 }
-async function describe(deps, operation, issueKey, snapshot, input) {
+async function describe(deps, operation, issueKey, snapshot, input, targetField) {
     const issue = snapshot.issue;
     switch (operation) {
         case "comment.add": {
@@ -178,6 +230,31 @@ async function describe(deps, operation, issueKey, snapshot, input) {
                 transition,
             };
         }
+        case "custom-field.update": {
+            const field = targetField;
+            const requested = input;
+            // Jira decides what is editable here and now, and in what shape. JAM
+            // does not model project contexts, screens or permissions - it asks the
+            // one endpoint that answers all three at once for this issue.
+            const metadata = await deps.jiraEditMetadata.getEditableFields(issueKey);
+            const editable = assertEditable(issueKey, field, metadata);
+            const kind = classifyKind(editable);
+            const { jiraValue, view, resolvedOptions } = resolveCustomFieldValue(editable, kind, requested);
+            return {
+                before: {
+                    customField: currentCustomFieldView(field, kind, snapshot.customFieldValues?.[field.id]),
+                },
+                intendedAfter: { customField: view },
+                mutation: { kind: "custom-field", fieldId: field.id, value: jiraValue },
+                customFieldRequirements: {
+                    fieldId: field.id,
+                    fieldName: field.name,
+                    kind,
+                    schema: editable.schema,
+                    ...(resolvedOptions ? { resolvedOptions } : {}),
+                },
+            };
+        }
         case "assignee.update": {
             const { assignee: requested } = input;
             // Ask Jira who this is, and decide from what it says. The requested
@@ -240,6 +317,31 @@ function currentValue(issue, field) {
             return undefined;
     }
 }
+/**
+ * What the field holds now, in the shape a receipt shows.
+ *
+ * Jira stores an option as an object and a scalar as itself; a person reading
+ * `before` wants the same canonical form they will see in `intendedAfter`, so
+ * they can compare the two rather than a payload against a summary.
+ */
+export function currentCustomFieldView(field, kind, raw) {
+    const named = { id: field.id, name: field.name };
+    if (kind === "multi-option") {
+        return { ...named, value: Array.isArray(raw) ? raw.map(toOptionView) : [] };
+    }
+    if (kind === "single-option") {
+        return { ...named, value: raw == null ? null : toOptionView(raw) };
+    }
+    if (raw == null)
+        return { ...named, value: null };
+    return { ...named, value: kind === "number" ? Number(raw) : String(raw) };
+}
+function toOptionView(raw) {
+    const o = raw;
+    const id = typeof o?.id === "string" ? o.id : typeof o?.id === "number" ? String(o.id) : "";
+    const label = typeof o?.value === "string" ? o.value : typeof o?.name === "string" ? o.name : String(raw);
+    return { id, label };
+}
 /** Whitelisted values to the shapes Jira's field API expects. */
 function toJiraFields(input) {
     const fields = {};

package/dist/bootstrap/mcp-config-merger.d.ts

@@ -13,7 +13,7 @@ import { LAUNCHER_PACKAGE_SPEC } from "@jam-mcp/launcher";
 export { LAUNCHER_PACKAGE_SPEC };
 export declare const JAM_MCP_ENTRY: {
     readonly command: "npx";
-    readonly args: readonly ["--yes", "@jam-mcp/launcher@1.3.0", "serve"];
+    readonly args: readonly ["--yes", "@jam-mcp/launcher@1.3.1", "serve"];
 };
 /**
  * Recognise wiring from before the launcher existed: a hard-coded path to one

package/dist/bootstrap/setup-plan.d.ts

@@ -64,10 +64,21 @@ export type SetupPlan = {
      * configured - so it is an `npx` bootstrap invocation, never a bare `jam`.
      * A human interface is free to render the short form; this field is the one
      * a script runs, and a script has no PATH to rely on.
+     *
+     * `userCommand` is the opposite: a command for the person, which the agent
+     * relays and never runs. Authentication is the only step of that shape, and
+     * it carries no `command` precisely so that no caller can execute it. The
+     * separation is the point - one field is for running, the other for showing.
+     *
+     * `env` names the variables that would satisfy the same requirement without
+     * the interactive command, so an agent that cannot show a prompt still knows
+     * what the person has to provide - never their values.
      */
     nextAction?: {
         type: "authenticate" | "select_project" | "configure_runtime";
         command?: string;
+        userCommand?: string;
+        env?: string[];
     };
     project?: {
         root: string;

package/dist/bootstrap/setup-plan.js

@@ -113,7 +113,16 @@ function finish(changes, state, project) {
             code: "JAM_AUTH_REQUIRED",
             changes,
             requiresUserAction: true,
-            nextAction: { type: "authenticate" },
+            nextAction: {
+                type: "authenticate",
+                // Deliberately no `command`: an agent must not run the login, and the
+                // absence is what stops it. `userCommand` is what it hands the person
+                // instead - previously that instruction existed only in CLI prose, so
+                // an agent reading the JSON alone knew a human was needed but not for
+                // what.
+                userCommand: portableBootstrapCommand("auth login"),
+                env: ["JIRA_BASE_URL", "JIRA_EMAIL", "JIRA_API_TOKEN"],
+            },
             project,
         };
     }

package/dist/cli-entry.js

@@ -11,39 +11,39 @@ import { authStatusCommand, doctorJsonCommand, setupAgentCommand, setupApplyComm
  * points (notably @jam-mcp/bootstrap) can forward to exactly these commands
  * instead of reimplementing them.
  */
-export const USAGE = `jam - Jira Agent MCP
-
-Usage:
-  jam serve               Run the MCP server over stdio (default; this is what Claude Code / Codex launch)
-  jam doctor              Diagnose config, credentials and Jira connectivity
-  jam setup [--project KEY] [--shared] [--migrate] [--non-interactive]
-                          Wire up this project and run doctor. Binds it to you
-                          alone, writing nothing to the repository; --shared
-                          adopts JAM for the team (project.yaml, .mcp.json)
-  jam runtime             Show which JAM build this machine runs
-  jam runtime use package | development <path>
-                          Change it (writes ~/.jam/config.yaml only, never a project)
-  jam auth login          Store Jira credentials in this user's OS secret store
-  jam auth logout         Remove them again
-
-For coding agents and scripts (stdout is JSON only, never prompts):
-  jam setup --agent       One shot: detect, plan, apply what is safe, verify
-  jam setup plan --json   Report what setup would change, changing nothing
-  jam setup apply --non-interactive --json
-                          Execute the plan
-  jam doctor --json       Health check as structured output
-  jam auth status --json  Whether Jira credentials are configured (never their value)
-
-Environment:
-  JIRA_BASE_URL     https://your-site.atlassian.net
-  JIRA_EMAIL        Atlassian account email
-  JIRA_API_TOKEN    Atlassian API token
-  JAM_PROJECT_KEY   Jira project key, used by \`jam setup\`/\`jam serve\` when no
-                     .jira-agent/project.yaml exists yet
-
-Credentials and JAM_PROJECT_KEY are read from the current shell's environment
-first, then (on Windows) from the User environment - so a value set with
-\`setx\` works without opening a new terminal.
+export const USAGE = `jam - Jira Agent MCP
+
+Usage:
+  jam serve               Run the MCP server over stdio (default; this is what Claude Code / Codex launch)
+  jam doctor              Diagnose config, credentials and Jira connectivity
+  jam setup [--project KEY] [--shared] [--migrate] [--non-interactive]
+                          Wire up this project and run doctor. Binds it to you
+                          alone, writing nothing to the repository; --shared
+                          adopts JAM for the team (project.yaml, .mcp.json)
+  jam runtime             Show which JAM build this machine runs
+  jam runtime use package | development <path>
+                          Change it (writes ~/.jam/config.yaml only, never a project)
+  jam auth login          Store Jira credentials in this user's OS secret store
+  jam auth logout         Remove them again
+
+For coding agents and scripts (stdout is JSON only, never prompts):
+  jam setup --agent       One shot: detect, plan, apply what is safe, verify
+  jam setup plan --json   Report what setup would change, changing nothing
+  jam setup apply --non-interactive --json
+                          Execute the plan
+  jam doctor --json       Health check as structured output
+  jam auth status --json  Whether Jira credentials are configured (never their value)
+
+Environment:
+  JIRA_BASE_URL     https://your-site.atlassian.net
+  JIRA_EMAIL        Atlassian account email
+  JIRA_API_TOKEN    Atlassian API token
+  JAM_PROJECT_KEY   Jira project key, used by \`jam setup\`/\`jam serve\` when no
+                     .jira-agent/project.yaml exists yet
+
+Credentials and JAM_PROJECT_KEY are read from the current shell's environment
+first, then (on Windows) from the User environment - so a value set with
+\`setx\` works without opening a new terminal.
 `;
 function findFlagValue(argv, flag) {
     const index = argv.indexOf(flag);

package/dist/config/schema.d.ts

@@ -19,6 +19,7 @@ export declare const ProjectConfigSchema: z.ZodObject<{
     customFields: z.ZodDefault<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         name: z.ZodString;
+        writable: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>>;
     output: z.ZodPrefault<z.ZodObject<{
         searchTokens: z.ZodDefault<z.ZodNumber>;

package/dist/config/schema.js

@@ -1,4 +1,23 @@
 import { z } from "zod";
+/** Values that appear more than once, each named once. */
+function duplicates(values) {
+    const seen = new Set();
+    const repeated = new Set();
+    for (const value of values) {
+        if (seen.has(value))
+            repeated.add(value);
+        seen.add(value);
+    }
+    return [...repeated];
+}
+function report(ctx, repeated, what) {
+    for (const value of repeated) {
+        ctx.addIssue({
+            code: "custom",
+            message: `duplicate custom field ${what} "${value}" - a selector must name one field`,
+        });
+    }
+}
 /**
  * `.jira-agent/project.yaml` - per-project policy only.
  * Credentials are never stored here; they come from the CredentialPort.
@@ -41,13 +60,28 @@ export const ProjectConfigSchema = z.object({
     /**
      * Whitelisted project-specific custom fields, surfaced at CONTEXT level and up.
      * `id` is the Jira field id (customfield_10011); `name` is what the agent sees.
+     *
+     * `writable` is a second, separate consent. Reading a field and letting an
+     * agent change it are different decisions, and a config written when JAM
+     * could only read must not start granting writes because JAM learned how.
+     * So it defaults to false: every whitelist that predates this is read-only,
+     * and a team opts a field in by saying so.
      */
     customFields: z
         .array(z.object({
         id: z.string().regex(/^customfield_\d+$/),
         name: z.string().min(1),
+        writable: z.boolean().default(false),
     }))
-        .default([]),
+        .default([])
+        .superRefine((fields, ctx) => {
+        // Ambiguity in a whitelist is worse than an omission: `custom-field.update`
+        // resolves a selector against these entries, and two rows answering to
+        // the same selector would make which field gets written a matter of
+        // ordering.
+        report(ctx, duplicates(fields.map((f) => f.id.toLowerCase())), "id");
+        report(ctx, duplicates(fields.filter((f) => f.writable).map((f) => f.name.trim().toLowerCase())), "writable name");
+    }),
     output: z
         .object({
         /** Rough token ceilings per level. Enforced by OutputBudgetPolicy. */

package/dist/deps.d.ts

@@ -6,6 +6,7 @@ import type { CredentialPort } from "./ports/credentials.port.js";
 import type { JiraReadPort } from "./ports/jira-read.port.js";
 import type { JiraAssigneeResolutionPort } from "./ports/jira-assignee-resolution.port.js";
 import type { JiraCreateMetadataPort } from "./ports/jira-create-metadata.port.js";
+import type { JiraEditMetadataPort } from "./ports/jira-edit-metadata.port.js";
 import type { JiraWritePort } from "./ports/jira-write.port.js";
 import { WritePlanStore } from "./application/write-plan-store.js";
 import type { TelemetryPort } from "./ports/telemetry.port.js";
@@ -36,6 +37,12 @@ export type JamDeps = {
      * it mutates nothing.
      */
     jiraAssignees: JiraAssigneeResolutionPort;
+    /**
+     * What Jira will let this account change on one issue. A fifth read-shaped
+     * port, for the same reason as the third and fourth: it mutates nothing, and
+     * it answers a question about a configuration rather than about an issue.
+     */
+    jiraEditMetadata: JiraEditMetadataPort;
     /**
      * Plans awaiting apply. Lives for the life of this server process - see
      * WritePlanStore for why it is not persisted.
@@ -55,6 +62,8 @@ export type BuildDepsOptions = {
     jiraCreateMetadata?: JiraCreateMetadataPort;
     /** Injected by tests so user resolution never reaches a real directory. */
     jiraAssignees?: JiraAssigneeResolutionPort;
+    /** Injected by tests so edit metadata comes from a fixture, not a site. */
+    jiraEditMetadata?: JiraEditMetadataPort;
     /** Injected by tests to bypass the real process/registry credential lookup. */
     credentials?: CredentialPort;
     /**

package/dist/deps.js

@@ -43,6 +43,11 @@ export async function buildDeps(options = {}) {
         const { JiraCloudAssigneeResolutionAdapter } = await import("./adapters/jira-cloud/jira-assignee-resolution.adapter.js");
         jiraAssignees = new JiraCloudAssigneeResolutionAdapter(credentials);
     }
+    let jiraEditMetadata = options.jiraEditMetadata;
+    if (!jiraEditMetadata) {
+        const { JiraCloudEditMetadataAdapter } = await import("./adapters/jira-cloud/jira-edit-metadata.adapter.js");
+        jiraEditMetadata = new JiraCloudEditMetadataAdapter(credentials);
+    }
     return {
         config: resolved.config,
         configPath: resolved.configPath,
@@ -51,6 +56,7 @@ export async function buildDeps(options = {}) {
         jiraWrite,
         jiraCreateMetadata,
         jiraAssignees,
+        jiraEditMetadata,
         writePlans: new WritePlanStore(),
         cache: new NoopCache(),
         telemetry,

package/dist/domain/errors.d.ts

@@ -5,7 +5,7 @@
  * is mapped onto one of these codes so the agent (and `jam doctor`) can reason
  * about failures without parsing vendor-specific payloads.
  */
-export declare const JAM_ERROR_CODES: readonly ["JIRA_AUTH_FAILED", "JIRA_PERMISSION_DENIED", "JQL_INVALID", "ISSUE_NOT_FOUND", "RATE_LIMITED", "CONTEXT_TOO_LARGE", "PARTIAL_RESULT", "CONFIG_INVALID", "JIRA_UNAVAILABLE", "JAM_SETUP_REQUIRED", "JAM_BINDINGS_UNREADABLE", "JAM_WRITE_SCOPE_VIOLATION", "JAM_WRITE_OPERATION_NOT_ALLOWED", "JAM_WRITE_FIELD_NOT_ALLOWED", "JAM_WRITE_TRANSITION_NOT_AVAILABLE", "JAM_WRITE_ISSUE_TYPE_NOT_AVAILABLE", "JAM_WRITE_REQUIRED_FIELD_UNSUPPORTED", "JAM_WRITE_VALUE_NOT_ALLOWED", "JAM_WRITE_SCHEMA_CHANGED", "JAM_WRITE_ASSIGNEE_NOT_FOUND", "JAM_WRITE_ASSIGNEE_AMBIGUOUS", "JAM_WRITE_ASSIGNEE_NOT_ASSIGNABLE", "JAM_WRITE_ASSIGNEE_ALREADY_SET", "JAM_WRITE_PLAN_NOT_FOUND", "JAM_WRITE_PLAN_EXPIRED", "JAM_WRITE_CONFLICT", "JAM_WRITE_VERIFICATION_FAILED", "JAM_WRITE_UNCERTAIN"];
+export declare const JAM_ERROR_CODES: readonly ["JIRA_AUTH_FAILED", "JIRA_PERMISSION_DENIED", "JQL_INVALID", "ISSUE_NOT_FOUND", "RATE_LIMITED", "CONTEXT_TOO_LARGE", "PARTIAL_RESULT", "CONFIG_INVALID", "JIRA_UNAVAILABLE", "JAM_SETUP_REQUIRED", "JAM_BINDINGS_UNREADABLE", "JAM_WRITE_SCOPE_VIOLATION", "JAM_WRITE_OPERATION_NOT_ALLOWED", "JAM_WRITE_FIELD_NOT_ALLOWED", "JAM_WRITE_TRANSITION_NOT_AVAILABLE", "JAM_WRITE_ISSUE_TYPE_NOT_AVAILABLE", "JAM_WRITE_REQUIRED_FIELD_UNSUPPORTED", "JAM_WRITE_VALUE_NOT_ALLOWED", "JAM_WRITE_SCHEMA_CHANGED", "JAM_WRITE_ASSIGNEE_NOT_FOUND", "JAM_WRITE_ASSIGNEE_AMBIGUOUS", "JAM_WRITE_ASSIGNEE_NOT_ASSIGNABLE", "JAM_WRITE_ASSIGNEE_ALREADY_SET", "JAM_WRITE_CUSTOM_FIELD_NOT_EDITABLE", "JAM_WRITE_CUSTOM_FIELD_TYPE_UNSUPPORTED", "JAM_WRITE_PLAN_NOT_FOUND", "JAM_WRITE_PLAN_EXPIRED", "JAM_WRITE_CONFLICT", "JAM_WRITE_VERIFICATION_FAILED", "JAM_WRITE_UNCERTAIN"];
 export type JamErrorCode = (typeof JAM_ERROR_CODES)[number];
 export type JamErrorPayload = {
     error: {

package/dist/domain/errors.js

@@ -42,6 +42,12 @@ export const JAM_ERROR_CODES = [
     "JAM_WRITE_ASSIGNEE_AMBIGUOUS",
     "JAM_WRITE_ASSIGNEE_NOT_ASSIGNABLE",
     "JAM_WRITE_ASSIGNEE_ALREADY_SET",
+    // Custom fields. Three permissions have to line up and none implies another,
+    // so a refusal says which one is missing: the team never opted this field in,
+    // Jira will not let it be set on this issue, or JAM does not know the type
+    // well enough to write it. Each points somewhere different.
+    "JAM_WRITE_CUSTOM_FIELD_NOT_EDITABLE",
+    "JAM_WRITE_CUSTOM_FIELD_TYPE_UNSUPPORTED",
     "JAM_WRITE_PLAN_NOT_FOUND",
     "JAM_WRITE_PLAN_EXPIRED",
     "JAM_WRITE_CONFLICT",

package/dist/domain/write.d.ts

@@ -20,9 +20,9 @@
  * layer: these name an issue, creation names a project; these compare a
  * revision to detect a conflict, creation has no revision to compare.
  */
-export declare const EXISTING_ISSUE_OPERATIONS: readonly ["comment.add", "field.update", "status.transition", "assignee.update"];
+export declare const EXISTING_ISSUE_OPERATIONS: readonly ["comment.add", "field.update", "status.transition", "assignee.update", "custom-field.update"];
 /** The operations the public MCP surface accepts. Nothing else is reachable. */
-export declare const WRITE_OPERATIONS: readonly ["comment.add", "field.update", "status.transition", "assignee.update", "issue.create"];
+export declare const WRITE_OPERATIONS: readonly ["comment.add", "field.update", "status.transition", "assignee.update", "custom-field.update", "issue.create"];
 export type ExistingIssueOperation = (typeof EXISTING_ISSUE_OPERATIONS)[number];
 export type WriteOperation = (typeof WRITE_OPERATIONS)[number];
 /**
@@ -93,7 +93,7 @@ export type CreateIssueInput = {
     labels?: string[];
     components?: string[];
 };
-export type WriteInput = CommentAddInput | FieldUpdateInput | StatusTransitionInput | AssigneeUpdateInput | CreateIssueInput;
+export type WriteInput = CommentAddInput | FieldUpdateInput | StatusTransitionInput | AssigneeUpdateInput | CustomFieldUpdateInput | CreateIssueInput;
 /** An issue type as Jira offers it for one project, right now. */
 export type CreateIssueType = {
     id: string;
@@ -143,6 +143,93 @@ export type CreateSchemaRequirements = {
         resolved: string;
     }[];
 };
+/**
+ * One field on an issue's edit screen, as Jira describes it.
+ *
+ * Normalized at the adapter: `operations` and `schema` come straight from
+ * Jira's own vocabulary because they are the vocabulary the decision is made
+ * in, but nothing else of the raw document travels.
+ */
+export type EditFieldMetadata = {
+    /** Jira's field id, e.g. `customfield_10021`. */
+    id: string;
+    name: string;
+    required: boolean;
+    /** What Jira says can be done to this field: `set`, `add`, `remove`, ... */
+    operations: string[];
+    schema: {
+        type: string;
+        /** Element type, for `type: "array"`. */
+        items?: string;
+        /** The custom field's implementation key, when it is a custom field. */
+        custom?: string;
+        customId?: number;
+    };
+    /** Present only where Jira constrains the value. Absent is not empty. */
+    allowedValues?: EditFieldOption[];
+};
+/**
+ * One option Jira offers for a constrained field.
+ *
+ * `id` is the identity and `label` is what a person reads - the same split as
+ * a user's accountId and display name, and for the same reason: an option can
+ * be renamed without becoming a different option, and two options could carry
+ * the same label.
+ */
+export type EditFieldOption = {
+    id: string;
+    label: string;
+};
+/**
+ * The custom field value families JAM can write.
+ *
+ * Narrow on purpose. Each of these has an unambiguous wire shape that JAM can
+ * produce from a plain caller value and compare after the fact. Everything
+ * else - dates needing a timezone policy, rich text needing ADF, user and
+ * group pickers needing identity resolution, app-owned fields with private
+ * semantics - is refused rather than guessed at.
+ */
+export declare const CUSTOM_FIELD_KINDS: readonly ["text", "number", "single-option", "multi-option"];
+export type CustomFieldKind = (typeof CUSTOM_FIELD_KINDS)[number];
+export type CustomFieldUpdateInput = {
+    /** A configured field id, or a configured writable field name. */
+    field: string;
+    value: string | number | string[];
+};
+/**
+ * What a custom-field plan depends on, recorded so apply can check it again.
+ *
+ * The issue's revision does not cover any of this: a field can be taken off a
+ * screen, lose its `set` operation, change type, or have an option renamed
+ * without the issue itself being touched. So these premises are frozen
+ * alongside `baseUpdated`, and re-derived before the write.
+ */
+export type CustomFieldRequirements = {
+    fieldId: string;
+    fieldName: string;
+    kind: CustomFieldKind;
+    schema: {
+        type: string;
+        items?: string;
+        custom?: string;
+    };
+    /** Options resolved from Jira's allowed list, for the option kinds. */
+    resolvedOptions?: EditFieldOption[];
+};
+/** A custom field value as a receipt shows it - reviewable, not a Jira payload. */
+export type CustomFieldValueView = {
+    id: string;
+    name: string;
+    value: string | number | null;
+} | {
+    id: string;
+    name: string;
+    value: EditFieldOption | null;
+} | {
+    id: string;
+    name: string;
+    value: EditFieldOption[];
+};
 /** A transition as Jira currently offers it for one issue. */
 export type JiraTransition = {
     id: string;
@@ -188,6 +275,11 @@ export type ExistingIssueWritePlan = WritePlanCommon & {
      * `undefined` means the issue was unassigned.
      */
     baseAssigneeAccountId?: string;
+    /**
+     * What this plan assumed about a custom field's configuration. Present only
+     * for `custom-field.update`; apply re-derives each premise before writing.
+     */
+    customFieldRequirements?: CustomFieldRequirements;
 };
 /**
  * A plan to create an issue that does not exist yet.
@@ -222,6 +314,10 @@ export type WriteMutation = {
 } | {
     kind: "assignee";
     accountId: string;
+} | {
+    kind: "custom-field";
+    fieldId: string;
+    value: unknown;
 } | {
     kind: "create";
     fields: Record<string, unknown>;

package/dist/domain/write.js

@@ -25,6 +25,7 @@ export const EXISTING_ISSUE_OPERATIONS = [
     "field.update",
     "status.transition",
     "assignee.update",
+    "custom-field.update",
 ];
 /** The operations the public MCP surface accepts. Nothing else is reachable. */
 export const WRITE_OPERATIONS = [...EXISTING_ISSUE_OPERATIONS, "issue.create"];
@@ -55,6 +56,16 @@ export const CREATABLE_FIELDS = [
     "labels",
     "components",
 ];
+/**
+ * The custom field value families JAM can write.
+ *
+ * Narrow on purpose. Each of these has an unambiguous wire shape that JAM can
+ * produce from a plain caller value and compare after the fact. Everything
+ * else - dates needing a timezone policy, rich text needing ADF, user and
+ * group pickers needing identity resolution, app-owned fields with private
+ * semantics - is refused rather than guessed at.
+ */
+export const CUSTOM_FIELD_KINDS = ["text", "number", "single-option", "multi-option"];
 export function isWriteOperation(value) {
     return WRITE_OPERATIONS.includes(value);
 }

package/dist/mcp/tools/jira-write-apply.tool.js

@@ -1,20 +1,20 @@
 import { z } from "zod";
 import { applyWritePlan } from "../../application/apply-write.js";
 import { runTool } from "../tool-result.js";
-const DESCRIPTION = `Apply a plan from jira_write_plan. This changes Jira.
-
-Takes a planId and nothing else. The change was decided when the plan was made, so there is no field, payload or override to pass here - that is deliberate, and it is what stops a write happening without the state check that planning did.
-
-Before writing, JAM re-reads the issue and compares it to what the plan saw. If it moved, you get JAM_WRITE_CONFLICT and no write happens: call jira_write_plan again against the new state rather than treating the conflict as a transient failure.
-
-After writing, JAM reads the issue back and checks the intended result is actually there. Only then does it return "applied". Jira accepting a request is not the same as the issue having changed.
-
-Failures worth handling differently:
-- JAM_WRITE_CONFLICT             the issue moved; re-plan
-- JAM_WRITE_PLAN_EXPIRED         the plan aged out; re-plan
-- JAM_WRITE_VERIFICATION_FAILED  Jira accepted it but the issue does not show it; read the issue and tell the user
-- JAM_WRITE_UNCERTAIN            JAM does not know whether it landed; read the issue. Do NOT call this tool again - the write may already have been applied, and applying it twice is a second comment or a second transition.
-
+const DESCRIPTION = `Apply a plan from jira_write_plan. This changes Jira.
+
+Takes a planId and nothing else. The change was decided when the plan was made, so there is no field, payload or override to pass here - that is deliberate, and it is what stops a write happening without the state check that planning did.
+
+Before writing, JAM re-reads the issue and compares it to what the plan saw. If it moved, you get JAM_WRITE_CONFLICT and no write happens: call jira_write_plan again against the new state rather than treating the conflict as a transient failure.
+
+After writing, JAM reads the issue back and checks the intended result is actually there. Only then does it return "applied". Jira accepting a request is not the same as the issue having changed.
+
+Failures worth handling differently:
+- JAM_WRITE_CONFLICT             the issue moved; re-plan
+- JAM_WRITE_PLAN_EXPIRED         the plan aged out; re-plan
+- JAM_WRITE_VERIFICATION_FAILED  Jira accepted it but the issue does not show it; read the issue and tell the user
+- JAM_WRITE_UNCERTAIN            JAM does not know whether it landed; read the issue. Do NOT call this tool again - the write may already have been applied, and applying it twice is a second comment or a second transition.
+
 Never report an uncertain or unverified write as done.`;
 export function registerJiraWriteApply(server, deps) {
     server.registerTool("jira_write_apply", {