fix(pages): stop Claude reaching for an artifact when the user asked for a page
Links
- Issue: SUPER-2021
Summary
- Adds a
PreToolUseguard on Claude Code'sArtifacttool that denies the first publish of a session inside a Superset terminal, pointing the agent atsuperset:page. The second call goes through untouched. - Teaches the three text surfaces we own (the
pageskill description and body, thepages_publishMCP tool description, the desktop page-agent prompt) to name artifacts explicitly, so the skill has a lexical reason to win.
Why / Context
From SUPER-2021: "Often i ask for a Superset page and it still generates a Claude artifact."
Artifact publishes a self-contained HTML document to a private URL, which is close enough to a page that the model picks it. It wins on prompt real estate: it is a one-step tool whose system-prompt description frames publishing as how a deliverable gets finished, while superset:page is a skill that must be invoked first. Before this PR nothing in the repo mentioned artifacts at all, so there was no signal pushing the other way.
The two are not interchangeable. A page is listed in the org, mints a version on every publish, and takes pinned comments that route back to an agent that can act on them. An artifact has none of that.
How It Works
The guard (packages/agent-setup/templates/artifact-guard.template.sh) stays completely silent unless all of:
| Condition | Why |
|---|---|
SUPERSET_TERMINAL_ID/SUPERSET_TAB_ID set | Hook configs are global; this must be inert in non-Superset Claude sessions |
tool_name is Artifact | |
| action is a publish | list/comments/reply/read_db/write_db operate on an artifact that already exists |
no url in tool_input | A url means updating an artifact the user already owns |
| this session not yet nudged | Marker file keyed by session_id, falling back to terminal id |
Then it emits permissionDecision: "deny" with a reason naming superset:page and superset pages publish. SUPERSET_PAGES_NUDGE=off disables it outright.
Registration goes into ~/.claude/settings.json under PreToolUse with matcher Artifact, wrapped in the same SUPERSET_HOME_DIR guard the notify command uses.
Design Decisions
- Why a separate script instead of another
notify.shevent: the guard returns a permission decision on stdout.notify.shis a fire-and-forget notifier whose only stdout is debug output, and mixing a decision into it would be fragile. - Why deny-once instead of a hard block: a hard block removes the choice from someone who genuinely wants a Claude artifact. Deny-once makes Pages the default while leaving a one-retry escape hatch that costs the agent nothing.
- Why not text-only: a one-line skill description does not reliably out-rank a long imperative tool description in the system prompt. The wording helps; the hook is what actually changes the outcome.
- Why
cleanEntryhad to change: it previously recognized managed entries by the notify script path alone. Without teaching it the guard path too, a re-merge would append a duplicate entry every boot and teardown would orphan it.
Manual QA Checklist
- Provisioned into a temp
SUPERSET_HOME_DIR, confirmed~/.superset/hooks/artifact-guard.shis written at mode 0755 - Ran the exact registered command string against a real
PreToolUsepayload: first call →deny, second call → no output (tool proceeds) -
PreToolUseentry merges as{"matcher":"Artifact", …}alongside the existing notify events - Re-merging over the hook's own output is idempotent (no duplicate
Artifactentry) - Teardown removes the guard and leaves a user-authored
PreToolUsehook in place - Guard is silent outside a Superset terminal, and with
SUPERSET_PAGES_NUDGEin0/off/false/no - Guard is silent for
list/comments/reply/read_db/write_dband for aurl-carrying update - Guard is silent for every other tool name
- End-to-end in a real Superset terminal: ask an agent for a page, confirm it lands on Pages rather than an artifact
Testing
bun testinpackages/agent-setup— 363 pass, 0 fail (10 new guard-script tests, 3 new registration tests)bunx turbo typecheck --filter=@superset/desktop --filter=@superset/mcp --filter=@superset/agent-setup— cleanbunx biome checkon the touched trees — cleanbun run check:plugins— passesbun run check:i18n— no catalog churn (all added text is agent-facing, not interface copy)bunx sherif— no issues
Known Limitations
- Claude-only by construction. No other harness Superset launches has an
Artifacttool, so Codex, Cursor, Droid et al. get the wording change and nothing else. - The plugin was not republished.
plugins/superset/skills/page/SKILL.mdchanged withoutsuperset plugins publish superset --bump patch. There is nosuperset@*tag on origin, socheck:pluginspasses and the edited skill still ships via the bundled plugin dir — but if you want the marketplace release, that is a follow-up commit. - The guard's once-per-session marker lives in
TMPDIR, so a machine that clears it mid-session gets one extra nudge. Harmless, and preferable to persisting state under~/.superset.
Risks / Rollout
- Risk: low, and scoped to Claude sessions launched from Superset terminals. Worst case is one denied tool call per session that the agent immediately retries.
- Rollout: provisioning is declarative and runs at desktop/host boot; existing installs pick the hook up on next start.
- Rollback: revert the commit. Next boot rewrites
~/.claude/settings.jsonwithout thePreToolUseentry, since teardown recognizes the guard command.SUPERSET_PAGES_NUDGE=offdisables it without a deploy.
https://claude.ai/code/session_01R3SdsBKMTAniYr8U78UooQ
Summary by cubic
Stops Claude from reaching for a Claude artifact when the user asked for a Superset page. A PreToolUse hook now denies the first Artifact publish inside a Superset terminal and points the agent to the superset:page skill; the second call in the same session goes through untouched. The page skill, pages_publish tool description, and desktop agent prompt now name artifacts explicitly so the wording also pushes toward pages. The guard can be disabled with SUPERSET_PAGES_NUDGE=off.
Tracks SUPER-2021.
Notes
- The guard only fires in Superset terminals, for publish actions without an existing
url, once per session. - Existing installs pick up the hook on next boot; teardown removes it cleanly.
- The edited
SKILL.mdships via the bundled plugin dir; republishing the plugin to the marketplace is a follow-up.
Summary by CodeRabbit
-
New Features
- Added a reminder that directs eligible artifact publishing to Superset Pages instead.
- Prevents repeated reminders for the same session while allowing explicitly requested artifacts and opt-out behavior.
- Pages guidance now highlights organization visibility, version history, pinned comments, and applicable content restrictions.
-
Bug Fixes
- When the Pages skill is unavailable, the agent no longer substitutes a generic HTML workflow or Claude artifact and instead explains the required setup.
-
Tests
- Added coverage for artifact publishing, session handling, opt-out behavior, and preserving existing configuration.