arisa 5.1.2 → 5.1.8

package/AGENTS.md

@@ -76,7 +76,12 @@ const result = await arisa.tools.run({
 }, { timeoutMs: 120_000 });
 ```
 
-The IPC channel is a local socket under `~/.arisa/state`. Every request must include `toolName`; chat-scoped capabilities also require `chatId`. Exposed capabilities are explicit: tools (`list`, `help`, `skills`, `setConfig`, `run`), artifacts (`createText`, `listRecent`, `get`, `deliver`), tasks (`add`, `list`, `cancel`, `cancelAll`), agent events (`enqueueEvent`), and runtime paths (`getChatToolStateDir`, `getToolStateDir`, `getChatToolTmpDir`, `getToolTmpDir`, `getChatArtifactsDir`). Do not expose raw `agentManager`, `taskStore`, `artifactStore`, or `toolRegistry` access.
+The IPC channel is a local socket under `~/.arisa/state`. Every request must include `toolName`; chat-scoped capabilities also require `chatId`. Exposed capabilities are explicit: tools (`list`, `help`, `skills`, `setConfig`, `setResourceNote`, `getResourceNote`, `run`), artifacts (`createText`, `listRecent`, `get`, `deliver`), tasks (`add`, `list`, `cancel`, `cancelAll`), agent events (`enqueueEvent`), and runtime paths (`getChatToolStateDir`, `getToolStateDir`, `getChatToolTmpDir`, `getToolTmpDir`, `getChatArtifactsDir`). Do not expose raw `agentManager`, `taskStore`, `artifactStore`, or `toolRegistry` access.
+
+## Tool resource notes
+A tool resource may have one deterministic chat-scoped operational note of at most 200 characters, keyed by the exact pair `toolName:resourceId`. Notes live in the chat state file returned by `getChatToolResourceNotesFile(chatId)`. They are separate from semantic memory and contain no credentials.
+
+Use `set_tool_resource_note` to set or clear a note. Tool events must put the exact resource identifier in `task.source.resourceId` or pass `resourceId` to `agent.enqueueEvent`; Arisa injects the matching note into the prompt before reasoning. Tool executions may pass `resourceId` to `run_tool`, which injects the note as `request.resourceNote`. Never infer resource identifiers from free-form prompt text.
 
 ## Conceptual pipe model
 There are two different moments where pipes can happen:
@@ -188,9 +193,12 @@ Reason in terms of capabilities, not tool names. Do not stop at "I cannot do tha
 Before asking the user for recurrent context, inspect available tools by `category` and `keywords`, especially `memory`, `context`, `contacts`, and `essential`.
 
 When the user asks for something new:
-1. check whether an existing registered tool, or an indirect use of one, can satisfy the task
-2. check the official catalog at `https://github.com/clasen/Arisa/tree/main/tools` before building anything
-3. install from the catalog when it fits, or create a new tool only when the needed capability is truly missing
+1. call `list_tools` with a concise capability query; it searches registered tool names, descriptions, categories, keywords, inputs, and outputs, and automatically falls back to official catalog manifests when no installed tool matches
+2. call `tool_help` for every plausible installed match before concluding the capability is missing
+3. if the search returned no installed or official match, inspect the official catalog at `https://github.com/clasen/Arisa/tree/main/tools` before offering to build anything
+4. install from the catalog when it fits, or create a new tool only when the needed capability is truly missing
+
+Never offer to create or extend a tool after inspecting only a few familiar tool names. A negative capability claim requires both a complete registered-tool scan and an official-catalog scan. For example, a request to read X bookmarks must match the `bookmarks` keyword on `x-session-reader`, even if `x-reader` and `x-dm` do not expose that action.
 
 To evaluate the official catalog:
 1. List it: `curl -s https://api.github.com/repos/clasen/Arisa/contents/tools`.