Merge remote-tracking branch 'upstream/main'

timvisher-dd · timvisher-dd · commit 83a1ce89d2e6 · 2026-03-18T15:21:53.000-04:00
diff --git a/.github/ISSUE_TEMPLATE/issue.md b/.github/ISSUE_TEMPLATE/issue.md
@@ -11,9 +11,9 @@ assignees: ''
 - [ ] *I agree to communicate with the author myself* (not AI-generated).
 - [ ] I've read the README's [Filing issues](https://github.com/xenodium/agent-shell?tab=readme-ov-file#filing-issues) section.
 - [ ] I'm running the latest versions (fill in below).
-  - agent-shell:
-  - acp.el:
-  - ACP package (e.g. claude-code-acp):
-  - Agent CLI (e.g. claude, gemini):
+  - agent-shell version:
+  - acp.el version:
+  - ACP package (e.g. claude-agent-acp) version:
+  - Agent CLI (e.g. claude, gemini) version:
 - [ ] For requesting new agent support, I'm including a link to the ACP-capable agent or related ACP package.
 - [ ] For issues, I'm including [ACP traffic](https://github.com/xenodium/agent-shell?tab=readme-ov-file#how-do-i-viewget-agent-client-protocol-traffic) (as per README).
diff --git a/CONTRIBUTING.org b/CONTRIBUTING.org
@@ -54,6 +54,18 @@ Accessing and working with =alists=? Please prefer =map.el= unless we have a str
   (map-elt animal :species)
 #+end_src
 
+** Prefer =map-nested-elt= over nested =map-elt=
+
+When accessing nested alist values, use =map-nested-elt= instead of nesting =map-elt= calls.
+
+#+begin_src emacs-lisp :lexical no
+  ;; Avoid
+  (map-elt (map-elt response 'usage) 'totalTokens)
+
+  ;; Prefer
+  (map-nested-elt response '(usage totalTokens))
+#+end_src
+
 ** cl-lib (limited to =cl-defun=)
 
 While I'm a fan of =cl-defun=, please limit =cl= usage to =cl-defun= if possible. Nothing against =cl-lib=. I'm just limiting the surface and number of idioms I need to keep in my head to maintain the codebase. Often, =seq.el= and =map.el= can do the job just fine.
@@ -146,7 +158,9 @@ When defining hook functions or callbacks, prefer a single alist/event parameter
 
 Remove comments obviously by an LLM (e.g. referencing "previous code" or restating the obvious). Avoid emojis in code and output strings.
 
-** Keep PRs focused
+** Keep PRs small and focused
+
+Prefer smaller PRs whenever possible. They're easier to review and less likely to introduce issues. If a change can be split into independent steps, submit them as separate PRs.
 
 Don't include unrelated changes (whitespace, indentation, formatting) in your PR. If you'd like to do a cleanup, please submit it as a separate PR.
 
diff --git a/README.org b/README.org
@@ -32,7 +32,7 @@ Thank you!
 
 A native Emacs shell to interact with LLM agents powered by ACP ([[https://agentclientprotocol.com][Agent Client Protocol]]).
 
-With agent-shell, you can chat with the likes of Gemini CLI, Claude Code, Auggie, Mistral Vibe, or any other ACP-driven agent.
+With agent-shell, you can chat with the likes of Gemini CLI, Claude Agent, Auggie, Mistral Vibe, or any other ACP-driven agent.
 
 Watch on [[https://www.youtube.com/watch?v=R2Ucr3amgGg][YouTube]]
 
@@ -60,7 +60,8 @@ We now have a handful of additional packages to extend the =agent-shell= experie
 - [[https://github.com/gveres/agent-shell-workspace][agent-shell-workspace]]: Dedicated tab-bar workspace for managing multiple =agent-shell= sessions.
 - [[https://github.com/ElleNajt/agent-shell-to-go][agent-shell-to-go]]: Interact with =agent-shell= sessions from your mobile or any other device via Slack.
 - [[https://github.com/ElleNajt/meta-agent-shell][meta-agent-shell]]: Multi-agent coordination system for =agent-shell= with inter-agent communication, task tracking, and project-level dispatching.
-- [[https://github.com/xenodium/emacs-skills][emacs-skills]]: Claude Code skills for Emacs.
+- [[https://github.com/xenodium/agent-shell-knockknock][agent-shell-knockknock]]: Notifications for =agent-shell= via [[https://github.com/konrad1977/knockknock][knockknock.el]].
+- [[https://github.com/xenodium/emacs-skills][emacs-skills]]: Claude Agent skills for Emacs.
 
 * Icons
 
@@ -70,9 +71,9 @@ Thanks to [[https://github.com/lobehub/lobe-icons][Lobe Icons]] for the lovely i
 
 ** External dependencies
 
-*** Claude Code
+*** Claude Agent SDK
 
-For Anthropic's Claude Code, follow [[https://github.com/zed-industries/claude-agent-acp][Zed's claude-agent-acp instructions]], typically something like:
+For Anthropic's [[https://platform.claude.com/docs/en/agent-sdk/overview][Claude Agent SDK]] (formerly known as the Claude Code SDK), follow [[https://github.com/zed-industries/claude-agent-acp][Zed's claude-agent-acp instructions]], typically something like:
 
 #+begin_src bash
 npm install -g @zed-industries/claude-agent-acp
@@ -390,7 +391,7 @@ For API key authentication:
 
 *** Customizing Available Agents
 
-By default, =agent-shell= includes configurations for all supported agents (Claude Code, Gemini CLI, Codex, Goose, Qwen Code, and Auggie). You can customize which agents are available through the =agent-shell-agent-configs= variable.
+By default, =agent-shell= includes configurations for all supported agents (Claude Agent, Gemini CLI, Codex, Goose, Qwen Code, and Auggie). You can customize which agents are available through the =agent-shell-agent-configs= variable.
 
 ** Usage
 
@@ -404,7 +405,7 @@ You can select and start any of the known agent shells (see =agent-shell-agent-c
 
 Start a specific agent shell session directly:
 
-- =M-x agent-shell-anthropic-start-claude-code= - Start a Claude Code agent session
+- =M-x agent-shell-anthropic-start-claude-code= - Start a Claude Agent session
 - =M-x agent-shell-auggie-start-agent= - Start an Auggie agent session
 - =M-x agent-shell-openai-start-codex= - Start a Codex agent session
 - =M-x agent-shell-google-start-gemini= - Start a Gemini agent session
@@ -717,7 +718,7 @@ always go to Evil modes if you need to with ~C-z~).
 |-----------------+---------------------------------------------------------+-------------------------------------------------------------------------------|
 |                 | agent-shell                                             | Start or reuse an existing agent shell.                                       |
 |                 | agent-shell--display-buffer                             | Toggle agent SHELL-BUFFER display.                                            |
-|                 | agent-shell-anthropic-start-claude-code                 | Start an interactive Claude Code agent shell.                                 |
+|                 | agent-shell-anthropic-start-claude-code                 | Start an interactive Claude Agent shell.                                      |
 |                 | agent-shell-auggie-start-agent                          | Start an interactive Auggie agent shell.                                      |
 |                 | agent-shell-clear-buffer                                | Clear the current shell buffer.                                               |
 |                 | agent-shell-completion-mode                             | Toggle agent shell completion with @ or / prefix.                             |
@@ -834,7 +835,7 @@ Sometimes including a traffic screenshot in an issue is enough. Other times incl
 
 If you're able to determine the agent is missing a feature (or a bug is present) in their [[https://agentclientprotocol.com][Agent Client Protocol]] implementation, please file an issue directly with the agent folks. For example:
 
-- [[https://github.com/zed-industries/claude-code-acp][claude-code-acp]]: For Claude Code.
+- [[https://github.com/zed-industries/claude-code-acp][claude-code-acp]]: For Claude Agent.
 - [[https://github.com/zed-industries/codex-acp][codex-acp]]: For Codex.
 - [[https://github.com/google-gemini/gemini-cli][Gemini CLI]].
 - [[https://block.github.io/goose/docs/getting-started/installation][Goose]].
diff --git a/agent-shell-anthropic.el b/agent-shell-anthropic.el
@@ -132,7 +132,7 @@ Example usage to set a custom Anthropic API base URL:
   :group 'agent-shell)
 
 (defun agent-shell-anthropic-make-claude-code-config ()
-  "Create a Claude Code agent configuration.
+  "Create a Claude Agent configuration.
 
 Returns an agent configuration alist using `agent-shell-make-agent-config'."
   (agent-shell-make-agent-config
@@ -152,7 +152,7 @@ Returns an agent configuration alist using `agent-shell-make-agent-config'."
    :install-instructions "See https://github.com/zed-industries/claude-agent-acp for installation."))
 
 (defun agent-shell-anthropic-start-claude-code ()
-  "Start an interactive Claude Code agent shell."
+  "Start an interactive Claude Agent shell."
   (interactive)
   (agent-shell--dwim :config (agent-shell-anthropic-make-claude-code-config)
                      :new-shell t))
diff --git a/agent-shell-diff.el b/agent-shell-diff.el
@@ -68,6 +68,14 @@ via `agent-shell-diff-mode-map'."
   (set-keymap-parent agent-shell-diff-mode-map nil)
   (setq buffer-read-only t))
 
+(defun agent-shell-diff-kill-buffer (buffer)
+  "Kill diff BUFFER, suppressing any `agent-shell-on-exit' callback.
+If BUFFER is not live, do nothing."
+  (when (buffer-live-p buffer)
+    (with-current-buffer buffer
+      (setq agent-shell-on-exit nil))
+    (kill-buffer buffer)))
+
 (defun agent-shell-diff-accept-all ()
   "Accept all changes in the current diff buffer."
   (interactive)
@@ -90,6 +98,8 @@ using `agent-shell-diff-mode'.  The buffer is read-only.
 
 When the buffer is killed, calls ON-EXIT with no arguments.
 
+Returns the newly created diff buffer.
+
 Arguments:
   :OLD       - Original string content
   :NEW       - Modified string content
@@ -154,18 +164,15 @@ Arguments:
               (setq agent-shell-on-exit on-exit)
               (add-hook 'kill-buffer-hook
                         (lambda ()
-                          (with-current-buffer diff-buffer
-                            (when agent-shell-on-exit
-                              (with-current-buffer calling-buffer
-                                (funcall on-exit))))
-                          (with-current-buffer calling-buffer
-                            ;; Make sure give focus back to calling buffer on exit.
-                            (if (window-live-p calling-window)
-                                (if (eq (window-buffer calling-window) calling-buffer)
-                                    ;; Calling buffer still on calling window, just select it.
-                                    (select-window calling-window)
-                                  ;; Calling buffer not on calling window, restore it.
-                                  (progn
+                          (when (and agent-shell-on-exit
+                                     (buffer-live-p calling-buffer))
+                            (with-current-buffer calling-buffer
+                              (funcall on-exit))
+                            ;; Give focus back to calling buffer.
+                            (ignore-errors
+                              (if (window-live-p calling-window)
+                                  (if (eq (window-buffer calling-window) calling-buffer)
+                                      (select-window calling-window)
                                     (set-window-buffer calling-window calling-buffer)
                                     (select-window calling-window))))))
                         nil t))
@@ -185,7 +192,8 @@ Arguments:
                     "\\[agent-shell-diff-accept-all] accept  "
                     "\\[agent-shell-diff-reject-all] reject  "
                     "\\[agent-shell-diff-open-file] open  "
-                    "\\[kill-current-buffer] quit")))))
+                    "\\[kill-current-buffer] quit"))))
+          diff-buffer)
       (pop-to-buffer diff-buffer '((display-buffer-use-some-window
                                     display-buffer-same-window))))))
 
diff --git a/agent-shell-heartbeat.el b/agent-shell-heartbeat.el
@@ -84,12 +84,12 @@ Returns the heartbeat alist with the timer started."
       (map-put! heartbeat :heartbeat-timer
                 (run-at-time 0 (/ 1.0 (map-elt heartbeat :beats-per-second))
                              (lambda ()
-                               (map-put! heartbeat :status 'busy)
-                               (map-put! heartbeat :value
-                                         (1+ (map-elt heartbeat :value)))
-                               (funcall (map-elt heartbeat :on-heartbeat)
-                                        (map-elt heartbeat :value)
-                                        (map-elt heartbeat :status))))))
+                               (when-let ((value (map-elt heartbeat :value)))
+                                 (map-put! heartbeat :status 'busy)
+                                 (map-put! heartbeat :value (1+ value))
+                                 (funcall (map-elt heartbeat :on-heartbeat)
+                                          (map-elt heartbeat :value)
+                                          (map-elt heartbeat :status)))))))
     heartbeat))
 
 (cl-defun agent-shell-heartbeat-stop (&key heartbeat)
diff --git a/agent-shell-ui.el b/agent-shell-ui.el
@@ -50,6 +50,13 @@ NAMESPACE-ID, BLOCK-ID, LABEL-LEFT, LABEL-RIGHT, and BODY are the keys."
         (cons :label-right (agent-shell-ui--string-or-nil label-right))
         (cons :body (agent-shell-ui--string-or-nil body))))
 
+(defun agent-shell-ui--insert-read-only (text)
+  "Insert TEXT as read-only output."
+  (add-text-properties 0 (length text)
+                       '(read-only t front-sticky (read-only))
+                       text)
+  (insert text))
+
 (cl-defun agent-shell-ui-update-fragment (model &key append create-new on-post-process navigation expanded no-undo)
   "Update or add a fragment using MODEL.
 
@@ -121,10 +128,10 @@ For existing blocks, the current expansion state is preserved unless overridden.
           ;; Not found or create-new - insert new block
           (goto-char (point-max))
           (setq padding-start (point))
-          (insert (agent-shell-ui--required-newlines 2))
+          (agent-shell-ui--insert-read-only (agent-shell-ui--required-newlines 2))
           (setq block-start (point))
           (agent-shell-ui--insert-fragment model qualified-id expanded navigation)
-          (insert "\n\n")
+          (agent-shell-ui--insert-read-only "\n\n")
           (setq padding-end (point))))
       (when on-post-process
         (funcall on-post-process))
@@ -444,7 +451,7 @@ When NO-UNDO is non-nil, disable undo recording."
          (t
           (goto-char (point-max))
           (let ((padding-start (point)))
-            (insert (agent-shell-ui--required-newlines 2))
+            (agent-shell-ui--insert-read-only (agent-shell-ui--required-newlines 2))
             (let ((block-start (point)))
               (insert (apply #'propertize text props))
               (list (cons :block (list (cons :start block-start)
diff --git a/agent-shell-usage.el b/agent-shell-usage.el
@@ -46,13 +46,18 @@ context window usage, and cost information after each agent response."
   :type 'boolean
   :group 'agent-shell)
 
-(defcustom agent-shell-show-context-usage-indicator t
-  "Non-nil to show the context usage indicator in the header and mode line.
+(defcustom agent-shell-show-context-usage-indicator 'detailed
+  "Whether and how to show the context usage indicator.
 
-The indicator displays context window usage as a vertical bar character,
-color-coded from green (low) to yellow (high) to red (critical).
+When set to t, displays a vertical bar character indicating
+fill level.  When set to `detailed', displays a numeric format
+like \"➤ 29k/200k (29%%)\".  When nil, no indicator is shown.
+
+Color-coded: green (low), yellow (high), red (critical).
 Only appears when the ACP server provides usage information."
-  :type 'boolean
+  :type '(choice (const :tag "Hidden" nil)
+                 (const :tag "Bar" t)
+                 (const :tag "Detailed" detailed))
   :group 'agent-shell)
 
 (cl-defun agent-shell--save-usage (&key state acp-usage)
@@ -192,9 +197,49 @@ When MULTILINE is non-nil, format as right-aligned labeled rows."
                    'font-lock-face 'font-lock-comment-face)
        cost))))
 
+(defun agent-shell--context-usage-face (percentage)
+  "Return the face for context usage at PERCENTAGE.
+Green for normal, yellow for warning, red for critical."
+  (cond
+   ((>= percentage 85) 'error)
+   ((>= percentage 60) 'warning)
+   (t 'success)))
+
+(defun agent-shell--context-usage-indicator-bar (usage context-used context-size)
+  "Return a bar indicator for context USAGE.
+CONTEXT-USED and CONTEXT-SIZE are token counts."
+  (let* ((percentage (/ (* 100.0 context-used) context-size))
+         (indicator (cond
+                     ((>= percentage 100) "█")
+                     ((>= percentage 87.5) "▇")
+                     ((>= percentage 75) "▆")
+                     ((>= percentage 62.5) "▅")
+                     ((>= percentage 50) "▄")
+                     ((>= percentage 37.5) "▃")
+                     ((>= percentage 25) "▂")
+                     ((> percentage 0) "▁")
+                     (t nil))))
+    (when indicator
+      (propertize indicator
+                  'face (agent-shell--context-usage-face percentage)
+                  'help-echo (agent-shell--format-usage usage)))))
+
+(defun agent-shell--context-usage-indicator-detailed (usage context-used context-size)
+  "Return a detailed indicator for context USAGE.
+CONTEXT-USED and CONTEXT-SIZE are token counts.
+Format: \"29k/200k (29%)\"."
+  (let ((percentage (/ (* 100.0 context-used) context-size)))
+    (propertize (format "%s/%s (%.0f%%%%)"
+                        (agent-shell--format-number-compact context-used)
+                        (agent-shell--format-number-compact context-size)
+                        percentage)
+                'face (agent-shell--context-usage-face percentage)
+                'help-echo (agent-shell--format-usage usage))))
+
 (defun agent-shell--context-usage-indicator ()
-  "Return a single character indicating context usage percentage.
-Uses Unicode vertical block characters to show fill level.
+  "Return a string indicating context usage percentage.
+Dispatches to bar or detailed indicator based on
+`agent-shell-show-context-usage-indicator'.
 Only returns an indicator if enabled and usage data is available."
   (when-let* ((agent-shell-show-context-usage-indicator)
               ((agent-shell--usage-has-data-p (map-elt (agent-shell--state) :usage)))
@@ -206,26 +251,11 @@ Only returns an indicator if enabled and usage data is available."
         (propertize "?"
                     'face 'warning
                     'help-echo (agent-shell--format-usage usage))
-      (let* ((percentage (/ (* 100.0 context-used) context-size))
-             ;; Unicode vertical block characters from empty to full
-             (indicator (cond
-                         ((>= percentage 100) "█")  ; Full
-                         ((>= percentage 87.5) "▇")
-                         ((>= percentage 75) "▆")
-                         ((>= percentage 62.5) "▅")
-                         ((>= percentage 50) "▄")
-                         ((>= percentage 37.5) "▃")
-                         ((>= percentage 25) "▂")
-                         ((> percentage 0) "▁")
-                         (t nil)))  ; Return nil for no usage
-             (face (cond
-                    ((>= percentage 85) 'error)         ; Red for critical
-                    ((>= percentage 60) 'warning)       ; Yellow/orange for warning
-                    (t 'success))))                     ; Green for normal
-        (when indicator
-          (propertize indicator
-                      'face face
-                      'help-echo (agent-shell--format-usage usage)))))))
+      (pcase agent-shell-show-context-usage-indicator
+        ('detailed
+         (agent-shell--context-usage-indicator-detailed usage context-used context-size))
+        (_
+         (agent-shell--context-usage-indicator-bar usage context-used context-size))))))
 
 (provide 'agent-shell-usage)
 ;;; agent-shell-usage.el ends here
diff --git a/agent-shell-viewport.el b/agent-shell-viewport.el
diff --git a/agent-shell.el b/agent-shell.el
diff --git a/tests/agent-shell-diff-tests.el b/tests/agent-shell-diff-tests.el
diff --git a/tests/agent-shell-tests.el b/tests/agent-shell-tests.el
