saravmajestic · Nov 10, 2026 · Oct 30, 2026 · Oct 30, 2026 · Oct 30, 2026 · Nov 4, 2026
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -0,0 +1,30 @@
+name: tests
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  shell:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install zsh
+        if: runner.os == 'Linux'
+        run: sudo apt-get update && sudo apt-get install -y zsh
+      - name: Run shell tests
+        run: |
+          set -e
+          for t in tests/*.sh; do
+            echo "::group::$t"
+            bash "$t"
+            echo "::endgroup::"
+          done
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -26,12 +26,19 @@ altimate-codex-plugin/
 │       │       └── SKILL.md                    # dbt/SQL PR reviewer routing
 │       ├── commands/
 │       │   ├── altimate.md                     # /altimate-code:altimate <task>
-│       │   └── review.md                       # /altimate-code:review [scope]
+│       │   ├── review.md                       # /altimate-code:review [scope]
+│       │   └── rules.md                        # /altimate-code:rules
 │       ├── hooks/
-│       │   ├── hooks.json                      # SessionStart hook definition
-│       │   └── altimate-code-session-start.sh  # SessionStart hook script
+│       │   ├── hooks.json                      # SessionStart, UserPromptSubmit and Stop hook definitions
+│       │   ├── altimate-code-session-start.sh  # SessionStart capability description
+│       │   └── altimate-code-workspace-rules.sh # team rules hooks (session-start, user-prompt-submit, stop)
 │       ├── README.md                           # plugin-specific docs
 │       └── CHANGELOG.md                        # plugin-specific changelog
+├── .github/workflows/
+│   └── tests.yml                               # runs tests/*.sh on Linux and macOS
+├── tests/
+│   ├── resolve-cli.sh                          # CLI resolver block check
+│   └── workspace-rules-hook.sh                 # workspace-rules hook check
 ├── README.md                                   # repo overview
 ├── PRIVACY.md
 ├── TERMS.md
@@ -73,7 +80,12 @@ description: >-
 
 ## Testing changes
 
-If you touch the CLI resolver block in a skill or command, run `./tests/resolve-cli.sh` — it checks every copy is identical and resolves correctly in bash and zsh.
+Run the shell tests before opening a PR (CI runs them too, on Linux and macOS):
+
+```bash
+bash tests/resolve-cli.sh          # the CLI resolver block: every copy identical, resolves in bash and zsh
+bash tests/workspace-rules-hook.sh # the workspace-rules hook against a stub CLI (needs python3 and git)
+```
 
 Smoke-install the plugin from your working copy:
 
@@ -100,6 +112,8 @@ codex plugin marketplace remove altimate-codex-plugin
 - **Command** — `plugins/altimate-code/commands/altimate.md` — `/altimate-code:altimate <task>` explicit-delegation slash command.
 - **Command** — `plugins/altimate-code/commands/review.md` — `/altimate-code:review [scope]` explicit-review slash command.
 - **Hook** — `plugins/altimate-code/hooks/hooks.json` + `plugins/altimate-code/hooks/altimate-code-session-start.sh` — SessionStart hook that publishes a static capability description of both skills so Codex can route between them when the task shape fits.
+- **Command** — `plugins/altimate-code/commands/rules.md` — `/altimate-code:rules` to answer proposed team rules.
+- **Hooks** — `plugins/altimate-code/hooks/altimate-code-workspace-rules.sh` — the team rules hooks (SessionStart, UserPromptSubmit, Stop), which call `altimate-code learn hook <event>` only in a folder altimate-code's link cache names, and never fail the session.
 
 ## Reporting bugs / requesting features
 

diff --git a/PRIVACY.md b/PRIVACY.md
@@ -1,6 +1,7 @@
 # Privacy Policy — Altimate Code plugin for Codex
 
 **Effective date:** July 18, 2026
+**Last revised:** November 4, 2026
 **Applies to:** the `altimate-code` Codex plugin distributed from this repository, and the data flows it initiates through the [altimate-code](https://github.com/AltimateAI/altimate-code) CLI.
 
 This policy supplements the Altimate AI [Privacy Policy](https://www.altimate.ai/privacy) and [Terms](https://www.altimate.ai/terms), which govern Altimate services generally. Where this document is silent, the master policy applies. Questions: **info@altimate.ai**.
@@ -9,16 +10,40 @@ This policy supplements the Altimate AI [Privacy Policy](https://www.altimate.ai
 
 ## The short version
 
-- The plugin itself collects **no data**. It is a routing layer (a skill, a slash command, and a static session hook) that tells Codex when to delegate a task to the altimate-code CLI installed on your machine.
+- The plugin itself collects **no data**. It is a routing layer (skills, slash commands, and session hooks) that tells Codex when to delegate a task to the altimate-code CLI installed on your machine.
+- In a project linked to an Altimate workspace, its workspace-rules hooks start the local altimate-code CLI, which pulls the workspace's approved team rules into the session. The hooks also hand your messages and the location of the session transcript to the CLI. With learning on, the CLI keeps corrections on your machine and may send a digest of the session, which can include file contents, command output and query results, to altimate-code's own model (not Codex's) to word a proposed team rule. A proposal reaches your workspace only when you send or approve it. The CLI also sends usage telemetry about team rules. See [Workspace rules](#workspace-rules).
 - When a task **is** delegated, your task text is passed to the altimate-code CLI, which sends it to an LLM provider to plan and execute the work — the Altimate LLM Gateway by default, or a provider you configure (BYOK).
 - Warehouse queries, dbt commands, and file edits run **locally on your machine, under your credentials**. Your warehouse credentials are never sent to Altimate.
-- The plugin ships as opt-in. Adding the marketplace does not enable the plugin — you must explicitly install it from Codex's `/plugins` browser and approve its SessionStart hook before any delegation happens.
+- The plugin ships as opt-in. Adding the marketplace does not enable the plugin — you must explicitly install it from Codex's `/plugins` browser and approve its hooks (SessionStart, UserPromptSubmit, Stop) before any delegation happens or any hook runs.
 
 ## What the plugin does and does not do
 
-The plugin contains no executable service of its own. Its only runtime behavior is a SessionStart hook that prints a fixed, static text block describing the skill's capabilities. It does not read your files, does not phone home, and does not collect analytics.
+The plugin contains no executable service of its own. At session start, a hook prints a fixed, static text block describing the skill's capabilities. The workspace-rules hooks (see below) call the locally installed altimate-code CLI. The plugin itself does not phone home and does not collect analytics; the altimate-code CLI it starts sends usage telemetry (see [Usage telemetry](#usage-telemetry)).
 
-Data leaves Codex's process only when the delegation skill or the `/altimate` command fires and invokes the locally installed altimate-code CLI.
+Data leaves Codex's process only when the delegation skill, the `/altimate-code:altimate`, `/altimate-code:review` or `/altimate-code:rules` command, or a workspace-rules hook invokes the locally installed altimate-code CLI.
+
+## Workspace rules
+
+**When the hooks start the CLI.** The workspace-rules hooks start the local altimate-code CLI only when the folder the session starts in, or a folder above it in the repository, is named in altimate-code's workspace link cache (`altimate-workspace-bindings.json`, in your own state directory). Elsewhere they start nothing. No file in the repository decides this: a branch or a merge can bring files into it. With `ALTIMATE_LEARN=0` (or `false`) no hook starts the CLI.
+
+**What needs what.**
+
+- *Team rules.* In a linked project, the CLI pulls the workspace's approved team rules at session start when workspaces are on (`ALTIMATE_DISABLE_WORKSPACE` is not set), you are signed in to Altimate and `ALTIMATE_LEARN` is not `0`. This does not depend on the learning setting.
+- *Recording corrections and drafting proposed rules* also need learning on. Learning is on when you turned it on in the project (`altimate learn enable`) or, if you have made no choice of your own, when the workspace owner turned on the workspace's "Learn from sessions" setting. Your own choice (`altimate learn enable` or `altimate learn disable`) overrides the workspace setting, unless your organization enforces a policy.
+- In a linked folder, the per-turn hooks hand each message you send and the location of the session transcript to the local CLI whether or not learning is on. When you are signed out, workspaces are off or the project is not linked, the CLI discards them and nothing leaves your machine. When learning is off, the CLI discards them too, but after each turn it still pulls the team rules and sends proposals you already answered and rule usage counts (no message or transcript text).
+
+**The digest used to word a proposed rule.** After a turn with new corrections, the CLI reads the Codex session transcript (its last 8 MB) and builds a digest of the session: your prompts, the input and output of each tool call (up to 300 and 400 characters per call, so file contents, command output and warehouse query results can appear), and the final reply, at most 24,000 characters in total. Secrets in the digest are masked; no other data is removed. The digest is sent to altimate-code's own model: the model named by `ALTIMATE_LEARN_MODEL`, otherwise the one set as `learn.model` in altimate-code's configuration, otherwise altimate-code's default model, which is the Altimate LLM Gateway or another provider configured for altimate-code. This is not the model Codex uses; it is a party that does not otherwise see your Codex session. If altimate-code has no model it can use, nothing is sent, and the next session start reports that the check failed. The CLI makes at most one such model call per check round, and a few per turn at most.
+
+| Data | Where it goes | Retention |
+|---|---|---|
+| Your workspace's approved team rules | Pulled by the local CLI from your Altimate workspace, given to Codex as session context | Mirrored locally in the project's git-ignored `.altimate-code/` directory, and given only while altimate-code's own rules state holds the same rules and you are signed in as the account they were pulled for. That state, which also keeps proposals waiting to be sent and your review notices, is in your own state directory (`$XDG_STATE_HOME/altimate-code/workspace-rules/`, usually `~/.local/state/altimate-code/workspace-rules/`), outside the project. This needs an altimate-code release that keeps the rules state there; earlier releases keep it in the project's `.altimate-code/learn/workspace-rules/` folder |
+| Each message you send | Handed to the local CLI, which checks it with no model call; with learning on, a message that reads as a correction is kept (secrets redacted) | Local only, in the project's git-ignored `.altimate-code/` directory |
+| The session transcript, after a turn with new corrections (learning on) | Read locally by the CLI; the digest described above goes to altimate-code's own model to word one proposed rule | The transcript stays local; the model provider's handling is as for delegated tasks below |
+| A proposed rule, with an excerpt of your correction if your workspace allows quotes | Your Altimate workspace's review queue, only when you send or approve it in `/altimate-code:rules` or `altimate learn proposals` | Per the Altimate Privacy Policy |
+| Rule usage counts (sessions a rule was shown in, corrections after it) | Your Altimate workspace | Per the Altimate Privacy Policy |
+| Rules telemetry events: `rules_sync`, `rules_delivered`, `rule_drafted`, `rule_proposal_shown`, `rule_proposal_answered`, `rule_proposal_skipped`, `rule_remember_routed`, and `rules_command` (the name of each `learn` subcommand you run, such as `learn proposals`; not sent for the hooks' own calls). Events about a session carry its id, `codex:<id>` for a Codex session. No rule text, prompts or file paths | Altimate's usage telemetry, as described in [Usage telemetry](#usage-telemetry) | As for usage telemetry; turned off with the telemetry opt-out there |
+
+Turn off recording and drafting with `altimate learn disable` in the project, or, for members who have made no choice of their own, with the workspace's "Learn from sessions" setting. `ALTIMATE_LEARN=0` turns off all of it, including the team rules pull, and the hooks then start nothing.
 
 ## Data flows when a task is delegated
 
@@ -57,7 +82,7 @@ All data transmitted to Altimate services is encrypted in transit using TLS. Alt
 
 ## Your choices
 
-- **Don't install the plugin** — adding the marketplace makes it discoverable but does not install it; delegation happens only after you install from Codex's `/plugins` browser and approve its SessionStart hook.
+- **Don't install the plugin** — adding the marketplace makes it discoverable but does not install it; delegation happens, and its hooks run, only after you install from Codex's `/plugins` browser and approve its hooks (SessionStart, UserPromptSubmit, Stop).
 - **Use BYOK** — route prompts directly to your own provider so Altimate never sees them.
 - **Disable telemetry** — see above.
 - **Contact us** — for access, correction, or deletion requests, email **info@altimate.ai**.
@@ -70,6 +95,8 @@ The plugin and the altimate-code CLI are professional developer tools, not direc
 
 We will update this document in this repository and revise the effective date when our practices change. Material changes to Altimate-wide practices are governed by the master [Privacy Policy](https://www.altimate.ai/privacy).
 
+**November 4, 2026:** added [Workspace rules](#workspace-rules) (the workspace-rules hooks and `/altimate-code:rules` in plugin 1.2.0), and the rules telemetry the altimate-code CLI sends.
+
 ## Contact
 
 Altimate Inc. · 440 North Wolfe Road #150, Sunnyvale, CA 94085, USA · +1 (650) 254-6266

diff --git a/README.md b/README.md
@@ -45,9 +45,9 @@ To remove the marketplace registration:
 codex plugin marketplace remove altimate-codex-plugin
 ```
 
-### Trusting the SessionStart hook
+### Trusting the plugin's hooks
 
-The plugin ships a `SessionStart` hook that injects a short routing hint into the model's context so it prefers the `altimate-code` skill for warehouse-touching work. Codex does not run plugin-bundled hooks automatically — the first time you start a session with the plugin installed, Codex will prompt you to review and trust the hook definition. Approve it once and the hook fires in every subsequent session; skip it and the plugin still installs but the routing hint won't be delivered.
+The plugin ships a `SessionStart` hook that injects a short routing hint into the model's context so it prefers the `altimate-code` skill for warehouse-touching work. Codex does not run plugin-bundled hooks automatically — the first time you start a session with the plugin installed, Codex will prompt you to review and trust the hook definition. Approve it once and the hook fires in every subsequent session; skip it and the plugin still installs but the routing hint won't be delivered. The same applies to the workspace-rules hooks (SessionStart, UserPromptSubmit, Stop; see Team rules): without them, no team rules are given and no corrections are proposed.
 
 ## Layout
 
@@ -59,7 +59,7 @@ altimate-codex-plugin/
     ├── .codex-plugin/
     │   └── plugin.json                         # plugin manifest
     ├── hooks/
-    │   ├── hooks.json                          # SessionStart hook definition
+    │   ├── hooks.json                          # SessionStart, UserPromptSubmit and Stop hook definitions
     │   └── altimate-code-session-start.sh      # hook script (routing hint)
     ├── commands/
     │   ├── altimate.md                         # /altimate-code:altimate

diff --git a/SECURITY.md b/SECURITY.md
@@ -19,7 +19,7 @@ This plugin's skill forwards the user's task text to the [altimate-code](https:/
 - **Warehouse queries and dbt commands** → executed locally under your credentials by the CLI; not forwarded.
 - **Query results and file edits** → produced locally; the CLI writes an output file which the plugin surfaces back to Codex.
 
-If you do not want prompts to leave Codex's process, do not install this plugin. Adding the marketplace only makes it discoverable in Codex's `/plugins` browser — no delegation happens until you explicitly install it and approve the SessionStart hook.
+If you do not want prompts to leave Codex's process, do not install this plugin. Adding the marketplace only makes it discoverable in Codex's `/plugins` browser — no delegation happens until you explicitly install it and approve its hooks (SessionStart, UserPromptSubmit, Stop).
 
 For the complete privacy policy covering the plugin and the altimate-code CLI, see [PRIVACY.md](./PRIVACY.md).
 

diff --git a/plugins/altimate-code/.codex-plugin/plugin.json b/plugins/altimate-code/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "altimate-code",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Delegates dbt and warehouse work to altimate-code, a specialized CLI agent with 100+ purpose-built data tools (SQL analysis, column-level lineage, dbt build/test/run, warehouse profiling, FinOps, connectivity to Snowflake, BigQuery, Redshift, Databricks, Postgres, MySQL, DuckDB).",
   "author": {
     "name": "Altimate AI",

diff --git a/plugins/altimate-code/CHANGELOG.md b/plugins/altimate-code/CHANGELOG.md
@@ -4,6 +4,18 @@ All notable changes to the Altimate Code Codex plugin are recorded here.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0] — 2026-10-30
+
+### Added
+- Team rules from a linked Altimate workspace apply in Codex sessions. At session start the plugin gives Codex the workspace's approved rules for the repository, the number of proposed rules waiting for you, and the owner's reviews of your proposals since your last session.
+- Corrections you make to Codex are recorded locally (UserPromptSubmit, no model call). After a turn, altimate-code checks them in the background (Stop) and keeps a proposed rule when you corrected the same topic in two sessions or corrected a team rule Codex was given.
+- "Remember this as a team rule: …" said to Codex waits as a proposal (no model call).
+- `/altimate-code:rules`: answer proposed rules (send for review, approve as owner, edit, save as memory, or "Not a rule"), and see the team rules and the review status of your proposals.
+- The hooks run altimate-code only where the session's folder (or a folder above it in the repository) is in altimate-code's workspace link cache, which is in your own state directory: nothing in the repository turns them on. Team rules arrive in a linked project when you are signed in; recording corrections and drafting proposals also need learning on. `ALTIMATE_LEARN=0` turns all of it off and the hooks start nothing.
+- Start the session in the linked folder or below it: with only a subfolder linked (a dbt project), a session started at the repository root gets no team rules.
+- Codex may ask you to approve the plugin's hooks again after upgrading from 1.1.0.
+- The hooks need an altimate-code release with `learn hook`; with an older one they do nothing.
+
 ## [1.1.0] — 2026-10-19
 
 ### Fixed