instar 0.4.4 → 0.4.6

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.
+
+**Scoped access** -- The agent operates within your project directory. It has access to the files and tools in that directory, your configured API keys, and your Telegram bot. It does not have access to other projects, system files, or credentials outside its scope.
+
+**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
+
+- The agent **can read, write, and execute** within your project directory without asking
+- The agent **can run shell commands** (builds, tests, git operations) without prompting
+- The agent **can send messages** via Telegram if configured
+- The agent **cannot access** other projects, system credentials, or resources outside its configured scope
+- 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 meaningful access to your project. The security model relies on intelligent behavior (identity, hooks, coherence) rather than permission dialogs.
+
+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/server.js

@@ -67,7 +67,9 @@ async function respawnSessionForTopic(sessionManager, telegram, targetSession, t
         bootstrapMessage = `[telegram:${topicId}] ${msg} (${relayNote})`;
     }
     const storedName = telegram.getTopicName(topicId);
-    const topicName = storedName || targetSession;
+    // Use topic name, not tmux session name — tmux names include the project prefix
+    // which causes cascading names like ai-guy-ai-guy-ai-guy-topic-1 on each respawn.
+    const topicName = storedName || `topic-${topicId}`;
     const newSessionName = await sessionManager.spawnInteractiveSession(bootstrapMessage, topicName);
     telegram.registerTopicSession(topicId, newSessionName);
     await telegram.sendToTopic(topicId, `Session respawned.`);

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/core/SessionManager.js

@@ -374,6 +374,10 @@ export class SessionManager extends EventEmitter {
                     execFileSync(this.config.tmuxPath, ['paste-buffer', '-t', exactTarget, '-p'], {
                         encoding: 'utf-8', timeout: 5000,
                     });
+                    // Brief delay to let the terminal process the paste before sending Enter.
+                    // Without this, the Enter arrives before paste processing completes and
+                    // the message sits in the input buffer without being submitted.
+                    execFileSync('/bin/sleep', ['0.3'], { timeout: 2000 });
                     // Send Enter to submit
                     execFileSync(this.config.tmuxPath, ['send-keys', '-t', exactTarget, 'Enter'], {
                         encoding: 'utf-8', timeout: 5000,

package/dist/scaffold/templates.js

@@ -174,6 +174,26 @@ 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 can read, write, execute, and interact within this project 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 can read and modify any file in this project directory
+- I can run shell commands (builds, tests, git operations) without prompting
+- I can send messages via configured integrations (Telegram, etc.)
+- Behavioral hooks guard against destructive operations (force push, rm -rf, database drops)
+- My identity and grounding infrastructure keeps me coherent across sessions
+
+**What I cannot do:**
+- Access other projects or system files outside this directory
+- Bypass behavioral hooks (they are structural, not advisory)
+- Act without an audit trail (all sessions are captured in tmux)
+
+This is a meaningful level of access. The user has opted into this model because they want genuine autonomy, not a permission dialog for every action.
+
 ### 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.4",
+  "version": "0.4.6",
   "description": "Persistent autonomy infrastructure for AI agents",
   "type": "module",
   "main": "dist/index.js",