feat(hooks): add PermissionRequest hook for external approval workflows

src/kimi_cli/app.py

@@ -255,6 +255,7 @@ async def create(
         hook_engine = HookEngine(config.hooks, cwd=str(session.work_dir))
         soul.set_hook_engine(hook_engine)
         runtime.hook_engine = hook_engine
+        runtime.approval.set_hook_engine(hook_engine)
 
         return KimiCLI(soul, runtime, env_overrides)
 

src/kimi_cli/hooks/config.py

@@ -16,6 +16,7 @@
     "PreCompact",
     "PostCompact",
     "Notification",
+    "PermissionRequest",
 ]
 
 HOOK_EVENT_TYPES: list[str] = list(HookEventType.__args__)  # type: ignore[attr-defined]

src/kimi_cli/hooks/events.py

@@ -188,3 +188,23 @@ def notification(
         "body": body,
         "severity": severity,
     }
+
+
+def permission_request(
+    *,
+    session_id: str,
+    cwd: str,
+    tool_name: str,
+    tool_input: dict[str, Any],
+    tool_call_id: str = "",
+    action: str = "",
+    description: str = "",
+) -> dict[str, Any]:
+    return {
+        **_base("PermissionRequest", session_id, cwd),
+        "tool_name": tool_name,
+        "tool_input": tool_input,
+        "tool_call_id": tool_call_id,
+        "action": action,
+        "description": description,
+    }

src/kimi_cli/hooks/runner.py

@@ -12,7 +12,7 @@
 class HookResult:
     """Result of a single hook execution."""
 
-    action: Literal["allow", "block"] = "allow"
+    action: Literal["allow", "block", "ask"] = "allow"
     reason: str = ""
     stdout: str = ""
     stderr: str = ""
@@ -75,10 +75,28 @@ async def run_hook(
             if isinstance(raw, dict):
                 parsed = cast(dict[str, Any], raw)
                 hook_output = cast(dict[str, Any], parsed.get("hookSpecificOutput", {}))
-                if hook_output.get("permissionDecision") == "deny":
+                decision = hook_output.get("permissionDecision") or hook_output.get("decision")
+                if decision == "deny":
                     return HookResult(
                         action="block",
-                        reason=str(hook_output.get("permissionDecisionReason", "")),
+                        reason=str(hook_output.get("permissionDecisionReason", hook_output.get("reason", ""))),
+                        stdout=stdout,
+                        stderr=stderr,
+                        exit_code=0,
+                    )
+                elif decision == "ask":
+                    # Explicitly ask user in terminal
+                    return HookResult(
+                        action="ask",
+                        reason=str(hook_output.get("reason", "")),
+                        stdout=stdout,
+                        stderr=stderr,
+                        exit_code=0,
+                    )
+                elif decision == "allow":
+                    return HookResult(
+                        action="allow",
+                        reason=str(hook_output.get("reason", "")),
                         stdout=stdout,
                         stderr=stderr,
                         exit_code=0,

src/kimi_cli/soul/approval.py

@@ -2,7 +2,7 @@
 
 import uuid
 from collections.abc import Callable
-from typing import Literal
+from typing import TYPE_CHECKING, Literal
 
 from kimi_cli.approval_runtime import (
     ApprovalCancelledError,
@@ -15,6 +15,9 @@
 from kimi_cli.utils.logging import logger
 from kimi_cli.wire.types import DisplayBlock
 
+if TYPE_CHECKING:
+    from kimi_cli.hooks.engine import HookEngine
+
 type Response = Literal["approve", "approve_for_session", "reject"]
 
 
@@ -76,17 +79,22 @@ def __init__(
         *,
         state: ApprovalState | None = None,
         runtime: ApprovalRuntime | None = None,
+        hook_engine: HookEngine | None = None,
     ):
         self._state = state or ApprovalState(yolo=yolo)
         self._runtime = runtime or ApprovalRuntime()
+        self._hook_engine = hook_engine
 
     def share(self) -> Approval:
         """Create a new approval queue that shares state (yolo + auto-approve)."""
-        return Approval(state=self._state, runtime=self._runtime)
+        return Approval(state=self._state, runtime=self._runtime, hook_engine=self._hook_engine)
 
     def set_runtime(self, runtime: ApprovalRuntime) -> None:
         self._runtime = runtime
 
+    def set_hook_engine(self, hook_engine: HookEngine) -> None:
+        self._hook_engine = hook_engine
+
     @property
     def runtime(self) -> ApprovalRuntime:
         return self._runtime
@@ -138,6 +146,70 @@ async def request(
         if action in self._state.auto_approve_actions:
             return ApprovalResult(approved=True)
 
+        # --- PermissionRequest hook ---
+        if self._hook_engine is not None:
+            from pathlib import Path
+
+            from kimi_cli.hooks import events
+            from kimi_cli.soul.toolset import _get_session_id
+
+            # Build tool_input from action and description
+            tool_input: dict = {"action": action, "description": description}
+
+            hook_results = await self._hook_engine.trigger(
+                "PermissionRequest",
+                matcher_value=tool_call.function.name,
+                input_data=events.permission_request(
+                    session_id=_get_session_id(),  # Use actual CLI session id
+                    cwd=str(Path.cwd()),
+                    tool_name=tool_call.function.name,
+                    tool_input=tool_input,
+                    tool_call_id=tool_call.id,
+                    action=action,
+                    description=description,
+                ),
+            )
+
+            # Aggregate results: block takes priority, then allow, then ask
+            # Timeouts/errors result in "ask" (fall back to terminal approval)
+            has_explicit_allow = False
+            allow_reason = ""
+            has_block = False
+            block_reason = ""
+
+            for result in hook_results:
+                if result.action == "block":
+                    # Block takes highest priority - check action, not reason
+                    has_block = True
+                    block_reason = result.reason
+                    break
+                elif result.action == "allow" and not result.timed_out and result.exit_code == 0:
+                    # Allow only if:
+                    # - no block found
+                    # - not timed out (timed-out hooks return action="allow")
+                    # - exit_code is 0 (errors/crashes return action="allow" with non-zero exit)
+                    has_explicit_allow = True
+                    allow_reason = result.reason
+                # result.action == "ask" or timeout/error/crash: continue to check other results
+
+            if has_block:
+                logger.debug(
+                    "PermissionRequest hook denied {tool_name}: {reason}",
+                    tool_name=tool_call.function.name,
+                    reason=block_reason,
+                )
+                return ApprovalResult(
+                    approved=False,
+                    feedback=block_reason or "Denied by PermissionRequest hook",
+                )
+            elif has_explicit_allow:
+                logger.debug(
+                    "PermissionRequest hook allowed {tool_name}",
+                    tool_name=tool_call.function.name,
+                )
+                return ApprovalResult(approved=True)
+            # If no explicit decision or only "ask"/timeouts, continue to terminal approval
+
         request_id = str(uuid.uuid4())
         display_blocks = display or []
         source = get_current_approval_source_or_none() or ApprovalSource(