claude-dev-env 8.7.0 → 8.9.0

package/.agents/skills/privacy-hygiene/SKILL.md

@@ -32,6 +32,7 @@ Surfaces:
 1. **Write / Edit / MultiEdit** — payload text about to land on disk (via PreToolUse dispatcher)
 2. **Durable posts** — `gh pr/issue create|comment|edit|review` bodies and GitHub MCP body/comment fields (Bash and PowerShell)
 3. **git commit** — staged blob text (non-exempt paths) on Bash and PowerShell, including `git.exe` and flag forms (`--no-verify`, `-c`, `-C`). Commit message bodies (`-m` / `-F`) are out of scope for the automated gate
+4. **CI** — the `committed-tree` job in `.github/workflows/ci-tests.yml` runs [gitleaks](https://github.com/gitleaks/gitleaks) over every commit the pull request adds, test files included. The repository-root `.gitleaks.toml` adds three rules to the gitleaks defaults: a user folder path that names a person, an RFC 1918 address, and an email other than a noreply or example address. To clear a fixture that must stay, add its gitleaks fingerprint to `.gitleaksignore`
 
 ## Sweep procedure
 

package/.agents/skills/pull-request/scripts/pull_request.py

@@ -100,6 +100,7 @@ def _linter_arguments(
         all_arguments.extend(["--body-file", str(arguments.body_file)])
     if getattr(arguments, "head", None) is not None:
         all_arguments.extend(["--head-branch", arguments.head])
+    all_arguments.extend(["--repository", arguments.repo])
     return all_arguments
 
 

package/.agents/skills/pull-request/scripts/test_pull_request.py

@@ -198,6 +198,8 @@ def test_actions_run_exact_linter_then_gh_arguments(
         "--body-file",
         BODY_FILENAME,
         *head_arguments,
+        "--repository",
+        all_cli_arguments[all_cli_arguments.index("--repo") + 1],
     ]
     assert exit_code == 0
     assert _calls(command_runner) == [expected_linter, expected_gh]

package/.agents/skills/team-advisor/SKILL.md

@@ -25,7 +25,7 @@ One warm advisor at the strongest tier this session can reach. This session is t
 
 1. Name the session identity first (protocol **Host profiles**), then walk the model floor.
 2. Claude: when `advisor` is in this session's tool list, the built-in advisor tool is the advisor. Spawn nothing and call `advisor()` at each consult point. Otherwise spawn or resume `pstack:poteto-agent` at `ADVISOR_EFFORT` (default low) with the advisor response contract in the prompt. When the bound model is out of usage, use the configured fallback at the same effort. Codex: use the native advisor path. Third-party: use the headless advisor path. When the host's walk fails, fail closed.
-3. Name the warm instance `team-advisor-agent` and keep its advisor response contract in every first prompt. When a native Codex subagent spawn is the advisor path, pass `flags: ["--advisor"]` with Astra.
+3. Name the warm instance `team-advisor-agent` and keep its advisor response contract in every first prompt. When a native Codex subagent spawn is the advisor path and the spawn tool has a `flags` field, pass `flags: ["--advisor"]` with Astra and record `advisor_flag: passed`. A spawn that skips an offered flag is a failed bind. When the spawn tool has no `flags` field, as in `codex exec`, spawn `gpt-6-astra` plainly, record `advisor_flag: unavailable`, and treat it as bound.
 4. Skip the multi-consumer "who you are" opener. This session is the sole consumer.
 5. When the bind or reply path fails, fail closed and report to the user. On a third-party host, only the bound advisor issues ENDORSE / CORRECTION / PLAN / STOP.
 
@@ -49,7 +49,7 @@ Aim for two consults on a normal task: one after orientation and one after write
 - Bind at or above the protocol floor for this host.
 - The advisor only answers (messaging); the session runs tools and posts.
 - Keep an optional reference gap in the reference record: path, status, repair action, and repair result. A reference gap leaves bind status separate.
-- On Codex, select native Astra when its bind and reply validation pass. Record `selected_tier: Astra` and `reply_path: native`.
+- On Codex, select native Astra when its bind and reply validation pass. Record `selected_tier: Astra` and `reply_path: native`, plus `advisor_flag: passed` or `advisor_flag: unavailable`.
 - Mark `fallback_kind: broken` only when the selected bind or reply path fails. Record the selected tier, fallback reason, and reply path in the same evidence object.
 - Record first, recovery, and completion consults with changed evidence, validation, unresolved risks, and report-back status.
 - Write the evidence object to the session-controlled `model-tier-run.json` record described in `advisor-tool.md`.

package/_shared/advisor/reference/identity.md

@@ -19,7 +19,7 @@ When both `codex` and `claude` tokens appear, Codex wins. Empty text is ThirdPar
 
 **Claude.** Spawn `subagent_type: session-advisor` at Fable through the Agent tool. When Fable is out of usage, bind Astra through the Codex helper if `ADVISOR_ASTRA` is on. Fail closed when neither binds.
 
-**Codex.** Spawn a native in-session Astra subagent at `resolve_codex_model_id("Astra")` (`gpt-6-astra`). Walk `candidate_tiers = ["Astra"]`. Record `{tier: "Astra", result: "spawned"}` on success. The `ADVISOR_ASTRA` flag is not required. Fail closed when Astra does not bind. Do not walk Fable on a Codex host.
+**Codex.** Spawn a native in-session Astra subagent at `resolve_codex_model_id("Astra")` (`gpt-6-astra`). Walk `candidate_tiers = ["Astra"]`. When the spawn tool has a `flags` field, pass `flags: ["--advisor"]` and record `fallback.advisor_flag: "passed"`. When it has none, as in `codex exec`, spawn `gpt-6-astra` plainly and record `fallback.advisor_flag: "unavailable"`. Both count as a bind. Record `{tier: "Astra", result: "spawned"}` on success. The `ADVISOR_ASTRA` flag is not required. Fail closed when Astra does not bind, or when the spawn skips a flag the host offers. Do not walk Fable on a Codex host.
 
 **ThirdParty.** Bind Fable through the CLI Claude-chain. When Fable is out of usage, bind Astra through the Codex helper if `ADVISOR_ASTRA` is on. Fail closed when neither binds.
 

package/_shared/advisor/reference/spawn-walk-log.md

@@ -29,5 +29,5 @@ Exit code `1` means a ladder invariant failed.
 Exit code `2` means the path or JSON was unusable.
 The same checks are available in-process via `validate_model_tier_run(run)`.
 
-The validator checks ladder shape and validates `evidence` when it is present. On Claude and ThirdParty, Astra is attempted after Fable when `astra_enabled` is enabled, and `selected_tier: "Astra"` requires `result: "codex"`. On Codex, the walk is Astra only, and `result: "spawned"` or `result: "codex"` counts as success. A Codex success record uses `reply_path: "native"`.
+The validator checks ladder shape and validates `evidence` when it is present. On Claude and ThirdParty, Astra is attempted after Fable when `astra_enabled` is enabled, and `selected_tier: "Astra"` requires `result: "codex"`. On Codex, the walk is Astra only, and `result: "spawned"` or `result: "codex"` counts as success. A Codex success record uses `reply_path: "native"` and `advisor_flag: "passed"` or `advisor_flag: "unavailable"`. A missing `advisor_flag` or `advisor_flag: "omitted"` fails validation.
 Host policy sits on top of it. See the Model floor section of the protocol.

package/_shared/advisor/reference/warm-up.md

@@ -31,7 +31,9 @@ The agent finishes its first turn standing by. `SendMessage` alone resumes it; b
 ## Codex host
 
 Spawn a native in-session Astra subagent at `resolve_codex_model_id("Astra")` (`gpt-6-astra`) with the charter as its prompt.
-Record `{tier: "Astra", result: "spawned"}` on success. Fail closed when that spawn does not bind.
+When the spawn tool has a `flags` field, pass `flags: ["--advisor"]` and record `fallback.advisor_flag: "passed"`.
+When the spawn tool has no `flags` field, as in `codex exec`, spawn `gpt-6-astra` plainly, record `fallback.advisor_flag: "unavailable"`, and treat the advisor as bound.
+Record `{tier: "Astra", result: "spawned"}` on success. Fail closed when that spawn does not bind, or when it skips a flag the host offers.
 The `ADVISOR_ASTRA` flag is not required. Do not walk Fable. Consults stay in-session with that Astra subagent.
 Identity routing: [`identity.md`](identity.md).
 

package/_shared/advisor/scripts/config/advisor_scripts_constants/model_tier_run_validator_constants.py

@@ -106,3 +106,18 @@ ALL_ADVISOR_REPLY_PATHS: frozenset[str] = frozenset(
     {"native", "sendmessage", "cli", "codex", "none"}
 )
 EVIDENCE_MUST_BE_OBJECT_MESSAGE: str = "evidence must be an object"
+ADVISOR_FLAG_PASSED: str = "passed"
+ADVISOR_FLAG_UNAVAILABLE: str = "unavailable"
+ADVISOR_FLAG_OMITTED: str = "omitted"
+ALL_ADVISOR_FLAG_STATES: frozenset[str] = frozenset(
+    {ADVISOR_FLAG_PASSED, ADVISOR_FLAG_UNAVAILABLE, ADVISOR_FLAG_OMITTED}
+)
+UNKNOWN_ADVISOR_FLAG_MESSAGE: str = (
+    "evidence.fallback.advisor_flag must be passed, unavailable, or omitted"
+)
+MISSING_ADVISOR_FLAG_MESSAGE: str = (
+    "Codex Astra success requires evidence.fallback.advisor_flag"
+)
+OMITTED_ADVISOR_FLAG_MESSAGE: str = (
+    "Codex Astra spawn skipped the --advisor flag the host offers"
+)

package/_shared/advisor/scripts/model_tier_run_validator.py

@@ -67,6 +67,8 @@ from advisor_scripts_constants.astra_advisor_constants import (
     ASTRA_FALLBACK_KIND_DECLINED,
 )
 from advisor_scripts_constants.model_tier_run_validator_constants import (
+    ADVISOR_FLAG_OMITTED,
+    ALL_ADVISOR_FLAG_STATES,
     ALL_ADVISOR_REPLY_PATHS,
     ATTEMPT_ORDER_MISMATCH_MESSAGE,
     ATTEMPT_TIER_OUT_OF_SLICE_MESSAGE,
@@ -82,10 +84,13 @@ from advisor_scripts_constants.model_tier_run_validator_constants import (
     HOST_PROFILE_JSON_KEY,
     HOST_PROFILE_MUST_BE_STRING_MESSAGE,
     INCOMPLETE_FALLBACK_WALK_MESSAGE,
+    MISSING_ADVISOR_FLAG_MESSAGE,
     MISSING_FALLBACK_REASON_MESSAGE,
+    OMITTED_ADVISOR_FLAG_MESSAGE,
     SELECTED_TIER_MISMATCH_MESSAGE,
     SELECTED_TIER_NOT_NULL_MESSAGE,
     THIRD_PARTY_MODEL_TIER,
+    UNKNOWN_ADVISOR_FLAG_MESSAGE,
     UNKNOWN_HOST_PROFILE_ERROR,
     UNKNOWN_OWN_TIER_MESSAGE,
 )
@@ -212,14 +217,26 @@ def _validate_fallback_reply_path(
         raise ModelTierRunError(
             "evidence.fallback.reply_path is not a known advisor path"
         )
-    if (
+    is_codex_astra_success = (
         canonical_host_profile(run.host_profile) == HOST_PROFILE_CODEX
         and maybe_run_selected_tier == ADVISOR_MODEL_TIER
-        and reply_path != "native"
-    ):
+    )
+    if is_codex_astra_success and reply_path != "native":
         raise ModelTierRunError(
             "Codex Astra success requires the native reply path"
         )
+    raw_advisor_flag = fallback_by_name.get("advisor_flag")
+    if raw_advisor_flag is None:
+        if is_codex_astra_success:
+            raise ModelTierRunError(MISSING_ADVISOR_FLAG_MESSAGE)
+        return
+    if (
+        not isinstance(raw_advisor_flag, str)
+        or raw_advisor_flag not in ALL_ADVISOR_FLAG_STATES
+    ):
+        raise ModelTierRunError(UNKNOWN_ADVISOR_FLAG_MESSAGE)
+    if is_codex_astra_success and raw_advisor_flag == ADVISOR_FLAG_OMITTED:
+        raise ModelTierRunError(OMITTED_ADVISOR_FLAG_MESSAGE)
 
 
 def _validate_fallback_evidence(

package/_shared/advisor/scripts/tests/test_model_tier_run_validator.py

@@ -44,7 +44,16 @@ def _native_codex_evidence(
     *,
     reply_path: str = "native",
     reference_status: str = "missing",
+    advisor_flag: str | None = "passed",
 ) -> dict[str, object]:
+    fallback: dict[str, object] = {
+        "selected_tier": "Astra",
+        "fallback_kind": None,
+        "fallback_reason": None,
+        "reply_path": reply_path,
+    }
+    if advisor_flag is not None:
+        fallback["advisor_flag"] = advisor_flag
     return {
         "schema_version": 1,
         "reference": {
@@ -53,12 +62,7 @@ def _native_codex_evidence(
             "repair_action": "use the projected docs root",
             "repair_result": "read",
         },
-        "fallback": {
-            "selected_tier": "Astra",
-            "fallback_kind": None,
-            "fallback_reason": None,
-            "reply_path": reply_path,
-        },
+        "fallback": fallback,
         "consult": {
             "changed_evidence": ["native bind returned a reply"],
             "validation": ["signal and session id read back"],
@@ -96,6 +100,46 @@ def test_codex_native_success_rejects_non_native_reply_path() -> None:
         validate_model_tier_run(run)
 
 
+def _codex_astra_success_run(evidence: dict[str, object]) -> ModelTierRun:
+    return ModelTierRun(
+        own_tier="Opus",
+        candidate_tiers=[ADVISOR_MODEL_TIER],
+        attempts=[{"tier": ADVISOR_MODEL_TIER, "result": "spawned"}],
+        selected_tier=ADVISOR_MODEL_TIER,
+        host_profile="Codex",
+        evidence=evidence,
+    )
+
+
+def test_codex_plain_astra_spawn_binds_when_host_lacks_advisor_flag() -> None:
+    run = _codex_astra_success_run(
+        _native_codex_evidence(advisor_flag="unavailable")
+    )
+
+    assert validate_model_tier_run(run) is None
+
+
+def test_codex_astra_spawn_that_skips_offered_advisor_flag_fails_closed() -> None:
+    run = _codex_astra_success_run(_native_codex_evidence(advisor_flag="omitted"))
+
+    with pytest.raises(ModelTierRunError, match="--advisor"):
+        validate_model_tier_run(run)
+
+
+def test_codex_astra_success_without_advisor_flag_record_fails_closed() -> None:
+    run = _codex_astra_success_run(_native_codex_evidence(advisor_flag=None))
+
+    with pytest.raises(ModelTierRunError, match="advisor_flag"):
+        validate_model_tier_run(run)
+
+
+def test_unknown_advisor_flag_state_is_rejected() -> None:
+    run = _codex_astra_success_run(_native_codex_evidence(advisor_flag="skipped"))
+
+    with pytest.raises(ModelTierRunError, match="advisor_flag"):
+        validate_model_tier_run(run)
+
+
 def test_broken_bind_keeps_fallback_evidence_separate_from_reference_gap() -> None:
     evidence = _native_codex_evidence()
     evidence["fallback"] = {

package/docs/references/advisor-tool.md

@@ -40,7 +40,7 @@ Work a disagreement in this order: keep the observed evidence in the record, nam
 
 ## Recovery record
 
-Keep one versioned `evidence` object in the session-controlled `model-tier-run.json` record. A missing optional reference belongs in `reference.status`; it keeps the bind result independent. `fallback_kind: "broken"` identifies a bind or reply failure. On a Codex host, a successful native route records `selected_tier: "Astra"` and `reply_path: "native"`.
+Keep one versioned `evidence` object in the session-controlled `model-tier-run.json` record. A missing optional reference belongs in `reference.status`; it keeps the bind result independent. `fallback_kind: "broken"` identifies a bind or reply failure. On a Codex host, a successful native route records `selected_tier: "Astra"`, `reply_path: "native"`, and `advisor_flag`. The value is `"passed"` when the spawn tool offers the `--advisor` flag and the spawn passed it, or `"unavailable"` when the spawn tool has no flag field. `"omitted"` fails the bind.
 
 ```json
 {
@@ -56,7 +56,8 @@ Keep one versioned `evidence` object in the session-controlled `model-tier-run.j
       "selected_tier": "Astra",
       "fallback_kind": null,
       "fallback_reason": null,
-      "reply_path": "native"
+      "reply_path": "native",
+      "advisor_flag": "passed"
     },
     "consult": {
       "changed_evidence": ["native bind returned a reply"],

package/docs/second-claude-account.md

@@ -0,0 +1,57 @@
+# Second Claude account
+
+A second Claude subscription runs agents on the same machine as the main one. It
+shares every skill, rule, plugin, setting and doc in the main Claude home, and it
+keeps its own sign-in and history.
+
+## Pieces
+
+| File | What it does |
+|---|---|
+| `scripts/claude_account_profile.py` | Links each shared entry of `~/.claude` into the profile `~/.claude-profiles/ev`, moves stale copies into `.replaced/<time>/`, and writes the `claude-ev.cmd` launcher into `~/.local/bin` |
+| `scripts/claude_account_choice.py` | Reads both accounts' 5-hour and weekly meters and prints which account a job runs on |
+| `scripts/dev_env_scripts_constants/claude_account_constants.py` | The profile name, the entries that stay per account, and the picker thresholds |
+
+The launcher sets `CLAUDE_CONFIG_DIR` to the profile and passes every argument to
+`claude`, so `claude-ev -p "..."` runs like `claude -p "..."` on the second
+account.
+
+These entries stay per account and are never linked: `.credentials.json` and
+`.claude.json` with their backups, `projects`, `sessions`, `todos`, `history.jsonl`,
+and the other state folders named in the constants file.
+
+## Sign in once
+
+```
+python packages/claude-dev-env/scripts/claude_account_profile.py
+claude-ev auth login
+```
+
+The sign-in lives in `~/.claude-profiles/ev/.credentials.json` on that machine.
+Claude refreshes it on each run.
+
+## Which account a job uses
+
+The main account belongs to the person who works on it, so a job borrows it only
+to spend leftover usage that expires soon.
+
+| Condition | Account |
+|---|---|
+| Main week resets within 24 hours, main under 90% of its week, main under 50% of its 5-hour window | main |
+| Otherwise, second under 95% of its week and under 90% of its 5-hour window | second |
+| Second meter unreadable | second, whose own run refreshes the sign-in |
+| Otherwise | wait, with the next reset time |
+
+An unreadable main meter never picks main.
+
+```
+python packages/claude-dev-env/scripts/claude_account_choice.py
+{"account": "second", "config_dir": "C:\\Users\\me\\.claude-profiles\\ev", "reason": "...",
+ "meters": {"main": {"session_used_percent": 12.0, "session_resets_at": "...",
+                     "weekly_used_percent": 34.0, "weekly_resets_at": "..."},
+            "second": null}}
+```
+
+The `meters` object carries each account's used percent and reset time for the
+5-hour window and the week. An account whose meter could not be read shows `null`.
+A usage report reads both accounts from this one call.

package/hooks/blocking/test_pii_scanner.py

@@ -24,6 +24,7 @@ SYNTHETIC_AWS_KEY = "AKIA" + ("B" * 16)
 SYNTHETIC_PEM_HEADER = "-----BEGIN RSA PRIVATE KEY-----"
 SYNTHETIC_REAL_EMAIL = "person.fixture@company-example.io"
 SYNTHETIC_SAFE_EMAIL = "user@example.com"
+SYNTHETIC_GITHUB_NOREPLY_EMAIL = "24366590+octocat@users.noreply.github.com"
 SYNTHETIC_HOME_PATH = r"C:\Users\fixture_real_user\notes.txt"
 SYNTHETIC_PLACEHOLDER_HOME = r"C:\Users\<you>\notes.txt"
 SYNTHETIC_PRIVATE_IP = "192.168.42.17"
@@ -42,6 +43,13 @@ def test_flags_real_email_and_allows_example_domain() -> None:
     assert all_safe_hits == []
 
 
+def test_allows_github_noreply_email_and_still_flags_a_company_lookalike() -> None:
+    all_noreply_hits = scan_text_for_pii(f"commit author {SYNTHETIC_GITHUB_NOREPLY_EMAIL}")
+    all_lookalike_hits = scan_text_for_pii("contact person@users.noreply.github.com.evil.io")
+    assert all_noreply_hits == []
+    assert any(each.category == "email" for each in all_lookalike_hits)
+
+
 def test_flags_home_path_and_allows_placeholder_user() -> None:
     all_home_hits = scan_text_for_pii(f"path is {SYNTHETIC_HOME_PATH}")
     all_placeholder_hits = scan_text_for_pii(f"path is {SYNTHETIC_PLACEHOLDER_HOME}")

package/hooks/hooks.json

@@ -2,6 +2,16 @@
   "description": "Code standards enforcement, safety guards, and development workflow hooks",
   "hooks": {
     "PreToolUse": [
+      {
+        "matcher": "Agent|Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/skill_loaded_reminder.py",
+            "timeout": 10
+          }
+        ]
+      },
       {
         "matcher": "multi_agent_v1__spawn_agent",
         "hooks": [
@@ -51,6 +61,11 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/style_reminder_prompt.py",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/skill_loaded_reminder.py",
+            "timeout": 10
           }
         ]
       }
@@ -95,6 +110,16 @@
             "timeout": 10
           }
         ]
+      },
+      {
+        "matcher": "compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/skill_loaded_reminder.py",
+            "timeout": 10
+          }
+        ]
       }
     ],
     "SessionEnd": [

package/hooks/hooks_constants/pii_prevention_constants.py

@@ -136,6 +136,7 @@ ALL_SAFE_EMAIL_DOMAINS: frozenset[str] = frozenset(
         "test",
         "local",
         "test.local",
+        "users.noreply.github.com",
     }
 )
 

package/hooks/hooks_constants/skill_loaded_reminder_constants.py

@@ -0,0 +1,58 @@
+"""Texts and names for the skill_loaded_reminder hook."""
+
+from __future__ import annotations
+
+__all__ = [
+    "ALL_SELF_LOADING_SUBAGENT_TYPES",
+    "ALL_SUBAGENT_TOOL_NAMES",
+    "ASSISTANT_ENTRY_TYPE",
+    "COMPACT_BOUNDARY_SUBTYPE",
+    "COMPACTION_REMINDER",
+    "COMPACTION_SOURCE",
+    "NOT_LOADED_REMINDER",
+    "POTETO_MODE_SKILL_NAME",
+    "PRE_TOOL_USE_EVENT_NAME",
+    "PROMPT_SEPARATOR",
+    "SESSION_START_EVENT_NAME",
+    "SKILL_TOOL_NAME",
+    "SLASH_COMMAND_MARKER",
+    "SUBAGENT_PROMPT_PREFIX",
+    "TOOL_USE_BLOCK_TYPE",
+    "USER_ENTRY_TYPE",
+    "USER_PROMPT_SUBMIT_EVENT_NAME",
+]
+
+PRE_TOOL_USE_EVENT_NAME = "PreToolUse"
+SESSION_START_EVENT_NAME = "SessionStart"
+USER_PROMPT_SUBMIT_EVENT_NAME = "UserPromptSubmit"
+COMPACTION_SOURCE = "compact"
+
+ALL_SUBAGENT_TOOL_NAMES = frozenset({"Agent", "Task"})
+ALL_SELF_LOADING_SUBAGENT_TYPES = frozenset({"pstack:poteto-agent", "poteto-agent"})
+
+POTETO_MODE_SKILL_NAME = "pstack:poteto-mode"
+SKILL_TOOL_NAME = "Skill"
+SLASH_COMMAND_MARKER = "<command-name>/pstack:poteto-mode</command-name>"
+PROMPT_SEPARATOR = "\n\n"
+
+ASSISTANT_ENTRY_TYPE = "assistant"
+USER_ENTRY_TYPE = "user"
+TOOL_USE_BLOCK_TYPE = "tool_use"
+COMPACT_BOUNDARY_SUBTYPE = "compact_boundary"
+
+SUBAGENT_PROMPT_PREFIX = (
+    "Before any other work, invoke the pstack:poteto-mode skill with the Skill tool. "
+    "Every prompt you write for a subagent opens with the same instruction."
+)
+
+NOT_LOADED_REMINDER = (
+    "The pstack:poteto-mode skill is not loaded in this context. "
+    "Your next tool call is the Skill tool with skill pstack:poteto-mode, before any other "
+    "tool call."
+)
+
+COMPACTION_REMINDER = (
+    "The context was just compacted and the pstack:poteto-mode skill rules were dropped. "
+    "Your next tool call is the Skill tool with skill pstack:poteto-mode, before any other "
+    "tool call. Then re-read the request that started this session and continue."
+)

package/hooks/session/skill_loaded_reminder.py

@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""PreToolUse, SessionStart and UserPromptSubmit hook. Keeps poteto-mode loaded in every context.
+
+::
+
+    Agent tool call, prompt lacks the skill      -> prompt opens with "invoke pstack:poteto-mode"
+    context compacted mid-run                    -> "invoke pstack:poteto-mode again"
+    user turn, skill not loaded since compacting -> "invoke pstack:poteto-mode now"
+    user turn, skill already loaded              -> nothing
+
+A session that loaded the skill hears nothing more until a compaction drops it.
+The hook prints its output and stops.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Iterable
+from pathlib import Path
+
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from hooks_constants.skill_loaded_reminder_constants import (
+    ALL_SELF_LOADING_SUBAGENT_TYPES,
+    ALL_SUBAGENT_TOOL_NAMES,
+    ASSISTANT_ENTRY_TYPE,
+    COMPACT_BOUNDARY_SUBTYPE,
+    COMPACTION_REMINDER,
+    COMPACTION_SOURCE,
+    NOT_LOADED_REMINDER,
+    POTETO_MODE_SKILL_NAME,
+    PRE_TOOL_USE_EVENT_NAME,
+    PROMPT_SEPARATOR,
+    SESSION_START_EVENT_NAME,
+    SKILL_TOOL_NAME,
+    SLASH_COMMAND_MARKER,
+    SUBAGENT_PROMPT_PREFIX,
+    TOOL_USE_BLOCK_TYPE,
+    USER_ENTRY_TYPE,
+    USER_PROMPT_SUBMIT_EVENT_NAME,
+)
+from hooks_constants.pre_tool_use_allow_output import write_pre_tool_use_allow_to_stdout
+from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+from hooks_constants.setup_project_paths_constants import DECODE_ERRORS_POLICY, UTF8_ENCODING
+
+
+def subagent_input_with_poteto_mode(
+    all_tool_input_fields: dict[str, object],
+) -> dict[str, object] | None:
+    """Return the Agent tool input with the poteto-mode instruction first, or None to leave it.
+
+    ::
+
+        {"prompt": "Reply leaf."}                          -> {"prompt": "Before any ...\\n\\nReply leaf."}
+        {"prompt": "Invoke pstack:poteto-mode, then ..."}  -> None
+        {"subagent_type": "pstack:poteto-agent", ...}      -> None, that agent loads the skill itself
+
+    Args:
+        all_tool_input_fields: The Agent tool input the session is about to send.
+    """
+    prompt = all_tool_input_fields.get("prompt")
+    if not isinstance(prompt, str) or POTETO_MODE_SKILL_NAME in prompt:
+        return None
+    if all_tool_input_fields.get("subagent_type") in ALL_SELF_LOADING_SUBAGENT_TYPES:
+        return None
+    return {**all_tool_input_fields, "prompt": SUBAGENT_PROMPT_PREFIX + PROMPT_SEPARATOR + prompt}
+
+
+def _invokes_poteto_mode(all_entry_fields: dict[str, object]) -> bool:
+    message = all_entry_fields.get("message")
+    if not isinstance(message, dict):
+        return False
+    content_blocks = message.get("content")
+    if all_entry_fields.get("type") == USER_ENTRY_TYPE and isinstance(content_blocks, str):
+        return SLASH_COMMAND_MARKER in content_blocks
+    if all_entry_fields.get("type") != ASSISTANT_ENTRY_TYPE or not isinstance(content_blocks, list):
+        return False
+    return any(
+        isinstance(each_block, dict)
+        and each_block.get("type") == TOOL_USE_BLOCK_TYPE
+        and each_block.get("name") == SKILL_TOOL_NAME
+        and isinstance(each_block.get("input"), dict)
+        and each_block["input"].get("skill") == POTETO_MODE_SKILL_NAME
+        for each_block in content_blocks
+    )
+
+
+def _marker_entry(transcript_line: str) -> dict[str, object] | None:
+    if (
+        COMPACT_BOUNDARY_SUBTYPE not in transcript_line
+        and POTETO_MODE_SKILL_NAME not in transcript_line
+    ):
+        return None
+    try:
+        parsed_entry = json.loads(transcript_line)
+    except json.JSONDecodeError:
+        return None
+    return parsed_entry if isinstance(parsed_entry, dict) else None
+
+
+def _is_loaded_after(all_entry_fields: dict[str, object], was_loaded: bool) -> bool:
+    if all_entry_fields.get("subtype") == COMPACT_BOUNDARY_SUBTYPE:
+        return False
+    return was_loaded or _invokes_poteto_mode(all_entry_fields)
+
+
+def is_poteto_mode_loaded(all_transcript_lines: Iterable[str]) -> bool:
+    """Return True when the transcript invoked the skill after its last compaction.
+
+    ::
+
+        Skill(pstack:poteto-mode) ... Read ... Edit               -> True
+        /pstack:poteto-mode typed as a command ... Read           -> True
+        Skill(pstack:poteto-mode) ... compact_boundary ... Read   -> False
+        Read ... Edit                                             -> False
+
+    Only lines naming the skill or a compaction are parsed, so a long transcript
+    reads fast.
+
+    Args:
+        all_transcript_lines: The session transcript, one JSON entry per line.
+    """
+    is_loaded = False
+    for each_line in all_transcript_lines:
+        all_entry_fields = _marker_entry(each_line)
+        if all_entry_fields is not None:
+            is_loaded = _is_loaded_after(all_entry_fields, is_loaded)
+    return is_loaded
+
+
+def _is_loaded_in_transcript(transcript_path: object) -> bool:
+    if not isinstance(transcript_path, str):
+        return False
+    try:
+        with open(
+            transcript_path, encoding=UTF8_ENCODING, errors=DECODE_ERRORS_POLICY
+        ) as transcript:
+            return is_poteto_mode_loaded(transcript)
+    except OSError:
+        return False
+
+
+def reminder_for(all_hook_fields: dict[str, object]) -> str | None:
+    """Return the reminder a session event carries, or None when the skill is in view.
+
+    ::
+
+        SessionStart, source compact                     -> COMPACTION_REMINDER
+        UserPromptSubmit, transcript lacks the skill     -> NOT_LOADED_REMINDER
+        UserPromptSubmit, transcript loaded the skill    -> None
+
+    Args:
+        all_hook_fields: The parsed hook input.
+    """
+    event_name = all_hook_fields.get("hook_event_name")
+    if event_name == SESSION_START_EVENT_NAME:
+        return COMPACTION_REMINDER if all_hook_fields.get("source") == COMPACTION_SOURCE else None
+    if event_name != USER_PROMPT_SUBMIT_EVENT_NAME:
+        return None
+    if _is_loaded_in_transcript(all_hook_fields.get("transcript_path")):
+        return None
+    return NOT_LOADED_REMINDER
+
+
+def _is_subagent_spawn(all_hook_fields: dict[str, object]) -> bool:
+    return (
+        all_hook_fields.get("hook_event_name") == PRE_TOOL_USE_EVENT_NAME
+        and all_hook_fields.get("tool_name") in ALL_SUBAGENT_TOOL_NAMES
+        and isinstance(all_hook_fields.get("tool_input"), dict)
+    )
+
+
+def main() -> None:
+    """Rewrite a subagent prompt, or print the reminder its event needs, or stay quiet."""
+    hook_payload = read_hook_input_dictionary_from_stdin()
+    if hook_payload is None:
+        return
+    if _is_subagent_spawn(hook_payload):
+        rewritten_input = subagent_input_with_poteto_mode(hook_payload["tool_input"])
+        if rewritten_input is not None:
+            write_pre_tool_use_allow_to_stdout(rewritten_input)
+        return
+    reminder = reminder_for(hook_payload)
+    if reminder is None:
+        return
+    reminder_output = {
+        "hookSpecificOutput": {
+            "hookEventName": hook_payload["hook_event_name"],
+            "additionalContext": reminder,
+        }
+    }
+    sys.stdout.write(json.dumps(reminder_output) + "\n")
+
+
+if __name__ == "__main__":
+    main()