Skip to content

Let a worker edit its own boot prompt

CLIAPIIntermediate~20 min

Your worker can fix its own boot prompt without you giving it write access. You tell it what to change. It asks you to sign a one-edit grant and hands you a link. You open the link and approve with your passkey, the worker makes the single edit, and then the result is compiled and approved: by you, or by the worker under a second grant you sign. Nothing is served until it is approved.

The worker does its half with the hadron CLI, so this task needs a terminal on the worker's side. Your half is a link, a passkey and an approval; you do not need to type a command for the signing. It needs CLI 0.42.0 or later and a server where signing is switched on (see What you need).

This page calls the grant the signed grant, because a person's signature is what makes it work. It is a different thing from the organization role grant (hadron grant create), an App's own grants such as workers.staff and app.members, a connection grant, and the Agent organization grant behind BOOT_PROMPT_GRANT_REQUIRED. For how grants are created and ended in general, see App grants.

A holder's instruction on its own never admits a boot-prompt edit. An instruction opens other doors; for this one, only a signed grant does.

What you need

  • Signing switched on. The flow exists only where the server's GET /capabilities lists the grant-signing token (see Server capabilities). Without it the CLI answers that the server "does not offer grant requests and grant signing" and exits 2. Whether a deployment has it is the deployment's setting.
  • A passkey registered for the person who signs.
  • The right person to sign. Someone who manages the App. For the role Agent's own system-memory source, someone who also manages the Agent. The signer is checked again when the edit is made, not only when they sign.
  • A worker bound in its worktree, in its own App, driven by a person (hadron team session start). The grant request refuses any other caller.

1. The worker asks for the grant

The worker names the one source node it may edit, by id, and asks for the bootprompt.source.edit action:

hadron team grant request \
  --action bootprompt.source.edit \
  --values '{"sourceNode":"<source-node-id>"}' \
  --reason 'fix a typo in my boot prompt'

The grant is pending and allows nothing yet. The values are ids, never URNs, and the reason (up to 2,000 characters) is shown to the signer as the worker's own words. A worker may edit only its own source: its boot:workers:<id>:source, or the role's boot:source in the App's install memory, or in the Agent's system memory.

Then it asks for a signature and prints the link:

hadron team grant request-signature <grant-id>

The output includes a ceremonyUrl. The worker hands it to you exactly as printed. Do not shorten or rewrite it.

2. You sign

Open the link the worker gave you. It is the server's grant-signing page, at a /grant-signing/… address. The page asks for your passkey first and then shows the terms: the action, the one node, the holder and the reason. Sign if they match what you asked for. Nothing the worker does can sign for you.

When you sign, the grant allows one edit within the hour that follows. A grant's expiresAt can only shorten that hour. The signing request has its own end states (COMPLETED, DECLINED, EXPIRED, STALE, WITHDRAWN); those describe the request, not the grant. The worker can check the request with hadron team grant signing-request get <request-id>.

3. The worker makes the edit

The worker changes the node's content, in place:

hadron node update <source-node-urn> --content-file new-prompt.md

From a bound worktree, node update is an authored write and carries the worker session on its own, so it needs no flag. Only the compile and approve commands in step 4 need --as-worker. This is the only edit the grant allows. Any other field supplied alongside the content (name, abstract, description, tags, properties, data, edges), and every create, delete, move, merge, restore, import, clone, replace or role change, stays refused. One grant is one edit: for the next change, the worker asks for a new grant.

4. Compile and approve

The edit changes the source, not what is served. A new revision is served only after it is compiled and approved, so either you or the worker finishes:

Which command compiles depends on which source was edited:

The edited source Compile with
The worker's own, boot:workers:<id>:source hadron team worker compile <worker>
The role's, boot:source in the App's install memory hadron app agent compile <app> <agent>
The role Agent's, boot:source in its system memory hadron agent compile <agent>

Each takes --as-worker for the worker's path below. A compile that names the wrong source compiles a different one, or is refused BOOT_PROMPT_NO_SOURCE.

You do it. As a manager, compile and approve as yourself. For a worker's own source:

hadron team worker compile <worker>
hadron node approve <compiled-node-ref> --revision <reviewed-revision>

Read the compiled node first and approve the revision you read. See Compile a boot prompt and Set up an AI team.

The worker does it, under a second signed grant. This is the batch grant: the signed grant for the bootprompt.compile.approve action. The worker asks for it, naming the compiled prompts it may handle, and you sign it the same way as above:

hadron team grant request \
  --action bootprompt.compile.approve \
  --values '{"compiledNode":["<compiled-node-id>"]}' \
  --reason 'compile and approve my prompt after the edit'

With that grant, the worker adds --as-worker to the compile and approve commands:

hadron team worker compile <worker> --as-worker    # or the matching command above
hadron node approve <compiled-node-ref> --revision <revision> --as-worker

This second grant lasts an hour and covers any number of compiles and approvals of the prompts it names, which can be any compiled prompt of this App or its own role Agent's. It never signs, and a compile under it never creates a compiled node or sets a pointer. The approval is recorded as the worker acting under a batch grant. No person reads the compiled text at that approval. Your check is the signature on the grant, so read the node ids you are signing: they can name any compiled prompt of the App, not only the worker's own. Without --as-worker the CLI acts as you and never falls back to the worker.

If your organization signs compiled prompts

A compiled prompt is served only when it is approved and, where the serving App's organization has switched signing on (and the deployment ships signing), only when it is also signed. A batch grant never covers that signature. A person still signs each compiled prompt.

When something is refused

Each refusal is a code, and what it means is below. The wording of a message can lag the code, so go by the code.

Code What it means
BOOT_PROMPT_WORKER_SESSION_REFUSED A worker session's boot-prompt write has no usable grant. It is also what you get for a write that is not a content-only edit of its own existing source, a grant that is spent, past its hour or whose signer can no longer make the edit, and an approval with no batch grant.
BOOT_PROMPT_COMPILE_NOT_PERMITTED A worker session's compile has no batch grant covering that target.
BOOT_PROMPT_GRANT_REQUIRED An included Agent has no grant for the recipient. A batch compile that would create a compiled node, set a pointer or provision a grant gets it too.
GRANT_REQUESTER_NOT_WORKER, GRANT_HOLDER_NOT_ALLOWED The request did not come from a bound worker session, or names a holder it may not.
GRANT_ACTION_UNKNOWN, GRANT_VALUES_INVALID, GRANT_TERMS_INVALID The action, its values or the terms (including a reason over 2,000 characters) are not acceptable.

The CLI maps these to exit codes; see Grants a worker asks for.

What may change

These parts are built but not settled, and may change:

  • An edit is content only, narrower than the title, abstract and content the rule once named.
  • The role Agent's system-memory source, and who must sign for it.
  • The batch grant's terms and scope.
  • A batch compile needs the App's pointer to already name the compiled node.
  • The signer is checked again when the edit is made, and an edit by a worker whose signer no longer manages the App (or the Agent) is refused.

There is no MCP tool for asking for one of these grants; the worker uses the CLI.