notices

Manage the notice keys that surface on your tool calls.

Notices are event records the engine and world content post so a side effect you did not trigger yourself — a component disabled on an awake error, an import that finished, a hot-reload that failed — reaches you on your next tool call. Each notice is addressed to an audience: the caller whose work raised it, a list of callers, or every caller. Every caller has its own read position, so you are shown each notice addressed to you once, and reading it removes nothing for anyone else. Most of the time you just read them. This toolbox is for the case where one key repeats and you have already acted on it: suppress mutes a key for you so it stops rendering, unsuppress brings it back, and list shows the notices addressed to you and what you have muted.

Each notice line you are shown ends with the notice's handle, eight hex digits after a #:

[info] Unpublished work in this world { commits="2" } #1a2b3c4d

Pass that handle to suppress as it is shown, # or not: tools.use("notices", "suppress", { key = "1a2b3c4d" }) in Luau, or zero notices suppress 1a2b3c4d in bash, where it goes without the # because bash reads an unquoted # as the start of a comment. unsuppress takes the same handle. list states each notice's handle beside its full key too, for a notice whose line you no longer have. A key you suppressed keeps counting while muted, so list also tells you how many times it fired at you after you silenced it. Your mute is your own — every other caller keeps receiving the key. A mute lasts until you unsuppress the key or its poster withdraws the notice because the condition it stated is over; a poster refreshing the notice with new values keeps it muted. On a world bound live it is kept in your user's store of the world and holds on the next engine that opens it; an engine booted offline keeps it for as long as it runs.

drain is for a caller that does not read notices off its tool results at all. It hands back your unread notices as the same delivery text a tool result would have carried, which is how a harness that composes its own context collects a notice posted while nothing was mid-call — the case a tool result cannot reach. If you read notices normally, you do not need it.

Notices are what the engine and the world tell you. To tell another agent or a person something yourself, message them with the messages toolbox.