Add issue-fields: read permission scope

docs/src/content/docs/reference/permissions.md

@@ -24,6 +24,7 @@ Key read permission scopes include:
 
 - `contents` (code access)
 - `issues` (issue management)
+- `issue-fields` (org issue field definitions and values — see below)
 - `pull-requests` (PR management)
 - `discussions` (discussions and comments)
 - `actions` (workflow control)
@@ -40,6 +41,27 @@ See [GitHub's permissions reference](https://docs.github.com/en/actions/using-jo
 - **`read-all`**: Read access to all scopes (useful for inspection workflows)
 - **`{}`**: No permissions (for computation-only workflows)
 
+### Permission: `issue-fields: read`
+
+The `issue-fields: read` permission grants read access to organization issue field definitions and issue-specific field values. It is required when your workflow uses the GitHub API to:
+
+- Query org-scoped issue field metadata (e.g., `list_issue_fields`, `list_issue_types`)
+- Read issue field values for a specific issue (e.g., `GET /repos/{owner}/{repo}/issues/{issue_number}/issue-field-values`)
+
+Without this permission, those API calls will return empty results or permission errors even when `issues: read` is present.
+
+```yaml wrap
+# Example: Read issue field definitions and values
+permissions:
+  contents: read
+  issues: read
+  issue-fields: read
+```
+
+> **Least-privilege guidance:** Only request `issue-fields: read` when the workflow needs to discover or read org issue field definitions or values. For workflows that only manage issue text, labels, or comments, `issues: read` or `issues: write` is sufficient.
+
+See [GitHub's documentation on issue fields](https://docs.github.com/en/rest/orgs/issue-fields) for the REST API reference.
+
 ### GitHub App-Only Permissions
 
 Certain permission scopes require [additional authentication](/gh-aw/reference/github-tools/#additional-authentication-for-github-tools). These include:

pkg/workflow/dangerous_permissions_validation_test.go

@@ -153,7 +153,7 @@ func TestFindWritePermissions(t *testing.T) {
 		{
 			name:               "write-all shorthand",
 			permissions:        NewPermissionsWriteAll(),
-			expectedWriteCount: 15,  // All GitHub Actions permission scopes except id-token and metadata (which are excluded)
+			expectedWriteCount: 16,  // All GitHub Actions permission scopes except id-token and metadata (which are excluded)
 			expectedScopes:     nil, // Don't check specific scopes for shorthand
 		},
 		{

pkg/workflow/permissions.go

@@ -66,6 +66,7 @@ const (
 	PermissionDiscussions         PermissionScope = "discussions"
 	PermissionIdToken             PermissionScope = "id-token"
 	PermissionIssues              PermissionScope = "issues"
+	PermissionIssueFields         PermissionScope = "issue-fields"
 	PermissionMetadata            PermissionScope = "metadata"
 	PermissionModels              PermissionScope = "models"
 	PermissionPackages            PermissionScope = "packages"
@@ -138,6 +139,7 @@ func GetAllPermissionScopes() []PermissionScope {
 		PermissionDiscussions,
 		PermissionIdToken,
 		PermissionIssues,
+		PermissionIssueFields,
 		PermissionMetadata,
 		PermissionModels,
 		PermissionPackages,

pkg/workflow/permissions_enum_test.go

@@ -365,6 +365,7 @@ func TestPermissionsScopeEnumValidation(t *testing.T) {
 		"deployments",
 		"discussions",
 		"id-token",
+		"issue-fields",
 		"issues",
 		"packages",
 		"pages",

pkg/workflow/permissions_operations_test.go

@@ -429,6 +429,7 @@ func TestPermissionsMerge(t *testing.T) {
 				PermissionChecks:              PermissionRead,
 				PermissionDeployments:         PermissionRead,
 				PermissionDiscussions:         PermissionRead,
+				PermissionIssueFields:         PermissionRead,
 				PermissionIssues:              PermissionRead,
 				PermissionMetadata:            PermissionRead,
 				PermissionPackages:            PermissionRead,
@@ -455,6 +456,7 @@ func TestPermissionsMerge(t *testing.T) {
 				PermissionDeployments:         PermissionWrite,
 				PermissionDiscussions:         PermissionWrite,
 				PermissionIdToken:             PermissionWrite, // id-token supports write
+				PermissionIssueFields:         PermissionWrite,
 				PermissionIssues:              PermissionWrite,
 				PermissionMetadata:            PermissionWrite,
 				PermissionPackages:            PermissionWrite,
@@ -479,6 +481,7 @@ func TestPermissionsMerge(t *testing.T) {
 				PermissionChecks:              PermissionRead,
 				PermissionDeployments:         PermissionRead,
 				PermissionDiscussions:         PermissionRead,
+				PermissionIssueFields:         PermissionRead,
 				PermissionIssues:              PermissionRead,
 				PermissionMetadata:            PermissionRead,
 				PermissionPackages:            PermissionRead,
@@ -506,6 +509,7 @@ func TestPermissionsMerge(t *testing.T) {
 				PermissionDeployments:         PermissionWrite,
 				PermissionDiscussions:         PermissionWrite,
 				PermissionIdToken:             PermissionWrite, // id-token supports write
+				PermissionIssueFields:         PermissionWrite,
 				PermissionMetadata:            PermissionWrite,
 				PermissionPackages:            PermissionWrite,
 				PermissionPages:               PermissionWrite,

pkg/workflow/permissions_scope_validation_test.go

@@ -40,6 +40,14 @@ pull-requests: read`,
   issues: write`,
 			wantErr: false,
 		},
+		{
+			name: "issue-fields read is a valid scope",
+			yaml: `permissions:
+  contents: read
+  issues: read
+  issue-fields: read`,
+			wantErr: false,
+		},
 		{
 			name:        "typo in scope name suggests correction",
 			yaml:        `contnts: read`,