Skip to content

fix(host): a workflow token widened outside every agent job is not counted as what the agent may do (#1011) - #1138

Merged
pengfei-threemoonslab merged 4 commits into
mainfrom
claude/issue-1011-workflow-job-scope
Nov 14, 2026
Merged

pengfei-threemoonslab merged 4 commits into
mainfrom
claude/issue-1011-workflow-job-scope

Conversation

@pengfei-threemoonslab

Copy link
Copy Markdown
Contributor

Closes #1011

What was wrong

A workflow whose agent job (analyze, anthropics/claude-code-action, contents: read, issues: read) gains a sibling job that runs no agent (publish, issues: write, run: echo) printed:

⚠ high  widened  github .github/workflows/agent.yml
                access: read, analyze: contents: read, analyze: issues: read, on: issues → access: write, analyze: contents: read, analyze: issues: read, publish: issues: write, on: issues
                grants write permissions to workflow jobs; an agent runs at analyze/steps[0] (anthropics/claude-code-action) beside the untrusted-input trigger issues and the secret ANTHROPIC_API_KEY

1 change(s), 1 widening what the agent may do (⚠).

The Claude Code Stop hook put the same row under "These rows widen what the agent can do". The job cells and the #823 note were right, and the token declaration did widen. But the agent job's token was byte-for-byte unchanged, so the summary claimed more than the job-level facts showed.

What changes (Option A: fix the claim, not the gate)

On the issue's reproduction this branch prints:

⚠ high  widened  github .github/workflows/agent.yml
                access: read, analyze: contents: read, analyze: issues: read, on: issues → access: write, analyze: contents: read, analyze: issues: read, publish: issues: write, on: issues
                grants write permissions to workflow jobs; publish gained the write scope issues, and this audit finds no agent launch or reusable workflow call in that job; analyze (agent launch) kept its token; widens a workflow job's token outside any agent job; an agent runs at analyze/steps[0] (anthropics/claude-code-action) beside the untrusted-input trigger issues and the secret ANTHROPIC_API_KEY

1 change(s), 1 widening a workflow job's token outside any agent job (⚠).

Compared with main's diff --json on the same repro, only the row's why and the review change's why differ. review.summary is still {changes: 1, rows: 1, widenings: 1}.

  • Engine, one predicate. workflow_widening_outside_agent_jobs(before, after) lives in core/host_grants.py, beside the workflow branch of host_grant_expansion_signals. That branch is now the shared helpers _workflow_expansion_signals and _gained_workflow_writes, so the signal and the predicate read one computation. The predicate fails closed. It returns None, which counts the change as the agent's, unless all of these hold:

    • both sides publish permission_contexts. A legacy grant counts as the agent's.
    • the change's only expansion signal is workflow_write_*. So pull_request_target, secrets: inherit and workflow_agent_widened_* each keep the change the agent's.
    • no job holds write-all on either side.
    • no step reference moved between jobs.
    • every gained write scope is in a job where the audit finds none of these, on either side: an agent launch (read or unread, unread_agent_runs), a reusable workflow call, or unreadable steps.
    • every job that does have one of those is present on both sides and declares its token explicitly. Its declaration, its effective write scopes and its reusable call are all unchanged. So a scope inherited from the workflow's permissions, an agent job on repository defaults, and an agent job new in the change each keep it the agent's.

    A workflow where the audit finds none of those in any job gets the same label.

  • Rows (core/capability_diff_rows.py). An expanding workflow row reads the predicate and appends to its why:

    • the jobs and the scopes they gained;
    • the possible agent jobs that kept their tokens;
    • the clause OUTSIDE_AGENT_JOBS = "widens a workflow job's token outside any agent job".

    This reuses the Hook, MCP server, plugin, permission-mode and sandbox edits are labelled widenings even when they narrow or disable #820 DIRECTION_UNKNOWN mechanism: a defined whole ; clause, which widens_outside_agent_jobs(expands, why) reads. The renderer derives nothing itself.

  • diff summary (cli/diff.py). Such changes are counted apart, e.g. 2 change(s), 1 widening what the agent may do, 1 widening a workflow job's token outside any agent job (⚠). The two counts add up to review.summary.widenings.

  • Stop hook (cli/install_hooks.py). The generated script renders OUTSIDE_AGENT_JOBS at install time and lists those rows under These rows widen a workflow job's token outside any agent job:. It still announces them, and the announcement digest is unchanged.

  • Unchanged: expands, direction, severity, cells, drift expansion_signals, check decisions and violations, verify gates and control state, baselines, grant ids and every JSON shape. No field or schema is added. The PR comment renderer and review_question already said "declared capability change"; I confirmed that and did not touch them.

Surface discipline

No new surface: no command, schema version, JSON field or summary block. This edits the wording of the existing capability_diff surface and of the Stop hook. The capability_diff row in docs/distribution-surfaces.md and its note in tests/test_distribution_surface_parity.py are updated. The metric it moves is noise rate: a non-agent publisher job no longer reads as an agent widening.

Tests

tests/test_workflow_job_scoped_widening.py (new, 32 cases, measured into tests/shard_seconds.json as a supplemental increment):

  • The issue's YAML: diff --json, the diff text, drift signals, check agent-boundary-json, the verify verifier.json row and summary, and the Stop hook.
  • Fail-closed controls, each of which must still read as the agent's:
    • the agent job gains a scope, alone or beside the publisher;
    • a workflow-level scope the agent job inherits;
    • a job with an unread claude run gains;
    • a reusable call raises its ceiling;
    • a reusable call is retargeted;
    • write-all;
    • the agent job is on repository defaults;
    • the agent job is new;
    • an agent launch moves into the publisher;
    • a step reference moves between jobs;
    • unreadable steps;
    • pull_request_target;
    • secrets: inherit;
    • a gained bypassPermissions rule;
    • a legacy grant.
  • Positives:
    • a workflow default only a non-agent job inherits;
    • unchanged unread-run and reusable-call jobs named as keeping their tokens;
    • an agent-less workflow, changed or added: the row, the diff text and the hook.
  • Both kinds together: the diff summary adds up to review.summary.widenings. The Stop hook gives each kind its own heading, and a look-alike clause in parentheses does not match. The rendered hook holds the engine's constant.

tests/test_actions_token_scope.py::test_control_an_ordinary_job_write_grant_still_widens pinned the exact why of an agent-less workflow. Its expectation now includes the new clauses. It still widens.

Coordination notes

  • Rendered hook script. The rendered hook script's bytes change: a new rendered constant and the split in _route_host_diff. No render-hash or prior-hash list pins the hook script, so nothing needs recomputing. The new constant sits after DIRECTION_UNKNOWN, clear of fix(trust): check and the Claude Code hook protect a declared policy pack (#1128) #1130's hunks.

  • Expected conflicts with fix(host): a tightened deny or ask rule is not a widening; lifted denials rate by what they restricted (#1036) #1136 (checked with git merge-tree):

    • the ## Unreleased → ### Host comparison heading in CHANGELOG.md;
    • the STABILITY insertion point;
    • the one-line capability_diff row in docs/distribution-surfaces.md.

    host_grants.py, capability_diff_rows.py, docs/quickstart.md and the parity test merge cleanly. Against fix(trust): check and the Claude Code hook protect a declared policy pack (#1128) #1130, only CHANGELOG.md and STABILITY.md conflict, both at the insertion point; install_hooks.py and tests/shard_seconds.json merge cleanly. Whichever PR merges second keeps both sides.

  • Local gate: pytest -m "not perf" -n auto -rfEs with the lock venv (pydantic 2.14.3) gave 2 failed, 24097 passed, 16 skipped, 120 xfailed. Both failures are tests/test_check_unmodelled_host_config_keys.py[local_settings_enabled_plugins-worktree|git_range], the known local XDG git-ignore failure: the fixture's base git commit exits 1. ruff check . is clean, and scripts/generate_schemas.py --check is clean under the lock venv.

  • Protected paths: none touched (.github/, pyproject.toml, constraints/, AGENTS.md, CLAUDE.md, frozen schemas).

Written by Claude Code (Opus 5.5). The main session reviews the diff.

🤖 Generated with Claude Code

…unted as what the agent may do (#1011)

A workflow whose agent job (`analyze`, claude-code-action, `contents: read`,
`issues: read`) gained a sibling job that runs no agent (`publish`,
`issues: write`) printed `1 change(s), 1 widening what the agent may do (⚠).`,
and the Stop hook listed the row under "These rows widen what the agent can
do", while the agent job's token was byte-for-byte unchanged.

Fix the claim, not the gate. One engine predicate,
`workflow_widening_outside_agent_jobs` in core/host_grants.py, computed
beside the workflow branch of host_grant_expansion_signals (now the shared
`_workflow_expansion_signals` / `_gained_workflow_writes` helpers), places a
widened workflow change outside every agent job. It fails closed: `None`
(the agent's) unless both sides publish job contexts, the only expansion
signal is `workflow_write_*`, no job holds write-all, no step reference moved
between jobs, every gained write scope is in a job with no agent launch (read
or unread), reusable workflow call or unreadable steps on either side, and
every such job is on both sides, explicit, and kept the same declaration,
effective writes and reusable call. A workflow with none of those anywhere is
placed the same way.

The row reads it: its `why` names the gained scopes and the agent jobs that
kept their tokens and holds the `; ` clause
`widens a workflow job's token outside any agent job`
(capability_diff_rows.OUTSIDE_AGENT_JOBS), as DIRECTION_UNKNOWN is a clause
(#820). `diff`'s summary counts such a change apart
(`1 widening a workflow job's token outside any agent job (⚠)`), the counts
adding up to review.summary.widenings, and the generated Stop hook, which
renders the clause at install time, names those rows under their own heading.

`expands`, direction, severity, cells, drift signals, check decisions,
verify gates, baselines, grant ids and every JSON shape are unchanged.

Docs: CHANGELOG (Host comparison), a STABILITY migration note, the
capability_diff registry row and its parity-test note, docs/integrations.md
and docs/quickstart.md on the marker. New test file measured into
tests/shard_seconds.json as a supplemental increment.
CHANGELOG (Unreleased, Host comparison) and a STABILITY migration note
state what moved: the row's why clause, diff's split summary and the Stop
hook heading, and what did not (expands, direction, severity, signals,
gates, JSON shape). The capability_diff registry row and its parity-test
note name the predicate and its test; docs/integrations.md and
docs/quickstart.md say a workflow-job widening outside any agent job is
still marked and counted apart.
Conflicts: CHANGELOG.md keeps both Unreleased entries (Host comparison,
then #1130's Changes); STABILITY.md keeps both migration notes, #1011's
above #1128's. install_hooks.py auto-merged; its diff against main is the
branch's own change, unaltered.
@pengfei-threemoonslab
pengfei-threemoonslab merged commit 1cccb88 into main Nov 14, 2026
16 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Host diff counts a separate non-agent job's write scope as widening what the agent may do

1 participant