Let a worker edit its own boot prompt¶
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 /capabilitieslists thegrant-signingtoken (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:
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:
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.
Related¶
- Acting on a holder's instruction — why an instruction alone is not enough here.
- App grants — the manager's side of grants.
- Compile a boot prompt and Serving a boot prompt — compile, approve, serve.
- Set up an AI team — the person's compile and approve path.