permission

type CreatePermissionRequest struct {
	SessionID               string `json:"session_id"`
	ToolName                string `json:"tool_name"`
	Description             string `json:"description"`
	Action                  string `json:"action"`
	Params                  any    `json:"params"`
	Path                    string `json:"path"`
	RequireExplicitApproval bool   `json:"require_explicit_approval,omitempty"`
	// NeverAutoApprove makes the request immune to every automatic grant:
	// per-session auto-approve, global auto-approve (yolo, headless modes) and
	// "allow for session" grants that do not carry the same non-empty
	// GrantKey. Only an explicit answer approves it, and when nobody is
	// subscribed to answer, it is denied at once. Session handlers (ACP, AG-UI)
	// receive the flag and must honour it.
	NeverAutoApprove bool `json:"never_auto_approve,omitempty"`
	// Justification is the agent's reason for the request (shown by UIs).
	Justification string `json:"justification,omitempty"`
	// GrantKey narrows an "allow for session" grant of this request: a stored
	// grant only matches later requests with the same tool, action, path and
	// GrantKey. Empty keeps the historical tool/action/path scope.
	GrantKey string `json:"grant_key,omitempty"`
}

type PermissionRequest struct {
	ID          string `json:"id"`
	SessionID   string `json:"session_id"`
	ToolName    string `json:"tool_name"`
	Description string `json:"description"`
	Action      string `json:"action"`
	Params      any    `json:"params"`
	Path        string `json:"path"`
	// The fields below mirror CreatePermissionRequest so UIs can render the
	// request (warning style, justification, what a session grant covers).
	RequireExplicitApproval bool   `json:"require_explicit_approval,omitempty"`
	NeverAutoApprove        bool   `json:"never_auto_approve,omitempty"`
	Justification           string `json:"justification,omitempty"`
	GrantKey                string `json:"grant_key,omitempty"`
}

type Service interface {
	pubsub.Suscriber[PermissionRequest]
	GrantPersistant(permission PermissionRequest)
	Grant(permission PermissionRequest)
	Deny(permission PermissionRequest)
	Request(opts CreatePermissionRequest) bool
	// RequestWithContext is Request bound to the caller's context. When ctx
	// ends before an answer arrives, the request fails closed (returns false)
	// instead of blocking the calling tool's goroutine forever. Tools should
	// prefer it and pass their own ctx; Request is the context.Background()
	// shorthand kept for the call sites that have none.
	RequestWithContext(ctx context.Context, opts CreatePermissionRequest) bool
	AutoApproveSession(sessionID string)
	RemoveAutoApproveSession(sessionID string)
	RequireExplicitApprovalSession(sessionID string)
	RemoveExplicitApprovalSession(sessionID string)
	SetGlobalAutoApprove(enabled bool)
	// RegisterSessionHandler installs a custom approval function for a specific session.
	// When set, this handler is called instead of the TUI dialog for that session.
	// The handler receives the full CreatePermissionRequest and returns true to approve.
	RegisterSessionHandler(sessionID string, handler func(req CreatePermissionRequest) bool)
	// UnregisterSessionHandler removes the custom handler for a session.
	UnregisterSessionHandler(sessionID string)
	// IsAutoApproveSession reports whether the given session is currently in
	// auto-approve ("auto mode") state.
	IsAutoApproveSession(sessionID string) bool
	// PendingRequests returns the permission requests that have been published
	// for a session and are still awaiting a response. Used to replay prompts to
	// clients (e.g. the Web UI) that reconnect to a session stream.
	PendingRequests(sessionID string) []PermissionRequest
}