feat(hooks): add on_request_permission hook for external notifications

[ro0gr]

Add a new on_request_permission hook that fires when the agent requests user permission (e.g., for file edits).

This complements the on_response_complete to enable external notification systems (like Ghostty OSC 9) to alert users when their attention is needed, even when they're not looking at the editor.

• update docs

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR introduces a new on_request_permission hook to the agentic.nvim plugin. The feature enables users to implement custom logic when the agent requests permission to execute tools. The hook receives the tool call request along with session and tab identifiers, and is invoked before standard permission handling proceeds. Configuration schema defines the hook contract, session manager wires the invocation into its handler pipeline, tests verify correct behavior, and documentation provides usage examples.

Sequence Diagram

sequenceDiagram
  participant Agent
  participant SessionManager
  participant InvokeHook as P.invoke_hook
  participant Config as UserConfig
  participant PermissionHandler as Handler
  
  Agent->>SessionManager: Request tool execution
  SessionManager->>InvokeHook: invoke_hook("on_request_permission", data)
  InvokeHook->>Config: Lookup hooks.on_request_permission
  alt Hook configured
    Config->>PermissionHandler: Execute on_request_permission(data)
    PermissionHandler->>PermissionHandler: Custom auth logic<br/>(derive label, notify user)
  else Hook not set
    InvokeHook->>InvokeHook: Return nil (no-op)
  end
  InvokeHook->>SessionManager: Return control
  SessionManager->>SessionManager: Apply standard<br/>permission handling

Loading

Possibly related PRs

• carlos-algms/agentic.nvim#158: Extends hook infrastructure by adding on_session_update hook wired into SessionManager, using the same P.invoke_hook dispatch mechanism.
• carlos-algms/agentic.nvim#186: Adds on_create_session_response hook to the shared hook framework in session_manager.lua with similar type updates to P.invoke_hook.
• carlos-algms/agentic.nvim#202: Extends the same hook contract surface in session_manager.lua by updating P.invoke_hook hook name and data type unions for the on_file_edit hook.

Poem

🐰 A new hook hops into view,
When tools need permission—who knew?
With data in paw, session and tab,
Users now author their custom auth stab!
Permission flows smooth, the agent stays true. ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title clearly and concisely summarizes the main change: adding a new hook for permission request notifications.
Description check	✅ Passed	The description accurately explains the purpose of the new hook and its intended use case with external notification systems.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@lua/agentic/session_manager.lua`:
- Around line 980-984: The hook payload uses self.session_id which can be stale;
update the P.invoke_hook call in the on_request_permission flow so the
session_id field comes from the incoming request (use request.sessionId) instead
of self.session_id, keeping tab_page_id as is; ensure you reference
request.sessionId in the payload when calling
P.invoke_hook("on_request_permission", {...}) to avoid misreporting after
session switches.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: b8e82fb1-0745-4a10-942b-858dcf92a9fa

📥 Commits

Reviewing files that changed from the base of the PR and between 994946d and 1e07af2.

📒 Files selected for processing (5)

• README.md
• doc/agentic.txt
• lua/agentic/config_default.lua
• lua/agentic/session_manager.lua
• lua/agentic/session_manager.test.lua

[carlos-algms]

@ro0gr Amazing. I don't know how it didn't come up earlier!