bpmnlint-plugin-camunda-compat 2.55.0 → 2.56.0

package/index.js

@@ -111,6 +111,9 @@ const camundaCloud87Rules = withConfig({
 
 const camundaCloud88Rules = withConfig({
   ...omit(camundaCloud87Rules, [ 'no-task-listeners' ]),
+  'agent-tool-documentation': 'warn',
+  'agent-tool-output-key': 'warn',
+  'agent-fromai-contract': 'error',
   'task-listener': 'error'
 }, { version: '8.8' });
 
@@ -169,6 +172,9 @@ const bpmnlintRules = [
 
 const rules = {
   'ad-hoc-sub-process': './rules/camunda-cloud/ad-hoc-sub-process',
+  'agent-fromai-contract': './rules/camunda-cloud/agent-fromai-contract',
+  'agent-tool-documentation': './rules/camunda-cloud/agent-tool-documentation',
+  'agent-tool-output-key': './rules/camunda-cloud/agent-tool-output-key',
   'before-all-execution-listener': './rules/camunda-cloud/before-all-execution-listener',
   'element-type': './rules/camunda-cloud/element-type',
   'cancel-execution-listener': './rules/camunda-cloud/cancel-execution-listener',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bpmnlint-plugin-camunda-compat",
-  "version": "2.55.0",
+  "version": "2.56.0",
   "description": "A bpmnlint plug-in for Camunda compatibility",
   "main": "index.js",
   "scripts": {
@@ -38,6 +38,7 @@
   },
   "dependencies": {
     "@bpmn-io/feel-analyzer": "^0.3.0",
+    "@bpmn-io/lezer-feel": "^2.5.0",
     "@bpmn-io/moddle-utils": "^0.3.0",
     "@bpmn-io/semver-compat": "^0.1.0",
     "@camunda/feel-builtins": "^1.2.0",

package/rules/camunda-cloud/agent-fromai-contract.js

@@ -0,0 +1,374 @@
+const { is } = require('bpmnlint-utils');
+
+const { findExtensionElement, findAncestorAdHocSubProcess, isAgenticAdHocSubProcess } = require('../utils/element');
+const { CORRECT_NAME, NAME_ALIASES, findFunctionInvocations, getPositionalArgs } = require('./utils/feel');
+const { reportErrors } = require('../utils/reporter');
+const { ERROR_TYPES } = require('../utils/error-types');
+const { skipInNonExecutableProcess } = require('../utils/rule');
+const { annotateRule } = require('../helper');
+
+/**
+ * Validates the parts of fromAi() calls that have no legitimate reading: the
+ * call silently resolves to nothing at runtime, with no error, and there is
+ * no plausible intent behind the violation. Covers wrong key type (including
+ * a conditional/if-expression key), missing/misplaced toolCall. prefix,
+ * multi-segment keys, duplicate keys within one tool, function name casing,
+ * a description argument that is not a string literal, and using fromAi()
+ * where the connector never populates toolCall (non-entry elements, output
+ * mappings, sequence flow conditions, non-agentic or non-AHSP contexts).
+ * Reports once per violation.
+ *
+ * Both the key and description arguments are parsed to FEEL AST nodes at
+ * tool-schema resolution time, from the deployed process definition, not
+ * evaluated against a process instance's variables (confirmed against
+ * FromAiTaggedParameterExtractor in camunda/camunda: `parameterName()`
+ * requires a `Ref` node and `asString()` requires a `ConstString` node,
+ * throwing otherwise; `throwsExceptionWhenValueIsNotAReference` in that
+ * repo's test suite confirms this for every non-reference shape it exercises,
+ * including a nested function call). A conditional key can never resolve
+ * this way, regardless of which branch would be "correct" at runtime, so it
+ * has no more legitimate reading than a bare number or null literal used as
+ * the key or description.
+ *
+ * A description that is simply absent (no argument, or an empty string) is
+ * valid: the fromAi() description is optional, so neither rule reports it.
+ */
+// ─── Constraint validators ────────────────────────────────────────────────────
+
+function validateKeyArg(arg) {
+  switch (arg.type) {
+  case 'StringLiteral':
+    return {
+      message: `fromAi() key must be a FEEL path, not a string literal. Remove the quotes around ${arg.text}.`,
+      data: { type: ERROR_TYPES.AGENT_FEEL_KEY_TYPE_INVALID },
+    };
+  case 'null':
+    return {
+      message: 'fromAi() key must be a FEEL path starting with "toolCall.", not null.',
+      data: { type: ERROR_TYPES.AGENT_FEEL_KEY_TYPE_INVALID },
+    };
+  case 'NumericLiteral':
+    return {
+      message: 'fromAi() key must be a FEEL path starting with "toolCall.", not a number.',
+      data: { type: ERROR_TYPES.AGENT_FEEL_KEY_TYPE_INVALID },
+    };
+  case 'ArithmeticExpression':
+    return {
+      message: 'fromAi() key must be a FEEL path starting with "toolCall.", not an arithmetic expression.',
+      data: { type: ERROR_TYPES.AGENT_FEEL_KEY_TYPE_INVALID },
+    };
+  case 'FilterExpression':
+    return {
+      message: 'fromAi() key must use dot notation, not bracket notation. Use toolCall.name instead of toolCall["name"].',
+      data: { type: ERROR_TYPES.AGENT_FEEL_KEY_TYPE_INVALID },
+    };
+  case 'VariableName':
+    return {
+      message: `fromAi() key must start with "toolCall.". Use toolCall.${arg.text} instead of a bare name.`,
+      data: { type: ERROR_TYPES.AGENT_FEEL_KEY_PREFIX_MISSING },
+    };
+  case 'PathExpression': {
+    if (!arg.text.startsWith('toolCall.')) {
+      return {
+        message: `fromAi() key must start with "toolCall.". Got ${arg.text}.`,
+        data: { type: ERROR_TYPES.AGENT_FEEL_KEY_PREFIX_MISSING },
+      };
+    }
+
+    // The connector uses the LAST path segment as the parameter name, so a
+    // nested key like toolCall.input.filter reads a path it never populates.
+    const segments = arg.text.split('.');
+    if (segments.length > 2) {
+      return {
+        message: `fromAi() key must be a single name under toolCall. Use toolCall.${ segments[ segments.length - 1 ] } instead of ${ arg.text }.`,
+        data: { type: ERROR_TYPES.AGENT_FEEL_KEY_SEGMENTS_INVALID },
+      };
+    }
+    return null;
+  }
+  case 'IfExpression':
+    return {
+      message: 'fromAi() key must be a FEEL path starting with "toolCall.", not a conditional expression. The connector requires a plain reference regardless of which branch would apply at runtime.',
+      data: { type: ERROR_TYPES.AGENT_FEEL_KEY_TYPE_INVALID },
+    };
+  default:
+    return {
+      message: `fromAi() key must be a FEEL path starting with "toolCall.", not a ${arg.type}.`,
+      data: { type: ERROR_TYPES.AGENT_FEEL_KEY_TYPE_INVALID },
+    };
+  }
+}
+
+/**
+ * Any non-string-literal description (a bare number, null, a variable
+ * reference, or any other expression) has no legitimate reading: the
+ * connector requires a literal string to build the tool schema and throws
+ * otherwise, so there is no case where a non-literal description works.
+ */
+function validateDescriptionTypeInvalid(arg) {
+  if (arg.type !== 'StringLiteral') {
+    return {
+      message: 'fromAi() description must be a string literal: a quoted string describing what the agent should provide.',
+      data: { type: ERROR_TYPES.AGENT_FEEL_DESCRIPTION_TYPE_INVALID },
+    };
+  }
+  return null;
+}
+
+// ─── Rule ─────────────────────────────────────────────────────────────────────
+
+module.exports = skipInNonExecutableProcess(function(config = {}) {
+  const { version } = config;
+  function check(node, reporter) {
+    if (is(node, 'bpmn:Activity')) {
+      checkDuplicateKeys(node, reporter);
+      return;
+    }
+
+    if (is(node, 'zeebe:Output')) {
+      checkOutputSurface(node, reporter);
+      return;
+    }
+
+    if (is(node, 'bpmn:SequenceFlow')) {
+      checkConditionSurface(node, reporter);
+      return;
+    }
+
+    if (!is(node, 'zeebe:Input')) {
+      return;
+    }
+
+    const source = node.get('source');
+    if (!source || !source.startsWith('=')) {
+      return;
+    }
+
+    const expr = source.substring(1).trim();
+    const invocations = findFunctionInvocations(expr);
+    if (invocations.length === 0) {
+      return;
+    }
+
+    // Walk from zeebe:Input → zeebe:IoMapping → bpmn:ExtensionElements → task
+    const task = node.$parent && node.$parent.$parent && node.$parent.$parent.$parent;
+    if (!task || !is(task, 'bpmn:FlowNode')) {
+      return;
+    }
+
+    // Properties-panel entry for this input parameter, so clicking the report
+    // opens the right mapping (id convention: {elementId}-input-{index}-source).
+    const inputIndex = (node.$parent.get('inputParameters') || []).indexOf(node);
+    const propertiesPanel = {
+      entryIds: [ `${ task.get('id') }-input-${ inputIndex }-source` ]
+    };
+
+    const ahsp = findAncestorAdHocSubProcess(task);
+
+    if (!ahsp) {
+      reportErrors(task, reporter, invocations.map(() => ({
+        message: 'fromAi() should only be used inside an agentic sub-process.',
+        data: { type: ERROR_TYPES.AGENT_FEEL_WRONG_CONTEXT },
+        propertiesPanel,
+      })));
+      return;
+    }
+
+    if (!isAgenticAdHocSubProcess(ahsp, version)) {
+      const ahspLabel = ahsp.get('name') || ahsp.get('id');
+      reportErrors(task, reporter, invocations.map(() => ({
+        message: `The "${ahspLabel}" sub-process is not marked as agentic, so fromAi() has no effect. Add an Extension property "io.camunda.agenticai.toolContainer" with value "true" to "${ahspLabel}".`,
+        data: { type: ERROR_TYPES.AGENT_FEEL_WRONG_CONTEXT },
+        propertiesPanel,
+      })));
+      return;
+    }
+
+    // The connector resolves fromAi() only on the tool's entry element: the
+    // root node sitting DIRECTLY inside the AHSP. A call is ignored at runtime
+    // either when the element has an incoming flow (it is downstream of the
+    // root) or when it is nested below the AHSP (e.g. a task inside a
+    // sub-process tool, whose parent is the sub-process, not the AHSP).
+    const incoming = task.get('incoming') || [];
+    if (incoming.length > 0 || task.$parent !== ahsp) {
+      reportErrors(task, reporter, invocations.map(() => ({
+        message: 'fromAi() is ignored here: only the tool\'s entry element defines AI inputs. Define it there and read the toolCall variable directly.',
+        data: { type: ERROR_TYPES.AGENT_FEEL_NON_ENTRY_ELEMENT },
+        propertiesPanel,
+      })));
+      return;
+    }
+
+    // Inside agentic AHSP, on the entry element: run structural checks.
+    const errors = [];
+
+    for (const inv of invocations) {
+
+      // Check for casing typo in function name.
+      if (inv.name !== CORRECT_NAME && NAME_ALIASES.includes(inv.name.toLowerCase())) {
+        errors.push({
+          message: `Wrong function name "${inv.name}". Use ${CORRECT_NAME} (case-sensitive).`,
+          data: { type: ERROR_TYPES.AGENT_FEEL_FUNCTION_NAME_INVALID },
+        });
+        continue;
+      }
+
+      const args = getPositionalArgs(inv.node, expr);
+
+      if (args.length === 0) {
+        errors.push({
+          message: 'fromAi() requires a key argument: a FEEL path like toolCall.url.',
+          data: { type: ERROR_TYPES.AGENT_FEEL_KEY_MISSING },
+        });
+        continue;
+      }
+
+      const keyError = validateKeyArg(args[0]);
+      if (keyError) {
+        errors.push(keyError);
+      }
+
+      if (args.length >= 2) {
+        const descriptionError = validateDescriptionTypeInvalid(args[1]);
+        if (descriptionError) {
+          errors.push(descriptionError);
+        }
+      }
+    }
+
+    if (errors.length) {
+      reportErrors(task, reporter, errors.map(error => ({ ...error, propertiesPanel })));
+    }
+  }
+
+  return annotateRule('agent-fromai-contract', {
+    check
+  });
+
+  /**
+   * The connector combines all fromAi() definitions of the tool's entry
+   * element into one input schema, so a key declared twice collides. Reports
+   * once per duplicated key on the entry activity.
+   */
+  function checkDuplicateKeys(task, reporter) {
+    const incoming = task.get('incoming') || [];
+    if (incoming.length > 0) {
+      return;
+    }
+
+    const ahsp = findAncestorAdHocSubProcess(task);
+    if (!ahsp || !isAgenticAdHocSubProcess(ahsp, version)) {
+      return;
+    }
+
+    // Only the tool's entry element (directly inside the AHSP) defines inputs;
+    // a nested task's fromAi() is ignored at runtime, so its keys are moot and
+    // the main check already reports it as a non-entry call.
+    if (task.$parent !== ahsp) {
+      return;
+    }
+
+    const ioMapping = findExtensionElement(task, 'zeebe:IoMapping');
+    if (!ioMapping) {
+      return;
+    }
+
+    const keyCounts = {};
+
+    for (const input of ioMapping.get('inputParameters') || []) {
+      const source = input.get('source');
+      if (!source || !source.startsWith('=')) {
+        continue;
+      }
+
+      const expr = source.substring(1).trim();
+      for (const inv of findFunctionInvocations(expr)) {
+        const args = getPositionalArgs(inv.node, expr);
+        const key = args[ 0 ];
+        if (key && key.type === 'PathExpression' && key.text.startsWith('toolCall.')) {
+          keyCounts[ key.text ] = (keyCounts[ key.text ] || 0) + 1;
+        }
+      }
+    }
+
+    const duplicates = Object.keys(keyCounts).filter(key => keyCounts[ key ] > 1);
+
+    if (duplicates.length) {
+      reportErrors(task, reporter, duplicates.map(key => ({
+        message: `fromAi() key ${ key } is declared more than once in this tool. Declare it once and reference it directly elsewhere.`,
+        data: { type: ERROR_TYPES.AGENT_FEEL_KEY_DUPLICATE },
+        propertiesPanel: { entryIds: [ 'inputs' ] },
+      })));
+    }
+  }
+
+  /**
+   * fromAi() only defines tool inputs; the connector reads it from input
+   * mappings and never populates toolCall on the output side, so a fromAi()
+   * call in an output source silently resolves to null. Scoped to agentic
+   * ad-hoc sub-processes to avoid firing on unrelated diagrams.
+   */
+  function checkOutputSurface(node, reporter) {
+    const source = node.get('source');
+    if (!source || !source.startsWith('=')) {
+      return;
+    }
+
+    const expr = source.substring(1).trim();
+    const invocations = findFunctionInvocations(expr);
+    if (!invocations.length) {
+      return;
+    }
+
+    const task = node.$parent && node.$parent.$parent && node.$parent.$parent.$parent;
+    if (!task || !is(task, 'bpmn:FlowNode')) {
+      return;
+    }
+
+    const ahsp = findAncestorAdHocSubProcess(task);
+    if (!ahsp || !isAgenticAdHocSubProcess(ahsp, version)) {
+      return;
+    }
+
+    const outputIndex = (node.$parent.get('outputParameters') || []).indexOf(node);
+    const propertiesPanel = {
+      entryIds: [ `${ task.get('id') }-output-${ outputIndex }-source` ]
+    };
+
+    reportErrors(task, reporter, invocations.map(() => ({
+      message: 'fromAi() defines a tool input and has no effect in an output mapping. Define it in an input mapping on the tool\'s entry element.',
+      data: { type: ERROR_TYPES.AGENT_FEEL_WRONG_CONTEXT },
+      propertiesPanel,
+    })));
+  }
+
+  /**
+   * The toolCall context is only populated for a tool's inputs, so fromAi() in
+   * a sequence flow condition resolves to null and the branch never behaves as
+   * intended. Scoped to agentic ad-hoc sub-processes.
+   */
+  function checkConditionSurface(node, reporter) {
+    const condition = node.get('conditionExpression');
+    const body = condition && condition.get('body');
+    if (!body || !body.startsWith('=')) {
+      return;
+    }
+
+    const expr = body.substring(1).trim();
+    const invocations = findFunctionInvocations(expr);
+    if (!invocations.length) {
+      return;
+    }
+
+    const ahsp = findAncestorAdHocSubProcess(node);
+    if (!ahsp || !isAgenticAdHocSubProcess(ahsp, version)) {
+      return;
+    }
+
+    reportErrors(node, reporter, invocations.map(() => ({
+      message: 'fromAi() defines a tool input and cannot be used in a sequence flow condition. Define it in an input mapping on the tool\'s entry element.',
+      data: { type: ERROR_TYPES.AGENT_FEEL_WRONG_CONTEXT },
+      propertiesPanel: { entryIds: [ 'conditionExpression' ] },
+    })));
+  }
+});

package/rules/camunda-cloud/agent-tool-documentation.js

@@ -0,0 +1,41 @@
+const { isAgenticToolElement } = require('../utils/element');
+const { reportErrors } = require('../utils/reporter');
+const { ERROR_TYPES } = require('../utils/error-types');
+const { skipInNonExecutableProcess } = require('../utils/rule');
+const { annotateRule } = require('../helper');
+
+/**
+ * The AI agent reads a tool's element documentation to decide which tool to
+ * call; without it the LLM falls back to the element name, which is
+ * underspecified. This rule warns when a tool entry activity (no incoming
+ * sequence flows, not an event sub-process) inside an agentic ad-hoc
+ * sub-process has no documentation text.
+ */
+module.exports = skipInNonExecutableProcess(function(config = {}) {
+  const { version } = config;
+  function check(node, reporter) {
+
+    // Only a tool (a root activity directly inside an agentic AHSP) needs
+    // documentation; steps nested inside a tool are not separate tools.
+    if (!isAgenticToolElement(node, version)) {
+      return;
+    }
+
+    const docs = node.get('documentation') || [];
+    const text = docs.map(d => d.get('text') || '').join('').trim();
+
+    if (!text) {
+      reportErrors(node, reporter, [
+        {
+          message: 'Tool documentation is missing.',
+          data: { type: ERROR_TYPES.AGENT_TOOL_DOCUMENTATION_MISSING },
+          propertiesPanel: { entryIds: [ 'documentation' ] },
+        },
+      ]);
+    }
+  }
+
+  return annotateRule('agent-tool-documentation', {
+    check
+  });
+});

package/rules/camunda-cloud/agent-tool-output-key.js

@@ -0,0 +1,279 @@
+const { is } = require('bpmnlint-utils');
+
+const { isAgenticToolElement } = require('../utils/element');
+const { reportErrors, getName } = require('../utils/reporter');
+const { ERROR_TYPES } = require('../utils/error-types');
+const { skipInNonExecutableProcess } = require('../utils/rule');
+const { annotateRule } = require('../helper');
+
+/**
+ * A tool inside an agentic ad-hoc sub-process returns its result through the
+ * `toolCallResult` variable. The result can be set at any point in the tool's
+ * flow and through several channels: an output mapping (target `toolCallResult`
+ * or a part like `toolCallResult.statusCode`), a script task or called decision
+ * `resultVariable`, or a connector `resultVariable`/`resultExpression` header.
+ *
+ * The rule warns once per tool: on the element that actually miswrote a
+ * result-shaped variable, when the tool flow writes some but none of them is
+ * `toolCallResult` (misdirection or wrong casing); on the entry activity when
+ * the flow writes none at all, since there's no single offending element to
+ * point to (the agent gets no completion signal and may retry or hallucinate
+ * an outcome). Results written from arbitrary FEEL expressions are not
+ * statically detectable.
+ */
+module.exports = skipInNonExecutableProcess(function(config = {}) {
+  const { version } = config;
+  function check(node, reporter) {
+
+    // Only a tool entry (a root activity directly inside an agentic AHSP) is a
+    // tool; the whole tool flow is then inspected from here. Elements nested
+    // inside a tool are not separate tools, so they are not entry points.
+    if (!isAgenticToolElement(node, version)) {
+      return;
+    }
+
+    const { channels, linear } = collectResultChannels(node);
+
+    if (!channels.length) {
+      reportErrors(node, reporter, {
+        message: 'Tool returns nothing to the agent. Set a "toolCallResult" (at minimum, note the task completed).',
+        data: { type: ERROR_TYPES.AGENT_TOOL_RESULT_MISSING },
+        propertiesPanel: { entryIds: [ 'outputs' ] },
+      });
+      return;
+    }
+
+    const hasResult = channels.some(isToolCallResultChannel);
+    if (!hasResult) {
+      const casingMismatch = channels.find(isToolCallResultCasingMismatch);
+
+      if (casingMismatch) {
+        reportErrors(casingMismatch.element, reporter, {
+          message: `Wrong casing "${getCasingMismatchText(casingMismatch)}": use toolCallResult (case-sensitive).`,
+          data: { type: ERROR_TYPES.AGENT_TOOL_OUTPUT_KEY_CASING_INVALID },
+          propertiesPanel: { entryIds: [ 'outputs' ] },
+        });
+        return;
+      }
+
+      // Every channel here is a miswrite (none matched toolCallResult), so
+      // the first one is a real misdirected write; report on the element
+      // that actually wrote it, not the tool's entry.
+      const misdirected = channels[ 0 ];
+      reportErrors(misdirected.element, reporter, {
+        message: '"toolCallResult" output is not mapped.',
+        data: { type: ERROR_TYPES.AGENT_TOOL_OUTPUT_KEY_INVALID },
+        propertiesPanel: { entryIds: [ 'outputs' ] },
+      });
+      return;
+    }
+
+    // toolCallResult is set somewhere, but assigning it more than once
+    // overwrites the earlier value. Part contributions (toolCallResult.part)
+    // and the context put(toolCallResult, ...) accumulation pattern are
+    // exempt; every other full write after the first one is flagged.
+    //
+    // Only flag overwrites on a strictly linear tool flow, where the writes
+    // are guaranteed to run one after another. If the flow branches (an
+    // exclusive/parallel split, a join, or a boundary event), two writes may
+    // sit on alternative paths that never both run in one execution, so
+    // flagging them would be a false positive. We conservatively suppress the
+    // check for any non-linear flow.
+    //
+    // Future improvement: instead of suppressing, walk backward from the
+    // flow's leaf nodes and reason about which writes can actually co-execute.
+    // That has to account for inclusive-OR splits and other BPMN
+    // diverge/converge shapes: the common inner-orchestration case is one
+    // entry with multiple leaf nodes, so naive flattening over-reports.
+    if (linear) {
+      const fullWrites = channels.filter(isToolCallResultChannel).filter(isFullOverwriteChannel);
+
+      for (let i = 1; i < fullWrites.length; i++) {
+        const overwriter = fullWrites[ i ];
+        const overwritten = fullWrites[ i - 1 ];
+        const overwrittenLabel = getName(overwritten.element) || overwritten.element.get('id');
+
+        reportErrors(overwriter.element, reporter, {
+          message: `This overwrites the "toolCallResult" value set on "${overwrittenLabel}".`,
+          data: { type: ERROR_TYPES.AGENT_TOOL_OUTPUT_KEY_OVERWRITE },
+          propertiesPanel: { entryIds: [ 'outputs' ] },
+        });
+      }
+    }
+  }
+
+  return annotateRule('agent-tool-output-key', {
+    check
+  });
+});
+
+/**
+ * Collect all result-channel writes across the tool flow: the entry element,
+ * everything reachable through outgoing sequence flows, and the contents of
+ * embedded sub-processes.
+ *
+ * Also reports whether the flow is strictly linear: a single chain with no
+ * branching. A flow is non-linear if any traversed element splits (more than
+ * one outgoing sequence flow), joins (more than one incoming), or has a
+ * boundary event attached. Non-linear flows can place two writes on
+ * alternative paths, so the caller uses this to avoid false overwrite reports.
+ *
+ * @param {ModdleElement} entry
+ *
+ * @returns {Object} { channels, linear } — channels as { kind, value, element }
+ * (element being whichever element in the flow actually wrote this channel),
+ * and linear being true when the flow is a single non-branching chain
+ */
+function collectResultChannels(entry) {
+  const channels = [],
+        visited = new Set(),
+        queue = [ entry ];
+
+  let linear = true;
+
+  while (queue.length) {
+    const element = queue.shift();
+
+    const id = element.get('id');
+    if (id && visited.has(id)) {
+      continue;
+    }
+    visited.add(id);
+
+    collectElementChannels(element, channels);
+
+    const outgoing = element.get('outgoing') || [];
+    const incoming = element.get('incoming') || [];
+
+    // A split (>1 outgoing) or a join (>1 incoming) means the flow is not a
+    // single guaranteed-sequential chain, so writes may live on paths that
+    // never both run.
+    if (outgoing.length > 1 || incoming.length > 1) {
+      linear = false;
+    }
+
+    for (const flow of outgoing) {
+      const target = flow.get('targetRef');
+      if (target) {
+        queue.push(target);
+      }
+    }
+
+    // Boundary events can define alternate tool paths that still contribute
+    // outputs; an alternate path is a branch, so the flow is not linear.
+    const parent = element.$parent;
+    const siblings = parent && parent.get && parent.get('flowElements');
+    for (const boundary of siblings || []) {
+      if (is(boundary, 'bpmn:BoundaryEvent') && boundary.get('attachedToRef') === element) {
+        linear = false;
+        queue.push(boundary);
+      }
+    }
+
+    if (is(element, 'bpmn:SubProcess')) {
+      for (const child of element.get('flowElements') || []) {
+        if (is(child, 'bpmn:FlowNode')) {
+          queue.push(child);
+        }
+      }
+    }
+  }
+
+  return { channels, linear };
+}
+
+function collectElementChannels(element, channels) {
+  const extensionElements = element.get('extensionElements');
+  if (!extensionElements) {
+    return;
+  }
+
+  for (const value of extensionElements.get('values')) {
+    if (is(value, 'zeebe:IoMapping')) {
+      for (const output of value.get('outputParameters') || []) {
+        channels.push({ kind: 'output', value: output.get('target') || '', source: output.get('source'), element });
+      }
+    }
+
+    if (is(value, 'zeebe:Script') || is(value, 'zeebe:CalledDecision')) {
+      const resultVariable = value.get('resultVariable');
+      if (resultVariable) {
+        channels.push({ kind: 'resultVariable', value: resultVariable, element });
+      }
+    }
+
+    // resultVariable / resultExpression task headers are treated as output
+    // channels for ANY task, not only recognized connector tasks. This breadth
+    // is intentional: the goal is to capture every way a tool writes its
+    // output. resultVariable/resultExpression is the convention connectors use,
+    // but custom element templates can follow the same convention, so gating on
+    // connector-ness would miss those and let a real miswrite through.
+    if (is(value, 'zeebe:TaskHeaders')) {
+      for (const header of value.get('values') || []) {
+        const key = header.get('key');
+        if (key === 'resultVariable') {
+          channels.push({ kind: 'resultVariable', value: header.get('value') || '', element });
+        }
+        if (key === 'resultExpression') {
+          channels.push({ kind: 'resultExpression', value: header.get('value') || '', element });
+        }
+      }
+    }
+  }
+}
+
+function isToolCallResultChannel({ kind, value }) {
+  if (kind === 'resultExpression') {
+    return /\btoolCallResult\b/.test(value);
+  }
+
+  return value === 'toolCallResult' || value.startsWith('toolCallResult.');
+}
+
+// A same-letters, wrong-case variant of toolCallResult (e.g. toolcallresult,
+// TOOLCALLRESULT), not any other typo. Mirrors agent-fromai-contract's
+// case-insensitive name matching for fromAi().
+function isToolCallResultCasingMismatch({ kind, value }) {
+  if (kind === 'resultExpression') {
+    return /\btoolcallresult\b/i.test(value) && !/\btoolCallResult\b/.test(value);
+  }
+
+  const lower = value.toLowerCase();
+  const isCasingVariant = lower === 'toolcallresult' || lower.startsWith('toolcallresult.');
+
+  return isCasingVariant && !isToolCallResultChannel({ kind, value });
+}
+
+// The mismatched word itself, not the whole expression, for resultExpression
+// channels (a connector header value is a full FEEL expression, e.g.
+// `={toolcallresult: response.body}`).
+function getCasingMismatchText({ kind, value }) {
+  if (kind === 'resultExpression') {
+    const match = value.match(/\btoolcallresult\b/i);
+    return match ? match[0] : value;
+  }
+
+  return value;
+}
+
+// The documented safe-accumulation pattern for combining several elements'
+// contributions into one toolCallResult: `context put(toolCallResult, ...)`.
+// Only meaningful for output mappings; connectors and script/decision result
+// variables can't read the prior value, so they can never accumulate this way.
+const CONTEXT_PUT_TOOL_CALL_RESULT = /^=?\s*context\s+put\s*\(\s*toolCallResult\s*,/;
+
+// Whether this channel fully replaces toolCallResult, as opposed to
+// contributing one field (toolCallResult.part) or safely appending to the
+// existing value via context put(). Only meaningful for channels that
+// already passed isToolCallResultChannel.
+function isFullOverwriteChannel({ kind, value, source }) {
+  if (kind === 'resultExpression' || kind === 'resultVariable') {
+    return true;
+  }
+
+  if (value !== 'toolCallResult') {
+    return false;
+  }
+
+  return !CONTEXT_PUT_TOOL_CALL_RESULT.test(source || '');
+}

package/rules/camunda-cloud/utils/feel.js

@@ -1,5 +1,7 @@
 const { isString } = require('min-dash');
 
+const { parser } = require('@bpmn-io/lezer-feel');
+
 // Properties ignored globally
 const IGNORED_PROPERTIES = [
   'name'
@@ -30,6 +32,60 @@ const isFeelProperty = (node, propertyName, value) => {
   return !isIgnoredProperty(node, propertyName) && isString(value) && value.startsWith('=');
 };
 
+// ─── fromAi() lezer helpers ─────────────────────────────────────────────────
+// Used by agent-fromai-contract to locate fromAi() calls and read their
+// positional arguments.
+
+const CORRECT_NAME = 'fromAi';
+const NAME_ALIASES = [ 'fromai', 'fromAI' ];
+
+function findFunctionInvocations(expr) {
+  const tree = parser.parse(expr);
+  const result = [];
+
+  function visit(node) {
+    if (node.type.name === 'FunctionInvocation') {
+      const nameNode = node.firstChild;
+      if (nameNode && nameNode.type.name === 'VariableName') {
+        const name = expr.slice(nameNode.from, nameNode.to);
+        const nameLower = name.toLowerCase();
+        if (nameLower === CORRECT_NAME.toLowerCase()) {
+          result.push({ name, node });
+        }
+      }
+    }
+    let child = node.firstChild;
+    while (child) {
+      visit(child);
+      child = child.nextSibling;
+    }
+  }
+
+  visit(tree.topNode);
+  return result;
+}
+
+function getPositionalArgs(invocationNode, expr) {
+  let child = invocationNode.firstChild;
+  while (child) {
+    if (child.type.name === 'PositionalParameters') {
+      const args = [];
+      let arg = child.firstChild;
+      while (arg) {
+        args.push({ type: arg.type.name, text: expr.slice(arg.from, arg.to) });
+        arg = arg.nextSibling;
+      }
+      return args;
+    }
+    child = child.nextSibling;
+  }
+  return [];
+}
+
 module.exports = {
-  isFeelProperty
+  isFeelProperty,
+  CORRECT_NAME,
+  NAME_ALIASES,
+  findFunctionInvocations,
+  getPositionalArgs
 };

package/rules/utils/element.js

@@ -20,6 +20,8 @@ const { getPath } = require('@bpmn-io/moddle-utils');
 
 const { ERROR_TYPES } = require('./error-types');
 
+const { greaterOrEqual } = require('./version');
+
 module.exports.ERROR_TYPES = ERROR_TYPES;
 
 function getEventDefinition(node) {
@@ -505,6 +507,93 @@ function addAllowedVersion(data, allowedVersion) {
   };
 }
 
+function findAncestorAdHocSubProcess(node) {
+  let el = node.$parent;
+  while (el) {
+    if (is(el, 'bpmn:AdHocSubProcess')) return el;
+    el = el.$parent;
+  }
+  return null;
+}
+
+module.exports.findAncestorAdHocSubProcess = findAncestorAdHocSubProcess;
+
+// Property-based agentic detection (solution 1, marker shape revised
+// 2026-07-13). The AI Agent element templates (and external-agent templates,
+// e.g. Bedrock, Hugging Face) apply a generic zeebe:property to mark a
+// detached tools ad-hoc sub-process as a tool container to lint. This is
+// read-only and has no execution effect; it parses on the current moddle with
+// no schema change. The marker is an independent boolean, not a single-valued
+// role enum, because a Camunda agent element can carry both the
+// `toolContainer` role (hosts tools) and the `agent` role at once; a
+// single-valued `io.camunda.agenticai.role` property could not represent
+// both roles on the same element.
+const TOOL_CONTAINER_PROPERTY = 'io.camunda.agenticai.toolContainer';
+
+function hasToolContainerRoleProperty(node) {
+  const properties = findExtensionElement(node, 'zeebe:Properties');
+
+  if (!properties) {
+    return false;
+  }
+
+  return (properties.get('properties') || []).some(
+    property => property.get('name') === TOOL_CONTAINER_PROPERTY
+      && property.get('value') === 'true'
+  );
+}
+
+module.exports.hasToolContainerRoleProperty = hasToolContainerRoleProperty;
+
+// Whether an ad-hoc sub-process should have agent tool contracts linted.
+//
+// The `io.camunda.agenticai.toolContainer=true` property marker is honored at
+// every version. From 8.10, a `zeebe:agentDefinition` marker on the AHSP
+// (Camunda-provided template) is an additional signal, tracked in
+// connectors#7842; that marker doesn't exist in this plugin's pinned
+// zeebe-bpmn-moddle yet, so the check below is inert until it ships.
+//
+// Deliberately does not fall back to a bare `zeebe:AdHoc` extension: that
+// extension is also carried by plain ad-hoc sub-processes using output
+// collection, so it can't reliably distinguish agentic from non-agentic ones.
+function isAgenticAdHocSubProcess(ahsp, version) {
+  if (hasToolContainerRoleProperty(ahsp)) {
+    return true;
+  }
+
+  return !!version
+    && greaterOrEqual(version, '8.10')
+    && !!findExtensionElement(ahsp, 'zeebe:AgentDefinition');
+}
+
+module.exports.isAgenticAdHocSubProcess = isAgenticAdHocSubProcess;
+
+// Whether a node is an agent tool, i.e. the root node of a tool sub-flow that
+// sits directly inside an agentic ad-hoc sub-process. This is the single "is
+// tool" contract every agent rule gates on, so lint scope matches how the
+// agent connector actually resolves tools: only at these roots. Anything
+// nested below a root (a step inside a sub-process tool, or a downstream
+// element reached by a sequence flow) is PART of a tool, not a tool itself.
+function isAgenticToolElement(node, version) {
+
+  // a tool is an activity (task or sub-process)
+  return is(node, 'bpmn:Activity')
+
+    // an event sub-process is not a tool
+    && !(is(node, 'bpmn:SubProcess') && node.get('triggeredByEvent'))
+
+    // tool root: nothing flows into it
+    && (node.get('incoming') || []).length === 0
+
+    // it must live DIRECTLY in the AHSP, not nested
+    && is(node.$parent, 'bpmn:AdHocSubProcess')
+
+    // and that AHSP must be an agent tool container
+    && isAgenticAdHocSubProcess(node.$parent, version);
+}
+
+module.exports.isAgenticToolElement = isAgenticToolElement;
+
 function findParent(node, type) {
   if (!node) {
     return null;

package/rules/utils/error-types.js

@@ -25,5 +25,19 @@ module.exports.ERROR_TYPES = Object.freeze({
   PROPERTY_VALUES_DUPLICATED: 'camunda.propertiesValuesDuplicated',
   PROPERTY_VALUE_NOT_ALLOWED: 'camunda.propertyValueNotAllowed',
   PROPERTY_VALUE_REQUIRED: 'camunda.propertyValueRequired',
-  SECRET_EXPRESSION_FORMAT_DEPRECATED: 'camunda.secretExpressionFormatDeprecated'
-});
+  SECRET_EXPRESSION_FORMAT_DEPRECATED: 'camunda.secretExpressionFormatDeprecated',
+  AGENT_FEEL_FUNCTION_NAME_INVALID: 'camunda.agentFeelFunctionNameInvalid',
+  AGENT_FEEL_KEY_MISSING: 'camunda.agentFeelKeyMissing',
+  AGENT_FEEL_KEY_TYPE_INVALID: 'camunda.agentFeelKeyTypeInvalid',
+  AGENT_FEEL_KEY_PREFIX_MISSING: 'camunda.agentFeelKeyPrefixMissing',
+  AGENT_FEEL_DESCRIPTION_TYPE_INVALID: 'camunda.agentFeelDescriptionTypeInvalid',
+  AGENT_FEEL_WRONG_CONTEXT: 'camunda.agentFeelWrongContext',
+  AGENT_FEEL_KEY_SEGMENTS_INVALID: 'camunda.agentFeelKeySegmentsInvalid',
+  AGENT_FEEL_KEY_DUPLICATE: 'camunda.agentFeelKeyDuplicate',
+  AGENT_FEEL_NON_ENTRY_ELEMENT: 'camunda.agentFeelNonEntryElement',
+  AGENT_TOOL_OUTPUT_KEY_INVALID: 'camunda.agentToolOutputKeyInvalid',
+  AGENT_TOOL_OUTPUT_KEY_CASING_INVALID: 'camunda.agentToolOutputKeyCasingInvalid',
+  AGENT_TOOL_OUTPUT_KEY_OVERWRITE: 'camunda.agentToolOutputKeyOverwrite',
+  AGENT_TOOL_RESULT_MISSING: 'camunda.agentToolResultMissing',
+  AGENT_TOOL_DOCUMENTATION_MISSING: 'camunda.agentToolDocumentationMissing',
+});