[JamesPatrickGill]

Problem

An agent asked to turn one feature flag off can silently wipe that flag's targeting, and nothing stops it.

The only tool for the job is update-feature-flag. Its own description tells the agent to read the whole flag, change active, then send everything back. filters is not partial: sending it replaces every release condition, variant, payload and holdout.

Two things turn that from verbose into unsafe.

• The agent cannot ask for conflict protection. FeatureFlagSerializer.update rejects a stale write when the caller sends version and original_flag, and the flag UI sends both on every PATCH. version sits on the excluded list in feature_flag_openapi_test_helpers.py, so it never reaches the tool schema. Any targeting edit made between the agent's read and its write is lost with no error.
• "Disable this flag" and "rewrite this flag's targeting" are the same API call. Nothing at the boundary can refuse the second when the user asked for the first.

The layer below added endpoints that fix this. Until they are turned on, no agent can reach them.

Before, four steps and a targeting payload:

flowchart LR
    Agent{{Agent}} --> Read[feature-flag-get-definition]
    Read --> Snapshot[filters snapshot]
    Snapshot --> Tool[update-feature-flag]
    Tool --> Write[(PATCH active and filters)]
    classDef phBlue fill:#1d4aff,stroke:#1d4aff,color:#fff;
    classDef phRed fill:#f54e00,stroke:#f54e00,color:#fff;
    classDef phYellow fill:#f9bd2b,stroke:#f9bd2b,color:#000;
    classDef phGray fill:#e5e7eb,stroke:#c7ccd1,color:#000;
    class Agent phYellow;
    class Read,Tool phBlue;
    class Snapshot phGray;
    class Write phRed;

Loading

After, one step and no targeting payload:

flowchart LR
    Agent{{Agent}} --> Tool[feature-flag-disable]
    Tool --> Write[(POST, flag id only)]
    classDef phBlue fill:#1d4aff,stroke:#1d4aff,color:#fff;
    classDef phRed fill:#f54e00,stroke:#f54e00,color:#fff;
    classDef phYellow fill:#f9bd2b,stroke:#f9bd2b,color:#000;
    class Agent phYellow;
    class Tool phBlue;
    class Write phRed;

Loading

Changes

• An agent can now enable, disable, archive or unarchive a flag in one call carrying only the flag id, through feature-flag-enable, feature-flag-disable, feature-flag-archive and feature-flag-unarchive.
• Sending targeting through a lifecycle tool is impossible, not merely discouraged. Each generated schema is { id }, because the endpoint declares no request body.
• Each description names the field its action changes and states that the tool never accepts or replaces filters.
• The disable description asks the agent to report linked-consumer impact when the user did not ask for the flag to be turned off. Linked experiments, surveys, early access features and replay settings all appear in the full definition.
• update-feature-flag keeps active and archived for combined edits. Its description now names the dedicated tool when one matches, so an agent has a reason to prefer the narrow call.
• Key resolution points at feature-flag-get-definition-by-key, which asks for at most five flags, rather than feature-flag-get-all, which returns a hundred per page.
• enable warns that a key lookup misses an archived flag. Both resolvers go through the list endpoint, which hides archived rows unless archived is in the query, so an agent would otherwise report the flag missing instead of unarchiving it.

Mechanical: the regenerated Orval schemas, tool handlers, tool-definition JSON and four schema snapshots. disable also joins the trailing-action list, so the compact domain index renders feature-flag rather than feature-flag-disable.

How did you test this code?

Automated only. The eval tasks were not executed.

• feature-flag-lifecycle-tools.test.ts asserts each tool's schema exposes id and nothing else. The schema snapshots would also catch a filters param appearing, but vitest -u silences them and these assertions it cannot.
• The same file asserts each tool posts to its own endpoint. A tool name and its URL come from separate lines of one YAML entry, so nothing else notices feature-flag-enable wired to /disable/. An agent asked to turn a flag on would turn it off.
• It also pins the write scope and the non-destructive, idempotent annotations. A tool cannot quietly become destructive, or drop out of a read-only session's exclusion.
• Five eval tasks cover tool selection for each action plus a targeting edit still choosing update-feature-flag. Their criteria judge the tool chosen and what the agent reports, so they score without a seeded fixture flag. Seeding mcp-eval-lifecycle in the benchmark project would also exercise the state change.

Not checked: no run against a deployed MCP client in either mode.

Automatic notifications

• Publish to changelog?

Docs update

None. The endpoint reference ships with the layer below.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Claude Code (Opus 5) wrote this. It is the top layer of a two-PR stack and depends on the endpoints in the layer below.

Skills invoked: /implementing-mcp-tools, /writing-tests, /writing-user-facing-copy, /review-code --fix, /stacking-prs, /writing-pr-descriptions.

The work started as one PR covering both layers, and was split on review. ci-things-already-tried.md records a rejected stack whose layers corrected each other's lines, so the split was checked against it. Layer 1's tools.yaml stubs carry the final tool names, and scaffold-yaml --sync-all matches on operation rather than the key. This layer only fills each block in. Its ten tools.yaml deletions are the four enabled: false lines and the one description rewritten on purpose.

products/feature_flags/skills/cleaning-up-stale-feature-flags/SKILL.md still points at update-feature-flag for disabling. That was left alone deliberately: the brief puts cleanup-task callers out of scope for this work.

Public artifact: nothing here carries material from the agent session that is not already public. The eval task intents are invented rather than derived, and the planning notes stay outside the repository.

[github-actions]

🤖 CI report

⚠️ Trunk lane — backend Python lane

This PR is assigned to the backend Python lane. It runs backend Python tests and may merge in parallel with PRs in other lanes.

ℹ️ MCP UI apps size — 33 app(s), 17663.3 KB JS

Built size of each MCP UI app (main.js + styles.css).

App	JS	CSS
debug	600.0 KB	195.2 KB
action	458.2 KB	195.2 KB
action-list	564.9 KB	195.2 KB
cohort	457.2 KB	195.2 KB
cohort-list	563.8 KB	195.2 KB
email-template	457.0 KB	195.2 KB
error-details	472.9 KB	195.2 KB
error-issue	457.9 KB	195.2 KB
error-issue-list	564.7 KB	195.2 KB
experiment	562.0 KB	195.2 KB
experiment-list	565.6 KB	195.2 KB
experiment-results	567.1 KB	195.2 KB
feature-flag	567.6 KB	195.2 KB
feature-flag-list	571.4 KB	195.2 KB
feature-flag-testing	461.4 KB	195.2 KB
inline-scan	457.7 KB	195.2 KB
insight-actors	563.0 KB	195.2 KB
invite-email-preview	456.4 KB	195.2 KB
llm-costs	560.0 KB	195.2 KB
session-recording	459.0 KB	195.2 KB
survey	458.8 KB	195.2 KB
survey-global-stats	562.7 KB	195.2 KB
survey-list	565.5 KB	195.2 KB
survey-stats	562.7 KB	195.2 KB
trace-span	457.6 KB	195.2 KB
trace-span-list	564.7 KB	195.2 KB
vision-observation-list	563.9 KB	195.2 KB
workflow	457.5 KB	195.2 KB
workflow-list	564.2 KB	195.2 KB
loops-review	461.9 KB	195.2 KB
query-results	755.4 KB	195.2 KB
render-ui	838.5 KB	195.2 KB
visual-review-snapshots	462.0 KB	195.2 KB

[posthog]

🦔 PostHog Review reviewed this pull request

Found 0 must fix, 1 should fix, 2 consider.

Published 3 findings (view the review).

Resolved comments: 2 fixed, 1 declined, 1 left for you

[greptile-apps]

Prompt To Fix All With AI

### Issue 1
services/mcp/src/tools/generated/feature_flags.ts:128-134
**Lifecycle handlers lack error handling**

The new archive, disable, enable, and unarchive handlers await project lookup and API requests without local error handling. Rejected operations therefore propagate without lifecycle-specific diagnostics, making failures less actionable.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "fix(flags): correct the lifecycle tool d..." | Re-trigger Greptile}

[posthog]

PostHog Review alpha 🦔 If you find any issues helpful - please reply "valid", "invalid", etc., for evaluation purposes 🙏

[posthog]

PostHog Review

Found 1 should fix, 2 consider.

[posthog]

Lifecycle tools accept soft-deleted flags

Why we think it's a valid issue

• Checked: the viewset's base queryset and where deleted is filtered, each lifecycle action's guard clauses, whether an equivalent guard already exists in this viewset, what evaluation does with a deleted flag, how an agent could obtain a deleted flag's ID, and the layer's test coverage.
• Found: detail routes really do resolve soft-deleted flags. queryset = FeatureFlag.objects_including_soft_deleted.all() at products/feature_flags/backend/api/feature_flag.py:3129, with a comment at :3126-3128 stating that non-list actions can access soft-deleted flags, and only the list branch applies queryset.filter(deleted=False) at :3189-3191.
• Found: none of the four actions check deleted. archive (:3591-3604), unarchive (:3620-3627) and _set_active (:3563-3575) go from self.get_object() straight to the facade. The viewset already owns a guard for exactly this — _deleted_flag_rejection at :3367-3379, applied at :3389 and :3425 — so the omission is inconsistent with the local pattern and the fix is two lines per action.
• Found: the misleading-success consequence holds. FeatureFlagManager.get_queryset excludes deleted=True (products/feature_flags/backend/models/feature_flag.py:134-136), and the evaluation/cache paths read through FeatureFlag.objects (products/feature_flags/backend/flags_cache.py:916, products/feature_flags/backend/tasks.py:389), so a deleted flag never evaluates however active reads back. feature-flag-unarchive's promise to restore a flag "to the default flag list" (products/feature_flags/mcp/tools.yaml:266) is also false for a deleted flag, since the list filters it out.
• Found: no coverage. products/feature_flags/backend/api/test/test_feature_flag_lifecycle_actions.py contains no deleted-flag case.
• Impact: a caller holding a deleted flag's numeric ID gets 200 and active: true for a flag that serves nobody, or a reported restore that leaves the flag invisible. Nothing in the response or the description corrects that, which is why this stays valid rather than being dismissed as already-handled.
• Priority: lowered to consider. The same behavior already exists on the tool these replace — partial_update (:3136-3138) adds no guard either, so update-feature-flag can enable a deleted flag on master today. Every lookup the new descriptions recommend is list-backed (feature-flag-get-all, and feature-flag-get-definition-by-key via the list endpoint), so both hide deleted flags and an agent has to be carrying a stale ID from an earlier turn or one the user supplied. Nothing is corrupted and the write is reversible, so the ceiling is a wrong report on a rare input rather than the should_fix impact claimed.

Issue description

The lifecycle endpoints can resolve soft-deleted flags and do not reject deleted: true. Enable can return active: true, but evaluation still excludes the flag. Unarchive can return success, but the default list still excludes it. A caller with an old numeric ID receives a successful result for an unusable flag.

Suggested fix

Reject deleted flags in every lifecycle endpoint. If restoration is supported, add a dedicated restore action and require it before enable or unarchive. Add tests for all four actions with a deleted flag.

Prompt to fix with AI (copy-paste)

## Context
@products/feature_flags/mcp/tools.yaml#L178-191
@products/feature_flags/mcp/tools.yaml#L264-275

<issue_description>
The lifecycle endpoints can resolve soft-deleted flags and do not reject `deleted: true`. Enable can return `active: true`, but evaluation still excludes the flag. Unarchive can return success, but the default list still excludes it. A caller with an old numeric ID receives a successful result for an unusable flag.
</issue_description>

<issue_validation>
- **Checked:** the viewset's base queryset and where `deleted` is filtered, each lifecycle action's guard clauses, whether an equivalent guard already exists in this viewset, what evaluation does with a deleted flag, how an agent could obtain a deleted flag's ID, and the layer's test coverage.
- **Found:** detail routes really do resolve soft-deleted flags. `queryset = FeatureFlag.objects_including_soft_deleted.all()` at `products/feature_flags/backend/api/feature_flag.py:3129`, with a comment at `:3126-3128` stating that non-list actions can access soft-deleted flags, and only the `list` branch applies `queryset.filter(deleted=False)` at `:3189-3191`.
- **Found:** none of the four actions check `deleted`. `archive` (`:3591-3604`), `unarchive` (`:3620-3627`) and `_set_active` (`:3563-3575`) go from `self.get_object()` straight to the facade. The viewset already owns a guard for exactly this — `_deleted_flag_rejection` at `:3367-3379`, applied at `:3389` and `:3425` — so the omission is inconsistent with the local pattern and the fix is two lines per action.
- **Found:** the misleading-success consequence holds. `FeatureFlagManager.get_queryset` excludes `deleted=True` (`products/feature_flags/backend/models/feature_flag.py:134-136`), and the evaluation/cache paths read through `FeatureFlag.objects` (`products/feature_flags/backend/flags_cache.py:916`, `products/feature_flags/backend/tasks.py:389`), so a deleted flag never evaluates however `active` reads back. `feature-flag-unarchive`'s promise to restore a flag "to the default flag list" (`products/feature_flags/mcp/tools.yaml:266`) is also false for a deleted flag, since the list filters it out.
- **Found:** no coverage. `products/feature_flags/backend/api/test/test_feature_flag_lifecycle_actions.py` contains no deleted-flag case.
- **Impact:** a caller holding a deleted flag's numeric ID gets 200 and `active: true` for a flag that serves nobody, or a reported restore that leaves the flag invisible. Nothing in the response or the description corrects that, which is why this stays valid rather than being dismissed as already-handled.
- **Priority:** lowered to `consider`. The same behavior already exists on the tool these replace — `partial_update` (`:3136-3138`) adds no guard either, so `update-feature-flag` can enable a deleted flag on master today. Every lookup the new descriptions recommend is list-backed (`feature-flag-get-all`, and `feature-flag-get-definition-by-key` via the list endpoint), so both hide deleted flags and an agent has to be carrying a stale ID from an earlier turn or one the user supplied. Nothing is corrupted and the write is reversible, so the ceiling is a wrong report on a rare input rather than the `should_fix` impact claimed.
</issue_validation>

## Task
Investigate the issue and solve it

<potential_solution>
Reject deleted flags in every lifecycle endpoint. If restoration is supported, add a dedicated restore action and require it before enable or unarchive. Add tests for all four actions with a deleted flag.
</potential_solution>

[posthog]

This is a real gap, but it belongs to the layer below, not this PR. The behavior the finding describes lives entirely in the lifecycle viewset actions (_set_active, archive, unarchive in products/feature_flags/backend/api/feature_flag.py): they resolve soft-deleted flags and don't reject deleted, unlike the sibling _deleted_flag_rejection guard already used by the usage-dashboard actions. That file ships in the base branch feat/flags-lifecycle-endpoints; this PR only wires the existing endpoints up as MCP tools and changes no backend code, so I can't fix it here without pulling a change into the wrong layer of the stack (the split was deliberate). It also needs a decision I shouldn't make unattended: reject deleted flags in all four actions, or add a dedicated restore action and require it before enable/unarchive — plus the backend tests for a deleted flag that are currently missing. Handing this to a human to land in the endpoints' own PR (or a follow-up) with the design choice made. I did not add a caveat to the tool descriptions instead: it wouldn't correct the misleading success response, and the recommended lookups (feature-flag-get-all, feature-flag-get-definition-by-key) are all list-backed and already hide deleted flags, so an agent can only reach this with a stale id carried from an earlier turn.

[trunk-io]

   

View Full Report ↗︎ ⋅ Docs

[haacked]

Looks good, one non-blocking suggestion inline.

[JamesPatrickGill]

/trunk merge

[trunk-io]

😎 Stack merged successfully - details.

[deployment-status-posthog]

Deploy status

Environment	Status	Deployed At	Workflow
dev	✅ Deployed	2026-09-03 09:11 UTC	Run
prod-us	✅ Deployed	2026-09-03 09:36 UTC	Run
prod-eu	✅ Deployed	2026-09-03 09:32 UTC	Run