openclacky 1.3.7 → 1.3.9

data/lib/clacky/server/http_server.rb

@@ -369,6 +369,8 @@ module Clacky
             res.body                  = html
           elsif req.path.start_with?("/agent_ui/")
             self.send(:serve_agent_ui, req, res)
+          elsif req.path.start_with?("/agent_avatar/")
+            self.send(:serve_agent_avatar, req, res)
           elsif req.path.start_with?("/ext_ui/")
             self.send(:serve_ext_ui, req, res)
           else
@@ -538,6 +540,7 @@ module Clacky
         when ["GET",    "/api/store/skills"]          then api_store_skills(res)
         when ["GET",    "/api/store/extensions"]      then api_store_extensions(req, res)
         when ["GET",    "/api/store/extension"]       then api_store_extension_detail(req, res)
+        when ["POST",   "/api/store/extension/install"]  then api_store_extension_install(req, res)
         when ["POST",   "/api/store/extension/disable"] then api_store_extension_disable(req, res)
         when ["POST",   "/api/store/extension/enable"]  then api_store_extension_enable(req, res)
         when ["DELETE", "/api/store/extension"]         then api_store_extension_uninstall(req, res)
@@ -623,6 +626,9 @@ module Clacky
           elsif method == "GET" && path.match?(%r{^/api/sessions/[^/]+/skills$})
             session_id = path.sub("/api/sessions/", "").sub("/skills", "")
             api_session_skills(session_id, res)
+          elsif method == "GET" && path.match?(%r{^/api/agents/[^/]+/skills$})
+            agent_id = path[%r{^/api/agents/([^/]+)/skills$}, 1]
+            api_agent_skills(agent_id, res)
           elsif method == "GET" && path.match?(%r{^/api/sessions/[^/]+/git/[a-z]+$})
             session_id = path[%r{^/api/sessions/([^/]+)/git/}, 1]
             action     = path[%r{/git/([a-z]+)$}, 1]
@@ -1061,6 +1067,7 @@ module Clacky
       private def webui_ext_script_tags
         [
           panel_agents_script,
+          ext_contributions_script,
           agent_webui_script_tags,
           container_ext_script_tags,
         ].reject(&:empty?).join("\n")
@@ -1097,6 +1104,36 @@ module Clacky
         "<script>Clacky.ext.registerPanelAgents(#{map.to_json})</script>"
       end
 
+      # Inline script mapping agent id => the panels & skills its extension
+      # contributes (straight from ext.yml). Built-in extensions are excluded so
+      # the new-session page only advertises what a third-party agent adds.
+      private def ext_contributions_script
+        map = ext_contributions_map
+        return "" if map.empty?
+
+        "<script>Clacky.ext.registerAgentContributions(#{map.to_json})</script>"
+      end
+
+      private def ext_contributions_map
+        result = Clacky::ExtensionLoader.load_all
+        by_ext = Hash.new { |h, k| h[k] = { "panels" => [], "skills" => [] } }
+        label = lambda do |unit|
+          { "id" => unit.id, "title" => unit.spec["title"] || unit.id, "title_zh" => unit.spec["title_zh"] }
+        end
+
+        result.panels.each { |u| by_ext[u.ext_id]["panels"] << label.call(u) unless u.layer == :builtin }
+        result.skills.each { |u| by_ext[u.ext_id]["skills"] << label.call(u) unless u.layer == :builtin }
+
+        out = {}
+        result.agents.each do |u|
+          next if u.layer == :builtin
+          contrib = by_ext[u.ext_id]
+          next if contrib["panels"].empty? && contrib["skills"].empty?
+          out[u.id] = contrib
+        end
+        out
+      end
+
       # panel id => list of agent names allowed to see it. Two sources merge:
       #   1. `agent.panels: [id]` — agent-side explicit reference (opt-in mount)
       #   2. `panel.attach: [...]` — panel-author's default suggestion
@@ -1283,6 +1320,42 @@ module Clacky
         serve_static_under(File.join(dir, "webui"), rel, res)
       end
 
+      # GET /agent_avatar/<id> — serve an agent's avatar image (extension
+      # `avatar` file, or a user agent's avatar.png). Read-only, images only.
+      private def serve_agent_avatar(req, res)
+        id = req.path.delete_prefix("/agent_avatar/").split("/").first.to_s
+        return (res.status = 404; res.body = "not found") if id.empty?
+
+        abs = agent_avatar_path(id)
+        unless abs && File.file?(abs)
+          res.status = 404
+          res.body   = "not found"
+          return
+        end
+
+        ctype = { ".png" => "image/png", ".jpg" => "image/jpeg", ".jpeg" => "image/jpeg",
+                  ".webp" => "image/webp", ".svg" => "image/svg+xml", ".gif" => "image/gif" }[File.extname(abs).downcase]
+        unless ctype
+          res.status = 415
+          res.body   = "unsupported media type"
+          return
+        end
+
+        res.status          = 200
+        res["Content-Type"] = ctype
+        res["Cache-Control"] = "public, max-age=86400"
+        res.body            = File.binread(abs)
+      end
+
+      private def agent_avatar_path(id)
+        unit = Clacky::ExtensionLoader.last_result&.agents&.find { |u| u.id == id }
+        avatar_abs = unit&.spec&.[]("avatar_abs").to_s
+        return avatar_abs unless avatar_abs.empty?
+
+        user_png = File.expand_path("~/.clacky/agents/#{id}/avatar.png")
+        File.file?(user_png) ? user_png : nil
+      end
+
       # Read-only static serve of `rel` under `root`, JS/CSS/HTML only, with
       # strict path containment so a crafted rel cannot escape `root`.
       private def serve_static_under(root, rel, res)
@@ -1419,6 +1492,9 @@ module Clacky
         output_dir   = body["output_dir"].to_s
         output_dir   = @agent_config.default_working_dir || Dir.pwd if output_dir.empty?
 
+        session_id = body["session_id"].to_s
+        session_id = nil if session_id.empty?
+
         result = Clacky::Media::Generator.new(@agent_config).generate_image(
           prompt: prompt,
           aspect_ratio: aspect_ratio,
@@ -1427,7 +1503,7 @@ module Clacky
           images: body["images"]
         )
         if result["success"]
-          log_media_usage(result, prompt: prompt)
+          log_media_usage(result, prompt: prompt, session_id: session_id)
         end
         status = result["success"] ? 200 : 422
         json_response(res, status, result)
@@ -1451,6 +1527,9 @@ module Clacky
         output_dir   = body["output_dir"].to_s
         output_dir   = @agent_config.default_working_dir || Dir.pwd if output_dir.empty?
 
+        session_id = body["session_id"].to_s
+        session_id = nil if session_id.empty?
+
         result = Clacky::Media::Generator.new(@agent_config).generate_video(
           prompt: prompt,
           aspect_ratio: aspect_ratio,
@@ -1459,7 +1538,7 @@ module Clacky
           image: image
         )
         if result["success"]
-          log_media_usage(result, prompt: prompt)
+          log_media_usage(result, prompt: prompt, session_id: session_id)
         end
         status = result["success"] ? 200 : 422
         json_response(res, status, result)
@@ -1480,13 +1559,16 @@ module Clacky
         output_dir = body["output_dir"].to_s
         output_dir = @agent_config.default_working_dir || Dir.pwd if output_dir.empty?
 
+        session_id = body["session_id"].to_s
+        session_id = nil if session_id.empty?
+
         result = Clacky::Media::Generator.new(@agent_config).generate_speech(
           input: input,
           voice: voice,
           output_dir: output_dir
         )
         if result["success"]
-          log_media_usage(result, prompt: input)
+          log_media_usage(result, prompt: input, session_id: session_id)
         end
         status = result["success"] ? 200 : 422
         json_response(res, status, result)
@@ -1547,7 +1629,7 @@ module Clacky
         json_response(res, 500, { error: e.message })
       end
 
-      private def log_media_usage(result, prompt:)
+      private def log_media_usage(result, prompt:, session_id: nil)
         usage = result["usage"]
         cost  = result["cost_usd"]
         return if usage.nil? && cost.nil?
@@ -1568,6 +1650,20 @@ module Clacky
                else "image"
                end
         Clacky::Logger.info("[Media] #{kind} generated #{parts.join(" ")}")
+
+        require_relative "../billing/billing_store"
+        require_relative "../billing/billing_record"
+        record = Clacky::Billing::BillingRecord.new(
+          session_id:        session_id,
+          model:             result["model"].to_s,
+          prompt_tokens:     usage.is_a?(Hash) ? usage["prompt_tokens"].to_i : 0,
+          completion_tokens: usage.is_a?(Hash) ? usage["completion_tokens"].to_i : 0,
+          cache_read_tokens: usage.is_a?(Hash) ? usage["cache_read_tokens"].to_i : 0,
+          cache_write_tokens: usage.is_a?(Hash) ? usage["cache_write_tokens"].to_i : 0,
+          cost_usd:          cost.to_f,
+          cost_source:       :api
+        )
+        Clacky::Billing::BillingStore.new.append(record)
       end
 
       # GET /api/media/types
@@ -2324,6 +2420,25 @@ module Clacky
       end
 
       # DELETE /api/store/extension   body: { id: <slug> }
+      def api_store_extension_install(req, res)
+        body         = parse_json_body(req)
+        download_url = body["download_url"].to_s.strip
+        name         = body["name"].to_s.strip
+
+        if download_url.empty?
+          json_response(res, 400, { ok: false, error: "Missing download_url." })
+          return
+        end
+
+        Clacky::ExtensionPackager.install(download_url, force: true)
+        Clacky::ExtensionLoader.invalidate_cache!
+        json_response(res, 200, { ok: true, name: name })
+      rescue Clacky::ExtensionPackager::Error => e
+        json_response(res, 422, { ok: false, error: e.message })
+      rescue StandardError => e
+        json_response(res, 500, { ok: false, error: e.message })
+      end
+
       def api_store_extension_uninstall(req, res)
         id = parse_json_body(req)["id"].to_s
         container = extension_container(id)
@@ -3917,7 +4032,36 @@ module Clacky
         json_response(res, 200, { skills: skill_data })
       end
 
-      # GET /api/sessions/:id/git/<action> — read-only git info for the session's
+      # GET /api/agents/:id/skills — like api_session_skills but keyed on an
+      # agent id rather than a live session. Used by the New Session page so the
+      # first-message composer can offer slash-command autocomplete before a
+      # session exists.
+      def api_agent_skills(agent_id, res)
+        profile = begin
+          Clacky::AgentProfile.load(agent_id)
+        rescue StandardError
+          nil
+        end
+
+        @skill_loader.load_all
+        skills = @skill_loader.user_invocable_skills
+        skills = skills.select { |s| s.allowed_for_agent?(profile.name) } if profile
+
+        loaded_from = @skill_loader.loaded_from
+        skill_data = skills.map do |skill|
+          {
+            name:           skill.identifier,
+            name_zh:        skill.name_zh,
+            description:    skill.description || skill.context_description,
+            description_zh: skill.description_zh,
+            encrypted:      skill.encrypted?,
+            source_type:    loaded_from[skill.identifier],
+            always_show:    skill.always_show
+          }
+        end
+
+        json_response(res, 200, { skills: skill_data })
+      end
       # working_dir. action ∈ status|diff|log|branches. diff accepts ?file=,
       # log accepts ?limit=.
       def api_session_git(session_id, action, req, res)

data/lib/clacky/shell_hook_loader.rb

@@ -14,28 +14,48 @@ module Clacky
   # hooks.yml format:
   #   hooks:
   #     before_tool_use:
+  #       # Simple protocol — no `type` (or `type: command`). exit-code driven.
   #       - name: guard            # optional label for logs
   #         command: "~/.clacky/hook-scripts/guard.sh"
   #         timeout: 10            # optional, seconds (default 10)
+  #
+  #       # Rewrite protocol — `type: rewrite`. Rich JSON stdin/stdout, supports
+  #       # matcher, updatedInput rewrite. (before_tool_use only)
+  #       - type: rewrite
+  #         # matcher must be the CANONICAL tool name the agent dispatches
+  #         # (e.g. `terminal`), NOT an alias (`bash`/`shell`/`exec`): the
+  #         # agent resolves aliases to canonical names BEFORE firing hooks,
+  #         # so `matcher: bash` would never match. "*" or omitted = all tools.
+  #         matcher: terminal
+  #         command: "~/.clacky/hook-scripts/rewrite.sh"
+  #         timeout: 30             # optional, seconds (default 60)
   #     on_complete:
   #       - command: "notify-send done"
   #
   # Runtime contract (per invocation):
   #   - The event payload is passed to the command as JSON on STDIN.
-  #   - exit 0  → allow (default).
-  #   - exit 2  → deny; STDOUT becomes the denial reason. Only meaningful for
-  #               before_tool_use, which the agent checks for {action: :deny}.
+  #   - exit 0  → allow (default). Rewrite hooks parse STDOUT as hookSpecificOutput.
+  #   - exit 2  → deny; STDOUT (simple) or stderr/stdout (rewrite) is the reason.
+  #               Only before_tool_use is checked for {action: :deny}.
   #   - any other exit / timeout / crash → logged, treated as allow (a broken
   #     hook must never wedge the agent).
+  #
+  # Rewrite entries chain in config order: each applies its updatedInput IN
+  # PLACE on the tool call (complete replacement — no merge); the first deny
+  # stops the chain.
   class ShellHookLoader
-    DEFAULT_PATH    = File.expand_path("~/.clacky/hooks.yml")
-    DEFAULT_TIMEOUT = 10
-    DENY_EXIT_CODE  = 2
+    DEFAULT_PATH            = File.expand_path("~/.clacky/hooks.yml")
+    DEFAULT_TIMEOUT         = 10
+    REWRITE_DEFAULT_TIMEOUT = 60
+    DENY_EXIT_CODE          = 2
 
     Result = Struct.new(:registered, :skipped, keyword_init: true)
 
-    def self.load_into(hook_manager, path: DEFAULT_PATH)
-      new(path: path).load_into(hook_manager)
+    # The context procs supply rewrite-protocol context at run time; optional so
+    # simple-only callers (e.g. `clacky hook_verify`) can omit them.
+    def self.load_into(hook_manager, session_id_fn: nil, cwd_fn: nil, permission_mode_fn: nil, path: DEFAULT_PATH)
+      new(path: path, session_id_fn: session_id_fn, cwd_fn: cwd_fn, permission_mode_fn: permission_mode_fn)
+        .load_into(hook_manager)
     end
 
     # Create a starter hooks.yml plus an example guard script. Idempotent-ish:
@@ -67,12 +87,18 @@ module Clacky
       File.write(path, <<~YAML)
         # Declarative shell hooks. Each command receives the event payload as JSON
         # on STDIN. For before_tool_use: exit 2 = deny (STDOUT = reason), exit 0 = allow.
+        # Add `type: rewrite` to a before_tool_use entry to use the rich JSON
+        # protocol (updatedInput rewrite, matcher).
         # Events: #{HookManager::HOOK_EVENTS.join(", ")}
         hooks:
           before_tool_use:
             - name: deny-example
               command: "#{guard}"
               timeout: 10
+        #    - type: rewrite
+        #      matcher: terminal
+        #      command: "~/.clacky/hook-scripts/rewrite.sh"
+        #      timeout: 30
         #  on_complete:
         #    - command: "echo task finished"
       YAML
@@ -80,8 +106,11 @@ module Clacky
       path
     end
 
-    def initialize(path: DEFAULT_PATH)
-      @path = path
+    def initialize(path: DEFAULT_PATH, session_id_fn: nil, cwd_fn: nil, permission_mode_fn: nil)
+      @path               = path
+      @session_id_fn      = session_id_fn
+      @cwd_fn             = cwd_fn
+      @permission_mode_fn = permission_mode_fn
     end
 
     # @return [Result] counts of registered hooks and skipped (with reasons)
@@ -106,14 +135,37 @@ module Clacky
     end
 
     private def register_one(hook_manager, event, spec, result)
+      if spec["type"] == "rewrite" && event != :before_tool_use
+        # type: rewrite only makes sense under before_tool_use (it rewrites tool
+        # input); elsewhere matcher/updatedInput would be silently ignored —
+        # skip + warn so the misconfiguration is visible.
+        name = (spec["name"] || spec["command"] || "rewrite hook").to_s
+        result.skipped << [name, "type: rewrite is only valid under before_tool_use"]
+      elsif spec["type"] == "rewrite"
+        register_rewrite(hook_manager, spec, result)
+      else
+        register_simple(hook_manager, event, spec, result)
+      end
+    end
+
+    # Returns [name, command] for a spec, or nil (after recording a skip) when
+    # the command is missing. Shared by the simple and rewrite registrars.
+    private def resolve_command(spec, result)
       command = spec["command"].to_s.strip
       name    = spec["name"] || command
-      timeout = (spec["timeout"] || DEFAULT_TIMEOUT).to_i
-
       if command.empty?
         result.skipped << [name, "missing command"]
-        return
+        nil
+      else
+        [name, command]
       end
+    end
+
+    private def register_simple(hook_manager, event, spec, result)
+      resolved = resolve_command(spec, result)
+      return unless resolved
+      name, command = resolved
+      timeout = (spec["timeout"] || DEFAULT_TIMEOUT).to_i
 
       unless HookManager::HOOK_EVENTS.include?(event)
         result.skipped << [name, "unknown event: #{event}"]
@@ -126,25 +178,123 @@ module Clacky
       result.registered << [event, name]
     end
 
-    private def run_command(event, command, timeout, args)
-      payload = JSON.generate(build_payload(event, args))
+    # Rewrite protocol (before_tool_use only): rich JSON stdin/stdout.
+    private def register_rewrite(hook_manager, spec, result)
+      resolved = resolve_command(spec, result)
+      return unless resolved
+      name, command = resolved
+      timeout = (spec["timeout"] || REWRITE_DEFAULT_TIMEOUT).to_i
+      matcher = spec["matcher"]
 
-      out = +""
+      hook_manager.add(:before_tool_use) do |call|
+        tool_name = (call[:name] || call["name"]).to_s
+        next { action: :allow } unless matcher_applies?(matcher, tool_name)
+        run_rewrite(command, timeout, call, tool_name)
+      end
+      result.registered << [:before_tool_use, name]
+    end
+
+    # "*" or omitted matches every tool; otherwise the matcher must equal the
+    # canonical tool name exactly (no aliases, regex, or lists).
+    private def matcher_applies?(matcher, tool_name)
+      matcher.nil? || matcher == "*" || matcher == tool_name
+    end
+
+    # Cap on bytes buffered per stream: before_tool_use fires on every tool
+    # call, so a runaway/malicious hook could otherwise OOM the agent.
+    MAX_OUTPUT_BYTES = 8 * 1024 * 1024
+
+    # Spawn `command` in its own process group, feed `payload` on STDIN, and
+    # return [stdout, stderr, status]. stdout and stderr are drained on parallel
+    # reader threads — a single sequential reader deadlocks once a child fills
+    # the 64KB stderr pipe while keeping stdout open. The dedicated process
+    # group lets us SIGKILL the whole tree on timeout (including grandchildren
+    # that inherit the fds), so a hook that traps TERM can't hang the agent.
+    # Output is scrubbed to valid UTF-8 so a stray non-UTF-8 byte can't turn a
+    # deny into an allow via a .strip / JSON.parse raise.
+    private def capture_streams(command, payload, timeout)
+      stdout = +""
+      stderr = +""
+      # Declared here so the block assigns this var, not a block-local one
+      # (else every deny silently becomes an allow).
       status = nil
-      Open3.popen3(command) do |stdin, stdout, _stderr, wait_thr|
-        stdin.write(payload)
-        stdin.close
+
+      Open3.popen3(command, pgroup: true) do |stdin, out, err, wait_thr|
+        pgid = wait_thr.pid
+
+        out_reader = Thread.new { drain_stream(out, stdout) }
+        err_reader = Thread.new { drain_stream(err, stderr) }
+
+        # Write stdin on its own thread: a child that doesn't read stdin (or a
+        # payload larger than the ~64KB pipe buffer) would otherwise block the
+        # main thread before it reaches wait_thr.join(timeout) — the only thing
+        # enforcing the timeout — and wedge capture_streams forever.
+        writer = Thread.new do
+          begin
+            stdin.write(payload)
+          rescue Errno::EPIPE
+            # Child already exited / stopped reading; its stdout may still be readable.
+          rescue IOError
+            # Pipes closed (timeout path) — nothing more to write.
+          ensure
+            stdin.close rescue nil
+          end
+        end
+
         if wait_thr.join(timeout)
-          out = stdout.read
           status = wait_thr.value
+          # Child exited; drain the readers (bounded join — a grandchild
+          # holding the pipe fd can keep them from EOF; see drain_stream).
+          out_reader.join(2)
+          err_reader.join(2)
         else
-          Process.kill("TERM", wait_thr.pid) rescue nil
+          # SIGTERM, then SIGKILL the whole group if it won't die. popen3's
+          # ensure joins wait_thr without a timeout, so the child MUST be dead
+          # before we leave the block — a hook that traps/ignores TERM can't be
+          # allowed to hang here.
+          Process.kill("TERM", -pgid) rescue nil
+          unless wait_thr.join(1)
+            Process.kill("KILL", -pgid) rescue nil
+            wait_thr.join
+          end
+          out_reader.join(1)
+          err_reader.join(1)
+          writer.kill rescue nil
           raise Timeout::Error
         end
       end
 
+      [stdout.scrub!, stderr.scrub!, status]
+    end
+
+    # Read `io` into `buf` in readpartial chunks until EOF, instead of a single
+    # IO#read. readpartial returns whatever is currently available, so a
+    # grandchild that inherited the pipe fd (and thus keeps it from EOF) can no
+    # longer block us forever — already-read bytes are preserved in `buf`.
+    # Appending stops at MAX_OUTPUT_BYTES so a runaway hook can't OOM the agent;
+    # we keep draining past the cap so the child doesn't block on a full pipe.
+    private def drain_stream(io, buf)
+      loop do
+        chunk = io.readpartial(4096)
+        buf << chunk if buf.bytesize < MAX_OUTPUT_BYTES
+      end
+    rescue EOFError, IOError
+      # EOFError: pipe closed (normal end). IOError: pipes closed on block exit.
+    end
+
+    # Strip + default, so a deny never has a blank reason.
+    private def deny_reason(raw)
+      s = raw.to_s.strip
+      s.empty? ? "Denied by hook" : s
+    end
+
+    private def run_command(event, command, timeout, args)
+      payload = JSON.generate(build_payload(event, args))
+
+      out, _err, status = capture_streams(command, payload, timeout)
+
       if status&.exitstatus == DENY_EXIT_CODE
-        { action: :deny, reason: out.strip.empty? ? "Denied by hook" : out.strip }
+        { action: :deny, reason: deny_reason(out) }
       else
         { action: :allow }
       end
@@ -177,5 +327,99 @@ module Clacky
 
       base
     end
+
+    # --- Rewrite protocol (type: rewrite) -------------------------------------
+
+    private def run_rewrite(command, timeout, call, tool_name)
+      tool_input = parse_tool_args(call)
+      payload    = build_rewrite_payload(tool_name, tool_input)
+
+      stdout, stderr, status = capture_streams(command, payload, timeout)
+
+      # nil exitstatus = killed by signal (SIGKILL/OOM) — a crash, not a clean
+      # exit. Treat as allow so a partial deny payload can't deny from garbage.
+      if status&.exitstatus.nil?
+        Clacky::Logger.warn("[ShellHookLoader] Rewrite hook '#{command}' died (signal) — allowing")
+        return { action: :allow }
+      end
+      exit_code = status.exitstatus
+
+      if exit_code == DENY_EXIT_CODE
+        source = stderr.strip.empty? ? stdout : stderr
+        return { action: :deny, reason: deny_reason(source) }
+      end
+
+      if exit_code != 0
+        Clacky::Logger.warn("[ShellHookLoader] Rewrite hook '#{command}' exited #{exit_code} (non-blocking) — allowing")
+        return { action: :allow }
+      end
+
+      result = parse_hook_output(stdout)
+      # Chained rewrite: apply updatedInput IN PLACE on `call` so the next
+      # rewrite sees it. updatedInput is a complete replacement (no merge);
+      # empty/absent means "no rewrite this time" — leave `call` untouched.
+      updated = result.delete(:updated_input)
+      call[:arguments] = JSON.generate(updated) if updated.is_a?(Hash) && !updated.empty?
+      result
+    rescue Timeout::Error
+      Clacky::Logger.warn("[ShellHookLoader] Rewrite hook '#{command}' timed out after #{timeout}s — allowing")
+      { action: :allow }
+    rescue StandardError => e
+      Clacky::Logger.warn("[ShellHookLoader] Rewrite hook '#{command}' failed: #{e.message} — allowing")
+      { action: :allow }
+    end
+
+    private def build_rewrite_payload(tool_name, tool_input)
+      JSON.generate({
+        session_id:      @session_id_fn&.call,
+        cwd:             @cwd_fn&.call || Dir.pwd,
+        permission_mode: @permission_mode_fn&.call || "default",
+        hook_event_name: "PreToolUse",
+        tool_name:       tool_name,
+        tool_input:      tool_input
+      })
+    end
+
+    # Parse the tool arguments the hook should see. Unparseable JSON is logged
+    # (not silently swallowed) but defers to an empty Hash so a broken payload
+    # doesn't wedge the agent.
+    private def parse_tool_args(call)
+      args = call[:arguments] || call["arguments"]
+      case args
+      when String then JSON.parse(args)
+      when Hash   then args
+      else             {}
+      end
+    rescue JSON::ParserError => e
+      Clacky::Logger.warn("[ShellHookLoader] Unparseable tool arguments (#{e.message}); hook sees empty input")
+      {}
+    end
+
+    # Missing or unparseable hookSpecificOutput defers to allow.
+    private def parse_hook_output(stdout)
+      return { action: :allow } if stdout.nil? || stdout.strip.empty?
+
+      parsed   = JSON.parse(stdout.strip)
+      specific = parsed.is_a?(Hash) && parsed["hookSpecificOutput"]
+      return { action: :allow } unless specific.is_a?(Hash)
+
+      decision      = specific["permissionDecision"]
+      reason        = specific["permissionDecisionReason"]
+      updated_input = specific["updatedInput"]
+
+      # Permission decision other than "deny" is treated as allow: the agent's
+      # own permission_mode governs confirmation, not the hook.
+      result = case decision
+               when "deny"
+                 { action: :deny, reason: deny_reason(reason) }
+               else
+                 { action: :allow }   # "allow", "ask", "defer", unknown
+               end
+
+      result[:updated_input] = updated_input if updated_input.is_a?(Hash)
+      result
+    rescue JSON::ParserError
+      { action: :allow }
+    end
   end
 end

data/lib/clacky/ui2/components/welcome_banner.rb

@@ -28,7 +28,7 @@ module Clacky
         TIPS = [
           "[*] Ask questions, edit files, or run commands",
           "[*] Be specific for the best results",
-          "[*] Create .clackyrules to customize interactions",
+          "[*] Create .clackyrules or AGENTS.md to customize interactions",
           "[*] Type /help for more commands"
         ].freeze
 

data/lib/clacky/utils/workspace_rules.rb

@@ -2,10 +2,10 @@
 
 module Clacky
   module Utils
-    # Discovers .clackyrules files in the workspace.
+    # Discovers project rules files in the workspace.
     # Used by both SystemPromptBuilder (rules injection) and WelcomeBanner (UI display).
     module WorkspaceRules
-      RULES_FILENAMES = [".clackyrules", ".cursorrules", "CLAUDE.md"].freeze
+      RULES_FILENAMES = [".clackyrules", "AGENTS.md", ".cursorrules", "CLAUDE.md"].freeze
       SUB_PROJECT_SUMMARY_LINES = 5
 
       # Find the main rules file in the given directory.

data/lib/clacky/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Clacky
-  VERSION = "1.3.7"
+  VERSION = "1.3.9"
 end