Default agent-shell-start wrapper and Emacs-native bootstrapping

[robjgray]

Description

This provides a 'batteries included' wrapper for starting agent-shell and an Emacs-native bootstrap option. Users can still point it at a fully custom starter if they want.

Main changes

• Adds meta-agent-shell-setup as an Emacs-native alternative to the current setup script
• Adds a package-owned default wrapper around agent-shell-start
• Preserves the startup behavior meta-agent-shell expects for:
  • buffer naming
  • project-root vs current-directory startup
  • the internal 'use-current-dir path used for programmatic named-agent starts
• Adds package-owned customization points for ergonomic editing of the startup wrapper
  • Codex defaults rely on a pre-release agent-shell variable. Latest version 0.46.1 specified for now.
• Updates README docs for setup and customization
• Adds focused test coverage for these changes

Additional changes

• Updated meta-agent-shell-test-ask-session
• Made the following tests more durable in sandboxed environments:
  • meta-agent-shell-test-view-session
  • meta-agent-shell-test-close-session
  • meta-agent-shell-test-full-workflow

Maintainer notes

• The default wrapper is based on the maintainer’s starter which was referenced in code. EDIT My general approach on the customization points was "would this or other common use cases be possible and ergonomic." @ElleNajt if I missed some necessary details or style preferences, I'm happy to make changes. Users who prefer their own starter can still do something like:

(setq meta-agent-shell-start-function
      #'my/agent-shell-anthropic-start-claude-code)

• I considered taking additional steps to make this more agent-agnostic, but figured it would be better as its own effort.

Type of Changes

• Bug fix
• New feature
• Documentation update
• Code refactoring

Related Issues

Fixes #1

Testing

• Unit tests added/updated
• Manual testing performed

Ran:

emacs -Q -batch -L . -l ert -l meta-agent-shell-test.el -f ert-run-tests-batch-and-exit

[ElleNajt]

Thanks for the PR! I'm a bit busy atm but will take a look asap.

[ElleNajt]

Thanks for this! Couple bits of feedback:

• ty for the buffer return bugfix :)
• meta-agent-shell--session-policy and meta-agent-shell--default-session-policy are defined but never called by anything, can you remove them?
• I'd want the default to be safe, with users opting into aggressive mode explicitly.
  (Per Claude, on a fresh install -- meta-agent-shell-safe-directory-prefixes is nil and meta-agent-shell-session-policy-function is nil, so --session-policy-with-source falls through to (cons 'aggressive :default)...)
• I'm a little bit concerned about the complexity of the policy system. Do you anticipate needing this complexity ? Are you using it in your config? (Very 2026 comment: if feasible, could you have Claude Code with Opus 4.6 look over it and see if it can be simplified?)

Per Claude:

The policy system adds ~6 new functions and 4 new defcustoms to ultimately pick between two mode strings. The call chain is:

  → default-session-mode-function
    → --session-policy-with-source
      → session-policy-function (user defcustom)
      → --directory-safe-p
    → --session-mode-id-for-policy
    → --configured-session-mode-id

I think this could collapse to something like:

(defun meta-agent-shell--resolve-session-mode (config directory)
  (let* ((identifier (map-elt config :identifier))
         (entry (assq identifier meta-agent-shell-session-mode-map))
         (policy (if (meta-agent-shell--directory-safe-p directory) 'safe 'aggressive)))
    (when entry
      (plist-get (cdr entry) (if (eq policy 'safe) :safe :aggressive)))))

That would keep `meta-agent-shell-session-mode-map` and `meta-agent-shell-safe-directory-prefixes` (both useful) but drop `session-policy-function` (YAGNI -- can add when someone needs it) and the source-tracking indirection.

[robjgray]

Thank you for these notes. I'll come up with a simpler approach. I tried to create an abstraction that emulated the agent-shell launcher from your Emacs repo's config. That led to a few "placeholder" elements like a stubbed container mode, which in retrospect aren't adding much.

[robjgray]

@ElleNajt The startup-wrapper customization system is now simpler and more ergonomic:

bind vars, run before hook, start, run after hook

• No placeholder container scaffolding
• No default meanings assigned to prefix args
• Less opinionated about policies and directory-specific behavior
• Preserves provider defaults unless a configurator overrides them
  • This means that for most models, the user has to explicitly opt in to bypassPermissions or full-access etc

The policy customization now I think makes more sense- exact mode IDs like plan for Claude can be specified in a simple way, but we also have a general map that can be expanded for "safe" or "unsafe" modes across providers. A major plus to this is if the mode IDs ever change, users can easily adapt in their own config.

The README.org shows ways these hooks can be used, one of which is from my own config where I tell the Dispatcher about project-specific policies after launch.

I also enhanced M-x meta-agent-shell-setup. It now ensures the support script directory is added to Emacs PATH and exec-path, and the package also adds it on load when that support directory already exists. This fixed an issue I found with setup.sh - it tells users to add the checkout bin/ directory to .bashrc/.zshrc, but that does not reliably mean Emacs-launched agent-shell sessions will inherit a PATH containing those wrappers.

With the current state of M-x meta-agent-shell-setup, I think it is safe to remove setup.sh and document M-x meta-agent-shell-setup as the normal setup path. Let me know your thoughts.