Skip to content

Host-native rules & hooks

In short

  • A skill pack may carry rule and hook files that Claude Code or Cursor read natively. The shipped ML pack has none.
  • Codex and Gemini CLI ignore pack rules and hooks; they get each skill in their prompt.
  • A session snapshots the rules and hooks it starts with; editing a pack never changes a running session.
  • Hook scripts run with the backend user's rights. Review them before you adopt a pack.

A pack may carry rule and hook files that Claude Code or Cursor understand natively. ParleML does not invent a rule language or a hook engine: it selects these files, snapshots them, keeps other configuration out, and puts them where the CLI looks. The shipped ML pack has none.

Layout

packs/<pack>/
  skills/<slug>/SKILL.md
  rules/claude/*.md
  rules/cursor/*.mdc
  hooks/claude/hooks.json   (+ the scripts it runs)
  hooks/cursor/hooks.json   (+ the scripts it runs)

Across the packs a profile selects, at most one pack may provide hooks.json per CLI. Settings → Skill packs edits these files (/api/agent/admin/packs/{pack}/{rules|hooks}/{claude|cursor}/…, with If-Match); an import previews them and reports executable hooks as a risk before you adopt the pack. The shipped pack cannot be edited.

Per CLI

CLI Rules Hooks What it is kept from reading
Claude Code copied to .claude/rules/parleml/<pack>/ in the work directory passed as a generated plugin (parleml-host-hooks) with --plugin-dir Project settings are read (--setting-sources project) only when the packs carry Claude rules, and then a CLAUDE.md, CLAUDE.local.md, .mcp.json or other .claude/ settings in the work directory stop the run. Only the granted MCP servers load (--strict-mcp-config).
Cursor copied to .cursor/rules/parleml/<pack>/ .cursor/hooks.json and its scripts Used only when PARLEML_AGENTS_CURSOR_HOST_ASSETS_ENABLED=true; until then a profile whose packs carry Cursor rules or hooks fails preflight, and Cursor sessions on other profiles run normally. An AGENTS.md, .cursorrules or .cursor/ settings in the packs or reference paths fail preflight.
Codex ignored ignored project_doc_max_bytes=0, so an AGENTS.md a step left in the work directory is not read; a .codex/ there stops the run.
Gemini CLI ignored ignored A GEMINI.md or .gemini/ in the work directory stops the run.

Codex, Gemini CLI and Cursor get each skill's SKILL.md in their prompt; Claude Code loads the packs as plugins. Preflight says so for the CLIs that skip rules and hooks ("gets each skill in its prompt and does not run the packs' rules or hooks").

Snapshot

A new session copies and hashes the selected packs' rules and hooks into runs/<root_id>/host-assets/. Its steps and every later resume use that snapshot, not the live pack files, so editing a pack never changes a session already under way. A resume refuses a missing or altered snapshot; back it up with the session.

The work directory is shared by the orchestrator and its steps. Before each attempt the runtime materializes only the files for that attempt's CLI, and refuses to start over files another CLI or an earlier step left behind (the "what it is kept from reading" column).

Hook scripts run with the backend user's rights. ParleML does not sandbox or translate them; review them before adopting a pack.

Switching hooks off

A profile's host_assets.run_hooks has one switch per host (Run its hooks on the profile page; both on by default). With a host's switch off, its hooks are left out of the session's snapshot: nothing is materialized for that host, no hook plugin is generated, and a resume cannot bring them back. Rules still apply. Changing a switch changes the profile, so live sessions ask before they continue on it.

Account apps

Include account apps (Codex and Claude Code) is a separate, default-off profile switch (host_assets.include_account_apps). It permits automatic discovery of apps connected to the account running the backend; login, provider and permission restrictions still apply. Turning it off preserves the profile's explicit MCP connections, skills, prompts, rules, hooks and built-ins. It does not change the account's saved login or personal CLI configuration. Tool-free annotations always exclude account apps. See context isolation.

Your own settings

By default a session's CLI reads only what is listed above. A profile's host_assets.include_user_settings (Include my own settings) launches it with the settings of the account that runs it as well:

CLI Off (default) On
Claude Code --setting-sources project (or none) --setting-sources user,project: the user's ~/.claude settings, CLAUDE.md, rules and hooks. Their MCP servers stay out (--strict-mcp-config).
Cursor the SDK's project setting source (or none) adds the user source
Codex --ignore-user-config the user's config.toml is read, its MCP servers and provider included
Gemini CLI no switch: Gemini CLI reads the user's settings either way; the run keeps only the session's MCP servers and tools the same

Security. Those settings can carry instructions, hooks and permissions nobody reviewed, and they run as the backend's user. That is right for a local, one-person install, where the person and the account are the same, and wrong for a shared server. So the installation must allow it first (PARLEML_AGENTS_USER_SETTINGS_ALLOWED=true); until then a profile that turns it on is refused on save, by preflight and at start. Each attempt records whether its CLI read them (include_user_settings in the session snapshot and the run view; always true on Gemini CLI).

Next