Harness spec 1.2.0: the library's tools fit both projects; the CLI implements it

The CLI's facts in memory, notes_search, note_manage, skills_list,
skill_view and skill_manage are `variables` now, filled with the CLI's own
values (src/tool/spec-vars.ts): every description and parameter list the CLI
sends is word for word what 1.1.0 said, except note and document ids, which
are strings on both sides (a number is still taken). Descriptions are
filled by the prompt texts' rules, parameter descriptions too. `narrow`
says what a project offers of a shared tool's parameters. Memory's changes
are one pure function (applyOps). Conformance: fill, narrow, memory.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

harness/tools/knowledge_get.json

@@ -14,7 +14,7 @@
     "type": "object",
     "properties": {
       "id": {
-        "type": "integer"
+        "type": "string"
       },
       "offset": {
         "description": "Characters to skip: to read past what the first call returned",

harness/tools/memory.json

@@ -12,7 +12,14 @@
       "memory_forget"
     ]
   },
-  "description": "Save durable facts to persistent memory that survives across sessions. Memory goes into the system prompt of every future session, so keep entries short and worth their place.\n\nHOW: make all your changes in ONE call with an `operations` list ({action, content?, old_text?}). The list is applied together and the size limit is checked only on the result, so one call can remove or shorten stale entries AND add new ones. One call finishes the update; do not repeat it. Use the single action/content/old_text fields only for one lone change.\n\nWHEN: only for facts that hold in EVERY session, whatever the task: who the user is, stable facts about their machines and environment, standing conventions with no better home. How to do a kind of task — procedures, pitfalls, the user's corrections about that work — belongs in a skill (skill_manage), which loads only when relevant. Anything about this project belongs in its AGENTS.md or the project's decision log, not here.\n\nTARGETS: 'user' — who the user is: name, role, preferences, how they like to work. 'memory' — your own notes: environment, conventions, tool quirks, lessons.\n\nIF FULL: an add is refused and the current entries are shown. Send one call that removes or shortens enough stale entries and adds the new one.\n\nSKIP: the obvious, what is easy to find again, raw data, task progress, logs of finished work, temporary state (session_search finds past work).\n\nWhat you save now is in the files at once but appears in your system prompt only from the next session.",
+  "variables": {
+    "project_home": "where facts about the current project belong instead, as a sentence after the WHEN paragraph's last one (\" Anything about this project belongs in its AGENTS.md or the project's decision log, not here.\"), or empty",
+    "targets": "the targets this project offers and what each is for",
+    "past_work": "how past work is found again, in parentheses after the SKIP list (\" (session_search finds past work)\"), or empty",
+    "when_seen": "when a saved entry reaches the model's instructions",
+    "target_values": "the `target` parameter's values and what each holds"
+  },
+  "description": "Save durable facts to persistent memory that survives across sessions. Memory goes into the system prompt of every future session, so keep entries short and worth their place.\n\nHOW: make all your changes in ONE call with an `operations` list ({action, content?, old_text?}). The list is applied together and the size limit is checked only on the result, so one call can remove or shorten stale entries AND add new ones. One call finishes the update; do not repeat it. Use the single action/content/old_text fields only for one lone change.\n\nWHEN: only for facts that hold in EVERY session, whatever the task: who the user is, stable facts about their machines and environment, standing conventions with no better home. How to do a kind of task — procedures, pitfalls, the user's corrections about that work — belongs in a skill (skill_manage), which loads only when relevant.{{project_home}}\n\nTARGETS: {{targets}}\n\nIF FULL: an add is refused and the current entries are shown. Send one call that removes or shortens enough stale entries and adds the new one.\n\nSKIP: the obvious, what is easy to find again, raw data, task progress, logs of finished work, temporary state{{past_work}}.\n\n{{when_seen}}",
   "parameters": {
     "type": "object",
     "properties": {
@@ -23,7 +30,7 @@
           "user",
           "project"
         ],
-        "description": "'memory' for your notes, 'user' for the user profile, 'project' for facts about this project only (kept in its .agent/local, never committed)."
+        "description": "{{target_values}}"
       },
       "action": {
         "description": "A single change. Omit when using operations.",
@@ -82,5 +89,14 @@
     "required": [
       "target"
     ]
+  },
+  "narrow": {
+    "llembas": {
+      "enum": {
+        "target": [
+          "user"
+        ]
+      }
+    }
   }
 }

harness/tools/note_manage.json

@@ -15,7 +15,12 @@
       "notes_delete"
     ]
   },
-  "description": "Write your notes: things worth keeping that are longer than a memory entry and not a skill — findings, a design worked out with the user, a list to come back to.\n\n- create (title, body, scope); edit (id, title and/or body — body replaces the whole text); delete (id).\n- scope: \"project\" (default, when there is a project) or \"global\".\n- Not for facts that hold in every session (memory), procedures (skills), or the project's own records (tasks, decisions).",
+  "variables": {
+    "create_scope": "\", scope\" where notes have a scope, or empty",
+    "scope": "what `scope` means (\"scope: \\\"project\\\" (default, when there is a project) or \\\"global\\\".\"), or empty — the line goes",
+    "records": "other records a note is not for (\", or the project's own records (tasks, decisions)\"), or empty"
+  },
+  "description": "Write your notes: things worth keeping that are longer than a memory entry and not a skill — findings, a design worked out with the user, a list to come back to.\n\n- create (title, body{{create_scope}}); edit (id, title and/or body — body replaces the whole text); delete (id).\n- {{scope}}\n- Not for facts that hold in every session (memory), procedures (skills){{records}}.",
   "parameters": {
     "type": "object",
     "properties": {
@@ -28,7 +33,7 @@
         ]
       },
       "id": {
-        "type": "integer"
+        "type": "string"
       },
       "title": {
         "type": "string",
@@ -48,5 +53,12 @@
     "required": [
       "action"
     ]
+  },
+  "narrow": {
+    "llembas": {
+      "drop": [
+        "scope"
+      ]
+    }
   }
 }

harness/tools/note_view.json

@@ -18,7 +18,7 @@
     "type": "object",
     "properties": {
       "id": {
-        "type": "integer"
+        "type": "string"
       }
     },
     "required": [

harness/tools/notes_search.json

@@ -11,7 +11,10 @@
     ],
     "llembas": []
   },
-  "description": "Search your notes: things worth keeping that are longer than a memory entry and not a skill — findings, a design worked out with the user, a list to come back to. Kept across sessions, global or this project's; both are searched. An empty query lists the newest. Read one with note_view; write with note_manage.",
+  "variables": {
+    "kept": "where notes are kept and which are searched (\", global or this project's; both are searched\"), or empty"
+  },
+  "description": "Search your notes: things worth keeping that are longer than a memory entry and not a skill — findings, a design worked out with the user, a list to come back to. Kept across sessions{{kept}}. An empty query lists the newest. Read one with note_view; write with note_manage.",
   "parameters": {
     "type": "object",
     "properties": {

harness/tools/skill_manage.json

@@ -12,7 +12,13 @@
       "skill_edit"
     ]
   },
-  "description": "Create, change or delete skills — your procedural memory for kinds of task that come back. Send a list of operations; they apply together, and if one fails none is kept.\n\n- create: a new skill from description + instructions (or content: a whole SKILL.md). Global unless where: project.\n- patch: fix part of a skill with old_string/new_string (read it with skill_view first) — preferred over rewriting.\n- write_file / remove_file: supporting files under references/, templates/, scripts/ or assets/.\n- delete: remove a skill (alone in its call).\n- revert: put back the skill as it was before its last change (a deleted one too); the version it replaces is kept, so a second revert undoes the first. Alone in its call.\n\nWrite the description as its trigger, in about 60 characters — only that much shows in the skills list: \"Use when <situation>. <what it does>.\" Write lessons, not logs: an instruction and why, no dates or incident stories.",
+  "variables": {
+    "create_where": "where a new skill goes (\" Global unless where: project.\"), or empty",
+    "files": "the supporting-file actions (\"write_file / remove_file: supporting files under references/, templates/, scripts/ or assets/.\"), or empty — the line goes",
+    "revert_deleted": "\" (a deleted one too)\" where a deleted skill can be reverted, or empty",
+    "index_cut": "why the description is kept short (\" — only that much shows in the skills list\"), or empty"
+  },
+  "description": "Create, change or delete skills — your procedural memory for kinds of task that come back. Send a list of operations; they apply together, and if one fails none is kept.\n\n- create: a new skill from description + instructions (or content: a whole SKILL.md).{{create_where}}\n- patch: fix part of a skill with old_string/new_string (read it with skill_view first) — preferred over rewriting.\n- {{files}}\n- delete: remove a skill (alone in its call).\n- revert: put back the skill as it was before its last change{{revert_deleted}}; the version it replaces is kept, so a second revert undoes the first. Alone in its call.\n\nWrite the description as its trigger, in about 60 characters{{index_cut}}: \"Use when <situation>. <what it does>.\" Write lessons, not logs: an instruction and why, no dates or incident stories.",
   "parameters": {
     "type": "object",
     "properties": {
@@ -93,5 +99,23 @@
     "required": [
       "operations"
     ]
+  },
+  "narrow": {
+    "llembas": {
+      "drop": [
+        "operations[].category",
+        "operations[].where",
+        "operations[].file_path",
+        "operations[].file_content"
+      ],
+      "enum": {
+        "operations[].action": [
+          "create",
+          "patch",
+          "delete",
+          "revert"
+        ]
+      }
+    }
   }
 }

harness/tools/skill_view.json

@@ -11,7 +11,10 @@
       "skill_get"
     ]
   },
-  "description": "Load a skill: its full instructions, and the list of its supporting files (references, templates, scripts, assets). To read one of those, call again with file_path.",
+  "variables": {
+    "files": "what else a skill carries and how to read it (\", and the list of its supporting files (references, templates, scripts, assets). To read one of those, call again with file_path.\"), or \".\""
+  },
+  "description": "Load a skill: its full instructions{{files}}",
   "parameters": {
     "type": "object",
     "properties": {
@@ -27,5 +30,12 @@
     "required": [
       "name"
     ]
+  },
+  "narrow": {
+    "llembas": {
+      "drop": [
+        "file_path"
+      ]
+    }
   }
 }

harness/tools/skills_list.json

@@ -9,7 +9,10 @@
     "cli": [],
     "llembas": []
   },
-  "description": "List the available skills (name, category, description). Load one with skill_view(name).",
+  "variables": {
+    "category": "\", category\" where skills have categories, or empty"
+  },
+  "description": "List the available skills (name{{category}}, description). Load one with skill_view(name).",
   "parameters": {
     "type": "object",
     "properties": {
@@ -18,5 +21,12 @@
         "type": "string"
       }
     }
+  },
+  "narrow": {
+    "llembas": {
+      "drop": [
+        "category"
+      ]
+    }
   }
 }