Writes and approvals

Read-only by default

read_only is true when you install the plugin. Every create and update Claude tries is blocked before it reaches NetSuite.

The plugin decides what counts as a write with an allowlist of read tools: ns_runCustomSuiteQL, ns_runSavedSearch, ns_runReport, any ns_get… or ns_list… tool, and the claude.ai connector's three UI apps (ns_prompt_library_app, ns_report_filters_app, ns_selector_app). Every other ns_* tool is guarded as a write, including tools the plugin has never seen. An unknown tool is named as unknown in its approval prompt.

If a hook fails, a normal call goes through untouched. A write the plugin couldn't check is blocked.

Turning writes on

Run this in your own terminal, outside Claude Code:

node <path to nsx.mjs> config set read_only=false

Claude is told never to do this for you, and nsx config set refuses read_only=false from anything Claude Code runs. When the guard blocks a write, Claude prints the command with the full path filled in. See Settings for why this isn't a hard lock.

To turn writes off again, set it back:

node <path to nsx.mjs> config set read_only=true

What every write goes through

With writes on, each create or update follows the same steps.

1. Metadata. Claude calls ns_getRecordTypeMetadata for the record type, which is cached after the first time. For an update, it also saves the current record from ns_getRecord to current.json.

2. Exact input. Claude writes the exact tool input to input.json. A create needs an externalId, and the guard denies one without it, so a retried call can't create a second record.

3. Preview. Claude runs nsx preview and shows you the diff:

   nsx preview ns_updateRecord input.json --before current.json

   Updates always pass --before. Without it the approval prompt can't show the old values. The diff compares exact field paths, so a change can't hide behind another field with the same name.

4. Exact-input match. The guard only lets a write through when a preview exists for that exact input. The PreToolUse hook then rebuilds the diff from the input actually being sent, not from the saved preview.

5. Your approval. Claude Code shows its permission prompt with that diff. The write runs only if you approve it.

6. Read back. A write counts as succeeded only when the response has a record id or success: true. Otherwise the result is marked "Write outcome unknown", and Claude reads the record back before telling you it worked.

A failed create is never retried on its own. Claude asks you to check NetSuite first, then retries with a new externalId, so a create that did go through isn't duplicated.

The audit log

Every NetSuite call is written to an audit log, including denied writes and writes waiting on your approval. The log is kept until you delete its audit/ folder, because it's meant for auditors.

Export it as CSV:

nsx audit export
nsx audit export --days 30 --out audit-september.csv
nsx audit export --session

Without --out, the file goes to ./exports/ in the current directory. --days 30 covers the last 30 days that had activity. --session limits the export to the current session, or to the session id you pass. nsx audit tail prints the latest entries.

A write is logged as pending when the approval prompt is shown. An approved write adds a second line with its outcome, and both lines carry the same preview hash. A write you reject at the prompt keeps only its pending line.

Cowork and claude.ai have no write protection

The plugin installs in Cowork and claude.ai, but plugin hooks don't run there. That means no read_only block, no preview, no exact-input match and no approval step from the plugin. The skill still tells Claude to confirm every create and update with you and show the exact values, but nothing enforces it.

In those apps, control writes through the connector role's permissions in NetSuite.