@agentwhy/cli 0.0.0-dev

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,2 @@
+agentwhy
+Copyright 2026 Nessprim Karol Kozer

package/README.md

@@ -0,0 +1,181 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/lockup-dark.svg">
+    <img src="docs/lockup-light.svg" alt="agentwhy" width="340">
+  </picture>
+</p>
+
+<h3 align="center">Your AI agent reads your files. Find out which ones, and why.</h3>
+
+<p align="center">
+  agentwhy reads the conversations Claude Code and Codex already save on your computer and shows which of your private files
+  (<code>.env</code>, keys, secrets) an agent opened, the task that led to it, and which key to change.
+</p>
+
+<p align="center">
+  <code>npx @agentwhy/cli</code><br>
+  One command · runs on your computer · sends nothing anywhere · <a href="LICENSE">Apache 2.0</a>
+</p>
+
+---
+
+## What you see
+
+You run one command in your project. A page opens in your browser. Most days it says there is nothing to do.
+When there is, it looks like this:
+
+```
+  the session itself · 4 actions · 1 file reached · wrote the value into files
+  └─ Agent 1 · Explore · 2 actions · 1 file reached · 1 refused · gave the value back
+
+  Agent 1 · Explore, asked to "Find why the webhook returns 500"
+    ● apps/web/.env.development  in a result  reached
+    ○ apps/web/.env.local        named        refused
+    ↩ its answer to the session itself carried a value from apps/web/.env.development
+```
+
+Read it top to bottom:
+
+1. **Your agent started a helper** (`Agent 1`) and gave it a task: find why the webhook fails.
+2. **It tried to open `.env.local`.** A rule stopped it (`○ refused`).
+3. **A search got through anyway.** It printed lines from `.env.development`, and the secret came along
+   (`● reached`, `in a result`). No command named that file, so no rule applied.
+4. **The helper handed the secret back** to your main agent (`↩`), which wrote it into a file.
+
+**What to do:** change that key at the service that issued it. agentwhy tells you which one. It never shows the
+value itself.
+
+## Why you need this
+
+You ask Claude Code something ordinary: *"Find out why our Stripe webhook started failing."* It starts a helper
+agent, and the helper goes looking for the webhook secret. Three things make this hard to notice:
+
+- **Your rules don't reach the helper.** Your `AGENTS.md` says "never read `.env` files". The helper only gets
+  its task, not your rules, and the task says to find the secret.
+- **A search names no file.** `grep -rn STRIPE .` prints the key without ever opening `.env` by name, so no
+  rule that blocks `.env` can stop it.
+- **Nothing tells you.** There is no prompt, no warning, no log you would look at. The key is now in the chat,
+  in the saved conversation on your disk, and with the model provider. Deleting the log does not bring it back.
+  Only changing the key does.
+
+## What agentwhy shows you
+
+**The cause, not only the file.** Other tools can say "a file was read". agentwhy shows the task that led
+there: which agent asked which helper to do what, and where the value went next.
+
+**Conversations from before you installed it.** It reads the records Claude Code and Codex already keep, weeks
+back. There is nothing to set up first.
+
+**The routes no rule catches.** Secrets that came in through a search result, and reads a rule refused. Claude
+Code records neither as an event you would see.
+
+## How it works
+
+1. **Run it in your project folder:** `npx @agentwhy/cli`. Needs Node 22 or later.
+2. **It reads your saved conversations** from the last 7 days, on your computer, by fixed rules. No AI model,
+   no account, no internet.
+3. **A page opens** with a short list: which private files were reached, by whom, and what to change.
+4. **Optional: protect the project from now on.** `npx @agentwhy/cli init` adds rules to Claude Code that refuse
+   the obvious reads - and to Codex, in a project that uses it - and a one-line notice in the chat when a secret gets
+   into the conversation. It shows exactly what it
+   will write and asks first.
+
+By default it treats these as private: `.env*`, `*.env`, `.npmrc`, `secrets/`, `.ssh/`, `id_rsa*`. Add your own
+with `init --protect "config/*.pem"`.
+
+## Can you trust it?
+
+A tool that reads your conversations and knows where your keys are should not be taken on faith. Each claim below
+can be checked without reading the source.
+
+| Claim | How to check it |
+|---|---|
+| **Nothing goes over the internet.** The only socket it opens is a small server on `127.0.0.1`, so the page can save what you mark as done. `--no-serve` skips even that. | Turn off Wi-Fi and run it: it behaves the same. Or, while it runs, `lsof -nP -iTCP -a -c node` lists only a `127.0.0.1` listener. |
+| **Your secrets never reach the report.** Values are replaced before the report is built, and the code's types forbid a raw value there. | Open a report and search it for a key you know is in your `.env`. |
+| **No AI model is called.** Every finding comes from reading the records, by rules. | Run it offline with no API key set: the result is the same. |
+| **One dependency, pinned.** Only [`@clack/prompts`](https://www.npmjs.com/package/@clack/prompts), for the questions `init` asks. 6 small packages in total. | `npm ls --omit=dev --all` in the installed package. |
+| **The package is what this repository built.** Every release after the first is published from a tagged commit by GitHub Actions, with [npm provenance](https://docs.npmjs.com/generating-provenance-statements). The first is published by hand, because npm lets a trusted publisher be set up only for a package that already exists. | The *Provenance* badge on npmjs.com, or `npm audit signatures`. |
+
+## Questions
+
+**Does it stop my agent from reading secrets?**
+In Claude Code, it stops the obvious routes: `init` adds rules for Claude Code's own file tools, and a check that
+refuses shell commands like `cat .env` or `grep -r` over a private file. It is not a sandbox. A path in a variable or a
+script can still get through, and that is why the main job is telling you what actually happened. In Codex the same
+check runs as a Codex hook, with the same list of files. When it blocks a command, a second hook asks Codex to explain
+the block in its reply in the terminal or code editor, without asking you to paste a secret. Codex runs new or changed
+hooks only after you approve them there: until then, it skips them without a word.
+
+**Which agents does it work with?**
+Claude Code, in the terminal and in code editors, and Codex. Not Cursor's own AI, Windsurf or chats on claude.ai. Each
+conversation on the page is marked with the AI that had it.
+
+Codex writes down less than Claude Code does, so a Codex report can answer fewer questions:
+
+| What the report tells you | Claude Code | Codex |
+|---|---|---|
+| Which private files the AI opened, and with which command | yes | yes, where its record shows the file was opened - a command that finished is not enough |
+| What a command or a search printed | yes | yes |
+| Whether the AI was handed what was printed | yes | on version 0.157.0; on other versions, it says it doesn't know |
+| Every step the AI took | yes | no: some steps leave no trace, so a Codex report never says there is nothing to fix |
+| A read a rule stopped | yes | yes, when agentwhy's own refusal is recorded in a code cell |
+| Which helper was asked to do what, and what it gave back | yes | yes |
+| Which files the AI changed | yes | yes; a change that failed is not counted |
+| What Codex was allowed to do at the time | - | yes, shown apart from your own rules |
+| Blocking a file | yes | yes, the same files, once you approve agentwhy's hook in Codex (measured on 0.159.2) |
+| A message in the chat after agentwhy blocks a command | yes | yes, in the terminal and code editor once both hooks are approved |
+| A warning when a value reached the chat, and `check` | yes | no |
+
+Older Codex files keep the commands only inside the code that ran them, so their reports show no commands and say so.
+What Codex writes down was measured on `codex exec` 0.157.0 on macOS. Other versions and computers are read too, and
+their reports say what could not be checked.
+
+**What if it finds something?**
+It names the file and the key to change, worst first. Changing the key at the service that issued it is the only
+step that undoes a leak. Mark it done and it leaves your list.
+
+**Does it look at all my projects?**
+One project at a time: the folder you run it in. The page lists your other projects so you can switch.
+
+**What does it cost?**
+Nothing, for any use except selling it, or something like it, as a competing product. See [License](#license).
+
+## How well it works
+
+Measured on 28 scripted sessions, each one a route by which a secret can reach an agent, including the routes it
+misses ([docs/detection.md](docs/detection.md), re-run with `npm run measure:detection`):
+
+- when a private file's value came into the conversation, it said to change the key in **13 of 17**;
+- it named the task a helper agent was given in **5 of 5**;
+- no part of a secret reached a report in **28 of 28**.
+
+The misses are listed there, with why: an interpreter or a library that opens the file, a glob, an MCP tool, a
+pasted key. These are routes written by the author, not a rate on real machines. How often each happens in real
+work is not measured yet.
+
+**Status: pre-MVP.** The reader, the report and the link between a main conversation and its helpers are built and
+tested, for Claude Code and for Codex. The 28 sessions above are Claude Code's.
+
+## Commands
+
+```bash
+npx @agentwhy/cli                  # every conversation in one page, start here
+npx @agentwhy/cli check            # the short answer, in the terminal
+npx @agentwhy/cli report --open    # the newest conversation, in the browser
+npx @agentwhy/cli init             # protect this project and add the chat notice
+npx @agentwhy/cli notify           # what you are told when a turn ends, and where
+```
+
+Every command, flag and hook, and what each word on the page means: [docs/reference.md](docs/reference.md).
+
+## License
+
+Open source, under the [Apache License 2.0](LICENSE). Use it, change it and share it for any purpose, commercial
+use included. When you pass on a copy, keep the license, the copyright and [NOTICE](NOTICE) with it. The license
+does not cover the name agentwhy. The full terms are in [LICENSE](LICENSE); this summary does not replace them.
+
+## More
+
+[docs/reference.md](docs/reference.md): every command and flag, the full report, and the limits of what it can
+tell you · [CONTRIBUTING.md](CONTRIBUTING.md): how to work on it · [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md):
+bundled third-party code · © 2026 Nessprim Karol Kozer.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,31 @@
+# Third-party notices
+
+agentwhy copies one MIT-licensed library into its own source, so that the pages it writes open from disk and
+fetch nothing. Its licence requires that the notice below travels with every copy.
+
+| Library | Version | Where it is copied | Upstream |
+|---|---|---|---|
+| Air Datepicker | 3.6.0 | `src/report/start/render/air-datepicker-vendor.ts` | <https://github.com/t1m0n/air-datepicker> |
+
+The rest of agentwhy is licensed under the Apache License 2.0; see `LICENSE` and `NOTICE`.
+This third-party component retains its own license.
+
+## Air Datepicker
+
+The MIT License (MIT)
+
+Copyright (c) Timofey Marochkin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and
+to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of
+the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
+THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.

package/dist/adapter/claude-code/contract/assumptions.js

@@ -0,0 +1,208 @@
+// `verified` means checked across every instance in the measured session, not a sample of them. The measured session
+// is the Claude Code 2.1.268 session that the corpus, tests/fixtures/redacted/, is a redacted copy of.
+export const ASSUMPTIONS = [
+    {
+        id: 'main-transcript-path',
+        statement: 'The main transcript of a session is <project>/<session-id>.jsonl.',
+        status: 'verified',
+        evidence: 'spec §4.0; every session inspected on 2026-09-12',
+    },
+    {
+        id: 'session-directory',
+        statement: 'Subagent files and spilled results live under <project>/<session-id>/; a session with neither has no such directory.',
+        status: 'verified',
+        evidence: 'spec §4.0; present for the session with subagents, absent for the sessions without',
+    },
+    {
+        id: 'subagent-file-pair',
+        statement: 'Each subagent has agent-<id>.jsonl and agent-<id>.meta.json in subagents/, sharing <id>.',
+        status: 'verified',
+        evidence: '15 of 15 pairs in the measured session',
+    },
+    {
+        id: 'spilled-tool-results',
+        statement: 'Large tool results are spilled to <project>/<session-id>/tool-results/<id>.txt.',
+        status: 'verified',
+        evidence: '2 of 2 files in the measured session',
+    },
+    {
+        id: 'tool-result-reference',
+        statement: 'A spilled result is referenced from a tool result — the toolUseResult field or a tool_result content block — through a tool-results/<id>.txt path.',
+        status: 'verified',
+        evidence: 'doctor counts references in result positions only: 2 referenced and 0 missing against the 2 spilled files, before redaction and in the corpus alike (2026-09-13)',
+    },
+    {
+        id: 'tool-result-reference-converse',
+        statement: 'The converse does NOT hold: not every tool-results/<id>.txt path inside a result is a spill reference. A result that merely quotes one - grep output, say - reads as a reference to a file that is missing.',
+        status: 'unverified',
+        evidence: 'no instance either way in the measured session; raised by the M1 review (2026-09-13). The error runs toward UNKNOWN, which is the safe direction, and M2 measures how often it fires before anything is tightened',
+    },
+    {
+        id: 'tool-result-block',
+        statement: 'A tool result sits in a message content block of type tool_result that carries tool_use_id and content.',
+        status: 'verified',
+        evidence: '373 of 373 result lines of the corpus carry one (208 main, 165 subagent), and every tool_use_id in them joins to a call (2026-09-13)',
+    },
+    {
+        id: 'assistant-text-block',
+        statement: 'What an agent writes sits in a message content block of type text, carrying the words under text, on an assistant line that holds no tool_use block.',
+        status: 'verified',
+        evidence: '149 of 149 assistant text blocks in the corpus carry a string text field - 129 main, 20 subagent - and none shares its line with a tool_use. User lines carry text blocks as well, 69 on 55 main lines, and are not an agent\'s words (2026-09-15)',
+    },
+    {
+        id: 'assistant-reasoning-block',
+        statement: 'What an agent works out before it calls sits in a message content block of type thinking, carrying the words under thinking, one block to a line, beside a signature.',
+        status: 'verified',
+        evidence: '249 of 249 reasoning blocks in the corpus carry a string thinking field, one to a line, with the keys type, thinking and signature. In an unredacted session the block sits on the line immediately before a call in 276 of 276 calls that have any words before them, and one block precedes a run of up to four calls. **The field may be empty**: in the measured session before redaction, all 249 of its reasoning blocks are - 160 main, 89 subagent - while its text blocks carry words. The committed corpus cannot show that, since redaction replaces content with a marker (2026-09-15)',
+    },
+    {
+        id: 'delegating-result-text-blocks',
+        statement: 'The result of a delegating call is a list of text blocks, and nothing else: its words are the text of those blocks.',
+        status: 'verified',
+        evidence: '15 of 15 delegating results in the measured session, counted before redaction, none holding a block of another type (2026-09-15). The committed corpus cannot show it: the block type inside a result is replaced by a marker there',
+    },
+    {
+        id: 'delivered-task-notification',
+        statement: 'An agent started in the background reports on a user line of its own that holds no tool_result: its words carry a <task-notification> whose tool-use-id tag is the id of the delegating call. A queue-operation line queues the same words first, and is not the delivery.',
+        status: 'verified',
+        evidence: '6 of 6 task notifications in the measured session were queued by a queue-operation line and delivered on a user line, as a string; tool-use-id equals a delegating call id on 6 of 6, and task-id that call\'s agent on 6 of 6, counted before redaction (2026-09-15). The committed corpus cannot show it: the words are replaced by a marker there',
+    },
+    {
+        id: 'file-writing-input',
+        statement: 'Edit carries file_path, old_string, new_string and replace_all, and old_string is the text it takes out; Write carries file_path and content. NotebookEdit and MultiEdit are not profiled as writing a file.',
+        status: 'verified',
+        evidence: '45 of 45 Edit calls and 7 of 7 Write calls in the corpus carry exactly those keys (2026-09-15). No NotebookEdit or MultiEdit call occurs there, so their inputs are unmeasured and a value in them is counted as a use in another call',
+    },
+    {
+        id: 'launch-notice-status',
+        statement: 'A delegating result whose payload status is async_launched is a launch notice - the agent was started, and its report is not in the result. A result whose status is completed carries the report.',
+        status: 'verified',
+        evidence: '6 of 15 delegating results in the measured session carry status async_launched and an isAsync key, and no content, and a report was delivered for each; the other 9 carry status completed and content, counted before redaction (2026-09-15). None of the 15 calls sets run_in_background to true, so what was asked does not say which',
+    },
+    {
+        id: 'result-join-field',
+        statement: 'The tool_use_id of the tool_result block is the join from a result to its call. toolUseResult is the payload, not a join: it is on 208 of 208 main result lines but only 10 of 165 subagent ones.',
+        status: 'verified',
+        evidence: '373 of 373 result lines join by it; measured on the corpus (2026-09-13). Corrects spec §4.3 rule 1',
+    },
+    {
+        id: 'one-call-per-assistant-line',
+        statement: 'An assistant line carries exactly one tool_use block, which is what makes sourceToolAssistantUUID unambiguous as a call reference.',
+        status: 'unverified',
+        evidence: 'true for all 373 assistant lines of the measured session (2026-09-13), but it is a property of this session, not of the format: nothing forbids two calls on one line. The model joins by tool_use_id and never relies on this',
+    },
+    {
+        id: 'line-types',
+        statement: 'Every parsable line has a type among 11 known values; only user and assistant carry the conversation.',
+        status: 'verified',
+        evidence: 'all 1571 main-session and 711 subagent lines (2026-09-12, 10 types); all 1573 main-session and 711 subagent lines a day later (2026-09-13), where bridge-session is the eleventh',
+    },
+    {
+        id: 'bridge-session-line',
+        statement: 'A bridge-session line carries only bridgeSessionId, lastSequenceNum, ownerAccountUuid, ownerOrganizationUuid, sessionId and type; with no message it carries no conversation and is skipped.',
+        status: 'verified',
+        evidence: '1 of 1 line in the measured session (2026-09-13); keys measured by doctor per unknown line type before classifying. It has no version, uuid or isSidechain key',
+    },
+    {
+        id: 'history-suppression-and-mode-lines',
+        statement: 'history-suppression and mode lines are not classified; doctor reports them as unknown line types.',
+        status: 'unverified',
+        evidence: 'seen only in another session (Claude Code 2.1.268-2.1.270, 2026-09-13), absent from the measured one; classify after doctor measures their keys on a session that has them',
+    },
+    {
+        id: 'version-per-line',
+        statement: 'The Claude Code version belongs to each line, not to the file, and not every line type carries it.',
+        status: 'verified',
+        evidence: 'another session spans 2.1.268, 2.1.269 and 2.1.270 (2026-09-13); in the measured session 1142 main-session lines carry version and 431 do not, bridge-session among them',
+    },
+    {
+        id: 'working-directory-per-line',
+        statement: 'The session working directory is carried by cwd on the lines that hold the conversation, not by every line. One session can carry more than one value; the one that names the project is the value matching the project directory\'s name.',
+        status: 'verified',
+        evidence: 'presence measured before redaction (2026-09-14): 1142 of 1573 main-session lines and 711 of 711 subagent lines, the same lines that carry version, gitBranch and userType. The committed corpus cannot measure the values: it was redacted before the redactor aliased working directories, so all 1853 of its cwd values are one flattened marker and doctor reports distinct 1 as an artefact of the fixture. Corrected 2026-09-28 (contract v12, which-project VB5): over the last megabyte of 244 real transcripts, cwd is in every one and a value matching the project directory\'s name is in every one, and 14 carry more than one value - so "one session carries one value", stated here until then, is false. Corrects 2026-09-13-agentwhy-plan.md §5 item 3, which recorded cwd as present on every line',
+    },
+    {
+        id: 'entry-point-per-session',
+        statement: 'The lines that hold a conversation carry entrypoint, which way into Claude Code the session was started by, and one session carries one value: cli, claude-vscode or sdk-cli. Any other value is unknown, never the nearest of these.',
+        status: 'verified',
+        evidence: 'which-project VB5 (2026-09-28): the last megabyte of each of 244 transcripts carries it - claude-vscode 180, cli 62, sdk-cli 2 - and no transcript, tail or whole, carries two values. The same values the hooks are given as CLAUDE_CODE_ENTRYPOINT (the-agent-tells-you B9e2). The committed corpus holds a canary marker in its place, which reads as unknown',
+    },
+    {
+        id: 'sidechain-discriminator',
+        statement: 'isSidechain is false on main-session lines and true on subagent lines, wherever it is present.',
+        status: 'verified',
+        evidence: '1142 of 1142 and 711 of 711 lines (2026-09-12); the same a day later (2026-09-13)',
+    },
+    {
+        id: 'denial-marker',
+        statement: 'A blocked call is marked by toolDenialKind on its result line; the only observed value is permission-rule.',
+        status: 'verified',
+        evidence: '5 of 5 denials',
+    },
+    {
+        id: 'meta-keys',
+        statement: 'Each meta.json carries agentType, description, toolUseId, spawnDepth, requestShape and requestNonInteractive.',
+        status: 'verified',
+        evidence: '15 of 15 files',
+    },
+    {
+        id: 'agent-tool-input',
+        statement: 'The Agent tool_use input carries description, prompt and subagent_type on every call, and optionally run_in_background.',
+        status: 'verified',
+        evidence: 'reconnaissance inspected 6 of 15 calls (2026-09-12); doctor, before redaction, counted the three keys on 15 of 15 calls and run_in_background on 9 (2026-09-13)',
+    },
+    {
+        id: 'delegation-join',
+        statement: 'Where a subagent was started by the Agent tool, meta.json toolUseId equals that call id. It is NOT universal: a subagent started another way has no toolUseId at all.',
+        status: 'verified',
+        evidence: '15 of 15 meta files join to one of the 15 Agent calls (2026-09-13). But another session has 3 subagents of type general-purpose, spawned through the Skill tool, whose meta files carry agentType and spawnDepth and no toolUseId, and whose main transcript holds no Agent call at all (2026-09-14)',
+    },
+    {
+        id: 'delegation-routes',
+        statement: 'An agent can be delegated to by routes other than the Agent tool - a Skill spawns one - and only the Agent route records which call started it.',
+        status: 'verified',
+        evidence: '3 of 3 subagents of a session that delegated through a Skill (2026-09-14). The consequence is that a count of Agent calls is not a count of delegations: an agent whose start is unrecorded must be reported as such, never left out',
+    },
+    {
+        id: 'file-id-matches-line-agent-id',
+        statement: 'The <id> in a subagent file name equals the agentId field on the lines inside that file.',
+        status: 'verified',
+        evidence: '15 of 15 transcripts carry exactly one agentId and it equals the file id; no line lacks it (2026-09-13, measured on the corpus, which keeps agentId since contract v3)',
+    },
+    {
+        id: 'session-title-shape',
+        statement: 'An ai-title line is {type, aiTitle, sessionId}, and aiTitle is a string.',
+        status: 'verified',
+        evidence: '82 of 82 ai-title lines in the corpus (2026-09-15)',
+    },
+    {
+        id: 'handback-shape',
+        statement: 'A subagent may deliver its report as a SubagentHandback call on its own transcript, whose input is {message: string}. The call names no delegation; the report answers the call that started the agent whose transcript it is on.',
+        status: 'verified',
+        evidence: '2 of 2 SubagentHandback calls in a later session, both on sidechain lines, each with the single input key message holding a string (2026-09-19). The measured session predates the tool and has none, so both shapes are carried: a report delivered as a task-notification and one handed back through a call',
+    },
+    {
+        id: 'line-timestamp',
+        statement: 'The lines that hold a conversation carry timestamp, when the line was written, as a string of ISO 8601 in UTC with milliseconds. Time does not follow the record: a line can be earlier than the one before it.',
+        status: 'verified',
+        evidence: 'three sessions of Claude Code 2.1.280 (2026-09-23): 1826 of 1826, 596 of 596 and 1598 of 1598 lines of the types that carry it, main and subagent alike, all matching the shape and all parsing; 23 of 1825, 14 of 595 and 17 of 1600 consecutive pairs run backwards. Read for display only (the report page spec M4); a line without it, or with a value that does not parse, has no time - never a guessed one',
+    },
+    {
+        id: 'hook-input-cwd',
+        statement: 'Every hook input carries cwd, the directory the session is running in.',
+        status: 'verified',
+        evidence: '5 of 5 Stop inputs (2026-09-17, the-agent-nobody-watches B8b) and every SubagentStop input of B4 (2026-09-16). Read by `watch` to decide which project a person\'s notification choices were made for, before any of the session has been read',
+    },
+    {
+        id: 'session-title-latest-near-end',
+        statement: 'The title a session has now is its last ai-title line, and that line lies within the last megabyte of the transcript.',
+        status: 'unverified',
+        evidence: 'In the corpus the last ai-title line ends 17 KB before the end of the file and no two are more than 30 KB apart (2026-09-15). Redaction changes the length of content, so the distances are indicative, and marker values cannot show whether a later title differs from an earlier one. A session that breaks this shows no title, never a wrong one',
+    },
+    {
+        id: 'recognition-by-first-line',
+        statement: "A main transcript's first non-blank line is a JSON object with a string `type` and a string `sessionId` equal to the file's name, and no `payload`.",
+        status: 'verified',
+        evidence: '257 of 257 main transcripts (2026-09-29, contract v13), counted as fixed labels only. The type was a listed one in 193; so recognition rests on the id, and accepts a listed type without one for the hand-built fixtures. Tells a transcript from a Codex rollout (`2026-09-27-what-codex-wrote.md` X2)',
+    },
+];

package/dist/adapter/claude-code/contract/denials.js

@@ -0,0 +1,15 @@
+export const KNOWN_DENIAL_KINDS = ['permission-rule'];
+// An unrecognised denial kind must surface as unknown, never be folded into a known one.
+export function isKnownDenialKind(value) {
+    return typeof value === 'string' && KNOWN_DENIAL_KINDS.includes(value);
+}
+/**
+ * What the Read tool itself answers when a deny rule covers the file. Measured 2026-09-24 on a real session: a Read of
+ * `.env` under a deny rule for every `.env` file came back as an error result holding these words, and the record carried no
+ * `toolDenialKind` - that marker is written for a shell command a rule refuses, not for this. Without these words the
+ * refusal read as a call that failed, and the page said "only saw a name" of a file a rule had kept out. Matched only
+ * inside a result marked as an error, so a file that merely quotes the sentence is not a refusal.
+ */
+export const RULE_REFUSED_READ = 'File is in a directory that is denied by your permission settings.';
+/** The kind a refusal recognised by its words is recorded as: the same rule, reached through another tool. */
+export const RULE_REFUSED_READ_KIND = 'permission-rule';