Feature: Permission Decision Center for Auditing, Replay, and Grant Lifecycle Management

[hoangsonww]

Summary

Add a first-class Permission Decision Center that gives users a complete, inspectable view of every permission request, approval, denial, cached grant, blanket flag, and trust-calibration decision across CLI, REPL, and dashboard-driven tasks.

Problem / Opportunity

Forge already treats permissions as a core product primitive: tools call requestPermission, risk and side effects are classified, cached grants persist through SQLite, and the UI can delegate prompts through the interactive host. That is strong runtime enforcement, but operators do not yet have a complete workflow for answering questions like:

• Why did this tool invocation run without prompting?
• Which project/global grants are active right now?
• Which grant allowed a shell/network/file operation?
• What would happen if I replayed this task under stricter permissions?
• Which previously granted permission should be revoked before sharing a workstation or project?

This feature would turn the permission system from a prompt-time control into an auditable security surface.

Proposed Feature

Build a Permission Decision Center available from both CLI and dashboard:

• CLI commands under forge permissions for listing, filtering, explaining, exporting, and revoking grants.
• Dashboard view that shows active grants, historical decisions, denied requests, auto-allowed requests, and decisions made through flags like --allow-shell or --allow-network.
• A per-task permission timeline connected to task/session/event logs.
• An explain mode that traces a decision through blanket flags, persistent grants, trust calibration, non-interactive mode, and risk rules.
• A dry-run/replay mode that evaluates historical tool requests against a proposed permission profile without executing tools.

Scope

Expected implementation areas:

• src/permissions/manager.ts and src/permissions/risk.ts for richer decision reasons.
• src/persistence/index-db.ts for durable permission decision history, not only grants.
• src/cli/commands/permissions.ts for new inspection and revocation commands.
• src/ui/server.ts, src/ui/task-runner.ts, and the vanilla UI shell for dashboard views.
• src/types/index.ts for explicit decision-reason contracts.
• Docs updates in docs/CLI-REFERENCE.md, docs/ARCHITECTURE.md, and setup/security guidance.

Acceptance Criteria

• Every permission decision records a structured reason such as blanket flag, session grant, project grant, global grant, trust calibration, interactive allow, interactive deny, non-interactive deny, or critical hard block.
• forge permissions list can filter by scope, project, tool, risk, side effect, and age.
• forge permissions explain <decision-id> prints the exact decision path without exposing credentials or sensitive targets.
• Users can revoke project/global grants from the CLI and dashboard.
• The dashboard includes a permission timeline for a task, with each tool invocation linked to its decision.
• Replay/dry-run mode can evaluate stored permission requests against current policy without executing tools.
• Exports redact sensitive paths and credentials using existing redaction utilities.
• Unit tests cover decision-reason persistence, revocation, non-interactive behavior, and explain output.

Non-Goals

• Replacing the existing requestPermission gate.
• Allowing critical-risk commands to bypass hard-block behavior.
• Building an enterprise RBAC system in the first iteration.
• Sending permission telemetry to any external service.

Dependencies / Risks

• The decision log must not leak command arguments containing secrets.
• Existing behavior for --skip-permissions, --strict, and non-interactive runs must remain compatible.
• UI and CLI must share the same permission model instead of drifting into separate implementations.
• Persistent decision history needs bounded retention so local databases do not grow without control.

Open Questions

• Should permission decision retention follow the same lifecycle as task/session retention?
• Should exports include denied requests by default, or require an explicit flag?
• Should project/global grants support expiration dates in the first version?
• Should the dashboard allow bulk revocation, or keep revocation one grant at a time for safety?