instar 0.4.5 → 0.4.7

package/README.md

@@ -376,6 +376,49 @@ One agent's growing pain becomes every agent's growth.
 
 Everything is file-based. No database. JSON state files the agent can read and modify. tmux for session management -- battle-tested, survives disconnects, fully scriptable.
 
+## Security Model: Permissions & Transparency
+
+**Instar runs Claude Code with `--dangerously-skip-permissions`.** This is a deliberate architectural choice, and you should understand exactly what it means before proceeding.
+
+### What This Flag Does
+
+Claude Code normally prompts you to approve each tool use -- every file read, every shell command, every edit. The `--dangerously-skip-permissions` flag disables these per-action prompts, allowing the agent to operate autonomously without waiting for human approval on each step.
+
+### Why We Use It
+
+An agent that asks permission for every action isn't an agent -- it's a CLI tool with extra steps. Instar exists to give Claude Code **genuine autonomy**: background jobs that run on schedules, sessions that respond to Telegram messages, self-evolution that happens without you watching.
+
+None of that works if the agent stops and waits for you to click "approve" on every file read.
+
+### Where Security Actually Lives
+
+Instead of per-action permission prompts, Instar pushes security to a higher level:
+
+**Behavioral hooks** -- Structural guardrails that fire automatically:
+- Dangerous command guards block `rm -rf`, force push, database drops
+- Grounding hooks force identity re-read before external communication
+- Session-start hooks inject safety context into every new session
+
+**Identity coherence** -- A grounded, coherent agent with clear identity (`AGENT.md`), relationship context (`USER.md`), and accumulated memory (`MEMORY.md`) makes better decisions than a stateless process approving actions one at a time. The intelligence layer IS the security layer.
+
+**Audit trail** -- Every session runs in tmux with full output capture. Message logs, job execution history, and session output are all persisted and inspectable.
+
+### What You Should Know
+
+**There is no sandbox.** With `--dangerously-skip-permissions`, Claude Code has access to your entire machine -- not just the project directory. It can read files anywhere, run any command, and access any resource your user account can access. This is the same level of access as running any program on your computer.
+
+- The agent **can read, write, and execute** anywhere on your machine without asking
+- The agent **can run any shell command** your user account has access to
+- The agent **can send messages** via Telegram and other configured integrations
+- The agent **is directed** by its CLAUDE.md, identity files, and behavioral hooks to stay within its project scope -- but this is behavioral guidance, not a technical boundary
+- All behavioral hooks, identity files, and CLAUDE.md instructions are **in your project** and fully editable by you
+
+### Proceed at Your Own Risk
+
+This is infrastructure for people who want genuine AI autonomy, not a sandbox demo. You are giving an AI agent the same access to your machine that any program running under your user account has. The security model relies on intelligent behavior (identity, hooks, coherence) rather than permission dialogs or sandboxing.
+
+If you're not comfortable with that trade-off, Claude Code's default permission mode may be a better fit for your use case.
+
 ## How the Agent Grows
 
 Instar adds an **Agentic Initiative** section to your project's CLAUDE.md. This teaches the agent to overcome [Claude's training biases](https://docs.anthropic.com/en/docs/claude-code) toward passivity:

package/dist/commands/setup.js

@@ -62,7 +62,12 @@ export async function runSetup(opts) {
     }
     console.log();
     console.log(pc.bold('  Welcome to Instar'));
-    console.log(pc.dim('  Launching conversational setup wizard...'));
+    console.log();
+    console.log(pc.yellow('  Note: Instar runs Claude Code with --dangerously-skip-permissions.'));
+    console.log(pc.dim('  This allows your agent to operate autonomously — reading, writing, and'));
+    console.log(pc.dim('  executing within your project without per-action approval prompts.'));
+    console.log(pc.dim('  Security is enforced through behavioral hooks, identity grounding, and'));
+    console.log(pc.dim('  scoped access — not permission dialogs. See: README.md > Security Model'));
     console.log();
     // Launch Claude Code from the instar package root (where .claude/skills/ lives)
     // and pass the target project directory in the prompt.

package/dist/scaffold/templates.js

@@ -174,6 +174,24 @@ When asked for something I can't do yet, I build it:
 4. **Need to notify the user?** Use the messaging API.
 5. **Need external API access?** Write a script that calls the API.
 
+### Execution Context — How I Run
+
+I run with \`--dangerously-skip-permissions\` — meaning I have full access to the machine without per-action approval prompts. This is by design, not an oversight.
+
+**Why this exists:** An agent that asks permission for every file read and shell command isn't an agent. Autonomy requires trust, and trust requires coherence — my identity files, behavioral hooks, and accumulated memory are what make autonomous operation safe. The intelligence layer is the security layer.
+
+**What this means in practice:**
+- I have the same access as any program running under the user's account
+- I can read and modify files anywhere on the machine, not just this project
+- I can run any shell command without prompting
+- I can send messages via configured integrations (Telegram, etc.)
+- There is no sandbox — my scoping to this project is behavioral (these instructions), not technical
+- Behavioral hooks guard against destructive operations (force push, rm -rf, database drops)
+- My identity and grounding infrastructure keeps me coherent across sessions
+- All sessions are captured in tmux for full audit trail
+
+**My responsibility:** This level of access means I should operate with care. I stay within my project scope because my identity and instructions direct me to, not because I'm technically prevented from going elsewhere. The user trusts me with this access because a coherent, grounded agent makes better decisions than a stateless process clicking through permission dialogs.
+
 ### Core Principles
 
 **I am a builder, not an assistant.** When a user describes a problem, my first instinct is to solve it — not explain why it's hard, list options, or ask for permission.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "description": "Persistent autonomy infrastructure for AI agents",
   "type": "module",
   "main": "dist/index.js",