#+TITLE: Flight Plan: Unified Tool Registry (def-cognitive-tool)
#+DATE: 2026-04-07
#+FILETAGS: :plan:kernel:architecture:tools:

* Phase A: Demand (Verify State)
- Current state: Tools like `read-file`, `grep-search`, and `eval` are implemented as loose actuators or skill-specific functions.
- The LLM's knowledge of available tools is manually hardcoded into prompts or "guessed" based on skill names.
- Objective: Create a formal, self-documenting Tool Registry that automatically injects tool definitions into neural prompts.

* Phase B: Blueprint (Surgical Edits)

** 1. Tool Registry Data Structure
- Define `*cognitive-tools*` hash table in `src/core.lisp`.
- Define a `cognitive-tool` struct to hold: name, description, parameters, guard, and body.

** 2. The `def-cognitive-tool` Macro
- Create a macro that simplifies tool definition.

** 3. Prompt Integration
- Update `think` in `src/neuro.lisp` to automatically inject the tool belt into the system prompt.

** 4. Recursive Loop Integration
- Update `cognitive-loop` to recognize and execute tool calls.

* Phase D: Build (Implementation)

** 1. Registry & Macro
#+begin_src lisp
(in-package :org-agent)

(defvar *cognitive-tools* (make-hash-table :test 'equal))

(defstruct cognitive-tool name description parameters guard body)

(defmacro def-cognitive-tool (name description &key parameters guard body)
  `(setf (gethash ,(string-downcase (string name)) *cognitive-tools*)
         (make-cognitive-tool :name ,(string-downcase (string name))
                             :description ,description
                             :parameters ',parameters
                             :guard ,guard
                             :body ,body)))
#+end_src

** 2. Tool-Belt Prompt Generator
#+begin_src lisp
(defun generate-tool-belt-prompt ()
  (let ((output "AVAILABLE TOOLS:
You can call tools by returning a Lisp plist: (:target :tool :action :call :tool <name> :args (...))

"))
    (maphash (lambda (name tool)
               (setf output (concatenate 'string output
                                         (format nil "- ~a: ~a\n  Parameters: ~s\n\n"
                                                 name
                                                 (cognitive-tool-description tool)
                                                 (cognitive-tool-parameters tool)))))
             *cognitive-tools*)
    output))
#+end_src

** 3. Integration with 'think'
Refactor `think` to:
- Generate the tool belt prompt.
- Prepend it to the `system-prompt` in `ask-neuro`.

** 4. Integration with 'cognitive-loop'
Update the recursive check to:
- Handle `(:target :tool :action :call ...)` specifically.
- Look up the tool in `*cognitive-tools*`.
- Execute guard -> body.

* Phase C: Tester (Automated Proof)
- Refactor `eval` into a cognitive tool.
- Verify the agent can use it recursively.