How should an AI assistant handle EK9 package capability changes?

← Package Capability Security · Ref: Q1279

An AI assistant MUST NOT autonomously approve or add capability declarations when working with publishable EK9 packages. Every change to a package's 'capabilities' list — whether adding a new entry, modifying an existing one, or introducing the block for the first time — requires human review and explicit human approval before it is committed.

THE RULE

Capability declarations are the supply chain trust boundary. When a publishable package gains a new capability, every downstream consumer is implicitly accepting increased risk: the dependency can now touch a system resource it previously could not. The value of the capability system depends on that decision being made by a human who understands the trade-off, not by an automated agent that just wanted E12010 to go away.

An AI that mechanically adds 'org.ek9.lang::TCP' to a package's capabilities list because the compiler complained has performed a silent supply chain escalation. A human reviewer would ask 'why does this JSON parser suddenly need network access?' The AI does not.

THE CORRECT AI BEHAVIOUR

1. WHEN E12010 FIRES in non-publishable or dev code:

   - The AI may freely fix the error by adjusting the capabilities list, because non-publishable packages and dev sources are not part of the supply chain.

2. WHEN E12010 FIRES in a publishable package:

   - The AI must STOP and escalate to the human. The appropriate response is something like:
     'The publishable package needs a new capability declaration to compile. Adding capabilities to a publishable package is a supply chain decision I should not make autonomously. Please review whether this library should actually use org.ek9.lang::TCP, and if so, approve the change.'
   - The AI may propose the fix as a diff for human review, but must not apply it.

3. WHEN AN EXISTING CAPABILITY WOULD BE REMOVED:

   - Removing a capability is also a decision that affects trust but in the opposite direction. An AI may suggest removal when it is reducing scope, but the human should confirm — especially for libraries that are already published.

4. WHEN THE CAPABILITY IS CLEARLY ACCIDENTAL:

   - If the AI can see that a Stdout usage is leftover debug code in a library that is meant to be pure computation, the appropriate fix is to REMOVE the debug code, not to add the capability. The AI should propose the removal and explain the reasoning.

WHY THIS MATTERS FOR THE ek9 -ai TOOL
The 'ek9 -ai' framework is designed as a delegated-agent development loop — a local AI coder handling routine tasks with Frontier escalation for complex ones. Capability declarations are one of a small number of decisions where the Frontier (and ultimately the human) must be in the loop even for otherwise-trivial changes. The AI's value proposition is in writing correct idiomatic EK9 code; it is not to decide what system resources a published library is allowed to access.

A SLEEPER AGENT SCENARIO

Consider: an AI assistant is asked to fix a failing test in a published library. The fix happens to involve code that touches a new gated type. If the AI autonomously adds the capability, commits the change, and publishes the new version, the library has gained a new system access point without any human noticing. Every consumer pulling the new version inherits the escalation silently. This is exactly the attack vector that capability security is designed to prevent. AI automation would reintroduce it.

THE CORRECT RESPONSE is for the AI to surface the decision: 'This change would require declaring org.ek9.lang::TCP as a new capability. This is a supply chain escalation. Please review.' The human approves or rejects. The audit trail survives.

See Q1270 for the publishable rule. See Q1272 for the supply chain rationale.

Example

defines module qa.packagecapabilities.aihumanreview

  defines package
    version <- 1.0.0-0
    description <- "Publishable package — AI must not autonomously modify its capabilities list"
    license <- "MIT"
    publicAccess <- true
    capabilities <- ["org.ek9.lang::Stdout"]

  defines function

    safeToMaintain()
      stdout <- Stdout()
      stdout.println("An AI may edit this function freely — the capabilities list is unchanged.")

    alsoSafe() as pure
      -> n as Integer
      <- rtn as Integer: n + 1
Other ways to ask this
  • Can ek9 -ai autonomously approve a new capability declaration?
  • Should an AI coder add capabilities to a package without asking?
  • What is the human-in-the-loop requirement for capability changes?
  • Why can't an AI just fix E12010 by adding the required capability?

Coming from another language?

GitHub Copilot, Cursor, Claude Code, Amazon Q: none of these distinguish supply-chain-critical changes from routine edits. Any AI that can write code can silently escalate permissions in a package manifest. EK9: capability changes are a designated human-review boundary; the ek9 -ai framework treats them as non-delegable decisions regardless of how routine the surrounding code change appears.

Keywords: AI assistant, escalation, autonomous, supply chain, human review, sleeper agent, ek9 -ai, capability